@ponchia/ui 0.3.6 → 0.4.0

package/docs/adr/0001-color-system.md

@@ -0,0 +1,272 @@
+# ADR-0001 — Color system: governed evolution beyond monochrome
+
+Status: accepted (all steps 1–8 implemented in 0.4.0) · 2026-05-31 ·
+supersedes the informal "monochrome + one accent" framing in `README.md` /
+`package.json`
+
+> This is the **color constitution** for `@ponchia/ui`. It is forward-looking:
+> nothing here changes the default build. It defines the tiers color is
+> allowed to occupy, the rules that keep restraint load-bearing, and the
+> ordered, backward-compatible path to expand expression without diluting the
+> brand. Companion to [`architecture.md`](../architecture.md).
+
+## Context
+
+`@ponchia/ui` took its aesthetic from Nothing: monochrome surfaces, one
+rationed red accent, dot-matrix motifs. The driving question for this ADR:
+**is monochrome creatively restrictive, and should we evolve past Nothing's
+literal one-hue constraint?**
+
+Two facts frame the answer.
+
+**1. We are already not monochrome — and that was the right call.** The README
+says "monochrome, one rationed accent." The CSS says otherwise. We already
+ship a full **functional status palette** (`--success`, `--warning`,
+`--danger`, `--info`, each with light/dark/`-soft` variants, contrast-tuned
+per theme, wired into `ui-alert` / `ui-toast` / `ui-meter`). It is rationed —
+status-only, always paired with a leading dot/shape, never decorative — but it
+exists. So the real model already has **three *active* tiers nobody wrote
+down** (neutral + accent + status); the two new axes this ADR adds (display
+expression, data-viz) are tiers 3–4. The question is not "should we abandon
+monochrome" (we did, carefully, around 0.3.4) but **"what is our color theory
+for the next axis."**
+
+**2. Inspiration is not doctrine.** The thing worth inheriting from Nothing is
+the *attitude* — restraint, intentionality, signal-over-noise — **not** the
+literal one-hue limit. "We do not decorate with color; we signal with it" is a
+stronger, more defensible principle than "we have no color," and we are most
+of the way to it already. Monochrome *is* creatively restrictive, but only on
+three specific axes: **categorical distinction** (tags/legends past ~3 items),
+**multi-series data-viz** (one accent + grays cannot draw a 5-line chart — we
+already felt this; `tokens/resolved.json` exists because charts needed real
+color), and **brand/emotional range** (one hue at a time). What monochrome
+*buys* and we must not casually spend: identity differentiation, forced
+hierarchy discipline, accessibility-by-default, and the scarcity that makes the
+one accent *mean* something.
+
+### What SOTA looks like (2025–2026)
+
+| Practice | Who | Relevance to us |
+| --- | --- | --- |
+| **Perceptual color space** (equal numeric step = equal perceived step) | Tailwind v4 (OKLCH+P3), Radix 3 (P3), Material 3 (HCT) | We derive `--accent-1..6` via `color-mix(in srgb,…)`; OKLCH is the modern substrate and is **CSS-native** — no dependency cost |
+| **Relative color syntax** `oklch(from var(--base) calc(l-.1) c h)` | CSS Color 5 | ~90% support, Baseline in 2026 — lets a single hue derive a whole tonal ramp natively |
+| **WCAG 2.2 to pass, APCA to design** | Radix text steps spec'd in APCA Lc | WCAG 2.2 AA stays the legal/hard gate; APCA (Lc, accounts for size/weight, WCAG 3 candidate) as an **advisory** track |
+| **Role-bound scale steps** (1–2 bg, 3–5 component, 6–8 border, 9–10 solid, 11–12 text) | Radix 12-step | Our tiers are coarser; the role-bound scale is where depth lives if we ever need it |
+| **Contrast-first generation** (pick a target Lc, derive the swatch) | Adobe Leonardo, Material dynamic | Natural evolution of "one `--accent` derives everything" |
+| **Categorical color is its own discipline** | Wong / IBM / ColorBrewer | Hard limit **6–8 hues**, ≥30 CIELAB lightness delta per pair, **redundant encoding** (shape/pattern/label) — our dot-matrix wheelhouse |
+
+SOTA is **not "more hues by default."** It is CSS-native token systems,
+perceptual color, role-based scales, contrast-aware generation, and *governed
+escape hatches*. Our restraint is already SOTA-adjacent; the work is to
+modernize the engine and add opt-in expression without spending the brand.
+
+## Decision
+
+Adopt a **five-tier color model** with a fixed governance contract. Color must
+*earn its place by encoding meaning*; the discipline moves from "absence of
+color" to "color is tiered, token-only, contrast-gated, and off-by-default."
+
+| Tier | Name | What it is | Default state |
+| --- | --- | --- | --- |
+| **0** | Neutral canvas | The grayscale ramp — surfaces, lines, text | Always on |
+| **1** | Brand accent | One themeable `--accent`, derives `--accent-1..6` | Always on (red) |
+| **2** | Functional status | `success` / `warning` / `danger` / `info` — signal only | Always on |
+| **3** | Display expression | Luminance, dot density/intensity, scan cadence, pulse, reveal timing — the dot-matrix substrate | Opt-in tokens |
+| **4** | Categorical / data-viz | A 6–8 color colorblind-safe scale + sequential/diverging ramps — **charts only** | Opt-in module, never bundled |
+
+### The six rules (the constitution)
+
+Each rule notes how it is held — **[gate]** = mechanically enforced by
+`check:color-policy`; **[other gate]** = enforced elsewhere in `npm run check`
+/ the e2e suite; **[norm]** = a review norm, not yet machine-checked. Don't
+read "rule" as "all six are CI-enforced" — only what's tagged **[gate]** is.
+
+1. **Token-only.** No raw chromatic color in component CSS — every color is a
+   tiered token (grays / `color-mix()` endpoints excepted). **[gate]** —
+   `check:color-policy` invariants 1 (tier classification) + 3 (raw-color scan).
+2. **Contrast-gated.** Every UI text/bg pairing passes **WCAG 2.2 AA**; **APCA
+   Lc is advisory** beside the matrix, never the sole gate while WCAG 3 is a
+   Working Draft. **[other gate]** — `check:contrast` + the e2e axe suite, not
+   `check:color-policy`.
+3. **Off-by-default.** The default red accent, all token names, and all visual
+   baselines remain **unchanged**; the strict-mono purist keeps their exact
+   system; everything new is opt-in. **[other gate]** — `check:dist`
+   byte-equality + visual baselines.
+4. **Semantic tier names.** A token's name declares its tier. **Status is never
+   decorative**; **chart color is never UI chrome.** No `primary/secondary`.
+   **[gate]** for "every color token is tiered" + the reserved `--chart/--cat/
+   --data-*` namespace (invariants 1–2); **[norm]** for "status never
+   decorative" (needs usage context a static gate can't see).
+5. **One active UI accent per scope.** No second brand accent. "Duotone" lives
+   in Tier 3 (dots/display ornament), not as a second interactive accent.
+   **[norm]**.
+6. **Meaning never by color or motion alone.** Redundant encoding (shape, dot,
+   label) is mandatory — satisfies WCAG 1.4.1 / 2.2.2 and is on-brand for the
+   dot-matrix. Reduced-motion users must get equivalent information statically.
+   **[other gate]** — the e2e axe/`forced-colors`/reduced-motion suite.
+
+### The brand's answer to "decorative color": luminance + time
+
+For a *dot-matrix display* system, the authentic expressive channel is not
+hue — it is **brightness and motion**, exactly like a real LED/phosphor panel
+(and we already shipped reveal/pulse in 0.3.6). Tier 3 is the strategic
+substitute for decorative polychrome: it deepens identity instead of diluting
+it, and no competitor in this niche owns it.
+
+### Resolving the `--orange` orphan — RESOLVED (removed, 0.4.0)
+
+Audit finding: `--orange` / `--orange-soft` were defined in every token file
+(`tokens/index.js`, `.d.ts`, `tokens.dtcg.json`, `resolved.json`,
+`css/tokens.css`, `reference.md`) but **consumed by no component and documented
+nowhere** — an untiered, dangling hue. Resolution: **removed** (not adopted as
+a categorical seed — there is no data-viz module or demand yet, and a stray
+top-level hue contradicts the tier model). If categorical color lands it ships
+as a governed Tier-4 module (step 7), not a loose token. The new
+`check:color-policy` gate now makes a future untiered hue a hard CI failure.
+
+## Backward-compatibility freeze
+
+Hard acceptance criteria for every step below:
+
+- **Default rendered output is unchanged** — the red accent defaults, the
+  resolved value of every token a component references, and the light/dark
+  **visual baselines** are identical. (Removing a token nothing resolves —
+  e.g. `--orange` in 0.4.0 — does change `dist/bronto.css` *bytes* but not what
+  any selector renders; that is cleanup, not a visual change. The earlier draft
+  said "dist bytes unchanged" — the precise invariant is *rendered output*.)
+- Token **names** are not renamed/repurposed (removals of provably-unreferenced
+  tokens follow the CONTRIBUTING.md deprecation-policy exception).
+- The existing `--accent-1..6` **sRGB `color-mix` derivation is not silently
+  changed.** `scripts/gen-resolved.mjs` only evaluates `color-mix(in srgb,…)`;
+  for any other space it returns `null`, and a `null` token is **dropped
+  entirely** from `resolved.json` (not defaulted) — so a consumer doing
+  `resolved.dark['--accent-3']` would get `undefined` and may throw. Combined
+  with the rendered-pixel change, switching the ramp to OKLCH is a breaking
+  change twice over. Stable names alone do not make it non-breaking. Any OKLCH
+  migration of the **existing** ramp is a documented **minor/RC** decision
+  after tooling + visual review, never a silent patch.
+
+## Roadmap (ordered, backward-compatible)
+
+1. **This ADR.** Make the constitution explicit before adding surface. *(done)*
+2. **`check:color-policy` gate.** Fail on: raw chromatic color in component CSS;
+   any untiered palette token; use of the reserved `--chart/--cat/--data-*`
+   namespace. Resolve `--orange`. *(done — `scripts/check-color-policy.mjs`,
+   wired into `npm run check`; `--orange` removed)*
+3. **Tier 3 expression tokens.** *(done — `css/dots.css`)* `--dotmatrix-glow`
+   (phosphor bloom on lit cells), `--dotmatrix-pulse-min` (the `--pulse` floor),
+   `--dotmatrix-reveal-step` (scan cadence); density stays on
+   `--dotmatrix-cols/-gap/-dot`. All default to a no-op, so the default render
+   is byte-for-byte unchanged; reduced-motion still kills the animations.
+4. **Optional display colorways** *(done — `tokens/skins.js` →
+   `css/skins.css`, exported as `./css/skins.css`, NOT in the default bundle)*:
+   `data-bronto-skin="amber-crt | phosphor-green | e-ink"`. **A root-level
+   choice, like `data-theme`** (apply on `:root`/`<html>`) — it must live there
+   because the accent's derived family (`--accent-strong/-text/-soft`,
+   `--bg-accent`, `--field-dot-accent`, `--accent-1..6`) is `color-mix(…
+   var(--accent) …)` declared on `:root` and only re-evaluates against the new
+   accent on the element that carries it; a skin on a subtree would leave that
+   family stale, so the selectors are `:root`-anchored and a subtree skin
+   no-ops. Each skin re-points only `--accent` (+ a dark `--dotmatrix-glow`);
+   the family + dot-matrix + glyphs follow automatically. Single-hue per skin →
+   keeps the one-accent discipline while unlocking range across skins. No
+   multi-hue palette. (A future per-subtree skin would need to re-declare the
+   derived family — deferred; whole-page is the natural colorway scope.) Skins
+   inherit the existing `forced-colors` + `print` behavior in `css/base.css` /
+   `css/forms.css` (they touch only the accent, never the canvas).
+5. **OKLCH for new work first.** *(done for colorways — accents authored in
+   OKLCH in `tokens/skins.js`; the contrast tooling now parses `oklch()` →
+   sRGB, so skin accents are gated, not eyeballed.)* The **core** `--accent-1..6`
+   ramp stays sRGB (decision below). For any future OKLCH in contractual token
+   files (the core ramp), still upgrade `gen-resolved` first and add a
+   gamut-aware fallback (`@supports`, sRGB-first), and consider `light-dark()`
+   to collapse the twice-written dark palette — both are in the same CSS
+   Color 5 / Baseline-2026 bracket.
+6. **APCA advisory reporting.** *(done — `scripts/gen-contrast.mjs`)* APCA-W3
+   0.1.9 `Lc` is computed beside the WCAG ratio for every pairing (core + skins)
+   in `docs/contrast.md`. **Advisory only** — WCAG 2.1 AA stays the hard gate.
+7. **Categorical chart module.** *(done in 0.4.0 — real demand arrived
+   (dashboards); `tokens/charts.js` → `css/dataviz.css` + `tokens/charts.json`
+   + `tokens/charts.d.ts`, gated by `check:charts`.)* Hybrid accent-led
+   (series 1 = `var(--accent)`) + Okabe-Ito colourblind-safe series 2–8 + a
+   sequential and a diverging ramp; **dot-matrix `--chart-pattern-*` fills** as
+   the mandated second channel. Gated for distinguishability under normal +
+   simulated protan/deutan/tritan vision (OKLab ΔE), `var(--chart-*)` forbidden
+   in core component CSS (charts-only), never in the default bundle. The
+   categorical fills are authored as the Okabe-Ito sRGB hex **verbatim** (a
+   CVD-proven *set* — re-deriving per-theme in OKLCH broke its colourblind
+   safety, which the gate caught); the ramps are OKLCH. A chart colour's WCAG
+   ratio vs the background is reported **advisory** (a fill is not body text;
+   the pattern + ΔE gate carry distinguishability).
+8. **OKLCH `--accent-1..6` ramp migration.** *(done in 0.4.0)* Steps 1–4 mix
+   the accent toward `--bg` `in oklch` (perceptually even). `gen-resolved` was
+   upgraded first to resolve `color-mix(in oklch,…)` → hex (bit-for-bit matching
+   the browser, incl. powerless-hue for near-neutral endpoints), so the
+   contractual `resolved.json`/DTCG never drop the tokens. Verified no rendered
+   change: `--accent-1..6` is consumed by **no** component (only JS/chart
+   consumers + the theme playground), so no visual baseline moved — the feared
+   "breaking + needs baseline review" turned out to touch only token *values*
+   (non-contractual under 0.x).
+
+## Risks & mitigations
+
+| Risk | Mitigation |
+| --- | --- |
+| **Brand dilution** (secondary accents, decorative hues creep in) | Rule 4/5; `check:color-policy`; off-by-default |
+| **Compat break** from OKLCH ramp swap | Freeze above; OKLCH for *new* work first; minor/RC only, never silent |
+| **Tooling drift** (resolver/DTCG/contrast/baseline assume sRGB) | Upgrade tooling *before* OKLCH enters token files; add computed-style tests |
+| **Chart color leakage** into UI chrome | `check:color-policy` forbids chart tokens in core CSS; docs forbid it |
+| **Motion/status misuse** carrying sole meaning | Rule 6; reduced-motion equivalence; status stays locked, never skin-derived |
+| **APCA overreach** | Advisory only; WCAG 2.2 AA stays the hard gate while WCAG 3 is draft |
+
+## Verification plan
+
+- Existing `npm run check`, `npm test`, token/DTCG/resolved/dist/visual/a11y
+  gates stay green and **unchanged** for the default build.
+- New `check:color-policy` (raw color, status misuse, chart leakage, untiered
+  hue).
+- Contrast matrices extended to: default light/dark, `prefers-contrast`,
+  `forced-colors`, **every shipped skin**, and chart tokens if shipped.
+- APCA output as non-blocking generated docs.
+- Playwright computed-style tests for `oklch()` / `color-mix(in oklch,…)`
+  before any core reliance.
+- Verify `prefers-reduced-motion`, `prefers-contrast`, `forced-colors`, and
+  native `accent-color` for every skin.
+- Confirm optional skin/chart CSS is exported + packed but **excluded** from
+  default `dist/bronto.css`.
+
+## Decisions taken (0.4.0)
+
+Resolved while implementing steps 3–6 (the open questions the earlier draft
+flagged):
+
+- **`--accent-1..6` is semver-stable and stays sRGB.** No silent ramp change.
+  → step 8 (default-ramp OKLCH migration) **deferred** — visual-diff review
+  cost outweighs the gain; reconsider as an opt-in engine / explicit minor.
+- **Colorways ship as a supported package export** (`./css/skins.css`),
+  opt-in, excluded from the default bundle. Not docs-only recipes.
+- **Colorways are root-level** (`data-bronto-skin` on `:root`, like
+  `data-theme`) — see step 4 for why per-subtree is deferred.
+- **OKLCH is within the existing browser floor** (Chrome 111+/Safari 16.4+/
+  Firefox 121+ all support `oklch()`); used for skin accents now. The contrast
+  tooling parses it so skins are gated.
+- **Build tooling stays dependency-free.** APCA + the OKLCH→sRGB conversion are
+  hand-rolled in `scripts/gen-contrast.mjs` (zero new deps), matching the
+  zero-dependency stance.
+- **Data-viz categorical color (step 7) shipped in 0.4.0** — real demand
+  arrived (dashboards). Built as a governed Tier-4 module (opt-in, charts-only,
+  leakage-gated, CVD-distinguishability-gated). `--cat/--data-*` remain reserved
+  alternative-name guards; `--chart-*` is now the live data-viz namespace.
+- **No second UI accent / "duotone" stays Tier-3 ornament only** (rule 5).
+
+## Method
+
+Grounded in web research (OKLCH/relative-color/`color-mix` baseline; APCA vs
+WCAG; Radix 12-step; Material 3 HCT; Adobe Leonardo; colorblind-safe
+categorical limits) and a 14-leg AgentMix `deep` multi-POV pass
+(Pi/MiniMax, Aider, OpenCode, Crush, Codex + architecture / implementation-risk
+/ testing / security / operations / contrarian legs). Key reconciled dissent:
+several legs wanted an immediate OKLCH ramp swap — rejected as a silent break
+(see freeze); the claim that `--accent-1..6` already serves as a categorical
+scale was rejected (a same-hue ramp encodes sequence/intensity, not independent
+categories); deriving status from skins was rejected (status stays locked).

