@ponchia/ui 0.6.6 → 0.6.8

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

@@ -0,0 +1,96 @@
+# Migrating 0.4 → 0.5
+
+0.5.0 builds out the **analytical & communication** identity: an opt-in suite of
+primitives for interfaces that explain themselves — SVG annotations, standalone
+legends, text/evidence marks, leader-line connectors, a guided-focus spotlight, a
+crosshair/readout, a selection vocabulary (rolled up in
+[`css/analytical.css`](../../css/analytical.css)), plus standalone
+`sources`/provenance, lifecycle `state`, AI-trust `generated`, `workbench` and a
+`command` palette.
+
+Almost all of it is **additive and opt-in** — the default `dist/bronto.css`
+renders identically and needs no change. There are **three breaking changes**,
+and every one of them lives in the _opt-in_ report / analytical layer. The
+machine-readable map is [`MIGRATIONS.json`](../../MIGRATIONS.json) (now shipped
+in the package).
+
+## 1. The report kit's chart key moved to the standalone Legends layer
+
+`.ui-chart__legend` / `.ui-chart__swatch` were **removed** from
+`css/report.css`. The data key is now the standalone Legends layer
+(`css/legend.css`), which is richer (categorical / gradient / threshold /
+pattern keys, an optional interactive series toggle) and reusable outside
+reports.
+
+**Migration:** add the legend leaf next to the report kit and rework the wrapper.
+
+```diff
++ <link rel="stylesheet" href="@ponchia/ui/css/legend.css">
+
+- <ul class="ui-chart__legend">
+-   <li><span class="ui-chart__swatch" style="--chart-color: var(--chart-1)"></span> Research</li>
+- </ul>
++ <ul class="ui-legend">
++   <li class="ui-legend__item">
++     <span class="ui-legend__swatch" style="--chart-color: var(--chart-1)"></span>
++     <span class="ui-legend__label">Research</span>
++   </li>
++ </ul>
+```
+
+The swatch's `--chart-color` / `--chart-pattern` inline contract is unchanged;
+the categorical colour is also available via `.ui-legend__swatch--1..8`. Full
+grammar: [`docs/legends.md`](../legends.md). Quick rename:
+
+```bash
+rg -l 'ui-chart__legend|ui-chart__swatch' .
+# s/ui-chart__swatch/ui-legend__swatch/g  + rework the <ul> wrapper as above
+```
+
+## 2. The marks rationed-accent tone `evidence` → `accent`
+
+To match the connector/annotation tone vocabulary, the **tone** modifier on
+text marks and bracket notes was renamed:
+
+| 0.4 | 0.5 |
+| --- | --- |
+| `.ui-mark--evidence` | `.ui-mark--accent` |
+| `.ui-bracket-note--evidence` | `.ui-bracket-note--accent` |
+| `ui.mark({ tone: 'evidence' })` | `ui.mark({ tone: 'accent' })` |
+| `ui.bracketNote({ tone: 'evidence' })` | `ui.bracketNote({ tone: 'accent' })` |
+
+**Do _not_ rewrite** `ui.annotation({ variant: 'evidence' })` or the
+`.ui-annotation--evidence` subject marker — those are a marker **shape**, not a
+tone, and are unchanged.
+
+```bash
+rg -l 'ui-mark--evidence|ui-bracket-note--evidence' .
+# s/ui-mark--evidence/ui-mark--accent/g ; s/ui-bracket-note--evidence/ui-bracket-note--accent/g
+```
+
+## 3. Annotation arrowheads share the connectors geometry kernel
+
+No API change — `connectorEndArrow` and the annotation arrowhead recipes keep
+their signatures. Only the **rendered arrowhead path** differs slightly now that
+it reuses the shared `@ponchia/ui/connectors` geometry kernel.
+
+**Migration:** nothing to change in code. If you keep exact-path SVG snapshot
+tests of annotation arrowheads, **re-baseline** them.
+
+## What's new (all opt-in, nothing to change)
+
+- **Analytical suite** — `@ponchia/ui/css/analytical.css` rolls up annotations,
+  legend, marks, connectors, spotlight, crosshair and selection. Each owns only
+  its visual grammar + pure geometry (no chart engine, no state, no hit-testing).
+- **App-tier leaves** — `css/sources.css` (citation/provenance trust),
+  `css/state.css` (lifecycle/system state), `css/generated.css` (AI-trust),
+  `css/workbench.css` (inspector/property/selection bar), and `css/command.css`
+  + `initCommand` (a filter/keyboard command palette).
+- **`.ui-shortcut`** — a keyboard-hint chord/sequence primitive in the core layer.
+
+## Re-pin
+
+```jsonc
+// package.json — 0.5 is a breaking minor under the pre-1.0 policy
+"@ponchia/ui": "~0.5.0"
+```

package/docs/migrations/0.5-to-0.6.md

