@ponchia/ui 0.6.11 → 0.7.0

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

@@ -0,0 +1,85 @@
+# Migrating 0.6 to 0.7
+
+Machine-readable migration graph: [`MIGRATIONS.json`](../../MIGRATIONS.json).
+
+0.7.0 repairs public contracts found by auditing ten real consumers. It does
+not add another component family. The only immediate breaking change is the
+value shape of `tokens.dtcg.json`.
+
+## 1. Update DTCG readers
+
+`@ponchia/ui/tokens.dtcg.json` now follows the DTCG 2025.10 typed-value format.
+Colors and dimensions are structured values instead of CSS strings, and the
+file contains no `null` placeholders.
+
+Before 0.7:
+
+```js
+const accent = tokens.color.light.accent.DEFAULT.$value; // '#d71921'
+```
+
+From 0.7:
+
+```js
+const accent = tokens.color.light.accent.DEFAULT.$value;
+// { colorSpace: 'srgb', components: [0.843137, 0.098039, 0.129412], alpha: 1, hex: '#d71921' }
+```
+
+Dimensions now use the same structured form:
+
+```js
+tokens.scale.space.md.$value; // { value: 1, unit: 'rem' }
+```
+
+Derived `var()` and `color-mix()` colors are resolved separately for the light
+and dark groups. Their authored CSS expression remains available under
+`$extensions["com.ponchia.css"].authoredValue`.
+
+If your tool needs every raw CSS expression, including CSS-only shadows and
+em-based letter-spacing, read `@ponchia/ui/tokens.json` instead. If it only needs
+static values for rendering, `@ponchia/ui/tokens/resolved.json` remains the
+simpler flat projection. The DTCG root extension lists the deliberately omitted
+CSS variables.
+
+## 2. Add a non-drag splitter path
+
+Keep the existing separator for pointer dragging and keyboard operation. Add
+normal buttons inside the splitter so a pointer user can resize without a drag:
+
+```html
+<button type="button" data-bronto-splitter-adjust="-10">Narrow first pane</button>
+<button type="button" data-bronto-splitter-adjust="10">Widen first pane</button>
+```
+
+The value is a signed percentage-point delta. `initSplitter()` clamps it to the
+separator's `aria-valuemin` and `aria-valuemax`, updates `--splitter-pos`, and
+emits the existing `bronto:splitter:resize` event.
+
+## 3. Replace deprecated package-only adapters
+
+The React, Solid, Qwik, Svelte, and Vue adapter subpaths remain compatible in
+0.7, but are deprecated for removal no earlier than 0.8. No inspected real
+consumer uses them. Initialize the framework-agnostic behavior in the
+framework's normal client lifecycle and retain its cleanup function.
+
+The controlled non-`<dialog>` `initModal()` path follows the same deprecation
+window. Prefer a native `<dialog class="ui-modal">` with `initDialog()`.
+
+## 4. Check consumer literals
+
+Run the package's zero-dependency checker after upgrading:
+
+```bash
+npx --no-install bronto-ui-check src
+```
+
+It reports literal `ui-*` classes absent from the shipped registry and
+unresolved Bronto-like `var(--*)` references. Use `--allow-class` or
+`--allow-token` only for an intentional consumer-owned exception.
+
+## Re-pin
+
+```jsonc
+// package.json — 0.7 is a breaking minor under the pre-1.0 policy
+"@ponchia/ui": "~0.7.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

@@ -1678,7 +1678,7 @@ Exact mirror of the `:root` blocks in `css/tokens.css`
 | `--display` | `var(--dot-font)` |
 | `--display-weight` | `700` |
 | `--display-weight-strong` | `800` |
-| `--text-2xs` | `0.68rem` |
+| `--text-2xs` | `0.72rem` |
 | `--text-xs` | `0.76rem` |
 | `--text-sm` | `0.86rem` |
 | `--text-base` | `0.95rem` |

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.11/dist/bronto.css" />
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.11/dist/css/report-kit.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.7.0/dist/bronto.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.7.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.11/dist/bronto.css" />
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.11/dist/css/report.css" />
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.11/dist/css/dataviz.css" />
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.11/dist/css/annotations.css" />
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.11/dist/css/legend.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.7.0/dist/bronto.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.7.0/dist/css/report.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.7.0/dist/css/dataviz.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.7.0/dist/css/annotations.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.7.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.11/schemas/report-claims.v1.schema.json",
+  "$schema": "https://cdn.jsdelivr.net/npm/@ponchia/ui@0.7.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
+# 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.7.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
@@ -11,7 +11,7 @@ For the exhaustive package-manifest inventory — every `exports` key, every
 shipped `files` entry, and the generated artifact provenance map — see
 [package-contract.md](./package-contract.md).
 
-## Path To 1.0
+## Path to 1.0
 
 `1.0.0` is a stability declaration, not a catalog milestone. The package is
 ready for 1.0 when the existing public contract is boring to upgrade:
@@ -36,7 +36,7 @@ ready for 1.0 when the existing public contract is boring to upgrade:
   migration entry when machine-actionable, and the deprecate-one-minor policy
   has been followed or explicitly exempted for provably-unreferenced surface.
 
-### 1.0 Readiness Ledger
+### 1.0 readiness ledger
 
 This ledger is the release-candidate checklist. A row is ready only when the
 evidence column is green for the candidate commit; prose approval alone is not
@@ -51,6 +51,31 @@ enough.
 | Bundle budget has headroom | `check:dist`, `check:public-metadata`, `check:pack`, and the README size badge keep default bundle and tarball claims visible. | Budget increases are intentional, reviewed, and named in `CHANGELOG.md`; accidental growth fails before release. |
 | Deprecation history is clean | `check:migrations`, `check:release`, `check:versions`, `MIGRATIONS.json`, and this deprecation policy tie breaking changes to changelog and migration evidence. | No removal ships without either a deprecate-one-minor trail or an explicit BREAKING note for provably-unreferenced surface. |
 
+### Adoption evidence for 1.0
+
+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
+  imports the published surface and passes its own build or checks.
+- **Package-proven:** Packed examples, unit tests, browser tests, and type tests
+  prove compatibility, but no inspected non-example consumer imports the
+  surface.
+- **Speculative:** Neither downstream use nor a package-level executable proof
+  justifies freezing the surface into 1.0.
+
+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.
+
+| 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. 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.7.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.
 
@@ -63,15 +88,16 @@ current public-surface matrix and the release policy above still applies.
 | 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. |
@@ -94,7 +120,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. |
@@ -104,13 +130,13 @@ 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, the `inert`-based focus trap + focus-return, and the cancelable `bronto:modal:close` (`detail: { reason }`) event are public. The consumer still owns the `is-open` class; the behavior never changes visibility. The native `<dialog>` path (`initDialog`) is the default and gets the trap for free. |
+| 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. |
 | Demo, examples, tests, scripts | Internal | Useful for learning and verification, but not shipped runtime API unless a path is explicitly exported in `package.json`. |
 
-## Deprecation Policy
+## Deprecation policy
 
 Public surface (`.ui-*` classes, `data-bronto-*` attributes, `cls`/token keys,
 behavior signatures, and exported schema values) is removed on a
@@ -126,7 +152,7 @@ A token/class/attribute that is provably referenced by no shipped CSS,
 component, behavior, or doc may skip that window and be removed with a BREAKING
 entry plus migration note; there is no working call-site to keep alive.
 
-## Trust Boundary
+## Trust boundary
 
 Behaviors assume trusted application markup. If a delegated root includes
 untrusted CMS or user HTML, sanitize it first or do not initialize behaviors on

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
@@ -307,11 +347,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`

