@draekien/create-d9-app 0.0.2 → 0.0.3

package/templates/base/.agents/skills/shadcn/design-system-page.md

@@ -0,0 +1,268 @@
+# The Design System Page
+
+What goes on a design system page, and how to show it. Distilled from Primer, Carbon, Atlassian, GitLab Pajamas, Cloudscape, Twilio Paste, Salesforce Lightning, Material 3, Evergreen and Orbit, and from EightShapes' component documentation guidance.
+
+## Contents
+
+- Principles
+- Page outline
+- Foundations
+- Components: tiers and block anatomy
+- States without interaction
+- Edge cases
+- Do and Don't
+- Recipes and example screens
+- Helpers
+- Checklist
+
+---
+
+## Principles
+
+1. **Foundations, then components, then compositions.** Every mature system follows this order (Primer, Carbon, Paste, Cloudscape, M3).
+2. **Roles, not palettes.** Show each color as a surface paired with its foreground and the measured contrast. The raw palette comes second.
+3. **Lead with the typical case.** Each component opens with its most common use in real content. Then come variants in priority order, then shared axes (size, icon), then states.
+4. **Pin states so reviewers can see them.** Hover, focus and pressed render side by side without interaction. Use one consistent label, and never put the state name inside the component.
+5. **Don't render every combination.** Primitives get a variant × state matrix. Composed components get a typical example plus additions. Exhaustive combinations belong in tests (Material 3 cut its list kit from 700+ variants to about 45).
+6. **Real content in the brand's voice.** No lorem ipsum. Include the awkward cases: long text, empty, error, loading.
+7. **Composition proves the system.** End with the DESIGN.md's own recipes and one realistic screen built only from the tokens and components.
+8. **Make the DESIGN.md's rules visible.** Turn its Do's and Don'ts into rendered do/don't pairs.
+
+---
+
+## Page Outline
+
+| #   | Section                    | Contents                                                                                                                             |
+| --- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| 1   | Header                     | System name, "Themed from DESIGN.md", section anchors, light/dark toggle, primary CTA.                                               |
+| 2   | Overview                   | The DESIGN.md hero recipe: display type, one-line personality, its signature artifact.                                               |
+| 3   | Foundations                | Color roles, palette, typography, spacing, radius, elevation, motion (if specified), icons.                                          |
+| 4   | Actions                    | Button, ButtonGroup, Toggle, ToggleGroup, Badge, Kbd.                                                                                |
+| 5   | Inputs                     | Field, Input, InputGroup, Textarea, Select, NativeSelect, Combobox, Checkbox, RadioGroup, Switch, Slider, InputOTP, Calendar, Label. |
+| 6   | Navigation                 | Tabs, Breadcrumb, Pagination, NavigationMenu, Menubar, Sidebar.                                                                      |
+| 7   | Data display               | Card, Table, Chart, Item, Avatar, Accordion, Collapsible, Carousel, ScrollArea, Resizable, AspectRatio, Separator.                   |
+| 8   | Feedback                   | Alert, toast (and Sonner in Base UI projects), Progress, Spinner, Skeleton, Empty.                                                   |
+| 9   | Overlays                   | Dialog, AlertDialog, Sheet, Drawer, Popover, HoverCard, Tooltip, DropdownMenu, ContextMenu, Command.                                 |
+| 10  | Conversation               | MessageScroller, Message, Bubble, Attachment, Marker, Questionnaire. See [rules/chat.md](./rules/chat.md).                           |
+| 11  | Do and Don't               | Rendered pairs for the DESIGN.md's rules.                                                                                            |
+| 12  | Recipes and example screen | The DESIGN.md's named components, then one realistic screen.                                                                         |
+| 13  | Footer                     | The DESIGN.md footer recipe.                                                                                                         |
+
+DirectionProvider goes wherever RTL matters (an RTL row in Inputs or Navigation).
+
+Alternate section surfaces the way the DESIGN.md paces its bands. Use `className="dark"` on a section to render a dark band with the same components.
+
+---
+
+## Foundations
+
+### Color roles
+
+A grid of pairs, each rendered as the surface with "Aa" in its foreground color, plus the token names, resolved value and measured contrast (Paste, Material 3, Pajamas):
+
+| Pair                                  | Required     |
+| ------------------------------------- | ------------ |
+| `background` / `foreground`           | Yes          |
+| `card` / `card-foreground`            | Yes          |
+| `popover` / `popover-foreground`      | Yes          |
+| `primary` / `primary-foreground`      | Yes          |
+| `secondary` / `secondary-foreground`  | Yes          |
+| `muted` / `muted-foreground`          | Yes          |
+| `accent` / `accent-foreground`        | Yes          |
+| `destructive` on `background`         | Yes          |
+| Each extra text token on `background` | When defined |
+
+Use `ColorPair` from the helpers. It measures contrast live and re-measures when the theme changes. Report any pair below 4.5:1 for body-size text, even when the DESIGN.md specifies it. A brand primary at 3:1 behind 14px labels is a real finding.
+
+### Palette
+
+Swatches grouped the way the DESIGN.md groups them (brand, surfaces, text, status, accents). Label each with its DESIGN.md name and token, for example "Warm Stone · `surface-warm`". Show `border`, `input`, `ring`, `chart-1…5` and `sidebar-*` here too.
+
+### Typography
+
+A specimen table, one row per type token (Cloudscape, Carbon, Atlassian):
+
+| Column   | Content                                           |
+| -------- | ------------------------------------------------- |
+| Token    | `type-display-lg`                                 |
+| Spec     | size / line height / weight / tracking            |
+| Use      | "Section heads", taken from the DESIGN.md         |
+| Specimen | Real copy set in the token, truncated to one line |
+
+Group the rows display → title → body → label/caption → code. Below the table, show one paragraph of running text at body size, with a link and inline code, so line length and rhythm are visible.
+
+### Spacing
+
+The base unit and the scale as labeled horizontal bars (Carbon, Atlassian), then a semantic ladder: inside a component, between related items, between groups, between sections (Pajamas). Skip it if the DESIGN.md defines no spacing.
+
+### Radius
+
+The same box at every step, labeled with the token, the value and what uses it (Material 3). Example: `md · 8px · buttons, inputs`.
+
+### Elevation
+
+Each level as a raised surface with the components that rest there (Pajamas, Material 3): flat for canvas and bands, hairline for cards, soft for popovers and menus, deep for dialogs.
+
+### Motion and icons
+
+Show motion only if the DESIGN.md defines durations or easings: a table of token, milliseconds and use. For icons, show one row with the icon library at each size used by components, in `foreground` and `muted-foreground`.
+
+---
+
+## Components: Tiers and Block Anatomy
+
+### Tiers
+
+| Tier         | Components                                                                                                                                                                                                            | How to show                                                         |
+| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
+| Primitives   | Button, Badge, Toggle, ToggleGroup, Input, Textarea, Select, NativeSelect, Checkbox, RadioGroup, Switch, Slider, Tabs                                                                                                 | Variant × state matrix, size ladder, icon row.                      |
+| Fields       | Field, InputGroup, Combobox, InputOTP, Calendar, Label                                                                                                                                                                | Typical field, then description, error, disabled, required.         |
+| Composed     | Card, Table, Item, Avatar, Alert, Empty, toast, Sonner, Accordion, Collapsible, Breadcrumb, Pagination, Progress, Skeleton, Spinner, Carousel, Chart, ScrollArea, Resizable, AspectRatio, Separator, Kbd, ButtonGroup | Typical example, then one element added at a time, then edge cases. |
+| Overlays     | Dialog, AlertDialog, Sheet, Drawer, Popover, HoverCard, Tooltip, DropdownMenu, ContextMenu, Menubar, NavigationMenu, Command                                                                                          | A real trigger per overlay, labeled with what it opens.             |
+| Shell        | Sidebar, DirectionProvider                                                                                                                                                                                            | Inline in a framed preview (`collapsible="none"`).                  |
+| Conversation | MessageScroller, Message, Bubble, Attachment, Marker, Questionnaire                                                                                                                                                   | One realistic thread, then variant rows.                            |
+
+### Block anatomy
+
+Each component block, in this order. Skip the parts that don't apply:
+
+1. **Name and one line on when to use it.** Take the wording from the DESIGN.md recipe when there is one.
+2. **Typical example** in real content.
+3. **Variants** in priority order (primary before secondary before ghost), each with a one-line "when".
+4. **Sizes** as a ladder, smallest to largest.
+5. **With icon**: leading, trailing, icon-only.
+6. **States**: the matrix for primitives, single examples for the rest.
+7. **Edge cases** (see below).
+
+Wide components (Table, NavigationMenu, Menubar, Sidebar, Chart, MessageScroller) span the full row.
+
+---
+
+## States Without Interaction
+
+Pin interaction states with a `data-preview` attribute. Override the hover, focus-visible and active variants so each also matches the attribute. Copy [assets/showcase/preview-states.css](./assets/showcase/preview-states.css) into `tailwindCssFile`:
+
+```css
+@custom-variant hover {
+  @media (hover: hover) {
+    &:hover {
+      @slot;
+    }
+  }
+  &[data-preview~="hover"] {
+    @slot;
+  }
+}
+@custom-variant focus-visible (&:focus-visible, &[data-preview~="focus"]);
+@custom-variant active (&:active, &[data-preview~="active"]);
+```
+
+If the theme adds an unlayered focus rule (for an outline-style focus), add `[data-preview~="focus"]` to its selector too.
+
+Render the matrix with `StateMatrix` and `previewState` from the helpers:
+
+```tsx
+const variants = ["default", "secondary", "outline", "ghost", "destructive", "link"] as const
+
+<StateMatrix
+  rows={variants}
+  render={(variant, state) => (
+    <Button variant={variant} {...previewState(state)}>
+      Save draft
+    </Button>
+  )}
+/>
+```
+
+The columns are default, hover, focus, active and disabled. Add `loading` with Spinner + `disabled` for Button, and `invalid` (`aria-invalid`) for fields:
+
+```tsx
+<StateMatrix
+  rows={["input"] as const}
+  states={["default", "hover", "focus", "disabled", "invalid"]}
+  render={(_, state) => (
+    <Input
+      placeholder="you@company.com"
+      aria-invalid={state === "invalid" || undefined}
+      {...previewState(state)}
+    />
+  )}
+/>
+```
+
+If the DESIGN.md says a state doesn't change ("primary darkens on press only"), leave that column identical. The matrix shows the spec is followed.
+
+---
+
+## Edge Cases
+
+Show these next to the component they stress:
+
+| Case          | Where                                                                     |
+| ------------- | ------------------------------------------------------------------------- |
+| Long text     | Button label, Badge, Item title, Table cell, Breadcrumb (truncation).     |
+| Empty         | Table with no rows → Empty, Combobox with no matches, empty Command.      |
+| Error         | Field with FieldError, Alert destructive, Attachment `state="error"`.     |
+| Loading       | Button with Spinner, Skeleton for Card and Item, Progress, toast loading. |
+| Many items    | AvatarGroup with count, Pagination with ellipsis, ScrollArea list.        |
+| Missing image | Avatar falling back to AvatarFallback.                                    |
+| Disabled      | Every field and its Field `data-disabled`.                                |
+| RTL           | One row inside `DirectionProvider` with `dir="rtl"`.                      |
+
+---
+
+## Do and Don't
+
+Pick the two to four DESIGN.md rules that are easiest to break and render each as a pair (Primer, Orbit, Carbon):
+
+```tsx
+<div className="grid gap-4 md:grid-cols-2">
+  <Example title="Do">
+    <Button>Get started</Button>
+    <Button variant="outline">Contact sales</Button>
+  </Example>
+  <Example title="Don't">
+    <Button>Get started</Button>
+    <Button>Contact sales</Button>
+  </Example>
+</div>
+```
+
+Caption each with the rule in one line, for example "One primary action per group." Mark Don't with `destructive` text, not a new color.
+
+---
+
+## Recipes and Example Screens
+
+**Recipes.** Build each named component in the DESIGN.md (`hero-band`, `feature-card`, `pricing-tier-card`, `callout-card-coral`, `footer`) from shadcn components and tokens. These are the spec's acceptance tests. If a recipe can't be built without raw values, the token mapping is incomplete.
+
+**Example screen.** One realistic screen in the brand's domain (Cloudscape demos, Paste page templates): a settings page (FieldGroup, Switch, Select, Button) or a list view (Table, Badge, Pagination, Empty). Use only tokens and components.
+
+---
+
+## Helpers
+
+Copy from `assets/showcase/` into the showcase folder:
+
+| File                 | Purpose                                                                    |
+| -------------------- | -------------------------------------------------------------------------- |
+| `preview-states.css` | Variant overrides that pin hover, focus and active through `data-preview`. |
+| `state-matrix.tsx`   | `StateMatrix` (labeled variant × state table) and `previewState(state)`.   |
+| `color-pair.tsx`     | `ColorPair`: surface + foreground with live contrast ratio and WCAG level. |
+
+They import `cn` from `@/lib/utils`. Rewrite that path to the project's `utils` alias.
+
+---
+
+## Checklist
+
+- [ ] Every installed component renders (run the coverage script).
+- [ ] Color roles shown as pairs with contrast; any pair under 4.5:1 is noted in the report.
+- [ ] Type specimen covers every DESIGN.md type token, in real copy.
+- [ ] Radius and elevation ladders name the components that use each step.
+- [ ] Primitives have a state matrix; Button and fields include loading and invalid.
+- [ ] Edge cases: long text, empty, error, loading, missing image.
+- [ ] Do/Don't pairs for the DESIGN.md's key rules.
+- [ ] DESIGN.md recipes rebuilt, plus one example screen.
+- [ ] Page-level theme toggle works, and at least one scoped dark band if the DESIGN.md has dark surfaces.
+- [ ] No lorem ipsum, and no state names inside components.