package/docs/contrast.md

@@ -38,63 +38,182 @@ Overall: **all contractual pairings meet their floor ✅**.
 
 ## Light theme
 
-| Foreground | Background | Role | Held to | Ratio | Verdict |
-| --- | --- | --- | --- | --- | --- |
-| `--text` | `--bg` | Body text on page background | AA text (4.5:1) | 17.98:1 | ✅ pass |
-| `--text` | `--surface` | Body text on a card/panel | AA text (4.5:1) | 19.80:1 | ✅ pass |
-| `--text` | `--surface-muted` | Body text on a muted panel | AA text (4.5:1) | 16.74:1 | ✅ pass |
-| `--text-soft` | `--bg` | Secondary text on page background | AA text (4.5:1) | 11.16:1 | ✅ pass |
-| `--text-soft` | `--surface` | Secondary text on a card | AA text (4.5:1) | 12.29:1 | ✅ pass |
-| `--text-soft` | `--surface-muted` | Secondary text on a muted panel | AA text (4.5:1) | 10.39:1 | ✅ pass |
-| `--text-dim` | `--bg` | Dim/meta text on page background | AA text (4.5:1) | 5.09:1 | ✅ pass |
-| `--text-dim` | `--surface` | Dim/meta text on a card | AA text (4.5:1) | 5.60:1 | ✅ pass |
-| `--text-dim` | `--surface-muted` | Dim/meta text on a muted panel | AA text (4.5:1) | 4.74:1 | ✅ pass |
-| `--accent-text` | `--bg` | Accent text on page background | AA text (4.5:1) | 6.32:1 | ✅ pass |
-| `--accent-text` | `--surface` | Accent text on a card | AA text (4.5:1) | 6.96:1 | ✅ pass |
-| `--button-text` | `--accent` | Label on the primary button | AA text (4.5:1) | 5.18:1 | ✅ pass |
-| `--focus-ring` | `--bg` | Focus ring vs page background | UI / large (3:1) | 4.71:1 | ✅ pass |
-| `--focus-ring` | `--surface` | Focus ring vs a card | UI / large (3:1) | 5.18:1 | ✅ pass |
-| `--accent` | `--bg` | Accent fill vs page background | UI / large (3:1) | 4.71:1 | ✅ pass |
-| `--success` | `--surface` | Success indicator vs a card | UI / large (3:1) | 5.04:1 | ✅ pass |
-| `--warning` | `--surface` | Warning indicator vs a card | UI / large (3:1) | 5.60:1 | ✅ pass |
-| `--danger` | `--surface` | Danger indicator vs a card | UI / large (3:1) | 6.21:1 | ✅ pass |
-| `--info` | `--surface` | Info indicator vs a card | UI / large (3:1) | 5.77:1 | ✅ pass |
-| `--line-strong` | `--surface` | Strong hairline vs a card | Decorative (1.4.11-exempt) | 2.39:1 | ℹ️ not gated |
+| 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 |
 
 ## Dark theme
 
