@ponchia/ui 0.6.6 → 0.6.8

package/docs/reporting.md

@@ -1,12 +1,19 @@
 # Static reports
 
 `@ponchia/ui` can dress static, LLM-authored HTML reports without a component
-runtime. Load the normal bundle, then opt in to the report layer, chart palette,
-and annotation layer only when the report needs them.
+runtime. Load the normal bundle, then either opt in to the complete report kit
+or import only the leaves a narrow report actually uses.
 
 In a bundled app, package specifiers are fine because Vite or another bundler
 rewrites them:
 
+```css
+@import '@ponchia/ui';
+@import '@ponchia/ui/css/report-kit.css';
+```
+
+For tighter payload control, import leaves one by one:
+
 ```css
 @import '@ponchia/ui';
 @import '@ponchia/ui/css/report.css';
@@ -16,9 +23,11 @@ rewrites them:
 ```
 
 **`dist/bronto.css` is the standard component set only — it does NOT contain
-the report, chart, annotation, or legend layers.** Those are opt-in leaves
-under `dist/css/`; a report links the default bundle *and* each leaf it uses.
-Forgetting them is the most common way an LLM-emitted report renders unstyled.
+the report, chart, annotation, source, trust, or code/diff layers.**
+`report-kit.css` is the one-file opt-in path for complete static reports; the
+individual leaves remain available under `dist/css/` when a report uses only a
+small subset. Forgetting the opt-in CSS is the most common way an LLM-emitted
+report renders unstyled.
 
 For standalone browser HTML, use real stylesheet URLs. Package specifiers like
 `@ponchia/ui/css/report.css` do not resolve in a saved `.html` file — and note
