design.md for a Chakra UI v3 Codebase: Recipes, Tokens, Rules

# acme — design.md
 
> Canonical design memory for the acme web app. Every AI session and human
> contributor reads this **before** writing UI. If a value isn't here,
> propose it as an addition before using it inline.
 
**Last updated**: 2026-05-14
**Scope**: `apps/web/src/`
**Stack**: Chakra UI v3 + Panda CSS, React 19, TanStack Query, Zustand,
react-hook-form + Zod.
**Source of truth for values**:
- Raw tokens — `src/theme/tokens.ts`
- Semantic tokens — `src/theme/semantic-tokens.ts`
- Recipes — `src/theme/recipes/*.ts`
- Slot recipes — `src/theme/slot-recipes/*.ts`
- Text styles — `src/theme/text-styles.ts`
- System config — `src/theme/system.ts` (via `createSystem(defaultConfig, …)`)
 
This file documents how to **use** those values. Never duplicate a hex
or a recipe variant name here without it existing in the source files.

## 1. Brand
 
| Surface | Value |
|---|---|
| Product | acme — operational dashboard for mid-market service businesses |
| Audience | operations managers, finance leads, finance admins |
| Wordmark | "acme" — lowercase, Inter, weight 600 |
| Voice | direct, calm, numerate, jargon-free; never cute, never marketing |
| References we draw from | Linear, Stripe Dashboard, Notion |
| References we **avoid** | Material Design demos, generic SaaS gradients, Bootstrap chrome |

Two layers:
 
1. **Raw tokens** — the palette. Defined in `src/theme/tokens.ts`. Numeric
   colour scales (`brand.50` … `brand.900`), spacing, radii, shadows.
   Never reference raw tokens from a component file.
 
2. **Semantic tokens** — meaning. Defined in `src/theme/semantic-tokens.ts`.
   `bg.canvas`, `fg.muted`, `border.subtle`, `accent.solid`. Components
   reference these and **only** these.
 
If you find yourself writing `color="brand.500"` in a component, you are
working at the wrong layer. Add a semantic token first, then use it.

// src/theme/tokens.ts (excerpt)
export const tokens = defineTokens({
  colors: {
    brand: {
      50:  { value: "#EFF6FF" },
      100: { value: "#DBEAFE" },
      200: { value: "#BFDBFE" },
      300: { value: "#93C5FD" },
      400: { value: "#60A5FA" },
      500: { value: "#1E40AF" }, // <- brand anchor
      600: { value: "#1E3A8A" },
      700: { value: "#1B3173" },
      800: { value: "#172A60" },
      900: { value: "#13234E" },
    },
    accent: {
      50:  { value: "#FFF7ED" },
      100: { value: "#FFEDD5" },
      200: { value: "#FED7AA" },
      300: { value: "#FDBA74" },
      400: { value: "#FB923C" },
      500: { value: "#F97316" }, // <- accent anchor (the CTA colour)
      600: { value: "#EA580C" },
      700: { value: "#C2410C" },
      800: { value: "#9A3412" },
      900: { value: "#7C2D12" },
    },
    // success, warning, danger, info follow the same 50–900 shape.
  },
});

// src/theme/semantic-tokens.ts (excerpt)
export const semanticTokens = defineSemanticTokens({
  colors: {
    // Surfaces
    bg: {
      canvas:  { value: "{colors.gray.50}" },      // page background
      surface: { value: "{colors.white}" },         // cards, drawers, table bg
      muted:   { value: "{colors.gray.100}" },      // hover rows, chips
      subtle:  { value: "{colors.gray.50}" },       // table header bg
      inverse: { value: "{colors.gray.900}" },      // tooltip, dark callout
    },
    // Foreground (text)
    fg: {
      default: { value: "{colors.gray.900}" },      // body
      muted:   { value: "{colors.gray.600}" },      // captions, helper text
      subtle:  { value: "{colors.gray.500}" },      // metadata
      inverse: { value: "{colors.white}" },         // text on inverse bg
    },
    // Borders
    border: {
      default: { value: "{colors.gray.200}" },      // table, card outer
      subtle:  { value: "{colors.gray.100}" },      // intra-card dividers
      strong:  { value: "{colors.gray.300}" },      // focused inputs
    },
    // Actions — note the inversion, documented in 2d
    cta: {
      solid:   { value: "{colors.accent.500}" },    // primary CTA fill
      hover:   { value: "{colors.accent.600}" },
      contrast:{ value: "{colors.white}" },
    },
    secondary: {
      solid:   { value: "{colors.brand.500}" },     // secondary CTA fill
      hover:   { value: "{colors.brand.600}" },
      contrast:{ value: "{colors.white}" },
    },
    // Status
    success: { solid: { value: "{colors.success.500}" }, subtle: { value: "{colors.success.50}" } },
    danger:  { solid: { value: "{colors.danger.500}"  }, subtle: { value: "{colors.danger.50}"  } },
    warning: { solid: { value: "{colors.warning.500}" }, subtle: { value: "{colors.warning.50}" } },
    info:    { solid: { value: "{colors.info.500}"    }, subtle: { value: "{colors.info.50}"    } },
  },
});

