@ponchia/ui 0.6.12 → 0.8.0

package/docs/package-contract.md

@@ -174,9 +174,11 @@ semantic versioning contract for the surfaces listed here.
 | `./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/migrations/0.6-to-0.7.md` | `./docs/migrations/0.6-to-0.7.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. |
+| `./docs/adr/0004-prune-unused-adapters.md` | `./docs/adr/0004-prune-unused-adapters.md` | Shipped documentation | Stable path | Markdown documentation shipped in the tarball. Paths are public reading assets within a compatible minor. |
 | `./classes` | types: `./classes/index.d.ts`<br>default: `./classes/index.js` | Class recipes JS | Stable | ESM class registry, recipes, attrs helpers, and cx joiner. The emitted class vocabulary is public. |
 | `./classes.json` | `./classes/classes.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. |
 | `./behaviors` | types: `./behaviors/index.d.ts`<br>default: `./behaviors/index.js` | Vanilla behavior JS | Stable | ESM, SSR-safe, cleanup-returning behavior initializers. Behavior internals are not public. |
@@ -205,11 +207,11 @@ semantic versioning contract for the surfaces listed here.
 | `./glyphs` | types: `./glyphs/glyphs.d.ts`<br>default: `./glyphs/glyphs.js` | Geometry/render helper JS | Stable additive | ESM helper surface. Function names, options, and data shapes are public; rendering heuristics may tune. |
 | `./annotations` | types: `./annotations/index.d.ts`<br>default: `./annotations/index.js` | Geometry/render helper JS | Stable additive | ESM helper surface. Function names, options, and data shapes are public; rendering heuristics may tune. |
 | `./connectors` | types: `./connectors/index.d.ts`<br>default: `./connectors/index.js` | Geometry/render helper JS | Stable additive | ESM helper surface. Function names, options, and data shapes are public; rendering heuristics may tune. |
-| `./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. |
+| `./react` | types: `./react/index.d.ts`<br>default: `./react/index.js` | Framework binding JS | Deprecated in 0.7 | Compatibility wrapper over vanilla behaviors. Scheduled for removal no earlier than 0.8 under ADR-0004; use direct behavior lifecycle cleanup. |
+| `./solid` | types: `./solid/index.d.ts`<br>default: `./solid/index.js` | Framework binding JS | Deprecated in 0.7 | Compatibility wrapper over vanilla behaviors. Scheduled for removal no earlier than 0.8 under ADR-0004; use direct behavior lifecycle cleanup. |
+| `./qwik` | types: `./qwik/index.d.ts`<br>default: `./qwik/index.js` | Framework binding JS | Deprecated in 0.7 | Compatibility wrapper over vanilla behaviors. Scheduled for removal no earlier than 0.8 under ADR-0004; use direct behavior lifecycle cleanup. |
+| `./svelte` | types: `./svelte/index.d.ts`<br>default: `./svelte/index.js` | Framework binding JS | Deprecated in 0.7 | Compatibility wrapper over vanilla behaviors. Scheduled for removal no earlier than 0.8 under ADR-0004; use direct behavior lifecycle cleanup. |
+| `./vue` | types: `./vue/index.d.ts`<br>default: `./vue/index.js` | Framework binding JS | Deprecated in 0.7 | Compatibility wrapper over vanilla behaviors. Scheduled for removal no earlier than 0.8 under ADR-0004; use direct behavior lifecycle cleanup. |
 | `./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. |
@@ -236,6 +238,7 @@ always includes `package.json`, `README.md`, `LICENSE`, and
 | `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. |
+| `bin` | Package file | Included in the npm files allowlist. |
 | `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. |
@@ -295,9 +298,11 @@ always includes `package.json`, `README.md`, `LICENSE`, and
 | `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/migrations/0.6-to-0.7.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. |
+| `docs/adr/0004-prune-unused-adapters.md` | Shipped documentation | Curated Markdown reading asset shipped in the npm tarball. |
 
 ## Artifact Provenance
 

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).
 
-- 644 classes across 179 component groups
+- 669 classes across 183 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`,
@@ -268,7 +268,9 @@ each one matches a real selector in the stylesheet.
 | Registry key | Class | Kind |
 | --- | --- | --- |
 | `cls.button` | `ui-button` | base |
