@thewhatmatters/wmds 0.4.9 → 0.4.28

package/CHANGELOG.md

@@ -7,6 +7,309 @@ Every release of `@thewhatmatters/wmds` is listed here, newest first.
 - **Pasted patterns:** when a release changes a **Pattern — …** story's Show code, it is named under Consumer actions so apps re-copy it.
 - **How to add an entry** (contributors): add your change to the top entry. If that version is already on npm (`npm view @thewhatmatters/wmds versions`), start a new entry above it and bump `version` in `package.json` to match. `npm run check:changelog` enforces the format.
 
+## 0.4.28
+
+**AlertDialog takes a body, Input takes a rich label, and dialogs get a roomier edge.**
+
+- **InlinePill** (new): a pill that sits inside running text and scales with it (em-sized), with an optional picture on its left held in the pill's padding so it never parts from its word. `useInlinePillsPopIn()` pops the pictures in one after another when the text scrolls into view, on the WMDS motion tokens; nothing under reduced motion. Not a control: `Chip` and `Badge` stay UI-sized. Story **Components/InlinePill**, with a 390px long-word test.
+- **AlertDialog** `children` (new) — content between the description and the actions, such as a typed-confirmation **Input**. It renders outside the description `<p>`, so `aria-describedby` still names the description alone. Cancel still takes initial focus. Without `children` the markup is unchanged.
+- **Input** `label` is now `ReactNode` (was `string`), so a label can read "Type **@handle** to confirm". The `<label htmlFor>` association is unchanged, and the whole label is the field's accessible name. A string label behaves as before.
+- **Pattern — alert dialog (typed confirmation delete)** is new on **Components/Dialog**: Delete stays off until the typed value matches the handle (a leading `@`, case, and surrounding spaces are ignored), and the field clears on reopen. **Pattern — rich label** is new on **Components/Input**.
+- New interaction test **Internal/Interactions/Overlay → AlertDialog — typed confirmation**.
+- **Dialog** and **AlertDialog** edge inset is **24px** on every side, phones included (was 16px): header, body, and footer share the same horizontal inset, and the panel's top and bottom are 24px. A pill action now clears the 16px panel radius instead of sitting in the corner. **Sheet**, **Panel**, and **Card** keep their 16px layout. `dialogStyles` adds `dialogPanelInsetXClasses`, `dialogHeaderInsetTopClasses`, `dialogFooterInsetBottomClasses`.
+- **Dialog**, **Sheet**, and **IntakeModal** scroll lock no longer leaves a pale strip at the trailing edge on platforms with classic scrollbars: `html { scrollbar-gutter: stable }` kept that strip after the body stopped scrolling, and the fixed scrim cannot paint into it. While a modal is open the gutter is released and the body takes its width as `padding-right`, so the page behind does not move and the scrim reaches the edge.
+- **Loading keeps keyboard focus.** **Button** `status="loading"` (and `"error"` with `disableOnError`), **IconButton** `loading`, **Checkbox** `loading`, and **Switch** `loading` set `aria-disabled` and ignore presses instead of setting native `disabled`, which dropped focus to `<body>` mid-submit. `disabled` still sets native `disabled`. **FilterPanel** Clear all moves focus to the first group (rail) or the results button (Sheet) as it disables itself. New interaction test **Internal/Interactions/Button → a loading button keeps keyboard focus and ignores presses**.
+- **Field** `description` now reaches the control: Field appends its description id to the single child's `aria-describedby` (keeping the child's own ids) instead of setting it on the wrapper `<div>`, where screen readers ignored it. A multi-control Field keeps it on its `role="group"`. **Select** takes `aria-describedby` (new) and joins it with its own `description`. New interaction test **Internal/Interactions/Form controls → Field — description describes the control**.
+- **AlertDialog** (and **Dialog** with `dismissOnBackdrop={false}`): a press on the scrim no longer moves focus to `<body>`, where the next Tab left the dialog. The interaction test **AlertDialog — confirm and cancel** now presses the scrim and checks focus stays inside.
+- **AppShell** has a skip link (new): the first Tab shows "Skip to content" over the top-start corner, and Enter moves focus to `<main>` without changing the URL. `labels.skipToContent` (new) words it. New interaction test **Internal/Interactions/AppShell → the first Tab reaches a skip link that moves focus to the page**.
+- **SiteNav**: while the compact bar is pinned (`placement="fixed"` or a `scrollContainer`), the page (or that container) gets `scroll-padding-top` of `--site-nav-height` plus 16px, so an element focused with Tab scrolls into view below the bar instead of under it. The previous value comes back when the bar unpins or unmounts. New interaction test **Internal/Interactions/SiteNav → pinned compact bar keeps focused elements out from under it**.
+- **Dialog**, **Sheet**, **IntakeModal**, and **Panel** share one open/close lifecycle (`useOverlayLifecycle` in `lib/dialogOverlay`, internal). What changes for users:
+  - **Escape closes only the topmost overlay**, so an AlertDialog over a Sheet no longer closes both. An Escape that a control inside already handled (`defaultPrevented`) is left alone.
+  - **Dialog** and **IntakeModal** make the page behind inert, as **Sheet** already did, so a screen reader's virtual cursor stays in the modal.
+  - **Panel** moves focus into itself on open (its first control).
+  - On close, focus returns to the opener only if it is still in the page and focus has not moved on elsewhere; otherwise it goes to `<main>`. This was Sheet-only before.
+  - Stacked modals share one scroll lock, so the page scrolls again however they close (closing them out of order used to leave it locked).
+  - New interaction tests in **Internal/Interactions/Overlay lifecycle** cover the shared lifecycle and each of the four overlays.
+  - **IntakeModal** `dismissOnEscape` (new, default `true`): set `false` so Escape cannot drop typed answers.
+- **Menus share one behaviour** (`useDropdownMenu`, internal, in the Dropdown folder). **Select**, **MoreMenu**, and **Breadcrumb**'s "…" menu:
+  - **Escape** closes only the menu and returns focus to its trigger, so a menu inside a **Dialog** or **Sheet** no longer closes the overlay too. An Escape during IME composition is ignored by menus and overlays.
+  - **Tab** closes the menu. A press outside closes it (`pointerdown`, so touch works too). Scroll and resize keep it attached to its trigger.
+  - **Keyboard:** ArrowDown/ArrowUp, Home/End, and type-ahead; disabled rows are skipped.
+  - **Screen readers hear the active row.** **Select**'s trigger is a select-only `combobox` naming the active option with `aria-activedescendant`. **MoreMenu** and Breadcrumb move real focus onto the rows; Space chooses a row like Enter does.
+  - **Tab** and **SiteNav** More menus use it too, through one overflow module (`useOverflowMenu`) that owns measuring, the fit, and the More menu. SiteNav no longer reaches into Tab. More menus now follow their trigger on scroll instead of closing, and stop listening for Escape on the whole page.
+  - **SiteNav** More rows are real links (`<a href>`), so Cmd-click and middle-click open a new tab.
+  - **Tab**: More now sits beside the `tablist` instead of inside it (a `tablist` may only own tabs), which clears the accessibility violations its overflow stories were waiving.
+  - New interaction tests in **Internal/Interactions/Menus** cover the shared behaviour and all five menus, including a Select and a MoreMenu inside a **Dialog** and a Breadcrumb inside a **Sheet**, where Escape closes the menu and leaves the overlay open.
+  - **Dropdown.Item** forwards its ref. A row that is both active and selected now shows the active fill, so focus is visible on it.
+- **Theme** sets `color-scheme` (new): `light` on `:root` and `dark` under `[data-theme="dark"]`, so native scrollbars, form controls, and autofill follow the theme instead of staying light in dark mode.
+- **`docs/exports.json`** now lists all 41 lib helpers `src/index.ts` exports (was 12). Nothing was added to or removed from the package. `npm run validate:manifest` now also fails when `src/index.ts` exports a lib helper the manifest does not list.
+
+- **Brand kit (new).** A client's brand is now a short `brand.css` of allow-listed knobs (**CONSUMING.md → Brand kit**):
+  - **Type:** `--font-display` (every `type-display-*` step; unset follows `--font-family-heading`), `--font-display-weight`, `--font-display-tracking`, `--font-display-case`, and a `--font-serif` slot. `--font-family-heading` is now allow-listed too. With none set, type renders as before.
+  - **New display steps:** `type-display-hero` (fluid to 16vw, `--text-display-hero-size` knob) and `type-display-xl` (44px → 136px), both with tight leading and safe word breaks on phones.
+  - **Section colours:** `--color-brand-surface` / `--color-on-brand-surface` (default: the navy) and `--color-field` / `--color-on-field` (default: the primary), each with an optional `-muted` step.
+  - **Band (new component):** `tone` `default` / `inverse` / `field` sets `data-tone`, which remaps surface, text, border, fill and focus roles so every component inside re-skins. It holds its own `grid-page`; inside a `grid-page` it bleeds to the viewport edges (no horizontal scrollbar) and keeps the page's columns. `spacing` `md` / `lg` / `none`. New stories **Components/Band → Pattern — page in bands** and **Foundations/Brand kit → Theme a client** (the offer-sheet values with a contrast table); new interaction tests **Internal/Interactions/Band**.
+  - **wmds-check** `brand-contrast` (new, error): fails an on-colour or muted step under 4.5:1 on its colour, for primary, brand surface and field, when both are hex in the same CSS rule. It now reads the app's `.css` files.
+  - **TextSequence** word masks reach 0.08em above and to the sides of each word, so tall caps on tight display leading and outline strokes aren't clipped. Layout is unchanged.
+- **Design knobs for shape (new).** `--radius-control` (default pill) and `--radius-surface` (default 16px) reshape every control and surface. Set them on `:root`, or on a wrapper with Tailwind (`[--radius-control:4px]`), for rectangular buttons, inputs, selects, chips, badges and tabs, and squarer cards and menus. Avatars, dots, spinners, radios, switches and progress bars stay round. Defaults are unchanged: every component renders as before. **CONSUMING.md → Design knobs**; new story **Foundations/Shape → Design knobs — rectangular controls**; new interaction test **Internal/Interactions/Shape**.
+
+### Consumer actions
+
+None. To ask for a typed confirmation, pass an **Input** as `children` of **AlertDialog** and set `confirmDisabled` until the value matches. Copy **Components/Dialog → Pattern — alert dialog (typed confirmation delete)**. A **Dialog** or **AlertDialog** is 16px wider on each side's content inset and 16px taller (8px top, 8px bottom); check the narrowest phone width. No `className` change is needed. `npx wmds-check` now reads your `.css` files: if `brand-contrast` fails on an existing `--color-on-primary`, pick an ink that clears 4.5:1 (or mark a deliberate exception with `/* wmds-check-ignore brand-contrast <reason> */` on the line above). To carry a client's type and section colours, see **CONSUMING.md → Brand kit** and replace hand-rolled section colours with **Band** `tone`.
+
+## 0.4.27
+
+**An opt-in counter for the Carousel.**
+
+- **Carousel** `counter` (new, default `false`) — a visible "1 of 6" under the row on `type-supporting`, `text-muted`, tabular figures; announced politely (`aria-live="polite"`) as the item the row rests on changes; hidden (keeping its space) while every item fits. `labels.counter(position, count)` words it.
+- **Carousel** `onIndexChange(index, count)` (new) — 0-based; fires once the row has been still for a moment and the item it rests on has changed. At the end of the row the index is the last item.
+- **Carousel** `activeIndex` (new) — controlled: the row moves to that item (0-based) when it changes; the first value is applied without a glide.
+- With none of the new props, the markup and behavior are unchanged.
+- Stories: **Carousel → Review — 390 counter** and **Reference — count outside the row**. See the ADR-0043 addendum.
+
+### Consumer actions
+
+None. To show the count, pass `counter`; to show it elsewhere, pass `onIndexChange`. No **Pattern — …** Show code changed.
+
+## 0.4.26
+
+**A side sheet with header actions, a phone layout, and URL state.**
+
+- **Sheet** `Sheet.Content` `headerActions` (new) — controls before the close (**IconButton** `size="sm"`: previous / next, share).
+- **Sheet** `side="end"` is **full-screen below `md`** (no inset, no radius; header and footer pinned, body scrolls, footer clears the home indicator). From `md` it is a rail over a lighter scrim (`bg-overlay/50`). The page behind is `inert` while open; closing a deep-linked sheet moves focus to `main`; reduced motion fades instead of sliding.
+- **`useSheetParam(kind, { initialUrl? })`**, **`readSheetParam(url)`**, **`withSheetParam(url, id | null, kind)`** (new) — keep a sheet in `?sheet=<kind>&id=<id>` with the History API, no router. Back closes; a deep link opens on first render; `initialUrl` serves the open sheet from the server.
+- New patterns: **Components/Sheet → Pattern — side sheet**, **Pattern — side sheet header actions**, **Pattern — side sheet URL deep link**; **Components/Table → Pattern — approvals with sheet**.
+- See ADR-0049.
+
+### Consumer actions
+
+None required. Every `side="end"` **Sheet**, including **SiteNav**'s phone menu, is now full-screen below `md`; check a phone width. To keep a detail in the URL, wire `useSheetParam` as in **Pattern — side sheet URL deep link** (new patterns, nothing to re-copy).
+
+## 0.4.24
+
+**One focus ring on TextArea and Input.**
+
+- **TextArea** and **Input** no longer show a second ring. The shell's ring sat 2px off the border behind a page-colored gap, so it read as a gray ring around the field's own edge. The ring now hugs the border, one `--color-focus-ring` (or status ring) token, for solo and validation shells.
+- The inner field of **TextArea**, **Input**, **PromptBar** and **CopyField** drops its outline and ring with `!important`. A global `:focus-visible { outline }` rule in an app is unlayered and used to beat the component's layered `outline-none`, which painted a blue ring inside the shell.
+- New **Components/TextArea → Focused** story.
+
+### Consumer actions
+
+None.
+
+## 0.4.23
+
+**The package loads under Node, and TextArea announces progress.**
+
+- **Fixed:** importing `@thewhatmatters/wmds` in Node ESM (a node test runner, or vitest in a DOM environment) threw `SyntaxError: Named export 'Rive' not found`. `@rive-app/react-canvas` is CommonJS, and **RiveHand** imported it by name; Node only exposes `default` for a CommonJS module. **RiveHand** now reads the runtime from the namespace and falls back to `default`, so bundlers (Vite, Next) and Node both load it. The `motion` imports were not the cause. The build now imports `dist/index.js` in Node, and a unit test does the same.
+- **TextArea** `liveStatus` (new) — progress text under the field, in a polite live region (`role="status"`, `aria-live="polite"`). Pass `""` when idle so the region stays mounted and "Saving…" / "Saved" are heard. It is separate from the validation `status` + `message`. `description` and `message` were already tied to the field with `aria-describedby`; tests now cover it.
+- **Pattern — save status** is new on **Components/TextArea**.
+
+### Consumer actions
+
+None. To announce a save state, pass `liveStatus`. Copy **Components/TextArea → Pattern — save status** (`docs/patterns/components-textarea--save-status.tsx`) for a worked example.
+
+## 0.4.22
+
+**A pinned sidebar footer, and AppShell on the server.**
+
+- **AppShell** `sidebarFooter` / **AppShell.SidebarFooter** (new) — pinned to the bottom of the sidebar column and the phone **Sheet**. The **NavList** scrolls on its own above it, so a theme switch stays visible at 1440x900 and on a phone. No new color, border, radius, or shadow.
+- **Pattern — portal dashboard** now puts a **DisplayControls** `controls="theme"` switch in the footer.
+- Documented: the phone toggle's accessible name is **"Menu"** (`labels.menu`), and the docs now say which parts render on the server, which need a `"use client"` boundary, that `displayThemeNoFlashScript` goes in `<head>`, and a Next.js App Router example (`docs/component-contracts.md → AppShell — server rendering`).
+- See the ADR-0047 addendum.
+
+### Consumer actions
+
+None for existing shells. To pin a footer, pass `sidebarFooter`. Re-copy **Components/AppShell → Pattern — portal dashboard** (`docs/patterns/components-appshell--portal-dashboard-pattern.tsx`) to get the theme switch in the footer.
+
+## 0.4.21
+
+**A table.**
+
+- **Table** (new, atom) — `Table`, `TableHeader`, `TableBody`, `TableFooter`, `TableRow`, `TableHead`, `TableCell`, `TableCaption`. Semantic HTML in a focusable, horizontal-scroll `region`. No new color, radius, shadow, or variant.
+- Patterns: **Components/Table → Pattern — basic table** and **Pattern — approvals queue** (Approve `primary`, Deny `outline`, an inline Confirm deny / Cancel step in the same row, then a success or failed status pill; keyboard focus follows, Escape cancels, and each button's `aria-label` carries the row name). States: deny confirm step, decided, empty, mobile 390.
+- **Table** polish: headers use `ui-label` and the caption `body` (one step up), `sticky` on `TableHead` / `TableCell` pins a column to the start edge (existing `bg-body` surface), and a table with a `colgroup` lays out from its `col` widths (fixed layout) so an empty and a filled table match.
+- **Pattern — approvals queue**: the row keeps one height through pending, confirm, and decided (44px decision slot); focus after a decision lands on the status pill and shows the `focus-ring` only for keyboard focus (no box after a mouse click); the Name column is sticky; a `colgroup` fixes the column widths for the filled and empty states.
+- **Pattern — approvals queue** on a phone (below `sm`, 640px): each row stacks as an outlined **Card** — name, then type and waiting, then **Approve** and **Deny** each taking half the row, all visible without sideways scroll. The deny confirm stays inline (Confirm deny · Cancel in the same slot) and the 44px decision slot keeps the card one height through pending, confirm, and decided. From `sm` the table is unchanged. No new color, radius, shadow, or Button role.
+- `Table` moves out of the planned list.
+- See ADR-0048.
+
+### Consumer actions
+
+None for existing pages. If you pasted **Pattern — approvals queue** from an earlier draft, re-copy `docs/patterns/components-table--approvals.tsx` (**Pattern — approvals queue** changed: phone card layout; it now also imports `Card`). To adopt it, `import { Table } from "@thewhatmatters/wmds"` and paste a **Components/Table** pattern (`docs/patterns/components-table--basic.tsx`, `docs/patterns/components-table--approvals.tsx`).
+
+## 0.4.20
+
+**An app shell.**
+
+- **AppShell** (new) — a sidebar on the page background and the page as an inset, raised surface with a title bar. It composes **NavList**, **PageHeader** `variant="app"`, **Sheet** (the sidebar below `lg`), and **Panel** (the optional aside). No new color, radius, shadow, or variant.
+- `<AppShell title brand sidebar header aside>` or the slots **AppShell.Brand**, **Sidebar**, **Header**, **Aside**. A `PanelLeft` toggle collapses the sidebar, **Ctrl** / **⌘** + **B** does the same, and `useAppShell()` returns the state.
+- Patterns: **Components/AppShell → Pattern — portal dashboard**. States: collapsed, aside open, phone, phone menu open.
+- **PageHeader** now applies `aria-label` when `title` is also set (it used to drop it), so a page header can have a name that tells it apart from other banners.
+- **Sheet**, **Panel**, **Dialog**, and **AlertDialog** headers carry `role="presentation"`, so an open overlay no longer adds a second `banner` landmark beside the page header.
+- See ADR-0047.
+
+### Consumer actions
+
+None for existing pages. To adopt it, `import { AppShell } from "@thewhatmatters/wmds"` and paste **Components/AppShell → Pattern — portal dashboard** (`docs/patterns/components-appshell--portal-dashboard-pattern.tsx`).
+
+## 0.4.19
+
+**A chart beside a stat column.**
+
+- **Pattern — revenue by line** composes **Chart.Cartesian** and a column of **Stat** inside a **Card**. No new component.
+- The same pattern includes the unwired state: "Revenue by line is not wired". Do not draw a series until the source exists.
+
+### Consumer actions
+
+Paste **Components/Chart → Pattern — revenue by line** (`docs/patterns/components-chart--revenue-by-line.tsx`). Keep the unwired card until revenue by line is connected. Drop it once `data` is real.
+
+## 0.4.18
+
+**A log viewer, and a dark detail pane.**
+
+- **LogView** (new) — line numbers, a tabular line count, **Copy**, and **Follow**. `follow` keeps the scroller on the last line. `loading` is a **Skeleton**. An empty log says "No log lines".
+- **Stat** `detail` — one tabular line under the figure, for example "3 new". Hidden while `loading` or `unavailable`. Hero props (`size="lg"`, `context`, `icon`, `action`, `unavailable`) stay.
+- Patterns: **Components/LogView → Pattern — log viewer**, **Pattern — detail pane** (prev/next, tags, a 2×2 stat grid, the log, on `data-theme="dark"`).
+
+### Consumer actions
+
+`import { LogView } from "@thewhatmatters/wmds"`. Paste **Components/LogView → Pattern — log viewer** (`docs/patterns/components-logview--log-viewer.tsx`) and **Pattern — detail pane** (`docs/patterns/components-logview--detail-pane.tsx`). Pass `detail` on **Stat** for the sub line. Existing hero stats keep `size`, `context`, `icon`, `action`, and `unavailable`.
+
+## 0.4.17
+
+**Card.Body can be a terminal frame.**
+
+- **`Card.Body variant="terminal"`** is a dark embed. `data-theme="dark"` on the frame uses the existing dark tokens, so the surface stays dark in both page themes. No new color.
+- `src` or `srcDoc`, `title`, `height` (`sm` | `md` | `lg` | `fill`), `readOnly` (muted **Read only** badge), `state` (`ready` | `loading` | `disconnected`).
+- `bodyTerminal` is unchanged: it only densifies the shell bottom when Body has no Footer. A terminal frame sits flush to the bottom of a footerless card.
+- Pattern: **Components/Card/Card → Pattern — terminal frame**.
+
+### Consumer actions
+
+Replace a hand-rolled iframe in **Card.Body** with `variant="terminal"`. Paste **Components/Card/Card → Pattern — terminal frame** (`docs/patterns/components-card-card--terminal-frame.tsx`). `bodyTerminal` still means footerless density — do not use it as the embed.
+
+## 0.4.16
+
+**DisplayControls can be a theme switch, with a no-flash snippet.**
+
+- **DisplayControls** `controls="theme"` drops the grid button. **G** is not captured. **T** still cycles Auto → Light → Dark.
+- `readDisplayTheme`, `persistDisplayTheme`, `applyDisplayTheme`, `commitDisplayTheme`, and `subscribeDisplayTheme` remember the choice under `wmds-theme` and set or clear `data-theme` on `<html>`. `light` clears the attribute. `dark` sets it. `auto` follows `prefers-color-scheme` and keeps listening until the next call. `useSyncExternalStore(subscribeDisplayTheme, readDisplayTheme, …)` reads the saved choice without a hydration mismatch.
+- `displayThemeNoFlashScript` is the head snippet that reads the same key before paint. Paste it before the stylesheet.
+- Pattern: **Components/DisplayControls → Pattern — theme switch**.
+
+### Consumer actions
+
+Paste `displayThemeNoFlashScript` in `<head>` before the stylesheet (a `<script>` whose text is that string). Render **DisplayControls** with `controls="theme"` and call `commitDisplayTheme` from `onThemeChange`. Paste **Components/DisplayControls → Pattern — theme switch** (`docs/patterns/components-displaycontrols--theme-switch.tsx`).
+
+Existing grid + theme pages keep `controls` omitted. **Pattern — page display controls** is unchanged.
+
+## 0.4.15
+
+**TaskRows: a needs-you table.**
+
+- **TaskRows** `variant="table"` (new) — columns of title, waiting, and metric. Not an accordion. `columns` is `{ id: "title" | "waiting" | "metric", header, align?, width? }`. Defaults are Item, Waiting, and Metric.
+- **TaskRows.Row** (new) — `title`, `href` or `render` (a router link; `render` wins), `status` (`tone`, `label` such as "Open · 2d", `pulsing`), `waiting` (a muted **Badge** pill and a detail line), `metric` (`value` is tabular, plus `detail`).
+- `source` — `ready` (default), `loading` (skeleton, `aria-busy`), `error` (the `note` in the destructive color), `unwired` (the `note` as a muted footer line, no fake metric).
+- `empty` — shown when there are no rows. Defaults to "Nothing waiting".
+- Below `md` the headers are visually hidden and each row is two lines: the title, then the status, the waiting detail, and the metric.
+- Pattern: **Components/TaskRows → Pattern — needs you**.
+
+### Consumer actions
+
+None for existing **TaskRows** lists and capsules.
+
+For a needs-you table, paste **Components/TaskRows → Pattern — needs you** (`docs/patterns/components-taskrows--needs-you-table.tsx`). Pass `source="unwired"` and `note` when a source is not connected. Do not invent a zero.
+
+## 0.4.14
+
+**Chart: a segmented progress ring, a tabular legend, and a SegmentedBar that renders before it is measured.**
+
+- **Chart.SegmentedRing** (new) — radial capacity meter. `value` / `max`, `segments` (default 72), `tone`, `centerValue`, `centerLabel`, `size` (`sm` 96px, `md` 160px, `lg` 192px), `animate` (`initial` sweeps on mount, `none` holds the fill), `label`. The figure is tabular. A fixed viewBox, so the ticks are in the server HTML.
+- Over capacity — a value above `max` fills every tick and shows "Over capacity". The arc does not grow past the ring.
+- `unavailable` — `{ reason, label? }` empties the track and replaces the center with muted "Not connected" (or `label`) and the reason. Do not pass a zero for an unwired source.
+- Reduced motion — no sweep. The server render is the settled fill, so hydration matches.
+- **Chart.Legend** `variant="tabular"` (new) — one row: swatch, label, mono value, percent, delta. `config` entries take optional `value`, `percent`, and `delta` (`{ label, direction?: "up" | "down" | "flat" }`). `up` is success, `down` is destructive, `flat` is muted. The default `series` variant is unchanged.
+- **Chart.SegmentedBar** — draws CSS ticks when the host width is still 0 (server HTML and the first client render). The measured SVG, including `fill="velocity"` and `fill="semantic"`, replaces them once the width is known. `animate="initial"` still springs that SVG.
+- Pattern: **Components/Chart → Pattern — segmented ring**.
+
+### Consumer actions
+
+None for existing **Chart.Legend** rows or **Chart.SegmentedBar** props.
+
+**Chart.SegmentedBar** now shows ticks before hydration. A client island is no longer required for the meter to appear. `animate="initial"` still springs once the bar has a width.
+
+For a radial meter and a source breakdown, paste **Components/Chart → Pattern — segmented ring** (`docs/patterns/components-chart--segmented-ring-pattern.tsx`). Pass `unavailable={{ reason }}` when the source is unwired.
+
+## 0.4.13
+
+**NavList: link rows, a trailing mark, a section action, and an app sidebar.**
+
+- **NavList** item `href` (new) — the row is an anchor, so a server-rendered app navigates without mapping `onSelect` to a router. `render={<Link href="/tasks/ikea" />}` (new) is the router link. Pass one. If both are set, `render` is used.
+- `trailing` (new) — a **Status** dot or a **Badge** `status` pill at the end of the row. Counts stay tabular beside it.
+- Section `action` (new) — an **IconButton** for filter or more, in the section label row.
+- **Button** `layout="nav"` accepts `render`, the same way a pill does. A selected link sets `aria-current="page"`.
+- Pattern: **Components/NavList → Pattern — app sidebar** — brand row, **Search**, sections, a footer slot, and below `lg` a **Sheet** `side="start"` opened from a menu **IconButton** in **PageHeader** `variant="app"`.
+
+### Consumer actions
+
+None for existing button rows.
+
+To navigate from a row: pass `href` or `render`. Paste **Components/NavList → Pattern — app sidebar** (`docs/patterns/components-navlist--app-sidebar.tsx`) for the sidebar and the phone sheet.
+
+## 0.4.12
+
+**Badge: a status pill for run state, cadence, and freshness.**
+
+- **Badge** `status` (new) — `active` | `idle` | `success` | `failed` | `warning`. A pill at cluster height (28px `sm`, 36px `md`) with tabular figures. `active` uses `bg-brand-tint` and `text-brand-outline` (navy `#011272` in light, the lifted navy in dark). The others use the existing muted fills. Not with `count`, `iconOnly`, or `avatar`.
+- `dot` (new) — an 8px mark on a status pill. It pulses when `status` is `active`. Reduced motion holds it still. The mark is Badge's own dot, not the **Status** component.
+- `icon` on a status pill leads cadence ("Every 2 days") and freshness ("Last checked 1d ago").
+- Plain label badges stay on the 20 / 24px shell.
+- Pattern: **Components/Badge → Pattern — status pill**.
+
+### Consumer actions
+
+None for existing badges.
+
+For a routine's state: `<Badge status="active" dot>Active</Badge>`, and `<Badge status="idle" icon={<Calendar />}>Every 2 days</Badge>`. Paste **Components/Badge → Pattern — status pill** (`docs/patterns/components-badge--status-pill.tsx`).
+
+## 0.4.11
+
+**Stat: a hero figure with a visible "vs" line.**
+
+- **Stat** `size="lg"` (new) — the figure is `type-display-3` with tabular numbers. The label is sentence case. `sm` and `md` are unchanged.
+- `context` (new) — a visible secondary line under the figure, tabular, for "vs $14,850" or "of $1M goal". `trend.label` stays a tooltip on the badge.
+- `icon` (new) — a leading Lucide glyph in a brand-tint tile (**ButtonIcon**). The glyph uses `text-brand-outline`, which is navy (`#011272`) in light and the lifted navy in dark.
+- `action` (new) — label-row slot. Pass **Button** `size="sm"` ("View details").
+- `unavailable` (new) — `{ reason, label? }` replaces the figure with muted "Not connected" (or `label`) and the reason. `trend` and `context` stay hidden. Do not fake a zero.
+- `trend.direction` accepts `flat`, the same muted badge as `neutral`.
+- `loading` still sets `aria-busy` and a **Skeleton**. `lg` adds a third bar for the context line.
+- Pattern: **Components/Stat → Pattern — hero stat**.
+
+### Consumer actions
+
+None for existing **Stat** tiles.
+
+For a hero KPI with a visible comparison: `size="lg"`, `context="vs $14,850"`, optional `icon` and `action`. Paste **Components/Stat → Pattern — hero stat** (`docs/patterns/components-stat--hero-stat.tsx`). When the source is unwired, pass `unavailable={{ reason }}` instead of a zero.
+
+## 0.4.10
+
+**CopyField: a read-only value with a Copy key button.** For copying an API key. See **ADR-0045**.
+
+- **CopyField** (new) — a read-only monospace value and a **Button** `role="secondary"` `size="sm"` labeled "Copy key", seated at the trailing end of **PromptBar**'s pill. **Input** is `inline` `mono` (`type-code`) and truncates, so a long key does not run under the button. A click copies `value` and the label switches to "Copied" for `buttonStatusHoldMs` (2s), announced from the button's polite live region, then returns. The button is in the tab order (Enter and Space). Focusing the value selects it. If the Clipboard API is missing or blocked, the field selects the value, tries `execCommand('copy')`, and shows "Press Cmd/Ctrl+C to copy." in a polite status. The value is never logged.
+- **Input** `mono` (new, optional) — the same monospace face, for a read-only key or id. Existing inputs are unchanged.
+- `state` (`"copied"` | `"fallback"`) pins that appearance for a specimen. Omit it in the app.
+- Patterns: **Components/CopyField → Pattern — copy key**, **Pattern — copied**, **Pattern — clipboard blocked**.
+- **On a navy field** — `data-theme="dark"` does not belong on `bg-brand`. Dark surfaces are `#262626`, about 1:1 on `#011272`, so the pill and a secondary button disappear. The label and the clipboard hint inherit the section color instead of `text-fg` / `text-muted`. The pill stays a surface. **Button** `role="inverse-outline"` is the on-brand hairline (`--color-on-brand`, no new color). The filled action stays `role="inverse"`. See **ADR-0046**. Paste **Components/CopyField → Pattern — on a navy field**.
+
+### Consumer actions
+
+None for existing apps on a light surface.
+
+On a brand-navy section: wrap it in `bg-brand text-on-brand`. Do not set `data-theme="dark"` on that section. Paste **Components/CopyField → Pattern — on a navy field** (`docs/patterns/components-copyfield--on-navy.tsx`): `<CopyField label="API key" value={apiKey} />`, **Button** `role="inverse"` for the filled action, `role="inverse-outline"` for the hairline. Do not log the key, and do not pass `state`.
+
+To copy an API key on a light surface: `import { CopyField } from "@thewhatmatters/wmds"` and render `<CopyField label="API key" value={apiKey} />`. Paste **Components/CopyField → Pattern — copy key** (`docs/patterns/components-copyfield--copy-key.tsx`). Do not log the key, and do not pass `state`.
+
 ## 0.4.9
 
 **Fixes from the site's 0.4.8 upgrade: router links in every page pattern, a tighter tile caption, and a checker that no longer skips files.**

package/CONSUMING.md

@@ -316,6 +316,67 @@ Browse [lucide.dev/icons](https://lucide.dev/icons/).
 
 ## Customization
 
+### Design knobs (shape)
+
+A site whose design isn't WMDS's default shape (rectangular buttons instead of pills, squarer cards) changes it with **design knobs**: allow-listed CSS variables that every component reads. Don't restyle components with `className`. A knob reshapes every component inside the element it's set on, and keeps focus rings, hit areas and nested radii consistent.
+
+| Knob | Default | Reshapes |
+|------|---------|----------|
+| `--radius-control` | pill | Button, IconButton, Input, Search, Select, Chip, PillGroup, Badge, SegmentedControl, Tab, the compact SiteNav bar. Multi-line controls (TextArea, NavList rows) use 12px or the knob, whichever is smaller. |
+| `--radius-surface` | `16px` | Card layout shells and occupants, Dropdown menus, Toast, ChatQa, Carousel. Smaller surfaces scale with it: Stat, LogView and Skeleton at ¾ (12px), a padded Card at ½ (8px). |
+
+Avatars, status dots, spinners, radios, switches, progress bars and chart marks stay round.
+
+Set knobs for the whole app on `:root` in `brand.css` (below), or for one page or section with a Tailwind arbitrary property on a plain wrapper:
+
+```tsx
+<main className="grid-page [--radius-control:4px] [--radius-surface:6px]">…</main>
+```
+
+Derived radii (`--radius-control-inner`, `--radius-control-box`, `--radius-surface-md`, `--radius-surface-sm`, `--radius-card-shell`, `--radius-card-body`) follow the knobs; don't set them. See **Foundations → Shape → Design knobs — rectangular controls**.
+
+### Brand kit (type and section colours)
+
+A client's brand on WMDS is a short `brand.css` (imported after `styles.css`, unlayered) that sets **allow-listed** knobs. Each knob is read by every component that needs it; nothing else is overridable, so contrast and layout stay guaranteed.
+
+| Knob | Default | Reads it |
+|------|---------|----------|
+| `--font-family-heading` | Geist | `type-heading-*`, and every display step when `--font-display` is unset |
+| `--font-display` | unset (the heading face) | every `type-display-*` step (`hero`, `xl`, `1`, `2`, `3`) |
+| `--font-display-weight` | each step's own (700 / 600) | display steps: set `400` for a one-weight face, so nothing is faux-bolded |
+| `--font-display-tracking` | each step's own | display steps: `0` for a condensed face |
+| `--font-display-case` | unset | display steps: `uppercase` for a face set in capitals (the accessible name stays the written text) |
+| `--font-serif` | system serif | a slot: point `--font-display` or `--font-family-heading` at `var(--font-serif)` |
+| `--text-display-hero-size` | `clamp(3.5rem, 16vw, 16rem)` | `type-display-hero` (a condensed face carries more vw) |
+| `--color-brand-surface` / `--color-on-brand-surface` | the navy / white | **Band** `tone="inverse"` |
+| `--color-on-brand-surface-muted` | 72% of the ink on the surface | secondary text on `inverse` |
+| `--color-field` / `--color-on-field` | the primary pair | **Band** `tone="field"` |
+| `--color-on-field-muted` | the ink itself | secondary text on `field` |
+
+The font knobs also work on a section wrapper (`[--font-display:…]`); set the colour pairs on `:root` (and `[data-theme="dark"]` if they differ there). Load the face yourself (`next/font` or `@fontsource/*`).
+
+**Display steps:** `type-display-hero` (fluid to 16vw, 0.92 leading) and `type-display-xl` (44px → 136px, 0.9 leading) sit above `type-display-1`; both break long words rather than overflow a phone. **TextSequence** word masks keep 0.08em headroom above and to the sides, so tall caps and outline strokes aren't clipped.
+
+**Contrast:** every on-colour and muted step needs **4.5:1** on its colour. `npx wmds-check` reads the app's CSS and fails a hex pair under that (`brand-contrast`, an error). Pairs it can't resolve (a `var()` or `color-mix`) aren't checked, so check those yourself.
+
+```css
+/* brand.css — the reference client (Foundations → Brand kit → Theme a client) */
+:root {
+  --font-display: "Anton", Impact, sans-serif;
+  --font-display-weight: 400;
+  --font-display-tracking: 0;
+  --font-display-case: uppercase;
+  --text-display-hero-size: clamp(4rem, 17.5vw, 18rem);
+  --color-brand-surface: #120d08;
+  --color-on-brand-surface: #f3e3c3;
+  --color-on-brand-surface-muted: #a89a80;
+  --color-field: #e2522b;
+  --color-on-field: #120d08;
+}
+```
+
+Sections then use **Band** `tone="inverse"` / `"field"`: it re-skins everything inside and bleeds full width on the page's own columns (**Components → Band**).
+
 ### Brand override (`--color-primary`)
 
 The **only** per-app color hook is the primary brand color. The WhatMatters default palette stays in **`src/theme/colors.css`**; an app overrides it by redefining the allowlisted tokens on `:root` (light) and `[data-theme="dark"]` (dark) in a stylesheet imported **after** `@thewhatmatters/wmds/styles.css`.
@@ -359,4 +420,4 @@ Rules:
 - Set both the light and the dark value. Leaving `[data-theme="dark"]` unset falls back to the WhatMatters dark primary, not to your light value.
 - Check contrast for `--color-on-primary` on your primary and for `--color-primary` on `--color-body` in both themes.
 
-**Not overridable per app:** brand navy (`--color-brand` `#011272`, `--color-on-brand`, `--color-brand-outline`, `--color-brand-soft`, `--color-on-brand-hover`), accent (`--color-accent*`, `--color-on-accent`), status (`--color-error*`, `--color-success*`, `--color-warning*`, `--color-info*`), chart series, typography (`--font-*`, `--line-height-*`, `type-*`), and grid (`--grid-*`, `--spacing`). Those roles are the shared WMDS contract — change them in `src/theme/`, rebuild, and bump the package. Do **not** fork component visuals with per-app utility overrides — extend WMDS via new variants/patterns in the design system repo.
+**Not overridable per app** (beyond the Brand kit and Design knobs above): brand navy (`--color-brand` `#011272`, `--color-on-brand`, `--color-brand-outline`, `--color-brand-soft`, `--color-on-brand-hover`), accent (`--color-accent*`, `--color-on-accent`), status (`--color-error*`, `--color-success*`, `--color-warning*`, `--color-info*`), chart series, typography (`--font-*`, `--line-height-*`, `type-*`, except the Brand kit knobs), and grid (`--grid-*`, `--spacing`). Those roles are the shared WMDS contract — change them in `src/theme/`, rebuild, and bump the package. Do **not** fork component visuals with per-app utility overrides — extend WMDS via new variants/patterns in the design system repo.

package/README.md

@@ -48,7 +48,7 @@ npm run validate:composition  # molecules/organisms must compose atoms (CI)
 | Atoms | `Avatar`, `Badge`, `Button`, `Checkbox`, `IconButton`, `Input`, `Kbd`, `Radio`, `RiveHand`, `Skeleton`, `Status`, `Switch`, `TextArea`, `TextLink`, `Tooltip` |
 | Molecules | `Accordion`, `CalEmbed`, `Card`, `ChatQa`, `CheckboxGroup`, `Chip`, `DisplayControls`, `Dropdown`, `Field`, `FloatingActionButton`, `HeroIntro`, `IntakeForm`, `NavList`, `PageHeader`, `PillGroup`, `PromptBar`, `RadioGroup`, `Search`, `Select`, `SelectableCard`, `SegmentedControl`, `Stat`, `StepProgress`, `TaskRows`, `TextSequence` |
 | Organisms | `Carousel`, `Chart`, `Confetti`, `Dialog`, `FooterReveal`, `HeroTileStack`, `IntakeConfirmation`, `IntakeModal`, `MoreMenu`, `Panel`, `ScrollHorizontal`, `Sheet`, `SiteNav`, `Tab`, `Toast` |
-| Planned, not built | `Pagination`, `Table` |
+| Planned, not built | `Pagination` |
 
 The list is `src/package.manifest.ts`. `npm run build` fails when it and `src/index.ts` disagree.
 

package/bin/wmds-check.mjs

@@ -18,6 +18,9 @@
  *                             content, data, handlers, and exports may change
  *   pattern-stale     warn   a pasted pattern's header names an older package version
  *   pattern-removed   error  a pasted pattern's id no longer ships
+ *   brand-contrast    error  a brand-kit pair in the app's CSS under WCAG AA 4.5:1: --color-on-X (and
+ *                             --color-on-X-muted) on --color-X, for primary, brand-surface and field,
+ *                             when both are hex values in the same rule
  *
  * Silence one line with a trailing or preceding comment: `wmds-check-ignore raw-control <reason>`.
  * The checks are line-based heuristics, not a parser: they favor few false negatives, and every
@@ -50,6 +53,7 @@ try {
 
 const skipDirs = new Set(["node_modules", ".next", "dist", "build", "out", ".git", "coverage", "storybook-static"]);
 const files = [];
+const cssFiles = [];
 const walk = (dir) => {
   for (const name of readdirSync(dir)) {
     const file = path.join(dir, name);
@@ -57,6 +61,8 @@ const walk = (dir) => {
       if (!skipDirs.has(name)) walk(file);
     } else if (/\.(tsx|jsx|ts|js|mdx)$/.test(name) && !/\.(test|spec|stories)\./.test(name)) {
       files.push(file);
+    } else if (/\.css$/.test(name)) {
+      cssFiles.push(file);
     }
   }
 };
@@ -259,6 +265,47 @@ for (const file of files) {
   }
 }
 
+// Brand-kit contrast. Innermost rule blocks only, so a pair inside @media is read as its own rule.
+const brandPairs = ["primary", "brand-surface", "field"];
+const channel = (value) => {
+  const c = value / 255;
+  return c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+};
+const luminance = (hex) => {
+  let digits = hex.slice(1);
+  if (digits.length === 3 || digits.length === 4) digits = [...digits].map((d) => d + d).join("");
+  if (digits.length === 8 && digits.slice(6) !== "ff") return null; // translucent: depends on what's behind
+  const [r, g, b] = [0, 2, 4].map((i) => parseInt(digits.slice(i, i + 2), 16));
+  return 0.2126 * channel(r) + 0.7152 * channel(g) + 0.0722 * channel(b);
+};
+const contrast = (a, b) => {
+  const [la, lb] = [luminance(a), luminance(b)];
+  if (la === null || lb === null) return null;
+  return (Math.max(la, lb) + 0.05) / (Math.min(la, lb) + 0.05);
+};
+for (const file of cssFiles) {
+  const source = readFileSync(file, "utf8");
+  const lines = source.split("\n");
+  for (const block of source.matchAll(/\{([^{}]*)\}/g)) {
+    const values = new Map();
+    for (const declaration of block[1].matchAll(/(--color-[\w-]+)\s*:\s*(#[0-9a-fA-F]{3,8})\b/g)) {
+      const index = block.index + 1 + declaration.index;
+      values.set(declaration[1], { hex: declaration[2].toLowerCase(), line: source.slice(0, index).split("\n").length });
+    }
+    for (const name of brandPairs) {
+      const background = values.get(`--color-${name}`);
+      if (!background) continue;
+      for (const ink of [`--color-on-${name}`, `--color-on-${name}-muted`]) {
+        const on = values.get(ink);
+        const ratio = on && contrast(on.hex, background.hex);
+        if (ratio && ratio < 4.5 && !ignored(lines, on.line - 1, "brand-contrast")) {
+          report(file, on.line, "brand-contrast", "error", `${ink} ${on.hex} on --color-${name} ${background.hex} is ${ratio.toFixed(2)}:1 — text needs 4.5:1`);
+        }
+      }
+    }
+  }
+}
+
 const errors = findings.filter((finding) => finding.severity === "error").length;
 const warnings = findings.length - errors;
 

package/dist/colors.css

@@ -9,6 +9,9 @@
  * Brand actions: primary / on-primary (WhatMatters — separate from accent).
  */
 :root {
+  /* Native UI (scrollbars, form controls, autofill) follows the theme. */
+  color-scheme: light;
+
   /* Surface hierarchy — body/muted lightened for softer inset wells (test) */
   --color-background-body: #f8f8f8;
   --color-background-surface: #ffffff;
@@ -102,6 +105,23 @@
    */
   --color-brand-tint: color-mix(in srgb, var(--color-brand) 10%, transparent);
 
+  /*
+   * Brand kit colour roles (apps may set these on :root, like --color-primary; CONSUMING.md → Brand kit).
+   * Read by **Band** `tone` (the `[data-tone]` scopes at the end of this file). Two pairs only, so every
+   * on-colour stays checkable: `npx wmds-check` fails a pair under 4.5:1.
+   * - brand surface: a dark section in the brand's own colour (`tone="inverse"`). Default: the navy.
+   * - field: a saturated section colour (`tone="field"`). Default: the primary.
+   * `*-muted` is the secondary text step on that colour; it must clear 4.5:1 too.
+   */
+  --color-brand-surface: var(--color-brand);
+  --color-on-brand-surface: var(--color-on-brand);
+  --color-field: var(--color-primary);
+  --color-on-field: var(--color-on-primary);
+  /*
+   * The muted steps (`--color-on-brand-surface-muted`, `--color-on-field-muted`) are optional and read
+   * with fallbacks in the tone scopes below, so they follow their pair wherever it's set.
+   */
+
   /* Derived from --color-primary — 62% clears WCAG 3:1 on white and #f8f8f8 */
   --color-focus-ring: color-mix(in srgb, var(--color-primary) 62%, transparent);
 
@@ -155,6 +175,7 @@
 }
 
 [data-theme="dark"] {
+  color-scheme: dark;
   --color-background-body: #1b1b1b;
   --color-background-surface: #262626;
   --color-background-card: #1b1b1b;
@@ -290,3 +311,74 @@
 
   --color-skeleton: color-mix(in srgb, var(--color-text-primary) 8%, var(--color-background-muted));
 }
+
+/**
+ * Band tones — `[data-tone]` remaps the surface, text, border and fill roles to a brand-kit pair,
+ * the way `[data-theme]` swaps the palette, so every component inside re-skins. Set by **Band**.
+ * `inverse` also carries `data-theme="dark"`, so status, chart, shadow and focus roles take their dark
+ * values, and this block (later in the file) overrides the surfaces and text on the same element.
+ * Status colours are not remapped on `field`: keep validation messages off a field band.
+ */
+[data-tone="inverse"] {
+  --tone-bg: var(--color-brand-surface);
+  --tone-fg: var(--color-on-brand-surface);
+  /* Default: 72% of the ink on the surface (on the navy, about #b8bdd8, 8.7:1). */
+  --tone-muted: var(
+    --color-on-brand-surface-muted,
+    color-mix(in srgb, var(--color-on-brand-surface) 72%, var(--color-brand-surface))
+  );
+  /* Cards lift 6% toward the ink; the muted step keeps its contrast on the light side. */
+  --tone-raised: color-mix(in srgb, var(--tone-fg) 6%, var(--tone-bg));
+}
+
+[data-tone="field"] {
+  --tone-bg: var(--color-field);
+  --tone-fg: var(--color-on-field);
+  /* Default: the ink itself, since a lighter step on a mid-tone field would fall under 4.5:1. */
+  --tone-muted: var(--color-on-field-muted, var(--color-on-field));
+  /* A tinted card would pull a mid-tone field under 4.5:1, so cards sit flat on the field. */
+  --tone-raised: var(--tone-bg);
+}
+
+[data-tone="inverse"],
+[data-tone="field"] {
+  --color-background-body: var(--tone-bg);
+  --color-background-surface: var(--tone-raised);
+  --color-background-card: var(--tone-raised);
+  --color-background-popover: var(--tone-raised);
+  --color-background-muted: var(--tone-bg);
+
+  --color-text-primary: var(--tone-fg);
+  --color-text-secondary: var(--tone-muted);
+  --color-text-disabled: color-mix(in srgb, var(--tone-fg) 45%, var(--tone-bg));
+  --color-text-accent: var(--tone-fg);
+
+  --color-accent: var(--tone-fg);
+  --color-accent-muted: color-mix(in srgb, var(--tone-fg) 10%, var(--tone-bg));
+  --color-on-accent: var(--tone-bg);
+
+  --color-neutral: color-mix(in srgb, var(--tone-fg) 10%, transparent);
+  --color-overlay-hover: color-mix(in srgb, var(--tone-fg) 8%, transparent);
+  --color-overlay-pressed: color-mix(in srgb, var(--tone-fg) 14%, transparent);
+  /* stateColors.css derives these on :root; derive them again here so they follow the tone. */
+  --color-ghost-foreground: var(--tone-fg);
+  --color-secondary-hover: var(--color-overlay-hover);
+  --color-secondary-active: var(--color-overlay-pressed);
+  --color-ghost-hover: var(--color-overlay-hover);
+  --color-ghost-active: var(--color-overlay-pressed);
+
+  --color-border: color-mix(in srgb, var(--tone-fg) 16%, transparent);
+  --color-border-emphasized: color-mix(in srgb, var(--tone-fg) 32%, transparent);
+  /* Control edges need 3:1; the muted text step clears 4.5:1. */
+  --color-border-control: var(--tone-muted);
+  --color-fill-selected: color-mix(in srgb, var(--tone-fg) 14%, var(--tone-bg));
+  --color-elevation-edge: color-mix(in srgb, var(--tone-fg) 16%, transparent);
+  --color-elevation-surface: var(--tone-raised);
+
+  --color-skeleton: color-mix(in srgb, var(--tone-fg) 12%, var(--tone-bg));
+  /* The ink itself: a primary-tinted ring can vanish on a saturated field. */
+  --color-focus-ring: var(--tone-fg);
+
+  background-color: var(--color-background-body);
+  color: var(--color-text-primary);
+}