From e59c3ba4ef75e3451846517a24189d594dfbb3ea Mon Sep 17 00:00:00 2001 From: Sluijsens Date: Fri, 2 Oct 2026 00:17:39 +0200 Subject: [PATCH] Adds Chakra UI CLI, self-hosted fonts, and prettier config Moves prettier config into web/, adds @chakra-ui/cli for typegen and the fontsource font packages needed for self-hosted Jost and Marcellus, and brings in the chakra-ui-* skill docs. --- web/.agents/skills/chakra-ui-builder/SKILL.md | 374 ++++++++ .../chakra-ui-builder/references/charts.md | 461 ++++++++++ .../references/component-decision-tree.md | 287 ++++++ .../chakra-ui-builder/references/theming.md | 331 +++++++ web/.agents/skills/chakra-ui-migrate/SKILL.md | 494 ++++++++++ .../skills/chakra-ui-refactor/SKILL.md | 284 ++++++ web/.claude/skills/chakra-ui-builder/SKILL.md | 374 ++++++++ .../chakra-ui-builder/references/charts.md | 461 ++++++++++ .../references/component-decision-tree.md | 287 ++++++ .../chakra-ui-builder/references/theming.md | 331 +++++++ web/.claude/skills/chakra-ui-migrate/SKILL.md | 494 ++++++++++ .../skills/chakra-ui-refactor/SKILL.md | 284 ++++++ web/.junie/skills/chakra-ui-builder/SKILL.md | 374 ++++++++ .../chakra-ui-builder/references/charts.md | 461 ++++++++++ .../references/component-decision-tree.md | 287 ++++++ .../chakra-ui-builder/references/theming.md | 331 +++++++ web/.junie/skills/chakra-ui-migrate/SKILL.md | 494 ++++++++++ web/.junie/skills/chakra-ui-refactor/SKILL.md | 284 ++++++ .prettierignore => web/.prettierignore | 0 web/.prettierrc | 6 + web/package.json | 58 +- web/pnpm-lock.yaml | 848 +++++++++++++++++- web/pnpm-workspace.yaml | 2 + web/skills-lock.json | 26 + web/tsconfig.json | 2 +- 25 files changed, 7597 insertions(+), 38 deletions(-) create mode 100644 web/.agents/skills/chakra-ui-builder/SKILL.md create mode 100644 web/.agents/skills/chakra-ui-builder/references/charts.md create mode 100644 web/.agents/skills/chakra-ui-builder/references/component-decision-tree.md create mode 100644 web/.agents/skills/chakra-ui-builder/references/theming.md create mode 100644 web/.agents/skills/chakra-ui-migrate/SKILL.md create mode 100644 web/.agents/skills/chakra-ui-refactor/SKILL.md create mode 100644 web/.claude/skills/chakra-ui-builder/SKILL.md create mode 100644 web/.claude/skills/chakra-ui-builder/references/charts.md create mode 100644 web/.claude/skills/chakra-ui-builder/references/component-decision-tree.md create mode 100644 web/.claude/skills/chakra-ui-builder/references/theming.md create mode 100644 web/.claude/skills/chakra-ui-migrate/SKILL.md create mode 100644 web/.claude/skills/chakra-ui-refactor/SKILL.md create mode 100644 web/.junie/skills/chakra-ui-builder/SKILL.md create mode 100644 web/.junie/skills/chakra-ui-builder/references/charts.md create mode 100644 web/.junie/skills/chakra-ui-builder/references/component-decision-tree.md create mode 100644 web/.junie/skills/chakra-ui-builder/references/theming.md create mode 100644 web/.junie/skills/chakra-ui-migrate/SKILL.md create mode 100644 web/.junie/skills/chakra-ui-refactor/SKILL.md rename .prettierignore => web/.prettierignore (100%) create mode 100644 web/.prettierrc create mode 100644 web/pnpm-workspace.yaml create mode 100644 web/skills-lock.json diff --git a/web/.agents/skills/chakra-ui-builder/SKILL.md b/web/.agents/skills/chakra-ui-builder/SKILL.md new file mode 100644 index 0000000..4717529 --- /dev/null +++ b/web/.agents/skills/chakra-ui-builder/SKILL.md @@ -0,0 +1,374 @@ +--- +name: chakra-ui-builder +description: > + Build responsive, accessible UI components and layouts using Chakra UI v3, + install or configure Chakra UI in new and existing projects, and design + scalable themes using tokens, semantic tokens, recipes, and slot recipes. Use + this skill whenever a user asks to build, create, or generate any UI + component, page, form, dashboard, navbar, card, landing section, pricing + table, or layout using Chakra UI; wants to add Chakra UI to a project, set up + ChakraProvider, run CLI snippets, configure color mode, or fix provider + wrapping; or asks about theming — defining brand colors, design tokens, + semantic tokens, dark mode values, component recipes, slot recipes, typegen, + or ejecting the default theme. Trigger on any Chakra UI building, setup, or + theming or charts request, however casually phrased — "add my brand colors", + "make a reusable card style", "build a bar chart", "show me a line chart", + "make me a login form", "build a sidebar", "add Chakra to my app". +--- + +# Chakra UI Builder + +You are building UI with Chakra UI v3 and helping developers set up Chakra UI in +their projects. Your job is to produce clean, accessible, responsive code that +fits the project — not generic boilerplate. Read the project context first, then +build or set up. + +--- + +## Step 1 — Read the project context + +Check `package.json` if available. Look for: + +- Chakra UI version (use v3 patterns by default; only use v2 if explicitly on + v2) +- Framework: Next.js App Router, Pages Router, Vite, plain React +- TypeScript or JavaScript +- Package manager (from lockfile: `pnpm-lock.yaml`, `yarn.lock`, `bun.lock`, + `package-lock.json`) + +Also glance at existing components if the user references them, so your code +matches the conventions already in use (naming, file structure, import style). + +If the requirements are vague or the component is complex enough that choices +matter (layout direction, data shape, color palette, number of variants), ask +before building rather than generating something that needs to be thrown away. + +--- + +## Project setup + +If Chakra UI isn't installed yet, complete setup before building. + +### Install + +```bash +# npm +npm install @chakra-ui/react @emotion/react + +# pnpm +pnpm add @chakra-ui/react @emotion/react + +# yarn +yarn add @chakra-ui/react @emotion/react + +# bun +bun add @chakra-ui/react @emotion/react +``` + +### Generate snippets with the CLI + +```bash +npx @chakra-ui/cli snippet add +``` + +With no arguments this adds the recommended set — `provider`, `toaster`, and +`tooltip` — and automatically installs required dependencies (including +`next-themes`). Use `--all` to add every snippet, or `snippet list` to browse +first. + +The CLI detects your framework and writes files to the right place: + +| Framework | Output path | +| --------------------- | -------------------- | +| Next.js (with `src/`) | `src/components/ui/` | +| Next.js (no `src/`) | `components/ui/` | +| Vite / plain React | `src/components/ui/` | +| Remix | `app/components/ui/` | + +### Wire up the Provider + +**Next.js App Router** (`app/layout.tsx`): + +```tsx +import { Provider } from "@/components/ui/provider" + +export default function RootLayout({ + children, +}: { + children: React.ReactNode +}) { + return ( + + + {children} + + + ) +} +``` + +`suppressHydrationWarning` prevents a mismatch caused by `next-themes` injecting +the color-mode class. Do **not** add `"use client"` to `layout.tsx` — the +generated provider file already has it. + +**Next.js Pages Router** (`pages/_app.tsx`): + +```tsx +import { Provider } from "@/components/ui/provider" + +export default function App({ Component, pageProps }) { + return ( + + + + ) +} +``` + +**Vite** (`src/main.tsx`): + +```tsx +import { Provider } from "./components/ui/provider" + +createRoot(document.getElementById("root")!).render( + + + + + , +) +``` + +### Manual Provider (if CLI is unavailable) + +If the CLI fails, create `components/ui/provider.tsx` manually and install +`next-themes` separately: + +```tsx +"use client" +import { ChakraProvider, defaultSystem } from "@chakra-ui/react" +import { ThemeProvider } from "next-themes" + +export function Provider({ children }: { children: React.ReactNode }) { + return ( + + + {children} + + + ) +} +``` + +### Common setup issues + +- **Unstyled components** — app is not wrapped in ``. Check the import + path and that `Provider` wraps the component tree. +- **Hydration mismatch** — add `suppressHydrationWarning` to `` in App + Router. +- **`next-themes` not found** — install it: `npm install next-themes` (only + needed for the manual fallback; the CLI handles it automatically). +- **`extendTheme` not exported** — this is a v2 pattern. Use `createSystem` in + v3. + +--- + +## Step 2 — Choose the right layout primitives + +Reach for the right Chakra primitive rather than wrapping everything in `Box`: + +| Need | Use | +| ------------------------ | --------------------------------------- | +| Vertical stack of items | `Stack` (default) or `VStack` | +| Horizontal row | `HStack` or `Flex` | +| CSS Grid | `Grid` + `GridItem` | +| Equal-column grid | `SimpleGrid columns={N}` | +| Centered page content | `Container maxW="container.lg"` | +| Full flexbox control | `Flex` with explicit props | +| Semantic section/article | `Box as="section"` / `Box as="article"` | + +Avoid deep nesting. If you're three `Box` levels deep with no semantic reason, +flatten it. Prefer `gap` over margin between siblings. + +--- + +## Step 3 — Use tokens, not raw values + +Chakra v3 ships semantic tokens that automatically adapt to light/dark mode. +Prefer them over hard-coded palette values — they make the component theme-aware +without any extra work. + +```tsx +// Prefer semantic tokens + + + + +// Use colorPalette for interactive components (not colorScheme) + +Active +``` + +Use raw palette values (`blue.500`, `gray.100`) only when a specific color is +intentional and should not shift with color mode. + +--- + +## Step 4 — Responsive styles + +Chakra uses mobile-first breakpoints. Use array or object syntax consistently: + +```tsx +// Array: [base, sm, md, lg, xl] + + +// Object: explicit breakpoints + + +``` + +Every layout component should handle at least `base` (mobile) and `md` (desktop) +breakpoints unless the request is explicitly desktop-only. + +--- + +## Step 5 — Forms + +Use `Field.Root` for all form fields — it wires up label, input, error, and help +text correctly: + +```tsx + + Email address + + {error} + We'll never share your email. + +``` + +For form submission state, use `disabled` (not `isDisabled`) on inputs and +buttons. Group related fields in a `Stack gap={4}`. + +--- + +## Step 6 — Accessibility + +Chakra's built-in components handle most accessibility automatically — don't +override it. The things you do need to provide: + +- **Icon-only buttons**: always add `aria-label` + ```tsx + } /> + ``` +- **Images**: always pass meaningful `alt` text (or `alt=""` for decorative) +- **Form labels**: use `Field.Label` or ensure `htmlFor` matches the input `id` +- **Interactive custom elements**: if you build something with `onClick` on a + `Box`, use `as="button"` or an actual ` + ) +} +``` + +The goal is to push interactivity to the leaves — keep as much of the tree as +Server Components as possible. + +--- + +## Step 8 — When to extract components, use recipes, and customize the theme + +Extract a component when the same structure appears more than twice, or when a +piece is complex enough that naming it makes the parent clearer. + +Suggest a **recipe** when a component has meaningful style variants that a +developer would want to customize. Suggest a **slot recipe** for components with +multiple coordinated parts (card with header/body/footer, stat with +label/value/icon, etc.). + +For deeper theming work — defining brand color tokens, semantic tokens with dark +mode values, full recipe/slot-recipe authoring, typegen, or ejecting the default +theme — read `references/theming.md` before responding. It covers the complete +`defineConfig` / `createSystem` API with full examples. + +For any chart request — bar charts, area charts, line charts, pie/donut charts, +`BarList`, `BarSegment`, or anything involving `@chakra-ui/charts` — read +`references/charts.md` before responding. It covers the `useChart` hook, all +three chart types, Recharts integration, color tokens, and complete runnable +examples. + +When you're unsure which component to use, or the user hasn't specified one, +read `references/component-decision-tree.md`. It covers every Chakra component +with guidance on when to choose one over a similar alternative. + +--- + +## Output format + +Produce: + +1. **Complete, runnable code** — correct imports, no placeholders like `TODO` or + `...rest of component` +2. **Proper import statements** — group Chakra imports, then local imports +3. **Component separation** — split into multiple components/files if the + component is complex or contains clearly separable parts +4. **Responsive styles** — at minimum `base` and `md` breakpoints for layout +5. **Brief explanation after the code** — 2–4 sentences on the key decisions + made (layout approach, accessibility choices, responsive strategy). Skip the + explanation if the request was trivial. + +```tsx +// Good import style +import { Box, Button, Field, Stack, Text } from "@chakra-ui/react" +// Then local +import { SomeLocalComponent } from "./SomeLocalComponent" +``` + +--- + +## When to ask first + +Build immediately if the request is clear enough to produce something useful. +Ask first when: + +- The data shape is unknown and it changes the entire structure (e.g., "build a + table" — how many columns? what data?) +- There are meaningful design choices the user might care about (layout + direction, number of columns, color palette) +- The user references files or existing components you haven't seen + +When in doubt, state your assumptions at the top of the response and build — +it's faster for the user to redirect from something concrete than from nothing. diff --git a/web/.agents/skills/chakra-ui-builder/references/charts.md b/web/.agents/skills/chakra-ui-builder/references/charts.md new file mode 100644 index 0000000..f5eb162 --- /dev/null +++ b/web/.agents/skills/chakra-ui-builder/references/charts.md @@ -0,0 +1,461 @@ +# Chakra UI Charts Reference + +Charts live in a separate package. Install it alongside `@chakra-ui/react`: + +```bash +# npm +npm install @chakra-ui/charts recharts + +# pnpm +pnpm add @chakra-ui/charts recharts + +# yarn +yarn add @chakra-ui/charts recharts +``` + +Imports come from `@chakra-ui/charts`, not `@chakra-ui/react`: + +```ts +import { BarList, BarSegment, Chart, useChart } from "@chakra-ui/charts" +import type { BarListData, BarSegmentData } from "@chakra-ui/charts" +``` + +--- + +## Three chart types + +| Component | Best for | Recharts? | +| ----------------------- | ---------------------------------------------- | --------- | +| `BarList` | Rankings, comparisons (horizontal bar per row) | No | +| `BarSegment` | Composition / parts of a whole (stacked bar) | No | +| `Chart.Root` + Recharts | Line, area, bar, pie, radar, and more | Yes | + +--- + +## `useChart` — the core hook + +Every chart starts with `useChart`. It processes data, resolves color tokens, +and provides utilities used throughout the chart's compound components. + +```ts +const chart = useChart({ + data: [...], // array of data objects + series: [...], // which keys to plot and how to color them + sort: { by: "value", direction: "desc" }, // optional +}) +``` + +**`series` items:** + +```ts +{ + name: keyof T // data key to read values from + color: ChartColor // Chakra token ("teal.solid") or CSS color ("#FF0000") + label?: ReactNode // display name in legend/tooltip (defaults to name) + stackId?: string // for stacking in Recharts charts + yAxisId?: string // for dual-axis charts +} +``` + +**Color type** — accepts any Chakra color token or CSS color: + +```ts +type ChartColor = Tokens["colors"] | CSSProperties["color"] +// "teal.solid" | "blue.subtle" | "red.500" | "#FF0000" | "hsl(...)" +``` + +**Useful return values:** + +```ts +chart.data // sorted data array +chart.series // resolved series config +chart.color("teal.solid") // resolves token → CSS color +chart.key("revenue") // safe key accessor +chart.formatNumber({ notation: "compact" })(1234567) // "1.2M" +chart.formatDate({ month: "short" })("2024-01-15") // locale-aware +chart.getTotal("revenue") // sum all values +chart.getMin("revenue") / chart.getMax("revenue") +chart.getValuePercent("revenue", value) // % of total +``` + +--- + +## BarList + +Horizontal bar chart — one bar per data row. Good for leaderboards, traffic +sources, top items. + +**Data shape:** + +```ts +interface BarListData { + name: string // label shown on the bar + value: number // determines bar width + href?: string // optional link +} +``` + +**Basic example:** + +```tsx +import { BarList, type BarListData, useChart } from "@chakra-ui/charts" + +const chart = useChart({ + data: [ + { name: "Google", value: 1_200_000 }, + { name: "Direct", value: 840_000 }, + { name: "Twitter", value: 320_000 }, + { name: "LinkedIn", value: 95_000 }, + ], + sort: { by: "value", direction: "desc" }, + series: [{ name: "name", color: "teal.subtle" }], +}) + +return ( + + + + + + + + + + +) +``` + +**With a custom value formatter:** + +```tsx + `${(v / 1000).toFixed(0)}K`} /> +``` + +**With multiple value columns:** + +```tsx + + + + + + `${chart.getValuePercent("value", v).toFixed(0)}%` + } + /> + +``` + +--- + +## BarSegment + +Single horizontal bar broken into colored segments. Good for showing how a total +is split across categories (budget, traffic, inventory). + +**Data shape:** + +```ts +interface BarSegmentData { + name: string // segment label + value: number // determines segment width + color: string // Chakra color token for this segment +} +``` + +**Basic example:** + +```tsx +import { BarSegment, useChart } from "@chakra-ui/charts" + +const chart = useChart({ + data: [ + { name: "Google", value: 500_000, color: "teal.solid" }, + { name: "Direct", value: 300_000, color: "blue.solid" }, + { name: "Twitter", value: 150_000, color: "purple.solid" }, + { name: "LinkedIn", value: 50_000, color: "orange.solid" }, + ], + sort: { by: "value", direction: "desc" }, +}) + +return ( + + + + + + + + +) +``` + +**With a reference line (e.g. target):** + +```tsx + + + +``` + +--- + +## Chart.Root + Recharts + +Wrapper for any Recharts chart. Handles sizing, token resolution, and styled +tooltips and legends. You still compose the chart using standard Recharts +components — `BarChart`, `AreaChart`, `LineChart`, `PieChart`, etc. + +### Bar chart + +```tsx +import { Chart, useChart } from "@chakra-ui/charts" +import { + Bar, + BarChart, + CartesianGrid, + Legend, + Tooltip, + XAxis, + YAxis, +} from "recharts" + +const chart = useChart({ + data: [ + { month: "Jan", revenue: 186, expenses: 80 }, + { month: "Feb", revenue: 165, expenses: 95 }, + { month: "Mar", revenue: 210, expenses: 110 }, + ], + series: [ + { name: "revenue", color: "teal.solid" }, + { name: "expenses", color: "orange.solid" }, + ], +}) + +return ( + + + + + + } /> + } /> + {chart.series.map((item) => ( + + ))} + + +) +``` + +### Area chart + +```tsx +import { Area, AreaChart, CartesianGrid, Tooltip, XAxis } from "recharts" + +return ( + + + + {chart.series.map((item) => ( + + ))} + + + + } /> + {chart.series.map((item) => ( + + ))} + + +) +``` + +### Pie / donut chart + +```tsx +import { Pie, PieChart, Tooltip } from "recharts" + +const chart = useChart({ + data: [ + { browser: "Chrome", visitors: 275, color: "teal.solid" }, + { browser: "Safari", visitors: 200, color: "blue.solid" }, + { browser: "Firefox", visitors: 120, color: "orange.solid" }, + { browser: "Edge", visitors: 80, color: "purple.solid" }, + ], + series: [{ name: "visitors" }], +}) + +return ( + + + } /> + + {chart.data.map((item, index) => ( + + ))} + {/* Center text for donut */} + + + +) +``` + +--- + +## Chart sub-components + +### `Chart.Tooltip` + +```tsx + [`$${value}`, name]} + /> + } +/> +``` + +### `Chart.Legend` + +```tsx + + } +/> +``` + +Legend interaction highlights/dims series on hover or click. + +### `Chart.Gradient` + +Defines an SVG gradient for area fills. Must be inside a `` block: + +```tsx + + + + + +``` + +### `Chart.RadialText` + +Centers a title + description inside a pie or donut chart: + +```tsx +