package/docs/usage.md

@@ -362,23 +362,29 @@ element (e.g. `aria-label="Ada Lovelace"`) because the initials alone don't
 convey identity to AT. Keep initials to ~2 characters — the box is
 `overflow: hidden` and silently clips a third.
 
-## Modal: native `<dialog>` vs `is-open`
+## Modal: use native `<dialog>`
 
 Prefer the **native `<dialog>`** path — you get top-layer, backdrop and
 focus-trap free (wire it with `initDialog` for open-triggers + focus-return).
-Only use `ui-modal.is-open` (`ui.modal({ open: true })`) when a portal/React
-modal genuinely can't be a `<dialog>`. The **backdrop and top-layer stacking
-stay yours**, but you no longer have to hand-roll the focus trap: mark the
-overlay `data-bronto-modal` and call `initModal()`. While `is-open` it traps
-focus with `inert` (the rest of the page goes non-interactive), returns focus to
-the opener on close, and dispatches a cancelable `bronto:modal:close` on Escape —
-you still own the `is-open` class, so drop it in response. On bind `initModal`
-also gives the overlay `role="dialog"` + `aria-modal="true"` and dev-warns if it
-has no accessible name (add `aria-label`/`aria-labelledby`). A drawer is a modal
-that enters from an edge — same rule.
-
-**Scroll-lock is not automatic on either path.** Neither the native `<dialog>`
-nor the `is-open` path freezes the background — the page behind an open modal can
+The older `ui-modal.is-open` + `data-bronto-modal` + `initModal()` path remains
+compatible throughout 0.7, but is deprecated for removal no earlier than 0.8.
+It duplicates platform focus, stacking, and inert ownership and no inspected
+real consumer uses it. Migrate portals to a native `<dialog>` where possible;
+if a framework must retain the controlled path during 0.7, keep the existing
+accessible name and `bronto:modal:close` handling unchanged.
+
+Controlled modals share one document-level stack. Opening a sibling portal
+modal makes the previous modal inert and keeps only the new top modal
+interactive; closing it restores focus into the previous modal. An
+`initPopover()` trigger inside the top modal may target a panel portaled
+elsewhere in the document: while that panel is open, it joins the live modal
+tree and owns Escape without releasing unrelated background content. Background
+nodes added after the modal opens are trapped too. If a controlled parent modal
+closes while a descendant still carries `is-open`, the descendant is suspended
+with the parent and resumes if the parent reopens.
+
+**Scroll-lock is not automatic.** A native `<dialog>` does not freeze background
+scroll — the page behind an open modal can
 still scroll. If that matters, toggle a lock yourself while the modal is open
 (`document.documentElement.style.overflow = 'hidden'`, restored on close), or add
 `html:has(dialog[open]) { overflow: hidden }` for the native path.
