@brignano/design 0.2.0 → 0.3.1

package/DECISIONS.md

@@ -248,3 +248,136 @@ over the existing state hues. No new hue enters the system.
   status share hues in ADR-0004.
 - Standalone exports (SVG files, Mermaid in a pull request) take the light theme's
   values, resolved from `tokens.css` by the consumer at build time.
+
+---
+
+## ADR-0006 — One declaration per colour, via `light-dark()`
+
+**Status:** accepted · 2026-10-25
+
+### Context
+
+Dark mode lived in three lists: a `prefers-color-scheme` block (the OS default),
+a `[data-theme='dark']` block (the toggle, which has to win), and a copy in
+`previews/_preview.css` so a preview could show both themes at once. CSS can't
+share one declaration block between a media query and a selector, so the
+duplication was structural, and the file's own rule — "edit one, edit the other"
+— was enforced by remembering. The preview copy had already fallen behind
+(`--i-selection`, `--scrim` and `--on-dark` were missing).
+
+### Decision
+
+Every colour is declared once, on `:root`, as `light-dark(<light>, <dark>)`. The
+theme is `color-scheme`: `light dark` by default, pinned by `[data-theme]`.
+
+Arguments are always concrete colours, never a `var()` to another
+theme-dependent token. Nested `light-dark()` — directly, or inside
+`color-mix()` — is valid CSS, but support across engines couldn't be verified
+when this was written, and getting it wrong would blank colours in one browser.
+Where that forces a repeat (a wash repeats its hue, `--bg` repeats a ramp step),
+`npm run check` holds the copy to its source.
+
+Shadows differ in blur as well as colour, and `light-dark()` only switches
+colour, so the two themes' shadows are separate layers, each transparent in the
+other theme.
+
+### Rationale
+
+- **Drift becomes impossible rather than checked.** There's no second list.
+- **Theming becomes scoped for free.** The value is picked where a colour is
+  used, so `data-theme="dark"` on a `<section>` themes that section. The preview's
+  forced-dark panel is now `color-scheme: dark` and nothing else.
+- **No change in output.** Verified in Chromium against the previous file: all
+  119 tokens are identical in five setups (OS light, OS dark, a toggle forcing
+  each way, and both agreeing). The shadows and every preview page are
+  identical pixel for pixel.
+
+### Consequences
+
+- Browser floor: Chrome/Edge 123, Firefox 120, Safari 17.5.
+- `getPropertyValue('--x')` returns the `light-dark(…)` text. JavaScript that
+  needs a colour resolves it through `getComputedStyle` on an element
+  (DESIGN.md §11). ADR-0002's advice that `chart-colors.ts` read the custom
+  properties still stands, but by that route.
+- Consumers shouldn't wrap tokens in `color-mix()`; washes are tokens. The
+  first consumer that needed one (`life`'s sticky bars) got `--surface-sticky`
+  in 0.3.1 rather than a local mix.
+- A build that lowers `light-dark()` for older browsers (Lightning CSS, inside
+  Next.js and Vite) fixes the theme at `:root`, losing scoped theming. Found in
+  `brignano.io`; consumers set `browserslist` to the floor (DESIGN.md §11).
+- Not a token rename and not a visual change, so a patch release.
+
+
+---
+
+## ADR-0007 — The neutral ramp is one temperature: OKLCH hue 286°
+
+**Status:** accepted · 2026-10-25
+
+### Context
+
+`tokens.css` called the ramp "cool-leaning", and most of it was: light 300–800
+and dark 0–800 sit at OKLCH hue 286°. But light 50, 100 and 200 — the hairline,
+`--line-soft`, the hover and pressed surfaces — sat at 106°, a faint yellow, and
+dark 900, the primary ink, did too. A border and the label beside it disagreed
+on temperature. It was too slight to notice as a colour, but enough to make a
+surface read slightly dirty next to a cool one.
+
+### Decision
+
+Every tinted step sits at hue 286°. The off-hue steps (light 25, 50, 100, 200,
+900; dark 800, 900) are regenerated at **their existing OKLCH lightness**, so
+contrast stays within 0.04 of its old value. Their chroma fits the curve
+already set by their neighbours: near zero at the ends, peaking in the
+mid-tones. Steps already at 286° are untouched. Pure white stays pure white.
+`npm run check` fails any step that leaves 286° ±3°.
+
+### Consequences
+
+- A visible change, if a quiet one, so the release that carries it is a minor.
+- The cool ground does the job the original comment gave it: the warm mark
+  and the amber attention state are the only warm things on a page.
+
+---
+
+## ADR-0008 — Cobalt is our own: OKLCH hue 256°, not Tailwind's blue
+
+**Status:** accepted · 2026-10-25
+**Amends:** ADR-0001 (the hue stays cobalt; the values change)
+
+### Context
+
+ADR-0001 chose cobalt for two reasons: it's semantically inert, and it's
+complementary to larch, so identity and affordance don't compete. The values
+it shipped, `#2563eb` / `#1d4ed8` / `#1e40af` / `#1e3a8a` and `#60a5fa` /
+`#93c5fd` / `#bfdbfe`, are exactly Tailwind's `blue-600…900` and `blue-300…400`,
+and the sequential chart ramp was Tailwind's blues too. That undercut both the
+second reason and DESIGN.md §1's "nothing here should read as a template":
+
+- Tailwind's blue is at OKLCH 263–266°, leaning violet. Larch is ≈68°, so its
+  opposite is ≈248°. The stock values were 15° further from that than they
+  needed to be.
+- It isn't even one hue. Across the ramp the stock steps wander from 251.8°
+  to 265.6°, so hover and pressed shift colour as well as depth.
+- It is the single most recognisable colour in the Tailwind default theme.
+
+### Decision
+
+Every cobalt step, interactive and sequential, sits at **OKLCH hue 256°**, and
+`npm run check` holds it there ±3°. 256° is as near to larch's opposite as sRGB
+allows while keeping cobalt's chroma (≈0.18 at the fill). At 248–252° the gamut
+caps chroma near 0.14–0.16, which reads as steel or ocean blue, and links lose
+some of the "you can act on this" that ADR-0001 chose blue for.
+
+Each step's lightness was **solved for the contrast its predecessor met**, so
+every ratio is within 0.07 of before: fill 5.18:1 under a white label, link
+6.78:1 on white, dark fill 7.07:1 on card. The sequential ramp keeps each
+step's OKLCH lightness and stays monotonic.
+
+### Consequences
+
+- The blue is deeper and calmer than Tailwind's electric violet-blue, and it is
+  one colour from fill to pressed. It still reads unmistakably as a link.
+- A visible change, so the release that carries it is a minor.
+- `--chart-1` is a separately validated categorical slot (ADR-0002) and is
+  unchanged.

package/DESIGN.md

@@ -106,13 +106,18 @@ The part that makes an interface feel built rather than styled.
 - Focus is always visible: 2px `--i-ink` outline, 2px offset. Never remove it.
 - Hover and pressed surfaces on neutral elements come from `--surface-hover` and
   `--surface-active`, not from opacity tricks.
+- A control's own edge — an input, a secondary button — is `--line-control`
+  (≥ 3:1). `--line-strong` is a divider, too faint to tell you a control is there.
+- Native checkboxes, radios and ranges inherit `accent-color: var(--i)` from
+  `tokens.css`; don't restyle them just to recolour them.
 
 ## 5. Type
 
 Three roles, no more:
 
-- **`--sans` (Geist)** — body and headings, both tiers. Tabular figures (`tnum`) on
-  body copy so dates, prices and countdowns align in a column.
+- **`--sans` (Geist)** — body and headings, both tiers. Tabular figures
+  (`font-variant-numeric: tabular-nums`) on body copy so dates, prices and
+  countdowns align in a column.
 - **`--mono` (IBM Plex Mono)** — data that must read *precise*: confirmation codes,
   timestamps, stat numbers, eyebrow labels.
 - **`--display` (Silkscreen)** — marketing tier only. The `A|B` monogram and hero
@@ -130,6 +135,10 @@ for cards, `--radius-lg` for hero surfaces.
 a shadow (`--shadow-1/2/3`). Dark mode does not use borders — surfaces get
 *lighter* with elevation. This is why `--line` can stay nearly invisible in dark.
 
+**Sticky chrome** — a header or toolbar that content scrolls under — is
+`--surface-sticky` with `backdrop-filter: blur(8px)`: 92% of the card in light,
+of the page ground in dark, so it reads as the surface it sits on, not a new layer.
+
 ## 7. Motion
 
 **Content is visible by default. Motion is progressive enhancement layered on top
@@ -193,22 +202,74 @@ is thirty coloured things, and the one that is down disappears among them.
   picture.
 - **Diagrams follow the theme.** On a page they use the tokens like everything
   else. A diagram exported as a standalone file (an SVG, a Mermaid block in a pull
-  request) cannot use `var()`; it takes the **light** theme's values, resolved from
-  this file at build time, never typed in.
+  request) cannot use `var()`; it takes the **light** theme's values — the first
+  argument of each `light-dark()` — resolved from this file at build time, never
+  typed in.
 
 ## 10. Accessibility floor
 
 Non-negotiable in both themes:
 
