@ponchia/ui 0.6.6 → 0.6.8

package/docs/figure.md

@@ -0,0 +1,71 @@
+# Figure
+
+`@ponchia/ui/css/figure.css` is an opt-in analytical/report figure stage. It
+does not render charts. It gives charts, diagrams, screenshots, and annotated
+SVGs a stable frame: caption, media stage, optional overlay, optional key, and
+fallback data.
+
+```css
+@import '@ponchia/ui';
+@import '@ponchia/ui/css/figure.css';
+@import '@ponchia/ui/css/legend.css';
+```
+
+Use it with `ui-report__figure` when the figure sits in a report. Use it alone
+when the same stage appears in a dashboard, doc page, or generated artifact.
+
+```html
+<figure class="ui-figure ui-report__figure ui-print-exact" role="group" aria-labelledby="fig-title">
+  <figcaption id="fig-title" class="ui-figure__caption ui-report__caption">
+    Fig 1 - Weekly focus split
+  </figcaption>
+  <div class="ui-figure__body ui-figure__body--key-right">
+    <div class="ui-figure__stage" style="--figure-max-inline: 30rem; --figure-min-block: 12rem">
+      <svg class="ui-figure__media" viewBox="0 0 320 120" role="img" aria-labelledby="svg-title svg-desc">
+        <title id="svg-title">Weekly focus split</title>
+        <desc id="svg-desc">Research is the largest category.</desc>
+        <rect x="80" y="24" width="180" height="20" fill="var(--chart-1)" />
+        <rect x="80" y="64" width="110" height="20" fill="var(--chart-2)" />
+      </svg>
+      <svg class="ui-figure__overlay" viewBox="0 0 320 120" aria-hidden="true">
+        <path class="ui-annotation__connector" d="M260,34L292,14" />
+      </svg>
+    </div>
+    <div class="ui-figure__key">
+      <ul class="ui-legend" aria-label="Series">...</ul>
+    </div>
+  </div>
+  <div class="ui-figure__data ui-table-wrap">
+    <table class="ui-table ui-table--dense">...</table>
+  </div>
+</figure>
+```
+
+## Contract
+
+| Class | Role |
+| --- | --- |
+| `.ui-figure` | Figure wrapper. |
+| `.ui-figure__caption` | Caption text; can compose with `ui-report__caption`. |
+| `.ui-figure__body` | Stage/key layout wrapper. |
+| `.ui-figure__body--key-right` | Two-column body: visual stage plus right-side key. |
+| `.ui-figure__stage` | Stable, centered media stage; `position: relative` for overlays. |
+| `.ui-figure__media` | Primary SVG, image, canvas, or rendered figure output. |
+| `.ui-figure__overlay` | Absolute, pointer-transparent overlay for annotations or guides. |
+| `.ui-figure__key` | Legend/key slot. |
+| `.ui-figure__data` | Fallback data slot, usually a `ui-table-wrap`. |
+
+| Custom property | On | Meaning |
+| --- | --- | --- |
+| `--figure-max-inline` | `.ui-figure__stage` | Maximum stage width, default `42rem`. |
+| `--figure-min-block` | `.ui-figure__stage` | Reserved stage height for late-rendered media. |
+| `--figure-key-width` | `.ui-figure__body--key-right` | Right key column width before mobile collapse. |
+
+## Boundary
+
+- Bronto owns layout, responsive collapse, overlay positioning, print spacing,
+  and class names.
+- The host owns scales, data binding, SVG/canvas/chart rendering, fallback table
+  rows, annotation text, and accessibility labels.
+- A figure should always have a `<figcaption>`. Data-bearing SVGs still need
+  `<title>` and `<desc>`.

package/docs/frontier-primitives.md

@@ -25,7 +25,7 @@ The pattern that worked for annotations should stay the rule:
 - Prefer CSS and markup first. Add JS only when the browser cannot express the
   behavior without measuring, filtering, keyboard state, or pointer tracking.
 
-This keeps Bronto useful across Astro, SvelteKit, React, Solid, Qwik, plain
+This keeps Bronto useful across Astro, SvelteKit, Vue, React, Solid, Qwik, plain
 HTML, and generated static reports without becoming a framework component kit.
 
 ## Already aligned in 0.5.0