package/templates/base/.agents/skills/shadcn/design-system.md

@@ -0,0 +1,386 @@
+# Design Systems from DESIGN.md
+
+Build a new app from a preset, install every component, restyle it from a `DESIGN.md`, then render a design system page.
+
+Trigger phrases: "build me a design system using <preset>", "apply this DESIGN.md", "create a showcase / design system page", "make shadcn look like <brand>".
+
+## Contents
+
+- Inputs to confirm
+- Step 1: Scaffold
+- Step 2: Install everything
+- Step 3: Read the DESIGN.md
+- Step 4: Map tokens to the theme
+- Step 5: Map component recipes to variants
+- Step 6: Build the design system page ([design-system-page.md](./design-system-page.md))
+- Step 7: Verify
+- Report back
+
+---
+
+## Inputs to Confirm
+
+| Input     | Default                             | Notes                                                                                                                                    |
+| --------- | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| Preset    | Optional                            | Code (`b0`), style name (`luma`) or URL. Pass it through. Never decode it by hand. Without one, pick a style (see Step 1).               |
+| DESIGN.md | Required                            | A path, URL or pasted content. Copy it into the new app root as `DESIGN.md`.                                                             |
+| Template  | `vite`                              | Use `next` when the user says Next.js, App Router or SSR.                                                                                |
+| App name  | Derived from the brand in DESIGN.md | Kebab-case.                                                                                                                              |
+| Base      | `base`                              | Pass `--base` when no preset code is given. Use `radix` only when the user asks. `info --json` after init decides `render` vs `asChild`. |
+
+If the DESIGN.md path can't be read (macOS privacy blocks `~/Downloads` and `~/Desktop` for some hosts), ask the user to copy it into the working directory. Don't guess its contents.
+
+---
+
+## Step 1: Scaffold
+
+With a preset code from the user:
+
+```bash
+npx shadcn@latest init --preset <code> --template vite --name <app> --no-monorepo -y
+```
+
+Without one, pick the style whose geometry is closest to the DESIGN.md and pass it with `--base`:
+
+```bash
+npx shadcn@latest init --base base --preset <style> --template vite --name <app> --no-monorepo -y
+```
+
+Then:
+
+```bash
+cd <app>
+npx shadcn@latest info --json
+```
+
+`init` with neither `--preset` nor `--base` stops at an interactive library prompt, even with `-y`. Always pass one of them, plus `--no-monorepo`.
+
+### Picking a style
+
+The theme gets replaced by the DESIGN.md anyway. The style decides geometry the CSS variables can't reach: control padding, density, how rounded and how raised the components are. Read the DESIGN.md's radius scale, control heights, shadows and layout density, then pick:
+
+| Style  | Character                                             | Pick when the DESIGN.md has                                            |
+| ------ | ----------------------------------------------------- | ---------------------------------------------------------------------- |
+| `vega` | The classic shadcn/ui look.                           | Neutral, conventional SaaS geometry; nothing extreme.                  |
+| `nova` | Reduced padding and margins for compact layouts.      | 32–36px controls, 6–8px radius, hairlines over shadows.                |
+| `maia` | Soft and rounded, with generous spacing.              | 40px+ controls, 12px+ card radius, generous padding, editorial pacing. |
+| `lyra` | Boxy and sharp.                                       | 0–4px radius, hard edges, mono or technical type.                      |
+| `mira` | Compact.                                              | Dense data UIs, 28–32px controls, tight tables.                        |
+| `luma` | Rounded geometry, soft elevation, breathable layouts. | Pill buttons, soft layered shadows, glassy or macOS-like surfaces.     |
+| `rhea` | Luma, but more compact.                               | Luma's softness with product-UI density.                               |
+| `sera` | Editorial and typographic.                            | Serif display type, editorial pacing, magazine-like hierarchy.         |
+
+State the choice and the reason in one line ("Picked maia: 40px controls, 12–16px cards, generous padding"). If the user names a style, use it. Read `base`, `style`, `iconLibrary`, `tailwindCssFile` and `aliases` from `info` before writing any code.
+
+## Step 2: Install Everything
+
+```bash
+npx shadcn@latest add --all -y
+ls <resolvedPaths.ui>/*.tsx | wc -l
+```
+
+Count the component files on disk. Never quote a component count from memory.
+
+Then wire up the providers in the app root:
+
+- Wrap the app in `TooltipProvider`.
+- Base UI: wrap the app in `Toaster` from the `toast` component and call `toast.add({ title, description, type })`. Radix: render `<Toaster />` from `sonner`.
+
+Then typecheck the app sources. In Vite apps, the root `tsc --noEmit` checks nothing because the root tsconfig only has project references:
+
+```bash
+npx tsc -p tsconfig.app.json --noEmit   # Vite.
+npx tsc --noEmit                        # Next.js.
+```
+
+Fix generated files that fail strict checks (for example, an unused `React` import) before moving on, or `vite build` will fail.
+
+---
+
+## Step 3: Read the DESIGN.md
+
+DESIGN.md files usually carry YAML frontmatter (`colors`, `typography`, `rounded`, `spacing`, `components`) and prose sections (Overview, Colors, Typography, Layout, Elevation, Shapes, Components, Do's and Don'ts, Responsive, Known Gaps). Some only have prose with `{colors.x}` references. Handle both.
+
+Long files exceed one read. Grep the headings first, then read frontmatter, **Do's and Don'ts**, **Iteration Guide** and **Known Gaps** in full. Those sections hold the rules that override defaults.
+
+Extract into a working table before editing anything:
+
+| Extract               | Look for                                                              |
+| --------------------- | --------------------------------------------------------------------- |
+| Canvas and ink        | `canvas`, `surface`, `ink`, "page floor", "body text"                 |
+| Action color + states | `primary`, `-hover`, `-active`, `-pressed`, `-disabled`, `on-primary` |
+| Secondary actions     | `button-secondary` fill, text and border                              |
+| Surfaces              | card fills, soft bands, dark product surfaces                         |
+| Lines                 | `hairline`, border alpha, "1px solid"                                 |
+| Focus                 | outline vs ring, color, width, offset, alpha                          |
+| Type families         | display, body, mono, and the documented **substitutes**               |
+| Type scale            | size, weight, line height, tracking per token                         |
+| Radius scale          | every value and what it applies to                                    |
+| Elevation             | each shadow tier, verbatim                                            |
+| Control heights       | button, input, ghost, icon-button heights and padding                 |
+| Hard rules            | every "Don't" and "never"                                             |
+
+---
+
+## Step 4: Map Tokens to the Theme
+
+Edit only `tailwindCssFile`. Keep hex values when the DESIGN.md gives hex. Don't convert them to OKLCH.
+
+### Role mapping
+
+| DESIGN.md role                               | shadcn variable                                             |
+| -------------------------------------------- | ----------------------------------------------------------- |
+| canvas / surface / page floor                | `--background`                                              |
+| ink / headline text                          | `--foreground`, `--card-foreground`, `--popover-foreground` |
+| primary CTA fill / on-primary                | `--primary` / `--primary-foreground`                        |
+| primary hover, pressed or active fill        | new `--primary-active` (or `--primary-pressed`)             |
+| secondary button fill / text                 | `--secondary` / `--secondary-foreground`                    |
+| soft band, alternating section               | `--muted`                                                   |
+| secondary or descriptive text                | `--muted-foreground`                                        |
+| ghost hover wash, active tab, menu highlight | `--accent` / `--accent-foreground`                          |
+| card / feature card fill                     | `--card`                                                    |
+| floating layer (menus, dialogs)              | `--popover` (usually the canvas)                            |
+| hairline / structural border                 | `--border`, `--input`                                       |
+| focus color                                  | `--ring`                                                    |
+| error / validation                           | `--destructive`                                             |
+| illustration accents                         | `--chart-1` … `--chart-5`, plus named tokens                |
+| sidebar or nav rail surface                  | `--sidebar-*`                                               |
+
+Every token without a shadcn slot gets a variable in `:root` (and `.dark` when it changes) and a registration in `@theme inline`:
+
+```css
+:root {
+  --primary-active: #a9583e;
+  --surface-card: #efe9de;
+}
+
+@theme inline {
+  --color-primary-active: var(--primary-active);
+  --color-surface-card: var(--surface-card);
+}
+```
+
+### Radius
+
+A DESIGN.md radius scale rarely fits the `--radius` multipliers. Pin each step in `@theme inline` instead. These are the classes base-nova components use:
+
+| Class         | Used by                                         |
+| ------------- | ----------------------------------------------- |
+| `rounded-sm`  | Small accents                                   |
+| `rounded-md`  | Menu, select and command items                  |
+| `rounded-lg`  | Buttons, inputs, selects, tabs, popovers, menus |
+| `rounded-xl`  | Cards, dialogs, command                         |
+| `rounded-2xl` | Toasts, large containers                        |
+| `rounded-4xl` | Badges (pill)                                   |
+
+```css
+@theme inline {
+  /* DESIGN.md step → Tailwind class used by that component. */
+  --radius-sm: 4px; /* xs: accents. */
+  --radius-md: 6px; /* sm: menu items. */
+  --radius-lg: 8px; /* md: buttons, inputs. */
+  --radius-xl: 12px; /* lg: cards, dialogs. */
+  --radius-2xl: 16px; /* xl: toasts, hero containers. */
+  --radius-3xl: 16px;
+  --radius-4xl: 9999px; /* pill: badges. */
+}
+```
+
+Replace the existing `--radius-*` lines in `@theme inline` rather than adding a second block. Confirm the classes for the installed style:
+
+```bash
+grep -ohE "rounded-(\[[^ \"]+\]|[a-z0-9]+)" <ui>/*.tsx | sort | uniq -c
+```
+
+`rounded-[min(var(--radius-md),Npx)]` caps small buttons and select triggers. Edit the cap when the DESIGN.md wants rounder small controls.
+
+### Elevation
+
+Override Tailwind's shadow scale in `@theme`, not `@theme inline`. Copy multi-layer shadows verbatim. Set `--shadow-xs` to `0 0 #0000` when the system is hairline-only, because inputs and outline buttons use it.
+
+```css
+@theme {
+  --shadow-xs: 0 0 #0000;
+  --shadow-sm: 0 1px 3px rgb(20 20 19 / 0.08);
+  --shadow-lg: 0 1px 3px rgb(20 20 19 / 0.08), 0 8px 24px rgb(20 20 19 / 0.06);
+}
+```
+
+### Fonts
+
+Brand fonts are usually licensed. Use the substitutes the DESIGN.md names, installed from Fontsource with the project's package manager, and import every face you reference at the top of the CSS file:
+
+```bash
+npm install @fontsource-variable/inter @fontsource-variable/cormorant-garamond @fontsource-variable/jetbrains-mono
+```
+
+```css
+@import "@fontsource-variable/inter";
+@import "@fontsource-variable/cormorant-garamond";
+@import "@fontsource-variable/jetbrains-mono";
+
+@theme inline {
+  --font-sans: "Inter Variable", -apple-system, system-ui, sans-serif;
+  --font-serif: "Cormorant Garamond Variable", Garamond, serif;
+  --font-mono: "JetBrains Mono Variable", ui-monospace, monospace;
+  --font-heading: var(--font-sans);
+}
+```
+
+`--font-heading` styles small component titles (`CardTitle`, `DialogTitle`, `SheetTitle`). Point it at the display face only when that face reads well at 16px. Otherwise keep it on the sans and use display tokens for page headings.
+
+### Type scale
+
+Turn every typography token into a `type-*` utility. Don't use `--text-*` theme keys for this, because `cn()` treats unknown `text-*` classes as colors and drops whichever comes first when one sits next to `text-muted-foreground`.
+
+```css
+@utility type-display-lg {
+  font-family: var(--font-serif);
+  font-size: clamp(34px, 3vw + 16px, 48px);
+  font-weight: 500;
+  line-height: 1.1;
+  letter-spacing: -0.021em;
+}
+
+@utility type-caption-upper {
+  font-size: 12px;
+  font-weight: 500;
+  letter-spacing: 1.5px;
+  text-transform: uppercase;
+}
+```
+
+- Clamp display sizes so mobile works. Convert pixel tracking to `em` (`-1px / 48px = -0.021em`) so the ratio holds as the size shrinks.
+- Respect the rules on tracking (none below a size) and weight (display never bold).
+
+### Dark mode
+
+- **DESIGN.md defines dark surfaces** (product mockups, footers): put them in `.dark`. Because shadcn's `@custom-variant dark (&:is(.dark *))` scopes to descendants, `className="dark"` on any section renders every component inside it with dark tokens. Use it for dark bands, featured pricing cards and footers.
+- **DESIGN.md is light-only**: derive `.dark` from the brand's known dark surfaces and tell the user it's derived.
+
+### Focus
+
+Match the documented focus treatment:
+
+- **Ring with alpha** (for example "3px coral at 15%"): replace `ring-ring/50` with the documented alpha on field components (`input`, `textarea`, `input-group`, `select`, `native-select`, `combobox`, `input-otp`).
+- **Solid outline with offset**: add an unlayered rule so it beats `outline-none`, and cancel the ring shadow:
+
+```css
+:is(
+  button,
+  a[href],
+  [role="button"],
+  [role="tab"],
+  [role="checkbox"],
+  [role="radio"],
+  [role="switch"],
+  [role="slider"]
+):focus-visible {
+  outline: 2px solid var(--ring);
+  outline-offset: 2px;
+  --tw-ring-shadow: 0 0 #0000;
+}
+```
+
+This covers actions only. Field controls keep their ring. When the DESIGN.md applies the outline to fields too, add `input, textarea, select, [role="combobox"]` to the selector.
+
+---
+
+## Step 5: Map Component Recipes to Variants
+
+Restyle by editing the `cva` variants in the installed component source. Keep existing variant names so usage stays standard. Add a variant only when the DESIGN.md defines a distinct recipe.
+
+| DESIGN.md recipe                     | shadcn target                                |
+| ------------------------------------ | -------------------------------------------- |
+| `button-primary`                     | `Button` `default`                           |
+| `button-secondary` (tinted fill)     | `Button` `secondary`                         |
+| `button-secondary` (canvas + border) | `Button` `outline`                           |
+| `button-ghost`, nav links            | `Button` `ghost`                             |
+| text link                            | `Button` `link`                              |
+| circular icon button                 | `Button` `icon*` sizes + `rounded-full`      |
+| `badge-pill`, `badge-<accent>`       | `Badge` `secondary`, `default`, new variants |
+| `card`, `feature-card`               | `Card` (fill, ring, `--card-spacing`)        |
+| `text-input`, `-focused`             | `Input`, `InputGroup`, `Select`, `Textarea`  |
+| `category-tab`, filter row           | `Tabs` `default` list + trigger              |
+
+**Control heights move together.** When the button height changes, change the field controls to match, or forms misalign. In base-nova the 32px default lives in:
+
+| File                | Class                            |
+| ------------------- | -------------------------------- |
+| `button.tsx`        | `h-8`, `size-8` (icon)           |
+| `input.tsx`         | `h-8`                            |
+| `input-group.tsx`   | `h-8`                            |
+| `select.tsx`        | `data-[size=default]:h-8`        |
+| `native-select.tsx` | `h-8`                            |
+| `combobox.tsx`      | `min-h-8` (chips)                |
+| `toggle.tsx`        | `h-8 min-w-8`                    |
+| `input-otp.tsx`     | `size-8` (slot)                  |
+| `tabs.tsx`          | `group-data-horizontal/tabs:h-8` |
+| `menubar.tsx`       | `h-8`                            |
+| `command.tsx`       | `h-8!` (input group)             |
+
+Re-grep before editing (`grep -n "\bh-8\b\|size-8\b" <ui>/*.tsx`); other styles use different values.
+
+**States.** Follow the documented states exactly. If the DESIGN.md says "darken on press only", use `active:` instead of `hover:`. Keep hover on ghost buttons and menu items even when the spec omits it, and tell the user you did.
+
+**Hard rules.** Turn each "Don't" into a check before you finish, for example: no radius outside the scale, no accent color on buttons, no bold display type.
+
+---
+
+## Step 6: Build the Design System Page
+
+Follow [design-system-page.md](./design-system-page.md). It sets the section outline, how to present each foundation, the component tiers and block anatomy, pinned state matrices, edge cases, do/don't pairs, and recipes.
+
+In short:
+
+1. Foundations first: color roles as contrast-checked pairs, palette, type specimen table, spacing, radius and elevation ladders.
+2. Components by tier: primitives get a variant × state matrix, size ladder and icon row. Composed components get a typical example, additions and edge cases. Overlays get real triggers.
+3. Then rendered do/don't pairs for the DESIGN.md's rules, the DESIGN.md's named recipes rebuilt from components, and one example screen.
+
+Copy the helpers from `assets/showcase/` (`preview-states.css`, `state-matrix.tsx`, `color-pair.tsx`). Put sections in `src/showcase/<section>.tsx` (Vite) or `app/design-system/` (Next.js). Write copy in the brand's voice.
+
+### Known traps
+
+| Component           | Trap                                                                        | Fix                                                                         |
+| ------------------- | --------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
+| `Command` inline    | cmdk scrolls its first item into view on mount, which jumps the page to it. | Control it: `value={value} onValueChange={setValue}` with initial `"none"`. |
+| `Sidebar`           | Default sidebar is `fixed` and escapes the preview frame.                   | `<SidebarProvider className="min-h-0">` + `<Sidebar collapsible="none">`.   |
+| `MessageFooter`     | Placed beside `MessageContent`, it becomes a squeezed flex column.          | Put it inside `MessageContent`.                                             |
+| `Select` (base)     | `SelectValue` shows the raw value.                                          | Pass `items` to `Select`.                                                   |
+| `Resizable`         | react-resizable-panels v4 dropped `direction` and numeric sizes.            | `orientation="horizontal"`, `defaultSize="40%"`.                            |
+| `DirectionProvider` | Provider alone doesn't flip layout.                                         | Also set `dir="rtl"` on the wrapper.                                        |
+| `NavigationMenu`    | The content is clipped by the example frame.                                | Leave bottom padding in that frame.                                         |
+| Header nav links    | `Button` renders a `<button>`.                                              | Base: `nativeButton={false} render={<a href="#…" />}`. Radix: `asChild`.    |
+
+### Coverage check
+
+```bash
+node <skill-dir>/scripts/showcase-coverage.mjs src/components/ui src   # Vite.
+node <skill-dir>/scripts/showcase-coverage.mjs components/ui app      # Next.js.
+```
+
+It lists every component file that no showcase file imports. Fix the list until it's empty. `add --all` installs both `toast` and `sonner` in Base UI projects; show `sonner` in Feedback next to `toast` so the list can reach zero.
+
+---
+
+## Step 7: Verify
+
+Start the dev server and check it in a browser:
+
+1. App typecheck passes (see Step 2).
+2. No console errors.
+3. Loads at `scrollY === 0`. Anything else means a component is stealing scroll on mount.
+4. No horizontal overflow at 375px and 1280px: `document.documentElement.scrollWidth <= innerWidth`.
+5. Screenshot the hero, Foundations, one form section and one dark band. Compare against the DESIGN.md: canvas color, CTA color, display font, radius, focus ring.
+6. Toggle dark mode once.
+
+---
+
+## Report Back
+
+- App path, dev URL, component count from disk.
+- The style picked (when no preset was given) and why.
+- What maps where: colors, fonts (and substitutes), radius, shadows, focus.
+- Contrast pairs under 4.5:1, including ones the DESIGN.md itself specifies.
+- Every component file you edited and why.
+- Every deliberate deviation from the DESIGN.md (derived dark mode, kept hover, substituted fonts).