+| `cls.buttonLabel` | `ui-button__label` | part |
 | `cls.buttonDanger` | `ui-button--danger` | modifier |
+| `cls.buttonDense` | `ui-button--dense` | modifier |
 | `cls.buttonGhost` | `ui-button--ghost` | modifier |
 | `cls.buttonIcon` | `ui-button--icon` | modifier |
 | `cls.buttonLg` | `ui-button--lg` | modifier |
@@ -577,6 +579,10 @@ each one matches a real selector in the stylesheet.
 | Registry key | Class | Kind |
 | --- | --- | --- |
 | `cls.emptyState` | `ui-empty-state` | base |
+| `cls.emptyStateGlyph` | `ui-empty-state__glyph` | part |
+| `cls.emptyStateHint` | `ui-empty-state__hint` | part |
+| `cls.emptyStateLead` | `ui-empty-state__lead` | part |
+| `cls.emptyStateInvite` | `ui-empty-state--invite` | modifier |
 
 ### `.ui-error-summary`
 
@@ -952,6 +958,17 @@ each one matches a real selector in the stylesheet.
 | `cls.pagination` | `ui-pagination` | base |
 | `cls.paginationItem` | `ui-pagination__item` | part |
 
+### `.ui-pane`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.pane` | `ui-pane` | base |
+| `cls.paneActions` | `ui-pane__actions` | part |
+| `cls.paneBody` | `ui-pane__body` | part |
+| `cls.paneHead` | `ui-pane__head` | part |
+| `cls.paneTitle` | `ui-pane__title` | part |
+| `cls.paneTitleInput` | `ui-pane__title-input` | part |
+
 ### `.ui-panel`
 
 | Registry key | Class | Kind |
@@ -1160,6 +1177,29 @@ each one matches a real selector in the stylesheet.
 | `cls.selectionbar` | `ui-selectionbar` | base |
 | `cls.selectionbarActions` | `ui-selectionbar__actions` | part |
 | `cls.selectionbarCount` | `ui-selectionbar__count` | part |
+| `cls.selectionbarAnchorBlockEnd` | `ui-selectionbar--anchor-block-end` | modifier |
+| `cls.selectionbarAnchorBlockStart` | `ui-selectionbar--anchor-block-start` | modifier |
+| `cls.selectionbarAnchored` | `ui-selectionbar--anchored` | modifier |
+
+### `.ui-severity`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.severity` | `ui-severity` | base |
+
+### `.ui-severity-dot`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.severityDot` | `ui-severity-dot` | base |
+
+### `.ui-severity-row`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.severityRow` | `ui-severity-row` | base |
+| `cls.severityRowMeta` | `ui-severity-row__meta` | part |
+| `cls.severityRowTitle` | `ui-severity-row__title` | part |
 
 ### `.ui-shortcut`
 
@@ -1511,10 +1551,15 @@ each one matches a real selector in the stylesheet.
 | `cls.toolstripActions` | `ui-toolstrip__actions` | part |
 | `cls.toolstripBrand` | `ui-toolstrip__brand` | part |
 | `cls.toolstripContext` | `ui-toolstrip__context` | part |
+| `cls.toolstripFill` | `ui-toolstrip__fill` | part |
 | `cls.toolstripGroup` | `ui-toolstrip__group` | part |
 | `cls.toolstripSearch` | `ui-toolstrip__search` | part |
+| `cls.toolstripAnchorBlockEnd` | `ui-toolstrip--anchor-block-end` | modifier |
+| `cls.toolstripAnchorBlockStart` | `ui-toolstrip--anchor-block-start` | modifier |
+| `cls.toolstripAnchored` | `ui-toolstrip--anchored` | modifier |
 | `cls.toolstripCompact` | `ui-toolstrip--compact` | modifier |
 | `cls.toolstripFloating` | `ui-toolstrip--floating` | modifier |
+| `cls.toolstripPane` | `ui-toolstrip--pane` | modifier |
 
 ### `.ui-tooltip`
 