> ⚠ **Critical convention**: the **CTA semantic group maps to the `accent`
> palette, not the `brand` palette.** The most committal action in the
> product is the warm orange `accent.500`, not the cool blue `brand.500`.
>
> Concretely: `<Button variant="solid" colorPalette="cta">` produces an
> orange button; `colorPalette="secondary"` produces a blue button.
> The brand colour is the **second** priority action on a surface.
>
> A model trained on the average React codebase will reach for
> `colorPalette="brand"` as the primary CTA. It is wrong every time. If
> you see `colorPalette="brand"` on a Save / Submit / Apply button, change
> it to `colorPalette="cta"`.

- **Primary CTA on any surface**: `colorPalette="cta"`. Exactly one per surface.
- **Secondary CTA**: `colorPalette="secondary"`.
- **Destructive action**: `colorPalette="danger"` (Delete, Disconnect, Revoke).
- **Status communication** (chips, alerts, banners): `success` | `warning` | `danger` | `info`.
- **Body text and links**: never set `colorPalette`. Use `color="fg.default"` or
  `color="cta.solid"` for inline links.
- **Tables, filters, page chrome**: never set `colorPalette`. They use neutral
  `gray` via the semantic `bg.*` and `border.*` tokens.
- **Gradients**: marketing and onboarding only. Never on data UI.
 
Choose `colorPalette` **once per surface**, at the top of the page module.
Do not pass `colorPalette` as a prop from a parent — if a child component
needs to override the palette, that is a design discussion, not a render-time
decision.

**Font family**: Inter, loaded via `@fontsource-variable/inter`.
Fallback: `ui-sans-serif, system-ui, sans-serif`.
 
**Scale** — defined as text-style recipes in `src/theme/text-styles.ts`.
Consume via the `textStyle` prop on `<Text>`, `<Heading>`, or `<Box>`.
Never set `fontSize`, `fontWeight`, or `lineHeight` inline.

// src/theme/text-styles.ts (excerpt)
export const textStyles = defineTextStyles({
  "display": {
    description: "page H1 — list page title, detail name",
    value: { fontSize: "1.5rem",  lineHeight: "2rem",    fontWeight: 600 },
  },
  "heading": {
    description: "section H2",
    value: { fontSize: "1.25rem", lineHeight: "1.75rem", fontWeight: 600 },
  },
  "title": {
    description: "card / drawer titles",
    value: { fontSize: "1rem",    lineHeight: "1.5rem",  fontWeight: 500 },
  },
  "title-sm": {
    description: "dense card titles, table-section headers",
    value: { fontSize: "0.875rem", lineHeight: "1.25rem", fontWeight: 500 },
  },
  "body": {
    description: "DEFAULT body — table rows, form fields, paragraph copy",
    value: { fontSize: "0.875rem", lineHeight: "1.25rem", fontWeight: 400 },
  },
  "caption": {
    description: "metadata, timestamps, helper text",
    value: { fontSize: "0.75rem",  lineHeight: "1rem",    fontWeight: 400 },
  },
  "overline": {
    description: "uppercase section labels",
    value: { fontSize: "0.75rem", lineHeight: "1rem", fontWeight: 500,
             letterSpacing: "0.08em", textTransform: "uppercase" },
  },
  "mono": {
    description: "IDs, hashes, money, quantities (tabular numbers)",
    value: { fontFamily: "mono", fontSize: "0.875rem",
             fontVariantNumeric: "tabular-nums" },
  },
});