@@ -164,19 +164,21 @@ and footnotes, but not a trust grammar. The shipped surface and its trust-state
 vocabulary are documented with the component; richer preview popovers remain
 host-owned.
 
-### 2. Lifecycle and system-state UI — 🟡 `ui-state` family shipped in 0.5.0
+### 2. Lifecycle and system-state UI — 🟡 `ui-state` family shipped in 0.5.0, `ui-job` added for 0.6.7
 
 Shipped as `@ponchia/ui/css/state.css` (`ui-state` + the canonical state matrix
-+ `ui-syncbar`), matching the "good first build" below. `ui-job` (background
-progress) and `ui-conflict` (resolution affordances) remain deferred until a
-consumer needs them; `ui-review-state` is covered by the reviewed/needs-review
++ `ui-syncbar`), matching the "good first build" below. The 0.6.7 local pass
+adds `ui-job`: a persistent background-job row with determinate progress,
+written status, and action slots, while polling/retry/cancel semantics stay in
+the host. `ui-conflict` (resolution affordances) remains deferred until a
+consumer needs it; `ui-review-state` is covered by the reviewed/needs-review
 state modifiers.
 
 Why it matters: serious apps spend a lot of time in states like saving, saved,
 queued, offline, stale, retrying, conflicted, locked, reviewed, and background
 job running. These states are usually improvised per product, so even good apps
-feel inconsistent. Still deferred: `ui-job` (background progress) and
-`ui-conflict` (resolution affordances), each until a consumer needs it.
+feel inconsistent. Still deferred: `ui-conflict` (resolution affordances), until
+a consumer needs it.
 
 ### 3. Command-first UI — ✅ shipped in 0.5.0
 
@@ -193,20 +195,19 @@ design-system contract: shortcuts, actions, groups, disabled reasons, context,
 and command result feedback. The host still owns the action registry and
 execution; global Cmd/Ctrl+K stays opt-in by design.
 
-### 4. Workbench UI — 🟡 inspector / property / selectionbar shipped in 0.5.0
+### 4. Workbench UI — 🟡 inspector / property / selectionbar shipped in 0.5.0, splitter added in 0.6.7
 
 Shipped as `@ponchia/ui/css/workbench.css` (`ui-inspector`, `ui-property`,
-`ui-selectionbar`) — the low-risk CSS core below. Resizable split panes
-(`ui-splitter`, an ARIA window-splitter behavior) and drag handles remain
-deferred until a consumer needs them.
+`ui-selectionbar`, `ui-splitter`) plus `initSplitter` — the low-risk workbench
+core below. Splitters own the focusable ARIA separator, keyboard/pointer resize,
+`--splitter-pos`, and `aria-valuenow`; the host owns pane contents, persistence,
+collapse policy, and saved layout state.
 
 Why it matters: real tools need inspectors, object action bars, split panes,
 resize handles, property rows, dense trees, and selected-object affordances.
 Generic UI kits tend to stop at cards/tables/forms, leaving every app to build
-its own half-consistent workbench. Still open: a `ui-splitter` ARIA
-window-splitter behavior (focusable separator, `aria-valuemin/max/now`,
-arrow-key resize) and drag/drop affordances — both deferred, and Bronto should
-style drag handles, not become a drag-and-drop framework.
+its own half-consistent workbench. Still open: drag/drop affordances. Bronto
+should style drag handles and drop targets, not become a drag-and-drop framework.
 
 ### 5. Generated-content and AI trust primitives — 🟡 shipped in 0.5.0
 
@@ -235,11 +236,10 @@ consumer since**; their follow-ons are demand-gated, not queued. Active work
 is therefore consolidation of the report lane (hub routing, print/PDF
 fidelity, consumer-contract gates), not new surfaces.
 
-### Report-lane candidates (build only after the routing hub carries them)
+### Report-lane primitives shipped in 0.6.7
 
-From the 2026-06-09 local scout — kept on merit, deliberately NOT started
-until the reporting.md routing/adoption pass has landed (shipping more leaves
-into an unrouted hub repeats the discoverability gap):
+From the 2026-06-09 local scout. These were kept on merit, then shipped only
+after `docs/reporting.md` carried routing rows so the leaves are discoverable:
 
 1. `ui-interval` — honest low–high uncertainty span + ± chip, inline in
    reports; the error-bar grammar generic kits never ship.