@@ -564,6 +570,49 @@ authoring engine.
   provide. The summary's title is the legible sans, not the display face — it's
   meant to be read.
 
+### Branded file input: keep the native control operable
+
+Prefer the visible native control: `<input class="ui-file" type="file">` styles
+its file-selector button without hiding the input. If the product needs a
+button-shaped label, keep the native input focusable inside the label and expose
+its focus on the visible wrapper. Never use `display: none` on the input: that
+removes it from keyboard navigation.
+
+```html
+<label class="ui-button upload-button">
+  Choose file
+  <input class="ui-visually-hidden" type="file" name="document" />
+</label>
+```
+
+```css
+.upload-button:focus-within {
+  outline: 3px solid var(--focus-ring);
+  outline-offset: var(--focus-offset);
+}
+```
+
+### Sortable table: the button is part of the contract
+
+Put a real button in each sortable header, mark the table, then initialize the
+behavior. Use `data-sort="num"` for numeric columns and `data-sort-value` on a
+cell when its displayed text is not a canonical sortable value.
+
+```html
+<table class="ui-table" data-bronto-sortable>
+  <thead><tr>
+    <th><button class="ui-table__sort" data-sort type="button">Name</button></th>
+    <th class="is-num"><button class="ui-table__sort" data-sort="num" type="button">Score</button></th>
+  </tr></thead>
+  <tbody><tr><td>Ada</td><td class="is-num" data-sort-value="9.5">9,5</td></tr></tbody>
+</table>
+```
+
+```js
+import { initTableSort } from '@ponchia/ui/behaviors';
+const cleanup = initTableSort();
+```
+
 ## Reveal: `ui-reveal` needs JS, `ui-scroll-reveal` doesn't
 
 `ui-scroll-reveal` is scroll-driven and **zero-JS** — reach for it in a static