@@ -0,0 +1,82 @@
+# Migrating 0.5 -> 0.6
+
+0.6.0 is the **charting realignment** release. The analytical layer still
+explains figures, but it no longer pretends CSS can be a chart renderer:
+scales, domains, axes and data binding belong to a chart engine.
+
+There is one breaking change. The data-viz palette (`--chart-*`,
+`tokens/charts.json`) and the standalone Legends layer are unchanged. The
+machine-readable map is [`MIGRATIONS.json`](../../MIGRATIONS.json).
+
+## 1. Replace the removed `.ui-chart*` renderer
+
+The static bar-chart classes were removed:
+
+```text
+ui-chart
+ui-chart__plot
+ui-chart__bar
+ui-chart__label
+ui-chart__track
+ui-chart__fill
+ui-chart__fallback
+ui-chart__caption
+```
+
+There is no safe class rename. Find call sites first:
+
+```bash
+rg -n 'ui-chart\b|ui-chart__' .
+```
+
+For live or data-driven charts, migrate to Vega-Lite and apply the Bronto
+theme config:
+
+```js
+import { brontoVegaConfig } from '@ponchia/ui/vega';
+
+vegaEmbed('#chart', spec, {
+  config: brontoVegaConfig(document.documentElement.dataset.theme || 'light'),
+  renderer: 'svg',
+  actions: false,
+});
+```
+
+Wrap the rendered chart in report chrome and keep the data key in the
+standalone legend layer:
+
+```html
+<figure class="ui-report__figure">
+  <div id="chart"></div>
+  <figcaption class="ui-report__caption">Latency by region.</figcaption>
+  <ul class="ui-legend">
+    <li class="ui-legend__item">
+      <span class="ui-legend__swatch ui-legend__swatch--1"></span>
+      <span class="ui-legend__label">EU West</span>
+    </li>
+  </ul>
+</figure>
+```
+
+For frozen print charts with no runtime, hand-author an inline `<svg>` using the
+resolved `--chart-*` palette or `tokens/charts.json`.
+
+## 2. Remove `--chart-value`
+
+The old renderer's per-bar `--chart-value` knob is gone with the renderer.
+Keep using `--chart-color` and `--chart-pattern` on `.ui-legend__swatch`; those
+belong to the unchanged Legends layer.
+
+## 3. Import the new chart theme helper only when needed
+
+`@ponchia/ui/vega` and `vega.json` are config/data only. Vega, Vega-Lite and
+vega-embed remain consumer dependencies; Bronto does not bundle a chart engine.
+See [`docs/vega.md`](../vega.md) for the browser, CDN and static-report
+recipes.
+
+## Re-pin
+
+```jsonc
+// package.json — 0.6 is a breaking minor under the pre-1.0 policy
+"@ponchia/ui": "~0.6.0"
+```

package/docs/package-contract.md

@@ -27,6 +27,8 @@ semantic versioning contract for the surfaces listed here.
 | --- | --- | --- | --- | --- |
 | `.` | style: `./dist/bronto.css`<br>default: `./dist/bronto.css` | CSS root bundle | Stable | CSS-only package root. Supported as a CSS side-effect import in CSS-aware bundlers; not a Node/runtime JS entrypoint. |
 | `./dist/bronto.css` | `./dist/bronto.css` | Flattened CSS bundle | Stable path | The prebuilt default stylesheet. Generated from css/core.css and byte-checked by check:dist. |
+| `./tailwind` | `./tailwind.css` | Tailwind CSS bridge | Stable additive | CSS-only Tailwind v4 theme/variant bridge. It maps Bronto tokens into Tailwind namespaces; it does not import component CSS. |
+| `./tailwind.css` | `./tailwind.css` | Tailwind CSS bridge | Stable additive | CSS-only Tailwind v4 theme/variant bridge. It maps Bronto tokens into Tailwind namespaces; it does not import component CSS. |
 | `./css` | `./css/core.css` | CSS source fan-out | Stable path | Bundler entrypoint for css/core.css. It preserves source @import boundaries and layer behavior. |
 | `./css/core.css` | `./css/core.css` | CSS source fan-out | Stable path | Source fan-out file for consumers that want the authored leaf graph through a bundler. |
 | `./css/tokens.css` | `./dist/css/tokens.css` | Bundled layered CSS leaf | Stable additive | Generated layered direct-import leaf. Also included in dist/bronto.css. |
@@ -47,6 +49,7 @@ semantic versioning contract for the surfaces listed here.
 | `./css/skins.css` | `./dist/css/skins.css` | Opt-in layered CSS leaf | Stable additive | Generated layered direct-import leaf. Opt-in and not included in dist/bronto.css. |
 | `./css/dataviz.css` | `./dist/css/dataviz.css` | Opt-in layered CSS leaf | Stable additive | Generated layered direct-import leaf. Opt-in and not included in dist/bronto.css. |
 | `./css/report.css` | `./dist/css/report.css` | Opt-in layered CSS leaf | Stable additive | Generated layered direct-import leaf. Opt-in and not included in dist/bronto.css. |
+| `./css/figure.css` | `./dist/css/figure.css` | Opt-in layered CSS leaf | Stable additive | Generated layered direct-import leaf. Opt-in and not included in dist/bronto.css. |
 | `./css/annotations.css` | `./dist/css/annotations.css` | Opt-in layered CSS leaf | Stable additive | Generated layered direct-import leaf. Opt-in and not included in dist/bronto.css. |
 | `./css/legend.css` | `./dist/css/legend.css` | Opt-in layered CSS leaf | Stable additive | Generated layered direct-import leaf. Opt-in and not included in dist/bronto.css. |
 | `./css/marks.css` | `./dist/css/marks.css` | Opt-in layered CSS leaf | Stable additive | Generated layered direct-import leaf. Opt-in and not included in dist/bronto.css. |
@@ -55,6 +58,9 @@ semantic versioning contract for the surfaces listed here.
 | `./css/crosshair.css` | `./dist/css/crosshair.css` | Opt-in layered CSS leaf | Stable additive | Generated layered direct-import leaf. Opt-in and not included in dist/bronto.css. |
 | `./css/selection.css` | `./dist/css/selection.css` | Opt-in layered CSS leaf | Stable additive | Generated layered direct-import leaf. Opt-in and not included in dist/bronto.css. |
 | `./css/sources.css` | `./dist/css/sources.css` | Opt-in layered CSS leaf | Stable additive | Generated layered direct-import leaf. Opt-in and not included in dist/bronto.css. |