-| Foreground | Background | Role | Held to | Ratio | Verdict |
-| --- | --- | --- | --- | --- | --- |
-| `--text` | `--bg` | Body text on page background | AA text (4.5:1) | 18.76:1 | ✅ pass |
-| `--text` | `--surface` | Body text on a card/panel | AA text (4.5:1) | 17.47:1 | ✅ pass |
-| `--text` | `--surface-muted` | Body text on a muted panel | AA text (4.5:1) | 15.55:1 | ✅ pass |
-| `--text-soft` | `--bg` | Secondary text on page background | AA text (4.5:1) | 12.04:1 | ✅ pass |
-| `--text-soft` | `--surface` | Secondary text on a card | AA text (4.5:1) | 11.22:1 | ✅ pass |
-| `--text-soft` | `--surface-muted` | Secondary text on a muted panel | AA text (4.5:1) | 9.98:1 | ✅ pass |
-| `--text-dim` | `--bg` | Dim/meta text on page background | AA text (4.5:1) | 5.69:1 | ✅ pass |
-| `--text-dim` | `--surface` | Dim/meta text on a card | AA text (4.5:1) | 5.30:1 | ✅ pass |
-| `--text-dim` | `--surface-muted` | Dim/meta text on a muted panel | AA text (4.5:1) | 4.72:1 | ✅ pass |
-| `--accent-text` | `--bg` | Accent text on page background | AA text (4.5:1) | 6.88:1 | ✅ pass |
-| `--accent-text` | `--surface` | Accent text on a card | AA text (4.5:1) | 6.41:1 | ✅ pass |
-| `--button-text` | `--accent` | Label on the primary button | AA text (4.5:1) | 5.95:1 | ✅ pass |
-| `--focus-ring` | `--bg` | Focus ring vs page background | UI / large (3:1) | 5.95:1 | ✅ pass |
-| `--focus-ring` | `--surface` | Focus ring vs a card | UI / large (3:1) | 5.55:1 | ✅ pass |
-| `--accent` | `--bg` | Accent fill vs page background | UI / large (3:1) | 5.95:1 | ✅ pass |
-| `--success` | `--surface` | Success indicator vs a card | UI / large (3:1) | 8.70:1 | ✅ pass |
-| `--warning` | `--surface` | Warning indicator vs a card | UI / large (3:1) | 10.66:1 | ✅ pass |
-| `--danger` | `--surface` | Danger indicator vs a card | UI / large (3:1) | 6.00:1 | ✅ pass |
-| `--info` | `--surface` | Info indicator vs a card | UI / large (3:1) | 8.41:1 | ✅ pass |
-| `--line-strong` | `--surface` | Strong hairline vs a card | Decorative (1.4.11-exempt) | 2.01:1 | ℹ️ not gated |
+| Foreground | Background | Role | Held to | Ratio | APCA _(advisory)_ | Verdict |
+| --- | --- | --- | --- | --- | --- | --- |
+| `--text` | `--bg` | Body text on page background | AA text (4.5:1) | 18.76:1 | Lc 99 | ✅ pass |
+| `--text` | `--surface` | Body text on a card/panel | AA text (4.5:1) | 17.47:1 | Lc 99 | ✅ pass |
+| `--text` | `--surface-muted` | Body text on a muted panel | AA text (4.5:1) | 15.55:1 | Lc 98 | ✅ pass |
+| `--text-soft` | `--bg` | Secondary text on page background | AA text (4.5:1) | 12.04:1 | Lc 71 | ✅ pass |
+| `--text-soft` | `--surface` | Secondary text on a card | AA text (4.5:1) | 11.22:1 | Lc 71 | ✅ pass |
+| `--text-soft` | `--surface-muted` | Secondary text on a muted panel | AA text (4.5:1) | 9.98:1 | Lc 70 | ✅ pass |
+| `--text-dim` | `--bg` | Dim/meta text on page background | AA text (4.5:1) | 5.69:1 | Lc 37 | ✅ pass |
+| `--text-dim` | `--surface` | Dim/meta text on a card | AA text (4.5:1) | 5.30:1 | Lc 37 | ✅ pass |
+| `--text-dim` | `--surface-muted` | Dim/meta text on a muted panel | AA text (4.5:1) | 4.72:1 | Lc 36 | ✅ pass |
+| `--accent-text` | `--bg` | Accent text on page background | AA text (4.5:1) | 6.88:1 | Lc 45 | ✅ pass |
+| `--accent-text` | `--surface` | Accent text on a card | AA text (4.5:1) | 6.41:1 | Lc 45 | ✅ 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.95:1 | Lc 41 | ✅ pass |
+| `--focus-ring` | `--surface` | Focus ring vs a card | UI / large (3:1) | 5.55:1 | Lc 40 | ✅ pass |
+| `--accent` | `--bg` | Accent fill vs page background | UI / large (3:1) | 5.95:1 | Lc 41 | ✅ pass |
+| `--success` | `--surface` | Success indicator vs a card | UI / large (3:1) | 8.70:1 | Lc 58 | ✅ pass |
+| `--warning` | `--surface` | Warning indicator vs a card | UI / large (3:1) | 10.66:1 | Lc 68 | ✅ pass |
+| `--danger` | `--surface` | Danger indicator vs a card | UI / large (3:1) | 6.00:1 | Lc 43 | ✅ pass |
+| `--info` | `--surface` | Info indicator vs a card | UI / large (3:1) | 8.41:1 | Lc 56 | ✅ pass |
+| `--line-strong` | `--surface` | Strong hairline vs a card | Decorative (1.4.11-exempt) | 2.01:1 | Lc 10 | ℹ️ not gated |
+
+## Display colorways (skins)
+
+The opt-in `data-bronto-skin` colorways (`@ponchia/ui/css/skins.css`,
+authored in `tokens/skins.js`) re-point the one accent to a different single
+hue. Because a shipped colorway is part of the framework — not an arbitrary
+consumer re-brand — **its accent is gated to the same floors as the core**:
+the primary-button label, accent-as-text, and the focus ring/accent fill. Only
+the accent-touching pairings are shown (a skin leaves the canvas and status
+palette untouched). Accents are authored in OKLCH; `--accent-text` is the
+`color-mix`-derived `--accent-strong`, exactly as in the core palette.
+
+### Amber CRT — light
+
+| 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 |
+
+### 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) | 12.97:1 | Lc 75 | ✅ pass |
+| `--accent-text` | `--surface` | Accent text on a card | AA text (4.5:1) | 12.08:1 | Lc 75 | ✅ 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) | 11.88:1 | Lc 70 | ✅ pass |
+| `--focus-ring` | `--surface` | Focus ring vs a card | UI / large (3:1) | 11.07:1 | Lc 70 | ✅ pass |
+| `--accent` | `--bg` | Accent fill vs page background | UI / large (3:1) | 11.88:1 | Lc 70 | ✅ 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 |
+
+### 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) | 13.98:1 | Lc 80 | ✅ pass |
+| `--accent-text` | `--surface` | Accent text on a card | AA text (4.5:1) | 13.02:1 | Lc 79 | ✅ 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) | 12.86:1 | Lc 75 | ✅ pass |
+| `--focus-ring` | `--surface` | Focus ring vs a card | UI / large (3:1) | 11.98:1 | Lc 74 | ✅ pass |
+| `--accent` | `--bg` | Accent fill vs page background | UI / large (3:1) | 12.86:1 | Lc 75 | ✅ 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 |
+
+### 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) | 14.54:1 | Lc 82 | ✅ pass |
+| `--accent-text` | `--surface` | Accent text on a card | AA text (4.5:1) | 13.55:1 | Lc 82 | ✅ 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) | 13.75:1 | Lc 79 | ✅ pass |
+| `--focus-ring` | `--surface` | Focus ring vs a card | UI / large (3:1) | 12.81:1 | Lc 79 | ✅ pass |
+| `--accent` | `--bg` | Accent fill vs page background | UI / large (3:1) | 13.75:1 | Lc 79 | ✅ pass |
+
+## Data-viz palette (advisory)
+
+The opt-in Tier-4 chart palette (`@ponchia/ui/css/dataviz.css`, authored in
+`tokens/charts.js`) is gated differently: categorical series are held to
+**mutual distinguishability under normal + simulated protan/deutan/tritan
+vision** (`check:charts`, OKLab ΔE), and colour is **never the sole signal** —
+each series ships a matching `--chart-pattern-*` dot-matrix fill. So the
+WCAG ratios below are **advisory** (a chart fill is not body text); use them to
+pick a darker series for thin lines/points, or rely on the pattern. Series 1 is
+the brand accent.
+
+### Light theme — categorical vs `--bg`
+
+| 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 |
+
+### Dark theme — categorical vs `--bg`
+
+| Series | Colour | Ratio _(advisory)_ | APCA _(advisory)_ |
+| --- | --- | --- | --- |
+| 1 _(accent)_ | `#ff3b41` | 5.95:1 | Lc 41 |
+| 2 | `#e69f00` | 9.32:1 | Lc 58 |
+| 3 | `#56b4e9` | 9.10:1 | Lc 57 |
+| 4 | `#009e73` | 6.14:1 | Lc 41 |
+| 5 | `#f0e442` | 15.88:1 | Lc 88 |
+| 6 | `#0072b2` | 4.05:1 | Lc 27 |
+| 7 | `#cc79a7` | 6.86:1 | Lc 45 |
+| 8 | `#4d5358` | 2.69:1 | Lc 15 |
 
 ## Scope & caveats
 