@@ -27,6 +36,14 @@ the path is `dist/css/`, the built leaf, not the source `css/`:
 ```html
 <!-- installed locally -->
 <link rel="stylesheet" href="./node_modules/@ponchia/ui/dist/bronto.css" />
+<link rel="stylesheet" href="./node_modules/@ponchia/ui/dist/css/report-kit.css" />
+```
+
+Or, if you are intentionally keeping a report minimal, link only the leaves it
+uses:
+
+```html
+<link rel="stylesheet" href="./node_modules/@ponchia/ui/dist/bronto.css" />
 <link rel="stylesheet" href="./node_modules/@ponchia/ui/dist/css/report.css" />
 <link rel="stylesheet" href="./node_modules/@ponchia/ui/dist/css/dataviz.css" />
 <link rel="stylesheet" href="./node_modules/@ponchia/ui/dist/css/annotations.css" />
@@ -37,11 +54,18 @@ No install? Link the same files from a CDN. Pin the version — pre-1.0, breakin
 changes ship in the minor (see [stability.md](./stability.md)):
 
 ```html
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.6/dist/bronto.css" />
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.6/dist/css/report.css" />
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.6/dist/css/dataviz.css" />
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.6/dist/css/annotations.css" />
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.6/dist/css/legend.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.8/dist/bronto.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.8/dist/css/report-kit.css" />
+```
+
+Leaf-by-leaf CDN imports use the same `dist/css/` paths:
+
+```html
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.8/dist/bronto.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.8/dist/css/report.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.8/dist/css/dataviz.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.8/dist/css/annotations.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.8/dist/css/legend.css" />
 ```
 
 The CDN serves the package's own `fonts/` next to the CSS, so font URLs resolve
@@ -60,21 +84,34 @@ sanitize that content before rendering it and do not initialize
 evidence). The _content_ inside those sections is where the rest of the
 analytical layer earns its place. Each one is an opt-in import that stays out of
 the default bundle — add the leaves a given report actually needs.
-`@ponchia/ui/css/analytical.css` is a convenience roll-up of the **seven
-figure-layer leaves only** (annotations, legends, marks, connectors, spotlight,
-crosshair, selection) — sources, generated, state, and the prose/evidence
-leaves below are NOT in it and must be linked individually. Reach for:
+`@ponchia/ui/css/analytical.css` is a convenience roll-up of the **nine
+figure/evidence-layer leaves only** (figure, annotations, legends, marks,
+connectors, spotlight, crosshair, selection, highlights) — sources, generated,
+state, interval, clamp, workbench, command, and the prose/evidence leaves below
+are NOT in it and must be linked individually. Reach for:
 
 | Layer | Import | Reach for it when… |
 | --- | --- | --- |
+| **Figure stage** (`.ui-figure*`) | `css/figure.css` | A chart, diagram, screenshot, or annotated SVG needs a stable media box, overlay slot, right-side key, and fallback-data slot. It composes with `ui-report__figure`; it does not render charts or own scales. See [figure.md](./figure.md). |
 | **Marks** (`.ui-mark`, `.ui-bracket-note`) | `css/marks.css` | You want to emphasise a phrase _in prose_ — a highlight on the finding, an underline on a risk, or a bracket around an evidence/caveat passage. The inline counterpart to annotations. See [marks.md](./marks.md). |
 | **Sources / provenance** (`.ui-citation`, `.ui-source-card`, `.ui-source-list`, `.ui-provenance`) | `css/sources.css` | The report makes claims a reader will question — "where did this come from?". A CSS-only trust layer whose cross-cutting state modifier (`.ui-src--verified`, plus reviewed / generated / unverified / stale / conflict) sets a rationed tone, always paired with a written label, never colour alone. See [sources.md](./sources.md). |
+| **Interval** (`.ui-interval*`) | `css/interval.css` | Evidence is a low/high estimate, confidence window, target band, or uncertain reading. The host normalises `--lo`, `--hi`, and optional `--v`; Bronto only paints the range and point. See [interval.md](./interval.md). |
+| **Clamp** (`.ui-clamp*`) | `css/clamp.css` | A source excerpt, claim basis, or caveat should scan as a bounded text block but remain reachable through explicit "Show more" / "Show less" labels and print expansion. See [clamp.md](./clamp.md). |
+| **Highlights** (`.ui-highlights`) | `css/highlights.css` | The host registers CSS Custom Highlight API ranges for cited evidence, search hits, or the current match without wrapping DOM text nodes. See [highlights.md](./highlights.md). |
+| **Chart palette** (`--chart-*`) | `css/dataviz.css` | A figure needs categorical, sequential, or diverging chart colours. The palette is opt-in, CVD-gated, and never UI chrome. See [theming.md](./theming.md#data-viz-palette). |
 | **Annotations** (`.ui-annotation*`) | `css/annotations.css` | A figure needs an explicit callout — a peak, a limit, a watched region — or a small decorative margin mark. SVG only. See [annotations.md](./annotations.md) and the [off-chart + scaling notes](./annotations.md#using-annotations-off-chart) before you size one. |
+| **Connectors** (`.ui-connector*`) | `css/connectors.css` | A note, card, or region needs a leader line to another DOM element. Bronto supplies overlay styling plus pure SVG path geometry; the host owns layout and meaning. See [connectors.md](./connectors.md). |
 | **Legends / data keys** (`.ui-legend*`) | `css/legend.css` | A chart figure needs a colour key. WCAG 1.4.1 by construction. See [legends.md](./legends.md). |
+| **Spotlight** (`.ui-spotlight*`, `.ui-tour-note*`) | `css/spotlight.css` | A screen report or guided workflow needs a visual focus cutout and callout note. It is not a tour engine; the host owns step order, persistence, and focus movement. See [spotlight.md](./spotlight.md). |
+| **Crosshair / readout** (`.ui-crosshair*`, `.ui-readout`) | `css/crosshair.css` | A plot needs pointer-tracking ruler lines and a readout chip. Bronto reports pixels/fractions; the host maps those to data values with its own scales. See [crosshair.md](./crosshair.md). |
+| **Selection emphasis** (`.ui-sel*`) | `css/selection.css` | Host-owned brush, filter, or selection logic needs a shared visual state vocabulary for selected / excluded / candidate items. See [selection.md](./selection.md). |
 | **Mermaid theme** (`@ponchia/ui/mermaid`) | _(JS/JSON, no CSS)_ | The report embeds a [Mermaid](https://mermaid.js.org) diagram (flowchart, sequence, pie…) and you want it on-brand instead of generic. A resolved `base` theme projected from the same tokens as `charts.json`; annotate the rendered SVG with the annotation layer. See [mermaid.md](./mermaid.md). |
 | **D2 theme** (`@ponchia/ui/d2`) | _(JS/JSON, no CSS)_ | The report embeds a [D2](https://d2lang.com) diagram and you want it on-brand. Resolved theme-override slots (monochrome base + one rationed accent) projected from the same tokens; annotate the rendered SVG. See [d2.md](./d2.md). |
+| **Vega theme** (`@ponchia/ui/vega`) | _(JS/JSON, no CSS)_ | The report embeds a live or generated Vega-Lite chart and you want token-matched axes, text, legends, and ramps. See [vega.md](./vega.md). |
 | **Generated-content trust** (`.ui-generated`, `.ui-origin-label`, `.ui-reasoning`, `.ui-tool-log`) | `css/generated.css` | The report (or a section of it) is AI/system-authored and should _say so_ — an origin label plus quiet, collapsible reasoning / tool-call logs. Pairs with the sources layer. See [generated.md](./generated.md). |
 | **Lifecycle / system state** (`.ui-state`, `.ui-syncbar`) | `css/state.css` | A status report needs to show the state a thing is in — saving / queued / stale / conflict / reviewed — as a labelled object, not a bare coloured dot. See [state.md](./state.md). |
+| **Workbench surfaces** (`.ui-inspector`, `.ui-property`, `.ui-selectionbar`, `.ui-splitter`) | `css/workbench.css` | A screen report or analytical tool needs an inspector, property rows, selected-item actions, or resizable panes. Not in `report-kit.css`; pair splitters with `initSplitter`. See [workbench.md](./workbench.md). |
+| **Command palette** (`.ui-command*`) | `css/command.css` | A screen report or analytical tool needs a searchable command shell. Not in `report-kit.css`; pair with `initCommand` and a host-owned opener/action registry. See [command.md](./command.md). |
 | **Spark** (`.ui-spark*`) | `css/spark.css` | A trend belongs _inside a sentence or table cell_ — a word-sized inline microchart, the inline counterpart to `ui-delta`/`ui-num`/`ui-stat`. See [spark.md](./spark.md). |
 | **Bullet graph** (`.ui-bullet*`) | `css/bullet.css` | A measure needs "inside budget? vs target?" at a glance — the canonical SLO / error-budget figure that `ui-meter` structurally cannot express. See [bullet.md](./bullet.md). |
 | **Diff** (`.ui-diff*`) | `css/diff.css` | The report shows what _changed_ — code review, changelogs, version history, config diffs. Marks call out a sentence; diff calls out a line. See [diff.md](./diff.md). |
@@ -88,8 +125,11 @@ leaves below are NOT in it and must be linked individually. Reach for:
 
 These compose with the report-native primitives already called out in
 [Composition rules](#composition-rules): `ui-statgrid`, `ui-alert`, `ui-table`,
-`ui-timeline`, `ui-meter`, and `ui-num`. None of them require behavior JS, so
-they are all safe in the static, PDF-first report path.
+`ui-timeline`, `ui-meter`, and `ui-num`. The static leaves do not require
+behavior JS, so they are safe in the PDF-first report path. `workbench.css` and
+`command.css` are deliberately screen-tool leaves: they stay out of
+`report-kit.css` and only become interactive when the host imports the matching
+behavior JS.
 
 ## Canonical skeleton
 
@@ -200,7 +240,8 @@ fetching, and claim wording.
   audit reports. Add `ui-report__action-title`, `__action-owner`,
   `__action-due`, `__action-priority`, `__action-criteria`, and
   `__action-source` when the action is a real workflow item. The status text
-  must be written out; do not rely on tone alone.
+  must be written out; do not rely on tone alone. The status occupies the side
+  rail on wide screens; the other action fields stay in the main text column.
 
 Decision brief pattern:
 
@@ -348,11 +389,11 @@ Evidence ledger pattern:
   deltas — they are not free-standing utilities.) Keep raw Markdown tables
   inside `ui-prose`; use `.ui-table` for curated evidence tables. If a
   `ui-report__evidence` block contains only a `ui-table-wrap`, the report layer
-  removes the inner frame so evidence tables do not look double-boxed.
-  Report tables preserve words by default so identifiers and headings do not
-  split into unreadable fragments in PDF. Add `ui-table--break-anywhere` only
-  for machine-token tables where avoiding horizontal overflow matters more than
-  preserving words.
+  removes the inner frame so evidence tables do not look double-boxed. Report
+  tables preserve words by default so identifiers and headings do not split into
+  unreadable fragments in PDF. Add `ui-table--break-anywhere` only for
+  machine-token tables where fixed, shrink-to-fit columns and forced wrapping
+  matter more than preserving words.
 - Every `<figure>` should include a `figcaption` using `ui-report__caption`.
 - Do not use raw color values. Theme with `--accent`; use status tones for
   status; use chart tokens only in chart figures.
@@ -473,12 +514,14 @@ from one of two routes:
   painting marks from the `--chart-N` palette so the figure prints exactly and
   carries no runtime.
 
-Whichever route, the figure frame is the same: wrap it in `ui-report__figure`,
-caption it with `ui-report__caption`, give it the standalone, portable
-`.ui-legend` data key (`@ponchia/ui/css/legend.css` — see
-[legends.md](./legends.md)), and pair every colour with a direct label, a
-pattern, **and** a fallback `ui-table` so the figure survives mono print and
-colour-vision deficiency.
+Whichever route, the figure frame is the same: wrap it in
+`ui-report__figure ui-figure`, caption it with
+`ui-report__caption ui-figure__caption`, put the rendered chart in
+`ui-figure__stage`, give it the standalone, portable `.ui-legend` data key
+(`@ponchia/ui/css/legend.css` — see [legends.md](./legends.md)), and pair every
+colour with a direct label, a pattern, **and** a fallback `ui-table` in
+`ui-figure__data` so the figure survives mono print and colour-vision
+deficiency.
 
 A Vega-Lite figure. The live mount is **`ui-screen-only`** and the fallback
 `ui-table` carries the data into print — a live chart bakes the on-screen theme
@@ -486,14 +529,16 @@ into its SVG/canvas at render time, so printing it would emit a dark-baked chart
 on white paper. Print the table; keep the chart for screen:
 
 ```html