+| `./css/interval.css` | `./dist/css/interval.css` | Opt-in layered CSS leaf | Stable additive | Generated layered direct-import leaf. Opt-in and not included in dist/bronto.css. |
+| `./css/clamp.css` | `./dist/css/clamp.css` | Opt-in layered CSS leaf | Stable additive | Generated layered direct-import leaf. Opt-in and not included in dist/bronto.css. |
+| `./css/highlights.css` | `./dist/css/highlights.css` | Opt-in layered CSS leaf | Stable additive | Generated layered direct-import leaf. Opt-in and not included in dist/bronto.css. |
 | `./css/diff.css` | `./dist/css/diff.css` | Opt-in layered CSS leaf | Stable additive | Generated layered direct-import leaf. Opt-in and not included in dist/bronto.css. |
 | `./css/code.css` | `./dist/css/code.css` | Opt-in layered CSS leaf | Stable additive | Generated layered direct-import leaf. Opt-in and not included in dist/bronto.css. |
 | `./css/spark.css` | `./dist/css/spark.css` | Opt-in layered CSS leaf | Stable additive | Generated layered direct-import leaf. Opt-in and not included in dist/bronto.css. |
@@ -69,6 +75,7 @@ semantic versioning contract for the surfaces listed here.
 | `./css/workbench.css` | `./dist/css/workbench.css` | Opt-in layered CSS leaf | Stable additive | Generated layered direct-import leaf. Opt-in and not included in dist/bronto.css. |
 | `./css/command.css` | `./dist/css/command.css` | Opt-in layered CSS leaf | Stable additive | Generated layered direct-import leaf. Opt-in and not included in dist/bronto.css. |
 | `./css/analytical.css` | `./dist/css/analytical.css` | Opt-in CSS roll-up | Stable additive | Generated layered roll-up of the analytical leaves. Not included in the default bundle. |
+| `./css/report-kit.css` | `./dist/css/report-kit.css` | Opt-in CSS roll-up | Stable additive | Generated layered roll-up for complete static reports. Not included in the default bundle. |
 | `./css/unlayered/tokens.css` | `./css/tokens.css` | Unlayered CSS leaf | Stable path | Raw authored CSS leaf for consumers that deliberately opt out of @layer bronto on that leaf. |
 | `./css/unlayered/fonts.css` | `./css/fonts.css` | Unlayered CSS leaf | Stable path | Raw authored CSS leaf for consumers that deliberately opt out of @layer bronto on that leaf. |
 | `./css/unlayered/base.css` | `./css/base.css` | Unlayered CSS leaf | Stable path | Raw authored CSS leaf for consumers that deliberately opt out of @layer bronto on that leaf. |
@@ -87,6 +94,7 @@ semantic versioning contract for the surfaces listed here.
 | `./css/unlayered/skins.css` | `./css/skins.css` | Unlayered CSS leaf | Stable path | Raw authored CSS leaf for consumers that deliberately opt out of @layer bronto on that leaf. |
 | `./css/unlayered/dataviz.css` | `./css/dataviz.css` | Unlayered CSS leaf | Stable path | Raw authored CSS leaf for consumers that deliberately opt out of @layer bronto on that leaf. |
 | `./css/unlayered/report.css` | `./css/report.css` | Unlayered CSS leaf | Stable path | Raw authored CSS leaf for consumers that deliberately opt out of @layer bronto on that leaf. |
+| `./css/unlayered/figure.css` | `./css/figure.css` | Unlayered CSS leaf | Stable path | Raw authored CSS leaf for consumers that deliberately opt out of @layer bronto on that leaf. |
 | `./css/unlayered/annotations.css` | `./css/annotations.css` | Unlayered CSS leaf | Stable path | Raw authored CSS leaf for consumers that deliberately opt out of @layer bronto on that leaf. |
 | `./css/unlayered/legend.css` | `./css/legend.css` | Unlayered CSS leaf | Stable path | Raw authored CSS leaf for consumers that deliberately opt out of @layer bronto on that leaf. |
 | `./css/unlayered/marks.css` | `./css/marks.css` | Unlayered CSS leaf | Stable path | Raw authored CSS leaf for consumers that deliberately opt out of @layer bronto on that leaf. |
@@ -95,6 +103,9 @@ semantic versioning contract for the surfaces listed here.
 | `./css/unlayered/crosshair.css` | `./css/crosshair.css` | Unlayered CSS leaf | Stable path | Raw authored CSS leaf for consumers that deliberately opt out of @layer bronto on that leaf. |
 | `./css/unlayered/selection.css` | `./css/selection.css` | Unlayered CSS leaf | Stable path | Raw authored CSS leaf for consumers that deliberately opt out of @layer bronto on that leaf. |
 | `./css/unlayered/sources.css` | `./css/sources.css` | Unlayered CSS leaf | Stable path | Raw authored CSS leaf for consumers that deliberately opt out of @layer bronto on that leaf. |