| `textStyle` | Use |
|---|---|
| `display`   | page H1 |
| `heading`   | section H2 |
| `title`     | card / drawer title |
| `title-sm`  | dense card title, table-section header |
| `body`      | **default body** — tables, fields, paragraph |
| `caption`   | helper, metadata, timestamps |
| `overline`  | uppercase section labels |
| `mono`      | money columns, IDs |
 
**Weights**: 400, 500, 600. **No 700.** If a piece of text needs more
emphasis than 600, change the colour to `fg.default`, do not increase weight.
 
**Tabular numbers** in any column with money, quantity, or count:
`textStyle="mono"` on the cell. Non-negotiable.

Chakra's spacing scale is `4px * n`. So `p={4}` = 16px.
 
**Sanctioned set** — use exactly these values:
 
| Token | Px | Use |
|---|---|---|
| `0.5` | 2  | chip internal padding, dense table cell |
| `1`   | 4  | tightest gap (icon + label) |
| `2`   | 8  | small button padding, dense table padding |
| `3`   | 12 | table cell padding |
| `4`   | 16 | card sections, form rows, default gap |
| `6`   | 24 | page header padding, dialog padding |
| `8`   | 32 | large section gaps |
 
**Banned**: `1.5`, `2.5`, `3.5`, `5`, `7`, `9`, `10+`, arbitrary px (`p="13px"`),
arbitrary calc (`p="calc(4px + 2px)"`).
 
**Standard gaps**:
- Between cards or form sections: `gap={6}` (24px)
- Between fields inside a form: `gap={4}` (16px)
- Inline elements (icon + label): `gap={2}` (8px)
- Inside a chip / pill: `px={2} py={0.5}`

**Borders** — colour comes from semantic tokens, never `gray.*` directly:
 
| Use                                            | Token                |
|---|---|
| Card outer, table outer                        | `border="1px solid"` + `borderColor="border.default"` |
| Intra-card divider, row separator              | `borderColor="border.subtle"` |
| Focused input ring                             | `outline="2px solid"` + `outlineColor="border.strong"` |
| Destructive confirmation outline               | `borderColor="danger.solid"` |
 
**Radii** — defined in `tokens.ts`:
 
| Token | Px | Use |
|---|---|---|
| `radii.xs`   | 2px  | tags, status dots (when not full circle) |
| `radii.sm`   | 4px  | inputs, buttons (Chakra default), chips |
| `radii.md`   | 8px  | table containers, small cards |
| `radii.lg`   | 12px | drawer content cards, form wrapper cards |
| `radii.full` | 9999px | avatars, status dots, pill chips |
 
Use the token name (`borderRadius="md"`), not the raw value.

Chakra ships a deep shadow scale (`xs` … `2xl`). The product is **flat by default**.
 
**Allowed**:
 
| Token       | Use |
|---|---|
| `shadow="xs"` | primary CTAs at rest, cards on tinted bg |
| `shadow="sm"` | dropdowns, autocomplete popovers, hover state on cards |
| `shadow="md"` | dialogs, drawers (Chakra default for these) |
 
**Banned**:
 
- ❌ `shadow="lg"`, `shadow="xl"`, `shadow="2xl"`
- ❌ Coloured shadows (`shadow="0 0 12px var(--colors-cta-solid)"`) anywhere on data UI
- ❌ Inset shadows
- ❌ Glow effects

import { Button } from "@/components/ui/button";
 
<Button variant="solid" colorPalette="cta" size="md">Save</Button>

export const buttonRecipe = defineRecipe({
  base: {
    fontWeight: 500,
    borderRadius: "sm",
    transition: "background 120ms ease",
    _focusVisible: { outline: "2px solid", outlineColor: "border.strong", outlineOffset: 2 },
  },
  variants: {
    variant: {
      solid:    { bg: "colorPalette.solid", color: "colorPalette.contrast",
                  _hover: { bg: "colorPalette.hover" } },
      outline:  { borderWidth: "1px", borderColor: "colorPalette.solid",
                  color: "colorPalette.solid", bg: "transparent",
                  _hover: { bg: "colorPalette.subtle" } },
      ghost:    { color: "colorPalette.solid", bg: "transparent",
                  _hover: { bg: "colorPalette.subtle" } },
      link:     { color: "colorPalette.solid", textDecoration: "underline",
                  bg: "transparent", px: 0, h: "auto" },
    },
    size: {
      sm: { h: 8,  px: 3, fontSize: "0.8125rem" },
      md: { h: 10, px: 4, fontSize: "0.875rem"  },
      lg: { h: 12, px: 5, fontSize: "1rem"      },
    },
  },
  defaultVariants: { variant: "solid", size: "md" },
});

