@tristan2828/ui-foundation 3.0.0

package/conventions/docs/add-an-entity.md

@@ -0,0 +1,204 @@
+# Add an Entity
+
+The most-repeated task in this system: add a full CRUD entity — spec, mocks,
+gateway, tests, table, form, routes — following the patterns in
+`src/routes/widgets/`. This file is the only copy of the steps, written for
+**any AI coding tool or a person**: follow it directly ("add a Game entity
+following docs/foundation/add-an-entity.md"). In Claude Code,
+`/new-entity <Name>` is a shortcut that runs this same file. It is synced
+from `@tristan2828/ui-foundation` — don't edit it here.
+
+Do not skip steps or reorder them. Replace `<Entity>` with the PascalCase
+entity name (e.g. `Invoice`) and `<entity>` with its kebab-case form
+(`invoice`) throughout.
+
+## Before anything: the entity plan
+
+**Never guess what an entity is.** Every field, type, option list and rule
+comes from `docs/entities/<entity>.md` — the developer's plan, in the
+format of `docs/foundation/entity-plan-template.md` (`docs/entities/widget.md`
+is a filled-in example while the Widgets demo is still here).
+
+- **The plan file exists:** it is the approved spec. Read it in full and
+  build exactly what it says — no extra fields, no invented options, no
+  renamed labels. If something the build needs isn't in it, stop and ask;
+  don't fill the gap yourself.
+- **It doesn't exist:** don't build anything yet. Work the plan out with
+  the developer — ask about purpose, each field and its type, required,
+  option lists, what the table shows, sorts and filters on, and ownership
+  — for as long as it takes. Write `docs/entities/<entity>.md` from the
+  answers, show it, and wait for an explicit go-ahead before step 1.
+- **Either way, stop and raise it (don't improvise) if** the plan has an
+  unresolved item under "Open questions", or needs a field type or screen
+  shape the foundation doesn't support yet (the supported list is in the
+  template). Write the case in `docs/BLOCKERS.md`.
+
+1. **Add `<Entity>` to `openapi.yaml`** — schema, list, get, create, update,
+   delete — exactly as the plan specifies: its fields, types, required
+   fields, option lists (as enums) and length/format rules, and a list
+   query parameter for each field the plan marks as a filter. Reuse the
+   `Page` and error components already in the spec; do not redefine
+   pagination or error shapes per entity, and leave the foundation's part
+   of the spec (`/auth/*`, the error bodies) alone — `ui-foundation
+   check-contract` fails verify if it changes.
+2. **`npm run gen:api`** to regenerate `src/api/schema.d.ts`. Never
+   hand-edit it.
+3. **Add gateway tests in `tests/gateway/<entity>.test.ts`, derived from
+   the spec** — `openapi.yaml` and the UI contracts (`Page<T>`, `AppError`,
+   `QuerySpec`) only, never the code in `src/api/gateway/`, so the tests assert
+   what the spec promises, not what an implementation happens to do. Write
+   them to fail first; the gateway that makes them pass doesn't exist yet.
+   - **If your tool can run an isolated subagent, use one** that can't see
+     those two folders. In Claude Code that's `spec-tester`
+     (`.claude/agents/spec-tester.md`), whose hook *blocks* reading it —
+     the enforced version of this rule.
+   - **Otherwise** write the tests yourself, now, before step 5 creates the
+     gateway, and don't open that folder while writing them. It's the
+     same rule, kept by discipline instead of a hook.
+4. **Add MSW handlers in `src/mocks/<entity>.ts`** and register them in
+   `src/mocks/handlers.ts`. **Include one deliberately sparse row** whose
+   every optional field is empty at once (see `Blank Slate` in
+   `src/mocks/data.ts`). Rows that all populate every field are the reason
+   an "empty value" path goes untested: nothing ever loads a record with a
+   field unset, so an em dash that never renders, or a form control showing
+   a raw sentinel instead of a "not set" label, passes `verify` unnoticed.
+   One row costs nothing and step 8 asserts it. Extend `tests/mocks/conformance.test.ts` so the
+   new handlers are validated against `openapi.yaml`, the same way
+   `widgets`/`categories` already are.
+5. **Add a gateway module in `src/api/gateway/<entity>.ts`** until step 3's
+   tests pass, built on `safeFetch`/`toAppError` from
+   `@tristan2828/ui-foundation/gateway` (see `src/api/gateway/widgets.ts`).
+   Wire → `Page<T>` / `AppError` translation only; no hand-written types
+   (everything comes from `schema.d.ts`).
+6. **Copy the widgets reference files, one for one, not just the two
+   screens** — shaped by the plan: table columns and sortable columns from
+   its "List" column, toolbar filters from its "Filter" column, form fields
+   and labels from its field table, and field types by pattern (a
+   `reference` field copies Category's searchable combobox, a
+   `single choice` copies Status's select, a `date-time` copies
+   Available From's date picker, a `multi choice` copies Tags — the
+   `<MultiChoice>` control from the foundation on the
+   form and as a toolbar filter via `useTableUrlState`'s multi filters,
+   badges in the table, and a `filters` array the gateway sends as a
+   repeated parameter):
+   - `src/routes/widgets/use-widgets.ts`, `use-categories.ts` →
+     `src/routes/<entity>/use-<entity>.ts` (TanStack Query hooks over the
+     new gateway module)
+   - `src/routes/widgets/widget-schema.ts` →
+     `src/routes/<entity>/<entity>-schema.ts` (zod schema mirroring
+     `<Entity>Create`/`<Entity>Update`, plus the form ↔ wire conversion
+     functions — see `widgetToFormValues`/`formValuesToWidgetCreate` for
+     the shape)
+   - `src/routes/widgets/widgets-columns.tsx` →
+     `src/routes/<entity>/<entity>-columns.tsx` (column defs; split any
+     row-action dialogs into their own file, as
+     `delete-widget-action.tsx` does — a fast-refresh hazard otherwise)
+   - `src/routes/widgets/widgets-table.tsx` →
+     `src/routes/<entity>/<entity>-table.tsx` — thin consumer of the
+     foundation's `<DataTable>`. Swap the type, columns, and toolbar
+     filters.
+   - `src/routes/widgets/widget-form.tsx` →
+     `src/routes/<entity>/<entity>-form.tsx` — thin consumer of the
+     foundation's `<EntityForm>` (its `danger` slot takes an edit-only
+     delete). Swap the zod schema and fields.
+
+   **`<SelectValue>` shows the value, not the label.** Base UI renders the
+   raw *value*, and `placeholder` only applies when the value is `null`.
+   Any `Select` whose "nothing chosen" state is a sentinel rather than
+   `null` therefore displays that sentinel on screen unless you pass the
+   children function. This bit every `Select` in the first app built on
+   this foundation. Two cases, both needing it:
+
+   - **A toolbar filter**, where "no filter" is `'all'` — copied straight
+     from `widgets-table.tsx`, which now carries the shape to copy: a
+     label constant read by both the trigger and its `<SelectItem>`.
+   - **An optional `single choice` field**, which Widget has no example of
+     (its `status` is required and its `categoryId` is a combobox). A Base
+     UI `Select` item's value cannot be `''`, so the field's own unset
+     value is remapped through a sentinel:
+
+     ```tsx
+     const UNSET = '__unset__'
+     const UNSET_LABEL = 'Not set'   // the plan's "not set" label
+     // ...
+     <Controller
+       control={form.control}
+       name="priority"
+       render={({ field }) => (
+         <Select
+           value={field.value === '' ? UNSET : field.value}
+           onValueChange={(value) => field.onChange(value === UNSET ? '' : value)}
+         >
+           <SelectTrigger id="<entity>-priority">
+             {/* Without this the trigger reads the literal "__unset__" */}
+             <SelectValue>{(value) => (value === UNSET ? UNSET_LABEL : value)}</SelectValue>
+           </SelectTrigger>
+           <SelectContent>
+             <SelectItem value={UNSET}>{UNSET_LABEL}</SelectItem>
+             {PRIORITIES.map((option) => (
+               <SelectItem key={option} value={option}>{option}</SelectItem>
+             ))}
+           </SelectContent>
+         </Select>
+       )}
+     />
+     ```
+
+     The zod schema keeps `''` as the unset value and converts it to
+     `null` on the way to the wire, the way `widget-schema.ts` already
+     handles a blank `assigneeEmail`. Step 8's specs must assert the
+     **unset** display, not only a picked one — a select whose enum values
+     equal their labels passes either way, which is exactly how this
+     shipped unnoticed.
+
+   **Choosing how each column looks.** The plan says what a field *means*,
+   not how its cell should render. For most columns plain text is right and
+   there is nothing to decide. Where there is:
+
+   - [`cell-patterns.md`](cell-patterns.md) is the catalogue — icon + label,
+     icon in a badge, icon-only with a tooltip, enum → tone-mapped badge,
+     clustered multi-value, link button, relative date, ordinal scale,
+     summary + popover — each with the parts a first attempt gets wrong.
+     They are markup to copy, not components to import.
+   - If the developer doesn't have a preference, don't pick for them and
+     don't guess: follow [`column-options.md`](column-options.md) to build
+     a short page of numbered options over the same sample rows, and let
+     them choose. That is how every pattern in the catalogue was picked.
+   - Any colour involved: [`design-language.md`](design-language.md). Most
+     values should stay grey, and colour is never the only signal.
+7. **Register routes** for `/<entity>`, `/<entity>/new`,
+   `/<entity>/:id/edit` in `src/App.tsx`, and add a nav entry to
+   `src/nav.ts`.
+8. **Add Playwright specs for both screens**, one test per state
+   (`loading`, `empty`, `error`, `validation`, `success`), forced through
+   MSW overrides — `forceMswOverride`, `waitForMswReady` and the
+   `window.__msw` handle from `@tristan2828/ui-foundation/testing`, and
+   `e2e/widgets-table.spec.ts`/`e2e/widget-form.spec.ts` for the pattern.
+   States forced via a first-load init script (loading, load-time error)
+   need `page.addInitScript` before navigation; states forced after the
+   page is already up (a mutation's error response) can use a
+   post-navigation `worker.use()` call gated on
+   `waitForFunction(() => window.__msw !== undefined)`. To stub what an
+   `<img>` loads (a cover or avatar cell), give the override `bodyBase64`
+   and `contentType` instead of `body` — a JSON body makes the image fire
+   `onError` — and stub it through the override, never `page.route`,
+   which cannot see requests the MSW service worker makes
+   (`e2e/msw-contract.spec.ts` has an example).
+9. **Register the nav entry and route names** in `e2e/shell.spec.ts`'s
+   `NAV_ENTRIES` so the shell smoke test covers the new screen, and add
+   `/<entity>/new` to `e2e/a11y.spec.ts`'s `formRoutes` (the table page is
+   picked up from the sidebar automatically; the form isn't in it).
+10. **`npm run verify`.** Fix until it passes. Then stop — do not add
+    anything beyond what this list covers; note ideas in the app's
+    backlog instead.
+
+## What not to copy
+
+- `src/api/gateway/widgets.ts`, `src/mocks/data.ts`, `src/mocks/handlers.ts`
+  are demo-domain content — write the entity's own versions rather than
+  adapting these by find-and-replace.
+- The composites (`DataTable`, `EntityForm`, `ErrorState`, `AppShell`)
+  are the foundation's and shared by every app. If a new entity needs a
+  capability they don't have (a new field-type widget, say), don't copy
+  one into `src/` to change it: raise it for the foundation (AGENTS.md
+  "Changing the Foundation") and build the screen once the release ships.

package/conventions/docs/cell-patterns.md

@@ -0,0 +1,204 @@
+# Cell Patterns
+
+How a column's value should *look*. Each entry is markup plus the bits a
+first attempt gets wrong — **not components**: the lookup maps are always
+per-entity, and only the shape is reusable. Copy the markup into your
+`<entity>-columns.tsx`.
+
+Every pattern below was chosen for a real column, from a page of
+alternatives ([`column-options.md`](column-options.md)), not designed in the abstract.
+A pattern that proves generic is worth raising for the foundation, so it
+ships here for every app.
+
+## The rules that apply to every cell
+
+- **An empty value renders an em dash**, never a blank cell: a blank reads
+  as a rendering bug. Define it once per columns file —
+  `const emptyCell = <span className="text-muted-foreground">—</span>` —
+  and use it everywhere. The one exception is a value whose "nothing" state
+  has its own meaning (an unrated 0-of-5 scale, a missing image), where the
+  shape itself should say so.
+- **Colour is never the only signal.** Greyscale, colourblindness and print
+  all lose it. The label usually carries the meaning; where a cell is a
+  glyph, vary the *shape* too. See [`design-language.md`](design-language.md).
+- **Type every lookup as `Record<TheEnum, …>`** so `tsc` fails when
+  `openapi.yaml` gains a value the map doesn't cover, instead of silently
+  falling back.
+- **A cell that reads across the row needs `row.original`**, not just
+  `getValue()`.
+- **Give a repeated control a row-specific `aria-label`.** Twenty-five
+  buttons all named "Link" are useless to a screen reader.
+
+---
+
+## 1. Plain text
+
+The default, and it wins more often than it looks like it should. Reach for
+something else only when the extra ink buys a decision the reader would
+otherwise have to make themselves.
+
+Always offer a plain-text option when exploring a column — in practice it
+gets picked about as often as the visual ones.
+
+## 2. Icon + label
+
+A single-value enum where a glyph speeds up scanning but the word still
+matters.
+
+```tsx
+const GENRE_ICON: Record<GameGenre, typeof Flame> = { Survival: Flame, Shooter: Crosshair, /* … */ }
+
+cell: ({ getValue }) => {
+  const genre = getValue() as GameGenre
+  const Icon = GENRE_ICON[genre]
+  return (
+    <span className="inline-flex items-center gap-1.5">
+      <Icon className="size-4 shrink-0" aria-hidden />
+      {genre}
+    </span>
+  )
+}
+```
+
+- **Don't wrap it in `Badge`** — beside a multi-value badge column it reads
+  as one more tag.
+- The glyph is decorative next to a visible label, so `aria-hidden`.
+- Check lucide before drawing anything; it covers most vocabularies.
+
+## 3. Icon in a badge
+
+A count or short scalar that should read as a unit.
+
+```tsx
+<Badge variant="outline">
+  <UsersIcon data-icon="inline-start" />
+  <span className="tabular-nums">{maxPlayers}</span>
+</Badge>
+```
+
+`Badge` already sizes child `svg`s and pads for
+`data-icon="inline-start"|"inline-end"` — don't add a wrapper.
+`tabular-nums` keeps a numeric column from jittering.
+
+## 4. Icon only, label in a tooltip
+
+An enum where the glyph alone is enough at a glance and the column is
+narrow.
+
+```tsx
+<Tooltip>
+  <TooltipTrigger render={<span role="img" aria-label={support} tabIndex={0} />}>
+    <GamepadGlyph support={support} />
+  </TooltipTrigger>
+  <TooltipContent>{support}</TooltipContent>
+</Tooltip>
+```
+
+- Base UI's `TooltipTrigger` renders a **`<button>`** by default. A
+  read-only cell isn't a button: `render={<span role="img" aria-label … tabIndex={0} />}`
+  keeps it focusable and named without faking one.
+- Needs the `TooltipProvider` that `AppShell` mounts — free in any
+  cell, absent in an isolated Storybook story.
+- Encode the value in the glyph's **shape** (solid / half / slashed /
+  dashed), not its colour.
+
+## 5. Enum → tone-mapped badge
+
+A many-valued enum that collapses to good / neutral / bad. **The grouping
+is the decision, not the style** — see
+[`design-language.md`](design-language.md#mapping-an-enum-to-tones).
+
+Keep a separate short-label map when the API strings are full sentences
+(`"Yes – Full Crossplay"` → `Full`): read once in a dropdown they're right,
+read down 25 rows under a column header they're noise.
+
+## 6. Multi-value enum, clustered
+
+A column holding several values from one enum. Cluster by family, with the
+family's icon once at the start of each cluster, rather than one badge per
+value — a six-value row is the stress case that kills per-value styles.
+
+- The family taxonomy is a **display decision made in the columns file**,
+  not part of the API contract.
+- Clustering **discards the picked order**, so if "first = primary" means
+  something, say in a comment that the form still preserves it.
+- Needs an empty case and a wrap policy (`flex flex-wrap gap-1`).
+- Tests that matched each value as its own element break when values share
+  a badge — assert `toContainText` on the row.
+
+## 7. Link as an outline button
+
+An external URL.
+
+```tsx
+<Button
+  variant="outline" size="sm" nativeButton={false}
+  aria-label={`Link to ${row.original.name} store page`}
+  render={<a href={link} target="_blank" rel="noreferrer" />}
+>
+  Link
+  <ExternalLinkIcon />
+</Button>
+```
+
+- `render={<a />}` **plus** `nativeButton={false}` is what keeps it a real
+  anchor styled as a button. A `<button>` wrapping an `<a>` is invalid, and
+  Base UI warns without the flag.
+- Every row shows the same word, so the `aria-label` must name the row —
+  and must still contain the visible text.
+- Null renders `emptyCell`, not a disabled button.
+- **Cost:** the loudest link style; a long table becomes a wall of buttons.
+
+## 8. Date, relative
+
+When the useful question is "how soon?" rather than "which day?".
+
+- `Intl.RelativeTimeFormat(undefined, { numeric: 'auto' })` gives
+  `tomorrow`/`today` free, but it takes **one unit** — write a ladder (days
+  under 2 weeks, weeks under ~2 months, months under 2 years, then years)
+  or you get "in 44 days".
+- An API `format: date` is a calendar day with no time. Parse as
+  `T00:00:00Z`, format with `timeZone: 'UTC'`, and count from **local today
+  rebuilt as UTC midnight** (`Date.UTC(y, m, d)`). Subtracting `Date.now()`
+  shifts the answer by a day for anyone west of UTC.
+- Relative text **goes stale**, so a fixture pinning a date drifts. Freeze
+  the clock (Playwright's `page.clock`) in any test asserting one.
+- `title` is mouse-only. If the exact date matters, use pattern 4 instead.
+- **Cost:** "2 years ago" is vague, and the column doesn't look sorted even
+  though server-side sorting still works.
+
+## 9. Ordinal scale (bounded integer)
+
+A 1–5 rating or similar. The grouping step from pattern 5 applies, but the
+values are a **range**: read the min/max from `schema.d.ts`, band it
+(5 and 4 share a tone, 3 alone, 2 and 1 share), and treat "not set" as its
+own state.
+
+- Token colours work as SVG fills (`fill-success-text` plus
+  `text-success-text`), and the tone classes must be whole strings picked
+  by a function — Tailwind won't generate one built from a value.
+- The filled **count** carries the value; the tone only reinforces it, so
+  the cell survives greyscale.
+- Accessible name on a wrapping `<span role="img">` with the glyphs
+  `aria-hidden`, saying the value in words and handling "not set".
+- Very faint "empty" glyphs fall below the 3:1 non-text minimum, and axe
+  does not check icon contrast. That's a defensible choice — make it
+  deliberately, in a comment, not by accident.
+
+## 10. Summary in the cell, detail in a popover
+
+A one-to-many value (`★ 4.7 (3)` opening a per-person breakdown).
+
+- Use `Popover` with `<PopoverTrigger openOnHover delay={100}>`, **not**
+  `Tooltip`: a tooltip can't hold rich content and is unreachable on touch.
+  Here the trigger *should* be a real `<button>` — it opens something —
+  unlike pattern 4.
+- shadcn's `hover-card` exists but has nothing to tap on touch, so it is
+  deliberately not used for information not available elsewhere in the row.
+  Say so, or someone will "fix" it.
+- `PopoverContent` defaults to `w-72`; use `w-auto min-w-48` for a short list.
+- The popup is **portaled** — Playwright must query
+  `page.getByRole('dialog')`, not within the row.
+- **Cost:** the detail can't be scanned down the column, and an average
+  can't be sorted server-side without a backend change
+  (`enableSorting: false`).

package/conventions/docs/column-options.md

@@ -0,0 +1,122 @@
+# Choosing How a Column Displays
+
+An optional step in [`add-an-entity.md`](add-an-entity.md), for a developer
+who knows what the data *means* but not what it should look like.
+
+Instead of the agent picking a cell style and the developer reacting to it,
+the agent builds a page of numbered options rendering **the same sample
+rows** in each style, and the developer replies with a number. That has now
+picked eight columns across a real app, and the choices it produced are
+[`cell-patterns.md`](cell-patterns.md).
+
+Run it per column, and only for columns where it isn't obvious. A plain
+text column doesn't need a page.
+
+## What the page must contain
+
+**Open with the value, before any style.** Two lines that decide most of
+what follows:
+
+- The field's **type, range and how "unset" is represented**, read from
+  `schema.d.ts` — not every field is an enum. A 1–5 integer whose
+  "not rated" state is *absence from a list* is a different problem from a
+  nullable enum, and the page should say which it is.
+- A **value grouping**: how many values mean good, bad, or neither, and
+  which ones can share a tone. For a many-valued enum this is the real
+  decision, and making it first renders half the styles obviously wrong.
+  If the agent invented a taxonomy (families, bands, thresholds), show it
+  as a **legend and flag it as a guess** — that's usually what the
+  developer actually wants to change.
+- **Why this column differs from the last one explored.** "One value, no
+  good/bad axis, so colour has nothing to say by default" saves a round.
+
+**Sample rows must span the value's cardinality, not just its values.**
+For a multi-value column: 1, 2, 3, 5 and 6 values *plus an empty row*. For
+a bounded scale: one row per value plus the unset row. The six-value row
+is what kills one-badge-per-value styles; the empty row surfaces the null
+case for free. For a date column, pin "today" in the header and choose
+rows relative to it, or the page's own relative strings rot.
+
+**Number the cards** so the developer can reply "5". If a second round is
+requested, **append** rather than renumber — the earlier numbers have
+already been used in conversation.
+
+**Per card:**
+
+- A **one-line tradeoff** and a **cost line**: what this style trades away
+  (an extra text shade, ambiguity of blank, needs colour, more ink).
+- **Capability tags** for a multi-value column — ✓ shows who rated, ✓ shows
+  disagreement, ✓ still fits 5+ values. This compares options on what each
+  *preserves*, which for a multi-value column matters more than looks.
+- A **backend-implication note** where one applies. "Sorting by average
+  needs a backend change — not sortable server-side today" reads to a
+  backend developer the way visual weight reads to a designer, and it stops
+  an unbuildable option winning on looks.
+- **Collision with neighbouring columns.** An outline badge beside a badge
+  column, or "★ n" beside an existing ratings column, looks identical to
+  its neighbour — a failure only visible in context.
+
+**Group the cards by what they cost the design system**, not by look:
+*fits as-is* / *needs new tokens* / *removes the column*. In a system whose
+Hard Rule bans palette colours, whether colour is worth new tokens **is**
+the decision, and grouping puts it on the page before any style is judged.
+
+**Include the boring option.** A plain-text style gets picked about as
+often as the visual ones. A page of only visual options is a loaded
+question.
+
+**Include options that remove the column** where they exist (the value as
+a subline under the name; rows grouped under a header), with their cost in
+`DataTable` terms: no column to sort by, and grouping fights both column
+sorting and server-side pagination.
+
+**For an editable cell, answer read-versus-edit up front.** Every display
+style silently decides whether one-click editing survives. Put a "decision
+for you" callout on the page, tag each card *keeps picker / read-only*, and
+list what else touches the cell — e2e tests driving the control, docs
+describing it. Moving a rating to the edit screen is a test-and-docs
+change, not a one-line cell change.
+
+## Controls on the page
+
+- **"Try it in a table"** — a switcher that re-renders one sample table
+  (real column names, ~7 rows including an empty one) in the selected
+  style. A style that looks fine in an isolated card can be far too noisy
+  down 25 rows; this is the single most useful control on the page.
+- **Greyscale toggle** (`filter: grayscale(1)` over every card) — the cheap
+  colourblind check, and it settles which options depend on hue alone.
+- **Tone toggle** (none / three tones) and **order toggle** (as picked / by
+  family) where they apply. Global toggles over all cards beat per-card
+  variants: a request like "card 1's shape with card 5's tone rule" is a
+  toggle that was missing.
+- **Demo interaction live** (CSS `:hover`/`:focus`) for any style whose
+  point is an interaction. A static screenshot hides exactly what's being
+  judged.
+
+## The one recurring failure: drift
+
+Every options page so far re-implemented the cells in vanilla CSS with
+copied tokens, and every one drifted:
+
+- an amber the app had no token for
+- a text shade of `oklch(0.42)` where the app shipped `0.5`
+- lucide glyph paths typed from memory
+- a `color-mix` tinted fill the design system had no variant for — and that
+  one **changed the outcome**: the developer picked it, and it had to be
+  rebuilt as the app's existing `secondary` fill
+
+An option using a fill the design system can't produce is being judged as
+something the app can't render.
+
+**Render the options from the app's real components.** Storybook is already
+in this repo and is the obvious host: the cards then use the real tokens
+and the real `Badge`, and the winner can be copied straight out. Do this
+rather than hand-writing a standalone HTML page.
+
+## After the pick
+
+Implement it in `<entity>-columns.tsx`. If the pattern isn't already in
+[`cell-patterns.md`](cell-patterns.md), raise it for the foundation — that
+file is synced from the package, so an addition there reaches every app —
+with the bits that were non-obvious while building it, not just the final
+markup.

package/conventions/docs/design-language.md

@@ -0,0 +1,116 @@
+# Design Language
+
+The part of this foundation a consuming app cannot cheaply get right on
+its own: color that carries meaning, checked for contrast in both themes.
+Tokens and styles here **grow freely**, in the foundation package, so every
+app gets them: they do not wait for a second app to need them. New
+composites don't grow that way; they are built against a real app's screen.
+
+## Semantic tones
+
+Three tones carry meaning: **success**, **warning**, **destructive**. Grey
+is not a tone — it is the absence of one, and most values should stay grey.
+
+Each tone has two kinds of token, and picking the wrong one is the single
+most common way to ship an unreadable label:
+
+| Token | For | Why it can't be the other one |
+|---|---|---|
+| `--success` / `--warning` / `--destructive` (+ `-foreground`) | a **solid fill**, always with white text on it | chosen to contrast with *white*, so on the page background it's too light in light mode |
+| `--success-text` / `--warning-text` / `--destructive-text` | the tone as **text, a border or an icon** on the page background | chosen to contrast with *the page*, so as a fill under white text it's needlessly dark |
+
+Only the `*-text` tokens are remapped in `.dark`. A solid fill keeps one
+shade in both themes, because it always carries white text and the page
+behind it never enters the calculation.
+
+Measured ratios (WCAG 2.x, sRGB) are recorded next to each primitive in
+the package's `styles/theme.css`, and its `e2e/storybook-visual.spec.ts` re-checks all
+nine tone/style combinations with axe against the rendered DOM in both
+themes. **A new tone or style is not done until it appears in that story.**
+
+## The three badge styles
+
+`Badge` ships each tone in three styles. They are not interchangeable:
+
+- **Outline** — `outline-success`, `outline-warning`, `outline-destructive`.
+  The default choice, and the one proven across real columns. Quiet enough
+  to repeat down 25 rows without the column becoming a wall of color.
+- **Tinted** — `tinted-success`, `tinted-warning`, `tinted-destructive`. A
+  low-alpha wash of the tone with `*-text` on top. More presence than
+  outline; use when the value is the point of the row, not a detail of it.
+- **Solid** — `success`, `warning`, `destructive`. The loudest. Use for one
+  value that must be impossible to miss, rarely for a whole column: solid
+  reads as an alert, and a column of alerts reads as noise.
+
+Pick **one style per table** and vary only the tone. Mixing styles across
+columns makes the difference look meaningful when it isn't.
+
+## Mapping an enum to tones
+
+The decision is the **grouping**, not the style. Before choosing how it
+looks, write down which values mean good, which mean bad, and which mean
+neither — including the ones that look distinct as text but should share a
+tone.
+
+```tsx
+const STATUS_BADGE_VARIANT: Record<WidgetStatus, 'outline' | 'outline-success' | 'secondary'> = {
+  draft: 'outline',
+  active: 'outline-success',
+  archived: 'secondary',
+}
+```
+
+Type the lookup as `Record<TheEnum, …>` so `tsc` fails when `openapi.yaml`
+gains a value with no tone, rather than falling back silently.
+
+Two rules that keep this honest:
+
+- **Most values are neutral.** If more than about a third of an enum is
+  coloured, the colour has stopped meaning anything. Widget's `archived` is
+  an end state, not a failure — it stays grey.
+- **Never let colour be the only signal.** A colourblind reader, a
+  greyscale screenshot and a printed page all lose it. The label text
+  usually carries the meaning already; where a cell is a glyph rather than
+  a word, vary the *shape* (filled / half / slashed) too, not just the hue.
+
+## Categorical colour
+
+Tones say good or bad. A value that is merely *different* from its
+neighbours — a genre, a team, a category — needs a different mechanism, and
+it is `--category-1` through `--category-8`.
+
+They are **generic slots, not per-value tokens**. An app maps its enum to a
+slot in its own columns file, so a new enum value costs a line there rather
+than three tokens in the design system:
+
+```tsx
+const GENRE_COLOR: Record<Genre, string> = {
+  Survival: 'text-category-1',
+  Shooter: 'text-category-2',
+  RPG: 'text-category-3',
+}
+```
+
+Tailwind needs whole class names, so map the value to a complete class —
+never build one by interpolation, or the class won't be generated.
+
+Four things about them:
+
+- **The hues avoid red, green and amber**, which the tones already spend. A
+  category drawn in red reads as "this one is bad" even when nothing is
+  wrong.
+- **They are ordered by distinctness, not by hue angle.** An app using
+  three categories gets three obviously different colours. Past about five,
+  hue alone stops separating them — slots 3 and 7 are both yellow-greens —
+  so the glyph has to carry the meaning and the colour only reinforces it.
+- **Tint the glyph, never fill behind text.** The label stays
+  `text-foreground`, so readability never depends on the hue. A slot used
+  as a background needs its own contrast check, which nothing here does
+  for you.
+- **Nothing re-measures them automatically.** All eight clear the 3:1
+  non-text minimum in both themes (measured, recorded in `theme.css`), but
+  axe checks text contrast, not icon contrast — so a change to these
+  values is not caught by any gate.
+
+If you find yourself wanting a ninth, that is usually a sign the column
+should be showing a shape or a label rather than more colours.