-<figure class="ui-report__figure" role="group" aria-labelledby="chart-title">
-  <figcaption id="chart-title" class="ui-report__caption">
+<figure class="ui-report__figure ui-figure" role="group" aria-labelledby="chart-title">
+  <figcaption id="chart-title" class="ui-report__caption ui-figure__caption">
     Fig 1 - Weekly focus split
   </figcaption>
-  <div id="focus-chart" class="ui-screen-only" style="min-block-size: 240px">
-    <noscript>Chart needs JavaScript — the data is in the table below.</noscript>
+  <div class="ui-figure__stage ui-screen-only" style="--figure-min-block: 240px">
+    <div id="focus-chart" class="ui-figure__media">
+      <noscript>Chart needs JavaScript — the data is in the table below.</noscript>
+    </div>
   </div>
-  <div class="ui-table-wrap">
+  <div class="ui-figure__data ui-table-wrap">
     <table class="ui-table ui-table--dense">
       <caption>Chart source data</caption>
       <thead>
@@ -543,35 +588,42 @@ A frozen, token-themed inline `<svg>` for the same data — no runtime, prints
 exactly, with a `.ui-legend` key and the fallback table:
 
 ```html
-<figure class="ui-report__figure ui-print-exact" role="group" aria-labelledby="chart-title">
-  <figcaption id="chart-title" class="ui-report__caption">
+<figure class="ui-report__figure ui-figure ui-print-exact" role="group" aria-labelledby="chart-title">
+  <figcaption id="chart-title" class="ui-report__caption ui-figure__caption">
     Fig 1 - Weekly focus split
   </figcaption>
-  <ul class="ui-legend" aria-label="Series">
-    <li class="ui-legend__item">
-      <span
-        class="ui-legend__swatch"
-        style="--chart-color: var(--chart-1); --chart-pattern: var(--chart-pattern-1)"
-        aria-hidden="true"
-      ></span>
-      <span class="ui-legend__label">Research</span>
-    </li>
-    <li class="ui-legend__item">
-      <span
-        class="ui-legend__swatch"
-        style="--chart-color: var(--chart-2); --chart-pattern: var(--chart-pattern-2)"
-        aria-hidden="true"
-      ></span>
-      <span class="ui-legend__label">Delivery</span>
-    </li>
-  </ul>
-  <svg viewBox="0 0 360 160" role="img" aria-labelledby="focus-svg-title">
-    <title id="focus-svg-title">Weekly focus split</title>
-    <line x1="36" y1="132" x2="324" y2="132" stroke="var(--line)" />
-    <rect x="72" y="42" width="96" height="90" fill="var(--chart-1)" />
-    <rect x="200" y="77" width="96" height="55" fill="var(--chart-2)" />
-  </svg>
-  <div class="ui-table-wrap">
+  <div class="ui-figure__body ui-figure__body--key-right">
+    <div class="ui-figure__stage">
+      <svg class="ui-figure__media" viewBox="0 0 360 160" role="img" aria-labelledby="focus-svg-title focus-svg-desc">
+        <title id="focus-svg-title">Weekly focus split</title>
+        <desc id="focus-svg-desc">Research is 18 hours and delivery is 11 hours.</desc>
+        <line x1="36" y1="132" x2="324" y2="132" stroke="var(--line)" />
+        <rect x="72" y="42" width="96" height="90" fill="var(--chart-1)" />
+        <rect x="200" y="77" width="96" height="55" fill="var(--chart-2)" />
+      </svg>
+    </div>
+    <div class="ui-figure__key">
+      <ul class="ui-legend" aria-label="Series">
+        <li class="ui-legend__item">
+          <span
+            class="ui-legend__swatch"
+            style="--chart-color: var(--chart-1); --chart-pattern: var(--chart-pattern-1)"
+            aria-hidden="true"
+          ></span>
+          <span class="ui-legend__label">Research</span>
+        </li>
+        <li class="ui-legend__item">
+          <span
+            class="ui-legend__swatch"
+            style="--chart-color: var(--chart-2); --chart-pattern: var(--chart-pattern-2)"
+            aria-hidden="true"
+          ></span>
+          <span class="ui-legend__label">Delivery</span>
+        </li>
+      </ul>
+    </div>
+  </div>
+  <div class="ui-figure__data ui-table-wrap">
     <table class="ui-table ui-table--dense">
       <caption>Chart source data</caption>
       <thead>
@@ -820,8 +872,14 @@ important reports. The HTML stays the readable artifact; the sidecar lets a
 checker prove that claim IDs, source IDs, trust states, retrieval dates and
 high-risk decisions still line up after editing.
 
+The declarative contract ships as
+`@ponchia/ui/schemas/report-claims.v1.schema.json` for validators in any
+language. It is a schema only — `@ponchia/ui` does not ship a report generator
+or validation runtime.
+
 ```json
 {
+  "$schema": "https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.8/schemas/report-claims.v1.schema.json",
   "schemaVersion": "bronto-report-claims.v1",
   "report": { "title": "Decision readiness", "type": "decision" },
   "claims": [
@@ -843,6 +901,14 @@ high-risk decisions still line up after editing.
       "retrievedAt": "2026-06-08T10:00:00Z",
       "supports": ["claim-primary"]
     }
+  ],
+  "relations": [
+    {
+      "claimId": "claim-primary",
+      "sourceId": "source-primary",
+      "kind": "supports",
+      "note": "The metrics export supports the operational-risk conclusion."
+    }
   ]
 }
 ```

package/docs/sidenote.md

@@ -23,7 +23,13 @@ tradition — the channel for evidence, caveats, and provenance asides that belo
    (or a section) so the count starts at 1 there.
 2. **The margin gutter.** At the same breakpoint, give that container
    `padding-inline-end: calc(var(--sidenote-width) + var(--sidenote-gap))` so the
-   floated note has room. `--sidenote-width` defaults to `12rem`.
+   floated note has room. The two knobs are **root-scoped** (defaults `12rem` /
+   `2rem`) precisely so this calc resolves on any container — and overriding
+   either one on the container re-sizes the notes and the gutter together.
+   **This is load-bearing, not cosmetic:** without the gutter the floated note
+   spills past the page edge — a horizontal-overflow defect any visual QA pass
+   will flag. In a constrained shell that cannot spare a gutter, use the
+   in-flow `ui-sidenote` (which collapses inline) rather than `ui-marginnote`.
 
 ```html
 <article style="counter-reset: ui-sidenote">