@@ -605,8 +654,9 @@ It is a **non-modal** dialog by design: the panel gets `role="dialog"` and focus
 moves into it, but there is **no focus trap** and the rest of the page stays
 interactive — Tab moves *out* of the panel (it does not cycle), and it closes on
 Escape or outside-click. Don't assume `<dialog>`-modal semantics; if you need a
-trap and an inert backdrop, use a real modal (`<dialog>` + `initDialog`, or
-`initModal`). And the `is-open` fallback is a plain stacked element, so it sits
+trap and an inert backdrop, use a real modal (`<dialog>` + `initDialog`). The
+deprecated `initModal()` path remains available only for 0.7 migration. And the
+`is-open` fallback is a plain stacked element, so it sits
 *under* any open native `<dialog>`'s top layer — another reason to prefer the
 native `popover` attribute when a popover and a dialog can be open together.
 
@@ -640,7 +690,7 @@ These are JS widgets wearing the Bronto look; without the behavior they are iner
 | Popover (`ui-popover`) | `initPopover` | no placement/ARIA — prefer the native `popover` attribute |
 | Carousel (`ui-carousel`) | `initCarousel` | a native scroll-snap track (usable, no controls) |
 | Native dialog/lightbox (`<dialog>`, `ui-lightbox`) | `initDialog` | closed markup stays closed; `data-bronto-open`/close buttons do nothing. Do not use `open` as a modal fallback: it is non-modal and has no trigger/focus-return path |
-| Controlled modal (`ui-modal.is-open`) | `initModal` | open skin only — no inert trap, focus-return, or Escape close signal |
+| Controlled modal (`ui-modal.is-open`, deprecated) | `initModal` (deprecated) | open skin only — no inert trap, focus-return, or Escape close signal |
 | Menu (`data-bronto-menu`) | `initMenu` | a button next to a list with no open/close, outside-click, or Escape |
 | Dismissible alert/callout (`data-bronto-dismissible`) | `dismissible` | the close affordance is just a button; nothing is removed |
 | Toast | `toast()` | nothing — it is imperative-only |
@@ -661,7 +711,7 @@ boundary of what CSS alone cannot do.
 
 The CSS is the framework; `@ponchia/ui/behaviors` is the *sanctioned*
 home for the little JS that genuinely needs scripting (theme persistence,
-disclosure, dialog glue, modal focus-trap, toast, combobox, form-validation,
+disclosure, native-dialog glue, toast, combobox, form-validation,
 table-sort, splitter resizing). Reach for it instead of reimplementing — every
 initializer is SSR-safe, idempotent, and returns a cleanup. If you find yourself
 writing focus management, ARIA value sync, or `aria-expanded` toggling by hand,

package/docs/workbench.md

@@ -80,7 +80,17 @@ domain selection model.
   data-bronto-splitter
   style="--splitter-pos: 36%"
 >
-  <section class="ui-splitter__pane" id="files" aria-label="Files">...</section>
+  <section class="ui-splitter__pane" id="files" aria-label="Files">
+    <div class="ui-cluster" role="group" aria-label="Resize files pane">
+      <button class="ui-button ui-button--sm" type="button" data-bronto-splitter-adjust="-10">
+        Narrow
+      </button>
+      <button class="ui-button ui-button--sm" type="button" data-bronto-splitter-adjust="10">
+        Widen
+      </button>
+    </div>
+    ...
+  </section>
   <div
     class="ui-splitter__handle"
     role="separator"
