@ponchia/ui 0.6.5 → 0.6.7

package/docs/architecture.md

@@ -39,9 +39,12 @@ on top of the CSS, none of which require a framework commitment**:
 ├── connectors/  pure SVG leader-line geometry kernel (no DOM)        [optional]
 ├── annotations/ pure SVG callout geometry (builds on connectors)     [optional]
 ├── glyphs/      dot-matrix glyph registry/renderers                 [optional]
+├── schemas/     declarative JSON contracts for report/tooling data   [optional]
 ├── react/       thin React hooks over behaviors                     [optional peer]
 ├── solid/       thin Solid primitives over behaviors                [optional peer]
-└── qwik/        thin Qwik hooks over behaviors (useVisibleTask$)     [optional peer]
+├── qwik/        thin Qwik hooks over behaviors (useVisibleTask$)     [optional peer]
+├── svelte/      thin Svelte actions over behaviors                  [optional]
+└── vue/         thin Vue directives over behaviors                  [optional]
 ```
 
 ### Consequences of each layer
@@ -57,12 +60,12 @@ on top of the CSS, none of which require a framework commitment**:
 - **tokens/** — `index.js` (`cssVars`) is the single source of truth for token
   values. The four `:root` palette blocks of `css/tokens.css` are **generated**
   from it (`scripts/gen-tokens-css.mjs`), as are the JSON artifacts (`index.json`,
-  `tokens.dtcg.json`, `resolved.json`). So the dark palette is authored once,
-  not in three places (the two CSS dark blocks are now identical by
-  construction), resolving the duplication ADR-0003 flagged. The CSS-only
-  presets (density / contrast / OLED) stay hand-authored below a marker and are
-  preserved across regeneration. `scripts/check-fresh.mjs` fails CI if
-  `css/tokens.css` drifts from the model.
+  `tokens.dtcg.json`, `resolved.json`, `figma.variables.json`). So the dark
+  palette is authored once, not in three places (the two CSS dark blocks are now
+  identical by construction), resolving the duplication ADR-0003 flagged. The
+  CSS-only presets (density / contrast / OLED) stay hand-authored below a marker
+  and are preserved across regeneration. `scripts/check-fresh.mjs` fails CI if a
+  generated mirror drifts from the model.
 - **classes/** — `cls` is the flat registry; recipes only emit from it;
   `scripts/check-classes.mjs` enforces a bidirectional match with the
   stylesheet's `.ui-*` selectors. The class contract cannot silently rot.
@@ -76,24 +79,28 @@ on top of the CSS, none of which require a framework commitment**:
 - **glyphs/** — static bitmap data and SSR-safe render helpers. The
   256-cell DOM renderers are for display and solid inline icons; the `.ui-icon`
   mask renderer is for dense icon-at-scale use.
-- **react/** / **solid/** / **qwik/** — optional lifecycle adapters over `behaviors/`.
-  They do not define markup, own state, or fork behavior logic; they only run
-  the vanilla initializers on mount and cleanup on unmount/dispose.
+- **react/** / **solid/** / **qwik/** / **svelte/** / **vue/** — optional lifecycle
+  adapters over `behaviors/`. They do not define markup, own state, or fork
+  behavior logic; they only run the vanilla initializers on mount and cleanup
+  on unmount/dispose. The Svelte and Vue adapters are plain action/directive
+  objects, so they do not add runtime dependencies to the package.
 - **`css/analytical.css` — the analytical roll-up.** This convenience file
-  `@import`s exactly **seven** analytical-figure leaves: `annotations`,
-  `legend`, `marks`, `connectors`, `spotlight`, `crosshair`, and `selection`.
-  The adjacent opt-in leaves — `sources`, `state`, `generated`, `workbench`,
-  and `command` — are report/tooling/trust surfaces that are intentionally
-  **not** part of the analytical roll-up and must be imported individually.
-  Importing `analytical.css` does not pull in any of those five.
+  `@import`s exactly **nine** analytical figure/evidence leaves: `figure`,
+  `annotations`, `legend`, `marks`, `connectors`, `spotlight`, `crosshair`,
+  `selection`, and `highlights`. The adjacent opt-in leaves — `sources`,
+  `interval`, `clamp`, `state`, `generated`, `workbench`, and `command` — are
+  report/tooling/trust surfaces that are intentionally **not** part of the
+  analytical roll-up and must be imported individually. Importing
+  `analytical.css` does not pull in any of those seven.
 - **Root export (`.`) is CSS-only.** `exports["."]` resolves to the CSS
   bundle (`dist/bronto.css`). It is a CSS side-effect import for CSS-aware
   bundlers (`@import '@ponchia/ui'` in CSS, or a side-effect
   `import '@ponchia/ui'` in Vite/Astro/SvelteKit). There is no runtime JS at
   the package root — Node/runtime JS imports of `.` are not supported. All JS
   entrypoints are explicit subpaths (`/behaviors`, `/classes`, `/tokens`,
-  `/glyphs`, `/react`, `/solid`, `/qwik`, `/skins`, `/charts`). This is a
-  permanent, intentional contract.
+  `/glyphs`, `/annotations`, `/connectors`, `/react`, `/solid`, `/qwik`,
+  `/skins`, `/charts`, `/mermaid`, `/d2`, `/vega`). This is a permanent,
+  intentional contract.
 
 ## Repository layout
 
@@ -108,9 +115,10 @@ generator overwrites them and a drift gate fails CI).
 | --- | --- | --- | --- |
 | `css/` | source | yes | The framework. Hand-authored `@layer bronto` CSS. (`css/tokens.css` palette blocks and `css/generated.css` are generated — see below.) |
 | `tokens/index.js` | source | yes | The single source of truth for token **values** (`cssVars`). |
-| `classes/index.js`, `behaviors/`, `annotations/`, `connectors/`, `react/`, `solid/`, `qwik/`, `glyphs/`, `shiki/` | source · published-subpath (path-frozen) | yes — but **do not move** | Authored ESM shipped as-is; the dir name is the public import path. The `.d.ts` beside them are generated/drift-checked: `connectors`/`annotations`/`react`/`solid`/`qwik`/`behaviors` are emitted from JSDoc by `tsc` (`npm run dts:emit`), `classes`/`tokens`/`glyphs` from the runtime. No leaf `.d.ts` is hand-maintained. |
+| `classes/index.js`, `behaviors/`, `annotations/`, `connectors/`, `react/`, `solid/`, `qwik/`, `svelte/`, `vue/`, `glyphs/`, `shiki/` | source · published-subpath (path-frozen) | yes — but **do not move** | Authored ESM shipped as-is; the dir name is the public import path. The `.d.ts` beside them are generated/drift-checked: `connectors`/`annotations`/`react`/`solid`/`qwik`/`svelte`/`vue`/`behaviors` are emitted from JSDoc by `tsc` (`npm run dts:emit`), `classes`/`tokens`/`glyphs` from the runtime. No leaf `.d.ts` is hand-maintained. |
+| `schemas/*.schema.json` | source · published schema files (path-frozen) | yes — but **do not move exported files** | Declarative JSON Schema contracts for sidecars/tooling data. Each exported schema file path is public; the directory itself is not a wildcard import. No validator runtime ships. |
 | `dist/` | generated | no | Build of `css/` (`npm run dist:build`); byte-checked by `check:dist`. |
-| `tokens/index.json`, `tokens/resolved.json`, `tokens/tokens.dtcg.json`, `tokens/charts.json`, `classes/index.d.ts`, `tokens/index.d.ts`, `tokens/{skins,charts}.d.ts`, `glyphs/glyphs.d.ts`, `classes/vscode.css-custom-data.json`, `docs/reference.md` | generated | no | Committed build artifacts; regenerate with `npm run prepack`, never hand-edit. Drift-checked in `npm run check`. |
+| `tokens/index.json`, `tokens/resolved.json`, `tokens/tokens.dtcg.json`, `tokens/figma.variables.json`, `tokens/charts.json`, `classes/index.d.ts`, `tokens/index.d.ts`, `tokens/{skins,charts}.d.ts`, `glyphs/glyphs.d.ts`, `classes/vscode.css-custom-data.json`, `docs/reference.md` | generated | no | Committed build artifacts; regenerate with `npm run prepack`, never hand-edit. Drift-checked in `npm run check`. |
 | `fonts/` | vendored | — | The Doto webfont (woff2) + its OFL license. |
 | `scripts/` | tooling | yes | `gen-*` regenerate artifacts, `check-*` are the drift/contract gates wired into `npm run check`, plus `build-dist`, `serve`, `size-report`. |
 | `docs/` | source (mostly) | yes | Hand-authored docs + ADRs; the curated subset in `package.json` `files` ships in the tarball. `docs/reference.md` is generated. |
@@ -134,9 +142,9 @@ gating" below), so a version that fails any invariant never reaches npm.
 | Invariant                                       | Enforced by         |
 | ----------------------------------------------- | ------------------- |
 | exports / import graph / `files` consistent     | `check-exports.mjs` |
-| pure generated mirrors fresh — `tokens.css`/`index.json`, `dtcg.json`, `resolved.json`, `classes`/`tokens` `.d.ts`, `reference.md`, vscode data — each byte-equal to its generator (registry: `scripts/lib/artifacts.mjs`) | `check-fresh.mjs` |
+| pure generated mirrors fresh — `tokens.css`/`index.json`, `dtcg.json`, `resolved.json`, `figma.variables.json`, `classes`/`tokens` `.d.ts`, `reference.md`, vscode data — each byte-equal to its generator (registry: `scripts/lib/artifacts.mjs`) | `check-fresh.mjs` |
 | `classes` `cls` ⇄ `.ui-*` selectors             | `check-classes.mjs` |
-| `connectors`/`annotations`/`react`/`solid`/`qwik`/`behaviors` `.d.ts` (+ maps) == fresh `tsc` emit of their JSDoc | `check-dts-emit.mjs` |
+| `connectors`/`annotations`/`react`/`solid`/`qwik`/`svelte`/`vue`/`behaviors` `.d.ts` (+ maps) == fresh `tsc` emit of their JSDoc | `check-dts-emit.mjs` |
 | legend swatch colours ⊆ `charts.js` · opt-in   | `check-legend.mjs`  |
 | color tokens tiered · no raw chromatic color in components | `check-color-policy.mjs` |
 | `css/skins.css` ⇄ `tokens/skins.js` · colorways opt-in | `check-skins.mjs` |
@@ -145,6 +153,10 @@ gating" below), so a version that fails any invariant never reaches npm.
 | `shiki/nothing.json` valid + on rationed palette | `check-shiki.mjs`  |
 | `dist/*.css` == fresh build of `css/` + budget  | `check-dist.mjs`    |
 | published tarball == intended `files` only      | `check-pack.mjs`    |
+| packed public text contains no private terms, local paths, or secret-looking assignments | `check-public-hygiene.mjs` |
+| CSS custom-property references resolve or carry an explicit fallback/host boundary | `check-variables.mjs` |
+| `MIGRATIONS.json` edges have structured rules and matching docs | `check-migrations.mjs` |
+| example inventory ⇄ CI matrix ⇄ browser-smoke list ⇄ README rows ⇄ preview ports | `check-examples.mjs` |
 | published `.d.ts` compile + reject typos        | `tsc` (`check:types`) |
 | CSS style/correctness                           | Stylelint           |
 | non-CSS source style                            | Prettier (`check:format`) |
@@ -163,29 +175,40 @@ freshness (`check-fresh`).
 
 ## Release gating
 
-`release.yml` (on a pushed `v*` tag) is a five-job DAG, serialized by a
+`release.yml` (on a pushed `v*` tag) is a six-job DAG, serialized by a
 `concurrency: release-publish` group so two tags can't race the dist-tag
 pointer:
 
-- `validate` — read-only: `npm run check` + tag↔version match. `check`
-  includes `check:release`; for a prerelease tag the base version's
-  CHANGELOG section need only exist (`## Unreleased — x.y.z` is fine) —
-  only a stable release must carry a dated heading.
-- `e2e` — Playwright (visual + axe a11y, both themes, cross-engine) in
-  the pinned `mcr.microsoft.com/playwright` container.
+- `validate` — read-only: verifies the tag commit is reachable from `main`,
+  then runs `npm run check`, `npm test`, and the tag↔version match. `check`
+  includes `check:release`; for a prerelease tag the base version's CHANGELOG
+  section need only exist (`## Unreleased — x.y.z` is fine) — only a stable
+  release must carry a dated heading.
+- `e2e` — `needs: validate`: Playwright (visual + axe a11y, both themes,
+  cross-engine) in the pinned `mcr.microsoft.com/playwright` container. Local
+  cross-engine reproduction without screenshot rasterisation is
+  `npm run test:e2e:nonpixel`; use `npm run test:e2e` or
+  `npm run test:e2e:chromium` only in the pinned container when the pixel
+  baseline gate itself is in scope.
 - `examples` — `needs: validate`: builds the downstream example
   apps against the **packed tarball**, mirroring CI. Catches a broken
   published surface (exports map / missing file / unresolved subpath)
   that `check:pack`'s file-allowlist inspection cannot — so the release
   path runs the same consumer smoke as merge-to-main.
-- `publish-npm` — `needs: [validate, e2e, examples]`: `npm publish` with
-  provenance. Runs in the `npm-publish` **Environment** (required-reviewer
-  protection), so after the gates pass the run pauses for a manual approval
-  in the Actions UI before anything reaches npm — a guard against an
-  accidental tag push publishing. Dist-tag is derived from the tag: stable
-  (`v0.4.0`) → `latest`; SemVer prerelease (`v0.4.0-rc.1`, any hyphenated
-  identifier) → `next`, so the default `npm i @ponchia/ui` never moves onto
-  an unstable build (opt in with `@ponchia/ui@next`).
+- `publish-preflight` — `needs: [validate, e2e, examples]`: installs with
+  lifecycle scripts disabled, runs `npm pack --dry-run --ignore-scripts`, and
+  writes the pack manifest + size report to the job summary for review before
+  the protected publish approval.
+- `publish-npm` — `needs: publish-preflight`: `npm publish --ignore-scripts`
+  with provenance. Runs in the `npm-publish` **Environment**
+  (required-reviewer protection), so after the gates and preflight pass the run
+  pauses for a manual approval in the Actions UI before anything reaches npm —
+  a guard against an accidental tag push publishing. Dist-tag is derived from
+  the tag: stable (`v0.4.0`) → `latest`; SemVer prerelease (`v0.4.0-rc.1`, any
+  hyphenated identifier) → `next`, so the default `npm i @ponchia/ui` never
+  moves onto an unstable build (opt in with `@ponchia/ui@next`). Post-publish
+  `npm view` registry observation is best-effort only: a registry read flake must
+  not fail the job after the immutable publish already succeeded.
 - `release-notes` — `needs: publish-npm`: a GitHub Release for visibility
   (transitively gated on a successful publish, hence on the gates above);
   prerelease tags are flagged so they aren't surfaced as "Latest". The Release
@@ -194,7 +217,7 @@ pointer:
   source of truth, surfaced where readers look.
 
 Because the documented install path is the npm package, **the npm publish
-is a real gate**: if `validate`, `e2e`, *or* `examples` fails,
+is a real gate**: if `validate`, `e2e`, `examples`, or `publish-preflight` fails,
 `publish-npm` never runs, the version never reaches the registry, and
 consumers never resolve it.
 (Corollary: a flaky `e2e` blocks releases — that is deliberate; fix the
@@ -210,9 +233,9 @@ Process still applies: bump `package.json`, land on `main`, go green, tag.
 ## Decision — distribution: npm public `@ponchia/ui`
 
 Decided 2026-05-15. The framework is consumed by a growing set of
-heterogeneous web frontends (Astro, SvelteKit, React, Solid, Qwik, vanilla),
-several deploying via third-party CI. The only option where onboarding a new
-frontend is `npm i @ponchia/ui` with zero per-consumer config is **npm
+heterogeneous web frontends (Astro, SvelteKit, React, Solid, Qwik, Vue,
+Tailwind, vanilla), several deploying via third-party CI. The only option where
+onboarding a new frontend is `npm i @ponchia/ui` with zero per-consumer config is **npm
 public**, and it uniquely also closes the release-gating gap (publish *is*
 the gate). GitHub Packages was rejected: it requires auth to install even
 public packages, i.e. an `.npmrc` + token on every frontend and CI runner —
@@ -237,8 +260,9 @@ explained, not surprising.
   provenance.
 - Run `npm pack --dry-run --json` locally or from CI logs and confirm the
   intended file count/payload.
-- Build the packed examples matrix (vanilla, Astro, SvelteKit, React, Solid, Qwik)
-  from the tarball, not a workspace link.
+- Build the packed examples matrix from the tarball, not a workspace link:
+  `npm run test:examples` covers vanilla, Astro, SvelteKit, Vue, React, Solid,
+  Qwik, Tailwind, and report-static, with browser smokes for runtime examples.
 - Confirm the GitHub Release body matches the curated changelog section.
 - If a bad package is published, deprecate that exact version on npm, publish a
   patched version, and link the deprecation note to the changelog/security

package/docs/clamp.md

@@ -0,0 +1,49 @@
+# Clamp
+
+`@ponchia/ui/css/clamp.css` is an opt-in bounded excerpt primitive for source
+excerpts, claim basis, caveats, and evidence text that should scan compactly but
+remain reachable.
+
+```css
+@import '@ponchia/ui';
+@import '@ponchia/ui/css/clamp.css';
+```
+
+## Bounded excerpt
+
+```html
+<div class="ui-clamp" style="--clamp-lines: 3">
+  <input class="ui-clamp__toggle" id="source-excerpt" type="checkbox" />
+  <p class="ui-clamp__body">
+    The source excerpt remains real text in the DOM. The visible block is
+    clamped for scanning, but the full passage is available through the reveal
+    control and is expanded for print.
+  </p>
+  <label class="ui-clamp__control" for="source-excerpt">
+    <span class="ui-clamp__more">Show more</span>
+    <span class="ui-clamp__less">Show less</span>
+  </label>
+</div>
+```
+
+If the host should not offer expansion, omit the toggle and control and keep
+only `ui-clamp` plus `ui-clamp__body`.
+
+## Contract
+
+| Class | Role |
+| --- | --- |
+| `.ui-clamp` | Wrapper and `--clamp-lines` host. |
+| `.ui-clamp__body` | The clamped text block. |
+| `.ui-clamp__toggle` | Optional checkbox state for CSS-only reveal. |
+| `.ui-clamp__control` | Optional visible reveal control. |
+| `.ui-clamp__more` / `.ui-clamp__less` | Explicit labels for closed/open state. |
+
+| Custom property | On | Meaning |
+| --- | --- | --- |
+| `--clamp-lines` | `.ui-clamp` | Number of lines before the excerpt is clamped. Default `4`. |
+
+## Print
+
+Print expands the body and hides the toggle/control. Do not use `ui-clamp` to
+hide information from archived or PDF output.

package/docs/contrast.md

@@ -15,7 +15,8 @@ model (`tokens/resolved.json`) so it cannot drift from the palette, and
 
 - **Body / UI text** pairings are guaranteed **WCAG 2.1 AA — 4.5:1**
   (1.4.3). This covers `--text`, `--text-soft`, `--text-dim`,
-  `--accent-text`, and the primary-button label.
+  `--accent-text`, neutral text on soft accent-tint components, and the
+  primary-button label.
 - **Non-text UI** (focus ring, accent fill, status colour) is guaranteed
   **3:1** (1.4.11 non-text contrast / the large-text bar). These are
   deliberately *not* held to 4.5:1 — a focus
@@ -32,7 +33,8 @@ model (`tokens/resolved.json`) so it cannot drift from the palette, and
   further but is out of scope for this gated baseline.
 
 Translucent foregrounds (soft fills) are alpha-flattened over their
-background before measuring — the ratio the eye actually gets.
+background before measuring. When a translucent background is a component
+tint, the table names the neutral base it is composited over.
 
 Overall: **all contractual pairings meet their floor ✅**.
 
@@ -51,6 +53,7 @@ Overall: **all contractual pairings meet their floor ✅**.
 | `--text-dim` | `--surface-muted` | Dim/meta text on a muted panel | AA text (4.5:1) | 4.74:1 | Lc 66.7 | ✅ pass |
 | `--accent-text` | `--bg` | Accent text on page background | AA text (4.5:1) | 6.32:1 | Lc 75.4 | ✅ pass |
 | `--accent-text` | `--surface` | Accent text on a card | AA text (4.5:1) | 6.96:1 | Lc 82.1 | ✅ pass |
+| `--text-soft` | `--accent-soft` over `--surface-muted` | Neutral tag/badge text on an accent tint | AA text (4.5:1) | 8.88:1 | Lc 77.0 | ✅ pass |
 | `--accent-text` | `--accent-soft` | Accent text on an accent tint | Advisory (translucent tint — not gated) | 5.91:1 | Lc 71.0 | ℹ️ not gated |
 | `--accent-text` | `--bg-accent` | Accent text on an accent-tinted surface | Advisory (translucent tint — not gated) | 6.31:1 | Lc 75.3 | ℹ️ not gated |
 | `--button-text` | `--accent` | Label on the primary button | AA text (4.5:1) | 5.18:1 | Lc 78.9 | ✅ pass |
@@ -77,10 +80,11 @@ Overall: **all contractual pairings meet their floor ✅**.
 | `--text-dim` | `--bg` | Dim/meta text on page background | AA text (4.5:1) | 7.16:1 | Lc 50.3 | ✅ pass |
 | `--text-dim` | `--surface` | Dim/meta text on a card | AA text (4.5:1) | 6.52:1 | Lc 49.3 | ✅ pass |
 | `--text-dim` | `--surface-muted` | Dim/meta text on a muted panel | AA text (4.5:1) | 5.94:1 | Lc 48.1 | ✅ pass |
-| `--accent-text` | `--bg` | Accent text on page background | AA text (4.5:1) | 6.14:1 | Lc 44.9 | ✅ pass |
-| `--accent-text` | `--surface` | Accent text on a card | AA text (4.5:1) | 5.58:1 | Lc 43.9 | ✅ pass |
-| `--accent-text` | `--accent-soft` | Accent text on an accent tint | Advisory (translucent tint — not gated) | 2.53:1 | Lc 43.8 | ℹ️ not gated |
-| `--accent-text` | `--bg-accent` | Accent text on an accent-tinted surface | Advisory (translucent tint — not gated) | 2.75:1 | Lc 49.1 | ℹ️ not gated |
+| `--accent-text` | `--bg` | Accent text on page background | AA text (4.5:1) | 6.42:1 | Lc 46.6 | ✅ pass |
+| `--accent-text` | `--surface` | Accent text on a card | AA text (4.5:1) | 5.84:1 | Lc 45.6 | ✅ pass |
+| `--text-soft` | `--accent-soft` over `--surface-muted` | Neutral tag/badge text on an accent tint | AA text (4.5:1) | 8.05:1 | Lc 68.4 | ✅ pass |
+| `--accent-text` | `--accent-soft` | Accent text on an accent tint | Advisory (translucent tint — not gated) | 2.42:1 | Lc 42.2 | ℹ️ not gated |
+| `--accent-text` | `--bg-accent` | Accent text on an accent-tinted surface | Advisory (translucent tint — not gated) | 2.63:1 | Lc 47.4 | ℹ️ not gated |
 | `--button-text` | `--accent` | Label on the primary button | AA text (4.5:1) | 5.95:1 | Lc 42.9 | ✅ pass |
 | `--on-accent` | `--accent` | Ink on an accent fill | AA text (4.5:1) | 5.95:1 | Lc 42.9 | ✅ pass |
 | `--focus-ring` | `--bg` | Focus ring vs page background | UI / large (3:1) | 5.31:1 | Lc 40.0 | ✅ pass |
@@ -109,8 +113,9 @@ palette untouched). Accents are authored in OKLCH; `--accent-text` is the
 | --- | --- | --- | --- | --- | --- | --- |
 | `--accent-text` | `--bg` | Accent text on page background | AA text (4.5:1) | 6.75:1 | Lc 78.9 | ✅ pass |
 | `--accent-text` | `--surface` | Accent text on a card | AA text (4.5:1) | 7.44:1 | Lc 85.6 | ✅ pass |
-| `--accent-text` | `--accent-soft` | Accent text on an accent tint | Advisory (translucent tint — not gated) | 6.31:1 | Lc 74.5 | ℹ️ not gated |
-| `--accent-text` | `--bg-accent` | Accent text on an accent-tinted surface | Advisory (translucent tint — not gated) | 6.74:1 | Lc 78.8 | ℹ️ not gated |
+| `--text-soft` | `--accent-soft` over `--surface-muted` | Neutral tag/badge text on an accent tint | AA text (4.5:1) | 9.13:1 | Lc 78.7 | ✅ pass |
+| `--accent-text` | `--accent-soft` | Accent text on an accent tint | Advisory (translucent tint — not gated) | 6.48:1 | Lc 76.1 | ℹ️ not gated |
+| `--accent-text` | `--bg-accent` | Accent text on an accent-tinted surface | Advisory (translucent tint — not gated) | 6.85:1 | Lc 79.9 | ℹ️ not gated |
 | `--button-text` | `--accent` | Label on the primary button | AA text (4.5:1) | 5.66:1 | Lc 83.3 | ✅ pass |
 | `--on-accent` | `--accent` | Ink on an accent fill | AA text (4.5:1) | 5.66:1 | Lc 83.3 | ✅ pass |
 | `--focus-ring` | `--bg` | Focus ring vs page background | UI / large (3:1) | 5.14:1 | Lc 71.4 | ✅ pass |
@@ -121,10 +126,11 @@ palette untouched). Accents are authored in OKLCH; `--accent-text` is the
 
 | Foreground | Background | Role | Held to | Ratio | APCA _(advisory)_ | Verdict |
 | --- | --- | --- | --- | --- | --- | --- |
-| `--accent-text` | `--bg` | Accent text on page background | AA text (4.5:1) | 11.57:1 | Lc 74.8 | ✅ pass |
-| `--accent-text` | `--surface` | Accent text on a card | AA text (4.5:1) | 10.52:1 | Lc 73.8 | ✅ pass |
-| `--accent-text` | `--accent-soft` | Accent text on an accent tint | Advisory (translucent tint — not gated) | 1.34:1 | Lc 15.1 | ℹ️ not gated |
-| `--accent-text` | `--bg-accent` | Accent text on an accent-tinted surface | Advisory (translucent tint — not gated) | 1.46:1 | Lc 20.3 | ℹ️ not gated |
+| `--accent-text` | `--bg` | Accent text on page background | AA text (4.5:1) | 11.84:1 | Lc 76.1 | ✅ pass |
+| `--accent-text` | `--surface` | Accent text on a card | AA text (4.5:1) | 10.77:1 | Lc 75.1 | ✅ pass |
+| `--text-soft` | `--accent-soft` over `--surface-muted` | Neutral tag/badge text on an accent tint | AA text (4.5:1) | 6.83:1 | Lc 65.5 | ✅ pass |
+| `--accent-text` | `--accent-soft` | Accent text on an accent tint | Advisory (translucent tint — not gated) | 1.46:1 | Lc 20.8 | ℹ️ not gated |
+| `--accent-text` | `--bg-accent` | Accent text on an accent-tinted surface | Advisory (translucent tint — not gated) | 1.51:1 | Lc 23.2 | ℹ️ not gated |
 | `--button-text` | `--accent` | Label on the primary button | AA text (4.5:1) | 11.88:1 | Lc 71.6 | ✅ pass |
 | `--on-accent` | `--accent` | Ink on an accent fill | AA text (4.5:1) | 11.88:1 | Lc 71.6 | ✅ pass |
 | `--focus-ring` | `--bg` | Focus ring vs page background | UI / large (3:1) | 10.60:1 | Lc 69.9 | ✅ pass |
@@ -137,8 +143,9 @@ palette untouched). Accents are authored in OKLCH; `--accent-text` is the
 | --- | --- | --- | --- | --- | --- | --- |
 | `--accent-text` | `--bg` | Accent text on page background | AA text (4.5:1) | 12.23:1 | Lc 93.3 | ✅ pass |
 | `--accent-text` | `--surface` | Accent text on a card | AA text (4.5:1) | 13.47:1 | Lc 99.9 | ✅ pass |
-| `--accent-text` | `--accent-soft` | Accent text on an accent tint | Advisory (translucent tint — not gated) | 11.43:1 | Lc 88.8 | ℹ️ not gated |
-| `--accent-text` | `--bg-accent` | Accent text on an accent-tinted surface | Advisory (translucent tint — not gated) | 12.22:1 | Lc 93.2 | ℹ️ not gated |
+| `--text-soft` | `--accent-soft` over `--surface-muted` | Neutral tag/badge text on an accent tint | AA text (4.5:1) | 8.78:1 | Lc 76.3 | ✅ pass |
+| `--accent-text` | `--accent-soft` | Accent text on an accent tint | Advisory (translucent tint — not gated) | 11.31:1 | Lc 88.2 | ℹ️ not gated |
+| `--accent-text` | `--bg-accent` | Accent text on an accent-tinted surface | Advisory (translucent tint — not gated) | 12.15:1 | Lc 92.8 | ℹ️ not gated |
 | `--button-text` | `--accent` | Label on the primary button | AA text (4.5:1) | 11.74:1 | Lc 100.6 | ✅ pass |
 | `--on-accent` | `--accent` | Ink on an accent fill | AA text (4.5:1) | 11.74:1 | Lc 100.6 | ✅ pass |
 | `--focus-ring` | `--bg` | Focus ring vs page background | UI / large (3:1) | 10.66:1 | Lc 90.4 | ✅ pass |
@@ -149,10 +156,11 @@ palette untouched). Accents are authored in OKLCH; `--accent-text` is the
 
 | Foreground | Background | Role | Held to | Ratio | APCA _(advisory)_ | Verdict |
 | --- | --- | --- | --- | --- | --- | --- |
-| `--accent-text` | `--bg` | Accent text on page background | AA text (4.5:1) | 12.47:1 | Lc 79.1 | ✅ pass |
-| `--accent-text` | `--surface` | Accent text on a card | AA text (4.5:1) | 11.35:1 | Lc 78.1 | ✅ pass |
-| `--accent-text` | `--accent-soft` | Accent text on an accent tint | Advisory (translucent tint — not gated) | 1.25:1 | Lc 11.0 | ℹ️ not gated |
-| `--accent-text` | `--bg-accent` | Accent text on an accent-tinted surface | Advisory (translucent tint — not gated) | 1.35:1 | Lc 16.3 | ℹ️ not gated |
+| `--accent-text` | `--bg` | Accent text on page background | AA text (4.5:1) | 12.72:1 | Lc 80.3 | ✅ pass |
+| `--accent-text` | `--surface` | Accent text on a card | AA text (4.5:1) | 11.57:1 | Lc 79.3 | ✅ pass |
+| `--text-soft` | `--accent-soft` over `--surface-muted` | Neutral tag/badge text on an accent tint | AA text (4.5:1) | 6.66:1 | Lc 65.0 | ✅ pass |
+| `--accent-text` | `--accent-soft` | Accent text on an accent tint | Advisory (translucent tint — not gated) | 1.38:1 | Lc 18.0 | ℹ️ not gated |
+| `--accent-text` | `--bg-accent` | Accent text on an accent-tinted surface | Advisory (translucent tint — not gated) | 1.42:1 | Lc 19.9 | ℹ️ not gated |
 | `--button-text` | `--accent` | Label on the primary button | AA text (4.5:1) | 12.86:1 | Lc 75.6 | ✅ pass |
 | `--on-accent` | `--accent` | Ink on an accent fill | AA text (4.5:1) | 12.86:1 | Lc 75.6 | ✅ pass |
 | `--focus-ring` | `--bg` | Focus ring vs page background | UI / large (3:1) | 11.48:1 | Lc 74.1 | ✅ pass |
@@ -165,8 +173,9 @@ palette untouched). Accents are authored in OKLCH; `--accent-text` is the
 | --- | --- | --- | --- | --- | --- | --- |
 | `--accent-text` | `--bg` | Accent text on page background | AA text (4.5:1) | 6.22:1 | Lc 76.6 | ✅ pass |
 | `--accent-text` | `--surface` | Accent text on a card | AA text (4.5:1) | 6.85:1 | Lc 83.3 | ✅ pass |
-| `--accent-text` | `--accent-soft` | Accent text on an accent tint | Advisory (translucent tint — not gated) | 5.81:1 | Lc 72.2 | ℹ️ not gated |
-| `--accent-text` | `--bg-accent` | Accent text on an accent-tinted surface | Advisory (translucent tint — not gated) | 6.21:1 | Lc 76.5 | ℹ️ not gated |
+| `--text-soft` | `--accent-soft` over `--surface-muted` | Neutral tag/badge text on an accent tint | AA text (4.5:1) | 9.16:1 | Lc 78.9 | ✅ pass |
+| `--accent-text` | `--accent-soft` | Accent text on an accent tint | Advisory (translucent tint — not gated) | 5.98:1 | Lc 74.1 | ℹ️ not gated |
+| `--accent-text` | `--bg-accent` | Accent text on an accent-tinted surface | Advisory (translucent tint — not gated) | 6.32:1 | Lc 77.7 | ℹ️ not gated |
 | `--button-text` | `--accent` | Label on the primary button | AA text (4.5:1) | 5.19:1 | Lc 80.7 | ✅ pass |
 | `--on-accent` | `--accent` | Ink on an accent fill | AA text (4.5:1) | 5.19:1 | Lc 80.7 | ✅ pass |
 | `--focus-ring` | `--bg` | Focus ring vs page background | UI / large (3:1) | 4.71:1 | Lc 68.6 | ✅ pass |
@@ -177,10 +186,11 @@ palette untouched). Accents are authored in OKLCH; `--accent-text` is the
 
 | Foreground | Background | Role | Held to | Ratio | APCA _(advisory)_ | Verdict |
 | --- | --- | --- | --- | --- | --- | --- |
-| `--accent-text` | `--bg` | Accent text on page background | AA text (4.5:1) | 12.97:1 | Lc 81.8 | ✅ pass |
-| `--accent-text` | `--surface` | Accent text on a card | AA text (4.5:1) | 11.80:1 | Lc 80.8 | ✅ pass |
-| `--accent-text` | `--accent-soft` | Accent text on an accent tint | Advisory (translucent tint — not gated) | 1.20:1 | Lc 8.4 | ℹ️ not gated |
-| `--accent-text` | `--bg-accent` | Accent text on an accent-tinted surface | Advisory (translucent tint — not gated) | 1.30:1 | Lc 13.7 | ℹ️ not gated |
+| `--accent-text` | `--bg` | Accent text on page background | AA text (4.5:1) | 13.18:1 | Lc 82.8 | ✅ pass |
+| `--accent-text` | `--surface` | Accent text on a card | AA text (4.5:1) | 11.99:1 | Lc 81.8 | ✅ pass |
+| `--text-soft` | `--accent-soft` over `--surface-muted` | Neutral tag/badge text on an accent tint | AA text (4.5:1) | 6.66:1 | Lc 65.0 | ✅ pass |
+| `--accent-text` | `--accent-soft` | Accent text on an accent tint | Advisory (translucent tint — not gated) | 1.33:1 | Lc 15.3 | ℹ️ not gated |
+| `--accent-text` | `--bg-accent` | Accent text on an accent-tinted surface | Advisory (translucent tint — not gated) | 1.37:1 | Lc 17.3 | ℹ️ not gated |
 | `--button-text` | `--accent` | Label on the primary button | AA text (4.5:1) | 13.75:1 | Lc 79.7 | ✅ pass |
 | `--on-accent` | `--accent` | Ink on an accent fill | AA text (4.5:1) | 13.75:1 | Lc 79.7 | ✅ pass |
 | `--focus-ring` | `--bg` | Focus ring vs page background | UI / large (3:1) | 12.27:1 | Lc 78.5 | ✅ pass |

package/docs/d2.md

@@ -153,6 +153,43 @@ paste the resolved hex from [`tokens/resolved.json`](./architecture.md) for a
 For anything larger or graph-laid-out, run D2 with the theme map and freeze its
 output — don't hand-lay a complex graph.
 
+### Tokenize D2 output — one inline SVG that re-skins live
+
+A frozen D2 SVG carries **resolved hex**, so a dynamic (screen-only) report
+would need a light SVG and a dark SVG and JS/CSS to swap them — and the hidden
+twin is dead weight. Instead, post-process the rendered SVG's colours back into
+tokens, and ONE inline SVG re-skins live when `data-theme` flips (this is the
+inverse of the resolved-hex rule above: it only works for **inline** SVG in a
+themed page, never for `file://`/PDF artifacts or `<img>` embeds):
+
+1. Render **light only** with the theme map (`brontoD2Vars()` prepended).
+2. D2 emits each colour twice: as inline `fill="#hex"`/`stroke="#hex"` AND as
+   class rules in an embedded `<style>` block — **not just `.fill-*` /
+   `.stroke-*`: there are also `.color-*` and `.background-color-*` rules**
+   (they carry the same hex and trip any raw-colour gate). **The style rules
+   win over the inline attributes**, so strip ALL hex-bearing rules from the
+   `<style>` first — only then do attribute rewrites take effect.
+3. Rewrite the inline hex → `var(--token)` using the slot table above
+   (`N1`→`--text`, `N4`/`B1`→`--line-strong`, `N6`/`B4`→`--panel-soft`,
+   `B6`→`--panel`, accent class fill→`--accent`, its ink→`--on-accent`, …).
+4. Leave `<mask>` `fill="black"`/`"white"` keywords alone — that is a
+   luminance mask, not a colour.
+5. Make the outer `<svg>` fluid (drop `width`/`height`, keep `viewBox`) and
+   inject `<title>` + `<desc>` with `role="img" aria-labelledby` before
+   inlining.
+
+The result follows the page theme with zero swap machinery, and avoids the
+visual-QA traps of the two-SVG approach (a `display:none` twin is easy to
+flag as a blank figure).
+
+> **Avoid `tooltip:` and `|md` markdown shapes in frozen report SVGs.** Both
+> make D2 embed GitHub-Primer styling that survives tokenization: tooltips
+> render Octicon info-icons and markdown text ships Primer CSS, each full of
+> foreign `var(--color-*)` references and extra hex (`#2e3346`-class values
+> outside the theme map). Fold tooltip text into the node label and use plain
+> labels or `shape: text` instead — or strip the tooltip appendix from the
+> SVG before inlining.
+
 ### Fit to small screens
 
 D2 emits an SVG with explicit `width`/`height` from its layout, so on a narrow

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
 
@@ -226,14 +227,38 @@ precision signal the product does not have).
 
 The CSS cores of candidates 1–5 shipped in 0.5.0, the 2026 scout batch shipped
 in PRs #97/#100, and scout batch #2 (textref / bullet / term / toc / tree)
-shipped 2026-06-04. The remaining active work, in order:
-
-1. `ui-job` / `ui-conflict` lifecycle surfaces (candidate 2).
-2. The `ui-splitter` ARIA window-splitter behavior + drag affordances
-   (candidate 4) — also the gating consumer for `ui-tree`'s deferred roving-focus
-   tree kernel.
-
-Deferred items stay gated on a real consumer needing them. This order keeps
+shipped 2026-06-04.
+
+**The proven lane is report / provenance / explanation** — it is the only lane
+with a real consumer (LLM-authored reports). The command, workbench, and
+durable-state lanes shipped their CSS cores and have had **no non-demo
+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 primitives shipped in 0.6.7
+
+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.
+2. `ui-clamp` — N-line clamp + fade + native show-more for claim-basis and
+   source excerpts (`-webkit-line-clamp` + `mask-image` + `<details>`).
+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-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,
 framework-agnostic primitives that make complex interfaces clearer.