@@ -248,14 +248,15 @@ into an unrouted hub repeats the discoverability gap):
 3. `ui-highlights` — cited-evidence / search-hit spans painted from host
    Ranges via the CSS Custom Highlight API (progressive enhancement; clean
    no-op below the floor).
+4. `ui-figure` — stable chart/diagram/screenshot stage with overlay/key/fallback
+   slots; it composes with report figures but still refuses chart scales.
 
 ### Dormant (build with the first real app consumer, not before)
 
-- `ui-job` / `ui-conflict` lifecycle surfaces (candidate 2).
-- `ui-splitter` ARIA window-splitter behavior + drag affordances
-  (candidate 4), which is also the gating consumer for `ui-tree`'s deferred
-  roving-focus tree kernel.
-- Any command/workbench follow-ons beyond the shipped CSS cores.
+- `ui-conflict` lifecycle surface (candidate 2).
+- Drag/drop workbench affordances (candidate 4) and any gating consumer for
+  `ui-tree`'s deferred roving-focus tree kernel.
+- Any command/workbench follow-ons beyond the shipped cores.
 
 Dormant items stay gated on a real consumer needing them. This posture keeps
 Bronto differentiated while staying inside its core philosophy: small,

package/docs/glyphs.md

@@ -49,6 +49,17 @@ the same as a hot `#` cell (both become opaque mask regions).
 | `render` | `'mask'` | — | the one-node `.ui-icon` path |
 | `size` | CSS length | `1em` | with `render: 'mask'`, the icon size (`--icon-size`) |
 
+## Registry and lower-level helpers
+
+The public registry is intentionally plain data:
+
+- `GLYPH_SIZE` is the grid edge length.
+- `GLYPHS` is the frozen name → bitmap registry.
+- `GLYPH_NAMES` is the sorted, frozen name list.
+- `glyph(name)` returns the raw bitmap rows or `undefined`.
+- `glyphCells(name)` returns the 256 row-major cell descriptors.
+- `glyphMask(name)` returns the CSS `url(...)` value used by the mask renderer.
+
 ## Big numeric readout — `renderReadout`
 
 Compose digits and punctuation into a row of dot-matrix glyphs — the

package/docs/highlights.md

@@ -0,0 +1,52 @@
+# Highlights
+
+`@ponchia/ui/css/highlights.css` is an opt-in paint layer for the CSS Custom
+Highlight API. It styles named `Range` sets without adding wrapper spans to the
+DOM.
+
+```css
+@import '@ponchia/ui';
+@import '@ponchia/ui/css/highlights.css';
+```
+
+Bronto only paints the names below. The host owns range discovery, search,
+source mapping, current-match state, and cleanup.
+
+| Highlight name | Use |
+| --- | --- |
+| `bronto-evidence` | Cited evidence or selected proof text. |
+| `bronto-search` | Search result matches. |
+| `bronto-current` | The active/current match. |
+
+```html
+<article class="ui-highlights" id="review">
+  <p id="evidence">Latency improved after the migration, but the window is short.</p>
+</article>
+```
+
+```js
+const text = document.querySelector('#evidence').firstChild;
+if (CSS.highlights) {
+  const range = new Range();
+  range.setStart(text, 0);
+  range.setEnd(text, 16);
+  CSS.highlights.set('bronto-evidence', new Highlight(range));
+}
+```
+
+## Contract
+
+| Class | Role |
+| --- | --- |
+| `.ui-highlights` | Scope for Bronto's named highlight paints. |
+
+| Custom property | On | Meaning |
+| --- | --- | --- |
+| `--highlight-evidence` | `.ui-highlights` | Wash for `bronto-evidence`. |
+| `--highlight-search` | `.ui-highlights` | Wash for `bronto-search`. |
+| `--highlight-current` | `.ui-highlights` | Wash for `bronto-current`. |
+
+## Robustness
+
+Check `CSS.highlights` before registering ranges. Without support, the page
+falls back to plain text; no wrapper spans or extra cleanup are required.

package/docs/interop/tailwind.md