package/docs/sources.md

@@ -44,7 +44,7 @@ host and add a tone. It draws a small pill with a leading trust dot:
 
 ```html
 <span class="ui-src ui-src--verified">Verified</span>
-<span class="ui-src ui-src--generated">AI-generated</span>
+<span class="ui-src ui-src--generated">Machine-generated</span>
 <span class="ui-src ui-src--stale">Stale · 14d</span>
 ```
 

package/docs/stability.md

@@ -16,20 +16,22 @@ shipped `files` entry, and the generated artifact provenance map — see
 | CSS package root (`@ponchia/ui`) | Stable | CSS-only entrypoint. CSS side-effect imports are supported in CSS-aware bundlers; Node/runtime JS root imports are not. |
 | JS module format | Stable | JS subpaths are ESM-only. CommonJS consumers use dynamic `import()`. |
 | CSS class names (`.ui-*`) | Stable | Names and documented modifier semantics are public. Internal selector structure and leaf-file boundaries may change. |
-| Class recipes (`@ponchia/ui/classes`) | Stable | Exported `cls`, `ui`, `cx`, recipe names, and option unions are public. |
+| Class recipes (`@ponchia/ui/classes`) | Stable | Exported `cls`, `ui`, `cx`, `attrs`, recipe names, ARIA attribute helper names, and option unions are public. |
 | Class vocabulary as data (`@ponchia/ui/classes.json`) | Stable additive | The JSON shape (`groups`/`classes`/`states`/`customProperties`) and its entries are public — for validating markup from a non-JS/non-TS host. Generated from `cls` (the `classes` list cannot drift from the CSS); `states`/`customProperties` are gated against the stylesheet. New classes/hooks are additive. |
 | Design tokens | Stable names/roles | Token names and documented roles are public. Exact values and generated colour math outputs may change for visual tuning before 1.0. |
 | `--accent-1..6` | Stable names/roles | A subtle-to-bold accent ramp derived from `--accent`. Exact resolved values are visual tuning; algorithm changes require release-note visibility and resolver/browser checks. |
 | Tokens as data (`tokens.json`, `tokens.dtcg.json`, `tokens/resolved.json`) | Stable additive | The JSON shapes are public for non-CSS/non-JS consumers. `resolved.json` exposes `light`/`dark` (resolved colours) and `scale` (resolved non-colour scales). Token names/roles are stable; exact resolved values are visual tuning (pin `~0.x`). |