import { Field } from "@/components/ui/field";
import { Input } from "@chakra-ui/react";
 
<Field label="Email" helperText="We never share this." required>
  <Input {...register("email")} />
</Field>

import { Card } from "@/components/ui/card";
 
<Card.Root>
  <Card.Header>
    <Card.Title>Customers</Card.Title>
    <Card.Description>Active in the last 30 days</Card.Description>
  </Card.Header>
  <Card.Body>{children}</Card.Body>
  <Card.Footer>{actions}</Card.Footer>
</Card.Root>

export const cardSlotRecipe = defineSlotRecipe({
  slots: ["root", "header", "body", "footer", "title", "description"],
  base: {
    root:        { bg: "bg.surface", borderRadius: "lg",
                   border: "1px solid", borderColor: "border.default" },
    header:      { p: 6, borderBottom: "1px solid", borderColor: "border.subtle" },
    body:        { p: 6 },
    footer:      { p: 6, borderTop: "1px solid", borderColor: "border.subtle",
                   display: "flex", justifyContent: "flex-end", gap: 3 },
    title:       { textStyle: "title" },
    description: { textStyle: "caption", color: "fg.muted" },
  },
  variants: {
    density: {
      comfortable: { body: { p: 6 } },
      compact:     { header: { p: 4 }, body: { p: 4 }, footer: { p: 4 } },
    },
  },
  defaultVariants: { density: "comfortable" },
});

<Avatar name="Maya Tan" src={user.avatarUrl} size="sm" />

import { DataTable } from "@/components/ui/data-table";
 
<DataTable
  columns={customerColumns}
  data={customers}
  getRowId={(row) => row.id}
  state={{ sorting, columnFilters }}
  onSortingChange={setSorting}
  onColumnFiltersChange={setColumnFilters}
/>

import { Drawer } from "@/components/ui/drawer";
 
<Drawer.Root open={open} onOpenChange={setOpen} size="md">
  <Drawer.Backdrop />
  <Drawer.Positioner>
    <Drawer.Content>
      <Drawer.Header>
        <Drawer.Title>New customer</Drawer.Title>
        <Drawer.CloseTrigger />
      </Drawer.Header>
      <Drawer.Body>{form}</Drawer.Body>
      <Drawer.Footer>{actions}</Drawer.Footer>
    </Drawer.Content>
  </Drawer.Positioner>
</Drawer.Root>

<Popover.Root>
  <Popover.Trigger asChild><Button variant="ghost">Filters</Button></Popover.Trigger>
  <Popover.Positioner>
    <Popover.Content>…</Popover.Content>
  </Popover.Positioner>
</Popover.Root>

<EmptyState
  icon={<UsersIcon />}
  title="No customers yet"
  description="Add your first customer to get started."
  action={<Button variant="solid" colorPalette="cta">Add customer</Button>}
/>

┌────────────────────────────────────────────────────┐
│ Module name                            [+ Create]  │ page header
├────────────────────────────────────────────────────┤
│ [search]    [Filter ▾] [Sort ▾]   [Export]         │ toolbar
├────────────────────────────────────────────────────┤
│ ☐  Col1   Col2   Col3   ...   Col6           ⋮     │ table header
├────────────────────────────────────────────────────┤
│ ... rows ...                                       │
├────────────────────────────────────────────────────┤
│ N of total                          [pagination]   │ footer
└────────────────────────────────────────────────────┘

                              ┌───────────────────────────┐
                              │ New customer         ✕   │ Drawer.Header
                              ├───────────────────────────┤
                              │ Field 1                   │
                              │ Field 2                   │
                              │ Field 3 (section break)   │
                              │ ─────────────────         │
                              │ Field 4                   │
                              │ Field 5                   │
                              ├───────────────────────────┤
                              │           [Cancel] [Save] │ Drawer.Footer
                              └───────────────────────────┘

┌────────────────────────────────────────────────────┐
│ ← Back   Customer name                  [⋮ Actions]│
├────────────────────────────────────────────────────┤
│  Summary card  │  Tabs                             │
│  Avatar        │  • Overview                       │
│  Key facts     │  • Invoices                       │
│                │  • Activity                       │
│                │  ─────────────────                │
│                │  ... tab body ...                 │
└────────────────────────────────────────────────────┘