-- This gates the **framework token contract**, not arbitrary consumer
-  re-brands. Re-accenting via `--accent` is your contrast obligation
-  (see [theming.md](theming.md) → "Re-brand obligations"); this table is
-  the guarantee for the *shipped* palettes only.
+- This gates the **framework token contract** (core palette **and** every
+  shipped colorway), not arbitrary consumer re-brands. Re-accenting via
+  `--accent` yourself is your contrast obligation (see [theming.md](theming.md)
+  → "Re-brand obligations"); this table is the guarantee for the *shipped*
+  palettes and skins only.
 - Status colours (`--success` / `--warning` / `--danger`) are gated
   as **indicators** (3:1). If you set status text *as body copy* on a
   surface, verify 4.5:1 yourself or pair it with an icon/label.
-- Ratios are sRGB WCAG 2.1. The newer APCA model is intentionally not
-  used — WCAG 2.1 AA is the testable legal/again-axe baseline the e2e
-  suite already asserts.
+- The gated **Ratio** is sRGB WCAG 2.1 AA — the testable legal / axe-compatible
+  baseline the e2e suite also asserts. The **APCA** column (APCA-W3 0.1.9 `Lc`)
+  is **advisory only**: a perceptual cross-check that, unlike WCAG 2.1's
+  symmetric ratio, accounts for polarity and is the WCAG 3 candidate. It does
+  **not** gate the build while WCAG 3 is a Working Draft — use it to tune
+  quality, not to override the WCAG 2.1 floor. As a rough read, body text wants
+  `Lc` ≥ 75 and non-text/large ≥ 45–60.