+| Schemas (`schemas/*.schema.json`) | Stable additive | Declarative JSON Schema contracts for package-adjacent tooling data. Existing schema files and enum values are public within a compatible minor; new optional properties and new schema files are additive. No validator runtime ships. |
 | Theme axes | Mixed | `data-theme` (light/dark) is the **contractual** base. `data-surface="oled"`, `data-density`, and `data-contrast` are **convenience presets** — best-effort visual variants, **not** part of the stability contract; their presence and exact values may change for tuning. Computed-style smoke tests guard that the presets apply to their intended token families. |
 | Behavior attributes (`data-bronto-*`) | Stable | Attribute names and documented markup relationships are public. Behavior internals are not. |
 | Behavior functions (`@ponchia/ui/behaviors`) | Stable | Exported function names, option names, custom events, SSR no-op behavior, idempotency, and cleanup-returning contract are public. |
 | Glyph registry/renderers (`@ponchia/ui/glyphs`) | Stable additive | Existing glyph names stay valid. New glyphs are additive. Renderer option names and accessibility defaults are public. |
 | `.ui-icon` mask renderer | Stable | Class name, `--icon-size`, currentColor inheritance, and `--icon-mask` contract are public. The internal data URL encoding is not. |
-| React/Solid/Qwik bindings | Stable thin adapters | Hook/primitive names, optional peer behavior, root ref/signal/resolver support, and cleanup lifecycle are public. They remain wrappers over vanilla behaviors, not component APIs. |
+| Framework lifecycle adapters (`react`/`solid`/`qwik`/`svelte`/`vue`) | Stable thin adapters | Hook/action/directive names, optional peer behavior where applicable, root ref/signal/resolver support, and cleanup lifecycle are public. They remain wrappers over vanilla behaviors, not component APIs. |
 | Skins (`@ponchia/ui/skins`, `css/skins.css`) | Stable additive | Existing skin names stay valid. New skins are additive. Skins are root-level choices. |
 | Charts (`@ponchia/ui/charts`, `charts.json`, `css/dataviz.css`) | Stable additive | Token names, JSON shape, and 8 categorical slots are public. Exact palette values may tune if gates and release notes justify it. |
 | Reports (`css/report.css`, `.ui-report*`, print utilities) | Stable additive | Report class names, BEM part names, and print utility names are public. Report CSS is opt-in and not imported by the default bundle. The data key now lives in the standalone Legends layer (below), not `css/report.css`; charting is via the Vega theme target (`@ponchia/ui/vega`, see [vega](./vega.md)) or a token-themed inline SVG, not a shipped renderer. |