### Rules
 
1. **Skeleton-match-layout.** Skeletons render at the exact dimensions and
   positions of the content they replace. Per-row, per-card, per-field.
2. **No centred full-page spinners** on list, form, or detail pages.
3. **TanStack Query's `placeholderData` / `keepPreviousData`** on paginated
   lists — never blank the table during pagination.
4. **Optimistic mutations** when the API contract permits a deterministic
   patch.
5. **Toast** for async results the user cannot see in the UI; **no toast**
   when the action's result is already visible (row removed, drawer closed).
6. **Prefetch on link hover** for primary nav and table-row links.
 
### Banned
 
- ❌ Centred `<Spinner />` as the only loading state.
- ❌ `"Loading..."` text alone.
- ❌ Custom slide-in / slide-out route transitions.
- ❌ Animated success checkmarks that block the user.
- ❌ `setTimeout` to delay any UI state for "smoothness."

- ❌ **Direct `@chakra-ui/react` imports in page modules.** Pages import from
  `@/components/ui/*`. Only the wrappers themselves import from
  `@chakra-ui/react`.
- ❌ **Inline `css={{…}}` overrides.** If a component needs a variant that
  does not exist, add the variant to the recipe. Do not patch at the call
  site.
- ❌ **Raw tokens in component files.** `color="brand.500"` → use a semantic
  token. If none fits, add one.
- ❌ **`colorPalette` chosen at render time without a reason.** Pick once per
  surface; do not pass it as a prop from a parent.
- ❌ **Bypassing slot recipes** for Card, Dialog, Drawer, Menu, Tabs. No
  hand-rolled `<Box>` cards.
- ❌ **Hardcoded hex values** anywhere outside `src/theme/tokens.ts`.
- ❌ **Hardcoded px values** (`p="13px"`) outside the sanctioned spacing scale.
- ❌ **`fontSize`, `fontWeight`, `lineHeight` inline.** Use `textStyle="…"`.
- ❌ **Default exports** in component files. Named exports only.
- ❌ **Cross-module imports.** Never import from `pages/<OtherModule>/`.
- ❌ **Icon barrel imports.** `import { ChevronDown } from "lucide-react"`
  pulls the entire icon set into the route chunk. Use
  `lucide-react/dist/esm/icons/chevron-down` or the project's
  `<Icon name="chevron-down" />` wrapper.
- ❌ **`useStyleConfig` / `useMultiStyleConfig`.** Those are Chakra v2 APIs.
  Use `useRecipe` / `useSlotRecipe` in v3.
- ❌ **`extendTheme`.** v2 API. Use `createSystem(defaultConfig, …)` in
  `src/theme/system.ts`.

Every list view that can be empty ships an `EmptyState` with:
 
- **Icon** — Lucide, single colour, `color="fg.muted"`, 24px.
- **Title** — `textStyle="title"`, `color="fg.default"`, one short line.
- **Description** — `textStyle="body"`, `color="fg.muted"`, one or two lines.
- **Action** — exactly one button, `variant="solid" colorPalette="cta"`, the
  primary "next step" for that surface.
 
A filtered list with no results uses a **distinct** empty state:
`title="No results"`, action is `variant="ghost"` "Clear filters", **not**
the create-action.

- **Schema** — Zod schema in `src/features/<module>/schema.ts`. Exported with
  inferred type: `export type CustomerInput = z.infer<typeof customerSchema>`.
- **Required strings** — `z.string().min(1, "Required")`. Never `.nonempty()`.
- **Nullable selects** — `z.string().nullable().refine(v => v !== null, "Required")`.
- **Resolver** — `zodResolver(schema)` from `@hookform/resolvers/zod`.
- **RHF mode** — `mode: "onBlur"`, `reValidateMode: "onChange"`.
- **Field wrapper** — every field uses `@/components/ui/field`. The `<Field>`
  wrapper passes `invalid` and the error text into Chakra's `Field.Root`.
- **Required indicator** — red asterisk (`color="danger.solid"`) inside the
  label. No "(required)" text.
- **Labels** — above the field, `textStyle="caption"`, `color="fg.muted"`.
- **Submit** — `variant="solid" colorPalette="cta"`, bottom-right of the form
  or `Drawer.Footer`.