+| `./css/unlayered/interval.css` | `./css/interval.css` | Unlayered CSS leaf | Stable path | Raw authored CSS leaf for consumers that deliberately opt out of @layer bronto on that leaf. |
+| `./css/unlayered/clamp.css` | `./css/clamp.css` | Unlayered CSS leaf | Stable path | Raw authored CSS leaf for consumers that deliberately opt out of @layer bronto on that leaf. |
+| `./css/unlayered/highlights.css` | `./css/highlights.css` | Unlayered CSS leaf | Stable path | Raw authored CSS leaf for consumers that deliberately opt out of @layer bronto on that leaf. |
 | `./css/unlayered/diff.css` | `./css/diff.css` | Unlayered CSS leaf | Stable path | Raw authored CSS leaf for consumers that deliberately opt out of @layer bronto on that leaf. |
 | `./css/unlayered/code.css` | `./css/code.css` | Unlayered CSS leaf | Stable path | Raw authored CSS leaf for consumers that deliberately opt out of @layer bronto on that leaf. |
 | `./css/unlayered/spark.css` | `./css/spark.css` | Unlayered CSS leaf | Stable path | Raw authored CSS leaf for consumers that deliberately opt out of @layer bronto on that leaf. |
@@ -113,8 +124,11 @@ semantic versioning contract for the surfaces listed here.
 | `./tokens.json` | `./tokens/index.json` | Machine-readable data | Stable additive | JSON package data for non-JS/tooling consumers. Shape is public unless the paired doc marks a field internal. |
 | `./tokens.dtcg.json` | `./tokens/tokens.dtcg.json` | Machine-readable data | Stable additive | JSON package data for non-JS/tooling consumers. Shape is public unless the paired doc marks a field internal. |
 | `./tokens/resolved.json` | `./tokens/resolved.json` | Machine-readable data | Stable additive | JSON package data for non-JS/tooling consumers. Shape is public unless the paired doc marks a field internal. |
+| `./tokens/figma.variables.json` | `./tokens/figma.variables.json` | Machine-readable data | Stable additive | JSON package data for non-JS/tooling consumers. Shape is public unless the paired doc marks a field internal. |
 | `./shiki/nothing.json` | `./shiki/nothing.json` | Machine-readable data | Stable additive | JSON package data for non-JS/tooling consumers. Shape is public unless the paired doc marks a field internal. |
 | `./llms.txt` | `./llms.txt` | Agent entrypoint | Stable path | Plain-text orientation file shipped for offline agents and tooling. |
+| `./MIGRATIONS.json` | `./MIGRATIONS.json` | Machine-readable data | Stable additive | JSON package data for non-JS/tooling consumers. Shape is public unless the paired doc marks a field internal. |
+| `./schemas/report-claims.v1.schema.json` | `./schemas/report-claims.v1.schema.json` | Machine-readable data | Stable additive | JSON package data for non-JS/tooling consumers. Shape is public unless the paired doc marks a field internal. |
 | `./docs/architecture.md` | `./docs/architecture.md` | Shipped documentation | Stable path | Markdown documentation shipped in the tarball. Paths are public reading assets within a compatible minor. |
 | `./docs/reference.md` | `./docs/reference.md` | Shipped documentation | Stable path | Markdown documentation shipped in the tarball. Paths are public reading assets within a compatible minor. |
 | `./docs/theming.md` | `./docs/theming.md` | Shipped documentation | Stable path | Markdown documentation shipped in the tarball. Paths are public reading assets within a compatible minor. |
@@ -129,6 +143,7 @@ semantic versioning contract for the surfaces listed here.
 | `./docs/mermaid.md` | `./docs/mermaid.md` | Shipped documentation | Stable path | Markdown documentation shipped in the tarball. Paths are public reading assets within a compatible minor. |
 | `./docs/d2.md` | `./docs/d2.md` | Shipped documentation | Stable path | Markdown documentation shipped in the tarball. Paths are public reading assets within a compatible minor. |
 | `./docs/vega.md` | `./docs/vega.md` | Shipped documentation | Stable path | Markdown documentation shipped in the tarball. Paths are public reading assets within a compatible minor. |
+| `./docs/figure.md` | `./docs/figure.md` | Shipped documentation | Stable path | Markdown documentation shipped in the tarball. Paths are public reading assets within a compatible minor. |
 | `./docs/annotations.md` | `./docs/annotations.md` | Shipped documentation | Stable path | Markdown documentation shipped in the tarball. Paths are public reading assets within a compatible minor. |
 | `./docs/legends.md` | `./docs/legends.md` | Shipped documentation | Stable path | Markdown documentation shipped in the tarball. Paths are public reading assets within a compatible minor. |
 | `./docs/marks.md` | `./docs/marks.md` | Shipped documentation | Stable path | Markdown documentation shipped in the tarball. Paths are public reading assets within a compatible minor. |
@@ -137,6 +152,9 @@ semantic versioning contract for the surfaces listed here.
 | `./docs/crosshair.md` | `./docs/crosshair.md` | Shipped documentation | Stable path | Markdown documentation shipped in the tarball. Paths are public reading assets within a compatible minor. |
 | `./docs/selection.md` | `./docs/selection.md` | Shipped documentation | Stable path | Markdown documentation shipped in the tarball. Paths are public reading assets within a compatible minor. |
 | `./docs/sources.md` | `./docs/sources.md` | Shipped documentation | Stable path | Markdown documentation shipped in the tarball. Paths are public reading assets within a compatible minor. |
+| `./docs/interval.md` | `./docs/interval.md` | Shipped documentation | Stable path | Markdown documentation shipped in the tarball. Paths are public reading assets within a compatible minor. |
+| `./docs/clamp.md` | `./docs/clamp.md` | Shipped documentation | Stable path | Markdown documentation shipped in the tarball. Paths are public reading assets within a compatible minor. |
+| `./docs/highlights.md` | `./docs/highlights.md` | Shipped documentation | Stable path | Markdown documentation shipped in the tarball. Paths are public reading assets within a compatible minor. |
 | `./docs/diff.md` | `./docs/diff.md` | Shipped documentation | Stable path | Markdown documentation shipped in the tarball. Paths are public reading assets within a compatible minor. |
 | `./docs/code.md` | `./docs/code.md` | Shipped documentation | Stable path | Markdown documentation shipped in the tarball. Paths are public reading assets within a compatible minor. |
 | `./docs/spark.md` | `./docs/spark.md` | Shipped documentation | Stable path | Markdown documentation shipped in the tarball. Paths are public reading assets within a compatible minor. |
