@ponchia/ui 0.9.0 → 0.11.0

package/docs/adr/0006-trusted-publishing.md

@@ -0,0 +1,92 @@
+# 0006. Publish to npm without a stored credential
+
+Status: accepted; applies from 0.10.0
+
+## Context
+
+Releases authenticated to npm with a granular access token held in the
+`NPM_TOKEN` secret of the protected `npm-publish` environment. The token was
+created on 2026-05-30 with 2FA bypass, write access to `@ponchia/ui`, and an
+expiry of 2026-08-28.
+
+The v0.10.0 release exposed the cost of that design. Every gate passed —
+validation, cross-engine end-to-end, packed examples, publish preflight — the
+maintainer approved the protected environment, and the publish then failed
+with `E404` on an existing package. `E404` reads as "no such package", so the
+first hypothesis was package metadata. The real cause was that the token had
+expired eleven days earlier. A read-only `whoami` request would have returned
+`401` at any point in those eleven days, but nothing was asking.
+
+Three properties of the old design combined into that outcome:
+
+- The credential's validity was invisible until the most expensive moment in
+  the pipeline, after roughly twenty minutes of gates and a human approval.
+- npm's failure mode misattributes an authentication problem to the package,
+  so the error text actively points investigation the wrong way.
+- Expiry is silent. Nothing in the repository, the environment, or CI knew the
+  date; it lived only in a note beside the token in the password manager.
+
+The approval gate did not and could not help. A required reviewer releases the
+job; it does not check that the job can authenticate.
+
+Two further constraints made "rotate the token and continue" unattractive.
+From August 2026 npm forbids tokens with 2FA bypass from performing token
+management, so a CI token can no longer mint or rotate its successor — every
+renewal is a manual browser session with a second factor. And npm has stated
+that direct token publishing will be reduced further, with trusted publishing
+as the endorsed path.
+
+Trusted publishing was previously assessed as unavailable to this estate: npm
+supports it only on provider-hosted runners, and most repositories here run on
+self-hosted `arc-vps-*` runners because GitHub-hosted minutes are billing
+blocked. That assessment does not hold for this repository. `bronto-ui` is
+public, so GitHub-hosted minutes are free, and the release workflow already
+runs entirely on `ubuntu-latest`.
+
+## Decision
+
+Publish by trusted publishing (OIDC). No npm credential is stored.
+
+GitHub mints a short-lived token for the workflow run; npm exchanges it for a
+publish credential scoped to that run. The publisher is registered on npmjs.com
+against a four-part identity: the organization `Ponchia`, the repository
+`bronto-ui`, the workflow filename `release.yml`, and the environment
+`npm-publish`. All four must match or the exchange is refused.
+
+Two conditions are enforced by `check:release` rather than left to review,
+because both fail only at publish time:
+
+- `publish-npm` raises the npm CLI past 11.5.1. Node 22 bundles npm 10.x,
+  which predates OIDC support and falls back to looking for a token.
+- `publish-npm` references neither `NODE_AUTH_TOKEN` nor `secrets.NPM_TOKEN`.
+  A reintroduced token takes precedence over OIDC, which would quietly restore
+  the failure mode this decision removes.
+
+## Consequences
+
+The expiry class of failure is gone: there is no long-lived credential, so
+there is no date to miss and no rotation to schedule. The blast radius of a
+compromised repository secret shrinks to nothing, because the secret does not
+exist. Provenance is generated automatically instead of depending on a flag.
+
+The identity is now positional, which is the cost. Renaming `release.yml`,
+moving the publish to another environment, or transferring the repository
+breaks publishing until the npm-side registration is updated — a rename that
+is otherwise routine becomes a release-blocking change. The workflow header
+and `docs/architecture.md` both say so at the point where someone would make
+that edit.
+
+Registration itself remains a browser action requiring the maintainer's second
+factor. That is a one-time cost rather than a recurring one, which is the
+whole point.
+
+The `NPM_TOKEN` secret and its password-manager entry are retired after the
+first successful trusted publish, not before, so the previous path stays
+available if the exchange needs debugging.
+
+Like every other ADR, this record ships in the package. `check:pack` enforces
+that: the published documentation points into `docs/adr/`, so an ADR that
+exists but is not in `files` leaves a consumer following that pointer at a
+404. The decision set is published whole or not at all — a release-mechanics
+record is not carved out on the grounds that consumers are unlikely to want
+it.