-- Body text ≥ 4.5:1; large text and UI marks ≥ 3:1.
+- Body text ≥ 4.5:1; large text and UI marks ≥ 3:1. `--slate` is the quietest
+  text step and clears 4.5:1 in both themes; `--n-500` in light does not, so it
+  is never text.
 - Touch targets ≥ 44px on coarse pointers, with a `.touch-hit` opt-out for controls
   whose shape is meaningful (a 22px circular checkbox forced to 44px becomes an
   oval — it expands its hit area instead).
 - Every state carries an icon and a word.
-- Measured ratios sit next to their values in `tokens.css`. Changing a value means
-  re-measuring it.
+- Measured ratios sit next to their values in `tokens.css`, and `npm run check`
+  (run in CI on every pull request) fails if any floor above is missed, if a colour
+  is declared anywhere but once, or if a hex appears outside the token files.
+
+## 11. Themes, and integrating with a Tailwind consumer
+
+### How the theme is chosen
+
+Every colour is one declaration holding both values, `light-dark(<light>, <dark>)`,
+and the browser picks a side from the element's `color-scheme`:
+
+- **No attribute** — `color-scheme: light dark`, so the page follows the OS.
+- **`data-theme="light"` / `"dark"`** — the explicit choice, which wins over the OS.
+
+The pick happens where a colour is *used*, so **`data-theme` works on any element,
+not just `<html>`.** A dark hero band on a light marketing page is
+`<section data-theme="dark">`. Give that element its own
+`background: var(--bg); color: var(--ink)` — backgrounds don't inherit.
+
+Two consequences for code that touches tokens directly:
+
+- **Don't read a token's value with `getPropertyValue`.** It returns the
+  declaration text, `light-dark(#076bd3, #6ba5f3)`, not a colour. To get the
+  colour a chart library needs, resolve it on an element in the right subtree:
+  set `el.style.color = 'var(--chart-1)'` and read `getComputedStyle(el).color`.
+  Re-read it when the theme changes.
+- **Don't wrap a token in `color-mix()` or `light-dark()`.** Nesting is valid CSS,
+  but not every engine has been verified to resolve it. If you need a wash, it's
+  a token (`--*-surface`, `--*-line`, `--surface-sticky`); if it isn't, add it here.
+
+Needs Chrome/Edge 123, Firefox 120, Safari 17.5 or later (all shipped by May 2024).
+An older browser drops every colour token and renders unstyled rather than wrong.
+
+### Build tools that lower `light-dark()`
+
+A CSS pipeline that targets browsers older than that floor rewrites
+`light-dark()` into a fallback. Lightning CSS (inside Next.js, Vite, Parcel)
+turns each token into `var(--lightningcss-light, …) var(--lightningcss-dark, …)`
+and flips those two variables wherever `color-scheme` changes. The tokens
+resolve on `:root`, so the side is fixed there. Page-wide theming still works,
+but **`data-theme` on an inner element stops re-theming that section.**
+
+The fix is to target the same floor the tokens need, which leaves `light-dark()`
+alone. In the consumer's `package.json`:
+
+```json
+"browserslist": ["chrome >= 123", "edge >= 123", "firefox >= 120", "safari >= 17.5"]
+```
+
+Verified with Lightning CSS: older targets lower the tokens; these targets
+pass `light-dark(#076bd3, #6ba5f3)` through untouched.
 
-## 11. Integrating with a Tailwind consumer
+### Tailwind
 
 Tailwind's dark variant keys off a `.dark` class; these tokens key off
 `[data-theme]`. **Both must be set together**, by the same code, in both places
@@ -223,11 +284,11 @@ Setting only the class is a silent, half-broken state: Tailwind utilities flip
 but the tokens do not, and the page renders one theme's tokens under the other
 theme's utilities. Setting only the attribute leaves every `dark:` utility dead.
 
-The reason the attribute is required rather than relying on
-`prefers-color-scheme`: a site with a manual toggle has already *resolved* the
-OS preference into an explicit choice. If the tokens also consulted the media
-query, a user on a dark OS who chose light would get dark tokens under light
-utilities. `[data-theme]` is what makes the choice authoritative.
+The reason the attribute is required rather than leaving the OS to decide: a
+site with a manual toggle has already *resolved* the OS preference into an
+explicit choice. Without the attribute, the tokens would still follow the OS, and
+a user on a dark OS who chose light would get dark tokens under light utilities.
+`[data-theme]` is what makes the choice authoritative.
 
 Import order matters — Tailwind first, then tokens, then the bridge:
 

package/README.md

@@ -15,11 +15,11 @@ The shared design system for every brignano surface — `brignano.io`, `life`,
 
 Three layers, so no colour does two jobs:
 
-- **`--brand-*`** — identity. Larch amber. The trail, the monogram. Never a control.
+- **`--mark`** — identity. Larch amber. Inks the trail and the monogram. Never a control.
 - **`--i-*`** — affordance. Cobalt. Links, buttons, focus, selection. Semantically inert.
-- **`--ok / --warn / --err / --info`** — state. Conventional hues, always with an icon and a word.
+- **`--success / --attention / --danger`** — state. Conventional hues, always with an icon and a word.
 
-Distinctiveness lives in the brand layer; conventionality lives in the control layer.
+Distinctiveness lives in the mark; conventionality lives in the control layer.
 
 ## Consuming it
 