+| Report kit roll-up (`css/report-kit.css`) | Stable additive | A convenience `@import` of the complete static-report vocabulary. The set of leaves it bundles may grow additively; each leaf also stays individually exported. Opt-in, not in the default bundle. |
 | Annotations (`@ponchia/ui/annotations`, `css/annotations.css`, `.ui-annotation*`) | Stable additive | SVG annotation class names, recipe option names, and helper function names are public. Helper internals and exact path-control heuristics may tune before 1.0. |
 | Legends (`css/legend.css`, `.ui-legend*`, `@ponchia/ui/behaviors` `initLegend`) | Stable additive | Legend class names, recipe option names, and the `bronto:legend:toggle` event contract (`aria-pressed="true"` ⇒ shown) are public. Opt-in, not in the default bundle; swatch colours are gated to the `--chart-*` palette. |
 | Marks (`css/marks.css`, `.ui-mark*`, `.ui-bracket-note*`) | Stable additive | Text-mark and bracket-note class names and recipe option names are public. Opt-in, not in the default bundle. Uses semantic tones only. |
@@ -37,17 +39,33 @@ shipped `files` entry, and the generated artifact provenance map — see
 | Spotlight (`css/spotlight.css`, `.ui-spotlight*`, `.ui-tour-note*`, `initSpotlight`) | Stable additive | Spotlight/tour-note class names, the `--spot-*` custom-property contract, and the `data-bronto-spotlight`/`data-target` attributes are public. Opt-in, not in the default bundle. Not a tour engine. |
 | Crosshair (`css/crosshair.css`, `.ui-crosshair*`, `.ui-readout`, `initCrosshair`) | Stable additive | Crosshair/readout class names, the `--crosshair-x/y` properties, the `data-bronto-crosshair` attribute, and the `bronto:crosshair:move`/`:leave` event contract are public. Opt-in. Reports pointer position only — no data mapping. |
 | Selection states (`css/selection.css`, `.ui-sel*`) | Stable additive | The `.ui-sel`/`--on`/`--off`/`--maybe` emphasis classes and recipe options are public. Opt-in, cross-cutting. The host owns selection logic; Bronto only styles the states. |
-| Analytical roll-up (`css/analytical.css`) | Stable additive | A convenience `@import` of the seven analytical leaves (annotations, legend, marks, connectors, spotlight, crosshair, selection). The set of leaves it bundles may grow additively; each leaf also stays individually exported. Opt-in, not in the default bundle. |
+| Analytical roll-up (`css/analytical.css`) | Stable additive | A convenience `@import` of the nine analytical leaves (figure, annotations, legend, marks, connectors, spotlight, crosshair, selection, highlights). The set of leaves it bundles may grow additively; each leaf also stays individually exported. Opt-in, not in the default bundle. |
 | Sources / provenance (`css/sources.css`, `.ui-citation*`, `.ui-source-card*`, `.ui-source-list*`, `.ui-provenance*`, `.ui-src--*`, `initSources`) | Stable additive | Citation/source/provenance class names, the cross-cutting `.ui-src--*` trust-state modifiers (always paired with an author label), the optional `data-bronto-sources` / `data-bronto-source-ref` behavior contract, `bronto:source:focus`, and the `ui.citation`/`ui.source`/`ui.provenance` recipes + `cls.sourceList` are public. Opt-in, not in the default bundle. |
 | Lifecycle state (`css/state.css`, `.ui-state*`, `.ui-syncbar`) | Stable additive | The `.ui-state`/`__label`/`__detail`/`--busy` classes, the canonical lifecycle state modifiers, `.ui-syncbar`, and the `ui.state` recipe are public. Opt-in, not in the default bundle. |
 | Generated / AI-trust (`css/generated.css`, `.ui-generated*`, `.ui-origin-label*`, `.ui-reasoning*`, `.ui-tool-log`, `.ui-tool-call*`) | Stable additive | The generated-content, origin-label (incl. `--ai`), reasoning-trace and tool-log/tool-call class names and the `ui.originLabel` recipe are public. Opt-in, not in the default bundle. Not a chat kit; no confidence widget. |