- **Cancel** — `variant="ghost" colorPalette="secondary"`, left of Submit.
- **Disable Submit** while `formState.isSubmitting`. Never use a separate
  `useState` boolean.
- **Error summary** — at the top of the form, only when there are >3 invalid
  fields. Otherwise inline `Field.ErrorText` is enough.

- **Column definitions** live in `src/features/<module>/columns.ts`, exported
  as `ColumnDef<RowType>[]`.
- **Cell formatters** are pure functions in `src/features/<module>/format.ts` —
  never inline in the column def.
- **Row selection** uses TanStack's `getRowSelectionRow` + the project's
  `selectionColumn` helper. Never roll your own checkbox column.
- **Server-side pagination** is the default. `pageIndex` and `pageSize` live
  in URL search params, parsed via `nuqs`.
- **Filters** live in the toolbar's `Popover` (one popover per filter
  group), never in the column header.
- **Sort indicators** use Chakra's `Icon` with Lucide's `ArrowUp` /
  `ArrowDown` / `ArrowUpDown`, `boxSize={4}`, `color="fg.muted"`.
- **Sticky headers** are on by default; bottom pagination bar is sticky too.
- **Row click** navigates to the detail page. The whole row is the link
  (wrap in `<Link>`), not a "View" button at the end.
- **Bulk action bar** appears only when `selection.size > 0`; mounts in the
  toolbar slot, replacing it.

Use the project's `toaster` instance created in `src/lib/toaster.ts` via
Chakra's `createToaster`:
 
```ts
import { createToaster } from "@chakra-ui/react";
 
export const toaster = createToaster({
  placement: "bottom-end",
  duration: 4000,
});

 
---
 
## 15. Modals and drawers
 
```markdown
| Use a **Drawer** for                       | Use a **Dialog** for                      |
|---|---|
| Create / edit forms with >2 fields         | Confirmation of destructive actions       |
| Multi-section settings                     | Single-question confirmations             |
| Slide-over detail / preview panels         | "Are you sure?" before risky actions      |
| Anything that scrolls                      | Anything that fits in ≤ 3 short lines     |

- **Use the project's `<Can>` wrapper**, not inline `if (user.role === …)`.
 
```tsx
import { Can } from "@/auth/Can";
 
<Can do="customer.create">
  <Button variant="solid" colorPalette="cta">Add customer</Button>
</Can>

 
---
 
## 17. Accessibility
 
```markdown
- **Focus ring** — never disabled. The `_focusVisible` outline in the button
  recipe (Section 7) is the standard; every interactive recipe matches it.
- **Form errors** — `Field.ErrorText` is wired by the snippet to
  `aria-describedby` automatically. Do not roll your own error text.
- **Dialog and Drawer** — Chakra v3's `Dialog` and `Drawer` ship correct
  focus trap, `aria-modal`, and ESC handling. Do not override.
- **Colour-only signals are banned.** Status uses a `Badge` with both colour
  and label. Validation uses red + error text + icon.
- **Icon-only buttons** must have `aria-label`. The `<IconButton>` wrapper
  enforces this via a required prop.
- **Skip link** at the top of `RootLayout`, focusable, jumps to main content.
- **Reduced motion** — every animation in this codebase honours
  `prefers-reduced-motion`. Chakra's defaults do; custom animations must
  branch.

1. **Before writing any UI code**, read this file end-to-end.
2. For a **value** (colour, size, spacing, radius, shadow): look in
   Sections 2–6 first. If no token fits, propose a new semantic token before
   using a raw token inline.
3. For a **component**: look in Section 7. Use the wrapper at `@/components/ui/*`.
   If the recipe variant you need does not exist, propose it as a recipe
   change, not as an `css={{…}}` override.
4. For a **layout**: look in Section 8. Each pattern names its reference
   implementation; read that file before writing a new one of the same
   shape.
5. After writing, scan the diff against Section 10 (Anti-patterns). Any hit there
   is a blocking issue, not a nit.
 
Cross-reference:
- `architecture/folder-structure.md` — where files go.
- `architecture/state.md` — TanStack Query vs Zustand, plus the URL-state rules.
- `prompts/list-page.md` — list-page recipe (new module).
- `prompts/form-drawer.md` — form-drawer recipe (new entity).
 
This file is referenced from `CLAUDE.md` so future sessions auto-load it.