@ponchia/ui 0.6.5 → 0.6.7

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.5/dist/bronto.css" />
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.5/dist/css/report.css" />
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.5/dist/css/dataviz.css" />
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.5/dist/css/annotations.css" />
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.5/dist/css/legend.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.7/dist/bronto.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.7/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.7/dist/bronto.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.7/dist/css/report.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.7/dist/css/dataviz.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.7/dist/css/annotations.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.7/dist/css/legend.css" />
 ```
 
 The CDN serves the package's own `fonts/` next to the CSS, so font URLs resolve
@@ -59,19 +83,37 @@ sanitize that content before rendering it and do not initialize
 `css/report.css` gives you the document grammar (covers, sections, findings,
 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, or pull the
-whole set with `@ponchia/ui/css/analytical.css`. Reach for:
+the default bundle — add the leaves a given report actually needs.
+`@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, 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). |
 | **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. |
 | **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). |
 | **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). |
 | **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). |
+| **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). |
+| **Code** (`.ui-code*`) | `css/code.css` | Code-as-evidence: fenced snippets with an optional gutter and add/remove/highlight line states, sharing diff's change vocabulary. On-brand syntax colours via the [Shiki theme](./code.md). See [code.md](./code.md). |
+| **Sidenotes** (`.ui-sidenote`, `.ui-marginnote`) | `css/sidenote.css` | Evidence, caveats, and provenance asides that belong _beside_ the prose, Tufte-style, instead of interrupting it. See [sidenote.md](./sidenote.md). |
+| **Textref** (`.ui-textref`) | `css/textref.css` | A citation should deep-link to the _exact quoted sentence_ (URL text fragments, on-brand `::target-text` paint) — the inline counterpart to the source-card layer. See [textref.md](./textref.md). |
+| **Term / glossary** (`.ui-term`, `.ui-glossary`) | `css/term.css` | Jargon should explain itself inline (native popover definition) and gather into an end-of-report glossary. See [term.md](./term.md). |
+| **Contents rail** (`.ui-toc*`) | `css/toc.css` | A long report needs a sticky table of contents with the in-view section highlighted; degrades to a plain anchored list with zero JS. Distinct from the in-flow `ui-report__toc` block. See [toc.md](./toc.md). |
+| **Tree** (`.ui-tree*`) | `css/tree.css` | Nested structure — file trees, object graphs, nested provenance — as a depth-indented outline on native `<details>`. See [tree.md](./tree.md). |
+| **Dot surfaces** (`.ui-waffle`, `.ui-activity`, `.ui-level`, `.ui-dotgauge`, `.ui-readout`, …) | _(in the core bundle)_ | A count, rate, level, or gauge wants the library's signature dot-matrix expression — waffle units, activity strips, dot gauges, readouts. See [dots.md](./dots.md). |
 
 These compose with the report-native primitives already called out in
 [Composition rules](#composition-rules): `ui-statgrid`, `ui-alert`, `ui-table`,
@@ -187,7 +229,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:
 
@@ -335,11 +378,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.
@@ -460,12 +503,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
@@ -473,14 +518,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>
@@ -530,35 +577,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>
@@ -807,8 +861,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.7/schemas/report-claims.v1.schema.json",
   "schemaVersion": "bronto-report-claims.v1",
   "report": { "title": "Decision readiness", "type": "decision" },
   "claims": [
@@ -830,6 +890,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."
+    }
   ]
 }
 ```
@@ -876,6 +944,14 @@ tooling.
   (Puppeteer ships its own). The repo's `scripts/render-pdf.mjs` is a working
   copy of this (`npm run report:pdf -- report.html`); it is a dev/example
   helper, not part of the published API — bronto does not own rendering.
+
+  **If the report renders figures from `<script type="module">`, do not load
+  it over `file://`** — browsers block relative module imports from `file://`
+  (CORS, opaque `null` origin), so the figures silently render empty in the
+  PDF. Serve the report over HTTP first; `render-pdf.mjs --serve` does this
+  (loopback server + load over `http://127.0.0.1`), waits for the report's
+  `data-report-ready` signal if it sets one, and logs page errors instead of
+  swallowing them.
 - **As a service / from another language:** run Chromium-as-a-service
   (e.g. **Gotenberg**'s `POST /forms/chromium/convert/html`, or a hosted CDP
   endpoint) and POST the HTML + the `dist/css/*` assets. A Python/Go/any host

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

@@ -21,15 +21,17 @@ shipped `files` entry, and the generated artifact provenance map — see
 | 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,11 +39,11 @@ 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. |
+| 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`) | 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. |
 | 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). |

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`
@@ -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

package/docs/usage.md

@@ -276,12 +276,14 @@ without it these widgets are unlabelled or unannounced:
 - **`ui-skiplink`** — keep it the first focusable element and point its `href`
   at the `id` of your main landmark.
 