@@ -0,0 +1,148 @@
+# Tailwind v4 bridge and cascade-layer interop
+
+Everything `@ponchia/ui` ships lives inside a single named cascade layer,
+`@layer bronto`. This makes coexistence with Tailwind (or any layer-based CSS)
+deterministic, but only if you control **layer order**.
+
+Bronto also ships a Tailwind v4 bridge at `@ponchia/ui/tailwind`. It maps
+Bronto's CSS custom properties into Tailwind's CSS-first `@theme` namespaces and
+defines Bronto-aware variants. The bridge does **not** import the Bronto
+component CSS for you; import both when you want both systems.
+
+## The one rule
+
+In CSS, an explicit `@layer` declaration's order beats specificity: later layers
+win over earlier layers, and **un-layered styles beat all layered styles**. So:
+
+- Un-layered Tailwind utilities already override `@ponchia/ui` with no
+  `!important` and no specificity fight.
+- If Tailwind is itself layered (Tailwind v4 default), you must place its layers
+  **after** `bronto`.
+
+## Tailwind v4
+
+v4 emits `@layer theme, base, components, utilities;`. Declare `bronto`
+**before** Tailwind's utilities so utilities can override components, then import
+Tailwind and the Bronto bridge:
+
+```css
+/* app.css — order line first, before any @import */
+@layer bronto, theme, base, components, utilities;
+
+@import '@ponchia/ui'; /* fills @layer bronto */
+@import 'tailwindcss'; /* fills theme/base/components/utilities */
+@import '@ponchia/ui/tailwind'; /* adds @theme + @custom-variant bridge */
+```
+
+Because the `@layer` statement above fixes the order up front, it does not
+matter that `@ponchia/ui` is imported first — `utilities` is declared after
+`bronto`, so `class="ui-button px-8"` gives Tailwind's `px-8` the final word.
+
+If you'd rather Tailwind's **Preflight reset not touch** `@ponchia/ui` elements,
+keep Preflight (in `base`) before `bronto` instead:
+
+```css
+@layer theme, base, bronto, components, utilities;
+```
+
+Pick based on which reset you want to win; `@ponchia/ui`'s own reset is inside
+`bronto`, so whichever layer is later wins the reset too.
+
+### Theme utilities
+
+The bridge uses Tailwind v4's CSS-first `@theme inline` form, so Bronto tokens
+become ordinary Tailwind utilities while still reading the live CSS variables
+from the active theme:
+
+```html
+<section
+  class="bg-bronto-surface text-bronto-text border border-bronto-border p-bronto-lg rounded-bronto-lg"
+>
+  <button class="bg-bronto-action text-bronto-on-action ring-bronto-focus">Save</button>
+</section>
+```
+
+Useful namespaces:
+
+| Bronto token family | Tailwind utility examples |
+| --- | --- |
+| Surface/text/action colours | `bg-bronto-surface`, `text-bronto-text`, `border-bronto-border`, `ring-bronto-focus` |
+| Accent ramps | `bg-bronto-accent-1` … `bg-bronto-accent-6` |
+| Status colours | `text-bronto-success`, `bg-bronto-warning`, `border-bronto-danger`, `text-bronto-info` |
+| Typography | `font-bronto-sans`, `font-bronto-mono`, `font-bronto-display`, `text-bronto-sm` |
+| Spacing/radius/shadow/easing | `p-bronto-md`, `gap-bronto-sm`, `rounded-bronto-xl`, `shadow-bronto-raised`, `ease-bronto-standard` |
+
+### Bronto variants
+
+The bridge defines root/theme variants and common Bronto state variants:
+
+```html
+<article
+  class="bg-bronto-surface bronto-dark:bg-bronto-surface-raised bronto-contrast-more:border-bronto-border-strong"
+>
+  ...
+</article>
+
+<button class="bronto-active:text-bronto-action bronto-busy:opacity-70">Run</button>
+```
+
+Available variants:
+
+| Variant | Selector intent |
+| --- | --- |
+| `bronto-light:*` / `bronto-dark:*` | Descendants under `html[data-theme="light|dark"]` |
+| `bronto-oled:*` | Descendants under `[data-surface="oled"]` |
+| `bronto-contrast-more:*` | Descendants under `[data-contrast="more"]` |
+| `bronto-compact:*` / `bronto-comfortable:*` | Descendants under density presets |
+| `bronto-active:*` | `.is-active`, current page, or selected tab state |
+| `bronto-open:*` | Native/dialog/popover/open disclosure state |
+| `bronto-selected:*` | selected/pressed state |
+| `bronto-invalid:*` | invalid field state |
+| `bronto-busy:*` | busy/loading state |
+
+### Svelte/Vue component styles
+
+When using `@apply` or `@variant` inside Vue or Svelte component style blocks,
+import your app stylesheet with Tailwind's `@reference` directive so Tailwind
+can see the Bronto theme variables and custom variants without duplicating CSS
+output:
+
+```css
+@reference '../app.css';
+
+.panel {
+  @apply bg-bronto-surface text-bronto-text bronto-dark:bg-bronto-surface-raised;
+}
+```
+
+### Package source detection
+
+`@ponchia/ui` components are normal `.ui-*` classes and do not need Tailwind to
+scan the package. If your own app builds Tailwind class names inside ignored
+generated files or an external package, register those sources with Tailwind's
+`@source` directive in your app stylesheet.
+
+## Tailwind v3
+
+v3 (`@tailwind base/components/utilities`) is un-layered by default, so its
+utilities **already** beat `@layer bronto` with zero config — just
+`@import '@ponchia/ui';` first. If you opt into v3's experimental `cssLayers`,
+apply the v4 rule above.
+
+## Override matrix
+
+| You want…                                            | Use                                                                 |
+| ---------------------------------------------------- | ------------------------------------------------------------------- |
+| Tailwind utilities to win (normal case)              | Nothing — un-layered utilities already beat `@layer bronto`          |
+| A full-specificity, layer-free `@ponchia/ui` build   | Import the `@ponchia/ui/css/unlayered/<leaf>.css` escape-hatch paths |
+| Per-route CSS splitting + the bundle, no inversion   | Mix freely — every leaf export self-wraps in `@layer bronto`         |
+| Tailwind's Preflight to NOT reset `ui-*` elements    | `@layer theme, base, bronto, components, utilities;`                 |
+| Bronto tokens as Tailwind utilities                  | `@import '@ponchia/ui/tailwind';` after Tailwind v4                  |
+| Vue/Svelte style blocks using Bronto utilities       | `@reference '../app.css';` from the component style block            |
+
+## Gotcha
+
+Do **not** mix `@ponchia/ui` (layered) with `@ponchia/ui/css/unlayered/*` for
+the _same_ leaf — the unlayered copy will unconditionally win and you lose the
+ordering guarantees. The `unlayered/*` paths are a deliberate, surgical escape
+hatch, not a default.