@@ -1672,6 +1717,12 @@ Exact mirror of the `:root` blocks in `css/tokens.css`
 | `--space-lg` | `1.35rem` |
 | `--space-xl` | `1.75rem` |
 | `--space-2xl` | `2.5rem` |
+| `--tap-target` | `max(44px, 2.9rem)` |
+| `--tap-target-min` | `max(24px, 1.6rem)` |
+| `--safe-area-top` | `env(safe-area-inset-top, 0px)` |
+| `--safe-area-right` | `env(safe-area-inset-right, 0px)` |
+| `--safe-area-bottom` | `env(safe-area-inset-bottom, 0px)` |
+| `--safe-area-left` | `env(safe-area-inset-left, 0px)` |
 | `--mono` | `'JetBrains Mono', 'Fira Code', 'Cascadia Code', 'SF Mono', ui-monospace, monospace` |
 | `--sans` | `'Inter', 'SF Pro Text', -apple-system, BlinkMacSystemFont, 'Segoe UI', system-ui, sans-serif` |
 | `--dot-font` | `'Doto', var(--mono)` |

package/docs/reporting.md

@@ -54,18 +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.12/dist/bronto.css" />
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.12/dist/css/report-kit.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.8.0/dist/bronto.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.8.0/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.12/dist/bronto.css" />
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.12/dist/css/report.css" />
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.12/dist/css/dataviz.css" />
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.12/dist/css/annotations.css" />
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.12/dist/css/legend.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.8.0/dist/bronto.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.8.0/dist/css/report.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.8.0/dist/css/dataviz.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.8.0/dist/css/annotations.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.8.0/dist/css/legend.css" />
 ```
 
 The CDN serves the package's own `fonts/` next to the CSS, so font URLs resolve
@@ -879,7 +879,7 @@ or validation runtime.
 
 ```json
 {
-  "$schema": "https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.12/schemas/report-claims.v1.schema.json",
+  "$schema": "https://cdn.jsdelivr.net/npm/@ponchia/ui@0.8.0/schemas/report-claims.v1.schema.json",
   "schemaVersion": "bronto-report-claims.v1",
   "report": { "title": "Decision readiness", "type": "decision" },
   "claims": [

package/docs/stability.md

@@ -1,7 +1,7 @@
 # Public API stability
 
 `@ponchia/ui` is pre-1.0. Breaking changes ship in the minor (`0.x.0`), and
-patches are non-breaking. In practical terms: **PATCH releases (`0.6.x`) are
+patches are non-breaking. In practical terms: **PATCH releases (`0.8.x`) are
 non-breaking bug-fixes and additive changes — safe to upgrade without review;
 MINOR releases (`0.x.0`) may include breaking changes and consumers should
 review the CHANGELOG before upgrading.** Pin `~0.x` (tilde) to accept only
@@ -53,7 +53,7 @@ enough.
 
 ### Adoption evidence for 1.0
 
-This snapshot records product evidence as of 2026-07-10. Use three evidence
+This snapshot records product evidence as of 2026-07-20. Use three evidence
 classes:
 
 - **Downstream-proven:** A non-example app, site, report generator, or tool
@@ -68,13 +68,41 @@ Package-proven is necessary but does not establish demand. During the catalog
 freeze, do not expand package-only surfaces. Recheck this table against real
 consumer upgrades before the 1.0 release candidate.
 
+> **The 0.8.0 consumer audit — read this before trusting the table below.** A
+> full-surface audit of the largest downstream consumer (a Yjs-collaborative
+> spatial canvas workspace: React, Vite, ~10k lines of its own CSS) found it
+> using **26 of the 646 published classes**, and hand-rebuilding much of the
+> rest — 10 bespoke empty states, 15 error surfaces, 17 control bars, three
+> parallel severity vocabularies, its own Markdown prose layer, its own diff
+> rows, its own meters, and two copies of visually-hidden text. Thirteen
+> primitives that map almost exactly onto what it built return **zero** uses:
+> `ui-state`, `ui-prose`, `ui-diff`, `ui-code`, `ui-meter`, `ui-progress`,
+> `ui-toolstrip`, `ui-dot`, `ui-chip`, `ui-tag`, `ui-timeline`, `ui-steps`,
+> `ui-job`.
+>
+> The lesson for this document is not about that consumer. It is that **"no
+> inspected consumer imports the surface" has been measuring discoverability,
+> not demand.** Those surfaces were not rejected; they were never found. The
+> opt-in leaf model is right, but nothing tells a consumer which leaf it is
+> about to reimplement — and `bronto-ui-check`, which catches part of it, was
+> installed in that consumer and had never been run. Before any 1.0 decision
+> retires a package-proven surface for lack of adoption, confirm the surface was
+> *reachable*: named in the consumer's imports, or at least in a leaf it
+> imports. Non-adoption of an unimported leaf is not evidence.
+>
+> The same audit produced this release's four consumer-driven changes (the tap
+> target floor, the safe-area tokens, `ui-button__label`, and the dense tier)
+> and the ADR-0001 canvas amendment. That is the intended loop: the consumer's
+> local classes are the backlog, resolving either to a deletion there or an
+> addition here.
+
 | Surface family | Current evidence | 1.0 disposition |
 | --- | --- | --- |
 | Core CSS, class recipes, vanilla behaviors, tokens, and Tailwind bridge | Downstream-proven across five inspected non-example app, site, and service consumers. | Stabilize names and behavior contracts. Use consumer upgrades as the release-candidate proof. |
 | Report, provenance, analytical CSS, annotations, glyphs, skins, workbench CSS, chart data, and Vega theme | Downstream-proven across four inspected report, site, dashboard, and tool consumers. | Keep opt-in. Stabilize the consumed paths; do not broaden the catalog during the freeze. |
-| Controlled non-`<dialog>` modal | Package-proven by stack, portal, late-node, focus, and cleanup regressions. No inspected non-example consumer initializes `initModal`. | Keep compatible through 0.6.x, but require a real consumer before declaring this alternative to native `<dialog>` stable in 1.0. |
-| React, Solid, Qwik, Svelte, and Vue lifecycle adapters | Package-proven by packed examples, types, and lifecycle tests. No inspected non-example consumer imports an adapter entrypoint. | Pre-1.0 candidate only. Freeze the adapter set and require downstream adoption before declaring all five stable in 1.0. |
-| Mermaid, D2, Shiki, Figma Variables, and the report-claims schema | Package-proven by generated-data, render, schema, and drift checks. No inspected non-example consumer currently supplies downstream proof for every path. | Keep compatible through 0.6.x, but decide each 1.0 contract from adoption evidence rather than generator coverage alone. |
+| Controlled non-`<dialog>` modal | Package-proven by stack, portal, late-node, focus, and cleanup regressions. None of ten inspected non-example consumers initializes `initModal`. | Deprecated in 0.7; remove no earlier than 0.8 unless a real consumer adopts it. Native `<dialog>` + `initDialog` is the stable path. |
+| React, Solid, Qwik, Svelte, and Vue lifecycle adapters | Package-proven by packed examples, types, and lifecycle tests. None of ten inspected non-example consumers imports an adapter entrypoint. | Deprecated in 0.7; remove no earlier than 0.8 unless a real consumer adopts one. Vanilla behaviors remain stable. |
+| Mermaid, D2, Shiki, Figma Variables, and the report-claims schema | Package-proven by generated-data, render, schema, and drift checks. No inspected non-example consumer currently supplies downstream proof for every path. | Keep compatible through 0.8.x, but decide each 1.0 contract from adoption evidence rather than generator coverage alone. |
 
 After 1.0, breaking changes move to majors. Until then, the table below is the
 current public-surface matrix and the release policy above still applies.
@@ -85,18 +113,20 @@ current public-surface matrix and the release policy above still applies.
 | JS module format | Stable | JS subpaths are ESM-only. CommonJS consumers use dynamic `import()`. |
 | CSS class names (`.ui-*`) | Stable | Names and documented modifier semantics are public. Internal selector structure and leaf-file boundaries may change. |
 | Class recipes (`@ponchia/ui/classes`) | Stable | Exported `cls`, `ui`, `cx`, `attrs`, recipe names, ARIA attribute helper names, and option unions are public. |
+| Severity ladder (`SEVERITY_LEVELS`, `severity()`, `.ui-severity*`) | Stable additive | The tier names and **their order** are public: `critical` › `error` › `warning` › `notice` › `ok`, with `unknown` deliberately outside the ordering as the fallback for "not measured". `severity()` returns `{ class, 'data-level' }`, and `data-level` is the public attribute contract — a host may carry it on its own element and read `var(--severity-tone)`. New tiers would be a breaking reorder, not an addition, so the ladder is closed; new *parts* (`chip`/`dot`/`row`) are additive. Ships in the opt-in `css/state.css`, not the default bundle. |
 | Class vocabulary as data (`@ponchia/ui/classes.json`, `@ponchia/ui/vscode.css-custom-data.json`) | Stable additive | The JSON shape (`groups`/`classes`/`states`/`customProperties`) and class/custom-property entries are public — for validating markup from a non-JS/non-TS host or editor integration. Generated from `cls` and CSS selectors; `classes.json`, `.d.ts`, reference docs, and VS Code custom data are drift-checked together. New classes/hooks are additive. |
 | Design tokens | Stable names/roles | Token names and documented roles are public. Exact values and generated colour math outputs may change for visual tuning before 1.0. |
 | `--accent-1..6` | Stable names/roles | A subtle-to-bold accent ramp derived from `--accent`. Exact resolved values are visual tuning; algorithm changes require release-note visibility and resolver/browser checks. |
-| Tokens as data (`tokens.json`, `tokens.dtcg.json`, `tokens/resolved.json`, `tokens/figma.variables.json`) | Stable additive | The JSON shapes are public for non-CSS/non-JS consumers and handoff tooling. `resolved.json` exposes `light`/`dark` (resolved colours) and `scale` (resolved non-colour scales). `tokens/figma.variables.json` mirrors the token contract for local Figma Variables import/sync. Token names/roles are stable; exact resolved values are visual tuning (pin `~0.x`). |
+| Tokens as data (`tokens.json`, `tokens.dtcg.json`, `tokens/resolved.json`, `tokens/figma.variables.json`) | Stable additive from 0.7 | The JSON shapes are public for non-CSS/non-JS consumers and handoff tooling. `tokens.dtcg.json` is a DTCG 2025.10 resolved projection with structured typed values; `tokens.json` preserves authored CSS expressions. `resolved.json` exposes flat `light`/`dark` colours and non-colour `scale`; `figma.variables.json` is the local Figma handoff. Token names/roles are stable; exact resolved values are visual tuning (pin `~0.x`). |
 | Schemas (`schemas/*.schema.json`, `schemas/report-claims.v1.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. |
 | Tailwind v4 bridge (`@ponchia/ui/tailwind`, `@ponchia/ui/tailwind.css`) | Stable additive | CSS-only token/variant bridge for Tailwind v4. It maps Bronto tokens and variants into Tailwind namespaces; it must not import Bronto component CSS or change the default bundle. |
 | 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. |
+| Consumer checker (`bronto-ui-check`) | Stable additive | The installed binary lexically validates literal `ui-*` classes and unresolved reserved-token references in supported code, style, and template sources after stripping comments; Markdown prose and generated/vendor directories are excluded. Exit 0 means no findings, exit 1 means contract findings, and exit 2 means invocation/input failure. New checks may be additive; an existing valid literal cannot become an error within a patch unless the corresponding public contract was already invalid. |
 | 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. |
-| 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. |
+| Framework lifecycle adapters (`react`/`solid`/`qwik`/`svelte`/`vue`) | Deprecated in 0.7 | Hook/action/directive names, optional peer behavior, root resolver support, and cleanup remain compatible through 0.7. Scheduled for removal no earlier than 0.8 under ADR-0004. Use vanilla behaviors in framework lifecycle code. |
 | Skins (`@ponchia/ui/skins`, `css/skins.css`) | Stable additive | Existing skin names stay valid. New skins are additive. Skins are root-level choices. Skin CSS is opt-in, not in the default bundle. |
 | Charts (`@ponchia/ui/charts`, `charts.json`, `css/dataviz.css`) | Stable additive | Token names, JSON shape, and 8 categorical slots are public. `css/dataviz.css` is opt-in, not in the default bundle. Exact palette values may tune if gates and release notes justify it. |
 | External renderer themes (`@ponchia/ui/mermaid`, `@ponchia/ui/mermaid.json`, `@ponchia/ui/d2`, `@ponchia/ui/d2.json`, `@ponchia/ui/vega`, `@ponchia/ui/vega.json`) | Stable additive | Theme helper names, JSON shapes, and supported renderer theme slots are public. Values are resolved colours because Mermaid, D2, and Vega cannot consume Bronto CSS variables directly. Exact colours may tune with token changes, but `check:mermaid`, `check:d2`, and `check:vega` must prove every exported theme resolves with no `var()` leaks. No renderer runtime ships. |
@@ -119,7 +149,7 @@ current public-surface matrix and the release policy above still applies.
 | 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-splitter*`, `.ui-inspector*`, `.ui-property*`, `.ui-selectionbar*`, `initSplitter`) | Stable additive | Splitter, inspector, property-row and selection-bar class + BEM part names are public (no recipe). `data-bronto-splitter`, `--splitter-pos`, `bronto:splitter:resize`, and the `initSplitter` cleanup contract are public. Opt-in, not in the default bundle. The host owns pane content, persistence, collapse policy, and selection state. |
-| Command palette (`css/command.css`, `.ui-command*`, `initCommand`, `useCommand` / `command` / `vCommand`) | Stable additive | Command class/part names, the `data-bronto-command` attribute, and the event contract — `bronto:command:select` (`detail: { value, label }`) and `bronto:command:close` — are public, plus the framework binding adapters. Bronto filters + navigates (APG combobox/listbox); the host owns the action registry/execution. Opt-in, not in the default bundle, no global hotkey. |
+| Command palette (`css/command.css`, `.ui-command*`, `initCommand`) | 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. Bronto filters + navigates (APG combobox/listbox); the host owns the action registry/execution. Opt-in, not in the default bundle, no global hotkey. The deprecated framework bindings remain compatible only for the 0.7 migration window. |
 | Spark microcharts (`css/spark.css`, `.ui-spark*`) | Stable additive | Spark class names and inline sizing/label slots are public. Opt-in, not in the default bundle. The host owns data reduction and accessible surrounding text. |
 | Bullet graphs (`css/bullet.css`, `.ui-bullet*`) | Stable additive | Bullet class names and measure/target/range custom-property slots are public. Opt-in, not in the default bundle. The host owns thresholds, units, and data mapping. |
 | Diffs (`css/diff.css`, `.ui-diff*`) | Stable additive | Diff container/line/gutter class names and add/remove/highlight state modifiers are public. Opt-in, not in the default bundle. Bronto styles evidence; it does not compute diffs. |
@@ -129,7 +159,7 @@ current public-surface matrix and the release policy above still applies.
 | Terms / glossary (`css/term.css`, `.ui-term`, `.ui-glossary`) | Stable additive | Term and glossary class names plus native-popover definition hooks are public. Opt-in, not in the default bundle. The host owns glossary content and terminology policy. |
 | Contents rail (`css/toc.css`, `.ui-toc*`) | Stable additive | TOC rail class/part names and current-section state classes are public. Opt-in, not in the default bundle. The host owns section observation and active-state updates. |
 | Tree outlines (`css/tree.css`, `.ui-tree*`) | Stable additive | Tree outline class names, depth styling, and native `<details>` composition are public. Opt-in, not in the default bundle. The host owns tree data, lazy loading, and selection state. |
-| 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, stack-aware `inert` ownership, focus-return, late-background trapping, owned portaled-popover admission, and the cancelable `bronto:modal:close` (`detail: { reason }`) event are public. The consumer still owns the `is-open` class; closing a parent suspends still-open controlled descendants until the parent reopens. The native `<dialog>` path (`initDialog`) remains the default. |
+| Controlled-modal focus trap (`initModal`, adapter `useModal`, `data-bronto-modal`) | Deprecated in 0.7 | The controlled non-`<dialog>` path remains compatible through 0.7 and is scheduled for removal no earlier than 0.8 under ADR-0004. Use native `<dialog>` with `initDialog()`; it remains stable. |
 | 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). |
 | Agent and migration data (`llms.txt`, `MIGRATIONS.json`) | Stable additive | `llms.txt` stays shipped as the offline agent entrypoint. `MIGRATIONS.json` stays a machine-readable migration map for breaking renames/removals. New migration entries are additive; removal of a migration record requires the same breaking-change discipline as the surface it describes. |
 | Generated docs shipped in npm | Stable paths | Exported docs paths stay shipped and resolvable within a compatible minor. Markdown/text assets are for reading unless your runtime has a loader. Generated content may change with the source contract. |

