@ponchia/ui 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,12 +1,353 @@
 # Changelog
 
-> **Versioning:** pre-1.0, breaking changes ship in the _minor_. Pin
-> `~0.x`; `^0.x` does **not** protect you. See README → Versioning, and
+> **Versioning:** pre-1.0, breaking changes ship in the _minor_. Pin to the
+> minor — `~0.4.0` (equivalently `^0.4.0`) resolves to `>=0.4.0 <0.5.0`; a bare
+> `^0` / `*` wildcard does **not** protect you. See README → Versioning, and
 > the deprecation policy in CONTRIBUTING.md.
 
+## 0.5.0 — 2026-06-02
+
+A **minor** that builds out the "analytical & generated-report UI" identity: a
+full suite of opt-in **communication primitives** — SVG annotations, legends,
+text/evidence marks, leader-line connectors, a guided-focus spotlight, a
+crosshair/readout, a selection-state vocabulary, label declutter + direct labels
+(`declutterLabels`/`directLabels`), and a source/citation/provenance **trust
+layer** — plus a consolidation pass over them. Each owns its visual grammar and
+pure geometry and refuses to own scales/state/hit-testing (no chart engine).
+
+Per the project's versioning policy, breaking changes ship in the minor. This
+release carries three: the opt-in report kit's chart data key moved into the new
+legend layer (`.ui-chart__legend`/`__swatch` removed — see Changed and
+[`MIGRATIONS.json`](MIGRATIONS.json)), annotation arrowheads now render via
+the shared connectors geometry kernel (a small path-shape change), and the
+opt-in marks' rationed-accent tone was renamed `evidence`→`accent` to match the
+rest of the analytical tone vocabulary. Everything else is additive and opt-in,
+save for the tiny `.ui-shortcut` keyboard-hint primitive that joins the core
+layer; the rest of the default `dist/bronto.css` is unchanged. Also folds in the
+0.4.x maintenance hardening that had not yet been released.
+
+### Added
+
+- **SVG annotations** (`@ponchia/ui/css/annotations.css`,
+  `@ponchia/ui/annotations`, `.ui-annotation*`, `ui.annotation()`): an opt-in
+  annotation layer for charts, reports, and analytical figures, following the
+  d3-annotation grammar (a **subject** marks the thing, a **connector** points
+  away, a **note** carries the text). Ships a class grammar (variants for
+  label/callout/elbow/curve/circle/rect/threshold/badge/bracket/band/slope/
+  compare/cluster/axis/timeline/evidence, six tones, and opt-in
+  `draw`/`reveal`/`pulse`/`focus` motion that respects `prefers-reduced-motion`)
+  plus tiny geometry helpers that return SVG strings only — they own no chart
+  scales, mutate no DOM, and provide no edit mode. Documented in
+  [`docs/annotations.md`](docs/annotations.md) and gated by `check:report`.
+- **Legends / data keys** (`@ponchia/ui/css/legend.css`, `.ui-legend*`,
+  `ui.legend()`/`ui.legendItem()`/`ui.legendSwatch()`, `initLegend`): an opt-in,
+  standalone data-key layer that reads the `--chart-*` palette tokens.
+  Categorical, continuous gradient (sequential + `--diverging`), threshold, and
+  pattern keys; swatch colour set inline (`--chart-color`) or via
+  `.ui-legend__swatch--1..8` index helpers; vertical/compact/with-values
+  layouts. WCAG 1.4.1 by construction (the text label is the non-colour
+  channel), with `forced-colors` and print care. Optional interactive
+  (series-toggling) entries are `<button aria-pressed>` controls: `initLegend`
+  flips `aria-pressed`/`.is-inactive` and emits `bronto:legend:toggle`
+  (`{ series, active }`) — the host owns hiding the series and any `aria-live`
+  announcement (it is never a chart engine). Optional `useLegend` hook in the
+  React/Solid/Qwik bindings. New `check:legend` gate proves swatch colours are a
+  subset of `tokens/charts.js` and never a raw hex. Documented in
+  [`docs/legends.md`](docs/legends.md).
+- **Text marks / evidence** (`@ponchia/ui/css/marks.css`, `.ui-mark*`,
+  `.ui-bracket-note*`, `ui.mark()`/`ui.bracketNote()`): an opt-in layer of
+  sober, report-grade emphasis for running prose — the counterpart to SVG
+  annotations (annotations call out a figure, marks call out a sentence). Inline
+  `.ui-mark` (highlight/underline/box/strike; `--accent` + status
+  tones; `--draw` reduced-motion-safe sweep) for use on `<mark>`, and
+  `.ui-bracket-note` for bracketing a whole passage. Pure CSS on semantic
+  tokens, monochrome by default, with `forced-colors` care. Documented in
+  [`docs/marks.md`](docs/marks.md).
+- **Connectors / leader lines** (`@ponchia/ui/css/connectors.css`,
+  `@ponchia/ui/connectors`, `.ui-connector*`, `initConnectors`, `ui.connector()`):
+  an opt-in layer that draws a line between two DOM elements (the
+  page-coordinate cousin of annotations). Pure geometry helpers
+  (`connectRects`/`connectorPath`/`arrowHead`/…) that return SVG strings and own
+  no DOM, an `.ui-connector` overlay grammar (straight/elbow/curve, arrow/dot
+  ends, tones, dashed, `--draw`), and an optional `initConnectors` behavior that
+  draws + tracks on resize/scroll. `useConnectors` in the bindings. Documented in
+  [`docs/connectors.md`](docs/connectors.md).
+- **Spotlight / guided focus** (`@ponchia/ui/css/spotlight.css`, `.ui-spotlight*`,
+  `.ui-tour-note*`, `initSpotlight`, `ui.spotlight()`): an opt-in guided-focus
+  overlay — a box-shadow cutout over a target element, optional ring, and a
+  callout note. `initSpotlight` positions the cutout (`--spot-x/y/w/h`) and
+  re-places on resize/scroll and when `data-target` changes. Deliberately **not**
+  a tour engine — the host owns step order/advancing/visibility. `useSpotlight`
+  in the bindings. Documented in [`docs/spotlight.md`](docs/spotlight.md).
+- **Crosshair / readout** (`@ponchia/ui/css/crosshair.css`, `.ui-crosshair*`,
+  `.ui-readout`, `initCrosshair`, `ui.crosshair()`): an opt-in plot ruler +
+  pinned readout. `initCrosshair` tracks the pointer over a
+  `[data-bronto-crosshair]` plot, sets `--crosshair-x/y`, and dispatches
+  `bronto:crosshair:move` with px + 0–1 fractions — it reports position only and
+  never maps pixels to data (that needs the host's scales). `useCrosshair` in the
+  bindings. Documented in [`docs/crosshair.md`](docs/crosshair.md).
+- **Selection states** (`@ponchia/ui/css/selection.css`, `.ui-sel*`,
+  `ui.sel()`): a tiny cross-cutting selection-emphasis vocabulary
+  (`--on`/`--off`/`--maybe`) reusable on chart marks, table rows, list items, or
+  map regions. The carve-out from brush/lasso — Bronto styles the states; the
+  host owns the selection/hit-test logic. Documented in
+  [`docs/selection.md`](docs/selection.md).
+- **Sources, citations & provenance** (`@ponchia/ui/css/sources.css`,
+  `.ui-citation`/`.ui-source-card`/`.ui-source-list`/`.ui-provenance`,
+  `ui.citation()`/`ui.source()`/`ui.provenance()`): an opt-in, CSS-only **trust
+  layer** for generated reports and AI output — the grammar for "where did this
+  come from?". A cross-cutting `.ui-src--*` state (verified/reviewed/generated/
+  unverified/stale/conflict) sets a rationed tone, always paired with an
+  author-written label (never colour alone). Bronto owns the grammar + states;
+  the host owns fetching, citation numbering, and trust. The first
+  frontier-primitive beyond the analytical suite. Documented in
+  [`docs/sources.md`](docs/sources.md).
+- **Keyboard-shortcut hint** (`.ui-shortcut` + `.ui-shortcut__sep`, core): a tiny
+  universal-chrome primitive that lays out one or more `.ui-kbd` keys as a chord
+  (`⌘`+`K`) or sequence (`G` then `I`) with a dim connective. The command tier's
+  smallest piece, broadly useful outside a palette (menu items, buttons,
+  tooltips). Class-only, like `.ui-kbd`.
+- **Lifecycle / system state** (`@ponchia/ui/css/state.css`, `.ui-state`
+  (+`__label`/`__detail`/`--busy`) with canonical state modifiers
+  (saving/saved/queued/offline/stale/conflict/error/locked/reviewed/
+  needs-review), `.ui-syncbar`, `ui.state()`): an opt-in, CSS-only vocabulary for
+  the states apps actually live in — a labelled state object with a rationed tone
+  and a page/document sync bar. The label is the state (never colour alone);
+  `--busy` pulses the indicator (reduced-motion-safe). Bronto ships the visual
+  states + canonical wording; the host owns the state machine, retry, and
+  persistence. Frontier candidate #2. Documented in [`docs/state.md`](docs/state.md).
+- **Generated content & AI trust** (`@ponchia/ui/css/generated.css`,
+  `.ui-generated`/`.ui-origin-label`/`.ui-reasoning`/`.ui-tool-log`/`.ui-tool-call`,
+  `ui.originLabel()`): an opt-in, CSS-only set of **trust surfaces** for AI /
+  system-generated content — a marked region, an origin label, and quiet
+  native-`<details>` reasoning + tool-call logs. Not a chat kit; no
+  fabricated-confidence widget. Bronto styles disclosure/origin/trace, the host
+  owns model metadata, redaction, and safety. Pairs with the source layer.
+  Documented in [`docs/generated.md`](docs/generated.md).
+- **Workbench** (`@ponchia/ui/css/workbench.css`, `.ui-inspector`/`.ui-property`/
+  `.ui-selectionbar`): an opt-in, CSS-only core for tool UIs — a selected-object
+  inspector panel, denser property rows, and a raised selection action bar.
+  Layout + affordances only; resizable split panes and drag handles are
+  deferred. Documented in [`docs/workbench.md`](docs/workbench.md).
+- **Command palette** (`@ponchia/ui/css/command.css`, `.ui-command` (+
+  `__input`/`__list`/`__group`/`__item`/`__shortcut`/`__meta`/`__empty`),
+  `initCommand`, `useCommand`): an opt-in CSS shell + behavior — filter +
+  keyboard-navigate a DOM-authored command list (roving focus, group hiding,
+  full keyboard), emitting `bronto:command:select` ({ value, label }) and
+  `bronto:command:close`. Bronto navigates; the host owns the action registry,
+  routing, and execution. No global Cmd/Ctrl+K. Completes the command tier
+  (frontier #3) atop the shipped `ui-shortcut`. Documented in
+  [`docs/command.md`](docs/command.md).
+- **Label declutter** (`@ponchia/ui/annotations` `declutterLabels`): a
+  deterministic, order-preserving **1-D** label de-overlap helper (sort, push
+  apart by `size + gap`, slide to fit `max`) — pure, no DOM/scales. Not a 2-D
+  collision solver. Documented in [`docs/annotations.md`](docs/annotations.md).
+- **Direct labels** (`@ponchia/ui/annotations` `directLabels`): the
+  direct-labeling companion to `declutterLabels` — it declutters labels along an
+  axis **and** draws the leader from each anchor to its placed label, reusing the
+  connectors geometry kernel. Returns `[{ x, y, anchor, key, d }]` (the `d` feeds
+  a `ui-annotation__connector`). Deterministic and pure: no scales, no DOM, no
+  2-D placement (the 1-D core of Labella, completed with leaders). Documented in
+  [`docs/annotations.md`](docs/annotations.md).
+- **Connectors** (`@ponchia/ui/connectors`, `@ponchia/ui/css/connectors.css`,
+  `initConnectors`, `useConnectors`, `ui.connector()`) and **Spotlight**
+  (`css/spotlight.css`, `initSpotlight`, `ui.spotlight()`) — leader lines between
+  DOM elements and a guided-focus overlay; both opt-in, geometry/visual only
+  (the host owns layout/tour state).
+- **Crosshair / readout** (`css/crosshair.css`, `initCrosshair`,
+  `ui.crosshair()`) and **selection states** (`css/selection.css`, `ui.sel()`) —
+  a plot ruler that reports pointer position (not data), and a cross-cutting
+  `.ui-sel--on/off/maybe` emphasis vocabulary (the host owns brush/hit-test).
+- **`@ponchia/ui/css/analytical.css`** — a convenience roll-up that bundles the
+  seven analytical leaves (annotations, legend, marks, connectors, spotlight,
+  crosshair, selection) into one import. Add `dataviz.css`/`report.css`
+  separately as needed.
+
+### Fixed
+
+- The optional Qwik binding (`@ponchia/ui/qwik`) is now built from the packed
+  tarball in CI **and** release, alongside React/Solid — closing a coverage gap
+  (it was documented as optimizer-proven but no job actually built it). Also
+  covered by `check:pack`, the size report, and the dead-code config.
+
+### Changed
+
+- **Breaking (opt-in report kit):** the chart data key moved out of
+  `css/report.css` into the standalone `css/legend.css`. `.ui-chart__legend` →
+  `.ui-legend` (now with `.ui-legend__item`/`.ui-legend__label` rows) and
+  `.ui-chart__swatch` → `.ui-legend__swatch`. Import `@ponchia/ui/css/legend.css`
+  beside the report kit; see [`MIGRATIONS.json`](MIGRATIONS.json) and
+  [`docs/legends.md`](docs/legends.md). The `--chart-color`/`--chart-pattern`
+  swatch contract is unchanged, so the rename is mechanical.
+- **Breaking (opt-in marks):** the rationed-accent **tone** on `.ui-mark` and
+  `.ui-bracket-note` was renamed `evidence` → `accent` (`ui-mark--evidence` →
+  `ui-mark--accent`, `ui-bracket-note--evidence` → `ui-bracket-note--accent`;
+  `ui.mark({ tone: 'accent' })` / `ui.bracketNote({ tone: 'accent' })`) so the
+  accent tone reads the same across every analytical primitive (it already was
+  `accent` on `ui.connector`/`ui.annotation`). `.ui-annotation--evidence` is
+  **unchanged** — it is a marker _variant_ (a proof/source shape), not a tone.
+  Mechanical whole-token rename; see [`MIGRATIONS.json`](MIGRATIONS.json).
+- **Consolidation:** the SVG geometry is single-sourced in the `connectors`
+  kernel — `@ponchia/ui/annotations` now builds its connectors on it, so a
+  line/curve/arrow/dot is drawn one way across both. `connectorLine`/`Curve`/
+  `EndDot` output is byte-identical; **`connectorEndArrow` is the one
+  (minor-breaking) shape change** — the arrowhead now matches the connectors
+  arrowhead. New `check:helpers-dts` gate keeps the hand-maintained
+  `annotations`/`connectors` `.d.ts` in parity with their runtime exports.
+- The Doto webfont now ships as **woff2 only** (Brotli) instead of uncompressed
+  TTF: ~5.7 kB per weight vs ~137 kB, cutting the six-weight payload from ~823 kB
+  to ~35 kB (the dot-matrix glyphs compress ~96%) and shrinking the unpacked
+  tarball by roughly the same. No TTF fallback is carried — woff2 is supported by
+  the entire browser floor (ADR-0002: Chrome 125 / Safari 18 / Firefox 129).
+  `@font-face` is internal, so this is transparent to consumers; only self-hosts
+  that referenced `fonts/doto-*.ttf` directly need to point at `*.woff2`.
+- `docs/architecture.md` now ships in the package, so the offline rationale the
+  shipped ADRs link to resolves inside the tarball.
+- `docs/stability.md` clarifies that `data-surface`/`data-density`/
+  `data-contrast` are **convenience presets**, not part of the stability
+  contract; `data-theme` (light/dark) remains the contractual base.
+
+### Internal
+
+- Token values are single-sourced in `tokens/index.js` (`cssVars`); the
+  `css/tokens.css` palette is generated from it, so the dark palette is authored
+  once instead of in three places (the shipped CSS is byte-identical).
+- `behaviors/index.js` is split into per-behavior modules behind the same public
+  barrel (no surface change).
+- Drift-gate consolidation (`assertFresh`), a Qwik type smoke + stronger
+  class-recipe wiring test, the APCA advisory widened to the accent text across
+  the core palette and every colorway (still advisory; WCAG 2.1 AA stays the
+  hard gate), an OLED computed-style smoke test, and several doc reconciliations.
+- New `demos.spec` e2e sweep runs the console-error / uncaught-exception /
+  failed-response guards **and** an axe scan over every per-feature demo page
+  (annotations, legends, marks, connectors, spotlight, crosshair, selection,
+  report) in both themes and cross-browser — previously only `/demo/` was
+  guarded, so a throw or 404 on those SVG-heavy pages could not fail CI.
+- The `check:dist` payload ceiling was raised to 80 kB raw / 14.5 kB gzip (from
+  78 kB / 13.5 kB). The default bundle was sitting ~21 bytes under the old gzip
+  gate — the analytical primitives are opt-in leaves and stay out of it, so this
+  is residual prior growth; the bump restores a real ~3% raw / ~7% gzip margin
+  so an ordinary token addition no longer trips an unrelated PR.
+
+## 0.4.1 — 2026-06-01
+
+Patch hardening for the public framework surface, plus the first step of the
+modern-platform motion direction (see [ADR-0002](docs/adr/0002-scope-and-2026-baseline.md)).
+
+### Added
+
+- **Static report kit — `@ponchia/ui/css/report.css` + `docs/reporting.md`.**
+  An opt-in, PDF-first report layer for LLM-authored and hand-authored HTML:
+  report covers, headers, section numbering, summaries, findings, evidence
+  blocks, source/appendix/footnote blocks, chart wrappers/legends/fallback
+  tables, and print utilities (`ui-print-only`, `ui-screen-only`,
+  `ui-break-before`, `ui-break-after`, `ui-keep`, `ui-print-exact`). It stays
+  out of the default bundle, ships with the offline LLM docs, and is covered by
+  a report fixture, package/export checks, and class-contract validation.
+  The layer also includes compact covers, unnumbered report sections, simple
+  static chart-bar primitives, and evidence-table framing rules so generated
+  reports need less private CSS.
+- **Zero-JS enter _and_ exit motion for native-`<dialog>` overlays.** Modal and
+  drawer (and their backdrop) now fade/scale **both ways** via `@starting-style`
+  + `transition-behavior: allow-discrete` — previously they only animated in and
+  vanished on close. Pure CSS, reduced-motion-aware (snaps with no flash), scoped
+  to `dialog.ui-modal` so the controlled `.is-open` path is unchanged.
+- **Enter/exit motion extended to popover, toast, and accordion** (ADR-0002
+  "next, same approach"):
+  - **Popover** (`.ui-popover`) fades + slides both ways via the same
+    `@starting-style` + `allow-discrete` recipe, covering both the native
+    `[popover]` top-layer path and the `.is-open` fallback. Zero JS,
+    reduced-motion-aware.
+  - **Toast** (`.ui-toast`) now plays a CSS fade-out on dismiss instead of being
+    yanked from the DOM. The `toast()` behavior adds `.is-leaving` and removes
+    the node on `transitionend` (with a timeout fallback); it falls back to
+    instant removal under reduced-motion or where no transition is computed, so
+    the persistent `aria-live` region is undisturbed.
+  - **Accordion** (`.ui-accordion`, native `<details>`) animates auto-height
+    open/close via `::details-content` + `interpolate-size: allow-keywords` +
+    `content-visibility … allow-discrete`. Strict progressive enhancement —
+    gated on `@supports selector(::details-content)`; engines without it (today,
+    Firefox/Safari) simply snap, exactly as before.
+- **Scroll-driven motion (progressive enhancement).** `.ui-scroll-progress` (a
+  reading-progress bar on a `scroll(root block)` timeline, RTL-aware) and
+  `.ui-scroll-reveal` (a JS-free, IntersectionObserver-free reveal on a `view()`
+  timeline). Both are gated on `@supports (animation-timeline: …)` and
+  `prefers-reduced-motion: no-preference`, so engines without scroll timelines
+  (today, Firefox/Safari) keep a static end-state and reduced-motion users get
+  no movement.
+- **View Transitions (progressive enhancement).** A `.ui-vt` helper
+  (`view-transition-name: var(--ui-vt-name)`) to morph an element across a
+  same-document `startViewTransition()` or a cross-document navigation, an
+  on-brand default for the `::view-transition-*(root)` cross-fade, and a
+  **reduced-motion kill-switch** for the `::view-transition-*` pseudo-tree
+  (which the platform does *not* quiet automatically). Cross-document nav stays
+  a documented one-liner you add yourself (`@view-transition { navigation: auto }`
+  is document-global, so it can't be layered or scoped by the framework).
+- **Optional Qwik bindings — `@ponchia/ui/qwik`.** Same thin-adapter shape as
+  the React/Solid bindings (`useDialog`, `useToast`, … `useBrontoBehavior`, plus
+  the `cls`/`ui`/`cx` + `applyStoredTheme` re-exports), wrapping the SSR-safe
+  behaviors in Qwik's `useVisibleTask$` (run on visible, cleanup on dispose) so a
+  resumable page stays zero-JS until interaction. Scope a behavior with a Qwik
+  signal: `useDialog({ root: useSignal() })`. `@builder.io/qwik` is an **optional**
+  peer dependency, so the core stays zero-dependency. New `examples/qwik-vite`
+  builds it through the real Qwik optimizer.
+- **OLED true-black surface variant — `data-surface="oled"`.** The dark base is
+  now a readable elevated near-black (see Changed); this opt-in root attribute
+  restores pure black for OLED power-saving and the original "Nothing" look.
+  CSS-only preset (like `data-density`/`data-contrast`), scoped to the dark
+  theme. Documented in `docs/theming.md`.
+- **APCA advisory for dark text.** `check:contrast` now emits a non-failing
+  warning when a dark text pairing falls below its perceptual APCA target (WCAG
+  stays the hard gate) — the early-warning that would have caught the illegible
+  dim text. The kitchen-sink demo gains a unified theme picker (theme × colorway
+  × surface, all persisted).
+- **[ADR-0003](docs/adr/0003-theme-model.md)** records the theme model: a binary
+  light/dark base × one-knob derivation × orthogonal axes (colorway, surface,
+  contrast, density), and why a flat named-theme catalog is rejected.
+- React and Solid Vite examples, CI/release matrix coverage for those examples,
+  runtime binding tests, public API stability docs, a release runbook, and
+  `npm run size:report`.
+
+### Changed
+
+- **Dark theme re-tuned for readability.** The dark base moved off pure `#000`
+  to an elevated near-black (`--bg #121212`, panels `#1c1c1c`/`#222`/`#242424`,
+  lines `#383838`/`#555`); body text eased `#f2f2f2 → #e6e6e6` (APCA Lc 99 → ~91,
+  removing halation) and **dim/meta text raised `#858585 → #a0a0a0`** (APCA
+  Lc ~36 → ~49 — the actual "hard to read" fix). WCAG 2.x over-rates contrast on
+  pure black, so pairings "passed" while reading poorly; the re-tune clears WCAG
+  AA on every pairing and lifts perceptual (APCA) contrast. Accent and status
+  colours are unchanged; true black stays available via `data-surface="oled"`.
+- **Browser floor raised to Chrome/Edge 125+, Safari 18+, Firefox 129+**
+  (early–mid 2025). A deliberate greenfield stance (ADR-0002) so the framework
+  can build natively on `@starting-style`, `transition-behavior: allow-discrete`,
+  `oklch()`/relative color, and `light-dark()`. No fallbacks ship below the
+  floor; not-yet-cross-engine features (View Transitions, scroll-driven
+  animations) are enhancement-only and degrade to a static end-state.
+- Bundle budget nudged for the new motion: gzip 13.0 → 13.5 kB (for the dialog
+  enter/exit work) and raw 76 → 77 kB (for the popover/toast/accordion motion
+  plus the scroll-driven + view-transition CSS). Gzip held at ~13.1 kB — it
+  compresses well — so the compressed payload still has headroom.
+
+### Fixed
+
+- React and Solid bindings now resolve scoped roots on mount, so `{ root: ref }`
+  and resolver callbacks work after framework refs are assigned. Nullish resolver
+  results normalize to default behavior instead of crashing destructuring
+  behavior initializers.
+- Scoped behavior roots now resolve controlled ids root-first, then
+  document-wide. This keeps existing body/portal-mounted dialogs, popovers, and
+  disclosure panels working while preventing earlier duplicate ids outside an
+  island from shadowing the in-root target.
+- `data-bronto-dismiss="<selector>"` ignores malformed selectors instead of
+  throwing during event handling.
+- The one-node glyph mask path now includes a WebKit-prefixed mask declaration,
+  and the OKLCH accent ramp uses an explicit white/black neutral endpoint for
+  cross-engine browser parity.
+
 ## 0.4.0 — 2026-05-31
 
-The color-system release — [ADR-0001](docs/adr/0001-color-system.md) steps 1–7.
+The color-system release — [ADR-0001](docs/adr/0001-color-system.md) steps 1–8.
 A governed evolution beyond pure monochrome: the tier model is written down and
 **enforced** (`check:color-policy`), and the "Nothing" look is proven to be a
 _skin, not the architecture_ — opt-in **colorways** (amber CRT · phosphor green ·
@@ -34,11 +375,11 @@ categorical color lands later it ships as a governed, opt-in data-viz module
 ### Added
 
 - **The `--accent-1..6` ramp is now perceptually even (OKLCH).** Steps 1–4 mix
-  the accent toward the background `in oklch` instead of `in srgb` (ADR-0001
-  step 8), so the ramp reads as evenly-spaced — better for charts / multi-state
-  surfaces. `scripts/gen-resolved.mjs` learned to resolve `color-mix(in oklch,…)`
-  → hex (bit-for-bit matching browser `color-mix`), so `tokens/resolved.json`,
-  the DTCG export, and `docs/reference.md` all carry the new values. These are
+  the accent `in oklch` instead of using the old sRGB ramp (ADR-0001 step 8), so
+  the ramp reads as evenly-spaced. `scripts/gen-resolved.mjs` learned to resolve
+  `color-mix(in oklch,…)` → hex with the same one-channel tolerance browsers
+  show, so `tokens/resolved.json`, the DTCG export, and `docs/reference.md` all
+  carry the new values. These are
   token **values** (non-contractual under the 0.x policy) and the ramp is not
   consumed by any shipped component, so there is **no change to any component's
   rendering** — only consumers using `var(--accent-1..4)` directly see the
@@ -102,10 +443,9 @@ categorical color lands later it ships as a governed, opt-in data-viz module
 - **`check:skins` gate** — `css/skins.css` can't drift from `tokens/skins.js`,
   every skin defines `--accent`, and colorways stay out of the default bundle.
 - **[ADR-0001 — Color system](docs/adr/0001-color-system.md)** — the five-tier
-  color constitution and the backward-compatible roadmap. Steps 1–6 are
-  implemented in this release (gate + colorways + Tier-3 tokens + OKLCH for new
-  work + APCA advisory); the data-viz categorical module and any core-ramp
-  OKLCH migration are deliberately deferred.
+  color constitution and the backward-compatible roadmap. Steps 1–8 are
+  implemented in this release: gate + colorways + Tier-3 tokens + OKLCH for new
+  work + APCA advisory + data-viz + OKLCH core accent ramp.
 
 ## 0.3.6 — 2026-05-31
 

package/MIGRATIONS.json

@@ -0,0 +1,92 @@
+{
+  "$comment": "Machine-readable rename/removal map for @ponchia/ui upgrades (classes, attributes, and tokens). Generated-by-hand from CHANGELOG BREAKING sections; consumed by docs/migrations/*.md and any codemod/sed recipe. 'safe' rules are mechanically rewritable (whole-token, no semantic change); 'manual' rules need human judgement (concept moved or removed, not a 1:1 rename).",
+  "migrations": [
+    {
+      "from": "0.2",
+      "to": "0.3",
+      "summary": "Entire non-ui-* legacy vocabulary removed; everything is now under the .ui-* contract and the check-classes drift gate.",
+      "safe": [
+        { "old": "skip-link", "new": "ui-skiplink" },
+        { "old": "site-nav", "new": "ui-sitenav" },
+        { "old": "site-menu", "new": "ui-sitemenu" },
+        { "old": "theme-toggle", "new": "ui-themetoggle", "prefix": true },
+        { "old": "app-shell", "new": "ui-app-shell", "prefix": true },
+        { "old": "app-rail", "new": "ui-app-rail", "prefix": true },
+        { "old": "app-topbar", "new": "ui-app-topbar", "prefix": true },
+        { "old": "app-toolbar", "new": "ui-app-toolbar", "prefix": true },
+        { "old": "app-nav", "new": "ui-app-nav", "prefix": true },
+        { "old": "app-panel", "new": "ui-app-panel", "prefix": true },
+        { "old": "app-content", "new": "ui-app-content", "prefix": true },
+        { "old": "app-main", "new": "ui-app-main", "prefix": true },
+        { "old": "app-metrics", "new": "ui-app-metrics", "prefix": true },
+        { "old": "app-metric", "new": "ui-app-metric", "prefix": true },
+        { "old": "app-empty-state", "new": "ui-app-empty-state", "prefix": true }
+      ],
+      "manual": [
+        {
+          "old": "hero / project-* / post-card / essay-* / page-* / home-* / signal-panel / worklog-summary",
+          "new": "the ui-* content layer",
+          "note": "Long-form content: .ui-prose / .ui-quote. Cards: .ui-card. Layout: .ui-grid / .ui-stack. Site chrome: the ui-site* shell. No 1:1 mapping — re-compose with the content primitives."
+        },
+        {
+          "old": "callout",
+          "new": "ui-alert",
+          "note": "Tone modifiers differ (.ui-alert--info/-success/-warning/-danger); re-pick the tone."
+        },
+        {
+          "old": "metric-tile",
+          "new": "ui-app-metric",
+          "note": "Now scoped to the admin shell vocabulary; standalone stat usage should wrap in .ui-app-metrics."
+        },
+        {
+          "old": "tag-list / tag",
+          "new": "ui-tags / ui-tag",
+          "note": "Compact variant .tag-list--compact → .ui-tags--compact; verify accent-on-accent contrast (see CHANGELOG 0.3.0 a11y fix)."
+        }
+      ],
+      "codemod": "See docs/migrations/0.2-to-0.3.md for a ready-to-run ripgrep+sed recipe covering the 'safe' rules."
+    },
+    {
+      "from": "0.3",
+      "to": "0.4",
+      "summary": "Additive colour-system release (ADR-0001); the default dist/bronto.css renders identically. No class or attribute renames. One orphan token pair removed.",
+      "safe": [],
+      "manual": [
+        {
+          "old": "--orange / --orange-soft",
+          "new": "(removed — re-declare in a consumer :root override if referenced)",
+          "note": "Orphan token pair: defined in the token mirrors but referenced by no shipped component and documented nowhere, and untiered under the new colour model. Removed under the CONTRIBUTING 'provably-unreferenced surface' exception. If you used it: :root { --orange: #a85f32; --orange-soft: rgb(168 95 50 / 0.13); }"
+        }
+      ],
+      "codemod": "No class codemod needed (no renames). See docs/migrations/0.3-to-0.4.md; audit usage with: rg -- '--orange' ."
+    },
+    {
+      "from": "0.4",
+      "to": "0.5",
+      "summary": "Adds the analytical-primitives suite (annotations, legend, marks, connectors, spotlight, crosshair, selection + the analytical.css roll-up); all additive/opt-in. Three breaking changes: the chart data key moved out of the report kit into the standalone Legends layer (`.ui-chart__legend`/`.ui-chart__swatch` removed); annotation arrowheads now render via the shared connectors geometry kernel (a small visual path change, no API change); and the marks/bracket-note rationed-accent tone was renamed `evidence`→`accent` to match the annotation/connector tone vocabulary (`.ui-annotation--evidence` stays — it's a marker variant, not a tone).",
+      "safe": [
+        { "old": "ui-chart__swatch", "new": "ui-legend__swatch" },
+        { "old": "ui-mark--evidence", "new": "ui-mark--accent" },
+        { "old": "ui-bracket-note--evidence", "new": "ui-bracket-note--accent" }
+      ],
+      "manual": [
+        {
+          "old": "ui.mark({ tone: 'evidence' }) / ui.bracketNote({ tone: 'evidence' })",
+          "new": "tone: 'accent'",
+          "note": "The rationed-accent tone option on the mark/bracket-note recipes is now 'accent' (was 'evidence'), matching ui.connector/ui.annotation. Do NOT rewrite ui.annotation({ variant: 'evidence' }) or the 'evidence' subject marker — those are a marker shape, not a tone, and are unchanged."
+        },
+        {
+          "old": "ui-chart__legend",
+          "new": "ui-legend",
+          "note": "Also import '@ponchia/ui/css/legend.css' beside report.css, and wrap each entry's content as <li class=\"ui-legend__item\"> … <span class=\"ui-legend__label\">…</span>. The swatch's --chart-color/--chart-pattern inline contract is unchanged; the categorical --chart-N colour is also available via .ui-legend__swatch--N. See docs/legends.md."
+        },
+        {
+          "old": "connectorEndArrow (annotations)",
+          "new": "connectorEndArrow (unchanged API)",
+          "note": "No code change needed. The function signature is identical; only the rendered arrowhead path differs slightly now that it shares the connectors geometry kernel. Re-baseline any exact-path SVG snapshot tests of annotation arrowheads."
+        }
+      ],
+      "codemod": "rg -l 'ui-chart__legend|ui-chart__swatch' then s/ui-chart__swatch/ui-legend__swatch/g and rework the ul.ui-chart__legend wrapper into ul.ui-legend with li.ui-legend__item rows. See docs/legends.md."
+    }
+  ]
+}