package/docs/interval.md

@@ -0,0 +1,55 @@
+# Interval
+
+`@ponchia/ui/css/interval.css` is an opt-in low/high uncertainty primitive for
+reports: confidence intervals, estimates, measurement ranges, target windows,
+and caveated values.
+
+```css
+@import '@ponchia/ui';
+@import '@ponchia/ui/css/interval.css';
+```
+
+The host normalises every value to `0..1`. Bronto paints only the track, range,
+and optional point estimate.
+
+```html
+<div
+  class="ui-interval"
+  style="--lo: 0.22; --hi: 0.68"
+  role="img"
+  aria-label="Estimated completion between 22 and 68 percent, point estimate 52 percent"
+>
+  <span class="ui-interval__label">Estimate window</span>
+  <span class="ui-interval__track" aria-hidden="true">
+    <span class="ui-interval__range"></span>
+    <span class="ui-interval__point" style="--v: 0.52"></span>
+  </span>
+  <span class="ui-interval__bounds" aria-hidden="true">
+    <span>22%</span>
+    <span>68%</span>
+  </span>
+</div>
+```
+
+## Contract
+
+| Class | Role |
+| --- | --- |
+| `.ui-interval` | Wrapper and custom-property host. |
+| `.ui-interval__track` | Neutral track. |
+| `.ui-interval__range` | Low-high range span. |
+| `.ui-interval__point` | Optional point estimate. Omit the element when none exists. |
+| `.ui-interval__label` | Written label. |
+| `.ui-interval__bounds` | Visible low/high labels. |
+
+| Custom property | On | Meaning |
+| --- | --- | --- |
+| `--lo` | `.ui-interval` | Required normalised lower bound, `0..1`. |
+| `--hi` | `.ui-interval` | Required normalised upper bound, `0..1`. |
+| `--v` | `.ui-interval__point` | Optional normalised point estimate, `0..1`. |
+
+## Accessibility
+
+Pair each interval with a written label or `role="img"` plus `aria-label`. The
+range is not the data of record: under forced-colors or print, the readable
+label and bounds must still explain the value.