@@ -150,6 +168,11 @@ semantic versioning contract for the surfaces listed here.
 | `./docs/generated.md` | `./docs/generated.md` | Shipped documentation | Stable path | Markdown documentation shipped in the tarball. Paths are public reading assets within a compatible minor. |
 | `./docs/workbench.md` | `./docs/workbench.md` | Shipped documentation | Stable path | Markdown documentation shipped in the tarball. Paths are public reading assets within a compatible minor. |
 | `./docs/command.md` | `./docs/command.md` | Shipped documentation | Stable path | Markdown documentation shipped in the tarball. Paths are public reading assets within a compatible minor. |
+| `./docs/interop/tailwind.md` | `./docs/interop/tailwind.md` | Shipped documentation | Stable path | Markdown documentation shipped in the tarball. Paths are public reading assets within a compatible minor. |
+| `./docs/migrations/0.2-to-0.3.md` | `./docs/migrations/0.2-to-0.3.md` | Shipped documentation | Stable path | Markdown documentation shipped in the tarball. Paths are public reading assets within a compatible minor. |
+| `./docs/migrations/0.3-to-0.4.md` | `./docs/migrations/0.3-to-0.4.md` | Shipped documentation | Stable path | Markdown documentation shipped in the tarball. Paths are public reading assets within a compatible minor. |
+| `./docs/migrations/0.4-to-0.5.md` | `./docs/migrations/0.4-to-0.5.md` | Shipped documentation | Stable path | Markdown documentation shipped in the tarball. Paths are public reading assets within a compatible minor. |
+| `./docs/migrations/0.5-to-0.6.md` | `./docs/migrations/0.5-to-0.6.md` | Shipped documentation | Stable path | Markdown documentation shipped in the tarball. Paths are public reading assets within a compatible minor. |
 | `./docs/adr/0001-color-system.md` | `./docs/adr/0001-color-system.md` | Shipped documentation | Stable path | Markdown documentation shipped in the tarball. Paths are public reading assets within a compatible minor. |
 | `./docs/adr/0002-scope-and-2026-baseline.md` | `./docs/adr/0002-scope-and-2026-baseline.md` | Shipped documentation | Stable path | Markdown documentation shipped in the tarball. Paths are public reading assets within a compatible minor. |
 | `./docs/adr/0003-theme-model.md` | `./docs/adr/0003-theme-model.md` | Shipped documentation | Stable path | Markdown documentation shipped in the tarball. Paths are public reading assets within a compatible minor. |
@@ -162,6 +185,8 @@ semantic versioning contract for the surfaces listed here.
 | `./react` | types: `./react/index.d.ts`<br>default: `./react/index.js` | Framework binding JS | Stable thin adapter | Optional peer wrapper over vanilla behaviors. It owns lifecycle hookup, not markup or component state. |
 | `./solid` | types: `./solid/index.d.ts`<br>default: `./solid/index.js` | Framework binding JS | Stable thin adapter | Optional peer wrapper over vanilla behaviors. It owns lifecycle hookup, not markup or component state. |
 | `./qwik` | types: `./qwik/index.d.ts`<br>default: `./qwik/index.js` | Framework binding JS | Stable thin adapter | Optional peer wrapper over vanilla behaviors. It owns lifecycle hookup, not markup or component state. |
+| `./svelte` | types: `./svelte/index.d.ts`<br>default: `./svelte/index.js` | Framework binding JS | Stable thin adapter | Optional peer wrapper over vanilla behaviors. It owns lifecycle hookup, not markup or component state. |
+| `./vue` | types: `./vue/index.d.ts`<br>default: `./vue/index.js` | Framework binding JS | Stable thin adapter | Optional peer wrapper over vanilla behaviors. It owns lifecycle hookup, not markup or component state. |
 | `./skins` | types: `./tokens/skins.d.ts`<br>default: `./tokens/skins.js` | Renderer/theme helper JS | Stable additive | ESM theme data/helpers for opt-in skins, chart palettes, and external renderers. |
 | `./charts` | types: `./tokens/charts.d.ts`<br>default: `./tokens/charts.js` | Renderer/theme helper JS | Stable additive | ESM theme data/helpers for opt-in skins, chart palettes, and external renderers. |
 | `./charts.json` | `./tokens/charts.json` | Machine-readable data | Stable additive | JSON package data for non-JS/tooling consumers. Shape is public unless the paired doc marks a field internal. |
@@ -183,16 +208,20 @@ always includes `package.json`, `README.md`, `LICENSE`, and
 | --- | --- | --- |
 | `css` | Source CSS directory | Public source leaves. Mostly hand-authored; generated exceptions are called out in the provenance table. |
 | `dist` | Generated CSS directory | Prebuilt layered bundle and leaves. Never hand-edit. |