package/docs/reference.md

@@ -9,7 +9,7 @@ rendering of every class is the kitchen-sink demo:
 **<https://ponchia.github.io/bronto-ui/>**. Theming knobs and the token
 contract: [docs/theming.md](theming.md).
 
-- 262 classes across 109 component groups
+- 263 classes across 110 component groups
 - Import the typed registry: `import { cls, ui, cx } from '@ponchia/ui/classes'`
 - Tokens as data: `import { cssVars, tokens, themeColor } from '@ponchia/ui/tokens'`
 
@@ -393,6 +393,12 @@ each one matches a real selector in the stylesheet.
 | `cls.hint` | `ui-hint` | base |
 | `cls.hintError` | `ui-hint--error` | modifier |
 
+### `.ui-icon`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.icon` | `ui-icon` | base |
+
 ### `.ui-input`
 
 | Registry key | Class | Kind |
@@ -913,10 +919,10 @@ Exact mirror of the `:root` blocks in `css/tokens.css`
 | `--z-overlay` | `30` |
 | `--z-popover` | `50` |
 | `--z-toast` | `60` |
-| `--accent-1` | `color-mix(in srgb, var(--accent) 8%, var(--bg))` |
-| `--accent-2` | `color-mix(in srgb, var(--accent) 16%, var(--bg))` |
-| `--accent-3` | `color-mix(in srgb, var(--accent) 32%, var(--bg))` |
-| `--accent-4` | `color-mix(in srgb, var(--accent) 60%, var(--bg))` |
+| `--accent-1` | `color-mix(in oklch, var(--accent) 8%, var(--bg))` |
+| `--accent-2` | `color-mix(in oklch, var(--accent) 16%, var(--bg))` |
+| `--accent-3` | `color-mix(in oklch, var(--accent) 32%, var(--bg))` |
+| `--accent-4` | `color-mix(in oklch, var(--accent) 60%, var(--bg))` |
 | `--accent-5` | `var(--accent)` |
 | `--accent-6` | `var(--accent-strong)` |
 | `--surface-1` | `var(--bg)` |