package/docs/state.md

@@ -124,14 +124,64 @@ 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.
 
+## Severity — `.ui-severity`
+
+`.ui-state` answers *what is this thing doing*. Severity answers *how bad is
+it*. Bronto already shipped the tones as per-component modifiers, but never the
+**scale** — the tier names, their order, and the attribute carrying them. So
+every consumer invents the ladder, and inside one app it drifts: one surface
+saying `critical|error|warning|note`, the next `bad|warn`, a third
+`critical|warning|info|ok`, under two different attribute names. Findings then
+do not sort against alerts, and a filter written for one list misses the other.
+
+The ladder, worst to best:
+
+| Level | Means |
+| --- | --- |
+| `critical` | Broken now, and still losing something. |
+| `error` | Something failed; it is not currently getting worse. |
+| `warning` | A threshold was crossed; nothing has failed yet. |
+| `notice` | Worth reading, no action implied. |
+| `ok` | Checked and healthy — an **assertion**, not the absence of news. |
+| `unknown` | Not measured, stale, or the check itself failed. |
+
+`unknown` sits **outside** the ordering on purpose. It is not "slightly worse
+than ok", it is "we do not know" — and collapsing it into `ok` is how a dead
+collector reads as a healthy system. `SEVERITY_LEVELS` therefore excludes it.
+
+The level travels on `data-level`, one attribute name, so the same selector
+works on a chip, a row, a dot, or your own element via `var(--severity-tone)`:
+
+```html
+<span class="ui-severity" data-level="critical">Critical</span>
+
+<li class="ui-severity-row" data-level="warning">
+  <span class="ui-severity-row__title">Disk 84% on kpi-1</span>
+  <span class="ui-severity-row__meta">12m</span>
+</li>
+```
+
+Colour is never the only channel (WCAG 1.4.1): `.ui-severity` carries an
+author-written label, and `.ui-severity-dot` is only for rows that **also** name
+their level in text.
+
 ## Recipe
 
 ```js
-import { ui } from '@ponchia/ui/classes';
+import { ui, severity, SEVERITY_LEVELS } 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"
+
+// Bundles the class WITH data-level, so the attribute that carries the meaning
+// cannot be forgotten — the class alone paints the neutral tone and silently
+// loses the level.
+severity('critical'); // { class: 'ui-severity', 'data-level': 'critical' }
+severity('warning', { part: 'row' }); // { class: 'ui-severity-row', … }
+severity('nope'); // { class: 'ui-severity', 'data-level': 'unknown' }
+
+SEVERITY_LEVELS; // ['critical','error','warning','notice','ok'] — sort/filter from this
 ```
 
 ## Scope

