zabi-components 8.0.0 → 9.0.0

package/THEMING.md

@@ -1,186 +1,1042 @@
-# Theming Guide
+# Theming guide
+
+An app gives the whole library its own brand from one generated file of token
+overrides. There is no component CSS to write and nothing to repeat for dark
+mode.
+
+This guide is the token API. The tokens under
+[Tokens an app may set](#tokens-an-app-may-set) and
+[Roles: read them, do not set them](#roles-read-them-do-not-set-them) are
+public: renaming or removing one is a breaking change (see
+[Stability](#stability)).
+
+The same guide, with a brand switcher to try it on real components, is on the
+docs site at [/theming](https://zabi-components.vercel.app/theming).
+
+- [The first thing to know: your colour is not pinned to a step](#the-first-thing-to-know-your-colour-is-not-pinned-to-a-step)
+- [Quick start](#quick-start)
+- [Import order](#import-order)
+- [Tokens an app may set](#tokens-an-app-may-set)
+- [Roles: read them, do not set them](#roles-read-them-do-not-set-them)
+- [Light, dark and auto](#light-dark-and-auto)
+- [Text and controls on a brand or accent block](#text-and-controls-on-a-brand-or-accent-block)
+- [Component-level properties](#component-level-properties)
+- [The generator](#the-generator)
+- [What does not follow an override](#what-does-not-follow-an-override)
+- [Stability](#stability)
+- [Reference: how the theme is built](#reference-how-the-theme-is-built)
+- [For maintainers](#for-maintainers)
+
+## The first thing to know: your colour is not pinned to a step
+
+**Need the exact brand colour on buttons? Use `--pin`.**
+`npx zabi-theme --brand "#0026EA" --pin` makes the primary button `#0026ea`
+itself in light, with a checked label colour. The rest of this section is what
+happens without it, and [`--pin`](#--pin-the-exact-brand-colour-on-buttons)
+has the trade-off.
+
+`zabi-theme` takes one brand colour and builds an 11-step ramp from it. The
+colour supplies the **hue and chroma**. The lightness of each step comes from
+the library's own curve (see [Calibrated colour ramps](#calibrated-colour-ramps)),
+so step 600 is as dark as every built-in 600 and every role keeps the contrast
+it was designed with.
+
+So the exact hex you give may not be in the ramp, and it is usually not the
+colour of the primary button:
+
+| You give | Nearest step | Primary button, light (step 600) | Primary button, dark (step 400) |
+|---|---|---|---|
+| `#0026EA` | 800, `#0024e1` (ΔE 3.5) | `#2b65ff` | `#84acff` |
+| `#C17B00` | 500, exact | `#9b6200` | `#d99f58` |
+
+`#0026EA` is darker than a 600, so it lands near step 800 and the button is the
+lighter `#2b65ff`. The header of the generated file, the command's summary line
+and `closest` from `createTheme()` all name the nearest step.
+
+A very bright colour has no step that bright at its chroma. `#FFE600` lands
+nearest step 300 at ΔE 14.8, and the generator says so:
 
-## 🎨 Single Source of Truth
+```
+zabi-theme: warning: brand #ffe600 is not in the ramp built from it: the nearest step is 300 (#dcc600, ΔE 14.8). The ramp keeps its hue on the library's lightness curve; fills use step 600 in light and 400 in dark.
+```
 
-**All theming is done in one file: `src/app.css`**
+If the brand colour itself has to be the button, use
+[`--pin`](#--pin-the-exact-brand-colour-on-buttons). If it only has to appear
+somewhere (a logo plate, a brand screen), use the step the generator names
+(`var(--zabi-brand-500)` for the amber above), not the hex.
 
-This file contains:
-- All color scales (brand, citron, pine, iris, base)
-- Semantic color tokens (primary, secondary, success, error, etc.)
-- Action colors (for buttons and interactive elements)
-- Dark mode overrides
-- Typography settings
-- Spacing, border radius, and z-index values
+## Quick start
 
-## 📍 Where to Make Changes
+1. Generate the brand file. Commit it; the output has no timestamp, and the
+   same input gives the same bytes.
 
-### Main Theme (Light Mode)
-Edit the `@theme` block in `src/app.css`.
+   ```bash
+   npx zabi-theme --brand "#C17B00" --neutral "#78716c" --out src/lib/brand.generated.css
+   ```
 
-### Dark Mode Theme
-Edit the `.dark` block in `src/app.css`.
+2. Import it after the theme files.
 
-## ⚠️ Important: Don't Edit These Files
+   ```css
+   /* src/lib/theme.css — the app's brand */
+   @import "zabi-components/theme-only";
+   @import "zabi-components/theme-dark-only";
+   @import "./brand.generated.css"; /* --zabi-brand-*, --zabi-accent-*, --zabi-base-* */
 
-### Generated Files (in `dist/` folder)
-These files are **automatically generated** from `src/app.css` by the build script:
-- ❌ `dist/zabi-components.css` - Full compiled CSS (generated)
-- ❌ `dist/zabi-components-theme.css` - Theme with Tailwind import (generated)
-- ❌ `dist/zabi-components-theme-only.css` - Theme only, no Tailwind (generated)
-- ❌ `dist/zabi-components-theme-dark.css` - Dark mode theme (generated)
-- ❌ `dist/zabi-components-theme-dark-only.css` - Dark mode theme only (generated)
-- ❌ `dist/zabi-components-colors.css` - Standalone colors (generated from app.css)
+   :root {
+     --font-family-heading: "Your Display Font", var(--font-family-sans);
+   }
+   ```
 
-**These files are overwritten every time you run `npm run build:css`**
+   ```css
+   /* src/app.css */
+   @import "tailwindcss";
+   @import "./lib/theme.css";
+   ```
 
-### Example Files
-- ❌ `examples/theme-extensions/02-custom-brand-colors.css` - Just an example, not your actual theme
-- ❌ `examples/theme-extensions/03-custom-semantic-colors.css` - Just an example, not your actual theme
+3. Choose how dark mode is selected, on `<html>`.
 
-### Source Files (Edit These)
-- ✅ `src/app.css` - **THIS IS THE ONLY FILE YOU NEED TO EDIT**
-- ✅ Removed deprecated files (`src/styles/colors.css`, `src/styles/base.css`, `src/styles/simple.css`, `src/app-simple.css`)
+   ```html
+   <html lang="en" data-theme="auto">
+   ```
 
-## 📦 What Are the Dist Files For?
+That is the whole rebrand: primary actions, focus rings, links, tints, text,
+borders, the page, cards and the dark surface levels follow, in light and dark.
 
-The `dist/` files are **for consumers** of your library who want to import the theme separately.
+## Import order
+
+| Order | Import | Why here |
+|---|---|---|
+| 1 | `tailwindcss` | The theme files are Tailwind v4 `@theme` blocks. |
+| 2 | `zabi-components/theme-only` | Declares every token, light values, and the raw ramps. |
+| 3 | `zabi-components/theme-dark-only` | Only remaps roles for dark. It declares no ramp, so it does nothing without the light theme. |
+| 4 | your generated file | `:root` overrides. After both theme files, so they win in dark as well. |
+| 5 | your own `:root { … }` | Fonts, radius and anything else from the tables below. |
 
-**Full import matrix, export paths, and examples:** [docs/theme-imports.md](./docs/theme-imports.md)
+Keep the brand file last. `:root`, `.dark` and `[data-theme="dark"]` have the
+same specificity, so between them the later rule wins: a brand file imported
+before the dark theme loses, in dark, every token the dark file restates (a
+role moved with `--set`, `--shadow-color`). The ramps happen to apply from
+either position in a Tailwind build, because Tailwind puts the theme's own
+values in a cascade layer and your `:root` rule is outside it. With
+`zabi-components/colors`, which is plain CSS, an override placed before the
+import does nothing at all.
 
-### For Library Developers (You)
-- **Edit**: `src/app.css` only
-- **Build**: Run `npm run build:css` to regenerate all dist files (or `npm run build:lib` before publish)
-- **After token edits**: run `node scripts/verify-build.js` to confirm outputs (also runs as part of `build:lib`)
-- **Base scale source**: use `tokens/base-scale.js`; run `npm run sync:tokens` (or `npm run build:css`) to render token blocks back into `src/app.css`
+If the app has no Tailwind, `zabi-components/css` replaces steps 1 to 3 (see
+[docs/theme-imports.md](./docs/theme-imports.md)); the brand file still goes
+after it.
 
-### For Library Consumers
+Set the overrides on `:root`, not on an element further down. The roles are
+resolved on the root element, so `--zabi-brand-600` set on a `<section>`
+changes nothing inside it.
 
-Use **package exports** (preferred):
+## Tokens an app may set
 
-| Need | Import |
-|------|--------|
-| Tailwind + full `@theme` (app has no Tailwind yet) | `zabi-components/theme` |
-| Tailwind already in app — merge `@theme` only | `zabi-components/theme-only` |
-| Dark overrides (+ Tailwind import in file) | `zabi-components/theme-dark` |
-| Dark overrides only (Tailwind already loaded) | `zabi-components/theme-dark-only` |
-| CSS variables only, no Tailwind | `zabi-components/colors` |
-| Full compiled CSS (utilities + everything) | `zabi-components/css` |
+Set these on `:root`, after the imports. One declaration covers light and dark
+unless the table says otherwise. All of them were checked in a browser against
+the built theme files.
 
-Examples:
+### Colour
+
+`zabi-theme` writes every token in this table. Write them by hand only if you
+have your own ramps.
+
+| Token | Steps | What follows |
+|---|---|---|
+| `--zabi-brand-50` … `--zabi-brand-950` | 50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950 | Primary actions, focus rings, links, brand tints, `--color-primary*` |
+| `--zabi-accent-50` … `--zabi-accent-950` | the same 11 | `--color-accent` and its roles: `bg-accent`, `text-accent`, `border-accent`. Defaults to the citron ramp. |
+| `--zabi-base-50` … `--zabi-base-950` | 50, 75, 100, 150, 200, 250, 300, 350, 400, 450, 500, 550, 600, 650, 700, 750, 800, 850, 900, 925, 950 | Text, borders, inputs, the page, cards and the four dark surface levels |
+| `--zabi-on-brand` | | Label on a primary fill in light. Default `#ffffff`. |
+| `--zabi-on-brand-dark` | | The same in dark. Default `var(--zabi-on-brand)` (white): the dark primary is the same step as light. Set a dark label here if the dark primary is a pale step. |
+| `--zabi-on-accent` | | Label on a solid accent fill in light. Default `#ffffff`. |
+| `--zabi-on-accent-dark` | | The same in dark. Default `var(--zabi-accent-950)`. |
+
+Each ramp runs light (50) to dark (950). Light mode puts fills on step 600;
+the primary and danger fills stay on step 600 in dark too (the physical
+`--zabi-*` steps, with a white label), so the main action keeps its colour. The
+other roles mirror the ramp in dark (the ring, links and tints are the light
+steps there). `createTheme({ darkPrimary: "mirror" })` restores the 8.1 pale
+dark fills.
+
+A ramp you write by hand should keep the library's lightness per step, or the
+contrast the roles were designed with is gone. Run it through
+`zabi-theme --set` to have it checked (see [`--set`](#--set-and-overrides)).
+
+### Type
+
+| Token | Default | What follows |
+|---|---|---|
+| `--font-family-sans` | the platform UI face: `ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji"` | Body text and every component |
+| `--font-family-heading` | `var(--font-family-sans)` | `h1` to `h6` and the Heading component |
+| `--font-family-display` | `var(--font-family-heading)` | `Heading variant="display"` and `font-display`: a second face, so it is a token and not a CSS rule |
+| `--font-family-mono` | `ui-monospace, "SF Mono", SFMono-Regular, Menlo, Consolas, "Liberation Mono", monospace` | CodeBlock |
+| `--font-weight-regular` | `400` | `font-normal` |
+| `--font-weight-medium` | `500` | `font-medium` |
+| `--font-weight-semibold` | `600` | `font-semibold` |
+| `--font-weight-bold` | `700` | `font-bold` |
+
+The default is the platform's own face (San Francisco on Apple devices, Segoe
+UI on Windows, Roboto on Android), so a default install downloads no font. It
+differs by platform, and text widths differ from 8.1's Nunito Sans. Loading any
+other font files is up to the app. To get the 8.1 face back, load Nunito Sans
+yourself and set
+`--font-family-sans: 'Nunito Sans', ui-sans-serif, system-ui, sans-serif`
+on `:root` after the imports. The heading face is applied in the
+base layer, so a `font-*` utility on a heading still wins.
+
+Tailwind's own font utilities follow these tokens: `font-sans` is
+`--font-family-sans`, `font-mono` is `--font-family-mono`, and `font-heading`
+is `--font-family-heading`, `font-display` is `--font-family-display`. The theme maps Tailwind's `--font-sans` and
+`--font-mono` (and a `--font-heading` and `--font-display` of its own) onto them. Before 8.1
+`font-sans` was Tailwind's system stack, so `class="font-sans"` on a heading
+dropped it out of the brand face. Set the `--font-family-*` tokens, not the
+short names: the short ones follow.
+
+### Shape, depth and stacking
+
+| Token | Default | What follows |
+|---|---|---|
+| `--radius-control` | `0.5rem` | Buttons, inputs, selects, toggles |
+| `--radius-container` | `0.75rem` | Cards, alerts, panels, list items, code blocks |
+| `--radius-overlay` | `1rem` | Modals, sheets, menus, popovers, toasts |
+| `--radius-pill` | `9999px` | Badges, avatars, status dots |
+| `--shadow-color` | `24 24 27` (dark: `0 0 0`) | The colour of `shadow-sm` and `shadow-lg`, as three space-separated RGB channels |
+| `--shadow-opacity` | `0.10` (dark: `0.24`) | The strength of the wide, soft layer of each shadow |
+| `--shadow-opacity-contact` | `0.06` (dark: `0.3`) | The strength of the tight contact layer |
+| `--z-dropdown`, `--z-sticky`, `--z-fixed`, `--z-modal-backdrop`, `--z-modal`, `--z-popover`, `--z-tooltip`, `--z-toast` | 1000 to 1080 | The layer of each floating component, when the app has its own stacking order to fit into. Each has a class of the same name (`z-sticky`, `z-fixed`, `z-modal`, …) that sets `z-index` from it |
+
+The shadow tokens are the only ones here with a separate dark value. A
+`:root` override after the imports replaces both; to keep two values, declare
+the dark one under the dark selectors (see
+[One role in dark only](#one-role-in-dark-only)).
+
+### Motion
+
+| Token | Default | What follows |
+|---|---|---|
+| `--duration-fast`, `--duration-base`, `--duration-moderate`, `--duration-slow` | 100, 150, 200, 300ms | `--duration-base` is Tailwind's default transition duration; use the others as `duration-(--duration-moderate)` |
+| `--ease-standard` | `cubic-bezier(0.2, 0, 0, 1)` | Tailwind's default transition curve, and the `ease-standard` utility |
+| `--ease-out` | `cubic-bezier(0, 0, 0.2, 1)` | The `ease-out` utility (Tailwind's own name and value) |
+| `--ease-spring` | a `linear()` spring, one small overshoot | The `ease-spring` utility; browsers without `linear()` get a cubic-bezier with a similar overshoot |
+
+Under `prefers-reduced-motion: reduce` the durations are `0s` and
+`--ease-spring` is the standard curve. This re-points the tokens with
+`:root:root`, so it also wins over an app's own value: to keep motion for
+reduced-motion users, set the token inside your own
+`@media (prefers-reduced-motion: reduce) { :root:root:root { … } }`. To get
+Tailwind's old curve back, set `--default-transition-timing-function`.
+
+### Not on the list
+
+These tokens exist, and their names are kept, but setting them does not restyle
+the components:
+
+- `--spacing-xs` … `--spacing-2xl` feed the `p-md`, `gap-lg` utilities for your
+  own markup. Components use Tailwind's numeric scale.
+- `--control-height-sm`, `-md`, `-lg` record the 32, 40 and 48px control
+  heights. Components set those heights with `h-8`, `h-10` and `h-12`.
+- `--radius-sm`, `-md`, `-lg`, `-xl` are legacy aliases. No component uses them.
+- `--shadow-sm`, `--shadow-md`, `--shadow-lg`, `--shadow-xl` are built from the
+  two shadow tokens above. Set those instead.
+
+## Roles: read them, do not set them
+
+A role says what a colour is for. Components paint with roles, and your own CSS
+should too: `var(--color-action-primary)` or the `bg-action-primary` class, not
+`var(--zabi-brand-600)`. A role is already the right step in each mode.
+
+| Roles | For |
+|---|---|
+| `--color-action-primary`, `-hover`, `-active`, `-text`, `-subtle`, `-subtle-hover` | Primary buttons and controls. The same set exists for `secondary` and `danger`; `--color-action-disabled`, `-disabled-text`, `-disabled-border` for disabled ones. |
+| `--color-on-brand`, `--color-on-accent` | Text on a primary fill and on a solid accent fill |
+| `--color-accent`, `-hover`, `-active`, `-subtle`, `-border`, `-text` | The second brand colour |
+| `--color-focus-ring`, `--color-focus-ring-offset`, `--color-focus` | The focus ring and the gap around it |
+| `--color-focus-ring-muted` | The neutral ring of ghost and link controls (`.focus-ring--muted`); 3:1 or more on every surface level |
+| `--color-focus-ring-danger` | The ring of a destructive control (`.focus-ring--danger`). It is `--color-error`; a role of its own so that a brand or accent block can re-point it |
+| `--color-control-border` | The edge of a control that has nothing else to be seen by, such as an empty Rating star; 3:1 or more on every surface level |
+| `--color-link`, `--color-link-hover` | Links |
+| `--color-headline`, `--color-body`, `--color-description`, `--color-caption`, `--color-label` | Text |
+| `--color-surface-base`, `-raised`, `-elevated`, `-overlay`, `-inset` | The page, cards, nested cards, floating panels, wells |
+| `--color-surface-hover`, `--color-surface-active`, `--color-surface-overlay-hover` | Hover and pressed fills |
+| `--color-border`, `-weak`, `-medium`, `-strong`, `--color-border-overlay` | Borders and dividers |
+| `--color-input`, `-border`, `-border-hover`, `-hover`, `-active`, `-focus`, `-disabled`, `-placeholder` | Form fields; `-active` is the pressed Select trigger; `--color-input-border` is the field edge, 3:1 or more on the field fill, the page and the card in both themes |
+| `--color-<family>`, `-weak`, `-medium`, `-strong`, `-subtle`, `-border`, `-text` | `success`, `warning`, `error`, `info`, `energetic`, `neutral` (see [Semantic families](#semantic-families)) |
+
+Aliases kept from earlier versions resolve to the same values: `--color-background`,
+`--color-card`, `--color-surface-1` … `-4`, `--color-primary*`,
+`--color-secondary*`, `--color-page`.
+
+**Why not set them.** A role set on `:root` after the imports is one value for
+both modes: it replaces the dark value as well, and nothing checks its
+contrast. If one role has to move, do it through the generator, which checks
+it: see [`--set`](#--set-and-overrides).
+
+**Do not set `--color-brand-*`, `--color-accent-<step>` or `--color-base-*`
+either.** Those are the mirrored steps: `--color-brand-600` is
+`--zabi-brand-600` in light and `--zabi-brand-400` in dark. Set on `:root`
+after the imports, one of them becomes the same colour in both modes and stops
+mirroring. Override the `--zabi-*` ramp instead.
+
+### One role in dark only
+
+Declare it under all three dark selectors, after the imports:
 
 ```css
-@import "zabi-components/theme-only";
-@import "zabi-components/theme-dark-only";
+.dark,
+[data-theme="dark"] {
+  --color-link: var(--zabi-brand-200);
+}
+
+@media (prefers-color-scheme: dark) {
+  [data-theme="auto"] {
+    --color-link: var(--zabi-brand-200);
+  }
+}
 ```
 
-```css
-@import "zabi-components/colors";
+## Light, dark and auto
+
+The mode is chosen on the `<html>` element, by an attribute or a class:
+
+| On `<html>` | Result |
+|---|---|
+| nothing | light, also on a dark system |
+| `data-theme="light"` | light |
+| `data-theme="dark"` | dark |
+| `data-theme="auto"` | follows the system (`prefers-color-scheme`) |
+| `class="dark"` | dark, the same as `data-theme="dark"` |
+
+- **Following the system is opt-in.** A page with no attribute and no class
+  stays light on a dark system, as it always has. `data-theme="auto"` needs no
+  script.
+- **`<html>` only.** A `.dark` or `data-theme` on an element further down is
+  not supported. It re-themes the roles the dark file restates (the card
+  surface, the label on a primary button) and leaves the rest (text, borders,
+  the primary fill) light, so the subtree comes out half dark.
+- `color-scheme` comes with the theme, so what the browser draws itself (date
+  and time pickers, scrollbars, autofill) matches: dark under `.dark`,
+  `data-theme="dark"` and `data-theme="auto"` on a dark system, and light
+  everywhere else, a page with no class and no attribute included. That
+  overrides a `<meta name="color-scheme">` tag, so the page needs neither the
+  tag nor an inline `color-scheme` on `<html>`; `ThemeToggle` writes none and
+  removes a stale `light` or `dark` one. Before 8.1 only the attributes set
+  it.
+- The dark file must be imported together with a light one. It only remaps
+  roles onto ramps the light theme declares.
+- Tailwind's own `dark:` variant follows the system unless you redefine it, and
+  does not read `data-theme`.
+
+### A theme control: system, light, dark
+
+`ThemeToggle` reads the mode from `<html>` and follows whatever else changes
+it.
+
+| | Press | Writes |
+|---|---|---|
+| `<ThemeToggle />` (`modes="two"`) | light ↔ dark | `data-theme` when `<html>` has the attribute, the `dark` class otherwise. It is a switch named "Dark mode" (`labels.darkMode`), with `aria-pressed` for its state |
+| `<ThemeToggle modes="three" />` | system → light → dark → system | always `data-theme` (`auto`, `light` or `dark`); it adds the attribute and removes a leftover `dark` class |
+
+With two modes, a press on a page that is on `auto` sets `light` or `dark`, and
+there is no way back to `auto` from that button. An app whose default is
+`data-theme="auto"` wants three modes.
+
+The three-mode button shows a monitor, a sun or a moon, and its accessible name
+states the mode and what a press does: "Theme: system. Switch to light". The
+words are replaceable:
+
+```svelte
+<ThemeToggle
+  modes="three"
+  labels={{
+    auto: "följ telefonen",
+    light: "ljust",
+    dark: "mörkt",
+    describe: (current, next) => `Tema: ${current}. Byt till ${next}`,
+  }}
+/>
 ```
 
-```css
-@import "zabi-components/css";
+**Remembering the choice.** The choice is kept in `localStorage` under
+`storageKey` (default `"theme"`) and applied again when the button mounts, with
+two modes and with three, on a `data-theme` page and on a class page: the
+two-way button on a `data-theme="auto"` page that finds `"dark"` stored sets
+`data-theme="dark"`.
+`storageKey={null}` keeps nothing. To store it in your own backend, bind the
+mode or listen for it:
+
+```svelte
+<ThemeToggle modes="three" storageKey={null} bind:mode onmodechange={(mode) => saveToProfile(mode)} />
+```
+
+`mode` is `"auto" | "light" | "dark"`. It follows the page, and assigning it
+switches the page.
+
+**No flash on load.** A component mounts after the first paint, so a visitor
+who chose dark would see light first. `themeInitScript(storageKey?)` returns a
+small script that applies the stored mode from `<head>`. It is a plain string
+with no dependencies. In SvelteKit, print it once and paste it into
+`src/app.html`, or inject it from `hooks.server.ts`:
+
+```html
+<!-- src/app.html -->
+<html lang="sv" data-theme="auto">
+  <head>
+    <script>
+      (function(){try{var m=localStorage.getItem("theme");if(m!=="auto"&&m!=="light"&&m!=="dark")return;var r=document.documentElement;if(r.hasAttribute("data-theme")||m==="auto"){r.setAttribute("data-theme",m);r.classList.remove("dark")}else{r.classList.toggle("dark",m==="dark")}}catch(e){}})();
+    </script>
+    %sveltekit.head%
 ```
 
-Canonical recommendation for most apps remains:
+```ts
+// src/hooks.server.ts: the same, generated, so it follows the package.
+// Put %theme-init% in the <head> of src/app.html where the script should go.
+import { themeInitScript } from "zabi-components";
 
-```css
-@import "tailwindcss";
-@import "zabi-components/theme-only";
-@import "zabi-components/theme-dark-only";
+export const handle = ({ event, resolve }) =>
+  resolve(event, {
+    transformPageChunk: ({ html }) => html.replace("%theme-init%", `<script>${themeInitScript()}</script>`),
+  });
 ```
 
-Dark mapping rule reference:
-- Physical ramp tokens are `--zabi-base-50 ... --zabi-base-950`.
-- Semantic dark mapping is generated with `S -> 1000 - S` (for example `50 <-> 950`, `75 <-> 925`, `500` unchanged).
+With nothing stored the script does nothing, and the `data-theme` in your
+markup stands.
 
-## 🎯 Common Customizations
+**Your own control.** A settings screen usually wants three labelled options,
+not a cycling button. Drive the theme with the same helpers and any
+`ThemeToggle` on the page follows:
 
-### Change Brand Colors
+```svelte
+<script lang="ts">
+  import { onMount } from "svelte";
+  import { SegmentedControl, getThemeMode, setThemeMode, type ThemeMode } from "zabi-components";
+
+  let mode = $state<ThemeMode>("auto");
+  onMount(() => (mode = getThemeMode()));
+</script>
+
+<SegmentedControl
+  label="Tema"
+  options={[
+    { value: "auto", label: "Följ telefonen" },
+    { value: "light", label: "Ljust" },
+    { value: "dark", label: "Mörkt" },
+  ]}
+  value={mode}
+  onchange={(value) => {
+    mode = value as ThemeMode;
+    setThemeMode(mode); // or setThemeMode(mode, { storageKey: null }) and save it yourself
+  }}
+/>
+```
 
-```css
-@theme {
-  /* Replace the brand color scale */
-  --color-brand-50: #f0f9ff;
-  --color-brand-100: #e0f2fe;
-  --color-brand-200: #bae6fd;
-  --color-brand-300: #7dd3fc;
-  --color-brand-400: #38bdf8;
-  --color-brand-500: #0ea5e9;
-  --color-brand-600: #0284c7;
-  --color-brand-700: #0369a1;
-  --color-brand-800: #075985;
-  --color-brand-900: #0c4a6e;
-  --color-brand-950: #082f49;
-}
+| Helper | |
+|---|---|
+| `getThemeMode()` | `"auto"`, `"light"` or `"dark"`, from `data-theme`; without the attribute, `"dark"` with the `dark` class and `"light"` without. |
+| `setThemeMode(mode, { storageKey? })` | Writes `data-theme`, removes a leftover `dark` class and inline `color-scheme`, stores the choice (`storageKey: null` stores nothing). |
+| `isThemeDark()` | Whether the page is dark right now; on `auto` that is the system's answer. |
+| `getStoredThemeMode(storageKey?)`, `storeThemeMode(mode, storageKey?)` | The stored choice. |
+| `themeInitScript(storageKey?)` | The `<head>` script above, as a string. |
+
+All of them are safe to call on the server, where they read `"light"` and
+write nothing.
+
+```js
+document.documentElement.dataset.theme = "dark"; // "light" | "auto"
+// or
+document.documentElement.classList.toggle("dark");
+```
+
+## Text and controls on a brand or accent block
+
+A block filled with the brand colour (`bg-action-primary`) or the accent
+(`bg-accent`) is not a surface level: the text roles (`--color-headline`,
+`--color-body`) are chosen for the page and for cards, and on a brand fill
+they are about 2:1 to 3.7:1. Three things make a block work.
+
+**1. Say what the block is.** Add `on-brand` beside `bg-action-primary`, or
+`on-accent` beside `bg-accent`:
+
+```svelte
+<section class="bg-action-primary on-brand rounded-container p-6">
+  <Heading level={2} tone="inherit">Dagens quiz</Heading>
+  <Text tone="inherit">Tio frågor om Sverige.</Text>
+  <Button variant="accent">Spela</Button>
+</section>
+```
+
+The class sets the block's text colour to the fill's label colour
+(`--color-on-brand` or `--color-on-accent`). For everything inside the block
+it re-points the focus rings, and the roles a control writes with when it has
+no fill of its own (see 3).
+
+**2. Give text a tone that belongs on a fill.** `Heading` and `Text` take:
+
+| `tone` | Colour | Use |
+|---|---|---|
+| `inherit` | the block's own text colour | inside `on-brand` / `on-accent`, or any block that sets a colour |
+| `on-brand` | `--color-on-brand` | on `bg-action-primary`, wherever the element is |
+| `on-accent` | `--color-on-accent` | on `bg-accent` |
+
+`Heading` is `tone="headline"` by default and `Text` `tone="body"`. Inside a
+block both roles are the block's label colour, so the defaults are legible
+there too; `inherit` says it outright, and is what works on a block of a
+colour of your own.
+
+**3. Controls on the block.** A control with no fill of its own writes with
+the page's roles: a Checkbox's label is `--color-label`, an outline Button's
+`--color-headline` with a `--color-border` edge, help text
+`--color-description`. On a brand fill those were 1.5:1 to 3.7:1. Inside
+`on-brand` and `on-accent` they are re-pointed at the block's label colour:
+
+- the text roles: `--color-headline`, `--color-body`, `--color-label`,
+  `--color-description`, `--color-caption`, `--color-link`,
+  `--color-link-hover`
+- the edges: `--color-border`, `--color-border-medium`,
+  `--color-border-strong`, `--color-control-border`
+- the rings: `--color-focus-ring`, `--color-focus-ring-muted`,
+  `--color-focus-ring-danger`, `--color-nav-menu-focus`, with the gap
+  (`--color-focus-ring-offset`) in the block's own colour
+
+So every one of them measures what the label colour measures against the
+fill, which the theme holds to 4.5:1 (`scripts/check-contrast.js` fails when a
+block stops re-pointing one, or points it at something that does not read):
+
+| Inside | Default theme, light | Default theme, dark | `#0026EA` pinned + `#FDD715` pinned accent, light | The same, dark |
+|---|---|---|---|---|
+| `on-brand` | 4.86 | 7.21 | 8.52 | 7.07 |
+| `on-accent` | 5.02 | 7.11 | 11.66 | 11.66 |
+
+That is the label of a Checkbox, Radio, Toggle, Input, Select, Textarea and
+Rating, a field's help text, `Text` and `Heading` in their default tones, a
+plain link, the label of an `outline`, `ghost` and `link` Button and
+IconButton, the border of an `outline` one, and the focus ring of all of
+them, the danger ring included. They were, on a brand block in the default
+theme: labels 2.15 (light) and 1.52 (dark), `outline` and `ghost` 3.65 and
+2.05, `link` 1.39 and 1.34, the danger ring 1.06 and 1.04.
+
+**A fill you choose.** `on-fill` is the same scope for a colour the library
+does not know: `<div class="on-fill" style="background: #123; --zabi-on-fill: #fff">`.
+Everything above applies with `--zabi-on-fill` as the label colour (without it
+the label is `currentColor`, and the ring's gap is transparent, so the block
+shows through). A surface inside (`bg-card`, `bg-card-tint`, `bg-chip`, `on-surface`
+and the rest of the list) gets the theme's roles back. The library cannot hold
+a colour the app picks at run time: the 4.5:1 of the label on your fill (3:1 for
+edges and rings) is yours to check. A primary Button, a solid Badge and a
+Rating keep their own fills and labels inside any of the three blocks; only the
+text roles, the edges and the rings follow the block.
+
+The Button variants, on a brand block (`bg-action-primary`). "Label" is
+against the button's own fill, or against the block where the button has
+none; "fill" is the button's fill against the block (3:1 for the button to be
+seen as a shape):
+
+| `Button variant` | Default theme, light | Default theme, dark | `#0026EA` + `#FDD715` pinned, light | The same, dark |
+|---|---|---|---|---|
+| `outline`, `ghost`, `link` | label 4.86 | label 7.21 | label 8.52 | label 7.07 |
+| `secondary` | label 5.65 | label 7.75 | label 9.58 | label 7.63 |
+| `accent` | label 5.02, fill 1.03 | label 7.11, fill 1.03 | label 11.66, fill 6.05 | label 11.66, fill 1.60 |
+| `danger` | label 4.78, fill 1.06 | label 7.10, fill 1.04 | label 4.78, fill 1.65 | label 7.10, fill 1.03 |
+| `primary` | the block's own colour: invisible | invisible | invisible | invisible |
+
+On an accent block (`bg-accent`):
+
+| `Button variant` | Default theme, light | Default theme, dark | `#0026EA` + `#FDD715` pinned, light | The same, dark |
+|---|---|---|---|---|
+| `outline`, `ghost`, `link` | label 5.02 | label 7.11 | label 11.66 | label 11.66 |
+| `secondary` | label 5.86 | label 7.73 | label 9.43 | label 11.92 |
+| `primary` | label 4.86, fill 1.03 | label 7.21, fill 1.03 | label 8.52, fill 6.05 | label 7.07, fill 1.60 |
+| `danger` | label 4.78, fill 1.03 | label 7.10, fill 1.01 | label 4.78, fill 3.66 | label 7.10, fill 1.65 |
+| `accent` | invisible | invisible | invisible | invisible |
+
+So the quiet variants (`outline`, `ghost`, `link`, `secondary`) are legible on
+either block in any theme. A solid one keeps its own label; whether it also
+stands out as a shape depends on how far apart the two brand colours are: an
+ultramarine and a yellow are 6:1 apart in light, the library's own blue and
+citron 1.03:1. Where they are close, use a quiet variant for a second action,
+or put the action on a card.
+
+**What a block cannot make legible: put it on a card.** Some parts of a
+control are not written with a role that a block can re-point. They are drawn
+with a neutral step, with the primary fill itself, or with a status colour.
+Against the block:
+
+| Part | On a brand block (default light, dark; pinned light, dark) | On an accent block |
+|---|---|---|
+| Checkbox or Radio box, and the Toggle track, empty | 1.89, 3.44; 3.32, 3.43 | 1.96, 3.35; 1.82, 5.49 |
+| the same, ticked or on, and a filled Rating star (the primary fill) | 1.00 in all four | 1.03, 1.03; 6.05, 1.60 |
+| the text of an error or other status message | 1.47, 1.31; 1.19, 1.31 | 1.42, 1.34; 5.07, 1.22 |
+| the fill of a field (Input, Select, Textarea) | 4.86, 7.31; 8.52, 7.30 | 5.02, 7.12; 1.41, 11.67 |
+
+The label of such a control is legible on the block and the control itself
+may not be: a ticked Checkbox on a brand block is a tick with no box around
+it. Put Checkbox, Radio, Toggle, Calendar and anything that shows a validation
+message on a card inside the block. A field is a surface of its own and
+carries its text; it only disappears on an accent as light as the field (the
+pinned yellow, 1.41). Rating has properties for its colours
+(`--zabi-rating-on`, `--zabi-rating-off`, below).
+
+**A surface inside a block is a surface again.** Anything inside the block
+that paints a surface (a `Card`, a field, an `Alert`, a `list-group`: the
+`bg-card`, `bg-surface-*`, `bg-input` and `bg-*-subtle` fills) gets the
+theme's own roles back, and its own text colour, so a card needs nothing: a
+Checkbox on it has the page's label colour and the theme's focus ring. For a
+background the library cannot recognise (an inline style, a class of your
+own), add `on-surface`:
+
+```svelte
+<section class="bg-action-primary on-brand p-6">
+  <Button variant="outline">Hoppa över</Button>
+  <div class="on-surface rounded-container p-4" style="background: #fffbeb">
+    <Checkbox label="Kom ihåg mig" />
+  </div>
+</section>
 ```
 
-### Change Primary Button Color
+A block inside that surface is a block again.
+
+**The focus ring.** The default ring (`--color-focus-ring`) is the primary
+fill, so on a brand block it measures 1.00:1 against the background and only
+its 2px gap shows; the danger ring is the error colour, 1.0:1 to 1.7:1 there.
+Inside a block every ring is the block's label colour and the gap is the
+block's colour: the numbers of the first table above.
 
-The primary button uses `--color-action-primary`, which defaults to `brand-600`
-(4.86:1 against a white label). To change it:
+To do the same on a block of another colour, set the colour and the ring on
+it yourself, and give text `tone="inherit"`:
 
 ```css
-@theme {
-  /* Use a different brand shade */
-  --color-action-primary: theme(colors.brand.600);
-  
-  /* Or use a completely custom color */
-  --color-action-primary: #your-color-here;
+.my-block {
+  color: #ffffff;
+  --color-focus-ring: #ffffff;
+  --color-focus-ring-offset: #7a1f5c; /* the block's own colour */
 }
 ```
 
-### Brand Scale Usage
+The roles of 3 are not re-pointed there: a quiet Button or a Checkbox on such
+a block keeps the page's colours. Re-point the ones you need the same way
+(`--color-label: #ffffff`, `--color-headline: #ffffff`, `--color-border:
+#ffffff`), and then mark any card inside it `on-surface` and set them back
+there.
+
+## Component-level properties
+
+A few components read custom properties of their own, for colours that are not
+roles of the theme. They are not tokens: the theme does not declare them, and
+they do not appear in the generated files. Set them on the component, or on
+anything around it; they inherit.
+
+| Component | Property | What it colours | Default |
+|---|---|---|---|
+| `Rating` | `--zabi-rating-on` | a filled star | `--color-action-primary`; `--color-accent` with `tone="accent"` |
+| `Rating` | `--zabi-rating-on-hover`, `--zabi-rating-on-active` | the same under the pointer and while pressed | `--zabi-rating-on` if you set it, else the tone's hover and pressed roles |
+| `Rating` | `--zabi-rating-on-edge` | the outline of a filled star | the fill; `--color-accent-text` with `tone="accent"` |
+| `Rating` | `--zabi-rating-off` | the outline of an empty star | `--color-control-border` |
+| `Rating` | `--zabi-rating-off-fill` | an empty star with `empty="soft"` (below 3:1 on the page; pair it with a visible label and value) | `--color-control-track` |
+| `SpeechBubble` | `--zabi-bubble-fill` | the bubble and its tail; wins over `tone` | the headline colour; the page colour with `tone="paper"` |
+| `SpeechBubble` | `--zabi-bubble-text` | the quoted text; wins over `tone` (4.5:1 on your fill is yours to check) | the page colour; the headline colour with `tone="paper"` |
+| `SpeechBubble` | `--zabi-bubble-radius` | not a colour: the bubble's corners, any `border-radius` value, the eight-value form included | `1.5rem` |
+| `SpeechBubble` | `--zabi-bubble-tilt` | not a colour: turns the fill and the tail, never the text | `0deg` |
+| `LineChart`, `BarChart`, `PieChart`, `Sparkline` | `--zabi-chart-1` | the first series: a line, the bars, the first slice (3:1 on the surface under it is yours to check) | `--color-action-primary`: the blue a `Progress` fills with |
+| `LineChart`, `PieChart` | `--zabi-chart-2` | the second series | `--color-accent-500`: the accent at its middle step |
+| `LineChart`, `PieChart` | `--zabi-chart-3` | the third series | `--color-brand-900`: the brand at its deepest step (its palest in dark) |
+| `LineChart`, `PieChart` | `--zabi-chart-4` | the fourth series | `--color-accent-700`: the accent, deep (pale in dark) |
+| `LineChart`, `PieChart` | `--zabi-chart-5` | the fifth series | `--color-base-500`: the neutral grey |
+| `LineChart`, `PieChart` | `--zabi-chart-6` | the sixth series; a seventh starts again at the first | plum: `--color-brand-700` and `--color-error-700` mixed half and half in OKLCH, the one colour from outside the three ramps |
+| `LineChart` | `--zabi-chart-surface` | paints the ring around each marker. Without it the ring is cut out of the lines, so it shows whatever the chart stands on (a card, a tint, glass) and there is nothing to set | none: the ring is see-through |
+
+The series colours are the library's own: the brand, the accent and the neutral ramp, each at a solid step and a deep one, so a chart sits beside a `Progress` or a `Badge` without a colour of its own. They are categories, not states: none is `--color-success`, `--color-warning`, `--color-error` or `--color-info`. Because they are steps of your ramps they follow light and dark and a brand of your own; they were measured on the default theme only (each 3:1 or more on a card in both modes; any two apart for a reader who does not see red and green). When a series means a state (right, wrong, skipped) give it `color: 'success'`, `'error'`, `'neutral'`; a series without a `color` in the same chart then steps past the series colour nearest to a named one.
+
+The rest of a chart is borrowed too, so it follows what you set for those: a `BarChart` with a `yMax` stands each bar in a track drawn with `--color-progress-track` and `--color-progress-track-border`; grid lines are `--color-border`; the rows of the `PieChart` key and of the narrow `LineChart` key are parted by the divider of a `List`; `showTable` shows a `Table`.
+
+The slices of a `PieChart` and the bars of a `BarChart` are drawn as glass. An SVG shape takes no backdrop blur, so each keeps its series colour, opaque, and the depth is a soft gradient and a barely-there edge: the veil of a solid control (`--color-control-gradient-accent-start` to `--color-control-gradient-accent-end`: darken-only in light, light at the top in dark), one pixel of light on the top of the rim (the lightest neutral at 30%, the same in both modes), a blurred sheen under it at about a third of that, and a soft shadow under the drawing (the two shadows of `--shadow-md`; the contact shadow only under a bar). Retune the veil and shadow tokens and the charts follow. They are the flat fills wherever the materials are opaque: reduced transparency, more contrast, forced colours, and inside `data-materials="opaque"`, which is also how an app turns the look off for one chart or for all of them. On the default theme every fill stays 3:1 or more on a card under the veil in both modes. The key marks, line markers and the `Sparkline` dot stay flat: at 6 to 10px there is no room for it. The gaps of a full pie narrow to a point at the centre, so every slice runs to the middle; in a ring they have parallel sides.
+
+The glass under a chart, as distinct from the marks, is the library's thick material and nothing of its own, so the material tokens and every fallback apply to it: reduced transparency, more contrast, forced colours, a browser without `backdrop-filter` and `data-materials="opaque"` all give the opaque surface. The pane of values that comes up over a `LineChart` when it is pointed at is always that material, as a `Tooltip` is. The `glass` prop on `LineChart`, `BarChart` and `PieChart` stands the whole chart on a panel of it; that is for a chart over the canvas wash, a tint card or a picture. On a plain card it shows only an edge and a shadow. Measured on the default theme, every series colour is 3:1 or more on the glass over the wash and over a tint card in both modes; over a solid brand or accent fill the second series falls to 2.9:1 in light and the first and fifth to 2.3:1 and 1.8:1 in dark, so put the chart on a `Card` there instead.
 
-The brand scale is used throughout the system:
+```svelte
+<Rating label="Betyg" tone="accent" bind:value />
 
-- **brand-50 to brand-100**: Subtle backgrounds, hover states
-- **brand-300 to brand-400**: Light accents, disabled states
-- **brand-500**: Focus rings, medium emphasis
-- **brand-600**: **Primary buttons** (`action-primary`)
-- **brand-700**: Primary hover, links
-- **brand-800**: Primary active, link hover
-- **brand-900 / 950**: Darkest brand shades
+<!-- or a colour of your own, here for every rating in a block -->
+<section class="bg-action-primary on-brand" style="--zabi-rating-on: var(--color-accent); --zabi-rating-off: var(--color-on-brand)">
+  <Rating label="Betyg" bind:value />
+</section>
+```
 
-Hover and active always move *toward* the dark end in light mode. The `.dark`
-mirror flips that automatically, so "more pressed" means "more contrast against
-the page" in both themes. Never point `-active` at a step on the far side of the
-ramp — that is how the pressed primary label ended up at 1.66:1.
+A star is a control whose shape has to be seen (3:1 against what it sits on).
+`tone="accent"` fills the star with the accent and outlines it in the accent's
+text step, because an accent can be a colour no fill can show on white:
+
+| Filled star, `tone="accent"` | page | card | inset |
+|---|---|---|---|
+| Default accent, light: fill / outline | 4.25 / 5.93 | 5.02 / 7.00 | 4.56 / 6.37 |
+| Default accent, dark: fill / outline | 7.68 / 10.34 | 6.54 / 8.81 | 7.12 / 9.60 |
+| `#FDD715` pinned, light: fill / outline | 1.19 / 5.94 | 1.41 / 7.01 | 1.28 / 6.38 |
+| `#FDD715` pinned, dark: fill / outline | 12.58 / 10.27 | 10.71 / 8.75 | 11.67 / 9.53 |
 
-### Dark Mode
+A yellow star cannot reach 3:1 on a white card: its fill is 1.41:1 there. The
+outline keeps the star's shape at 7:1, so the stars are always there to see.
+What tells a filled star from an empty one on white is then the yellow inside
+the outline and the outline's own colour, which is less than 3:1; the rating
+also has its value as text (`showValue`, on by default when `readonly`) and in
+its accessible name. On a dark or a brand block the yellow fill itself is
+6:1 or more. If you set `--zabi-rating-on` to a light colour yourself, set
+`--zabi-rating-on-edge` too.
 
-Dark mode automatically inverts the brand scale:
-- `brand-50` becomes `brand-950` (darkest)
-- `brand-950` becomes `brand-50` (lightest)
+## The generator
 
-This happens automatically in the `.dark` block, so you typically don't need to override action colors in dark mode.
+Exact brand colour on buttons: use `--pin`.
 
-## 🌙 Dark Mode Action Colors
+```bash
+npx zabi-theme --brand "#0026EA" --pin --out src/lib/brand.generated.css
+```
 
-Dark mode action colors are handled in `src/app.css` in the `.dark` block (lines 393-404):
+Without it, every fill is a step of a ramp built from the colour:
 
-### Primary Actions
-- **No explicit dark mode override needed** - Brand colors are automatically inverted
-- `brand-800` (light mode) → `brand-200` (dark mode) automatically
+```bash
+npx zabi-theme --brand "#0026EA" --out src/lib/brand.generated.css
+npx zabi-theme --brand "#C17B00" --accent "#ff3366" --neutral "#78716c" --out src/lib/brand.generated.css
+```
 
-### Secondary Actions  
-- **No explicit dark mode override needed** - Base colors are automatically inverted
-- `base-600` (light mode) → `base-400` (dark mode) automatically
+| Option | |
+|---|---|
+| `--brand <hex>` | Required. Builds `--zabi-brand-50 … 950`. |
+| `--pin` | The primary action is the exact brand colour in light. See [`--pin`](#--pin-the-exact-brand-colour-on-buttons). |
+| `--accent <hex>` | Builds `--zabi-accent-50 … 950`. Omitted: the library's citron. |
+| `--pin-accent` | The same for the solid accent fill. Needs `--accent`. |
+| `--neutral <hex>` | Tints the 21-step `--zabi-base-50 … 950`. Omitted: the library's greys. Takes the hue only, at no more than 0.03 chroma. |
+| `--neutral-chroma <n>` | OKLCH chroma at the neutral ramp's peak, 0 to 0.1; needs `--neutral`. Lifts the 0.03 cap (0.04 to 0.06 gives a clearly tinted neutral such as a blue-slate), and makes the ink roles follow the neutral ramp. See [`--neutral-chroma`](#neutral-chroma-a-strongly-tinted-neutral). |
+| `--out <file>` | Where to write. Omitted: stdout. |
+| `--strict` | Exit 1 when a role pair is below WCAG AA. |
+| `--set <token>=<value>` | Also write this declaration, in light and dark; repeatable. |
+| `--set-light <token>=<value>` | The same for light only: dark keeps the library's value. Repeatable. See [`--set` and overrides](#--set-and-overrides). |
+| `--set-dark <token>=<value>` | The same for dark only. Repeatable. |
+| `--help` | Usage. |
+
+Colours are hex, `#rgb` or `#rrggbb`. Warnings and the one-line summary go to
+stderr. Exit codes: 0 done, 1 `--strict` with a failed pair, 2 bad usage
+(missing `--brand`, not a hex colour).
+
+### `--neutral-chroma`: a strongly tinted neutral
+
+`--neutral` gives the neutral ramp its hue and never more chroma than 0.03, so
+it stays a tinted grey. For a UI that reads as one hue with the brand, say a
+blue-slate under an ultramarine brand, give the chroma yourself:
 
-### Danger Actions
-- **No re-pointing needed.** Danger resolves through `--color-error-*`, which
-  mirrors like every other ramp, so dark danger is the same step of the same
-  ramp as light danger. The `.dark` block restates the aliases only so that
-  `zabi-components/theme-dark-only` remains a complete standalone import
-  (`validate-theme.js` enforces that).
+```bash
+npx zabi-theme --brand "#0026EA" --neutral "#607296" --neutral-chroma 0.05 --out src/lib/brand.generated.css
+```
+
+The ramp has the same 21 lightness steps and the same shape; only its peak
+chroma is the number you gave (`0` to `0.1`). The contrast check runs on the
+result as always. Without `--neutral-chroma` the output is exactly what it was.
+
+With it, the translucent ink roles stop being grey and follow the ramp, as
+`color-mix()` over `--zabi-base-900` (light) or `--zabi-base-50` (dark) at the
+alpha the library gives each role:
+`--color-action-secondary`, `-hover`, `-active`, `--color-surface-hover`,
+`--color-surface-active` and, in light, `--color-border-overlay`.
+`--shadow-color` becomes the RGB triplet of step 900 in light and stays `0 0 0`
+in dark. The modal scrim `--color-overlay` stays black. Because a role on
+`:root` is one value in both modes, the file restates the dark values under the
+dark selectors, as `--pin` does. A role you set with `--set`, `--set-light` or
+`--set-dark` keeps your value.
+The contrast check does not evaluate these translucent roles, with or without
+the option; the library's own guard (`npm run check:design`) does for the
+defaults.
+
+### `--pin`: the exact brand colour on buttons
+
+Unpinned, the primary button is step 600 of the ramp: for `#0026EA` that is
+`#2b65ff`, visibly lighter than the brand. With `--pin` the ramp is the same
+ramp, and the roles that *are* the brand colour are written as role overrides:
+
+| | Unpinned | `--pin` |
+|---|---|---|
+| Primary button, light | step 600, `#2b65ff` | the colour itself, `#0026ea` |
+| Its label | white, 4.76:1 | white, 8.52:1 |
+| Hover, pressed | steps 700, 800 | the same hue, darker by the same distances: `#0100c4`, `#000e78` |
+| Focus ring, links, checked boxes | steps 600 and 700 | the colour itself, because every guarded pair still passes |
+| Tints and borders (`-subtle`, `-border`), `--color-brand-*` | on the ramp | on the ramp, unchanged |
+| Dark | step 400, `#84acff` | step 400, `#84acff`: not pinned |
+
+What it decides, and how:
+
+- **The fill is never moved.** If the colour fails a pair, the pair is a
+  warning (and `--strict` exits 1). `#C17B00` pinned is 2.92:1 against the
+  light page, where a button needs 3:1, and the generator says so.
+- **The label** is white or the ramp's 950 step, whichever reaches 4.5:1 on the
+  fill and both its states. An amber gets the dark label, and its hover and
+  pressed states go lighter, since darker states would lose the label.
+- **Focus ring and links follow only if they pass.** The ring needs 3:1 on
+  every surface and a link 4.5:1 on the page and on a card. A yellow passes
+  neither, so both stay on the ramp. The header lists which followed.
+- **Dark is not pinned unless the colour passes there.** `#0026EA` is 2.08:1
+  against a dark page and 1.77:1 against a dark card, where a fill needs 3:1:
+  no label makes that a button. Dark keeps
+  step 600 (the mirrored step 400 with `darkPrimary: "mirror"`), exactly as
+  without `--pin`, and the header says so. A
+  colour that does pass in dark (the amber, the yellow) is pinned there too,
+  with lighter states.
+
+The trade-off: a ramp step is guaranteed to pass, in both modes, for any
+colour. A pinned colour is exact and passes only if the colour can. Unpinned,
+a brand rarely warns; pinned, read the warnings.
+
+The file then has three rules, not one: `:root` with the ramp and the light
+roles, and the dark values of those roles under `.dark, [data-theme="dark"]`
+and under `[data-theme="auto"]` in the dark media query. A role set on `:root`
+alone would be one value in both modes. To force a dark value the generator
+declined, write the role in your own dark rule after the file (see
+[One role in dark only](#one-role-in-dark-only)).
+
+A role you pass with `--set` (or `--set-light`, `--set-dark`) is left to you:
+`--pin` does not write it in either mode. With `--set` it is your value in both
+modes; with `--set-light` or `--set-dark`, only in that mode.
+
+### What it does
+
+- **Brand and accent ramps** on the library's lightness curve, from the hue and
+  chroma of the colour you give. See
+  [the first section](#the-first-thing-to-know-your-colour-is-not-pinned-to-a-step).
+- **Neutral ramp.** It keeps the base scale's own 21 lightness steps and takes
+  only the hue, at low chroma (0.03 at most). A saturated colour gives a tinted
+  grey, not a coloured page. `neutralChroma` lifts that cap.
+  The chroma tapers towards the light end of the ramp, so the lightest steps
+  are paler than the mid steps. To match an owner's page colour exactly, do not
+  raise `neutralChroma` (that tints the mid steps and muted text too); set the
+  page per mode instead: `overrides: { light: { '--color-surface-base': '#e3edff' } }`.
+- **Links follow an overridden primary.** If `overrides` set `--color-action-primary` (and not `--color-link`), links take that colour in each mode the override applies to, and `--color-link-hover` the primary hover if you set one, as long as no guarded pair fails that did not before; otherwise the ramp's link stays in that mode. An explicit `--color-link` always wins. To put the library's link back: `overrides: { '--color-link': 'var(--color-brand-700)', '--color-link-hover': 'var(--color-brand-800)' }`.
+- **"On" colours.** It sets `--zabi-on-brand` and `--zabi-on-brand-dark` (and
+  the accent pair when `--accent` is given) to white or the ramp's 950 step,
+  whichever reaches 4.5:1 on the fill, its hover and its active step. In dark
+  the brand label tries white first (the dark primary is step 600), and falls
+  back to the 950 step when an app has moved the dark primary to a pale step.
+- **`darkPrimary`.** `"brand"` (default) writes nothing: the library's dark
+  primary and danger are step 600 with a white label. `"mirror"` writes the 8.1
+  fills under the dark selectors: primary and danger on the mirrored 600, 700
+  and 800 (pale in dark), danger's label as it was, the label chosen by the
+  contrast check, and the control veil at 22% / 6%. An override of those roles
+  in `dark` or `both` always wins. CLI: `--dark-primary brand|mirror`. A
+  `--set --color-action-primary=...` that applies to both modes keeps its dark
+  value; move it under `--set-light` to take the dark default.
+- **Contrast check.** Every pair the library holds itself to is resolved in
+  light and dark with the new ramps in place: 4.5:1 for text and
+  3:1 for focus rings and UI parts.
+
+### What it does not do
+
+- It does not put your exact hex in the ramp. `--pin` puts it on the primary
+  action; the ramp steps stay on the curve.
+- It does not write fonts, radius or shadow unless you pass them with `--set`.
+- It does not check the hover, pressed and secondary-button alpha tints. They
+  are not part of the contrast list.
+- It does not check that a `--set` token exists. A misspelt name is written as
+  given.
+- It does not load or check fonts.
+
+### Warnings
+
+A plain brand passes, because the ramps share the library's curve. Warnings
+come from two places.
+
+An input that will not give the ramp its author probably expects:
+
+```
+zabi-theme: warning: brand #808080 has almost no colour in it, so the ramp is a grey scale. Give a more saturated colour for a visible hue.
+```
+
+A role pair below AA, which only happens when `--set` moves a role or `--pin`
+pins a colour that cannot carry it:
+
+```
+zabi-theme: warning: light · on-brand label on primary: #2f1b00 on #9b6200 is 3.24:1, needs 4.5:1 (--color-on-brand on --color-action-primary)
+```
+
+### `--strict` in CI
+
+Without `--strict` a failed pair is a warning and the file is still written.
+With it the command exits 1. Because the output is deterministic, one line
+checks both that the brand passes and that the committed file is current:
+
+```bash
+npx zabi-theme --brand "#C17B00" --neutral "#78716c" --strict --out src/lib/brand.generated.css && git diff --exit-code src/lib/brand.generated.css
+```
 
-### In Generated Files
+### `--set` and overrides
 
-- **`dist/zabi-components.css`**: Has dark mode at line 2178, danger actions at lines 2264-2269
-- **`dist/zabi-components-theme-dark-only.css`**: Has dark mode action colors at lines 119-130 (only danger has explicit overrides)
-- **`dist/zabi-components-theme-only.css`**: Only has light mode (@theme block), no dark mode
-- **`dist/zabi-components-theme.css`**: Only has light mode (@theme block), no dark mode
+`--set` writes one more declaration into the file. It applies in light and in
+dark, and it takes part in the contrast check and in the choice of the "on"
+colours. `--set-light` and `--set-dark` do the same for one mode.
+
+```bash
+npx zabi-theme --brand "#C17B00" --set "--color-link=var(--color-brand-800)" --out src/lib/brand.generated.css
+npx zabi-theme --brand "#C17B00" --set '--font-family-heading="Fraunces", var(--font-family-sans)' --out src/lib/brand.generated.css
+```
+
+Point a role at a **semantic** step, `var(--color-brand-800)`, not at a
+physical one. The semantic step mirrors in dark; `var(--zabi-brand-800)` is
+the same dark brown in both modes, and as a link colour it fails in dark:
+
+```
+zabi-theme: warning: dark · link on page: #613b00 on #18181b is 1.8:1, needs 4.5:1 (--color-link on --color-surface-base)
+```
+
+#### One mode only: `--set-light` and `--set-dark`
+
+Dark is derived from light, so `--set "--color-surface-raised=#f8faff"` also
+paints the dark cards `#f8faff`. To tint the light card and keep the dark mix
+the library gives it:
+
+```bash
+npx zabi-theme --brand "#0026EA" \
+  --set-light "--color-surface-raised=#f8faff" --set-light "--color-surface-overlay=#f8faff" \
+  --out src/lib/brand.generated.css
+```
+
+The value goes on `:root`. A `:root` value would win in dark too, so the file
+restates, under both dark selectors, the library's own dark value of every token
+you set in light only (the ramp the file writes, for a ramp step; the light
+default if the library has no dark value for it). `--set-dark` writes only under
+the dark selectors. A token given to `--set` and to a mode flag takes the mode's
+value in that mode. The contrast check evaluates each mode with that mode's own
+values, and a warning names the mode as before.
+
+A token the library has no dark value for, or one you made up
+(`--set-light "--my-gap=4px"`), cannot be put back in dark: it keeps the light
+value there unless you also pass `--set-dark`.
+
+### `createTheme()`
+
+The same thing as a function, for a build script:
+
+```js
+import { writeFileSync } from "node:fs";
+import { createTheme } from "zabi-components/create-theme";
+
+const { css, tokens, warnings, closest } = createTheme({
+  brand: "#C17B00",
+  accent: "#ff3366", // optional
+  neutral: "#78716c", // optional
+  neutralChroma: 0.05, // optional, 0 to 0.1, needs neutral: a clearly tinted neutral; the ink roles follow it
+  overrides: { "--color-link": "var(--color-brand-800)" }, // optional; both modes. Or { light, dark, both }
+  pin: true, // optional: the exact brand on the primary action; or { brand: true, accent: true }
+  darkPrimary: "brand", // optional: "brand" (default, step 600 in dark too) or "mirror" (the 8.1 pale dark fills)
+});
+
+for (const warning of warnings) console.warn(warning.message);
+console.log(`Brand is closest to step ${closest.brand.step} (${closest.brand.hex}).`);
+
+if (warnings.some((warning) => warning.type === "contrast")) process.exit(1);
+writeFileSync("src/lib/brand.generated.css", css);
+```
+
+| Returned | |
+|---|---|
+| `css` | The stylesheet: a header comment and one `:root { … }` rule. With `pin`, `neutralChroma`, `darkPrimary: "mirror"` or `light` / `dark` overrides, two dark rules follow it. |
+| `tokens` | Every declaration of the `:root` rule, name to value. |
+| `darkTokens` | Only with `pin`, `neutralChroma`, `darkPrimary: "mirror"` or `light` / `dark` overrides: every declaration of the dark rules. |
+| `pinned` | Only with `pin`: `{ brand?, accent? }`, each `{ hex, light: { followed, onRamp, states }, dark: { pinned, followed, onRamp, states?, failed? } }`. |
+| `warnings` | `{ type: "contrast", pair, mode, ratio, required, foreground, background, message }` for each role pair below AA, and `{ type: "input", option, message }` notes about the colours given. Empty when everything passes. |
+| `closest` | `{ brand, accent?, neutral? }`, each `{ step, hex, deltaE, exact }`: where the input landed in its ramp. |
+
+`overrides` is either the flat map above, one value for both modes, or an object
+with any of `light`, `dark` and `both`, each a flat map:
+
+```js
+createTheme({
+  brand: "#0026EA",
+  overrides: {
+    light: { "--color-surface-raised": "#f8faff", "--color-surface-overlay": "#f8faff" }, // dark keeps its mix
+    dark: { "--color-link": "var(--color-brand-300)" }, // dark only
+    both: { "--color-focus": "var(--color-brand-700)" }, // same as the flat form
+  },
+});
+```
+
+Flat `--token` keys beside the three count as `both`. A token in `both` and in
+`light` or `dark` takes the mode's value in that mode. `tokens` holds the `:root`
+rule (`both`, then `light`); `darkTokens` holds what the dark rules say: the
+`dark` map, and for every token set in `light`, the library's dark value for it
+(or the `both` value), so `:root` does not reach dark. See
+[One mode only](#one-mode-only---set-light-and---set-dark).
+
+It throws a `TypeError` when `brand` is missing, a colour is not hex,
+`pin.accent` is set without `accent`, `neutralChroma` is not a number from 0
+to 0.1 or is given without `neutral`, `darkPrimary` is not `"brand"` or `"mirror"`, or an override is not a custom property
+name with a non-empty string value (the message names the key path, for example
+`overrides.light["--color-link"]`). Without these options the result and the
+file are exactly what they were before the option existed.
+
+## What does not follow an override
+
+- **Hover, pressed and secondary-button fills.** `--color-surface-hover`,
+  `--color-surface-active` and `--color-action-secondary` (and `-hover`,
+  `-active`) are fixed near-black (light) and near-white (dark) alpha tints.
+  They do not take the hue of `--zabi-base-*`, unless you give `neutralChroma`
+  (`--neutral-chroma`): then they are mixes of the neutral ramp's ink at the
+  same alphas.
+- **The overlay edge and the modal backdrop.** `--color-border-overlay` in
+  light is a fixed alpha tint too, and follows the ramp with `neutralChroma`
+  (in dark it is already a ramp step). `--color-overlay`, the scrim, stays black.
+- **The shadow colour.** `--shadow-color` is the default neutral's ink, not
+  your neutral's. With `neutralChroma` it is the ramp's step 900 in light;
+  otherwise set it yourself, it is on the list above.
+- **The `energetic` family.** It points at the citron ramp, not at the accent,
+  so it stays yellow when `--zabi-accent-*` changes. `success`, `warning`,
+  `error` and `info` keep their own ramps as well.
+- **The size of the dark surface steps.** The four dark levels are mixed from
+  your neutral ramp, so they take its hue. The mix amounts were solved for the
+  default greys; a neutral whose 900 or 50 step is far from `#18181b` /
+  `#fafafa` gives steps of a different size.
+- **Browsers without `color-mix()`.** Where Tailwind compiles the dark file
+  (your build, or the `zabi-components/css` bundle) it adds the default hex as
+  a fallback before each mixed surface. Those browsers get the default dark
+  surfaces whatever the app overrides.
+- **Tokens set below `<html>`.** See [Import order](#import-order).
+- **Semantic steps.** `--color-brand-*` and friends do not rebrand both modes;
+  see [Roles](#roles-read-them-do-not-set-them).
+
+## Stability
+
+Every token named in [Tokens an app may set](#tokens-an-app-may-set) and
+[Roles](#roles-read-them-do-not-set-them) is public API, and so is every other
+token the theme files publish. **Renaming or removing one is a breaking
+change.** Adding a token is not. Regenerating the library's own ramps is
+breaking too, because it changes every colour an app has not overridden.
+`RELEASING.md` says the same from the release side.
+
+This is enforced, not just promised.
+`tests/__snapshots__/theme-token-names.snap.json` lists every published token
+name. `npm run test:themes` reads the names out of the built
+`zabi-components/colors` file and fails if one on the list is missing. The
+list only grows: refreshing the snapshots adds new names and never drops one,
+so taking a name off is a hand edit of that file in a commit, which is where a
+breaking change gets noticed.
+
+The CSS export paths (`zabi-components/theme-only` and the rest) are public in
+the same way: removing one is breaking.
+
+---
+
+## Reference: how the theme is built
+
+Background for the tables above. An app does not need any of it to rebrand.
+
+### Which step does what
+
+The brand scale is used throughout the system:
+
+- **brand-50 to brand-100**: Subtle backgrounds, hover states
+- **brand-300 to brand-400**: Light accents, disabled states
+- **brand-500**: Medium emphasis
+- **brand-600**: **Primary buttons** (`action-primary`) and the focus ring, in both modes
+- **brand-700**: Primary hover, links
+- **brand-800**: Primary active, link hover
+- **brand-900 / 950**: Darkest brand shades
+
+Hover and active always move *toward* the dark end in light mode. The `.dark`
+mirror flips that automatically, so "more pressed" means "more contrast against
+the page" in both themes. Never point `-active` at a step on the far side of the
+ramp — that is how the pressed primary label ended up at 1.66:1.
 
-## 🎨 Calibrated Colour Ramps
+### Calibrated colour ramps
 
 Every chromatic ramp (`brand`, `citron`, `pine`, `iris`, `warning`, `error`) is
 **generated against one shared lightness curve**, so `<ramp>-600` means the same
@@ -194,22 +1050,29 @@ as one family instead of six unrelated colours.
 Step **600** is the solid-fill step: dark enough to clear 4.5:1 against white,
 light enough to still read as a colour. Every semantic token points at it.
 
-- **Source of truth:** `tokens/chromatic-scales.js` — hue, peak chroma, the
-  chroma envelope, and the target curve.
+- **Source of truth:** `tokens/chromatic-scales.js` — hue and peak chroma per
+  ramp. The target curve, the chroma envelope and the solver are in
+  `create-theme/lib/ramp-math.js`, which the theme generator ships, so a
+  generated brand sits on the same curve.
 - **Regenerate:** `node scripts/generate-ramps.js` (runs inside `npm run sync:tokens`).
 - **Verify:** `node scripts/check-ramp-lightness.js` — fails if any step drifts
   more than ±1.5 L\* off the curve, or if two adjacent steps differ by more than
   15 L\* (a cliff rather than a ramp).
 
-To rebrand, edit `hue` / `peakChroma` for a ramp in `tokens/chromatic-scales.js`
-and re-run the generator. **Do not hand-edit `--zabi-<ramp>-*` in `src/app.css`** —
-the generator overwrites them, in both the `@theme` block and the `.dark` mirror.
+To change the library's own ramps, edit `hue` / `peakChroma` for a ramp in
+`tokens/chromatic-scales.js` and re-run the generator. **Do not hand-edit
+`--zabi-<ramp>-*` in `src/app.css`** — the generator overwrites them. They live
+in `@theme` only; `.dark` no longer holds a copy. (An app rebrands by overriding
+them on `:root` instead; see [Tokens an app may set](#tokens-an-app-may-set).)
+
+`--zabi-accent-*` is not a generated ramp: each step aliases the citron step of
+the same number.
 
 The `base` (neutral) ramp is deliberately **not** on this curve: it is wider on
 purpose because it also drives text, borders and the surface levels. Semantic
 `neutral` aliases the base step closest to the chromatic 600s.
 
-## 🧩 Semantic Families
+### Semantic families
 
 Each family exposes the same roles, built from the same steps:
 
@@ -219,53 +1082,155 @@ Each family exposes the same roles, built from the same steps:
 | `--color-<family>-weak` | 700 | pressed / emphasis |
 | `--color-<family>-medium` | 800 | strongest fill |
 | `--color-<family>-strong` | 900 | darkest |
-| `--color-<family>-subtle` | 100 | tinted fill — badges, alerts |
-| `--color-<family>-border` | 200 | tinted edge |
+| `--color-<family>-subtle` | 200 (dark: 16% of step 500 over the card surface) | tinted fill — badges, alerts |
+| `--color-<family>-border` | 300 (dark: 36% of step 500 over the card surface) | tinted edge |
 | `--color-<family>-text` | 700 | text on a subtle fill or a page surface |
 
 Families: `success`, `warning`, `error`, `info`, `energetic`, `neutral`.
 
+`accent` has the subtle trio on the same steps, and action-style `-hover` (700)
+and `-active` (800) instead of `-weak` / `-medium` / `-strong`.
+
+The tints are the one role that does not simply mirror. A step-100 fill is
+1.16:1 on a white card, which is enough on the near-white 9.0 page once the
+tint has its edge, so light uses steps 100 and 200 for the fill and the edge.
+`.dark` restates 100 and 200 too (the mirror of those would be too heavy on a
+dark surface). `neutral` follows the same shape on the base ramp: `base-200`
+fill and `base-250` edge in light, `base-300` and `base-200` in dark.
+
 Prefer the **subtle** trio (`-subtle` fill + `-border` edge + `-text` label) for
 anything informational. Solid fills are for the one element on a screen that has
 to shout.
 
-## 📐 Control Geometry
+### Surface elevation levels
 
-One height scale is shared by **every** form control, so a Button, Input, Select
-and IconButton of the same size line up in a row:
+Every surface uses one of four semantic levels. Use these tokens instead of raw `base-*` steps for backgrounds:
 
-| size | height | token |
-|---|---|---|
-| `sm` | 32px | `--control-height-sm` |
-| `md` | 40px | `--control-height-md` |
-| `lg` | 48px | `--control-height-lg` |
+| Level | Token / utility | Use for | Light (OKLCH L) | Dark (OKLCH L) |
+|---|---|---|---|---|
+| Base | `--color-surface-base` · `bg-surface-base` | Page / app shell (the darkest level in both themes) | `base-150` · 94 | `--zabi-base-900` `#18181b` · 21 |
+| Raised | `--color-surface-raised` · `bg-surface-raised` | Cards, panels, sidebars | `#ffffff` · 100 | `--zabi-base-850` `#1f1f22` · 24 |
+| Elevated | `--color-surface-elevated` · `bg-surface-elevated` | Nested cards, hover and active fills | `base-100` · 97 | `--zabi-base-800` `#27272a` · 27 |
+| Overlay | `--color-surface-overlay` · `bg-surface-overlay` | Modals, sheets, dropdown/select menus, navigation panels, toasts | `#ffffff` · 100 | `--zabi-base-800` `#27272a` · 27 (same tone as elevated; set apart by rim and shadow) |
+| Inset | `--color-surface-inset` · `bg-surface-inset` | A recessed area on a raised surface: a well, a stat strip, a code sample inside a card | `base-100` · 97 | `--zabi-base-900` `#18181b` · 21 (the page step) |
+
+**Inset is not a fifth rung.** The four levels say how far a surface is lifted;
+inset says it is cut into the card it sits on. In light it is the ramp step
+below the raised surface, about 3 lightness points under it, and every text token
+passes AA on it. In dark it is the page step (3 points below the card). In
+light it shares `base-100` with `elevated`: under a white card the only
+direction left is down, so a nested card and a well are the same colour there.
+In dark the inset and the page are the same colour, so an inset area on the page
+needs an edge. `--color-input` no longer points at it in dark (it did up to
+9.0.0-alpha.5): a dark field is a translucent step of the neutral ramp, below.
+Do not use `--color-input` for a well. It is white in light mode, because a
+light field is a raised surface.
+
+**The dark field fill.** `--color-input` is base-50 at 7% over transparent in dark,
+`-hover` 10%, `-focus` 7%, `-active` 15%: a well lighter than whatever it sits on,
+with no rule per surface, as the dark flat card is a lighter layer. Measured on the
+default theme: the resting well is 1.20:1 off the page (#28282b), 1.22:1 off a card
+(#2e2e31) and 1.23:1 off the overlay (#363639); the pressed fill is 1.30:1 past
+the resting one on all three, the value text 7.34:1 or more and the placeholder
+4.08:1 or more on every fill (4.5:1 except pressed over the overlay, held to 4:1).
+`--color-input-placeholder` is 40% of base-350 into base-400 in dark (#ababb3, was
+base-600, #a1a1aa), because a lifted fill took the old one to 4.04:1 pressed on a
+card. The well is held at 1.15:1 or more off the page, a card and the overlay in
+dark, the hover step 1.08:1 and the pressed step 1.25:1 past rest, as pairs
+laid over what is behind the field (`behind`, `only: 'dark'`, `fgPaint`), also in
+`createTheme`'s check. The edge stays 3:1 against the surface outside the field
+(`--color-input-border`, unchanged); against the lifted fill it is 3.05:1 on the
+page, 2.79:1 on a card and 2.50:1 on the overlay (guarded at 3, 2.7 and 2.4).
+Inside a colour block (`.on-brand`, `.on-accent`, `.on-fill`) a field takes the
+opaque `--color-input-solid`, `-hover`, `-focus`, `-active` (in light the field's
+own values, in dark the old opaque field), as the flat card takes the opaque card.
+The progress track is unchanged (`--color-base-75` in dark). Restore the 9.0.0-alpha.5
+field: `overrides: { dark: { '--color-input': 'var(--color-surface-inset)',
+'--color-input-hover': 'var(--color-base-200)', '--color-input-focus':
+'var(--color-base-150)', '--color-input-active': 'color-mix(in srgb,
+var(--zabi-base-50) 10%, var(--color-surface-inset))', '--color-input-placeholder':
+'var(--color-base-600)' } }`.
 
-Enforced by `scripts/check-control-geometry.js`.
+Supporting tokens:
+- `--color-surface-overlay-hover` (`bg-surface-overlay-hover`): row and icon-button hover **inside** an overlay. It is lighter than the overlay in dark mode.
+- `--color-border-overlay` (`border-border-overlay`): 1px edge on overlays. A 10% ink tint in light mode, so a white menu on a white card has an outline; a solid step in dark mode.
 
-## 🔲 Border Radius
+**The light ladder runs downwards.** Light cannot go lighter than white, so
+below the card it is ordered page → elevated → raised, with overlay equal to
+raised and separated from it by `shadow-lg` and the overlay edge. The page is
+`base-150`, not `base-100`: at `base-100` a card was 1.10:1 on the page and a
+nested card 1.04:1 on its parent.
 
-Four radii, chosen by **role**, never by size. A large button is a bigger box
-with the same corner as a small one.
+**The dark levels are steps of the neutral ramp** (9.0, decisions D133/D134).
+The page is `--zabi-base-900`, the card `--zabi-base-850`, elevated and overlay
+`--zabi-base-800` (default `#18181b` / `#1f1f22` / `#27272a`, OKLCH L 21.0 /
+24.1 / 27.4): two tone steps in all. The overlay hover is one step lighter
+(`--zabi-base-750`, `#333338`) and the inset (a field, a well) is the page step.
+The ladder lives in `tokens/surface-ladder.js` (`SURFACE_STEP`); edit the steps
+there and run `npm run sync:tokens`, never the values in `app.css`.
 
-| token | value | use |
-|---|---|---|
-| `--radius-control` | 8px | buttons, inputs, selects, toggles |
-| `--radius-container` | 12px | cards, alerts, panels, list items, code blocks |
-| `--radius-overlay` | 16px | modals, sheets, menus, popovers, toasts |
-| `--radius-pill` | full | badges, avatars, status dots |
+Each role is a plain alias of its step and nothing else:
 
-`--radius-sm/md/lg/xl` remain as legacy aliases for consumer overrides, but
-components must not use them — `check-control-geometry.js` fails the build if a
-component reaches for a t-shirt radius.
+```css
+--color-surface-base: var(--zabi-base-900);
+--color-surface-raised: var(--zabi-base-850);
+--color-surface-overlay: var(--zabi-base-800);
+```
+
+That keeps the ramp's own hue and chroma. Until 8.1 the levels were a white
+wash mixed into the darkest neutral, which lost chroma at every level on a
+tinted neutral (`createTheme({ neutral, neutralChroma })`): the higher the
+surface, the greyer. Now `neutral: '#607296', neutralChroma: 0.08` gives a
+`#111828` page, `#18202f` card and `#202837` overlay, and a `--zabi-base-*`
+override carries all of them.
+
+**An overlay is told apart by its edge and its shadow, not by being greyer.**
+Its tone equals elevated. `--color-material-rim` (14% of `--zabi-base-50`) laid
+over the overlay is 1.85:1 on the page, 1.72:1 on the card and 1.56:1 on the
+overlay itself, and the dark `--shadow-opacity` / `--shadow-opacity-contact`
+(0.5 / 0.4) are much stronger than light's. The decorative hairline
+`--color-border` is `--color-base-250` (`#333338`) in dark: 1.41:1 on the page
+and 1.31:1 on the card. A field on the page is told apart by its 3:1 edge
+(`--color-input-border`), which is guarded on the field, page, card, elevated
+and overlay surfaces in both themes.
+
+Two things to know. The step distances depend on the app's neutrals: a ramp
+whose 900, 850 and 800 steps are far from the defaults can land outside the
+2 to 5 point window the guard holds. And wherever Tailwind compiles the dark
+file (the `zabi-components/css` bundle, or an app's own build) it may add a
+static fallback, the default hex, before an alias for browsers without
+`var()`-in-colour support.
+
+**Why dark mode steps lightness, and so little of it:** a drop shadow simulates light blocked by a raised object, which reads on a light page. On a dark page the shadow is as dark as the background, so the signal comes from tone: each level is **lighter** than the one below it, by about 3 OKLCH lightness points, with the overlay at the elevated tone and set apart by its rim and a stronger shadow. Light mode keeps white surfaces and uses shadows for elevation.
+
+**Rules:**
+- Anything that floats above content must use a lighter level than what it floats over. Floating components (Modal, SlideUp, Dropdown/Select menu, NavigationMenu panel, Toaster/Toast) use `bg-surface-overlay`.
+- Hover fills on overlays use `bg-surface-overlay-hover`, not `bg-base-*`, which would go darker in dark mode.
+- Existing tokens remain as aliases: `background` → base, `card` / `surface-1` → raised, `surface-2` / `card-hover` → elevated, `surface-3` → overlay (dark), `card-elevated` → overlay (light) / elevated (dark).
+
+**Enforced by** `scripts/check-surface-elevation.js`, which `validate-theme.js` runs during `npm run build:css`. It fails when:
+- a dark level, the overlay hover or the inset is not declared as one step of the ramp (`var(--zabi-base-N)` or `var(--color-base-N)`), for example a `color-mix()` with a wash;
+- dark lightness decreases base to raised to elevated to overlay, or raised is not lighter than the page;
+- raised, elevated and overlay use more than two distinct tones above the page, a tone step is outside 2 to 5 OKLCH L points, or the top is more than 8 points above the page;
+- the rim over the overlay is under 1.5:1 on the page or the card, or under 1.3:1 on the overlay; or the dark `--color-border` is under 1.2:1 on the page or the card;
+- the light levels are not ordered base < elevated < raised, either step is under 2 points, or the overlay is darker than raised;
+- the inset surface is less than 2 points below raised, or darker than the page, in either theme;
+- a text token falls below AA on any level or on the inset surface;
+- overlay hover or tooltip fills are darker than the overlay;
+- a floating component paints a surface class below overlay.
+
+To retune the dark levels, edit `SURFACE_STEP` in `tokens/surface-ladder.js`, run `npm run sync:tokens`, and then `node scripts/check-surface-elevation.js`.
+
+> The light surface tokens must stay **below** the `/* Background Colors */` marker in `@theme`. `scripts/sync-theme-tokens.js` regenerates everything between the base-scale aliases and that marker.
 
-## ✋ Interaction Fills
+### Interaction fills
 
 Hover and active fills are **surface-relative alpha tints**, not fixed ramp steps:
 
 ```css
 /* light */
---color-surface-hover:  rgba(9, 9, 11, 0.06);
---color-surface-active: rgba(9, 9, 11, 0.11);
+--color-surface-hover:  rgba(9, 9, 11, 0.09);
+--color-surface-active: rgba(9, 9, 11, 0.15);
 /* dark */
 --color-surface-hover:  rgba(250, 250, 250, 0.08);
 --color-surface-active: rgba(250, 250, 250, 0.14);
@@ -274,88 +1239,186 @@ Hover and active fills are **surface-relative alpha tints**, not fixed ramp step
 A fixed step can coincide exactly with the surface it sits on — `base-100` in
 dark mode *is* `--color-surface-base`, which is how ghost-button hover became
 invisible. `check-token-violations.js` now fails on `hover:bg-base-*` /
-`active:bg-base-*` in component source.
+`active:bg-base-*` in component source, in `src/routes` and in the `@apply`
+lines of `src/app.css`.
+
+Being one step away is not the same as being visible. `check-contrast.js`
+composites each tint over every surface level and requires 1.2:1 for the
+resting hover and the secondary button, and a further 1.08:1 for each state
+after it. Light hover was 6% ink, 1.14:1, and passed every check until then.
 
 Use `hover:bg-surface-hover` / `active:bg-surface-active` for quiet controls, and
 the `action-*-hover` / `action-*-active` tokens for filled ones.
 
-## ♿ Contrast
+**State variants next to a hand-written colour class.** `text-description`,
+`border-border`, `bg-card` and the other semantic colour classes are written by
+hand in `src/app.css`, outside every cascade layer, so they beat any generated
+utility on the same element, including the state variant meant to replace
+them. `text-description hover:text-headline` compiled and never changed on
+hover. Each such variant a component uses is restated by hand in the block
+headed "STATE VARIANTS OF THE HAND-WRITTEN COLOUR CLASSES". When a component
+needs a new one, add the rule there; `tests/state-variants.test.ts`
+(`scripts/check-state-variants.js`) fails until it exists.
+
+### Contrast
 
 `scripts/check-contrast.js` resolves every fill/foreground pair a component can
 render — through the same token chain the CSS uses — in **both** themes, and
-fails below WCAG AA. Run it after re-pointing any token:
+fails below WCAG AA. It also holds the focus ring to 3:1 against the page, a
+card, and the offset gap that separates it from a primary button. The muted
+ring (`--color-focus-ring-muted`), the danger ring (`--color-focus-ring-danger`) and the control boundary
+(`--color-control-border`), and the brand and nav rings, are held to 3:1 on
+all five surfaces: page, card, inset, elevated and overlay. The colour a focus-ring rule
+uses must be a token in that list (`scripts/contrast-pairs.js`), so a ring
+cannot read a raw ramp step.
+`--color-input-border`, the edge of a form field, is held to 3:1 on the field
+fill (`--color-input`; over the page, a card and the overlay in dark, where the fill is translucent), the page and the card (WCAG 1.4.11). The same pairs are
+in the list `createTheme` checks, so a generated theme that lets a field's edge
+fall below 3:1 is reported. Run it after
+re-pointing any token:
 
 ```bash
-npm run check:contrast     # or: npm run check:design (all four guards)
+npm run check:contrast     # or: npm run check:design (all five guards)
 ```
 
-## 🧱 Surface Elevation Levels
+### Border radius
 
-Every surface uses one of four semantic levels. Use these tokens instead of raw `base-*` steps for backgrounds:
+Four radii, chosen by **role**, never by size. A large button is a bigger box
+with the same corner as a small one.
 
-| Level | Token / utility | Use for | Light | Dark (OKLCH L) |
-|---|---|---|---|---|
-| Base | `--color-surface-base` · `bg-surface-base` | Page / app shell (the darkest level in dark mode) | `base-100` | `#18181b` · 21 |
-| Raised | `--color-surface-raised` · `bg-surface-raised` | Cards, panels, sidebars | `#ffffff` | `#262629` · 27 |
-| Elevated | `--color-surface-elevated` · `bg-surface-elevated` | Nested cards, hover and active fills | `base-50` | `#35353a` · 33 |
-| Overlay | `--color-surface-overlay` · `bg-surface-overlay` | Modals, sheets, dropdown/select menus, navigation panels, toasts | `#ffffff` | `#44444c` · 39 |
+| token | value | use |
+|---|---|---|
+| `--radius-control` | 8px | buttons, inputs, selects, toggles |
+| `--radius-container` | 12px | cards, alerts, panels, list items, code blocks |
+| `--radius-overlay` | 16px | modals, sheets, menus, popovers, toasts |
+| `--radius-pill` | full | badges, avatars, status dots |
 
-Supporting tokens:
-- `--color-surface-overlay-hover` (`bg-surface-overlay-hover`): row and icon-button hover **inside** an overlay. It is lighter than the overlay in dark mode.
-- `--color-border-overlay` (`border-border-overlay`): 1px edge on overlays. Transparent in light mode, visible in dark mode.
+`--radius-sm/md/lg/xl` remain as legacy aliases so that existing consumer
+stylesheets keep compiling, but components must not use them — `check-control-geometry.js` fails the build if a
+component reaches for a t-shirt radius.
+
+### Control geometry
 
-**The dark levels are generated, not hand-picked.** Each one is `#fafafa` — the
-same light as the dark hover tint `--color-surface-hover` — washed over the page
-at 6.4% / 13.1% / 19.7%, so every level is literally the level below it with more
-light on it. The ladder lives in `tokens/surface-ladder.js`; edit the alphas
-there and run `npm run sync:tokens`, never the hex in `app.css`.
+One height scale is shared by **every** form control, so a Button, Input, Select,
+IconButton and Slider of the same size line up in a row:
 
-The composite is baked to an opaque hex at build time rather than shipped as
-`rgba()`. Flat colours keep the static toolchain working — `check-contrast.js`
-can resolve every AA pair against a surface, `check-surface-elevation.js` can
-measure the steps — and an opaque overlay means a modal never lets the page bleed
-through it. The trade: nesting past the four levels is not automatic. A card
-inside a card does not self-lighten, it names the next level up.
+| size | height | token |
+|---|---|---|
+| `sm` | 32px | `--control-height-sm` |
+| `md` | 40px | `--control-height-md` |
+| `lg` | 48px | `--control-height-lg` |
 
-**Why dark mode steps lightness instead of using shadows:** a drop shadow simulates light blocked by a raised object, which reads on a light page. On a dark page the shadow is as dark as the background, so the signal disappears. In dark mode each level is therefore **lighter** than the one below it, by +6 OKLCH lightness points on the neutral base hue. Light mode keeps white surfaces and uses shadows for elevation.
+IconButton also has `xs`, a 24px box for dense pointer-first layouts. No text
+control is that small, so it sits outside the shared scale, and the check pins
+it separately.
 
-**Rules:**
-- Anything that floats above content must use a lighter level than what it floats over. Floating components (Modal, SlideUp, Dropdown/Select menu, NavigationMenu panel, Toaster/Toast) use `bg-surface-overlay`.
-- Hover fills on overlays use `bg-surface-overlay-hover`, not `bg-base-*`, which would go darker in dark mode.
-- Existing tokens remain as aliases: `background` → base, `card` / `surface-1` → raised, `surface-2` / `card-hover` → elevated, `surface-3` → overlay (dark), `card-elevated` → overlay (light) / elevated (dark).
+Enforced by `scripts/check-control-geometry.js`.
 
-**Enforced by** `scripts/check-surface-elevation.js`, which `validate-theme.js` runs during `npm run build:css`. It fails when:
-- dark levels aren't strictly increasing;
-- any step is outside 5–8 OKLCH L points;
-- overlay hover or tooltip fills are darker than the overlay;
-- a floating component paints a surface class below overlay.
+### Materials
+
+Frosted glass is the default for the layer that **floats over content**: bars,
+sheets, menus. It is never for cards, lists, inputs or the page. A material is
+a surface at partial alpha with a backdrop blur, a light top edge, a 1px rim
+and a soft shadow, applied together by one class.
+
+| Class | Fill | Use for | Text it may carry |
+|---|---|---|---|
+| `material-thin` | `--color-material-thin` (from `--color-surface-chrome`) | A single control floating on a bar | headline |
+| `material-regular` | `--color-material-regular` (from `--color-surface-chrome`) | Bars, the tab bar, a floating sidebar | headline, body, label |
+| `material-thick` | `--color-material-thick` (from `--color-surface-overlay`) | Sheets, menus, modals, toasts, tooltips | all five text roles |
+
+Supporting tokens: `--material-alpha-thin|regular|thick`, `--material-backdrop-brightness`, `--material-blur-thin|regular|thick`
+(16, 24 and 32px), `--material-saturate`, `--color-material-highlight`,
+`--color-material-rim` and `--shadow-material`. The highlight and rim are mixes
+of the neutral ramp (`--zabi-base-50` and `--zabi-base-900`) and the shadow is
+built on `--shadow-color`, so a neutral override tints all of them. A class
+sets no position, radius or overflow: add `rounded-*` yourself. A component
+never writes `backdrop-blur-*` or `backdrop-filter` (`scripts/check-token-violations.js`
+fails it).
+
+**The floor.** A material is judged over the worst backdrop of the mode, not
+alone: the fill is composited over `--zabi-base-950` (light) or `--zabi-base-50`
+(dark), the far ends of the neutral ramp, because a photo can be that dark or
+that bright. In dark that backdrop is first dimmed: the filters are
+`blur() saturate() brightness(var(--material-backdrop-brightness))`, the token is
+`1` in light (an identity) and `0.6` in dark, and `brightness()` multiplies the
+sRGB channels, so the brightest thing behind dark glass is step 50 times 0.6.
+This is what a browser paints, because every fallback below removes the filter
+and makes the fill opaque in the same breath. Only material pairs are dimmed. On
+that result the roles above need 4.5:1, and regular and thick need the focus ring
+at 3:1 (a thin control's ring is drawn around it, outside the material); the same
+roles are also held over the mode's own page. `npm run check:contrast` and
+`createTheme` both compute this, with the mode's own value of the token, so an
+app that sets `--material-backdrop-brightness` back to 1 in dark is warned if its
+alphas then fail. The alphas for thin, regular and thick are light 58, 84, 88
+and dark 60, 68, 72: each is the smallest whole percent that passes plus a
+margin (against the page-colour chrome the floors are thin 50 / 30, regular
+82 / 47 and thick 84 / 68, light / dark).
+
+**Fallbacks.** The three fills become the opaque surface they are made from and
+the blur is removed under `prefers-reduced-transparency: reduce`,
+`prefers-contrast: more`, `forced-colors: active`, where `backdrop-filter` is
+unsupported, and wherever the app sets `data-materials="opaque"` on the root or
+any ancestor (a way out for a slow phone). The fallback re-points the tokens,
+so every use of them follows, in both modes and over an app's own fill. Under
+forced colors the rim is a 1px `CanvasText` outline. To set a fill per mode:
+`overrides: { light: { '--color-material-regular': … }, dark: { … } }`.
+
+**Layers.** `backdrop-filter` makes an element the containing block of its fixed
+descendants, so a container that holds a Dropdown or a Tooltip puts the glass on
+a `::before` instead. `material-layer-thick` and `material-layer-regular` are the
+layer forms of thick and regular (same tokens, so every fallback applies): the
+element is positioned by you, never scrolls its own content, and keeps only the
+outer shadow.
+
+**Bars.** `--color-surface-chrome` is the page colour in both modes, so a bar is
+flush with the page. `material-bar` is the bar surface: put it on a positioned
+element (never a scroller). At rest its `::before` layer is `--color-bar`, with
+no line and no blur; with `data-scrolled-under="true"` it is the regular material
+and a 1px `--color-bar-border` hairline on the content side (the bottom edge, or
+the top edge with `data-bar-edge="bottom"`). The fill and line fade over
+`--duration-moderate`. Under the fallbacks a scrolled bar is page coloured with the
+hairline (`CanvasText` in forced colors). Scope `--color-bar` on the element
+(`transparent`, `var(--color-bar-brand)`) and the layer follows. Tokens, each
+settable per mode:
+
+| Token | Default | Use |
+|---|---|---|
+| `--color-bar` (read by `material-bar`) | `var(--color-surface-chrome)` | A bar's fill at rest |
+| `--color-bar-border` (`border-bar`) | headline at 10% | The hairline once content is under the bar; decorative |
+| `--color-bar-brand` (`bg-bar-brand`) | `var(--color-action-primary)` | An on-brand AppBar; `--color-on-brand` is held at 4.5:1 on it |
+| `--color-tabbar-active` (`bg-tabbar-active`) | `var(--color-nav-menu-active)` | The active tab's pill; `--color-nav-menu-item-active` is held at 4.5:1 on it |
 
-To retune the dark levels, edit the four `--color-surface-*` values in the `.dark` block of `src/app.css` and run `node scripts/check-surface-elevation.js`.
+`--color-bar` and headline are held at 4.5:1 as well. To get the raised bar fill
+back: `--color-surface-chrome: var(--color-surface-raised)`.
 
-> The light surface tokens must stay **below** the `/* Background Colors */` marker in `@theme`. `scripts/sync-theme-tokens.js` regenerates everything between the base-scale aliases and that marker.
+### Gradients
 
-## 🎛️ Overriding a Component's Classes
+Two gradients, as tokens, so a rebrand carries through. Contrast is never measured against a gradient; the guard checks the worst stop of each.
 
-`class` is the public prop on every component and is merged **last**, so a
-call-site utility wins. That promise needs `cn()` (`src/components/util/cn.ts`,
-tailwind-merge) to be true: `rounded-control` and `rounded-container` are
-equal-specificity utilities, so plain concatenation leaves the winner to
-whichever one Tailwind emits later in the stylesheet, not to the caller.
+- **Canvas.** `--gradient-canvas` is two soft radial washes from `--color-brand-300` and `--color-accent-300` (stops `--color-canvas-wash-brand|accent`, strength `--gradient-canvas-strength`, light 55%, dark 25%). Glass over a flat page shows nothing; put `bg-canvas` (page colour plus the wash) on a fixed-height shell or a scroll container, where the wash stays put as content moves. The library never applies it to `body`. Text roles, link, focus ring and field edge are held on each stop over the page.
+- **Solid controls.** `bg-control-gradient` (primary and danger; the veil is neutral) and `bg-control-gradient-accent` lay a veil over the control's own `background-color`: a light neutral at the top, a slight dark one at the bottom (`--color-control-gradient-start|end`, `--color-control-gradient-accent-start|end`), plus an inset top edge (`--shadow-control-highlight`). Hover and pressed fills still show through. The label is held at 4.5:1 on both ends over rest, hover and pressed, for primary, accent and danger. Progress does not take a gradient.
+  - Light is darken-only: `--gradient-control-top-strength: 0%` (the top is the control's own colour, so the label keeps its full contrast and your brand colour is not altered) and `--gradient-control-bottom-strength: 14%`. Dark is 22% / 6%. The accent has strengths of its own, `--gradient-control-accent-top-strength` and `-bottom-strength`, which follow the shared ones.
+  - The highlight is written to Tailwind's inset-shadow variable, so a `shadow-*` class and `focus-ring` on the same element still draw.
+  - `createTheme` does not hand you a veil that fails: where the darkened bottom takes a dark label under 4.5:1 (a light accent), it flips that veil to lighten-only in that mode (top up to 14%, bottom 0); if no strength passes it writes both as 0%. A strength you set yourself is never moved, only reported.
+- Override per mode with `createTheme` `overrides` and restate dark; a strength too high is reported as a contrast warning.
 
-```svelte
-<Card class="rounded-pill" />   <!-- rounded-container is dropped, not fought -->
-```
+### Buttons and the Toggle
 
-Most semantic utilities work with stock tailwind-merge — `bg-card` vs
-`bg-surface-overlay`, `text-headline` vs `text-description` all resolve. The
-role-based radii are the exception and are declared explicitly in `cn.ts`,
-because `control`/`container`/`overlay`/`pill` are role names rather than scale
-values. **Add any future custom scale to that config**, or tailwind-merge keeps
-both classes and stylesheet order silently decides again.
+Tokens and classes the 9.0 Button, Toggle and FloatingActionButton read. All settable like any role; dark is restated.
 
-Covered by `tests/class-merge.test.ts`.
+- **Tonal** (`bg-action-tonal`, `text-action-tonal`): `--color-action-tonal` (the brand tint), `-hover`, `-active`, and `--color-action-tonal-text` (brand step 800, 4.5:1 or more on all three fills in both modes; step 700 fails the pressed fill on a saturated brand).
+- **Outline edge** (`border-action-outline`): `--color-action-outline-border` and `-hover`, the field edge by default (3:1 on the page and a card in both modes). Inside `.on-brand` and `.on-accent` it is the block's label colour.
+- **Button corner and label weight**, apart from fields: `rounded-button` reads `--zabi-button-radius` and falls back to `--radius-control`; `font-button` (500) and `font-button-strong` (600) read `--zabi-button-font-weight`. Declared nowhere, so set them on any ancestor (or in `createTheme` `overrides`).
+- **Off Toggle** (`bg-toggle-track`, `ring-toggle-track`): `--color-toggle-track`, `-hover`, `-active` and `--color-toggle-track-border`. The track is a light tint; its edge is what holds 3:1 on the page and a card (WCAG 1.4.11). `--color-control-track*` is unchanged and still the Slider's. **Toggle knob** (`bg-toggle-thumb`, `bg-toggle-thumb-checked`): the default knob is `--color-toggle-knob` off (light base-500, dark base-700) and `--color-toggle-knob-checked` on (the primary fill's label colour), each 3:1 or more on every track fill it sits on, at rest, hovered and pressed (WCAG 1.4.11; guarded, 3.27:1 at the least in light off, 4.86:1 on). A theme sets those two, light and dark each in their own block, and `scripts/check-contrast.js` holds the pairs. `--color-toggle-thumb` and `--color-toggle-thumb-checked` are declared nowhere, so any ancestor can set them and they win: the first is the knob in both states (the checked state reads it when its own is unset), the second the knob when on only. Contrast of an override is yours to check. In forced colours the knob is a system colour and none of the tokens is read.
+- **Neutral subtle Badge** (`bg-badge-neutral`, `text-badge-neutral`): `--zabi-badge-neutral-fill` and `--zabi-badge-neutral-text`, declared nowhere, read in front of `--color-neutral-subtle` and `--color-neutral-text`. Set them on any ancestor or in the theme (light and dark each in their own block) and the neutral subtle `Badge` moves; `Alert variant="neutral"`, `Skeleton`, `AvatarGroup`, `Header` and the other badge variants do not. Unset, the badge is as it was. Inside `.on-brand`, `.on-accent` and `.on-fill` the text is the theme's body colour again, as for any neutral surface; the fill follows the property. Contrast of the pair is yours to check (the default is 8.2:1 in light).
+- **Skeleton on a colour block** (`tone="on-color"`, `bg-skeleton-on-color`): the fill is the surface's label colour at 24% (`color-mix(in srgb, currentColor 24%, transparent)`), so inside `.on-brand`, `.on-accent`, `.on-fill` or a `Card` with `tone` it follows the block's label colour in light and dark. `--zabi-skeleton-fill`, declared nowhere, replaces it on any ancestor. The class is not in the lists that restore the theme's text on a surface inside a block, on purpose. The default `tone="neutral"` is `bg-neutral-subtle`, unchanged.
+- **Chip** (`bg-chip`, `text-chip-text`): `--color-chip`, `-hover`, `-active` (light base-200, 300, 350; dark base-750, 700, 650) and `--color-chip-text` (the headline, 4.5:1 on all three). Seen on the page and a card without an edge, 1.2:1 or more, guarded. **Selected chip** (`bg-chip-selected`, `text-chip-selected-text`): `--color-chip-selected`, `-hover`, `-active`, `-text`, the tonal role by default, as tokens of their own, with the label held on all three fills.
+- **Tint card** (`bg-card-tint`): `--color-card-tint`, brand-100 in light and the brand at 8% over the card in dark. Headline, body, label, description, caption and link are held to 4.5:1 on it, and the ring, the field edge and the outline Button's edge to 3:1, in both modes.
+- **Flat card** (`bg-card-flat`): `--color-card-flat`, `-hover`, `-active`. Light is the card, hover and pressed fills, opaque, as before. Dark is the neutral ramp's base-50 at 7%, 11% and 15% over transparent, so a flat card is a lighter layer of whatever is behind it: on the page (#18181b) one layer is #282829, on a card (#1f1f22) #2e2e31, on the overlay (#27272a) #363638, and each nested layer is another 1.2:1 to 1.25:1 step. It is derived from the ramp, so `neutralChroma` tints it. Restore the opaque fill with `overrides: { dark: { '--color-card-flat': 'var(--color-card)' } }` (and `-hover`, `-active` for an interactive flat card). Held in dark: the five text roles, the link and the ring on three layers over the card, two over the overlay and one over the page (the caption is 4.1:1 on three over the overlay, so that stack is not held), and the field edge and the outline Button's edge at 3:1 on one layer over the page (3.03:1; on a layer over a card or an overlay they are 2.8:1 or less, so a field there keeps its own fill). Inside a `tone` card (`.on-brand`, `.on-accent`, `.on-fill`) a flat card is the opaque card with the theme's text, in dark too, as `bg-card` was: a translucent step over the block's fill would carry the theme's text at about 2.3:1, and the label colour at 4.4:1.
+- **Progress track edge** (`border-progress-track-border`): `--color-progress-track-border`, the field edge by default (3:1 on the page and a card in both modes, because the default track is the field fill and does not reach it). `transparent` skips the guard. `createTheme` writes `transparent` for a mode in which you override `--color-progress-track` with a colour that itself reaches 3:1 on the page and the card, unless you set the edge; an edge you set, `transparent` included, is never moved.
 
-## 🌑 Shadow Scale
+### Shadow scale
 
 Elevation in light mode is **two steps**, not a ramp. A shadow says "this is
 above the page" or "this floats over it" — there is no third meaning, and an
@@ -378,11 +1441,15 @@ Rules:
   `shadow` utility is the sneaky one: it resolves to a Tailwind default that
   `app.css` never defines, so no token controls it.
 - Shadows carry elevation in **light mode only**. In dark mode the surface
-  levels above do the work — see Surface Elevation Levels.
+  levels above do the work — see [Surface elevation levels](#surface-elevation-levels).
+- The light shadow is the ramp's own ink (`--shadow-color: 24 24 27`). Every
+  step is two layers: a tight contact shadow at `--shadow-opacity-contact`
+  (0.06; dark 0.3) and a wider, softer one at `--shadow-opacity` (0.10; dark
+  0.24). Until 8.1 both layers shared one flat 0.14 (dark 0.3).
 
 Enforced by `scripts/check-token-violations.js`.
 
-## 📏 Spacing Rhythm
+### Spacing rhythm
 
 Layout spacing rides a **4px grid**. Half-steps (`gap-1.5`, `px-2.5`, `py-2.5`)
 set up a second rhythm competing with the first: a 6px gap beside an 8px gap is
@@ -398,7 +1465,7 @@ a 2px wobble nobody chose, and it accumulates down a dense form.
 
 Enforced by `scripts/check-token-violations.js`.
 
-## 🔠 Type Scale
+### Type scale
 
 `Heading` and `Text` sit on **one** ramp rather than each carrying its own, so a
 heading and the copy beneath it share line boxes instead of nearly matching.
@@ -414,65 +1481,158 @@ heading and the copy beneath it share line boxes instead of nearly matching.
 | 14px | — | `size="sm"` |
 | 12px | — | `size="xs"` |
 
-Headings tighten tracking as they grow and are `semibold`/`bold`; `Text` takes a
+Headings use `--font-family-heading` (the sans family unless an app sets it),
+tighten tracking as they grow and are `semibold`/`bold`; `Text` takes a
 `weight` prop (`normal` · `medium` · `semibold` · `bold`) so body copy can carry
 emphasis without being promoted to a heading. `tone="label"` defaults to
 `medium`; every other tone defaults to `normal`.
 
-## 📁 File Structure
+### Overriding a component's classes
+
+`class` is the public prop on every component and is merged **last**, so a
+call-site utility wins. That promise needs `cn()` (`src/components/util/cn.ts`,
+tailwind-merge) to be true: `rounded-control` and `rounded-container` are
+equal-specificity utilities, so plain concatenation leaves the winner to
+whichever one Tailwind emits later in the stylesheet, not to the caller.
 
+```svelte
+<Card class="rounded-pill" />   <!-- rounded-container is dropped, not fought -->
 ```
-src/
-└── app.css          ← 🎯 EDIT THIS FILE FOR ALL THEMING (single source of truth)
 
-dist/                 ← ⚠️ GENERATED FILES - DON'T EDIT
-├── zabi-components.css              (full CSS with dark mode)
-├── zabi-components-theme.css       (light mode only)
-├── zabi-components-theme-only.css  (light mode only)
-├── zabi-components-theme-dark.css   (dark mode only)
-├── zabi-components-theme-dark-only.css (dark mode only)
-└── zabi-components-colors.css       (standalone, both modes)
+Most semantic utilities work with stock tailwind-merge — `bg-card` vs
+`bg-surface-overlay`, `text-headline` vs `text-description` all resolve. The
+role-based radii are the exception and are declared explicitly in `cn.ts`,
+because `control`/`container`/`overlay`/`pill` are role names rather than scale
+values. **Add any future custom scale to that config**, or tailwind-merge keeps
+both classes and stylesheet order silently decides again.
+
+Covered by `tests/class-merge.test.ts`.
 
-examples/             ← ⚠️ EXAMPLES ONLY - DON'T EDIT
-└── theme-extensions/
-    ├── 02-custom-brand-colors.css
-    └── 03-custom-semantic-colors.css
-```
+---
 
-## ⚠️ Important Notes
+## For maintainers
 
-1. **Never edit files in `dist/`** - These are automatically generated from `src/app.css` by `scripts/build-css.js`
-2. **All theming is in `src/app.css`** - This is the single source of truth
-3. **Always edit `src/app.css`** - This is your single source of truth
-4. The `examples/` folder contains examples, not your actual theme
-5. **Dist files are overwritten** every time you run `npm run build:css`
+This part is about changing the library's own theme, not an app's.
 
-## 🔄 Build Process
+### One source file
 
-When you edit `src/app.css`:
+All theming is in `src/app.css`:
 
-1. **Development**: Changes are automatically reflected (no build needed)
-2. **Production**: Run `npm run build:css` to regenerate dist files
-3. The build script (`scripts/build-css.js`) reads `src/app.css` and generates:
-   - `zabi-components.css` - Full compiled CSS with Tailwind processed (includes dark mode)
-   - `zabi-components-theme.css` - Theme block with Tailwind import (light mode only)
-   - `zabi-components-theme-only.css` - Theme block only (light mode only)
-   - `zabi-components-theme-dark.css` - Dark mode theme with Tailwind import
-   - `zabi-components-theme-dark-only.css` - Dark mode theme only
-   - `zabi-components-colors.css` - Standalone CSS custom properties (both light and dark)
+- the `@theme` block holds every token and the light values, including the raw
+  `--zabi-*` ramps, declared once;
+- one `.dark { … }` rule remaps roles for dark. No `--zabi-*` token and no hex
+  literal belongs in it; `validate-theme.js` fails the build on either.
 
-## 🔄 After Making Changes
+The files under `dist/` are generated from it by `scripts/build-css.js` and are
+overwritten on every build. Never edit them. Which file is which is in
+[docs/theme-imports.md](./docs/theme-imports.md). `examples/theme-extensions/`
+holds examples, not the theme.
 
-### For Development
-After editing `src/app.css`, changes are automatically reflected in your app. No build needed!
+Parts of `src/app.css` are generated too, so edit the source instead:
 
-### For Production/Library Build
-If you're building the library for distribution:
-```bash
-npm run build:css  # Regenerates all dist CSS files from src/app.css
+| To change | Edit | Then run |
+|---|---|---|
+| A chromatic ramp (`brand`, `citron`, `pine`, `iris`, `warning`, `error`) | `hue` / `peakChroma` in `tokens/chromatic-scales.js` | `npm run sync:tokens` |
+| The neutral ramp | `tokens/base-scale.js` | `npm run sync:tokens` |
+| The dark surface levels | `SURFACE_STEP` in `tokens/surface-ladder.js` | `npm run sync:tokens` |
+| A role, a font, a radius | `src/app.css` | nothing in development |
+
+Before a release, `npm run build:css` regenerates the `dist/` files and
+`npm run build:lib` does that and verifies them (`scripts/verify-build.js`).
+
+### Dark mode selectors
+
+`src/app.css` holds one `.dark { … }` rule. `scripts/build-css.js` publishes it,
+in every file that carries dark tokens, as:
+
+```css
+:root, [data-theme="light"] { color-scheme: light; }   /* in the light files */
+[data-theme="light"] { color-scheme: light; }
+[data-theme="dark"]  { color-scheme: dark; }
+[data-theme="auto"]  { color-scheme: light dark; }
+.dark, [data-theme="dark"] { …; color-scheme: dark; }
+@media (prefers-color-scheme: dark) { [data-theme="auto"] { …; color-scheme: dark; } }
 ```
 
-## Optional perceptual midpoint generation (OKLCH)
+- The light rule is written by hand in `src/app.css`, above `.dark`, and has
+  to stay above it: all of these have the specificity of one class, so the
+  later one wins. `validate-theme.js` fails the build if a light file lacks
+  the rule or has it after a dark one.
+- `color-scheme: dark` is the last declaration of the source `.dark` rule, so
+  every dark selector carries it. The three attribute rules come first: with
+  `class="dark" data-theme="light"` the class brings the dark tokens, and so
+  the dark scheme with them.
+- All selectors have the specificity of `.dark`.
+- Keep it as one `.dark` rule in the source and do not write the others by
+  hand; `scripts/dark-selectors.js` generates them.
+- The dev site and Storybook read `src/app.css` directly. `postcss.config.cjs`
+  runs the same expansion on it, so `data-theme` works there as it does in the
+  published files.
+
+`validate-theme.js` fails the build if a dark-carrying file lacks any of the
+three, or if the `auto` copy differs from `.dark`.
+
+### Dark mode action colours
+
+- **Primary.** The same physical steps as light: `.dark` points
+  `--color-action-primary`, `-hover` and `-active` at `--zabi-brand-600`, `700`
+  and `800` (not the mirrored `--color-brand-*`, which are the pale 400, 300
+  and 200). The label is `--color-on-brand`, which `.dark` points at
+  `--zabi-on-brand-dark` (white). The fill is 3.72:1 on the dark page, 3.43:1
+  on a card and 3.10:1 on the overlay, held by guarded pairs. The ring, links,
+  the tonal roles and the nav-active roles stay on the mirrored steps (they are
+  text, rings and tints on a dark surface).
+  `--color-primary*` is unchanged (still mirrored; no component reads it).
+- **Status tints.** In dark, `--color-<success|warning|error|info|energetic|accent>-subtle`
+  is the hue thinned into the card surface: `color-mix(in srgb, var(--zabi-<ramp>-500) 16%, var(--color-surface-raised))`;
+  `-border` is the same mix at 36%. A badge or alert is a low-chroma tint of its
+  card (never darker than it) and the hue is carried by the icon and the text,
+  which are unchanged. Because the base is a `var()`, an app's override of the
+  card surface (or `neutralChroma`) carries through. `neutral` and the brand
+  tints are unchanged.
+- **Secondary.** No dark override: `--color-base-*` mirrors the same way.
+- **Danger.** The same physical steps as light danger (`--zabi-error-600`,
+  `700`, `800`, label `--zabi-error-50`), so a destructive button is one red in
+  both modes. Its `-subtle` tint is the error tint (`--color-error-subtle`), with
+  `-subtle-hover` (20%) and `-subtle-active` (32%) stronger mixes. Restated in `.dark` so that
+  `zabi-components/theme-dark-only` remains a complete standalone import
+  (`validate-theme.js` enforces that).
+
+Hover and active move toward the dark end for the primary and danger fills in
+both modes (one recipe). For the mirrored roles the mirror flips that, so "more
+pressed" means "more contrast against the page" in both themes. Never point `-active` at a step on the far side of the ramp; that is
+how the pressed primary label once ended up at 1.66:1.
+
+### Building the generator
+
+The source is `create-theme/`. It ships as plain ESM in `dist/create-theme/`
+and needs `culori` at runtime, so `culori` is a dependency.
+`scripts/build-create-theme.js` copies it and writes `theme-data.js`, the
+default theme and the pair list, from `src/app.css` and
+`scripts/contrast-pairs.js` on every build. `verify-build.js` fails if that
+file differs from its sources, and runs the bin from `dist/`. Tests:
+`tests/create-theme.test.js`, part of `npm run test:themes`.
+
+### Where the two-brand proof lives
+
+- `tests/theme-output.test.js` (`npm run test:themes`) proves from the built
+  CSS that one ramp override rebrands light and dark, and keeps the list of
+  published token names.
+- The docs site runs under two brands: the default, and Amber, which
+  `vite-plugin-brand-themes.js` builds with `createTheme` from the inputs in
+  `src/lib/marketing/brand-inputs.ts` each time the site starts or builds. The
+  switcher is in the top bar and on `/theming`; `?brand=amber` opens any page
+  in it.
+- `playwright/theme-brands.spec.ts` (`npm run test:e2e`) loads component pages
+  under both brands, in light and dark, at desktop width and at 375px, and
+  checks from computed styles that the primary fill, its label, the focus ring,
+  the card surface and the heading face change with the brand and that the
+  label keeps 4.5:1.
+- `tests/theming-guide.test.ts` (`npm test`) fails if this guide, `THEME.md`,
+  `docs/theme-imports.md` or the site's token tables name a token the theme
+  does not publish.
+
+### Optional perceptual midpoint generation (OKLCH)
 
 Base midpoints are frozen hex by default (`fixed` mode).  
 For experimentation, you can generate midpoint steps in OKLCH interpolation and commit the resulting frozen values: