@ponchia/ui 0.5.0 → 0.6.0

package/docs/architecture.md

@@ -61,7 +61,7 @@ on top of the CSS, none of which require a framework commitment**:
   not in three places (the two CSS dark blocks are now identical by
   construction), resolving the duplication ADR-0003 flagged. The CSS-only
   presets (density / contrast / OLED) stay hand-authored below a marker and are
-  preserved across regeneration. `scripts/check-tokens.mjs` fails CI if
+  preserved across regeneration. `scripts/check-fresh.mjs` fails CI if
   `css/tokens.css` drifts from the model.
 - **classes/** — `cls` is the flat registry; recipes only emit from it;
   `scripts/check-classes.mjs` enforces a bidirectional match with the
@@ -79,6 +79,51 @@ on top of the CSS, none of which require a framework commitment**:
 - **react/** / **solid/** / **qwik/** — optional lifecycle adapters over `behaviors/`.
   They do not define markup, own state, or fork behavior logic; they only run
   the vanilla initializers on mount and cleanup on unmount/dispose.
+- **`css/analytical.css` — the analytical roll-up.** This convenience file
+  `@import`s exactly **seven** analytical-figure leaves: `annotations`,
+  `legend`, `marks`, `connectors`, `spotlight`, `crosshair`, and `selection`.
+  The adjacent opt-in leaves — `sources`, `state`, `generated`, `workbench`,
+  and `command` — are report/tooling/trust surfaces that are intentionally
+  **not** part of the analytical roll-up and must be imported individually.
+  Importing `analytical.css` does not pull in any of those five.
+- **Root export (`.`) is CSS-only.** `exports["."]` resolves to the CSS
+  bundle (`dist/bronto.css`). It is a CSS side-effect import for CSS-aware
+  bundlers (`@import '@ponchia/ui'` in CSS, or a side-effect
+  `import '@ponchia/ui'` in Vite/Astro/SvelteKit). There is no runtime JS at
+  the package root — Node/runtime JS imports of `.` are not supported. All JS
+  entrypoints are explicit subpaths (`/behaviors`, `/classes`, `/tokens`,
+  `/glyphs`, `/react`, `/solid`, `/qwik`, `/skins`, `/charts`). This is a
+  permanent, intentional contract.
+
+## Repository layout
+
+The repo root mixes five kinds of directory that look alike but follow very
+different rules. Two distinctions matter most: several are **path-frozen
+published subpaths** — the directory name _is_ the public import specifier
+(`@ponchia/ui/react` resolves to `./react/`), so they cannot be moved or
+renamed — and several are **generated** and must never be hand-edited (a
+generator overwrites them and a drift gate fails CI).
+
+| Path | Kind | Edit here? | Notes |
+| --- | --- | --- | --- |
+| `css/` | source | yes | The framework. Hand-authored `@layer bronto` CSS. (`css/tokens.css` palette blocks and `css/generated.css` are generated — see below.) |
+| `tokens/index.js` | source | yes | The single source of truth for token **values** (`cssVars`). |
+| `classes/index.js`, `behaviors/`, `annotations/`, `connectors/`, `react/`, `solid/`, `qwik/`, `glyphs/`, `shiki/` | source · published-subpath (path-frozen) | yes — but **do not move** | Authored ESM shipped as-is; the dir name is the public import path. The `.d.ts` beside them are generated/drift-checked: `connectors`/`annotations`/`react`/`solid`/`qwik` are emitted from JSDoc by `tsc` (`npm run dts:emit`), `classes`/`tokens`/`glyphs` from the runtime; only `behaviors/index.d.ts` is still hand-maintained (its barrel + destructured-param shape emit poorly), guarded by `check-behaviors`. |
+| `dist/` | generated | no | Build of `css/` (`npm run dist:build`); byte-checked by `check:dist`. |
+| `tokens/index.json`, `tokens/resolved.json`, `tokens/tokens.dtcg.json`, `tokens/charts.json`, `classes/index.d.ts`, `tokens/index.d.ts`, `tokens/{skins,charts}.d.ts`, `glyphs/glyphs.d.ts`, `classes/vscode.css-custom-data.json`, `docs/reference.md` | generated | no | Committed build artifacts; regenerate with `npm run prepack`, never hand-edit. Drift-checked in `npm run check`. |
+| `fonts/` | vendored | — | The Doto webfont (woff2) + its OFL license. |
+| `scripts/` | tooling | yes | `gen-*` regenerate artifacts, `check-*` are the drift/contract gates wired into `npm run check`, plus `build-dist`, `serve`, `size-report`. |
+| `docs/` | source (mostly) | yes | Hand-authored docs + ADRs; the curated subset in `package.json` `files` ships in the tarball. `docs/reference.md` is generated. |
+| `demo/`, `test/`, `examples/` | fixtures | yes | The self-driving demo/showcase, the unit + Playwright e2e suite, and consumer example apps built against the packed tarball. |
+| `.github/`, `*.config.mjs`, `.prettierrc`, `.stylelintrc.json`, `tsconfig.json`, `.editorconfig` | config | yes | CI workflows and tool config. |
+| `package.json`, `llms.txt`, `CHANGELOG.md`, `MIGRATIONS.json`, `README.md`, `CONTRIBUTING.md`, `ROADMAP.md`, `LICENSE` | meta | yes | Manifest, the agent entrypoint, the curated changelog, the rename map, and project docs. |
+
+The **path-frozen** dirs are the cost of zero-build, path-stable publishing:
+`files` map 1:1 to published paths and the consumer's own bundler tree-shakes
+the ESM, so there is no `src/` indirection (and no JS bundler — see the
+distribution decision below). **Generated** files are regenerated from their
+source and policed by a drift gate — edit the source, run the generator, commit
+the result.
 
 ## Drift control
 
@@ -89,12 +134,11 @@ gating" below), so a version that fails any invariant never reaches npm.
 | Invariant                                       | Enforced by         |
 | ----------------------------------------------- | ------------------- |
 | exports / import graph / `files` consistent     | `check-exports.mjs` |
-| `tokens.css` ⇄ `tokens/index.js` ⇄ `.json`      | `check-tokens.mjs`  |
+| pure generated mirrors fresh — `tokens.css`/`index.json`, `dtcg.json`, `resolved.json`, `classes`/`tokens` `.d.ts`, `reference.md`, vscode data — each byte-equal to its generator (registry: `scripts/lib/artifacts.mjs`) | `check-fresh.mjs` |
 | `classes` `cls` ⇄ `.ui-*` selectors             | `check-classes.mjs` |
-| `classes`/`tokens` `.d.ts` ⇄ JS runtime (exact) | `check-dts.mjs`     |
-| `annotations`/`connectors` hand-written `.d.ts` ⇄ exports | `check-helpers-dts.mjs` |
+| `connectors`/`annotations`/`react`/`solid`/`qwik` `.d.ts` (+ maps) == fresh `tsc` emit of their JSDoc | `check-dts-emit.mjs` |
+| `behaviors/index.d.ts` ⇄ `behaviors/*` exports (the one hand-maintained leaf `.d.ts`) | `check-behaviors.mjs` |
 | legend swatch colours ⊆ `charts.js` · opt-in   | `check-legend.mjs`  |
-| `tokens.dtcg.json` ⇄ token model                | `check-dtcg.mjs`    |
 | color tokens tiered · no raw chromatic color in components | `check-color-policy.mjs` |
 | `css/skins.css` ⇄ `tokens/skins.js` · colorways opt-in | `check-skins.mjs` |
 | every shipped colorway accent meets its WCAG floor | `check-contrast.mjs` |
@@ -116,7 +160,7 @@ payload contract, raised only intentionally with a CHANGELOG note.
 `test/types.test-d.ts`, whose `@ts-expect-error`s would fail to compile
 if the generated literal `cls`/token types stopped rejecting typos —
 so the *value* of the generated `.d.ts` is itself gated, not just their
-freshness (`check-dts`).
+freshness (`check-fresh`).
 
 ## Release gating
 

package/docs/contrast.md

@@ -40,51 +40,57 @@ Overall: **all contractual pairings meet their floor ✅**.
 
 | Foreground | Background | Role | Held to | Ratio | APCA _(advisory)_ | Verdict |
 | --- | --- | --- | --- | --- | --- | --- |
-| `--text` | `--bg` | Body text on page background | AA text (4.5:1) | 17.98:1 | Lc 99 | ✅ pass |
-| `--text` | `--surface` | Body text on a card/panel | AA text (4.5:1) | 19.80:1 | Lc 106 | ✅ pass |
-| `--text` | `--surface-muted` | Body text on a muted panel | AA text (4.5:1) | 16.74:1 | Lc 94 | ✅ pass |
-| `--text-soft` | `--bg` | Secondary text on page background | AA text (4.5:1) | 11.16:1 | Lc 91 | ✅ pass |
-| `--text-soft` | `--surface` | Secondary text on a card | AA text (4.5:1) | 12.29:1 | Lc 98 | ✅ pass |
-| `--text-soft` | `--surface-muted` | Secondary text on a muted panel | AA text (4.5:1) | 10.39:1 | Lc 87 | ✅ pass |
-| `--text-dim` | `--bg` | Dim/meta text on page background | AA text (4.5:1) | 5.09:1 | Lc 71 | ✅ pass |
-| `--text-dim` | `--surface` | Dim/meta text on a card | AA text (4.5:1) | 5.60:1 | Lc 78 | ✅ pass |
-| `--text-dim` | `--surface-muted` | Dim/meta text on a muted panel | AA text (4.5:1) | 4.74:1 | Lc 67 | ✅ pass |
-| `--accent-text` | `--bg` | Accent text on page background | AA text (4.5:1) | 6.32:1 | Lc 75 | ✅ pass |
-| `--accent-text` | `--surface` | Accent text on a card | AA text (4.5:1) | 6.96:1 | Lc 82 | ✅ pass |
-| `--button-text` | `--accent` | Label on the primary button | AA text (4.5:1) | 5.18:1 | Lc 79 | ✅ pass |
-| `--focus-ring` | `--bg` | Focus ring vs page background | UI / large (3:1) | 4.71:1 | Lc 67 | ✅ pass |
-| `--focus-ring` | `--surface` | Focus ring vs a card | UI / large (3:1) | 5.18:1 | Lc 73 | ✅ pass |
-| `--accent` | `--bg` | Accent fill vs page background | UI / large (3:1) | 4.71:1 | Lc 67 | ✅ pass |
-| `--success` | `--surface` | Success indicator vs a card | UI / large (3:1) | 5.04:1 | Lc 75 | ✅ pass |
-| `--warning` | `--surface` | Warning indicator vs a card | UI / large (3:1) | 5.60:1 | Lc 78 | ✅ pass |
-| `--danger` | `--surface` | Danger indicator vs a card | UI / large (3:1) | 6.21:1 | Lc 79 | ✅ pass |
-| `--info` | `--surface` | Info indicator vs a card | UI / large (3:1) | 5.77:1 | Lc 78 | ✅ pass |
-| `--line-strong` | `--surface` | Strong hairline vs a card | Decorative (1.4.11-exempt) | 2.39:1 | Lc 47 | ℹ️ not gated |
+| `--text` | `--bg` | Body text on page background | AA text (4.5:1) | 17.98:1 | Lc 99.2 | ✅ pass |
+| `--text` | `--surface` | Body text on a card/panel | AA text (4.5:1) | 19.80:1 | Lc 105.8 | ✅ pass |
+| `--text` | `--surface-muted` | Body text on a muted panel | AA text (4.5:1) | 16.74:1 | Lc 94.5 | ✅ pass |
+| `--text-soft` | `--bg` | Secondary text on page background | AA text (4.5:1) | 11.16:1 | Lc 91.4 | ✅ pass |
+| `--text-soft` | `--surface` | Secondary text on a card | AA text (4.5:1) | 12.29:1 | Lc 98.1 | ✅ pass |
+| `--text-soft` | `--surface-muted` | Secondary text on a muted panel | AA text (4.5:1) | 10.39:1 | Lc 86.7 | ✅ pass |
+| `--text-dim` | `--bg` | Dim/meta text on page background | AA text (4.5:1) | 5.09:1 | Lc 71.4 | ✅ pass |
+| `--text-dim` | `--surface` | Dim/meta text on a card | AA text (4.5:1) | 5.60:1 | Lc 78.0 | ✅ pass |
+| `--text-dim` | `--surface-muted` | Dim/meta text on a muted panel | AA text (4.5:1) | 4.74:1 | Lc 66.7 | ✅ pass |
+| `--accent-text` | `--bg` | Accent text on page background | AA text (4.5:1) | 6.32:1 | Lc 75.4 | ✅ pass |
+| `--accent-text` | `--surface` | Accent text on a card | AA text (4.5:1) | 6.96:1 | Lc 82.1 | ✅ pass |
+| `--accent-text` | `--accent-soft` | Accent text on an accent tint | Advisory (translucent tint — not gated) | 5.91:1 | Lc 71.0 | ℹ️ not gated |
+| `--accent-text` | `--bg-accent` | Accent text on an accent-tinted surface | Advisory (translucent tint — not gated) | 6.31:1 | Lc 75.3 | ℹ️ not gated |
+| `--button-text` | `--accent` | Label on the primary button | AA text (4.5:1) | 5.18:1 | Lc 78.9 | ✅ pass |
+| `--on-accent` | `--accent` | Ink on an accent fill | AA text (4.5:1) | 5.18:1 | Lc 78.9 | ✅ pass |
+| `--focus-ring` | `--bg` | Focus ring vs page background | UI / large (3:1) | 4.71:1 | Lc 66.8 | ✅ pass |
+| `--focus-ring` | `--surface` | Focus ring vs a card | UI / large (3:1) | 5.18:1 | Lc 73.5 | ✅ pass |
+| `--accent` | `--bg` | Accent fill vs page background | UI / large (3:1) | 4.71:1 | Lc 66.8 | ✅ pass |
+| `--success` | `--surface` | Success indicator vs a card | UI / large (3:1) | 5.04:1 | Lc 74.6 | ✅ pass |
+| `--warning` | `--surface` | Warning indicator vs a card | UI / large (3:1) | 5.60:1 | Lc 77.8 | ✅ pass |
+| `--danger` | `--surface` | Danger indicator vs a card | UI / large (3:1) | 6.21:1 | Lc 78.9 | ✅ pass |
+| `--info` | `--surface` | Info indicator vs a card | UI / large (3:1) | 5.77:1 | Lc 78.3 | ✅ pass |
+| `--line-strong` | `--surface` | Strong hairline vs a card | Decorative (1.4.11-exempt) | 2.39:1 | Lc 47.1 | ℹ️ not gated |
 
 ## Dark theme
 
 | Foreground | Background | Role | Held to | Ratio | APCA _(advisory)_ | Verdict |
 | --- | --- | --- | --- | --- | --- | --- |
-| `--text` | `--bg` | Body text on page background | AA text (4.5:1) | 15.01:1 | Lc 91 | ✅ pass |
-| `--text` | `--surface` | Body text on a card/panel | AA text (4.5:1) | 13.65:1 | Lc 90 | ✅ pass |
-| `--text` | `--surface-muted` | Body text on a muted panel | AA text (4.5:1) | 12.44:1 | Lc 89 | ✅ pass |
-| `--text-soft` | `--bg` | Secondary text on page background | AA text (4.5:1) | 11.20:1 | Lc 73 | ✅ pass |
-| `--text-soft` | `--surface` | Secondary text on a card | AA text (4.5:1) | 10.19:1 | Lc 72 | ✅ pass |
-| `--text-soft` | `--surface-muted` | Secondary text on a muted panel | AA text (4.5:1) | 9.28:1 | Lc 71 | ✅ pass |
-| `--text-dim` | `--bg` | Dim/meta text on page background | AA text (4.5:1) | 7.16:1 | Lc 50 | ✅ pass |
-| `--text-dim` | `--surface` | Dim/meta text on a card | AA text (4.5:1) | 6.52:1 | Lc 49 | ✅ pass |
-| `--text-dim` | `--surface-muted` | Dim/meta text on a muted panel | AA text (4.5:1) | 5.94:1 | Lc 48 | ✅ pass |
-| `--accent-text` | `--bg` | Accent text on page background | AA text (4.5:1) | 6.14:1 | Lc 45 | ✅ pass |
-| `--accent-text` | `--surface` | Accent text on a card | AA text (4.5:1) | 5.58:1 | Lc 44 | ✅ pass |
-| `--button-text` | `--accent` | Label on the primary button | AA text (4.5:1) | 5.95:1 | Lc 43 | ✅ pass |
-| `--focus-ring` | `--bg` | Focus ring vs page background | UI / large (3:1) | 5.31:1 | Lc 40 | ✅ pass |
-| `--focus-ring` | `--surface` | Focus ring vs a card | UI / large (3:1) | 4.83:1 | Lc 39 | ✅ pass |
-| `--accent` | `--bg` | Accent fill vs page background | UI / large (3:1) | 5.31:1 | Lc 40 | ✅ pass |
-| `--success` | `--surface` | Success indicator vs a card | UI / large (3:1) | 7.58:1 | Lc 57 | ✅ pass |
-| `--warning` | `--surface` | Warning indicator vs a card | UI / large (3:1) | 9.29:1 | Lc 67 | ✅ pass |
-| `--danger` | `--surface` | Danger indicator vs a card | UI / large (3:1) | 5.23:1 | Lc 42 | ✅ pass |
-| `--info` | `--surface` | Info indicator vs a card | UI / large (3:1) | 7.33:1 | Lc 55 | ✅ pass |
-| `--line-strong` | `--surface` | Strong hairline vs a card | Decorative (1.4.11-exempt) | 2.29:1 | Lc 15 | ℹ️ not gated |
+| `--text` | `--bg` | Body text on page background | AA text (4.5:1) | 15.01:1 | Lc 91.1 | ✅ pass |
+| `--text` | `--surface` | Body text on a card/panel | AA text (4.5:1) | 13.65:1 | Lc 90.1 | ✅ pass |
+| `--text` | `--surface-muted` | Body text on a muted panel | AA text (4.5:1) | 12.44:1 | Lc 88.9 | ✅ pass |
+| `--text-soft` | `--bg` | Secondary text on page background | AA text (4.5:1) | 11.20:1 | Lc 72.7 | ✅ pass |
+| `--text-soft` | `--surface` | Secondary text on a card | AA text (4.5:1) | 10.19:1 | Lc 71.7 | ✅ pass |
+| `--text-soft` | `--surface-muted` | Secondary text on a muted panel | AA text (4.5:1) | 9.28:1 | Lc 70.6 | ✅ pass |
+| `--text-dim` | `--bg` | Dim/meta text on page background | AA text (4.5:1) | 7.16:1 | Lc 50.3 | ✅ pass |
+| `--text-dim` | `--surface` | Dim/meta text on a card | AA text (4.5:1) | 6.52:1 | Lc 49.3 | ✅ pass |
+| `--text-dim` | `--surface-muted` | Dim/meta text on a muted panel | AA text (4.5:1) | 5.94:1 | Lc 48.1 | ✅ pass |
+| `--accent-text` | `--bg` | Accent text on page background | AA text (4.5:1) | 6.14:1 | Lc 44.9 | ✅ pass |
+| `--accent-text` | `--surface` | Accent text on a card | AA text (4.5:1) | 5.58:1 | Lc 43.9 | ✅ pass |
+| `--accent-text` | `--accent-soft` | Accent text on an accent tint | Advisory (translucent tint — not gated) | 2.53:1 | Lc 43.8 | ℹ️ not gated |
+| `--accent-text` | `--bg-accent` | Accent text on an accent-tinted surface | Advisory (translucent tint — not gated) | 2.75:1 | Lc 49.1 | ℹ️ not gated |
+| `--button-text` | `--accent` | Label on the primary button | AA text (4.5:1) | 5.95:1 | Lc 42.9 | ✅ pass |
+| `--on-accent` | `--accent` | Ink on an accent fill | AA text (4.5:1) | 5.95:1 | Lc 42.9 | ✅ pass |
+| `--focus-ring` | `--bg` | Focus ring vs page background | UI / large (3:1) | 5.31:1 | Lc 40.0 | ✅ pass |
+| `--focus-ring` | `--surface` | Focus ring vs a card | UI / large (3:1) | 4.83:1 | Lc 39.0 | ✅ pass |
+| `--accent` | `--bg` | Accent fill vs page background | UI / large (3:1) | 5.31:1 | Lc 40.0 | ✅ pass |
+| `--success` | `--surface` | Success indicator vs a card | UI / large (3:1) | 7.58:1 | Lc 56.6 | ✅ pass |
+| `--warning` | `--surface` | Warning indicator vs a card | UI / large (3:1) | 9.29:1 | Lc 66.6 | ✅ pass |
+| `--danger` | `--surface` | Danger indicator vs a card | UI / large (3:1) | 5.23:1 | Lc 41.5 | ✅ pass |
+| `--info` | `--surface` | Info indicator vs a card | UI / large (3:1) | 7.33:1 | Lc 54.8 | ✅ pass |
+| `--line-strong` | `--surface` | Strong hairline vs a card | Decorative (1.4.11-exempt) | 2.29:1 | Lc 14.5 | ℹ️ not gated |
 
 ## Display colorways (skins)
 
@@ -101,67 +107,85 @@ palette untouched). Accents are authored in OKLCH; `--accent-text` is the
 
 | Foreground | Background | Role | Held to | Ratio | APCA _(advisory)_ | Verdict |
 | --- | --- | --- | --- | --- | --- | --- |
-| `--accent-text` | `--bg` | Accent text on page background | AA text (4.5:1) | 6.75:1 | Lc 79 | ✅ pass |
-| `--accent-text` | `--surface` | Accent text on a card | AA text (4.5:1) | 7.44:1 | Lc 86 | ✅ pass |
-| `--button-text` | `--accent` | Label on the primary button | AA text (4.5:1) | 5.66:1 | Lc 83 | ✅ pass |
-| `--focus-ring` | `--bg` | Focus ring vs page background | UI / large (3:1) | 5.14:1 | Lc 71 | ✅ pass |
-| `--focus-ring` | `--surface` | Focus ring vs a card | UI / large (3:1) | 5.66:1 | Lc 78 | ✅ pass |
-| `--accent` | `--bg` | Accent fill vs page background | UI / large (3:1) | 5.14:1 | Lc 71 | ✅ pass |
+| `--accent-text` | `--bg` | Accent text on page background | AA text (4.5:1) | 6.75:1 | Lc 78.9 | ✅ pass |
+| `--accent-text` | `--surface` | Accent text on a card | AA text (4.5:1) | 7.44:1 | Lc 85.6 | ✅ pass |
+| `--accent-text` | `--accent-soft` | Accent text on an accent tint | Advisory (translucent tint — not gated) | 6.31:1 | Lc 74.5 | ℹ️ not gated |
+| `--accent-text` | `--bg-accent` | Accent text on an accent-tinted surface | Advisory (translucent tint — not gated) | 6.74:1 | Lc 78.8 | ℹ️ not gated |
+| `--button-text` | `--accent` | Label on the primary button | AA text (4.5:1) | 5.66:1 | Lc 83.3 | ✅ pass |
+| `--on-accent` | `--accent` | Ink on an accent fill | AA text (4.5:1) | 5.66:1 | Lc 83.3 | ✅ pass |
+| `--focus-ring` | `--bg` | Focus ring vs page background | UI / large (3:1) | 5.14:1 | Lc 71.4 | ✅ pass |
+| `--focus-ring` | `--surface` | Focus ring vs a card | UI / large (3:1) | 5.66:1 | Lc 78.0 | ✅ pass |
+| `--accent` | `--bg` | Accent fill vs page background | UI / large (3:1) | 5.14:1 | Lc 71.4 | ✅ pass |
 
 ### Amber CRT — dark
 
 | Foreground | Background | Role | Held to | Ratio | APCA _(advisory)_ | Verdict |
 | --- | --- | --- | --- | --- | --- | --- |
-| `--accent-text` | `--bg` | Accent text on page background | AA text (4.5:1) | 11.57:1 | Lc 75 | ✅ pass |
-| `--accent-text` | `--surface` | Accent text on a card | AA text (4.5:1) | 10.52:1 | Lc 74 | ✅ pass |
-| `--button-text` | `--accent` | Label on the primary button | AA text (4.5:1) | 11.88:1 | Lc 72 | ✅ pass |
-| `--focus-ring` | `--bg` | Focus ring vs page background | UI / large (3:1) | 10.60:1 | Lc 70 | ✅ pass |
-| `--focus-ring` | `--surface` | Focus ring vs a card | UI / large (3:1) | 9.64:1 | Lc 69 | ✅ pass |
-| `--accent` | `--bg` | Accent fill vs page background | UI / large (3:1) | 10.60:1 | Lc 70 | ✅ pass |
+| `--accent-text` | `--bg` | Accent text on page background | AA text (4.5:1) | 11.57:1 | Lc 74.8 | ✅ pass |
+| `--accent-text` | `--surface` | Accent text on a card | AA text (4.5:1) | 10.52:1 | Lc 73.8 | ✅ pass |
+| `--accent-text` | `--accent-soft` | Accent text on an accent tint | Advisory (translucent tint — not gated) | 1.34:1 | Lc 15.1 | ℹ️ not gated |
+| `--accent-text` | `--bg-accent` | Accent text on an accent-tinted surface | Advisory (translucent tint — not gated) | 1.46:1 | Lc 20.3 | ℹ️ not gated |
+| `--button-text` | `--accent` | Label on the primary button | AA text (4.5:1) | 11.88:1 | Lc 71.6 | ✅ pass |
+| `--on-accent` | `--accent` | Ink on an accent fill | AA text (4.5:1) | 11.88:1 | Lc 71.6 | ✅ pass |
+| `--focus-ring` | `--bg` | Focus ring vs page background | UI / large (3:1) | 10.60:1 | Lc 69.9 | ✅ pass |
+| `--focus-ring` | `--surface` | Focus ring vs a card | UI / large (3:1) | 9.64:1 | Lc 68.9 | ✅ pass |
+| `--accent` | `--bg` | Accent fill vs page background | UI / large (3:1) | 10.60:1 | Lc 69.9 | ✅ pass |
 
 ### E-ink — light
 
 | Foreground | Background | Role | Held to | Ratio | APCA _(advisory)_ | Verdict |
 | --- | --- | --- | --- | --- | --- | --- |
-| `--accent-text` | `--bg` | Accent text on page background | AA text (4.5:1) | 12.23:1 | Lc 93 | ✅ pass |
-| `--accent-text` | `--surface` | Accent text on a card | AA text (4.5:1) | 13.47:1 | Lc 100 | ✅ pass |
-| `--button-text` | `--accent` | Label on the primary button | AA text (4.5:1) | 11.74:1 | Lc 101 | ✅ pass |
-| `--focus-ring` | `--bg` | Focus ring vs page background | UI / large (3:1) | 10.66:1 | Lc 90 | ✅ pass |
-| `--focus-ring` | `--surface` | Focus ring vs a card | UI / large (3:1) | 11.74:1 | Lc 97 | ✅ pass |
-| `--accent` | `--bg` | Accent fill vs page background | UI / large (3:1) | 10.66:1 | Lc 90 | ✅ pass |
+| `--accent-text` | `--bg` | Accent text on page background | AA text (4.5:1) | 12.23:1 | Lc 93.3 | ✅ pass |
+| `--accent-text` | `--surface` | Accent text on a card | AA text (4.5:1) | 13.47:1 | Lc 99.9 | ✅ pass |
+| `--accent-text` | `--accent-soft` | Accent text on an accent tint | Advisory (translucent tint — not gated) | 11.43:1 | Lc 88.8 | ℹ️ not gated |
+| `--accent-text` | `--bg-accent` | Accent text on an accent-tinted surface | Advisory (translucent tint — not gated) | 12.22:1 | Lc 93.2 | ℹ️ not gated |
+| `--button-text` | `--accent` | Label on the primary button | AA text (4.5:1) | 11.74:1 | Lc 100.6 | ✅ pass |
+| `--on-accent` | `--accent` | Ink on an accent fill | AA text (4.5:1) | 11.74:1 | Lc 100.6 | ✅ pass |
+| `--focus-ring` | `--bg` | Focus ring vs page background | UI / large (3:1) | 10.66:1 | Lc 90.4 | ✅ pass |
+| `--focus-ring` | `--surface` | Focus ring vs a card | UI / large (3:1) | 11.74:1 | Lc 97.0 | ✅ pass |
+| `--accent` | `--bg` | Accent fill vs page background | UI / large (3:1) | 10.66:1 | Lc 90.4 | ✅ pass |
 
 ### E-ink — dark
 
 | Foreground | Background | Role | Held to | Ratio | APCA _(advisory)_ | Verdict |
 | --- | --- | --- | --- | --- | --- | --- |
-| `--accent-text` | `--bg` | Accent text on page background | AA text (4.5:1) | 12.47:1 | Lc 79 | ✅ pass |
-| `--accent-text` | `--surface` | Accent text on a card | AA text (4.5:1) | 11.35:1 | Lc 78 | ✅ pass |
-| `--button-text` | `--accent` | Label on the primary button | AA text (4.5:1) | 12.86:1 | Lc 76 | ✅ pass |
-| `--focus-ring` | `--bg` | Focus ring vs page background | UI / large (3:1) | 11.48:1 | Lc 74 | ✅ pass |
-| `--focus-ring` | `--surface` | Focus ring vs a card | UI / large (3:1) | 10.44:1 | Lc 73 | ✅ pass |
-| `--accent` | `--bg` | Accent fill vs page background | UI / large (3:1) | 11.48:1 | Lc 74 | ✅ pass |
+| `--accent-text` | `--bg` | Accent text on page background | AA text (4.5:1) | 12.47:1 | Lc 79.1 | ✅ pass |
+| `--accent-text` | `--surface` | Accent text on a card | AA text (4.5:1) | 11.35:1 | Lc 78.1 | ✅ pass |
+| `--accent-text` | `--accent-soft` | Accent text on an accent tint | Advisory (translucent tint — not gated) | 1.25:1 | Lc 11.0 | ℹ️ not gated |
+| `--accent-text` | `--bg-accent` | Accent text on an accent-tinted surface | Advisory (translucent tint — not gated) | 1.35:1 | Lc 16.3 | ℹ️ not gated |
+| `--button-text` | `--accent` | Label on the primary button | AA text (4.5:1) | 12.86:1 | Lc 75.6 | ✅ pass |
+| `--on-accent` | `--accent` | Ink on an accent fill | AA text (4.5:1) | 12.86:1 | Lc 75.6 | ✅ pass |
+| `--focus-ring` | `--bg` | Focus ring vs page background | UI / large (3:1) | 11.48:1 | Lc 74.1 | ✅ pass |
+| `--focus-ring` | `--surface` | Focus ring vs a card | UI / large (3:1) | 10.44:1 | Lc 73.1 | ✅ pass |
+| `--accent` | `--bg` | Accent fill vs page background | UI / large (3:1) | 11.48:1 | Lc 74.1 | ✅ pass |
 
 ### Phosphor Green — light
 
 | Foreground | Background | Role | Held to | Ratio | APCA _(advisory)_ | Verdict |
 | --- | --- | --- | --- | --- | --- | --- |
-| `--accent-text` | `--bg` | Accent text on page background | AA text (4.5:1) | 6.22:1 | Lc 77 | ✅ pass |
-| `--accent-text` | `--surface` | Accent text on a card | AA text (4.5:1) | 6.85:1 | Lc 83 | ✅ pass |
-| `--button-text` | `--accent` | Label on the primary button | AA text (4.5:1) | 5.19:1 | Lc 81 | ✅ pass |
-| `--focus-ring` | `--bg` | Focus ring vs page background | UI / large (3:1) | 4.71:1 | Lc 69 | ✅ pass |
-| `--focus-ring` | `--surface` | Focus ring vs a card | UI / large (3:1) | 5.19:1 | Lc 75 | ✅ pass |
-| `--accent` | `--bg` | Accent fill vs page background | UI / large (3:1) | 4.71:1 | Lc 69 | ✅ pass |
+| `--accent-text` | `--bg` | Accent text on page background | AA text (4.5:1) | 6.22:1 | Lc 76.6 | ✅ pass |
+| `--accent-text` | `--surface` | Accent text on a card | AA text (4.5:1) | 6.85:1 | Lc 83.3 | ✅ pass |
+| `--accent-text` | `--accent-soft` | Accent text on an accent tint | Advisory (translucent tint — not gated) | 5.81:1 | Lc 72.2 | ℹ️ not gated |
+| `--accent-text` | `--bg-accent` | Accent text on an accent-tinted surface | Advisory (translucent tint — not gated) | 6.21:1 | Lc 76.5 | ℹ️ not gated |
+| `--button-text` | `--accent` | Label on the primary button | AA text (4.5:1) | 5.19:1 | Lc 80.7 | ✅ pass |
+| `--on-accent` | `--accent` | Ink on an accent fill | AA text (4.5:1) | 5.19:1 | Lc 80.7 | ✅ pass |
+| `--focus-ring` | `--bg` | Focus ring vs page background | UI / large (3:1) | 4.71:1 | Lc 68.6 | ✅ pass |
+| `--focus-ring` | `--surface` | Focus ring vs a card | UI / large (3:1) | 5.19:1 | Lc 75.3 | ✅ pass |
+| `--accent` | `--bg` | Accent fill vs page background | UI / large (3:1) | 4.71:1 | Lc 68.6 | ✅ pass |
 
 ### Phosphor Green — dark
 
 | Foreground | Background | Role | Held to | Ratio | APCA _(advisory)_ | Verdict |
 | --- | --- | --- | --- | --- | --- | --- |
-| `--accent-text` | `--bg` | Accent text on page background | AA text (4.5:1) | 12.97:1 | Lc 82 | ✅ pass |
-| `--accent-text` | `--surface` | Accent text on a card | AA text (4.5:1) | 11.80:1 | Lc 81 | ✅ pass |
-| `--button-text` | `--accent` | Label on the primary button | AA text (4.5:1) | 13.75:1 | Lc 80 | ✅ pass |
-| `--focus-ring` | `--bg` | Focus ring vs page background | UI / large (3:1) | 12.27:1 | Lc 79 | ✅ pass |
-| `--focus-ring` | `--surface` | Focus ring vs a card | UI / large (3:1) | 11.16:1 | Lc 78 | ✅ pass |
-| `--accent` | `--bg` | Accent fill vs page background | UI / large (3:1) | 12.27:1 | Lc 79 | ✅ pass |
+| `--accent-text` | `--bg` | Accent text on page background | AA text (4.5:1) | 12.97:1 | Lc 81.8 | ✅ pass |
+| `--accent-text` | `--surface` | Accent text on a card | AA text (4.5:1) | 11.80:1 | Lc 80.8 | ✅ pass |
+| `--accent-text` | `--accent-soft` | Accent text on an accent tint | Advisory (translucent tint — not gated) | 1.20:1 | Lc 8.4 | ℹ️ not gated |
+| `--accent-text` | `--bg-accent` | Accent text on an accent-tinted surface | Advisory (translucent tint — not gated) | 1.30:1 | Lc 13.7 | ℹ️ not gated |
+| `--button-text` | `--accent` | Label on the primary button | AA text (4.5:1) | 13.75:1 | Lc 79.7 | ✅ pass |
+| `--on-accent` | `--accent` | Ink on an accent fill | AA text (4.5:1) | 13.75:1 | Lc 79.7 | ✅ pass |
+| `--focus-ring` | `--bg` | Focus ring vs page background | UI / large (3:1) | 12.27:1 | Lc 78.5 | ✅ pass |
+| `--focus-ring` | `--surface` | Focus ring vs a card | UI / large (3:1) | 11.16:1 | Lc 77.5 | ✅ pass |
+| `--accent` | `--bg` | Accent fill vs page background | UI / large (3:1) | 12.27:1 | Lc 78.5 | ✅ pass |
 
 ## Data-viz palette (advisory)
 
@@ -178,27 +202,27 @@ the brand accent.
 
 | Series | Colour | Ratio _(advisory)_ | APCA _(advisory)_ |
 | --- | --- | --- | --- |
-| 1 _(accent)_ | `#d71921` | 4.71:1 | Lc 67 |
-| 2 | `#e69f00` | 2.05:1 | Lc 37 |
-| 3 | `#56b4e9` | 2.10:1 | Lc 39 |
-| 4 | `#009e73` | 3.11:1 | Lc 54 |
-| 5 | `#f0e442` | 1.20:1 | Lc 9 |
-| 6 | `#0072b2` | 4.71:1 | Lc 68 |
-| 7 | `#cc79a7` | 2.78:1 | Lc 51 |
-| 8 | `#4d5358` | 7.08:1 | Lc 80 |
+| 1 _(accent)_ | `#d71921` | 4.71:1 | Lc 66.8 |
+| 2 | `#e69f00` | 2.05:1 | Lc 37.4 |
+| 3 | `#56b4e9` | 2.10:1 | Lc 38.6 |
+| 4 | `#009e73` | 3.11:1 | Lc 54.4 |
+| 5 | `#f0e442` | 1.20:1 | Lc 9.1 |
+| 6 | `#0072b2` | 4.71:1 | Lc 68.4 |
+| 7 | `#cc79a7` | 2.78:1 | Lc 50.6 |
+| 8 | `#4d5358` | 7.08:1 | Lc 80.4 |
 
 ### Dark theme — categorical vs `--bg`
 
 | Series | Colour | Ratio _(advisory)_ | APCA _(advisory)_ |
 | --- | --- | --- | --- |
-| 1 _(accent)_ | `#ff3b41` | 5.31:1 | Lc 40 |
-| 2 | `#e69f00` | 8.32:1 | Lc 58 |
-| 3 | `#56b4e9` | 8.12:1 | Lc 56 |
-| 4 | `#009e73` | 5.48:1 | Lc 40 |
-| 5 | `#f0e442` | 14.17:1 | Lc 87 |
-| 6 | `#0072b2` | 3.61:1 | Lc 26 |
-| 7 | `#cc79a7` | 6.12:1 | Lc 44 |
-| 8 | `#4d5358` | 2.40:1 | Lc 14 |
+| 1 _(accent)_ | `#ff3b41` | 5.31:1 | Lc 40.0 |
+| 2 | `#e69f00` | 8.32:1 | Lc 57.5 |
+| 3 | `#56b4e9` | 8.12:1 | Lc 56.3 |
+| 4 | `#009e73` | 5.48:1 | Lc 40.0 |
+| 5 | `#f0e442` | 14.17:1 | Lc 87.4 |
+| 6 | `#0072b2` | 3.61:1 | Lc 26.1 |
+| 7 | `#cc79a7` | 6.12:1 | Lc 43.9 |
+| 8 | `#4d5358` | 2.40:1 | Lc 14.4 |
 
 ## Scope & caveats
 

package/docs/d2.md

@@ -0,0 +1,195 @@
+# D2
+
+[D2](https://d2lang.com) compiles a diagram script to **SVG** (Go CLI or the
+`@terrastruct/d2` WASM build). Like the [Mermaid integration](./mermaid.md),
+`@ponchia/ui` doesn't render diagrams — it **themes** them from your tokens and
+lets you **annotate** the result. Two things ship:
+
+- `@ponchia/ui/d2` — helpers that produce on-brand D2 theme overrides.
+- `@ponchia/ui/d2.json` — the resolved slot → hex maps, for any consumer.
+
+D2 stays the consumer's renderer; this is config only, and D2 is **not** a
+dependency.
+
+## Theme a diagram
+
+D2's theme is a compact set of named colour slots. Override them with the bronto
+palette by prepending a `vars` block to your diagram source — `brontoD2Vars()`
+returns exactly that block (both light and dark):
+
+```js
+import { brontoD2Vars } from '@ponchia/ui/d2';
+
+const source = brontoD2Vars() + `
+  api -> db: query
+  db: Store { shape: cylinder }
+`;
+// → render `source` with the D2 CLI or @terrastruct/d2
+```
+
+If you render through D2's Go or WASM API instead of source, pass the slot map to
+its `themeOverrides` / `darkThemeOverrides`:
+
+```js
+import { brontoD2Overrides } from '@ponchia/ui/d2';
+brontoD2Overrides('dark'); // { N1: '#e6e6e6', B1: '#555555', … }
+```
+
+For a build step or non-JS host, read `@ponchia/ui/d2.json` directly.
+
+> **file:// portability.** A report opened from disk (`file://`) cannot
+> `import` the `@ponchia/ui/d2` module **nor** `fetch('…/d2.json')` — the browser
+> blocks both across the `null`/file origin (CORS), exactly as with
+> [Vega](./vega.md#from-a-cdn-no-bundler) and [Mermaid](./mermaid.md#theme-a-diagram).
+> This is rarely an issue for D2, whose native path is **build-time
+> pre-rendering** to a frozen SVG (no client runtime — see below), but if you do
+> theme D2 in the browser over `file://`, **inline** the slot map (paste the
+> object from `d2.json`) rather than importing it. Over `http(s)` the
+> `import`/`fetch` forms both work.
+
+### Why resolved colours, not `var(--x)`
+
+D2 compiles to a **frozen SVG** in Go/WASM — there is no client CSS cascade, so a
+`var(--accent)` could never resolve. The maps therefore ship **resolved hex per
+theme**, projected from the same token source as
+[`tokens/resolved.json`](./architecture.md) / `charts.json`. Each slot is set
+explicitly (D2 does not derive a ramp from one seed). Because the output is a
+static SVG, **build-time pre-rendering is D2's native path** — ideal for the
+[report layer](./reporting.md).
+
+### What the slots paint
+
+The mapping keeps a diagram **monochrome by default** — the rationed accent is
+not spent on borders, edges, or shapes the author never marked:
+
+| Slots | Paint | bronto mapping |
+| --- | --- | --- |
+| `N1`–`N3` | Text · muted · subtle | `--text` · `--text-soft` · `--text-dim` |
+| `N4`–`N5` | Strong / regular lines | `--line-strong` · `--line` |
+| `N6`–`N7` | Subtle background · canvas | `--panel-soft` · `--bg` |
+| `B1` | Shape borders **and** connections (edges) | `--line-strong` |
+| `B2`–`B3` | Muted borders | `--line` |
+| `B4`–`B6` | Container fills (outer → leaf) | `--panel-soft` · `--bg-elevated` · `--panel` |
+| `AA*` / `AB*` | Alternative-accent ramps (special-shape fills, class/sql headers) | kept **neutral** |
+
+The alt-accent ramps are deliberately neutral: D2 spends them on special shapes
+(cylinders, class/sql-table headers) by default, so mapping them to the accent
+would colour shapes you never marked. Keeping them neutral is what holds the
+monochrome default.
+
+### Spending the accent
+
+To emphasise a node, opt it into a class that sets the accent explicitly — the
+accent appears only where you ask for it:
+
+```d2
+classes: {
+  accent: {
+    style: { fill: "#d71921"; font-color: "#ffffff"; stroke: "#b2151b" }
+  }
+}
+
+alert: Alert { class: accent }
+```
+
+Use the resolved `--accent` / `--accent-strong` hex (from
+[`tokens/resolved.json`](./architecture.md), per theme) for the `fill` / `stroke`
+so the emphasis matches the rest of the surface. Reserve it for the one thing a
+reader must not miss.
+
+> **The label on an accent fill uses `--on-accent`, not `--accent-text`.** A
+> filled-accent node needs **on-accent ink** for its `font-color` — the resolved
+> `--on-accent` token (white on the light accent, black on the dark accent;
+> ≥ 4.5:1, gated in [contrast.md](./contrast.md)). Do **not** reach for
+> `--accent-text` by name: that is the inverse token — _accent-coloured text for
+> a neutral background_ (it resolves to `--accent-strong`, ~1.3:1 on the accent
+> fill, an unreadable label). The literal `#ffffff` above is `--on-accent` for
+> the light theme; pull the per-theme hex from `tokens/resolved.json`.
+
+### Frozen inline SVG (no D2 runtime)
+
+A static, PDF-first report often has no D2 binary in its pipeline. When you only
+need a few boxes and arrows, **hand-author a token-themed inline `<svg>`** instead
+of running D2 — the same frozen-figure route the [report chart
+recipe](./reporting.md#chart-figure-recipe) uses. Paint each element from the
+token that the live theme map would have resolved, so the frozen diagram still
+re-skins (drive fills from `var(--token)` in the inline `style`/attributes, or
+paste the resolved hex from [`tokens/resolved.json`](./architecture.md) for a
+`file://` PDF):
+
+| Diagram element | bronto token | (live D2 slot it mirrors) |
+| --- | --- | --- |
+| Node fill | `--panel` | `B4`–`B6` container fills |
+| Node border | `--line-strong` | `B1` |
+| Node label | `--text` | `N1` |
+| Edge / connector + arrowhead | `--line-strong` | `B1` |
+| Edge label | `--text-soft` | `N2` |
+| Cluster / container fill | `--panel-soft` | `B4` |
+| Accent (emphasised) node fill · its label | `--accent` · `--on-accent` | the `accent` class above |
+
+```html
+<svg viewBox="0 0 320 120" role="img" aria-labelledby="flow-title">
+  <title id="flow-title">Ingest → Queue → Worker</title>
+  <!-- edge -->
+  <line x1="92" y1="40" x2="128" y2="40" stroke="var(--line-strong)" marker-end="url(#arrow)" />
+  <line x1="220" y1="40" x2="256" y2="40" stroke="var(--line-strong)" marker-end="url(#arrow)" />
+  <defs>
+    <marker id="arrow" viewBox="0 0 8 8" refX="7" refY="4" markerWidth="6" markerHeight="6" orient="auto">
+      <path d="M0,0 L8,4 L0,8 z" fill="var(--line-strong)" />
+    </marker>
+  </defs>
+  <!-- neutral node -->
+  <rect x="16" y="22" width="76" height="36" rx="6" fill="var(--panel)" stroke="var(--line-strong)" />
+  <text x="54" y="44" text-anchor="middle" fill="var(--text)" font-size="12">Ingest</text>
+  <!-- accent (emphasised) node: on-accent ink on the accent fill -->
+  <rect x="128" y="22" width="92" height="36" rx="6" fill="var(--accent)" stroke="var(--accent-strong)" />
+  <text x="174" y="44" text-anchor="middle" fill="var(--on-accent)" font-size="12">Queue</text>
+  <rect x="256" y="22" width="64" height="36" rx="6" fill="var(--panel)" stroke="var(--line-strong)" />
+  <text x="288" y="44" text-anchor="middle" fill="var(--text)" font-size="12">Worker</text>
+</svg>
+```
+
+For anything larger or graph-laid-out, run D2 with the theme map and freeze its
+output — don't hand-lay a complex graph.
+
+### Fit to small screens
+
+D2 emits an SVG with explicit `width`/`height` from its layout, so on a narrow
+screen it overflows unless you make it fluid. Two build-time options:
+
+- **Scale to fit** — drop the fixed `width`/`height` attributes (keep the
+  `viewBox`) so the SVG shrinks to its container. Best for diagrams that stay
+  legible at smaller sizes.
+- **Scroll a wide diagram** — wrap it in `overflow-x: auto` so a large diagram
+  scrolls inside its box instead of pushing the page wide, the same pattern the
+  report layer uses for wide figures.
+
+```css
+.diagram-scroll {
+  overflow-x: auto;
+}
+.diagram-scroll svg {
+  max-inline-size: 100%;
+  block-size: auto;
+}
+```
+
+Render **non-sketch** at a fixed `scale` for predictable boxes.
+
+## Annotate a diagram
+
+D2 output is SVG, so the [annotation layer](./annotations.md) composes onto it
+exactly as in the [Mermaid recipe](./mermaid.md#annotate-a-diagram): render to a
+frozen SVG (the D2 CLI `d2 in.d2 out.svg`, or `@terrastruct/d2` in a build
+script), read the target shape's box, and paste a `<g class="ui-annotation">`
+computed with `@ponchia/ui/annotations`. The same caveats apply — D2's internal
+SVG (element ids, the root transform) is not a public contract, so pin your D2
+version, render **non-sketch**, account for `pad` / `scale`, and avoid
+`animate-interval` (a multi-board animated SVG would not track a single overlay).
+
+## Scope
+
+bronto owns the theme map (gated: every slot resolves to a colour, both themes,
+no `var()` leaks) and the annotation geometry. It does not own D2's rendering,
+its internal SVG, or its CLI — those stay D2's, and the overlay is a documented
+composition, not a shipped runtime binding.

package/docs/legends.md

@@ -13,8 +13,9 @@ drifts from the series it describes.
 ```
 
 Bronto **paints and positions** the key; it owns no scales, no data→pixel
-mapping, and no series state. Pair it with Bronto's own `.ui-chart` bars, an
-SVG/canvas figure, or any external chart engine — the host owns the chart.
+mapping, and no series state. Pair it with any chart — a token-themed inline
+SVG, or an external engine like [Vega-Lite](./vega.md) — the host owns the
+chart.
 
 ## What it is not
 
@@ -89,6 +90,21 @@ chart mark uses, or with a `--N` index helper for the categorical palette.
 `ui-legend__swatch--circle` and `ui-legend__swatch--line` change the chip shape
 (dot series, line series).
 
+A `ui-legend__symbol` chip is an `.ui-icon` mask — it needs a `--icon-mask`
+(e.g. `style="--icon-mask: var(--glyph-dot)"`) or it paints a solid square, like
+any [icon](./reference.md). And an **interactive** legend entry must be a real
+`<button>` (as in the example below) — a non-button `ui-legend__item` carrying
+`data-series` is not keyboard-reachable.
+
+**Keying the de-emphasised series.** In an accent-rationed chart — one mark
+painted with [`brontoVegaAccent`](./vega.md#spending-the-accent), the rest left
+quiet with `brontoVegaNeutral` — the quiet neutral **is** the last categorical
+series, `--chart-8` (`#4d5358`). So a legend that honestly mirrors that chart
+uses `ui-legend__swatch--1` for the highlighted entry and
+`ui-legend__swatch--8` for the "everything else" entry — both are real palette
+tokens, so the key never drifts from the marks and `check:legend` stays happy.
+Don't hand-roll a grey: `--chart-8` is the neutral by construction.
+
 ## Variants
 
 | Modifier | Effect |