package/docs/legends.md

@@ -184,5 +184,6 @@ document.addEventListener('bronto:legend:toggle', (e) => {
 Convention: `aria-pressed="true"` means the series is **shown** (the default).
 The entry's label never changes on toggle — only `aria-pressed` and
 `.is-inactive` flip, so a screen reader reads a stable name with a clear
-pressed state. React/Solid/Qwik consumers can use `useLegend()` instead of
-calling `initLegend` directly.
+pressed state. React/Solid/Qwik/Svelte consumers can use `useLegend()` (or the
+`legend` Svelte action) instead of calling `initLegend` directly; Vue consumers
+can use `vLegend`.

package/docs/mermaid.md

@@ -54,6 +54,12 @@ below):
 </script>
 ```
 
+> **There is no classic-script path.** Mermaid v11 ships **no UMD bundle** —
+> its `dist/` is ESM-chunked, so vendoring a `mermaid.min.js` for a plain
+> `<script src>` is a dead end. In the browser it is the ES-module import
+> above (over a real `http(s)` origin); for everything else, pre-render to a
+> frozen SVG with `mmdc` (below) so there is no runtime at all.
+
 > **file:// portability.** A report opened straight from disk (`file://`) cannot
 > `import` the `@ponchia/ui/mermaid` module **nor** `fetch('…/mermaid.json')` —
 > the browser blocks both across the `null`/file origin (CORS), exactly as with

package/docs/migrations/0.2-to-0.3.md

@@ -0,0 +1,80 @@
+# Migrating 0.2 → 0.3
+
+0.3.0 removed the entire pre-`ui-*` vocabulary. Everything shipped is now
+under the `.ui-*` contract and the `check-classes` drift gate. This page
+turns the CHANGELOG's BREAKING notes into a runnable recipe. The
+machine-readable source of truth is [`MIGRATIONS.json`](../../MIGRATIONS.json).
+
+## 1. Mechanical renames (safe to automate)
+
+These are whole-class-token renames with no semantic change. Run from
+your **consuming app's** repo root (adjust the glob to your templates —
+`.astro`, `.svelte`, `.jsx`, `.tsx`, `.html`):
+
+```bash
+# Preview first — list every file/line that will change:
+rg -l --glob '*.{astro,svelte,jsx,tsx,vue,html}' \
+  -e 'skip-link' -e 'site-nav' -e 'site-menu' -e 'theme-toggle' -e '\bapp-' .
+
+# Apply (BSD/macOS sed shown; GNU sed: drop the '' after -i):
+fd -e astro -e svelte -e jsx -e tsx -e vue -e html -x sed -i '' \
+  -e 's/\bskip-link\b/ui-skiplink/g' \
+  -e 's/\bsite-nav\b/ui-sitenav/g' \
+  -e 's/\bsite-menu\b/ui-sitemenu/g' \
+  -e 's/\btheme-toggle\b/ui-themetoggle/g' \
+  -e 's/\bapp-\(shell\|rail\|topbar\|toolbar\|nav\|panel\|content\|main\|metrics\|metric\|empty-state\)/ui-app-\1/g' {}
+```
+
+The `\b` word boundaries keep `app-` from clobbering unrelated tokens,
+but **review the diff** — a codemod cannot know your markup.
+
+If you import the typed class registry, switch to the new entries
+instead and let the compiler find the rest:
+
+```js
+import { cls } from '@ponchia/ui/classes';
+// cls.appShell, cls.appRail, …, cls.themetoggleTrack, cls.menuHost
+```
+
+## 2. Concept moves (manual — no 1:1 rename)
+
+| Old                                              | Now                                                                         |
+| ------------------------------------------------ | --------------------------------------------------------------------------- |
+| `.hero`, `.project-*`, `.post-card`, `.essay-*`, `.page-*`, `.home-*`, `.signal-panel`, `.worklog-summary` | Re-compose with the content layer: `.ui-prose` / `.ui-quote`, `.ui-card`, `.ui-grid` / `.ui-stack`, the `ui-site*` shell |
+| `.callout`                                       | `.ui-alert` (pick a tone: `--info` / `--success` / `--warning` / `--danger`) |
+| `.metric-tile`                                   | `.ui-app-metric` inside `.ui-app-metrics`                                    |
+| `.tag-list` / `.tag`                             | `.ui-tags` / `.ui-tag` (verify accent-on-accent contrast)                    |
+
+## 3. Import and token checks
+
+The bundle collapsed in 0.3.0. Use the package root (`@ponchia/ui`) or
+`@ponchia/ui/css`; removed paths such as `./css/index.css`,
+`./css/responsive.css`, `./dist/bronto-core.css`, and
+`./css/{layout,typography,cards}.css` should be deleted.
+
+Direct leaf imports changed meaning too: `@ponchia/ui/css/<leaf>.css` now
+resolves to the safe layered build. If you intentionally depended on a raw
+unlayered leaf overriding your app by specificity, switch that import to
+`@ponchia/ui/css/unlayered/<leaf>.css`.
+
+If you re-brand with a pale `--accent`, set `--accent-text` as well; 0.3.0
+routes small accent-coloured text through that AA-safe token. TypeScript users
+should also expect `cls` and token helpers to reject typos now that the
+declarations are literal unions.
+
+## 4. Verify
+
+- `rg -n 'class(Name)?=.*"[^"]*\b(hero|callout|metric-tile|post-card|skip-link)\b'`
+  should return nothing after the pass.
+- `rg -n '@ponchia/ui/(css/(index|responsive|layout|typography|cards)\\.css|dist/bronto-core\\.css)'`
+  should return nothing.
+- Visual-diff your app: token **values** can change in any release
+  without a major bump, so eyeball the result, don't just diff classes.
+
+## Deprecation policy
+
+From 0.3.1 onward, removals follow the policy in
+[stability.md](../stability.md#deprecation-policy): a class is
+deprecated for **one minor** (kept working, marked in CHANGELOG +
+`MIGRATIONS.json`) before it is removed. 0.2 → 0.3 predates this policy,
+which is why it was a hard cut.

package/docs/migrations/0.3-to-0.4.md

@@ -0,0 +1,48 @@
+# Migrating 0.3 → 0.4
+
+0.4.0 is the **colour-system** release (see
+[ADR-0001](../adr/0001-color-system.md)). It is **additive for almost
+everyone** — the default `dist/bronto.css` renders identically. There is a
+single breaking change, and it only bites if you used an undocumented token.
+The machine-readable map is [`MIGRATIONS.json`](../../MIGRATIONS.json).
+
+## The one breaking change
+
+**`--orange` / `--orange-soft` were removed.** They were defined in the token
+mirrors but referenced by no component and documented nowhere — an orphan that
+contradicted the tier model. Removed under the CONTRIBUTING "provably-
+unreferenced surface" exception.
+
+**Migration:** if you referenced `--orange` / `--orange-soft` anywhere, define
+it yourself in a consumer override:
+
+```css
+:root {
+  --orange: #a85f32;
+  --orange-soft: rgb(168 95 50 / 0.13);
+}
+```
+
+Most apps need to do nothing. Verify with:
+
+```bash
+rg -- '--orange' .
+```
+
+## What's new (all opt-in, nothing to change)
+
+- **Colorways** — `@ponchia/ui/css/skins.css` + `data-bronto-skin="amber-crt |
+  phosphor-green | e-ink"` on `<html>`. Not loaded → no effect.
+- **Data-viz palette** — `@ponchia/ui/css/dataviz.css` + `@ponchia/ui/charts.json`
+  (`--chart-*` + dot-matrix pattern fills). Charts only.
+- **Tier-3 dot-matrix display tokens** (`--dotmatrix-glow`, `--dotmatrix-pulse-min`)
+  — default to a no-op.
+- **APCA** advisory contrast column in `docs/contrast.md`; WCAG 2.1 AA stays the
+  gate.
+
+## Re-pin
+
+```jsonc
+// package.json — 0.4 is a breaking minor under the pre-1.0 policy
+"@ponchia/ui": "~0.4.0"
+```