-## App shell: the admin dashboard frame
+## App shell: the service frame
 
-`ui-app-shell` is a CSS-only two-column admin frame (sidebar rail + main
-column) that collapses to a single column with a horizontal rail below 880px —
-no behavior required. The nesting matters; the rail is `ui-app-rail` and the
-content side is `ui-app-main`:
+`ui-app-shell` is the default cross-service identity frame: a CSS-only
+two-column app shell (sidebar rail + main column) that collapses to a single
+column with a horizontal rail below 880px — no behavior required. Use it for
+ops tools, admin apps, internal services, generated dashboards, and any workflow
+surface that should feel like part of the same system. The nesting matters; the
+rail is `ui-app-rail` and the content side is `ui-app-main`:
 
 ```html
 <div class="ui-app-shell">
@@ -290,7 +292,9 @@ content side is `ui-app-main`:
     <nav class="ui-app-nav" aria-label="Primary">
       <span class="ui-app-nav__section">Main</span>
       <a href="/overview" aria-current="page">Overview</a>
-      <a href="/reports">Reports</a>
+      <a href="/jobs">Jobs</a>
+      <a href="/integrations">Integrations</a>
+      <a href="/settings">Settings</a>
     </nav>
     <div class="ui-app-rail__account">…</div>
   </aside>
@@ -310,6 +314,21 @@ Knobs: `--app-rail` sets the rail width (default 14rem); `ui-app-shell--full`
 drops the rail for a single-column app. `ui-app-nav` honours `aria-current="page"`
 (preferred) and the visual-only `.is-active`.
 
+Service composition checklist:
+
+- Start with `ui-app-shell`, `ui-app-rail`, `ui-app-nav`, `ui-app-main`,
+  `ui-app-topbar`, and `ui-app-content`.
+- Put brand and account identity in the rail; do not rebuild that frame per app.
+- Use `ui-app-toolbar` for filters/actions above a workflow surface.
+- Use `ui-app-panel` for grouped operational sections, not nested cards.
+- Use `ui-statgrid`/`ui-stat`, `ui-table`, `ui-field`, `ui-alert`, and
+  `ui-progress` inside panels; add opt-in `state.css` for `ui-state` lifecycle
+  labels.
+- Keep nav current state on `aria-current="page"` so the visual cue and AT cue
+  match.
+- Reach for opt-in `workbench.css` only when the service needs panes,
+  inspectors, or selected-object bulk actions.
+
 ## Menus: `data-bronto-menu` + `initMenu`
 
 A dropdown menu is a native `<details data-bronto-menu>` styled as
@@ -606,10 +625,11 @@ These are JS widgets wearing the Bronto look; without the behavior they are iner
 | Tabs (`ui-tabs`) | `initTabs` | **author panels visible** — ship `hidden` panels and if `initTabs` never runs the content is unreachable |
 | Combobox (`ui-combobox`) | `initCombobox` | a plain text input beside an unfiltered list |
 | Command palette (`ui-command`) | `initCommand` | a static, unfiltered list |
+| Splitter (`ui-splitter`) | `initSplitter` | fixed panes at the authored `--splitter-pos`; no keyboard/pointer resize or `aria-valuenow` updates |
 | Table sort/select (`[data-bronto-sortable]`) | `initTableSort` | a static table (still readable) |
 | Popover (`ui-popover`) | `initPopover` | no placement/ARIA — prefer the native `popover` attribute |
 | Carousel (`ui-carousel`) | `initCarousel` | a native scroll-snap track (usable, no controls) |
-| Controlled modal (`ui-modal.is-open`) | `initModal` | no focus trap — provide one or use native `<dialog>` |
+| Controlled modal (`ui-modal.is-open`) | `initModal` | open skin only — no inert trap, focus-return, or Escape close signal |
 | Menu (`data-bronto-menu`) | `initMenu` | a button next to a list with no open/close, outside-click, or Escape |
 | Toast | `toast()` | nothing — it is imperative-only |
 
@@ -628,10 +648,10 @@ boundary of what CSS alone cannot do.
 The CSS is the framework; `@ponchia/ui/behaviors` is the *sanctioned*
 home for the little JS that genuinely needs scripting (theme persistence,
 disclosure, dialog glue, modal focus-trap, toast, combobox, form-validation,
-table-sort). Reach for it instead of reimplementing — every initializer is
-SSR-safe, idempotent, and returns a cleanup. If you find yourself writing focus
-management or `aria-expanded` toggling by hand, there is probably already
-a behavior for it.
+table-sort, splitter resizing). Reach for it instead of reimplementing — every
+initializer is SSR-safe, idempotent, and returns a cleanup. If you find yourself
+writing focus management, ARIA value sync, or `aria-expanded` toggling by hand,
+there is probably already a behavior for it.
 
 ## Re-brand obligations (the short version)