@@ -32,6 +32,11 @@ npm install @brignano/design
 @import '@brignano/design/tokens.chart.css'; /* only if the surface has charts */
 ```
 
+Light and dark follow the OS until something sets `data-theme="light"` or
+`"dark"` — on `<html>` for the whole page, or on any element to theme just that
+part (DESIGN.md §11). Each colour is a single `light-dark()` declaration, so this
+needs a browser from mid-2024 or later.
+
 The tool tier is the default. A marketing surface opts in with
 `class="tier-marketing"` on `<html>`, which unlocks the display face and opens the
 type scale. Colour is identical across tiers.

package/package.json

@@ -1,12 +1,15 @@
 {
   "name": "@brignano/design",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Shared design system for brignano surfaces — colour, type, space, shape, motion.",
   "license": "MIT",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/brignano/design.git"
   },
+  "scripts": {
+    "check": "node scripts/check.mjs"
+  },
   "publishConfig": {
     "access": "public",
     "provenance": true

package/tailwind.css

@@ -7,7 +7,10 @@
 
    `@theme inline` is load-bearing: it makes the generated utilities emit
    `var(--i)` rather than baking a literal at build time, so `bg-interactive`
-   follows the light/dark switch instead of freezing one theme's value. */
+   follows the light/dark switch instead of freezing one theme's value.
+
+   The bare `--radius` key is what drives `rounded`. Tailwind v4 has no
+   `-DEFAULT` suffix; with one, `rounded` silently stayed at 0.25rem. */
 @theme inline {
   --color-ink: var(--ink);
   --color-ink-soft: var(--ink-soft);
@@ -15,26 +18,48 @@
   --color-bg: var(--bg);
   --color-card: var(--card);
   --color-line: var(--line);
+  --color-line-soft: var(--line-soft);
   --color-line-strong: var(--line-strong);
+  --color-line-control: var(--line-control);
   --color-surface-hover: var(--surface-hover);
   --color-surface-active: var(--surface-active);
+  --color-surface-sticky: var(--surface-sticky);
+  --color-on-dark: var(--on-dark);
 
   --color-interactive: var(--i);
   --color-interactive-ink: var(--i-ink);
   --color-interactive-hover: var(--i-hover);
   --color-interactive-pressed: var(--i-pressed);
   --color-interactive-surface: var(--i-surface);
+  --color-interactive-line: var(--i-line);
   --color-on-interactive: var(--on-i);
 
   --color-success: var(--success);
   --color-success-ink: var(--success-ink);
   --color-success-surface: var(--success-surface);
+  --color-success-line: var(--success-line);
   --color-attention: var(--attention);
   --color-attention-ink: var(--attention-ink);
   --color-attention-surface: var(--attention-surface);
+  --color-attention-line: var(--attention-line);
   --color-danger: var(--danger);
   --color-danger-ink: var(--danger-ink);
   --color-danger-surface: var(--danger-surface);
+  --color-danger-line: var(--danger-line);
+  --color-info: var(--info);
+  --color-info-ink: var(--info-ink);
+  --color-info-surface: var(--info-surface);
+  --color-info-line: var(--info-line);
+
+  --color-diff-added: var(--diff-added);
+  --color-diff-added-ink: var(--diff-added-ink);
+  --color-diff-added-surface: var(--diff-added-surface);
+  --color-diff-changed: var(--diff-changed);
+  --color-diff-changed-ink: var(--diff-changed-ink);
+  --color-diff-changed-surface: var(--diff-changed-surface);
+  --color-diff-removed: var(--diff-removed);
+  --color-diff-removed-ink: var(--diff-removed-ink);
+  --color-diff-removed-surface: var(--diff-removed-surface);
 
   --color-mark: var(--mark);
   --color-mark-ink: var(--mark-ink);
@@ -44,7 +69,7 @@
   --font-display: var(--display);
 
   --radius-sm: var(--radius-sm);
-  --radius-DEFAULT: var(--radius);
+  --radius: var(--radius);
   --radius-lg: var(--radius-lg);
 
   --shadow-1: var(--shadow-1);

package/tokens.chart.css

@@ -4,10 +4,10 @@
    WHY THIS IS A SEPARATE FILE FROM THE BRAND ACCENT
    -------------------------------------------------
    A chart's colours do a different job from a brand's colours, so they are
-   not derived from the accent and they are not the status ramp.
+   not derived from the mark and they are not the state hues.
 
-     brand accent (--accent)   identity. One hue. "This is Anthony."
-     status (--forest/rust)    state. RESERVED — never a series colour.
+     mark (--mark)             identity. One hue. "This is Anthony."
+     state (--success/…)       state. RESERVED — never a series colour.
      categorical (this file)   IDENTITY OF A SERIES. Needs 8 hues that a
                                human can tell apart at a glance, including
                                the ~8% of men with a colour-vision
@@ -19,6 +19,7 @@
 
    THESE VALUES ARE VALIDATED, NOT CHOSEN BY EYE
    ----------------------------------------------
+   Values are light-dark(<light>, <dark>), one declaration each.
    Both modes pass every hard gate of the six-check colour formula:
 
      lightness band     PASS  (all 8 inside the mode's band)
@@ -53,14 +54,14 @@
 :root {
   --chart-surface: var(--card);
 
-  --chart-1: #2a78d6; /* blue    */
-  --chart-2: #eb6834; /* orange  */
-  --chart-3: #1baf7a; /* aqua    — relief required (2.74:1) */
-  --chart-4: #eda100; /* yellow  — relief required (2.11:1) */
-  --chart-5: #e87ba4; /* magenta — relief required (2.62:1) */
-  --chart-6: #008300; /* green   */
-  --chart-7: #4a3aa7; /* violet  */
-  --chart-8: #e34948; /* red     */
+  --chart-1: light-dark(#2a78d6, #3987e5); /* blue    */
+  --chart-2: light-dark(#eb6834, #d95926); /* orange  */
+  --chart-3: light-dark(#1baf7a, #199e70); /* aqua    — relief required (2.74:1) */
+  --chart-4: light-dark(#eda100, #c98500); /* yellow  — relief required (2.11:1) */
+  --chart-5: light-dark(#e87ba4, #d55181); /* magenta — relief required (2.62:1) */
+  --chart-6: #008300; /* green — same in both */
+  --chart-7: light-dark(#4a3aa7, #9085e9); /* violet  */
+  --chart-8: light-dark(#e34948, #e66767); /* red     */
 
   /* Everything past slot 8 aggregates here. Deliberately neutral: "Other"
      is not an entity, so it does not earn a hue. */
@@ -79,9 +80,9 @@
    Rules that differ from the categorical palette above:
      - ONE hue. Never a rainbow — a rainbow implies categories where there
        are only degrees.
-     - Lightness must be MONOTONIC. Verified: light L 0.838 -> 0.107
-       descending, dark L 0.015 -> 0.532 ascending, every adjacent step
-       separated by dL >= 0.037.
+     - Lightness must be MONOTONIC. Verified in OKLCH: light L 0.888 ->
+       0.487 descending, dark L 0.380 -> 0.808 ascending, every adjacent
+       step separated by dL >= 0.107.
      - `--seq-0` is NEUTRAL on purpose. Zero contributions is not a small
        amount of the hue, it is the absence of a value — colouring it a pale
        blue would claim data that isn't there.
@@ -91,44 +92,8 @@
    it its own hue would add a meaning the system doesn't need.
    ───────────────────────────────────────────────────────────────────────── */
   --seq-0: var(--line);
-  --seq-1: #c7dcfb;
-  --seq-2: #8ab4f4;
-  --seq-3: #3b82f6;
-  --seq-4: #1d4ed8;
-}
-
-@media (prefers-color-scheme: dark) {
-  :root:not([data-theme='light']) {
-    --chart-1: #3987e5;
-    --chart-2: #d95926;
-    --chart-3: #199e70;
-    --chart-4: #c98500;
-    --chart-5: #d55181;
-    --chart-6: #008300;
-    --chart-7: #9085e9;
-    --chart-8: #e66767;
-
-    --seq-0: var(--line);
-    --seq-1: #1e3a8a;
-    --seq-2: #1d4ed8;
-    --seq-3: #3b82f6;
-    --seq-4: #93c5fd;
-  }
-}
-
-:root[data-theme='dark'] {
-  --chart-1: #3987e5;
-  --chart-2: #d95926;
-  --chart-3: #199e70;
-  --chart-4: #c98500;
-  --chart-5: #d55181;
-  --chart-6: #008300;
-  --chart-7: #9085e9;
-  --chart-8: #e66767;
-
-  --seq-0: var(--line);
-  --seq-1: #1e3a8a;
-  --seq-2: #1d4ed8;
-  --seq-3: #3b82f6;
-  --seq-4: #93c5fd;
+  --seq-1: light-dark(#c6dcfb, #014084);
+  --seq-2: light-dark(#87b5f3, #015cbb);
+  --seq-3: #2885f5;
+  --seq-4: light-dark(#015cbb, #98c3fe);
 }

package/tokens.css

@@ -36,49 +36,107 @@
    1. NEVER hardcode a hex outside this file. A literal survives a theme
       change silently — that is how `life`'s status pills sat light grey in
       dark mode for months.
-   2. Every colour is declared in BOTH theme scopes. CSS cannot share a
-      declaration block between a media query and a plain selector, so the
-      dark list is duplicated on purpose. Edit one, edit the other.
+   2. Every colour is ONE declaration holding both themes:
+      `light-dark(<light>, <dark>)`. There is no dark list to keep in step.
+      The arguments are always concrete colours, never a var() to another
+      theme-dependent token — nested light-dark() is legal CSS, but not
+      every engine has been verified to resolve it. Where that forces a
+      value to repeat (a wash repeats its hue), `npm run check` holds the
+      copies to their source.
    3. Ratios in the comments are MEASURED. Change a value, re-measure it.
 
    See DESIGN.md for the rules that govern use, DECISIONS.md for why.
    ───────────────────────────────────────────────────────────────────────── */
 
+/* ── Themes ─────────────────────────────────────────────────────────────
+   One declaration per colour, light value first: light-dark(<light>, <dark>).
+   The browser picks the side from the element's color-scheme:
+
+     default            follows the OS (light dark below)
+     [data-theme]       the in-app toggle, which must WIN over the OS
+                        — `light` forces light under a dark OS
+
+   Because the pick happens where a colour is USED, not where it's declared,
+   [data-theme] (or color-scheme) on ANY element themes that subtree — a dark
+   hero band on a light page is one attribute. Give that element its own
+   `background: var(--bg)`; it doesn't inherit the page's.
+
+   Dark is selected, not inverted:
+   1. Not pure black. #0d0d0f — pure black behind bright text causes
+      halation and is fatiguing at night, which is when a personal tool
+      actually gets opened.
+   2. Surfaces LIGHTEN with elevation instead of gaining borders.
+   3. Accents lift in luminance rather than shifting hue, and washes carry
+      a higher mix — 12% over #0d0d0f is invisible where it reads on white.
+
+   Ratios are given light / dark. */
 :root {
+  color-scheme: light dark;
+}
+[data-theme='light'] {
   color-scheme: light;
+}
+[data-theme='dark'] {
+  color-scheme: dark;
+}
 
+:root {
   /* ── Neutral ramp ─────────────────────────────────────────────────────
      Twelve steps, up from five. The gap that mattered most: there was no
      hover or pressed background token, so every interactive surface in
      both repos was improvising.
 
-     Deliberately COOL-leaning — a cool grey lets the warm mark and the
-     amber attention state read as warm, instead of muddying into them. */
-  --n-0: #ffffff;
-  --n-25: #fafafa;
-  --n-50: #f3f3f1;
-  --n-100: #ececea; /* hairline */
-  --n-200: #e2e2e0; /* hover surface */
-  --n-300: #cbcbce; /* strong border, pressed surface */
-  --n-400: #a9a9ae;
-  --n-500: #8a8a8f; /* muted label   3.44:1 — large text / UI marks only */
-  --n-600: #6b6b73; /*               5.28:1 */
-  --n-700: #52525b; /* secondary     7.73:1 */
-  --n-800: #33333a;
-  --n-900: #111111; /* primary      18.88:1 */
-
-  /* Semantic aliases. Components use THESE, not the raw steps. */
-  --bg: var(--n-25);
-  --card: var(--n-0);
+     Deliberately COOL — a cool grey lets the warm mark and the amber
+     attention state read as warm, instead of muddying into them.
+
+     ONE TEMPERATURE, top to bottom, both themes: every tinted step sits at
+     OKLCH hue 286° (±3°, `npm run check` holds it). Chroma is a whisper at
+     the ends (~0.0015 at n-25) and peaks in the mid-tones (~0.015 at
+     n-700), where a grey reads most neutral-flat without it. Only pure
+     white (light n-0) is untinted. An earlier ramp mixed warm hairlines
+     (106°) with cool text, so a border and the label beside it disagreed.
+
+     Changing a step: keep its OKLCH lightness, keep the hue, re-run the
+     check. */
+  --n-0: light-dark(#ffffff, #0d0d0f);
+  --n-25: light-dark(#fafafb, #131316);
+  --n-50: light-dark(#f3f3f4, #17171a);
+  --n-100: light-dark(#ececee, #202024); /* hairline */
+  --n-200: light-dark(#e1e1e4, #2a2a2f); /* hover surface */
+  --n-300: light-dark(#cbcbce, #3a3a41); /* strong border, pressed surface */
+  --n-400: light-dark(#a9a9ae, #55555e);
+  --n-500: light-dark(#8a8a8f, #8b8b93); /* 3.44:1 — UI marks only, never text / 5.29:1 */
+  --n-600: light-dark(#6b6b73, #9c9ca4); /* muted label 5.28:1 */
+  --n-700: light-dark(#52525b, #a8a8b0); /* secondary 7.73:1 / 7.58:1 */
+  --n-800: light-dark(#33333a, #d0d0d5);
+  --n-900: light-dark(#111114, #f2f2f4); /* primary 18.85:1 / 16.00:1 */
+
+  /* Semantic aliases. Components use THESE, not the raw steps.
+     Where a role sits on a different step in each theme, the step's two
+     hexes are written out (rule 2) and named in the comment; the check
+     holds them to the ramp. */
+  --bg: light-dark(#fafafb, #0d0d0f); /* n-25 / n-0 */
+  --card: light-dark(#ffffff, #17171a); /* n-0 / n-50 */
   --surface-hover: var(--n-100);
   --surface-active: var(--n-200);
+  /* Sticky chrome — a header or toolbar that content scrolls under, usually
+     with `backdrop-filter: blur()`. 92% of the surface it sits on: the card
+     in light, the page ground in dark, where cards are lighter than the
+     page. A token so consumers never color-mix() one (DESIGN.md §11). */
+  --surface-sticky: light-dark(color-mix(in srgb, #ffffff 92%, transparent), color-mix(in srgb, #0d0d0f 92%, transparent)); /* card / bg */
   --ink: var(--n-900);
   --ink-soft: var(--n-700);
-  --slate: var(--n-500);
+  --slate: light-dark(#6b6b73, #8b8b93); /* n-600 / n-500 — text-safe: eyebrows, axis labels, captions */
   --line: var(--n-100);
   --line-soft: var(--n-50);
-  --line-strong: var(--n-300);
-  --on-dark: var(--n-25);
+  --line-strong: var(--n-300); /* 1.62:1 — decoration, not a boundary */
+  /* The edge that tells you a control is there: inputs, secondary buttons.
+     WCAG 1.4.11 asks 3:1 of a boundary you need to find the control, which
+     --line-strong is nowhere near. Light is n-500 (3.44:1 on card, 3.29:1
+     on bg); dark sits between n-400 and n-500, which the ramp has no step
+     for (3.39:1 on card, 3.68:1 on bg). */
+  --line-control: light-dark(#8a8a8f, #6b6b73);
+  --on-dark: light-dark(#fafafb, #0d0d0f); /* n-25 / n-0 */
 
   /* ── Interactive — cobalt ─────────────────────────────────────────────
      Everything you can act on: links, buttons, focus, selection. Chosen to
@@ -86,21 +144,28 @@
      green and red do — and complementary to the mark hue, so identity and
      affordance never compete for the same attention.
 
-       --i          fill               5.17:1  (white label 5.17:1)
-       --i-ink      link/icon/focus    6.70:1  on #fff
-       --i-hover    hover fill        10.36:1
-       --i-pressed  pressed fill      12.65:1
+     Every step sits at OKLCH hue 256° (`npm run check` holds it), as near
+     to larch's opposite (~248°) as sRGB allows while keeping cobalt's
+     chroma. It is deliberately NOT Tailwind's blue-600 (263°, a touch
+     violet and electric): same affordance, our own colour (ADR-0008).
+
+       --i          fill               5.18:1 / 7.07:1  (label 5.18 / 7.46)
+       --i-ink      link/icon/focus    6.78:1 / 7.07:1
+       --i-hover    hover fill         8.65:1 / 10.50:1 (label)
+       --i-pressed  pressed fill      10.44:1 / 13.32:1 (label)
+
+     In dark, fill and ink converge, and hover/pressed get LIGHTER.
 
      DISABLED IS NEUTRAL, NEVER HUED — a greyed-out control must stop
      signalling "click me". */
-  --i: #2563eb;
-  --i-ink: #1d4ed8;
-  --i-hover: #1e40af;
-  --i-pressed: #1e3a8a;
-  --i-surface: color-mix(in srgb, var(--i) 12%, transparent);
-  --i-line: color-mix(in srgb, var(--i) 32%, transparent);
-  --i-selection: color-mix(in srgb, var(--i) 26%, transparent);
-  --on-i: #ffffff;
+  --i: light-dark(#076bd3, #6ba5f3);
+  --i-ink: light-dark(#0159b5, #6ba5f3);
+  --i-hover: light-dark(#014a97, #98c4ff);
+  --i-pressed: light-dark(#003e82, #c0dbff);
+  --i-surface: light-dark(color-mix(in srgb, #076bd3 12%, transparent), color-mix(in srgb, #6ba5f3 20%, transparent));
+  --i-line: light-dark(color-mix(in srgb, #076bd3 32%, transparent), color-mix(in srgb, #6ba5f3 44%, transparent));
+  --i-selection: light-dark(color-mix(in srgb, #076bd3 26%, transparent), color-mix(in srgb, #6ba5f3 30%, transparent));
+  --on-i: light-dark(#ffffff, #111111);
   --i-disabled-bg: var(--n-200);
   --i-disabled-ink: var(--n-400);
 
@@ -109,31 +174,32 @@
      tiers. Always shipped with an ICON AND A WORD — colour is never the
      only signal.
 
-       --success    settled · confirmed · done · succeeded    6.29:1
-       --attention  now · next · warning · needs you          6.08:1
-       --danger     overdue · failed · invalid                6.10:1
+       --success    settled · confirmed · done · succeeded    6.29:1 / 8.15:1
+       --attention  now · next · warning · needs you          6.08:1 / 8.17:1  (ink)
+       --danger     overdue · failed · invalid                6.10:1 / 6.06:1
 
      `--info` is the interactive hue on purpose: an informational message
      is the same "neutral, no action implied" register as a link.
 
      `-ink` is the text-safe step; the bare token is for marks and fills.
-     `-surface` and `-line` are the wash and its edge. */
-  --success: #2f6b4f;
-  --success-ink: #245740;
-  --attention: #b4741f; /* 3.85:1 — mark/fill only, NOT text */
-  --attention-ink: #8a5714; /* 6.08:1 */
-  --danger: #a4442c;
-  --danger-ink: #8a3722;
+     `-surface` and `-line` are the wash and its edge: 12% / 32% of the hue
+     in light, 20% / 44% in dark. */
+  --success: light-dark(#2f6b4f, #6fbf95);
+  --success-ink: light-dark(#245740, #8fd4ae);
+  --attention: light-dark(#b4741f, #e0a44f); /* 3.85:1 in light — mark/fill only, NOT text */
+  --attention-ink: light-dark(#8a5714, #e0a44f); /* 6.08:1 / 8.17:1 — mark and label converge in dark */
+  --danger: light-dark(#a4442c, #e07a5f);
+  --danger-ink: light-dark(#8a3722, #ec9880);
   --info: var(--i);
   --info-ink: var(--i-ink);
 
-  --success-surface: color-mix(in srgb, var(--success) 12%, transparent);
-  --attention-surface: color-mix(in srgb, var(--attention) 12%, transparent);
-  --danger-surface: color-mix(in srgb, var(--danger) 12%, transparent);
+  --success-surface: light-dark(color-mix(in srgb, #2f6b4f 12%, transparent), color-mix(in srgb, #6fbf95 20%, transparent));
+  --attention-surface: light-dark(color-mix(in srgb, #b4741f 12%, transparent), color-mix(in srgb, #e0a44f 20%, transparent));
+  --danger-surface: light-dark(color-mix(in srgb, #a4442c 12%, transparent), color-mix(in srgb, #e07a5f 20%, transparent));
   --info-surface: var(--i-surface);
-  --success-line: color-mix(in srgb, var(--success) 32%, transparent);
-  --attention-line: color-mix(in srgb, var(--attention) 32%, transparent);
-  --danger-line: color-mix(in srgb, var(--danger) 32%, transparent);
+  --success-line: light-dark(color-mix(in srgb, #2f6b4f 32%, transparent), color-mix(in srgb, #6fbf95 44%, transparent));
+  --attention-line: light-dark(color-mix(in srgb, #b4741f 32%, transparent), color-mix(in srgb, #e0a44f 44%, transparent));
+  --danger-line: light-dark(color-mix(in srgb, #a4442c 32%, transparent), color-mix(in srgb, #e07a5f 44%, transparent));
   --info-line: var(--i-line);
 
   /* ── Diff ─────────────────────────────────────────────────────────────
@@ -144,8 +210,7 @@
        --diff-changed  modified by this change     interactive — informational
        --diff-removed  removed by this change      danger — can lose data
 
-     Always with a symbol and a word (+ added, ~ changed, − removed). Aliased
-     in this block only: these resolve against whichever theme block wins. */
+     Always with a symbol and a word (+ added, ~ changed, − removed). */
   --diff-added: var(--success);
   --diff-added-ink: var(--success-ink);
   --diff-added-surface: var(--success-surface);
@@ -168,21 +233,21 @@
      the attention state are the same warmth, and because --mark never
      appears as a UI surface the two can never be mistaken for each other
      in the same context. */
-  --mark: #b4741f;
-  --mark-ink: #8a5714; /* when the mark carries a label, 6.08:1 */
+  --mark: light-dark(#b4741f, #e0a44f);
+  --mark-ink: light-dark(#8a5714, #e0a44f); /* when the mark carries a label, 6.08:1 / 8.17:1 */
 
   /* ── Legacy aliases ───────────────────────────────────────────────────
      Kept so existing `life` components keep compiling. Do not use in new
      work — reach for the semantic tokens above.
 
-     --larch-deep is declared explicitly in BOTH themes rather than
-     aliased, because "deep" inverts: darker in light, BRIGHTER in dark. An
-     alias to either role silently changes one theme — it moved
-     .pill-active from #f0bd74 to #e0a44f before this was caught. */
+     --larch-deep is written out rather than aliased, because "deep"
+     inverts: darker in light, BRIGHTER in dark. An alias to either role
+     silently changes one theme — it moved .pill-active from #f0bd74 to
+     #e0a44f before this was caught. */
   --forest: var(--success);
   --forest-deep: var(--success-ink);
   --larch: var(--attention);
-  --larch-deep: #8a5714;
+  --larch-deep: light-dark(#8a5714, #f0bd74);
   --rust: var(--danger);
   --rust-deep: var(--danger-ink);
   --gold: var(--slate);
@@ -204,153 +269,36 @@
   --s6: 32px; --s7: 48px; --s8: 64px; --s9: 96px;
 
   /* ── Shape & elevation ────────────────────────────────────────────────
-     In LIGHT these are shadows; in DARK the surface lightens instead. */
+     In LIGHT these are shadows; in DARK the surface lightens instead, and
+     the shadow only has to separate it from a near-black ground.
+
+     light-dark() switches colours, not geometry, and the two themes' blur
+     differs. So shadows 2 and 3 carry one layer per theme, with the other
+     theme's layer transparent — it draws nothing. */
   --radius-sm: 6px;
   --radius: 12px;
   --radius-lg: 18px;
-  --shadow-1: 0 1px 2px rgba(17, 17, 17, 0.04);
-  --shadow-2: 0 2px 8px rgba(17, 17, 17, 0.07);
-  --shadow-3: 0 8px 24px rgba(17, 17, 17, 0.10);
-  --scrim: rgba(17, 17, 17, 0.55);
+  --shadow-1: 0 1px 2px light-dark(rgba(17, 17, 17, 0.04), rgba(0, 0, 0, 0.45));
+  --shadow-2:
+    0 2px 8px light-dark(rgba(17, 17, 17, 0.07), transparent),
+    0 2px 10px light-dark(transparent, rgba(0, 0, 0, 0.55));
+  --shadow-3:
+    0 8px 24px light-dark(rgba(17, 17, 17, 0.10), transparent),
+    0 10px 28px light-dark(transparent, rgba(0, 0, 0, 0.65));
+  --scrim: light-dark(rgba(17, 17, 17, 0.55), rgba(0, 0, 0, 0.68));
   --shadow: var(--shadow-1); /* legacy alias */
 
   /* ── Motion ───────────────────────────────────────────────────────────
      Content is ALWAYS visible by default; motion is enhancement layered on
      top, never the thing that makes content appear. brignano.io shipped a
      homepage whose contact CTA was invisible on 100% of loads because an
-     animation library owned the visible state. See DESIGN.md §6. */
+     animation library owned the visible state. See DESIGN.md §7. */
   --ease: cubic-bezier(0.22, 1, 0.36, 1);
   --dur-fast: 150ms;
   --dur: 250ms;
   --dur-slow: 600ms;
 }
 
-/* ── Dark ───────────────────────────────────────────────────────────────
-   Selected, not inverted:
-   1. Not pure black. #0d0d0f — pure black behind bright text causes
-      halation and is fatiguing at night, which is when a personal tool
-      actually gets opened.
-   2. Surfaces LIGHTEN with elevation instead of gaining borders.
-   3. Accents lift in luminance rather than shifting hue, and washes carry
-      a higher mix — 12% over #0d0d0f is invisible where it reads on white.
-
-   Declared twice: the media query is the default and no-JS fallback;
-   [data-theme] is the in-app toggle and must WIN over the system.
-   `:not([data-theme='light'])` lets the toggle force light under a dark OS. */
-@media (prefers-color-scheme: dark) {
-  :root:not([data-theme='light']) {
-    color-scheme: dark;
-
-    --n-0: #0d0d0f;
-    --n-25: #131316;
-    --n-50: #17171a;
-    --n-100: #202024;
-    --n-200: #2a2a2f;
-    --n-300: #3a3a41;
-    --n-400: #55555e;
-    --n-500: #8b8b93; /* 5.29:1 on card */
-    --n-600: #9c9ca4;
-    --n-700: #a8a8b0; /* 7.58:1 */
-    --n-800: #d0d0d2;
-    --n-900: #f2f2f0; /* 15.96:1 */
-
-    --bg: var(--n-0);
-    --card: var(--n-50);
-    --surface-hover: var(--n-100);
-    --surface-active: var(--n-200);
-    --on-dark: var(--n-0);
-
-    --i: #60a5fa; /* 7.04:1 */
-    --i-ink: #60a5fa;
-    --i-hover: #93c5fd;
-    --i-pressed: #bfdbfe;
-    --i-surface: color-mix(in srgb, var(--i) 20%, transparent);
-    --i-line: color-mix(in srgb, var(--i) 44%, transparent);
-    --i-selection: color-mix(in srgb, var(--i) 30%, transparent);
-    --on-i: #111111;
-
-    --success: #6fbf95;
-    --success-ink: #8fd4ae;
-    --attention: #e0a44f;
-    --attention-ink: #e0a44f; /* 8.17:1 — mark and label converge in dark */
-    --danger: #e07a5f;
-    --danger-ink: #ec9880;
-
-    --success-surface: color-mix(in srgb, var(--success) 20%, transparent);
-    --attention-surface: color-mix(in srgb, var(--attention) 20%, transparent);
-    --danger-surface: color-mix(in srgb, var(--danger) 20%, transparent);
-    --success-line: color-mix(in srgb, var(--success) 44%, transparent);
-    --attention-line: color-mix(in srgb, var(--attention) 44%, transparent);
-    --danger-line: color-mix(in srgb, var(--danger) 44%, transparent);
-
-    --mark: #e0a44f;
-    --mark-ink: #e0a44f;
-
-    --larch-deep: #f0bd74; /* brighter step in dark — see the light block */
-
-    --shadow-1: 0 1px 2px rgba(0, 0, 0, 0.45);
-    --shadow-2: 0 2px 10px rgba(0, 0, 0, 0.55);
-    --shadow-3: 0 10px 28px rgba(0, 0, 0, 0.65);
-    --scrim: rgba(0, 0, 0, 0.68);
-  }
-}
-
-:root[data-theme='dark'] {
-  color-scheme: dark;
-
-  --n-0: #0d0d0f;
-  --n-25: #131316;
-  --n-50: #17171a;
-  --n-100: #202024;
-  --n-200: #2a2a2f;
-  --n-300: #3a3a41;
-  --n-400: #55555e;
-  --n-500: #8b8b93;
-  --n-600: #9c9ca4;
-  --n-700: #a8a8b0;
-  --n-800: #d0d0d2;
-  --n-900: #f2f2f0;
-
-  --bg: var(--n-0);
-  --card: var(--n-50);
-  --surface-hover: var(--n-100);
-  --surface-active: var(--n-200);
-  --on-dark: var(--n-0);
-
-  --i: #60a5fa;
-  --i-ink: #60a5fa;
-  --i-hover: #93c5fd;
-  --i-pressed: #bfdbfe;
-  --i-surface: color-mix(in srgb, var(--i) 20%, transparent);
-  --i-line: color-mix(in srgb, var(--i) 44%, transparent);
-  --i-selection: color-mix(in srgb, var(--i) 30%, transparent);
-  --on-i: #111111;
-
-  --success: #6fbf95;
-  --success-ink: #8fd4ae;
-  --attention: #e0a44f;
-  --attention-ink: #e0a44f;
-  --danger: #e07a5f;
-  --danger-ink: #ec9880;
-
-  --success-surface: color-mix(in srgb, var(--success) 20%, transparent);
-  --attention-surface: color-mix(in srgb, var(--attention) 20%, transparent);
-  --danger-surface: color-mix(in srgb, var(--danger) 20%, transparent);
-  --success-line: color-mix(in srgb, var(--success) 44%, transparent);
-  --attention-line: color-mix(in srgb, var(--attention) 44%, transparent);
-  --danger-line: color-mix(in srgb, var(--danger) 44%, transparent);
-
-  --mark: #e0a44f;
-  --mark-ink: #e0a44f;
-
-  --larch-deep: #f0bd74;
-
-  --shadow-1: 0 1px 2px rgba(0, 0, 0, 0.45);
-  --shadow-2: 0 2px 10px rgba(0, 0, 0, 0.55);
-  --shadow-3: 0 10px 28px rgba(0, 0, 0, 0.65);
-  --scrim: rgba(0, 0, 0, 0.68);
-}
-
 :root {
   /* Tool-tier scale — compact, because scanning beats reading.
      Declared BEFORE the marketing tier on purpose: `:root` and
@@ -381,7 +329,7 @@
   --text-xl: 1.5rem;
   --text-2xl: 2rem;
   --text-3xl: 2.75rem;
-  --text-4xl: clamp(2.75rem, 6vw, 4rem);
+  --text-4xl: clamp(2.75rem, 1rem + 4.5vw, 4rem); /* rem term keeps it zoomable (WCAG 1.4.4) */
   --section-gap: var(--s9);
   --measure: 68ch;
 }
@@ -390,6 +338,12 @@
   background: var(--i-selection);
 }
 
+/* Native checkboxes, radios, range and progress take the control hue
+   instead of the browser's own blue. */
+:root {
+  accent-color: var(--i);
+}
+
 /* Ships here so no surface can forget it. */
 @media (prefers-reduced-motion: reduce) {
   *,