package/docs/theming.md

@@ -4,6 +4,46 @@
 This is the **stable, supported surface** for re-branding without forking.
 Anything not listed here is internal and may change between minor versions.
 
+## Theme selection, persistence, and OS synchronization
+
+Declare both supported schemes in the document head so browser-owned controls
+and chrome follow the active theme:
+
+```html
+<meta name="color-scheme" content="light dark" />
+```
+
+Call `initThemeToggle()` for any `[data-bronto-theme-toggle]` controls. It
+persists an explicit light/dark choice in `localStorage['bronto-theme']`, keeps
+`aria-pressed` current, and emits `bronto:themechange` on `<html>`. When there is
+no explicit `data-theme`, an OS preference change emits the same event, so
+canvas, SVG, MapLibre, and other non-CSS renderers can redraw without a separate
+media-query listener.
+
+```js
+import { initThemeToggle } from '@ponchia/ui/behaviors';
+
+const stopTheme = initThemeToggle();
+document.documentElement.addEventListener('bronto:themechange', (event) => {
+  redrawNonCssSurface(event.detail.theme);
+});
+```
+
+For a stored preference without first-paint flash, put this render-blocking
+script in `<head>` before the stylesheet/module code:
+
+```html
+<script>
+  try {
+    var theme = localStorage.getItem('bronto-theme');
+    if (theme === 'light' || theme === 'dark') document.documentElement.dataset.theme = theme;
+  } catch (error) {}
+</script>
+```
+
+To return to automatic OS mode, remove both the storage item and `data-theme`,
+then reinitialize the theme behavior so it can subscribe to OS changes again.
+
 ## The brand knob: `--accent`
 
 The accent family derives from `--accent` via `color-mix()` and the