+| `tailwind.css` | Tailwind CSS bridge | CSS-only Tailwind v4 theme/variant bridge; hand-authored and not part of the default Bronto bundle. |
 | `fonts` | Vendored assets | Doto woff2 files plus OFL license. |
 | `tokens` | Mixed source/generated data | Token source plus generated JSON, declarations, and renderer theme data. |
 | `classes` | Mixed source/generated data | Class recipe source plus generated JSON/declarations/custom-data. |
 | `behaviors` | Authored public JS directory | ESM source shipped as-is; adjacent declarations/maps are generated. |
 | `glyphs` | Authored public JS directory | Glyph registry/renderers shipped as JS; declarations are generated. |
+| `schemas` | Machine-readable schemas | Declarative JSON schemas for package-adjacent report/tooling contracts. |
 | `annotations` | Authored public JS directory | ESM source shipped as-is; adjacent declarations/maps are generated. |
 | `connectors` | Authored public JS directory | ESM source shipped as-is; adjacent declarations/maps are generated. |
 | `react` | Authored public JS directory | ESM source shipped as-is; adjacent declarations/maps are generated. |
 | `solid` | Authored public JS directory | ESM source shipped as-is; adjacent declarations/maps are generated. |
 | `qwik` | Authored public JS directory | ESM source shipped as-is; adjacent declarations/maps are generated. |
+| `svelte` | Authored public JS directory | ESM source shipped as-is; adjacent declarations/maps are generated. |
+| `vue` | Authored public JS directory | ESM source shipped as-is; adjacent declarations/maps are generated. |
 | `shiki` | Theme data | Shiki theme JSON on the governed palette. |
 | `llms.txt` | Agent entrypoint | Shipped plain-text orientation for offline LLM/agent consumers. |
 | `CHANGELOG.md` | Release record | Shipped historical release notes. |
@@ -211,6 +240,7 @@ always includes `package.json`, `README.md`, `LICENSE`, and
 | `docs/mermaid.md` | Shipped documentation | Curated Markdown reading asset shipped in the npm tarball. |
 | `docs/d2.md` | Shipped documentation | Curated Markdown reading asset shipped in the npm tarball. |
 | `docs/vega.md` | Shipped documentation | Curated Markdown reading asset shipped in the npm tarball. |
+| `docs/figure.md` | Shipped documentation | Curated Markdown reading asset shipped in the npm tarball. |
 | `docs/annotations.md` | Shipped documentation | Curated Markdown reading asset shipped in the npm tarball. |
 | `docs/legends.md` | Shipped documentation | Curated Markdown reading asset shipped in the npm tarball. |
 | `docs/marks.md` | Shipped documentation | Curated Markdown reading asset shipped in the npm tarball. |
@@ -219,6 +249,9 @@ always includes `package.json`, `README.md`, `LICENSE`, and
 | `docs/crosshair.md` | Shipped documentation | Curated Markdown reading asset shipped in the npm tarball. |
 | `docs/selection.md` | Shipped documentation | Curated Markdown reading asset shipped in the npm tarball. |
 | `docs/sources.md` | Shipped documentation | Curated Markdown reading asset shipped in the npm tarball. |
+| `docs/interval.md` | Shipped documentation | Curated Markdown reading asset shipped in the npm tarball. |
+| `docs/clamp.md` | Shipped documentation | Curated Markdown reading asset shipped in the npm tarball. |
+| `docs/highlights.md` | Shipped documentation | Curated Markdown reading asset shipped in the npm tarball. |
 | `docs/diff.md` | Shipped documentation | Curated Markdown reading asset shipped in the npm tarball. |
 | `docs/code.md` | Shipped documentation | Curated Markdown reading asset shipped in the npm tarball. |
 | `docs/spark.md` | Shipped documentation | Curated Markdown reading asset shipped in the npm tarball. |
@@ -232,6 +265,11 @@ always includes `package.json`, `README.md`, `LICENSE`, and
 | `docs/generated.md` | Shipped documentation | Curated Markdown reading asset shipped in the npm tarball. |
 | `docs/workbench.md` | Shipped documentation | Curated Markdown reading asset shipped in the npm tarball. |
 | `docs/command.md` | Shipped documentation | Curated Markdown reading asset shipped in the npm tarball. |
+| `docs/interop/tailwind.md` | Shipped documentation | Curated Markdown reading asset shipped in the npm tarball. |
+| `docs/migrations/0.2-to-0.3.md` | Shipped documentation | Curated Markdown reading asset shipped in the npm tarball. |
+| `docs/migrations/0.3-to-0.4.md` | Shipped documentation | Curated Markdown reading asset shipped in the npm tarball. |
+| `docs/migrations/0.4-to-0.5.md` | Shipped documentation | Curated Markdown reading asset shipped in the npm tarball. |
+| `docs/migrations/0.5-to-0.6.md` | Shipped documentation | Curated Markdown reading asset shipped in the npm tarball. |
 | `docs/adr/0001-color-system.md` | Shipped documentation | Curated Markdown reading asset shipped in the npm tarball. |
 | `docs/adr/0002-scope-and-2026-baseline.md` | Shipped documentation | Curated Markdown reading asset shipped in the npm tarball. |
 | `docs/adr/0003-theme-model.md` | Shipped documentation | Curated Markdown reading asset shipped in the npm tarball. |
@@ -244,15 +282,15 @@ result. The listed gates are part of `npm run check`.
 
 | Surface | Source of truth | Generated outputs | Generator | Gate | Note |
 | --- | --- | --- | --- | --- | --- |