@@ -968,8 +974,6 @@ Exact mirror of the `:root` blocks in `css/tokens.css`
 | `--success-soft` | `rgb(47, 125, 79, 0.12)` |
 | `--warning` | `#806414` |
 | `--warning-soft` | `rgb(128, 100, 20, 0.13)` |
-| `--orange` | `#a85f32` |
-| `--orange-soft` | `rgb(168, 95, 50, 0.13)` |
 | `--danger` | `#c01622` |
 | `--danger-soft` | `rgb(192, 22, 34, 0.1)` |
 | `--info` | `#1f63c4` |
@@ -1006,8 +1010,6 @@ Exact mirror of the `:root` blocks in `css/tokens.css`
 | `--success-soft` | `rgb(78, 194, 126, 0.14)` |
 | `--warning` | `#d8bd72` |
 | `--warning-soft` | `rgb(216, 189, 114, 0.14)` |
-| `--orange` | `#d08c5b` |
-| `--orange-soft` | `rgb(208, 140, 91, 0.15)` |
 | `--danger` | `#ff4d54` |
 | `--danger-soft` | `rgb(255, 77, 84, 0.15)` |
 | `--info` | `#6fb0e6` |

package/docs/theming.md

@@ -141,7 +141,72 @@ coarser-grained handles.
   these; override one to slot your app's own layers around the
   framework's without specificity/`z-index` wars.
 