@@ -100,6 +140,24 @@ you change CSS `--accent` later.
   [ADR-0003](adr/0003-theme-model.md) for the theme-model rationale.
 - **Radius** — `--radius-sm … --radius-xl`, `--radius-pill`. The Nothing
   default is near-sharp; raise these for a softer brand.
+- **Tap targets** — `--tap-target` (44px, WCAG 2.5.5 / iOS HIG / Material) is
+  the floor every control floats to inside `@media (pointer: coarse)`;
+  `--tap-target-min` (24px) is the WCAG 2.5.8 AA minimum used by controls that
+  only have to clear the smaller bar. Both are authored as `max(px, rem)` on
+  purpose: they scale up with a larger root font but **cannot shrink below the
+  standard** if you re-point `html { font-size }`. If you override them, keep
+  the clamp — a bare rem is how a 44px floor quietly becomes 43.5px. Raise them
+  for a glove-friendly or kiosk build; do not lower them.
+- **Safe areas** — `--safe-area-top / -right / -bottom / -left` default to
+  `env(safe-area-inset-*, 0px)`, so they are 0 everywhere except a device with
+  a display cutout or a gesture bar. Every viewport-anchored surface Bronto
+  ships reads them: the app rail and topbar, a sticky site header, the skip
+  link, both toast stacks, the drawer modal and the lightbox. Override them
+  when your host supplies its own insets — an embedded webview, a kiosk frame,
+  or a test runner that cannot emulate `env()`, which is the reason the values
+  are indirected through custom properties rather than called at the point of
+  use. Consumers positioning their own floating chrome should follow the same
+  convention: `inset-block-end: max(<your offset>, var(--safe-area-bottom))`.
 - **Type** — `--display` (dot-matrix face), `--mono`, `--sans`. Override
   to drop Doto or swap the body face; the token layer keeps working even
   if you self-host fonts (see the `fonts.css` note in the README).