@@ -99,7 +109,11 @@ domain selection model.
 Use `.ui-splitter--horizontal` for top/bottom panes. Arrow keys change the value
 by 2 percentage points, Shift+Arrow and PageUp/PageDown by 10, and Home/End jump
 to `aria-valuemin` / `aria-valuemax`. The handle needs a real accessible name
-and `aria-controls` pointing at the primary pane.
+and `aria-controls` pointing at the primary pane. Also provide ordinary buttons
+with `data-bronto-splitter-adjust="-10"` / `"10"`: pointer users then have a
+non-drag resize path, while keyboard and assistive-technology users retain the
+separator interaction. The signed value is a percentage-point delta and is
+clamped to the separator's min/max.
 
 ## Inspector — `.ui-inspector`
 

package/llms.txt

@@ -45,7 +45,7 @@ the path changes from source `css/` to built `dist/css/`:
 <!-- installed locally -->
 <link rel="stylesheet" href="./node_modules/@ponchia/ui/dist/css/<leaf>.css" />
 <!-- or from a CDN; pin the version (pre-1.0, breaking changes ship in the minor) -->
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.11/dist/css/<leaf>.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.7.0/dist/css/<leaf>.css" />
 ```
 
 The flattened default bundle is `dist/bronto.css` (bundler shorthand
@@ -75,7 +75,8 @@ import { applyStoredTheme } from '@ponchia/ui/behaviors';
 Notable behaviors beyond the obvious: `initMenu()` adds close affordances to a
 native `<details data-bronto-menu>` dropdown (outside-click/Escape/select-close);
 `initModal()` wires the controlled `.ui-modal.is-open` path (inert focus-trap +
-role/aria-modal); `initDisabledGuard()` makes every `aria-disabled` control
+role/aria-modal), but is deprecated in 0.7 for removal no earlier than 0.8;
+prefer native `<dialog>` + `initDialog()`. `initDisabledGuard()` makes every `aria-disabled` control
 keyboard-inert (CSS alone is only pointer-inert). For the value-bearing fills,
 `attrs.meter(value)` / `attrs.progress(value)` from `@ponchia/ui/classes` return
 `role`+`aria-valuenow/min/max`+the `--value` style to spread onto the host.
@@ -86,6 +87,8 @@ matching `.ui-source-card`, seed lightweight preview metadata, and emit
 and any rich preview popover.
 
 Optional lifecycle adapters wrap those behaviors without owning markup or state.
+They remain compatible in 0.7 but are deprecated for removal no earlier than
+0.8; prefer vanilla behavior initialization in the host lifecycle.
 React/Solid/Qwik use hook bindings (peer deps `react` / `solid-js` /
 `@builder.io/qwik`, optional — core stays zero-dep); Svelte uses dependency-free
 actions, and Vue uses dependency-free directives/plugin helpers:
@@ -769,7 +772,8 @@ Read these from `node_modules/@ponchia/ui/` — no network needed:
   resolved palette; the build fails below the declared floor.
 - `tokens/index.d.ts` — every design-token name as a literal union.
 - `tokens/index.json` — tokens as plain data (global / light / dark).
-- `tokens/tokens.dtcg.json` — same tokens in W3C DTCG format.
+- `tokens/tokens.dtcg.json` — resolved DTCG 2025.10 structured typed values;
+  authored CSS expressions remain in `tokens/index.json` and DTCG extensions.
 - `tokens/resolved.json` — every colour token resolved to a static
   `#rrggbb` / `rgba(...)` per theme (var() + color-mix() evaluated) in
   `light`/`dark`, plus a `scale` block of the non-colour scales