-| Workbench (`css/workbench.css`, `.ui-inspector*`, `.ui-property*`, `.ui-selectionbar*`) | Stable additive | Inspector, property-row and selection-bar class + BEM part names are public (class-only — no recipe). Opt-in, not in the default bundle. Splitters/drag handles are out of scope. |
-| Command palette (`css/command.css`, `.ui-command*`, `initCommand`, `useCommand`) | Stable additive | Command class/part names, the `data-bronto-command` attribute, and the event contract — `bronto:command:select` (`detail: { value, label }`) and `bronto:command:close` — are public, plus the `useCommand` binding hook. Bronto filters + navigates (APG combobox/listbox); the host owns the action registry/execution. Opt-in, not in the default bundle, no global hotkey. |
+| Workbench (`css/workbench.css`, `.ui-splitter*`, `.ui-inspector*`, `.ui-property*`, `.ui-selectionbar*`, `initSplitter`) | Stable additive | Splitter, inspector, property-row and selection-bar class + BEM part names are public (no recipe). `data-bronto-splitter`, `--splitter-pos`, `bronto:splitter:resize`, and the `initSplitter` cleanup contract are public. Opt-in, not in the default bundle. The host owns pane content, persistence, collapse policy, and selection state. |
+| Command palette (`css/command.css`, `.ui-command*`, `initCommand`, `useCommand` / `command` / `vCommand`) | Stable additive | Command class/part names, the `data-bronto-command` attribute, and the event contract — `bronto:command:select` (`detail: { value, label }`) and `bronto:command:close` — are public, plus the framework binding adapters. Bronto filters + navigates (APG combobox/listbox); the host owns the action registry/execution. Opt-in, not in the default bundle, no global hotkey. |
 | Controlled-modal focus trap (`initModal`, `useModal`, `data-bronto-modal`) | Stable additive | For the `.ui-modal.is-open` (non-`<dialog>`) path: the `data-bronto-modal` opt-in marker, the `inert`-based focus trap + focus-return, and the cancelable `bronto:modal:close` (`detail: { reason }`) event are public. The consumer still owns the `is-open` class; the behavior never changes visibility. The native `<dialog>` path (`initDialog`) is the default and gets the trap for free. |
 | Keyboard-shortcut hint (`.ui-shortcut`, `.ui-shortcut__sep`) | Stable additive | Class names for the chord/sequence hint over `.ui-kbd` are public. Ships in the core layer (class-only, no recipe). |
 | Generated docs shipped in npm | Stable paths | `llms.txt` and exported docs paths stay shipped and resolvable within a compatible minor. Markdown/text assets are for reading unless your runtime has a loader. Generated content may change with the source contract. |
 | Demo, examples, tests, scripts | Internal | Useful for learning and verification, but not shipped runtime API unless a path is explicitly exported in `package.json`. |
 
+## Deprecation Policy
+
+Public surface (`.ui-*` classes, `data-bronto-*` attributes, `cls`/token keys,
+behavior signatures, and exported schema values) is removed on a
+**deprecate-one-minor** cycle:
+
+1. **Deprecate** in minor _N_: the surface keeps working unchanged, is marked
+   deprecated in `CHANGELOG.md`, and, for renames, gets an entry in
+   [`MIGRATIONS.json`](../MIGRATIONS.json).
+2. **Remove** no earlier than minor _N+1_, with a **BREAKING** changelog entry
+   and migration note.
+
+A token/class/attribute that is provably referenced by no shipped CSS,
+component, behavior, or doc may skip that window and be removed with a BREAKING
+entry plus migration note; there is no working call-site to keep alive.
+
 ## Trust Boundary
 
 Behaviors assume trusted application markup. If a delegated root includes

package/docs/state.md

@@ -2,9 +2,10 @@
 
 `@ponchia/ui/css/state.css` is an opt-in vocabulary for the states real apps
 spend their time in — saving, saved, queued, offline, stale, conflicted, locked,
-reviewed. These are usually improvised per product, so even good apps feel
+reviewed, and background work still running after the initiating interaction is
+gone. These are usually improvised per product, so even good apps feel
 inconsistent. This is the canonical set: a labelled state object with a rationed
-tone, plus a page/document sync bar.
+tone, a page/document sync bar, and a persistent background-job row.
 
 ```css
 @import '@ponchia/ui';
@@ -12,10 +13,10 @@ tone, plus a page/document sync bar.
 ```
 
 Bronto ships the visual states and the canonical wording. The host owns the
-state machine, retry policy, persistence, and announcements. **Persistent state
-deserves persistent UI** — a toast is secondary, not the answer. The tone is a
-second channel; the **label is the state**, so it survives forced-colors and
-screen readers (WCAG 1.4.1).
+state machine, retry policy, persistence, cancellation, and announcements.
+**Persistent state deserves persistent UI** — a toast is secondary, not the
+answer. The tone is a second channel; the **label is the state**, so it
+survives forced-colors and screen readers (WCAG 1.4.1).
 
 ## `.ui-state`
 