-| Package manifest | `package.json` | docs/package-contract.md | `npm run package-contract:build` | check:fresh | The complete export/file matrix in this document is generated from the manifest. |
-| Token model | `tokens/index.js` | css/tokens.css; tokens/index.json; tokens/tokens.dtcg.json; tokens/resolved.json; tokens/index.d.ts | `npm run tokens:css:build; tokens:build; dtcg:build; resolved:build; dts:build` | check:fresh; check:contrast | Token names/roles are public. Resolved values are visual tuning before 1.0. |
+| Package manifest | `package.json` | docs/package-contract.md | `npm run package-contract:build` | check:fresh; check:exports; check:pack; check:consumer-surface; check:consumer-types; check:publint; check:attw | The complete export/file matrix in this document is generated from the manifest; packed tarball imports, concrete file resolution, and package-level type resolution are smoke-tested in clean consumers. |
+| Token model | `tokens/index.js` | css/tokens.css; tokens/index.json; tokens/tokens.dtcg.json; tokens/resolved.json; tokens/figma.variables.json; tokens/index.d.ts | `npm run tokens:css:build; tokens:build; dtcg:build; resolved:build; figma:variables:build; dts:build` | check:fresh; check:contrast | Token names/roles are public. Resolved and Figma handoff values are visual tuning before 1.0. |
 | Class registry | `classes/index.js plus css/*.css selectors` | classes/classes.json; classes/index.d.ts; classes/vscode.css-custom-data.json; docs/reference.md | `npm run classes:json:build; dts:build; vscode:build; reference:build` | check:fresh; check:classes; check:contract | The typed registry, JSON vocabulary, and generated reference stay aligned with real selectors. |