package/docs/architecture.md

@@ -11,9 +11,9 @@ Status: accepted · 2026-05-15 · applies from v0.2.0
 >   gates, opt-in colorways, data-viz, APCA advisory reporting, and the
 >   OKLCH core accent ramp.
 > - [ADR-0004 — Prune unused adapter and controlled-modal surfaces](./adr/0004-prune-unused-adapters.md)
->   (accepted; deprecated in 0.7) — retain the package-only adapters and
->   controlled modal for one migration minor, then remove them unless a real
->   consumer supplies adoption evidence.
+>   (implemented in 0.10) — remove unadopted adapters and the controlled modal.
+> - [ADR-0005 — Productive tools and editorial reports](./adr/0005-productive-tools-and-editorial-reports.md)
+>   (accepted; 0.10) — readable defaults, selective display identity, and task-led composition.
 
 ## Context
 
@@ -44,11 +44,6 @@ on top of the CSS, none of which require a framework commitment**:
 ├── annotations/ pure SVG callout geometry (builds on connectors)     [optional]
 ├── glyphs/      dot-matrix glyph registry/renderers                 [optional]
 ├── schemas/     declarative JSON contracts for report/tooling data   [optional]
-├── react/       deprecated React hooks over behaviors               [remove >=0.8]
-├── solid/       deprecated Solid primitives over behaviors          [remove >=0.8]
-├── qwik/        deprecated Qwik hooks over behaviors                 [remove >=0.8]
-├── svelte/      deprecated Svelte actions over behaviors            [remove >=0.8]
-└── vue/         deprecated Vue directives over behaviors            [remove >=0.8]
 ```
 
 ### Consequences of each layer
@@ -92,11 +87,6 @@ on top of the CSS, none of which require a framework commitment**:
 - **glyphs/** — static bitmap data and SSR-safe render helpers. The
   256-cell DOM renderers are for display and solid inline icons; the `.ui-icon`
   mask renderer is for dense icon-at-scale use.
-- **react/** / **solid/** / **qwik/** / **svelte/** / **vue/** — deprecated
-  lifecycle adapters over `behaviors/`. They remain compatible for the complete
-  0.7 minor, then may be removed in 0.8 under ADR-0004. Ten real-consumer audits
-  found no adapter imports; framework consumers already use the vanilla
-  initializers in their own mount/cleanup lifecycle.
 - **`css/analytical.css` — the analytical roll-up.** This convenience file
   `@import`s exactly **nine** analytical figure/evidence leaves: `figure`,
   `annotations`, `legend`, `marks`, `connectors`, `spotlight`, `crosshair`,
@@ -111,8 +101,7 @@ on top of the CSS, none of which require a framework commitment**:
   `import '@ponchia/ui'` in Vite/Astro/SvelteKit). There is no runtime JS at
   the package root — Node/runtime JS imports of `.` are not supported. All JS
   entrypoints are explicit subpaths (`/behaviors`, `/classes`, `/tokens`,
-  `/glyphs`, `/annotations`, `/connectors`, `/react`, `/solid`, `/qwik`,
-  `/svelte`, `/vue`, `/skins`, `/charts`, `/mermaid`, `/d2`, `/vega`). This is
+  `/glyphs`, `/annotations`, `/connectors`, `/skins`, `/charts`, `/mermaid`, `/d2`, `/vega`). This is
   a permanent, intentional contract.
 
 ### Surface admission rule
@@ -140,7 +129,7 @@ registries, virtualized grids, or framework component APIs.
 The repo root mixes five kinds of directory that look alike but follow very
 different rules. Two distinctions matter most: several are **path-frozen
 published subpaths** — the directory name _is_ the public import specifier
-(`@ponchia/ui/react` resolves to `./react/`), so they cannot be moved or
+(`@ponchia/ui/behaviors` resolves to `./behaviors/`), so they cannot be moved or
 renamed — and several are **generated** and must never be hand-edited (a
 generator overwrites them and a drift gate fails CI).
 
@@ -148,7 +137,7 @@ generator overwrites them and a drift gate fails CI).
 | --- | --- | --- | --- |
 | `css/` | source | yes | The framework. Most leaves are hand-authored `@layer bronto` CSS. The palette blocks in `css/tokens.css`, plus `css/skins.css` and `css/dataviz.css`, are generated. `css/generated.css` is authored trust-surface CSS despite its name. |
 | `tokens/index.js` | source | yes | The single source of truth for token **values** (`cssVars`). |
-| `classes/index.js`, `behaviors/`, `annotations/`, `connectors/`, `react/`, `solid/`, `qwik/`, `svelte/`, `vue/`, `glyphs/`, `shiki/` | source · published-subpath (path-frozen) | yes — but **do not move** | Authored ESM shipped as-is; the dir name is the public import path. The `.d.ts` beside them are generated/drift-checked: `connectors`/`annotations`/`react`/`solid`/`qwik`/`svelte`/`vue`/`behaviors` are emitted from JSDoc by `tsc` (`npm run dts:emit`), `classes`/`tokens`/`glyphs` from the runtime. No leaf `.d.ts` is hand-maintained. |
+| `classes/index.js`, `behaviors/`, `annotations/`, `connectors/`, `glyphs/`, `shiki/` | source · published-subpath (path-frozen) | yes — but **do not move** | Authored ESM shipped as-is; the dir name is the public import path. The `.d.ts` beside them are generated/drift-checked: `connectors`/`annotations`/`behaviors` are emitted from JSDoc by `tsc` (`npm run dts:emit`), `classes`/`tokens`/`glyphs` from the runtime. No leaf `.d.ts` is hand-maintained. |
 | `schemas/*.schema.json` | source · published schema files (path-frozen) | yes — but **do not move exported files** | Declarative JSON Schema contracts for sidecars/tooling data. Each exported schema file path is public; the directory itself is not a wildcard import. No validator runtime ships. |
 | `dist/` | generated | no | Build of `css/` (`npm run dist:build`); byte-checked by `check:dist`. |
 | `tokens/index.json`, `tokens/resolved.json`, `tokens/tokens.dtcg.json`, `tokens/figma.variables.json`, `tokens/charts.json`, `classes/index.d.ts`, `tokens/index.d.ts`, `tokens/{skins,charts}.d.ts`, `glyphs/glyphs.d.ts`, `classes/vscode.css-custom-data.json`, `docs/reference.md` | generated | no | Committed build artifacts; regenerate with `npm run prepack`, never hand-edit. Drift-checked in `npm run check`. |
@@ -184,7 +173,7 @@ are copied into consumer reports.
 | exports / import graph / source CSS `layer(bronto)` imports / layered-vs-unlayered CSS target map / `files` consistent | `check-exports.mjs` |
 | pure generated mirrors fresh — `tokens.css`/`index.json`, `dtcg.json`, `resolved.json`, `figma.variables.json`, `classes`/`tokens` `.d.ts`, `reference.md`, vscode data — each byte-equal to its generator (registry: `scripts/lib/artifacts.mjs`) | `check-fresh.mjs` |
 | `classes` `cls` ⇄ `.ui-*` selectors             | `check-classes.mjs` |
-| `connectors`/`annotations`/`react`/`solid`/`qwik`/`svelte`/`vue`/`behaviors` `.d.ts` (+ maps) == fresh `tsc` emit of their JSDoc | `check-dts-emit.mjs` |
+| `connectors`/`annotations`/`behaviors` `.d.ts` (+ maps) == fresh `tsc` emit of their JSDoc | `check-dts-emit.mjs` |
 | legend swatch colours ⊆ `charts.js` · opt-in   | `check-legend.mjs`  |
 | color tokens tiered · no raw chromatic color in components | `check-color-policy.mjs` |
 | `css/skins.css` ⇄ `tokens/skins.js` · colorways opt-in | `check-skins.mjs` |
@@ -193,14 +182,13 @@ are copied into consumer reports.
 | `shiki/nothing.json` valid + on rationed palette | `check-shiki.mjs`  |
 | `dist/*.css` == fresh single-`@layer bronto` build of `css/` + budget | `check-dist.mjs`    |
 | published tarball == intended `files` only      | `check-pack.mjs`    |
-| packed core JS/JSON public subpaths import without optional framework peers, packed JS named exports exactly match source modules, peer-backed adapters import after peers are linked, concrete CSS/doc/font subpaths resolve, and packed behavior initializers/toast no-op in a clean consumer with no DOM globals | `check-consumer-surface.mjs` |
+| packed JS/JSON public subpaths import without framework peers, packed JS named exports exactly match source modules, concrete CSS/doc/font subpaths resolve, and packed behavior initializers/toast no-op in a clean consumer with no DOM globals | `check-consumer-surface.mjs` |
 | packed typed public subpaths compile through package exports in a clean TypeScript consumer | `check-consumer-types.mjs` |
 | function-level cyclomatic complexity stays ≤12 and function NLOC stays within budget, with no per-function exception list | `check-complexity.mjs` |
 | GitHub Actions workflow syntax and embedded shell snippets lint | `check:workflows` (`github-actionlint`) |
 | every shipped CSS leaf is classified as foundation or has explicit docs/demo/e2e ownership | `check-component-matrix.mjs` |
 | every public behavior export has explicit docs, unit-test, and browser-test ownership | `check-behavior-matrix.mjs` |
 | every public helper export in `classes`/`annotations`/`connectors`/`glyphs` has explicit docs, unit-test, and type-test ownership | `check-helper-matrix.mjs` |
-| every delegated behavior has React/Solid/Qwik hook, Svelte action, Vue directive, docs, example, unit, and type ownership | `check-binding-matrix.mjs` |
 | `@playwright/test` version ⇄ pinned Playwright container image ⇄ visual workflows/docs/local runner | `check-playwright-container.mjs` |
 | every shipped JSON schema is exported, documented, validates its public cookbook example, and rejects malformed sidecars | `check-schemas.mjs` |
 | packed public text contains no private terms, local paths, or secret-looking assignments | `check-public-hygiene.mjs` |
@@ -263,7 +251,13 @@ pointer:
   with provenance. Runs in the `npm-publish` **Environment**
   (required-reviewer protection), so after the gates and preflight pass the run
   pauses for a manual approval in the Actions UI before anything reaches npm —
-  a guard against an accidental tag push publishing. Dist-tag is derived from
+  a guard against an accidental tag push publishing. Authentication is
+  **trusted publishing (OIDC)**: no npm token is stored anywhere, and the
+  credential npm mints is short-lived and bound to this repository, this
+  workflow filename, and this environment
+  ([ADR-0006](./adr/0006-trusted-publishing.md)). Renaming `release.yml` or
+  moving the publish to another environment breaks publishing until the
+  npm-side registration is updated. Dist-tag is derived from
   the tag: stable (`v0.4.0`) → `latest`; SemVer prerelease (`v0.4.0-rc.1`, any
   hyphenated identifier) → `next`, so the default `npm i @ponchia/ui` never
   moves onto an unstable build (opt in with `@ponchia/ui@next`). Post-publish
@@ -321,8 +315,7 @@ explained, not surprising.
 - Run `npm pack --dry-run --json` locally or from CI logs and confirm the
   intended file count/payload.
 - Build the packed examples matrix from the tarball, not a workspace link:
-  `npm run test:examples` covers vanilla, Astro, SvelteKit, Vue, React, Solid,
-  Qwik, Tailwind, and report-static, with Chromium browser smokes for runtime
+  `npm run test:examples` covers vanilla, Astro, SvelteKit, React, Tailwind, and report-static, with Chromium browser smokes for runtime
   examples. For a deeper consumer pass, `npm run test:examples:cross-browser`
   runs the same packed smokes in Chromium, Firefox, and WebKit; manual CI
   dispatches pass the same cross-browser flag to the reusable examples workflow.

package/docs/command.md

@@ -34,8 +34,7 @@ stable ids, roles, `aria-controls`, `aria-expanded`,
 `aria-activedescendant`, keyboard navigation, filtering, selection, and close
 behavior. Do not bind both owners to the same palette.
 
-The framework adapter subpaths remain compatible in 0.7 but are deprecated for
-removal no earlier than 0.8. Prefer direct `initCommand()` lifecycle cleanup for
+The framework adapter subpaths were removed in 0.10. Use direct `initCommand()` lifecycle cleanup for
 a DOM-authored list, or controlled host mode when the framework owns the widget.
 
 ## Markup

package/docs/compositions.md

@@ -0,0 +1,131 @@
+# Compose a tool or report
+
+Start with the task and its important state. Use the catalog to find a part,
+not to decide how many parts a page should contain.
+
+## Service overview
+
+Load the core CSS and the opt-in state leaf. Use `ui-app-shell` for navigation,
+`ui-app-topbar` for the page title and primary action, and `ui-app-content` for
+the current state and work queue. Panels group content without adding another
+frame around every metric and table.
+
+```css
+@import '@ponchia/ui';
+@import '@ponchia/ui/css/state.css';
+```
+
+Use sentence-case labels. Keep the main action distinguishable from destructive
+actions through wording and placement. Use `ui-delta--invert` when a decrease
+is favorable, such as queue delay. Unknown, stale, and failed are distinct
+states; do not present missing observations as success.
+
+The complete specimen is [service.html](https://ponchia.github.io/bronto-ui/demo/service.html). On a phone,
+navigation wraps and the compact metrics leave room for the work queue.
+The specimen owns deterministic loading, empty, error and stale scenarios,
+search/environment filtering and a local sample-job dialog. Unknown observations
+hide operational health claims; stale ones stay visibly qualified. Use Sync to
+recover. These behaviors are sample host logic, not package state management.
+
+Check the main action, every navigation destination, and a long account name
+at 360px and with a coarse pointer. A data table may scroll in its own region.
+
+## Inspector and workbench
+
+Load `workbench.css` beside core. An inspector supplies its own container
+boundary: property rows stack below 20rem of available inline size, including
+inside a narrow panel on a wide desktop.
+
+```html
+<aside class="ui-inspector" aria-label="Selected job">
+  <header class="ui-inspector__head"><h2>Job settings</h2></header>
+  <div class="ui-inspector__body">
+    <div class="ui-property">
+      <label class="ui-property__label" for="retry-count">Retry limit</label>
+      <div class="ui-property__value">
+        <input class="ui-input" id="retry-count" type="number" value="3" />
+      </div>
+    </div>
+  </div>
+</aside>
+```
+
+A splitter does not choose a product's collapse policy. The
+[workbench specimen](https://ponchia.github.io/bronto-ui/demo/workbench.html) stacks its two panes below 42rem
+of container width and hides the inactive resize handle and resize controls.
+Both panes remain available. A tool that needs a pane switch instead should
+keep that policy in its own component.
+
+Keep a badge inside a `ui-row__meta` wrapper rather than applying both classes
+to the same element: the wrapper owns layout and the badge owns its tone.
+
+Use `ui-chip--dense` for static labels inside short pane headers. Dense chips
+on buttons, links, or button roles retain pointer target floors. Use regular
+buttons for actions; a colored chip is not an action registry.
+
+Test the resize control’s keyboard and pointer paths at wide sizes, then verify
+that the narrow layout has no hidden keyboard-reachable resize control and both panes
+have a useful reading width. Test the inspector inside a 280px parent while
+the browser itself is wide.
+
+## Decision report
+
+Use the core stylesheet plus `report-kit.css` for a standalone HTML report.
+Use real asset URLs in HTML; package specifiers resolve only in build tools.
+
+```html
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.11.0/dist/bronto.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.11.0/dist/css/report-kit.css" />
+<article class="ui-report">
+  <header class="ui-report__cover ui-report__cover--compact">
+    <h1 class="ui-report__title">Keep the current configuration</h1>
+    <p class="ui-report__subtitle">Queue delay improved; verify the next scheduled run.</p>
+  </header>
+  <section class="ui-report__section" aria-labelledby="decision-title">
+    <h2 class="ui-report__section-head" id="decision-title">Decision and basis</h2>
+    <p>The completed runs support keeping the change. The next batch remains unobserved.</p>
+  </section>
+  <details class="ui-report__toc ui-screen-only">
+    <summary>Contents and evidence</summary>
+    <ol><li><a href="#decision-title">Decision and basis</a></li></ol>
+  </details>
+</article>
+```
+
+Screen prose is 1.125rem with a 68ch maximum reading measure; the report can
+still contain wider figures and evidence tables. Print uses 11pt ink-on-white
+text. Use the `--report-measure` and `--report-width` hooks deliberately.
+Do not apply `ui-display` to every report heading.
+
+The [standalone specimen](https://ponchia.github.io/bronto-ui/demo/report-standalone.html) keeps its decision
+before collapsed navigation. Verify the recommendation and its source are
+findable, the text remains readable at narrow widths, and the PDF retains
+claims, captions, and evidence across page boundaries.
+
+## Display identity
+
+`ui-display`, dot glyphs, and readouts preserve the expressive identity.
+Use them for a short hero title or deliberate display moment. Ordinary `h1`
+through `h4`, prose, labels, and controls use sans typography. Fixed-width type is for
+code, identifiers, and aligned data; a whole page does not need to be mono to
+look technical.
+
+Use one dominant action per local task. Separate navigation, action, severity,
+and evidence status semantically even when they share a color family. Test
+light and dark together, and keep keyboard focus and reduced motion visible.
+
+## Embedded evidence
+
+Constrain the figure, decision grid or action list inside a wide page. Each
+uses its own available width. A two-up comparison wraps intrinsically even
+outside `ui-report`. Keep value columns readable and source links reachable;
+page overflow is an incomplete test. The container regression suite checks
+280/320/480px parents and a wide layout.
+
+Review long action status, legend names and citation markers. Keep chart
+annotations in their `viewBox` or supply an equivalent narrow fallback. Print
+uses document flow instead of size containment.
+
+For an existing application, review explicit typography overrides with the
+[0.11 migration recipe](migrations/0.10-to-0.11.md). A dependency pin does not
+remove consumer CSS that overrides the shared layer.

package/docs/discussion.md

@@ -0,0 +1,64 @@
+# Discussions
+
+Use the opt-in discussion leaf for readable thread lists, messages, quotations,
+and composers in a host application:
+
+```css
+@import '@ponchia/ui';
+@import '@ponchia/ui/css/discussion.css';
+```
+
+BrontoUI supplies the visual structure. The host owns storage, identity,
+thread resolution, text anchoring, unread state, and posting behavior. This leaf
+adds no JavaScript or editor dependency.
+
+## Thread structure
+
+```html
+<section class="ui-discussion" aria-labelledby="thread-title">
+  <header class="ui-discussion__header">
+    <div>
+      <h2 id="thread-title">Discussion</h2>
+      <p>Release notes</p>
+    </div>
+  </header>
+  <p class="ui-discussion__state">Open · passage attached</p>
+  <blockquote class="ui-discussion__quote">The selected passage.</blockquote>
+  <ol class="ui-discussion__messages">
+    <li class="ui-discussion__message">
+      <p class="ui-discussion__meta"><strong>Reviewer</strong> · today</p>
+      <p>Can we clarify this sentence?</p>
+    </li>
+  </ol>
+  <form class="ui-discussion__composer">
+    <label for="reply">Reply</label>
+    <textarea id="reply" name="reply" rows="4"></textarea>
+    <div class="ui-discussion__actions">
+      <button class="ui-button" type="submit">Post reply</button>
+    </div>
+  </form>
+</section>
+```
+
+Wire the form to the host's posting mechanism. Keep the draft when posting
+fails, disable duplicate submissions while a request is pending, and announce
+success only after confirmation. Use native buttons for actions and real links
+for navigation. A modal host must supply focus management and focus return.
+
+## Reading and recovery
+
+The styles use sentence case and sans-serif prose, wrap long text, and allow
+action rows to wrap in narrow panels. Keep secondary actions visually quiet
+with `ui-button--ghost`; posting is normally the primary action. The quote
+should remain visible when its anchor disappears, with a clear status and a
+host-owned way to choose a new target. Anchor status and thread resolution
+answer different questions and should be labelled separately.
+
+`ui-discussion__list` and `ui-discussion__item` style a host-owned thread index.
+Keep the list bounded and offer more results explicitly. If a canvas uses pins,
+provide the same discussions in a keyboard-accessible list. Pins, positions,
+and annotation geometry are outside this CSS leaf.
+
+The [discussion specimen](https://ponchia.github.io/bronto-ui/demo/discussion.html) includes a narrow-container
+example and a local reply/resolve demonstration. Its state lasts only until
+the page reloads.

package/docs/figure.md

@@ -61,7 +61,7 @@ when the same stage appears in a dashboard, doc page, or generated artifact.
 | --- | --- | --- |
 | `--figure-max-inline` | `.ui-figure__stage` | Maximum stage width, default `42rem`. |
 | `--figure-min-block` | `.ui-figure__stage` | Reserved stage height for late-rendered media. |
-| `--figure-key-width` | `.ui-figure__body--key-right` | Right key column width before mobile collapse. |
+| `--figure-key-width` | `.ui-figure__body--key-right` | Right key column width before the figure container stacks. |
 
 ## Boundary
 
@@ -76,3 +76,12 @@ when the same stage appears in a dashboard, doc page, or generated artifact.
 
 - [Usage](usage.md#static-reports) shows report figure composition.
 - [Reference](reference.md) lists the generated figure and report classes.
+
+## Narrow containers
+
+The figure establishes the named `bronto-figure` inline-size container. Its
+right-hand key stacks below 44rem of figure width, even in a wide browser.
+Print disables size containment and uses document flow. Keep annotation text
+and strokes within the authored `viewBox`; container layout does not reposition
+chart geometry. Verify a 280px parent with long legend names and a fallback
+table, not just a narrow viewport.

package/docs/frontier-primitives.md

@@ -185,8 +185,7 @@ a consumer needs it.
 The keyboard-hint primitive (`.ui-shortcut` + `.ui-shortcut__sep` over `.ui-kbd`,
 core chrome) landed first, then the `ui-command` palette: the
 `@ponchia/ui/css/command.css` shell + the `initCommand` `data-bronto-command`
-behavior (filter, roving focus, `bronto:command:select`/`close`) + `useCommand`
-bindings. The host still owns the action registry and execution — Bronto only
+behavior (filter, roving focus, `bronto:command:select`/`close`). The host still owns the action registry and execution — Bronto only
 filters and navigates.
 
 Why it matters: command palettes turn a product from a page collection into a

package/docs/migrations/0.10-to-0.11.md

@@ -0,0 +1,61 @@
+# Upgrade from 0.10 to 0.11
+
+0.11 completes the readable composition direction. The structured visual
+changes are in [`MIGRATIONS.json`](../../MIGRATIONS.json). JavaScript exports,
+classes, and tokens remain available. If you are coming from 0.9, apply the
+[0.10 migration](0.9-to-0.10.md) first, including the retired adapters/modal.
+
+## Review reusable layouts
+
+Figures use their own inline-size container to stack a right-hand key below
+44rem. Decision grids and action lists stack their rows below 32rem of their
+own width, including inside an otherwise wide report. Keep the documented
+`ui-report__decision-grid` and `ui-report__actions` wrappers. Two-up comparisons
+need no wrapper: they keep at most two columns, with a 16rem reading floor.
+
+Test a 280px and 320px parent inside a 1440px browser. Check that charts have
+useful drawing width, text columns remain readable, long labels wrap and all
+sources are reachable. Zero page overflow alone does not prove those things.
+Keep authored SVG labels and annotations inside the drawing's `viewBox`, or
+provide a narrow fallback with the same information. Bronto does not own chart
+geometry. Named size containment is disabled in print; review your PDF too.
+
+## Review typography overrides by role
+
+Figure captions, legends, generated labels and command groups use sans and
+sentence case. Technical log bodies and identifiers keep mono. Inline citation
+markers have a 12px floor at a default 16px root. Do not globally replace `Doto`:
+keep intentional hero/display and readout roles.
+
+1. Find explicit `font-family: var(--display)` and `var(--dot-font)` declarations
+   in your loaded consumer styles, plus old root-size and control-height rules.
+2. Classify each use: display identity, numeric readout, heading, instruction,
+   control label or metadata. Check grouped selectors individually.
+3. Remove overrides that recreate old generic styles. Use `var(--sans)` for
+   local explanatory headings and labels; keep intentional display roles.
+4. Inspect complete tasks, not just the homepage. Include setup, result,
+   filtering, error/retry, source details and an empty state where applicable.
+5. Compare long names and translated text at narrow, laptop, and desktop widths,
+   in both themes, with keyboard and touch input.
+
+Consumer CSS outside a layer takes precedence over the package's `bronto` layer.
+Updating the package alone cannot change those explicit overrides. A prepared
+patch from an older application revision must be reintegrated and checked
+against current source before it can count as migration evidence.
+
+## Verify the package and consumer together
+
+Install the packed candidate into an isolated consumer checkout before changing
+production pins. Record the exact package version, consumer revision and screens
+checked. Update the dependency and registry lock file together after publication;
+do not commit a task-local tarball path into a production lock file.
+
+Use the [composition guide](../compositions.md) for the service's local state
+scenarios, container boundaries and report reading/print checks. Existing package
+checks remain necessary; real consumer tasks provide additional evidence.
+
+## Optional discussion UI
+
+Import `@ponchia/ui/css/discussion.css` for thread lists, quotations, messages,
+and composers. The new `ui-discussion` vocabulary is additive. It carries no
+posting behavior, storage, or editor dependency; see [Discussions](../discussion.md).

package/docs/migrations/0.9-to-0.10.md

@@ -0,0 +1,47 @@
+# Upgrade from 0.9 to 0.10
+
+0.10 changes visual defaults and removes the adapter and controlled-modal
+paths deprecated in 0.7. The structured changes are in
+[`MIGRATIONS.json`](../../MIGRATIONS.json).
+
+## Update imports and modal ownership
+
+Remove imports from `@ponchia/ui/react`, `/solid`, `/qwik`, `/svelte`, and
+`/vue`. Import class names from `@ponchia/ui/classes` and initialization functions from
+`@ponchia/ui/behaviors`. Call each initialization function after the DOM root exists and
+call its cleanup on component removal. The [integration guide](https://github.com/Ponchia/bronto-ui/blob/main/docs/integration.md) links
+the host lifecycle recipes.
+
+Replace `initModal`, `ModalCloseDetail`, and `@ponchia/ui/behaviors/modal` with
+native `<dialog>` and `initDialog`. Remove `data-bronto-modal` and the
+`ui.modal({ open: true })` option. Open with `showModal()` and close with
+`close()` or the existing `data-bronto-open` / `data-bronto-close` triggers.
+Use the native `cancel` and `close` events instead of `bronto:modal:close`.
+The `ui-modal` and drawer classes remain; `.is-open` no longer opens them.
+
+## Review complete screens
+
+- The root respects the browser's default size: 16px at the usual setting.
+  The small text steps are 12px, 13px, and 14px rather than approximately
+  10.8px, 11.4px, and 12.9px.
+- Headings and controls use sans and sentence case. Keep an intentional
+  display title by applying `ui-display`, not by restyling every heading.
+- Service panels lose redundant frames, metrics stay compact, and narrow
+  navigation wraps. Remove consumer overrides that recreated those fixes.
+- Reports use larger screen prose, a reading measure, and 11pt print text.
+  Prefer a decision before navigation; a `details.ui-report__toc` can collapse
+  its contents without JavaScript. A `nav.ui-report__toc` remains expanded.
+- Inspectors adapt property rows to their own width. Splitter collapse policy
+  remains host-owned; use the [composition recipe](../compositions.md).
+
+Check your real content at narrow, laptop, and desktop sizes, in both themes,
+with keyboard and touch input. Review print output for reports. Upgrade from
+the packed candidate before changing production version pins.
+
+## Retained and new surface
+
+Core CSS, class recipes, vanilla behaviors, tokens, report and analytical
+leaves remain framework-neutral. `ui-timestrip` and `ui-severity-tone`,
+previously unreleased on main, are included. `ui-chip--dense` replaces repeated
+static-label height overrides. Specialist behavior libraries may live in a
+consumer; the core still has no runtime or peer dependencies.