@@ -68,6 +69,61 @@ the other.
 </div>
 ```
 
+## `.ui-job`
+
+A durable row for background jobs, imports, exports, sync runs, and pipelines.
+It is deliberately not a task runner: the host owns polling, retry/cancel
+semantics, queue position, partial failures, and completion messages. Bronto
+paints a persistent status/progress object so long-running work is not hidden in
+a transient toast.
+
+```html
+<article
+  class="ui-job ui-job--running"
+  style="--job-progress: 64%"
+  aria-labelledby="job-title"
+>
+  <div class="ui-job__head">
+    <h3 class="ui-job__title" id="job-title">Importing listings</h3>
+    <span class="ui-state ui-state--saving ui-state--busy">
+      <span class="ui-state__label">Running</span>
+      <span class="ui-state__detail">64%</span>
+    </span>
+  </div>
+  <p class="ui-job__body">124 of 194 records processed. Latest checkpoint saved.</p>
+  <div
+    class="ui-job__progress"
+    role="progressbar"
+    aria-label="Import progress"
+    aria-valuemin="0"
+    aria-valuemax="100"
+    aria-valuenow="64"
+  >
+    <span class="ui-job__bar"></span>
+  </div>
+  <div class="ui-job__actions">
+    <button class="ui-button ui-button--subtle ui-button--sm" type="button">View log</button>
+    <button class="ui-button ui-button--ghost ui-button--sm" type="button">Cancel</button>
+  </div>
+</article>
+```
+
+Use the written state as the source of truth:
+
+| State | Class | Typical label | Use when… |
+| --- | --- | --- | --- |
+| Queued | `ui-job--queued` | "Queued" | The job is accepted but not running yet. |
+| Running | `ui-job--running` | "Running" / "Syncing" | Work is actively progressing. |
+| Blocked | `ui-job--blocked` | "Blocked" / "Waiting" | Work cannot proceed without another system or user action. |
+| Failed | `ui-job--failed` | "Failed" | The job stopped and needs retry, inspection, or acknowledgement. |
+| Complete | `ui-job--complete` | "Complete" | Work finished and the result is available. |
+
+For determinate jobs, set `--job-progress` as a percentage on `.ui-job` and
+put `role="progressbar"` plus `aria-valuenow/min/max` on `.ui-job__progress`.
+For indeterminate jobs, omit the progress block or omit `aria-valuenow`, and
+make the written state clear ("Running", "Waiting for worker", "Retrying").
+Use `ui-job--compact` for dense queues.
+
 ## Recipe
 
 ```js
@@ -75,11 +131,12 @@ import { ui } from '@ponchia/ui/classes';
 
 ui.state({ state: 'saving', busy: true }); // "ui-state ui-state--saving ui-state--busy"
 ui.state({ state: 'conflict' }); // "ui-state ui-state--conflict"
+ui.job({ state: 'running' }); // "ui-job ui-job--running"
 ```
 
 ## Scope
 
-CSS only — there is no JS yet. Auto-updating elapsed time ("2m ago") or live
-progress text is the host's job; a small optional behavior may come later if a
-real consumer needs it. Background-job progress and conflict-resolution
-affordances are deliberately deferred until then.
+CSS only — there is no JS yet. Auto-updating elapsed time ("2m ago"), live
+progress text, polling, cancellation, retry, and conflict-resolution affordances
+are the host's job. A small optional behavior may come later if a real consumer
+needs it.

package/docs/theming.md

@@ -11,7 +11,7 @@ theme-owned neutral ramp endpoint:
 
 | Token                 | Derivation (light / dark)                    | Role |
 | --------------------- | -------------------------------------------- | ---- |
-| `--accent-strong`     | `--accent` mixed 83% with black / 84% white  | darker/lighter accent for hover, emphasis |
+| `--accent-strong`     | `--accent` mixed 83% with black / 80% white  | darker/lighter accent for hover, emphasis |
 | `--accent-ramp-end`   | white / black                                | neutral endpoint for the low-chroma OKLCH ramp |
 | `--accent-text`       | `var(--accent-strong)` (alias)               | **accent used as foreground text** — the on-surface, AA-safe one |
 | `--accent-soft`       | `--accent` at 10% / 14% over transparent     | tinted fills |
@@ -63,7 +63,7 @@ fills — follows automatically, in both light and dark.
 >    defaults to `--accent-strong` (a darkened/​lightened accent). If you
 >    re-brand to a pale hue, raw `--accent` would fail as text — override
 >    `--accent-text` to a sufficiently dark/light value rather than
->    relying on the 83%/84% mix.
+>    relying on the 83%/80% mix.
 >
 > The defaults are tuned for both; verify if you deviate hard. The focus
 > ring is solid `--accent` (≥ 3:1 non-text) — re-brand to a near-`--bg`
@@ -223,7 +223,7 @@ you have, so the one-accent discipline holds.
   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`)
+## Data-viz palette
 
 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
@@ -275,7 +275,7 @@ semantics — the CSS can't add ARIA for you:
   content use `.ui-popover` + `initPopover()` (collision-aware).
 
 > **Verify a rebrand:** open
-> [`demo/theme-playground.html`](../demo/theme-playground.html) — paste
+> [the theme playground](https://ponchia.github.io/bronto-ui/demo/theme-playground.html) — paste
 > your `--accent`, see the derived family and the computed WCAG ratios
 > for `--accent-text` / `--accent` against the surface, and copy the CSS
 > + DTCG override. This is the instrument for the "verify your hue"
@@ -303,6 +303,14 @@ palette) carry real `$value`s; the CSS-runtime-derived family
 `$value: null` + the CSS in `$extensions["com.ponchia.css"]` rather than
 fabricating a number — the resolvable knob is `color.<theme>.accent`.
 
+`@ponchia/ui/tokens/figma.variables.json` is the resolved local handoff for
+Figma Variables import/sync scripts. It is generated from `tokens/resolved.json`
+and keeps a `Bronto / Color` collection with `Light` and `Dark` modes plus a
+`Bronto / Scale` collection for spacing, radius, type, z-index and motion.
+Colour values are exported as Figma-style RGBA objects; non-colour values keep
+their original CSS value under `$extensions["com.ponchia.css"]` so importer
+scripts do not lose units.
+
 ## Reading tokens from JS
 
 `@ponchia/ui/tokens` exposes the model as data. The ergonomic view only