-| Authored CSS graph | `css/core.css plus css/*.css leaves` | dist/bronto.css; dist/css/*.css (40 layered outputs) | `npm run dist:build` | check:dist; check:exports | Default bundle and direct layered leaf imports are generated from authored CSS and size-gated. |
-| JSDoc-authored public JS | `behaviors/; annotations/; connectors/; react/; solid/; qwik/` | adjacent *.d.ts and *.d.ts.map files | `npm run dts:emit` | check:dts-emit; check:types; check:attw; check:publint | Declarations are emitted from the shipped JS, not separately maintained. |
-| Glyph registry | `glyphs/glyphs.js` | glyphs/glyphs.d.ts | `npm run glyphs:build` | check:glyphs; npm test | Glyph names and render options are public. The registry stays sorted and type-covered. |
+| Authored CSS graph | `css/core.css plus css/*.css leaves` | dist/bronto.css; dist/css/*.css (46 layered outputs) | `npm run dist:build` | check:dist; check:exports; check:component-matrix | Default bundle and direct layered leaf imports are generated from authored CSS, size-gated, and coverage-owned as foundation or component leaves. |
+| JSDoc-authored public JS | `behaviors/; annotations/; connectors/; react/; solid/; qwik/; svelte/; vue/` | adjacent *.d.ts and *.d.ts.map files | `npm run dts:emit` | check:dts-emit; check:types; check:consumer-surface; check:consumer-types; check:behavior-matrix; check:attw; check:publint | Declarations are emitted from the shipped JS, package subpath imports are compiled from a packed clean consumer, and public behavior exports are docs/unit/browser owned. |
+| Glyph registry | `glyphs/glyphs.js` | glyphs/glyphs.d.ts | `npm run glyphs:build` | check:glyphs; check:unit | Glyph names and render options are public. The registry stays sorted and type-covered. |
 | Display colorways | `tokens/skins.js` | css/skins.css; tokens/skins.d.ts | `npm run skins:build` | check:skins; check:contrast | Skins are opt-in root-level choices and never part of dist/bronto.css. |
 | Chart palette | `tokens/charts.js` | css/dataviz.css; tokens/charts.json; tokens/charts.d.ts | `npm run charts:build` | check:charts | Data-viz colors are opt-in, CVD-gated, and never UI chrome. |
-| External renderer themes | `tokens/mermaid.js; tokens/d2.js; tokens/vega.js` | tokens/{mermaid,d2,vega}.{js,json,d.ts} | `npm run mermaid:build; d2:build; vega:build` | check:mermaid; check:d2; check:vega | Renderer configs use resolved colors because the external renderers cannot consume CSS variables directly. |
+| External renderer themes | `tokens/mermaid.js; tokens/d2.js; tokens/vega.js` | tokens/{mermaid,d2,vega}.{js,json,d.ts} | `npm run mermaid:build; d2:build; vega:build` | check:mermaid; check:d2; check:vega; check:unit | Renderer configs use resolved colors because the external renderers cannot consume CSS variables directly; unit tests prove helper defaults and Vega render landing. |
 | Contrast report | `tokens/resolved.json; tokens/skins.js; tokens/charts.js` | docs/contrast.md | `npm run contrast:build` | check:contrast | WCAG floors are hard-gated; APCA is reported as advisory. |
 
 ## Internal Paths

package/docs/reference.md

@@ -9,7 +9,7 @@ rendering of every class is the kitchen-sink demo:
 **<https://ponchia.github.io/bronto-ui/>**. Theming knobs and the token
 contract: [docs/theming.md](theming.md).
 
-- 593 classes across 171 component groups
+- 634 classes across 177 component groups
 - Import the typed registry: `import { cls, ui, cx } from '@ponchia/ui/classes'`
 - Validate markup as data (no JS/TS): `@ponchia/ui/classes.json` — the same
   vocabulary as language-neutral JSON (`groups`, `classes`, `states`,
@@ -348,6 +348,17 @@ each one matches a real selector in the stylesheet.
 | `cls.claimUnknown` | `ui-claim--unknown` | modifier |
 | `cls.claimUnsupported` | `ui-claim--unsupported` | modifier |
 
+### `.ui-clamp`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.clamp` | `ui-clamp` | base |
+| `cls.clampBody` | `ui-clamp__body` | part |
+| `cls.clampControl` | `ui-clamp__control` | part |
+| `cls.clampLess` | `ui-clamp__less` | part |
+| `cls.clampMore` | `ui-clamp__more` | part |
+| `cls.clampToggle` | `ui-clamp__toggle` | part |
+
 ### `.ui-cluster`
 
 | Registry key | Class | Kind |
@@ -616,6 +627,20 @@ each one matches a real selector in the stylesheet.
 | --- | --- | --- |
 | `cls.field` | `ui-field` | base |
 
+### `.ui-figure`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.figure` | `ui-figure` | base |
+| `cls.figureBody` | `ui-figure__body` | part |
+| `cls.figureBodyKeyRight` | `ui-figure__body--key-right` | modifier |
+| `cls.figureCaption` | `ui-figure__caption` | part |
+| `cls.figureData` | `ui-figure__data` | part |
+| `cls.figureKey` | `ui-figure__key` | part |
+| `cls.figureMedia` | `ui-figure__media` | part |
+| `cls.figureOverlay` | `ui-figure__overlay` | part |
+| `cls.figureStage` | `ui-figure__stage` | part |
+
 ### `.ui-file`
 
 | Registry key | Class | Kind |
@@ -649,6 +674,12 @@ each one matches a real selector in the stylesheet.
 | --- | --- | --- |
 | `cls.halftone` | `ui-halftone` | base |
 
+### `.ui-highlights`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.highlights` | `ui-highlights` | base |
+
 ### `.ui-hint`
 
 | Registry key | Class | Kind |
@@ -691,6 +722,36 @@ each one matches a real selector in the stylesheet.
 | `cls.inspectorBody` | `ui-inspector__body` | part |
 | `cls.inspectorHead` | `ui-inspector__head` | part |
 
+### `.ui-interval`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.interval` | `ui-interval` | base |
+| `cls.intervalBounds` | `ui-interval__bounds` | part |
+| `cls.intervalLabel` | `ui-interval__label` | part |
+| `cls.intervalPoint` | `ui-interval__point` | part |
+| `cls.intervalRange` | `ui-interval__range` | part |
+| `cls.intervalTrack` | `ui-interval__track` | part |
+
+### `.ui-job`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.job` | `ui-job` | base |
+| `cls.jobActions` | `ui-job__actions` | part |
+| `cls.jobBar` | `ui-job__bar` | part |
+| `cls.jobBody` | `ui-job__body` | part |
+| `cls.jobHead` | `ui-job__head` | part |
+| `cls.jobMeta` | `ui-job__meta` | part |
+| `cls.jobProgress` | `ui-job__progress` | part |
+| `cls.jobTitle` | `ui-job__title` | part |
+| `cls.jobBlocked` | `ui-job--blocked` | modifier |
+| `cls.jobCompact` | `ui-job--compact` | modifier |
+| `cls.jobComplete` | `ui-job--complete` | modifier |
+| `cls.jobFailed` | `ui-job--failed` | modifier |
+| `cls.jobQueued` | `ui-job--queued` | modifier |
+| `cls.jobRunning` | `ui-job--running` | modifier |
+
 ### `.ui-kbd`
 
 | Registry key | Class | Kind |
@@ -1189,6 +1250,16 @@ each one matches a real selector in the stylesheet.
 | --- | --- | --- |
 | `cls.spinner` | `ui-spinner` | base |
 
+### `.ui-splitter`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.splitter` | `ui-splitter` | base |
+| `cls.splitterHandle` | `ui-splitter__handle` | part |
+| `cls.splitterPane` | `ui-splitter__pane` | part |
+| `cls.splitterHorizontal` | `ui-splitter--horizontal` | modifier |
+| `cls.splitterVertical` | `ui-splitter--vertical` | modifier |
+
 ### `.ui-spotlight`
 
 | Registry key | Class | Kind |
@@ -1517,9 +1588,11 @@ works in any framework without a binding layer:
   vocabulary onto a tone is application logic, not a framework class.
 - **Modal** — native `<dialog>` gets backdrop + top-layer + focus-trap
   free. For a controlled/portal modal, add `is-open`
-  (`ui.modal({ open: true })`) for the same skin/layout; the
-  backdrop, top-layer stacking AND focus-trap are then yours (`.is-open`
-  is a bare grid — it does not float or stack on its own).
+  (`ui.modal({ open: true })`) for the same skin/layout, mark the overlay
+  `data-bronto-modal`, and run `initModal()` for the inert focus trap,
+  focus-return, and Escape close signal. You still own the `is-open` state,
+  backdrop, and top-layer stacking (`.is-open` is a bare grid — it does not
+  float or stack on its own).
 - **Current page** — mark the active link with `aria-current="page"`; it is
   the programmatic cue the navs honour (`ui-sitenav`, `ui-app-nav`). The
   `.is-active` class is the visual-only equivalent on `ui-app-nav`/`ui-tab`;
@@ -1694,7 +1767,7 @@ Exact mirror of the `:root` blocks in `css/tokens.css`
 | `--text-dim` | `#a0a0a0` |
 | `--accent` | `#ff3b41` |
 | `--accent-ramp-end` | `#000000` |
-| `--accent-strong` | `color-mix(in srgb, var(--accent) 84%, #fff)` |
+| `--accent-strong` | `color-mix(in srgb, var(--accent) 80%, #fff)` |
 | `--accent-text` | `var(--accent-strong)` |
 | `--on-accent` | `var(--button-text)` |
 | `--accent-soft` | `color-mix(in srgb, var(--accent) 14%, transparent)` |