@@ -307,11 +365,15 @@ semantics — the CSS can't add ARIA for you:
 `@ponchia/ui/tokens.dtcg.json` is the token model in the W3C Design
 Tokens Community Group format, for Style Dictionary / Figma / other
 tooling. Generated from `tokens/index.js` and drift-checked by
-`npm run check`. Resolvable primitives (the scale, `--accent`, literal
-palette) carry real `$value`s; the CSS-runtime-derived family
-(`accent-soft`, `focus-ring`, aliases) is spec-shaped with
-`$value: null` + the CSS in `$extensions["com.ponchia.css"]` rather than
-fabricating a number — the resolvable knob is `color.<theme>.accent`.
+`npm run check`. From 0.7 it is a resolved DTCG 2025.10 projection: colours use
+structured sRGB values, dimensions use `{ value, unit }`, durations use
+`{ value, unit }`, and every typed token has a non-null portable value. Derived
+`var()` / `color-mix()` colours are resolved independently in the light and dark
+groups. The authored CSS remains in `$extensions["com.ponchia.css"].authoredValue`.
+CSS-only expressions that cannot be represented portably, including shadows,
+and em-based letter-spacing remain in `@ponchia/ui/tokens.json` rather than
+becoming fake DTCG values. The root extension lists every deliberately omitted
+CSS variable.
 
 `@ponchia/ui/tokens/figma.variables.json` is the resolved local handoff for
 Figma Variables import/sync scripts. It is generated from `tokens/resolved.json`