-All four tiers are in the DTCG export and the JS token model.
+All four tiers are in the DTCG export and the JS token model. The full
+five-tier colour model and its rules live in
+[ADR-0001](adr/0001-color-system.md).
+
+## Display colorways (`data-bronto-skin`)
+
+Opt-in single-hue colorways, shipped as a **separate** entrypoint (never in
+the default bundle):
+
+```html
+<link rel="stylesheet" href="@ponchia/ui/css/skins.css" />
+<html data-theme="dark" data-bronto-skin="phosphor-green">
+  …
+</html>
+```
+
+`data-bronto-skin="amber-crt | phosphor-green | e-ink"` is a **root-level**
+choice, like `data-theme` — put it on `:root`/`<html>`. It re-points the one
+`--accent` (per theme, authored in OKLCH); the derived family, focus ring,
+dot-matrix and glyphs follow automatically, and status colours + the neutral
+canvas are untouched. A colorway is _not_ a second accent — it swaps the one
+you have, so the one-accent discipline holds.
+
+- **Root-level only.** The accent's derived family (`--accent-strong`/`-text`,
+  `--field-dot-accent`, `--accent-1..6`, …) is `color-mix(… var(--accent) …)`
+  declared on `:root`; it only re-evaluates on the element that carries it. A
+  skin on a subtree would leave that family stale, so the selectors are
+  `:root`-anchored and a subtree skin simply no-ops.
+- **Phosphor bloom.** The `amber-crt` / `phosphor-green` skins set
+  `--dotmatrix-glow` (a Tier-3 display knob, default `0`) in dark, so the
+  dot-matrix gains a CRT-style glow. Set it yourself on any `.ui-dotmatrix`
+  to tune the bloom.
+- **Contrast-gated.** Every shipped skin accent meets the same WCAG AA / 3:1
+  floors as the core palette — see [contrast.md](contrast.md) → "Display
+  colorways". (Your _own_ `--accent` re-brand is still your obligation; the
+  guarantee covers the shipped palettes and skins.)
+
+## Data-viz palette (`@ponchia/ui/css/dataviz.css`)
+
+Opt-in Tier-4 chart colours for dashboards — **charts only, never UI chrome**
+(a build gate fails on `var(--chart-*)` in component CSS), and never in the
+default bundle.
+
+```html
+<link rel="stylesheet" href="@ponchia/ui/css/dataviz.css" />
+```
+
+```js
+// resolved hex for canvas / SVG / Chart.js etc.
+import charts from '@ponchia/ui/charts.json' with { type: 'json' };
+const series = charts.dark.categorical; // ['#ff3b41', '#e69f00', …] — series 0 = accent
+```
+
+- **Categorical `--chart-1..8`** — hybrid accent-led: series 1 is the live
+  `var(--accent)` (your brand leads), series 2–8 are the Okabe-Ito
+  colourblind-safe set. The set is **gated for mutual distinguishability under
+  normal + simulated protanopia/deuteranopia/tritanopia** (OKLab ΔE).
+- **Sequential `--chart-seq-1..6`** — single-hue light→dark, for
+  heatmaps/intensity. **Diverging `--chart-div-1..7`** — blue↔neutral↔orange,
+  for ±/gains-losses.
+- **Pattern fills `--chart-pattern-1..8`** — a dot-matrix second channel so
+  colour is never the sole signal (WCAG 1.4.1). Pair colour N with pattern N:
+  `background: var(--chart-2); background-image: var(--chart-pattern-2); background-size: var(--chart-pattern-size); --chart-pattern-ink: rgb(0 0 0 / .34);`
+- A chart colour's WCAG ratio vs the background is published **advisory** in
+  [contrast.md](contrast.md) (a fill is not body text) — pick a darker series
+  for thin lines/points, or lean on the pattern.
 
 ## Accessibility markup contracts