@nqlib/nqui 0.5.5 → 0.6.0

package/docs/nqui-skills/AGENT_PROMPT.md

@@ -0,0 +1,190 @@
+---
+name: nqui-agent-prompt
+description: The canonical system prompt for AI agents building with nqui. Paste this (or a reference to it) into the system prompt of any agent that will generate nqui code. This is what makes the skills folder enforceable, not just aspirational.
+---
+
+# nqui — Agent System Prompt
+
+This is the **canonical system prompt** for AI agents building product UI with `@nqlib/nqui`. It is designed to be pasted (or referenced) at the top of any agent system prompt that will produce nqui code — Anthropic Claude API, Cursor, Lovable-style tools, internal AI workflows.
+
+The skills folder is the depth. This file is the **entry contract**: the rules an agent must respect before any tool call, before any file write.
+
+---
+
+## Agent role
+
+You are a senior frontend engineer building product UI with the **@nqlib/nqui** component library. Your work is judged by senior designers at Linear / Vercel / Stripe / Apple — not by visual ambition, but by restraint, clarity, and the absence of AI-flavored cues.
+
+You write production code. Not demos. Not portfolios. Not "look at our buttons." **Products people use.**
+
+---
+
+## Hard rules (non-negotiable)
+
+These rules apply before any decision. Violating any of them is a failure regardless of how the rest of the code looks.
+
+### 1. Always load context before building
+- Read `SKILL.md` Agent Build Protocol (steps 1-10).
+- If `.impeccable.md` exists in project root, use the design context there. If not, ASK the user — do not infer brand voice from the codebase.
+- For ANY new view, read in this order: `nqui-composition/SKILL.md` → `COMPOSITION.md` (pattern) → `RECIPES.md` (combo) → one component doc per component.
+- Token budget: see `READ_BUDGET.md`. Never bulk-read the skills folder.
+
+### 2. Surface cap: 2 inline + 1 elevated
+- Page uses `bg-background` (surface A)
+- Card uses `bg-muted/40` or `bg-muted/50` (surface B)
+- **Never a third inline surface.** Past 2 nested surfaces, use spacing (`gap-6` between sections) + uppercase labels (`text-xs uppercase tracking-wider text-muted-foreground`) instead.
+- `bg-popover` + `.nqui-elevated` shadow is reserved for Dialog / Sheet / Popover / DropdownMenu — the one legitimate exception.
+- See `ELEVATION.md` for the decision tree when tempted to add a third surface.
+
+### 3. State coverage is mandatory
+For every interactive surface, design **all** required states from `STATES.md`:
+- Lists: idle + loading (`Skeleton` shaped like content) + empty (`Empty` w/ CTA) + error (`Alert variant="destructive"` w/ retry)
+- Forms: idle + focus + filled + submitting + validation-error + server-error + success
+- Buttons: idle + hover + focus + active + disabled + loading
+- Async views: loading + populated + empty + error + refreshing
+
+**Never ship a blank screen.** No happy-path-only views.
+
+### 4. Component selection — non-negotiable mappings
+| Situation | Use | NEVER use |
+|-----------|-----|-----------|
+| Inline toolbar selection (mode, format, view) | `ToggleGroup` | `RadioGroup` |
+| Form choice with descriptions | `RadioGroup` | `ToggleGroup` |
+| Destructive confirmation | `AlertDialog` | `Dialog` |
+| Form with ≤ 5 fields | `Dialog` | `Sheet` for big forms only |
+| Form with > 5 fields | `Sheet` or route | `Dialog` (modal trap) |
+| Side panel (filters, detail) | `Sheet` | `Drawer` (mobile-only) |
+| Quick contextual info on click | `Popover` | `Dialog` |
+| Status indicator | `Badge` or colored dot | `border-left: 4px` stripe (banned) |
+| Loading | `Skeleton` matching content shape | `Spinner` (only for unknown duration < 1s) |
+| Empty | `Empty` component | Generic "No data" div |
+| Master-detail < 900px container width | `Sheet` for detail | Shrinking both panels |
+| Default control density | `size="sm"` for dense product UI | `size="default"` only for marketing/forms |
+
+### 5. Writing rules (UX copy)
+- **Specific over generic.** Button: `Send invite` not `Submit`. Confirmation: `Delete 412 issues and 1.2 GB` not `Are you sure?`.
+- **Present tense, active voice, sentence case.** `Changes saved` not `Your changes have been saved successfully!`.
+- **No exclamation marks.** No emoji in UI chrome. No "Welcome to your dashboard!" / "Let's get started!" / "Awesome!" — these are AI signatures.
+- **Errors say what + what to do.** `Couldn't reach the server — check your connection.` not `Error 500`.
+- See `WRITING.md` for the full set + 13 banned phrases.
+
+### 6. Motion rules
+- Default to no motion. Add it only when it serves comprehension (entry/exit, state change, attention direction).
+- Use named tokens or matching Tailwind durations: `100ms` micro / `150ms` quick (default) / `200ms` standard / `250ms` slow / `350ms` dramatic.
+- **Never** elastic / bounce / overshoot easing. Use `ease-out` for entrances, `ease-in` for exits.
+- **Only** animate `transform` and `opacity`. Never layout properties (width, height, padding, margin).
+- Respect `prefers-reduced-motion: reduce` — already wired in `motion.css`, don't fight it.
+- See `MOTION.md` for the full vocabulary.
+
+### 7. Anti-patterns — STOP if you reach for any of these
+- Nested cards (Card inside Card inside Card)
+- `border-left: 4px solid color` for status
+- Gradient text (background-clip: text)
+- Hero metric layout template (big-number / small-label / decorative-gradient)
+- Identical card grids (icon + heading + text repeated endlessly)
+- Two competing primary buttons on one surface
+- `font-bold` on every label
+- `shadow-lg` on inline (non-elevated) surfaces
+- `Tooltip` as the only label for an icon button (touch users see nothing)
+- `Submit` / `OK` / `Cancel` (in non-destructive flows) buttons
+
+If you find yourself writing any of these, stop. The kit has a correct alternative — find it in `RECIPES.md` or `COMPONENTS_INDEX.md`.
+
+---
+
+## Build flow (per request)
+
+Every UI build request follows this flow:
+
+```
+1. UNDERSTAND
+   - What is the one outcome on this screen? (5 words)
+   - What is the single primary action?
+   - What can move off this view (Sheet, route, hover card)?
+
+2. PATTERN MATCH
+   - Look up in COMPOSITION.md: which named pattern fits?
+     (app shell, settings, dashboard, master-detail, wizard, command, form dialog)
+   - Look up in RECIPES.md: which combos apply?
+     (status pill, bulk action, filter toolbar, the three states, etc.)
+
+3. SELECT COMPONENTS
+   - Use COMPONENTS_INDEX.md decision tables for "which component?"
+   - Load ONE doc per component you'll use
+
+4. COMPOSE
+   - Apply the surface rule (2+1)
+   - Apply the state matrix (every interactive surface, all required states)
+   - Apply the writing rules (every label, button, error, empty state)
+   - Apply motion sparingly (default: none)
+
+5. SELF-REVIEW (the 30-second Linear designer test)
+   - Hierarchy clear within 2 seconds?
+   - All states designed?
+   - Copy specific, not generic?
+   - One primary action per surface?
+   - Spacing varied (not monotonous)?
+   - Cards used only for bounded topics?
+   - Focus styles on every interactive element?
+   - No decorative shadows on flat elements?
+   If you can name 2+ failures → fix them BEFORE asking the user.
+
+6. SHIP
+   - The code should be readable cold by a senior engineer.
+   - No commentary on what you did — the diff speaks for itself.
+```
+
+**Skipping any step produces AI-flavored work.** The protocol is the difference between "looks like AI made it" and "looks like a real product."
+
+---
+
+## When the user asks for something the kit doesn't cover
+
+1. **First, double-check.** Most requests map to an existing recipe or component. Don't reinvent.
+2. **If genuinely missing:** use the closest existing pattern as a base, extend it minimally. Flag to the user that you extended (so they can decide if it's worth adding to the kit).
+3. **Never reach outside the kit** for cosmetic reasons (custom CSS for a "fancier" button, hand-written animations, decorative gradients). The kit has constraints by design; respecting them is what makes output consistent.
+
+---
+
+## Quality bar
+
+Output meets the bar when:
+
+- A senior Linear designer reviewing your diff would have **zero** of these reactions:
+  - "Why is this nested 4 levels deep?"
+  - "Where's the empty state?"
+  - "Why does the button say 'Submit'?"
+  - "Why is there a shadow on a flat card?"
+  - "Why are there two primary buttons?"
+  - "This looks like every AI dashboard."
+
+- A senior engineer reviewing your code would have zero of these reactions:
+  - "Why is there custom CSS when a component does this?"
+  - "Why is there a `<div>` where `<Item>` belongs?"
+  - "Why is this not using the design tokens?"
+  - "This breaks dark mode."
+
+If any of those reactions are possible, the work isn't done.
+
+---
+
+## What to do when you're uncertain
+
+- **Composition uncertain** → re-read `nqui-composition/SKILL.md`
+- **Pattern uncertain** → re-read `COMPOSITION.md` (named patterns)
+- **Combo uncertain** → re-read `RECIPES.md`
+- **Component choice uncertain** → re-read `COMPONENTS_INDEX.md` decision tables
+- **State coverage uncertain** → re-read `STATES.md` matrix
+- **Copy uncertain** → re-read `WRITING.md`
+- **Motion uncertain** → re-read `MOTION.md` (default: no motion)
+- **Surface uncertain** → re-read `ELEVATION.md` (default: 2 surfaces, spacing for the rest)
+
+If you're uncertain and the docs don't resolve it, **ask the user** — do not guess. Guessing produces inconsistency across the kit's output.
+
+---
+
+## Closing rule
+
+The kit's promise to its consumers is: **"AI built with nqui produces work that's reliably 8/10 or better, regardless of which agent or which prompt."** Your job as the agent is to make that promise true on every request.
+
+Restraint, not ambition. Recipes, not invention. Specifics, not vagueness.

package/docs/nqui-skills/COMPONENTS_INDEX.md

@@ -9,7 +9,7 @@ description: Token-efficient map for nqui per-component docs. Use BEFORE opening
 
 1. **Pick one doc:** `nqui-<kebab-case>.md` for the component you are implementing (e.g. `nqui-toggle-group.md`). In this repo use **`docs/components/`**; after `init-skills` use **`.cursor/nqui-skills/components/`**.
 2. **Unsure which component?** Skim **`README.md`** in that folder only for **“When to Use”** and the category table — or use **[HUMAN_GUIDE.md](./HUMAN_GUIDE.md)** (task → docs) or the **area → filenames** list below.
-3. **Deep selection logic** (toolbar vs form, ToggleGroup vs RadioGroup): **`nqui-components/SKILL.md`** and **`nqui-design-system/SKILL.md`**.
+3. **Deep selection logic** (toolbar vs form, ToggleGroup vs RadioGroup): **`nqui-components/SKILL.md`** and **`nqui-design-system/SKILL.md`**. **Bounded data tables + ScrollArea:** **`nqui-data-tables/SKILL.md`** + **`nqui-scroll-area.md`**.
 
 ## Paths
 
@@ -45,4 +45,54 @@ Suffix every name with `.md` in the components folder you are using (`docs/compo
 
 ---
 
+---
+
+## Common "which component?" decisions
+
+Use these before opening a doc. If the answer is clear, load just that one file.
+
+### Selection input
+| Situation | Use |
+|-----------|-----|
+| ≤6 options, known at build time, no search | `nqui-select` |
+| Many options OR need search/filter | `nqui-combobox` |
+| Inside a native form, progressive enhancement needed | `nqui-native-select` |
+| Inline toolbar mode (list/grid, linear/log) | `nqui-toggle-group` (never RadioGroup here) |
+| Stacked form options with descriptions | `nqui-radio-group` |
+
+### Overlay / panel
+| Situation | Use |
+|-----------|-----|
+| Focused task requiring input (create, edit) | `nqui-dialog` |
+| Destructive action confirmation | `nqui-alert-dialog` |
+| Side panel with details or filter controls | `nqui-sheet` |
+| Mobile-first or gesture-heavy panel | `nqui-drawer` |
+| Quick contextual info on click | `nqui-popover` |
+| Quick info on hover (non-critical) | `nqui-hover-card` |
+| Tiny label for icon-only controls | `nqui-tooltip` |
+
+### Data display
+| Situation | Use |
+|-----------|-----|
+| Static rows, no sorting/filtering | `nqui-table` |
+| Sortable/filterable/paginated data | `nqui-data-table` (TanStack) |
+| Key-value list, menu-style rows | `nqui-item` |
+| Inline status tags | `nqui-badge` |
+| Empty state (no data yet) | `nqui-empty` |
+| Loading placeholder | `nqui-skeleton` |
+| Inline feedback (warning, error, info) | `nqui-alert` |
+| Transient notification | `nqui-toaster` (sonner) |
+
+### Navigation
+| Situation | Use |
+|-----------|-----|
+| Primary app sections | `nqui-sidebar` |
+| Sub-views within a page | `nqui-tabs` |
+| Page location trail | `nqui-breadcrumb` |
+| Actions on right-click | `nqui-context-menu` |
+| Actions on a trigger button | `nqui-dropdown-menu` |
+| Power-user global search / actions | `nqui-command-palette` |
+
+---
+
 Full index + long-form guidance: `README.md` next to those files (large — use sections, not whole-file dump).

package/docs/nqui-skills/COMPOSITION.md

@@ -0,0 +1,321 @@
+# nqui — composition (putting UI together)
+
+Use this after **HUMAN_GUIDE.md** (task routing) and before opening many `nqui-*.md` files. Components are documented individually; this file explains **how to assemble them** into calm, product-quality screens.
+
+## Named Layout Patterns
+
+Pick the pattern that matches the user’s job before choosing components. These are blueprints, not templates — adapt them.
+
+### App Shell (sidebar + content)
+**When:** Multi-section app, persistent navigation, route-based views.
+```
+SidebarProvider
+  Sidebar (collapsible, h-full)
+    SidebarHeader (h-12, branding + workspace picker)
+    SidebarContent (nav groups, ScrollArea)
+    SidebarFooter (user avatar + menu)
+  main (flex flex-col, overflow-y-auto)
+    sticky header (h-12, breadcrumb + page actions)
+    page content (p-6, max-w-screen-xl)
+```
+Components: `Sidebar`, `SidebarProvider`, `Breadcrumb`, `DropdownMenu` for workspace/user.
+
+### Settings Page
+**When:** User-controlled preferences, profile, account — organized by topic.
+```
+Page header (h1 + description, border-b)
+Two-column: nav (sticky, ScrollArea) | form area
+  FieldSet per section (border-b, pb-8)
+    FieldLegend (section title)
+    FieldGroup (max-w-lg, flex flex-col gap-4)
+      Field (label + input + description)
+  Footer row (Save + Cancel buttons)
+```
+Components: `FieldSet`, `FieldGroup`, `Field`, `Input`, `Select`, `Switch`, `Button`. Nav uses `Tabs` (vertical) or plain `nav` with `Item`.
+
+### Dashboard (metrics + table/chart)
+**When:** Overview screen, monitoring, analytics — data-first.
+```
+Page header (h1 + date range picker + export button)
+Metric row (3-4 Cards, key numbers only — real data, not decorative)
+Primary region: DataTable or Chart (Card, full-width)
+Optional secondary: filter Sheet or side panel (Resizable)
+```
+Anti-pattern: fake KPI cards, hero metric layout, card grids of every component. Use `Empty` when data is absent.
+Components: `Card`, `DataTable`, `Select`/`Combobox` for filters, `Sheet` for filter panel, `Skeleton` for loading.
+
+### Master-Detail Split
+**When:** List of items + contextual detail (email, files, tickets, settings rows).
+```
+Resizable (direction="horizontal", defaultSize=[35, 65])
+  ResizablePanel: item list (ScrollArea, Item components)
+  ResizableHandle  ← provides the visible divider
+  ResizablePanel: detail view (sticky header + ScrollArea content)
+```
+Components: `Resizable`, `Item`, `ScrollArea`, `Breadcrumb` in detail header.
+
+**CSS-flex fallback** (when `Resizable` won't size inside `overflow-y-auto` scroll containers):
+```tsx
+<div className="flex flex-1 min-h-0 overflow-hidden bg-muted/20">
+  <div className="flex flex-col border-r border-border bg-background"
+       style={{ width: 260, flexShrink: 0, overflow: "hidden" }}>
+    {/* list panel */}
+  </div>
+  <div className="flex-1 min-w-0 overflow-hidden bg-background">
+    {/* detail panel */}
+  </div>
+</div>
+```
+
+**Required for both versions — visual separation rules (these are mandatory, not aesthetic):**
+
+1. **Three-layer divider**, not just `border-r`:
+   - Panels: `bg-background` (or a flat panel color)
+   - Outer wrapper: `bg-muted/20` (slightly darker) — peeks through as a subtle gutter
+   - Border: `border-r border-border` on the list panel
+   - The combination of border + background contrast is what reads as "separated." A lone `border-r` against same-color panels reads as "overlapping" — especially in dark mode where borders are subtle.
+
+2. **List items must use minimal chrome.** In a narrow list panel:
+   - Use `Item variant="ghost"` (or pass `variant` such that border is transparent) — never `outline` or `muted`
+   - Selected state: `bg-accent/70`, not a bordered/elevated card
+   - Hover: `hover:bg-muted/40` only
+   - Bordered/card-style items in a 260px panel look like they bleed into the detail panel even when text-truncation is correct.
+
+3. **Both panels need `overflow: hidden`** on their root container. Without this, item backgrounds and focus rings can paint past the panel boundary.
+
+4. **Detail content needs `max-w-2xl` and `p-6`** (or similar) so it doesn't hug the divider — breathing room from the boundary reinforces separation.
+
+5. **Don't put borders on list items AND between panels.** Pick one source of separation per axis. Bordered items + bordered panels = visual noise that reads as overlap.
+
+**Responsive: switch to Sheet below ~900px container width (mandatory).**
+
+A 260px list + flex-1 detail split below ~900px leaves the detail under ~640px — metadata rows wrap, description loses reading flow, the layout feels squeezed. **Don't try to shrink both panels.** Switch the detail to a Sheet instead.
+
+```tsx
+// Measure the master-detail container, not the viewport.
+// The viewport includes sidebars; what matters is space available to the split.
+const [splitRef, splitWidth] = useContainerWidth<HTMLDivElement>()
+const isCompact = splitWidth > 0 && splitWidth < 900
+
+<div ref={splitRef} className="flex flex-1 min-h-0 overflow-hidden bg-muted/20">
+  {/* List: full-width in compact, 260px sidebar when split */}
+  <div style={{ width: isCompact ? "100%" : 260, flexShrink: 0 }}>
+    {/* items */}
+  </div>
+  {/* Detail: inline panel only when wide */}
+  {!isCompact && <div className="flex-1 min-w-0">{detail}</div>}
+</div>
+
+{/* Detail: Sheet when compact, driven off the same selectedId */}
+{isCompact && (
+  <Sheet open={selected !== null} onOpenChange={(o) => !o && setSelected(null)}>
+    <SheetContent side="right" className="w-full sm:max-w-lg p-0 flex flex-col gap-0">
+      <SheetHeader className="sr-only">
+        <SheetTitle>{selected?.title}</SheetTitle>
+      </SheetHeader>
+      {selected && <DetailContent item={selected} />}
+    </SheetContent>
+  </Sheet>
+)}
+```
+
+**Why container width, not `useIsMobile`/viewport:** the available split width depends on sidebars (primary sidebar, TOC sidebar, collapsible filter panels). A 1400px viewport with two open sidebars can still leave you under 900px — at which point Sheet is correct. Measure the container with `ResizeObserver`, not the window.
+
+**Reusable hook** (drop into your project — does not require a library):
+
+```tsx
+function useContainerWidth<T extends HTMLElement>(): [React.RefObject<T | null>, number] {
+  const ref = React.useRef<T>(null)
+  const [width, setWidth] = React.useState(0)
+  React.useEffect(() => {
+    const el = ref.current
+    if (!el) return
+    const ro = new ResizeObserver((entries) => {
+      const entry = entries[0]
+      if (entry) setWidth(entry.contentRect.width)
+    })
+    ro.observe(el)
+    setWidth(el.getBoundingClientRect().width)
+    return () => ro.disconnect()
+  }, [])
+  return [ref, width]
+}
+```
+
+**Selection state lives on the parent**, not inside either panel. Same `selectedId` state drives both the inline detail render and the Sheet's `open` prop. Don't duplicate state across modes.
+
+**Reference: Linear, GitHub Issues, Things 3** all use this exact pattern. Sheet → split is the standard transition, not split → smaller-split.
+
+### Wizard / Stepper
+**When:** Multi-step flow with mandatory sequence (onboarding, checkout, ATP procedure).
+```
+Page layout (centered, max-w-lg)
+  Progress indicator (step count or Progress bar)
+  Card (current step content)
+    CardHeader (step title + description)
+    CardContent (form fields or instructions)
+    CardFooter (Back + Continue buttons, primary right)
+```
+**Rule:** One primary action per step (Continue/Submit). Back is always `variant="outline"`. Never skip validation before advancing.
+Components: `Card`, `Progress`, `Button`, `Field`, `Alert` for step errors.
+
+### Command / Search Interface
+**When:** Power-user navigation, global search, quick actions (Cmd+K pattern).
+```
+CommandPalette (modal, triggered by keyboard shortcut)
+  CommandInput (search)
+  CommandList (ScrollArea)
+    CommandGroup per category
+      CommandItem (icon + label + shortcut)
+```
+Components: `CommandPalette`, `Command`, `CommandInput`, `CommandGroup`, `CommandItem`, `Kbd` for shortcuts.
+
+### Form Dialog
+**When:** Inline creation or editing without leaving the page (create record, edit field).
+```
+Dialog (not AlertDialog — that’s for destructive confirms only)
+  DialogHeader (DialogTitle required, DialogDescription optional)
+  DialogContent (FieldGroup, max-w-sm or md)
+  DialogFooter (Cancel outline + Submit primary)
+```
+**Rule:** Keep forms short. >5 fields → use Sheet or a dedicated page. Always include `DialogTitle` (use `sr-only` if visually hidden).
+Components: `Dialog`, `Field`, `Input`, `Select`, `Button`.
+
+---
+
+## Three modes (don’t mix them on one page)
+
+| Mode | Question it answers | Where in the dev app |
+|------|---------------------|----------------------|
+| **Recipes** | How do I build a real screen? | `/`, `/patterns`, `/recipes/settings` |
+| **Catalog** | What props/variants exist? | `/catalog` (+ Storybook) |
+| **Tokens** | What are the colors, radius, type? | `/design-system` |
+
+**Rule:** Product work starts in **Recipes**. Use **Catalog** to look up a single component. Use **Tokens** when theming.
+
+## Start from the user’s job
+
+```text
+1. What is the one outcome on this screen?
+2. What is the single primary action?
+3. What can move to a secondary surface (tab, sheet, another route)?
+4. Only then: pick components (HUMAN_GUIDE → one nqui-*.md).
+```
+
+## The “three surfaces” cap
+
+Per viewport, avoid more than **three** competing regions:
+
+1. **Chrome** — sidebar + page header (`h-12`, breadcrumbs).
+2. **Primary** — table, form, editor, or dashboard focus.
+3. **Secondary** — filters, TOC, inspector (collapse on small screens).
+
+If everything is a Card, you already have too many surfaces.
+
+## When to use a Card
+
+| Use Card | Don’t use Card |
+|----------|----------------|
+| One bounded topic (“Shipping”, “Team members”) | Every control in a grid |
+| A chart or table block on a dashboard | Toolbar buttons |
+| Settings group with footer actions | Page-level layout |
+
+Prefer **sections** (`border-b`, `gap-6`, `h2`) for page structure. One Card per topic, not per widget.
+
+## Selection vs action (quick)
+
+| Job | Component |
+|-----|-----------|
+| Toolbar mode (list/grid, linear/log) | **ToggleGroup** `single` |
+| Multi format (bold/italic) | **ToggleGroup** `multiple` |
+| Commands (save, export) | **Button** / **ButtonGroup** |
+| Form choice (plan, role) | **RadioGroup** or **Select** |
+| Searchable list | **Combobox** |
+| Settings on/off | **Switch** |
+
+**RadioGroup in a horizontal toolbar = wrong default** (OK in catalog to show variants).
+
+## Forms recipe
+
+```tsx
+<FieldSet>
+  <FieldLegend>Profile</FieldLegend>
+  <FieldGroup className="flex flex-col gap-4 max-w-lg">
+    <Field>
+      <FieldLabel htmlFor="name">Name</FieldLabel>
+      <Input id="name" />
+      <FieldDescription>Shown on invoices.</FieldDescription>
+    </Field>
+    {/* … */}
+  </FieldGroup>
+</FieldSet>
+<div className="flex gap-2 pt-4">
+  <Button type="submit">Save</Button>
+  <Button type="button" variant="outline">Cancel</Button>
+</div>
+```
+
+Use **FieldGroup + Field**, not raw `div` + `space-y-*`. See `rules/forms.md`.
+
+## Toolbar recipe (context-first)
+
+```tsx
+<div className="rounded-lg border border-input bg-muted/30 p-3">
+  <div className="flex flex-wrap items-center gap-1">
+    <ToggleGroup type="multiple" …>…</ToggleGroup>
+    <Separator orientation="vertical" className="mx-2 h-5" />
+    <ToggleGroup type="single" …>…</ToggleGroup>
+  </div>
+  <div className="mt-3 rounded border border-input/50 bg-background px-3 py-2 text-sm text-muted-foreground">
+    {/* content the toolbar affects */}
+  </div>
+</div>
+```
+
+Reference: `/catalog` → Toggle & ToggleGroup, or `/patterns` overview.
+
+## Page shell recipe
+
+```text
+SidebarProvider
+  sticky header (h-12, --z-sticky-page)
+  main (#main)
+    h1 + short description
+    optional Alert (one per page)
+    primary region (tabs | form | table)
+```
+
+Scroll: custom main scroll container — see `README.md` → Layout & Scroll Patterns.
+
+## Anti-patterns (busy UI)
+
+| Anti-pattern | Fix |
+|--------------|-----|
+| Card grid of every component | Catalog route or Storybook |
+| Fake KPI cards (12,345 users) on a reference page | Real metrics only in product demos |
+| Mail-app nav for a component library | Task-based nav (Recipes / Catalog) |
+| Command palette items that don’t navigate | Wire only real routes |
+| `space-y-*` on flex layouts | `flex flex-col gap-*` |
+| Tooltip as only label for required fields | Visible `FieldLabel` |
+| Nested Cards | Section + one Card, or `calc(radius)` nesting rules |
+| Raw `bg-blue-500` chrome | Semantic tokens |
+
+## Pre-ship checklist
+
+- [ ] One clear user goal and primary action
+- [ ] ≤3 major surfaces on screen
+- [ ] Toolbars in context (`bg-muted/30`), not isolated in Cards
+- [ ] Forms use FieldSet + FieldGroup
+- [ ] Cards only for real topics
+- [ ] States: Skeleton / Empty / Alert (not placeholder lorem boxes)
+- [ ] Z-index from `elevation.css` only
+
+## Dev app map
+
+| Route | Recipe |
+|-------|--------|
+| `/` | Hub — start here |
+| `/patterns` | Commerce dashboard (dense product UI) |
+| `/recipes/settings` | Workspace settings (forms) |
+| `/catalog` | Full variant catalog |
+| `/design-system` | Tokens |