@ponchia/ui 0.8.0 → 0.9.0

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

@@ -0,0 +1,216 @@
+# Migrating 0.7 to 0.8
+
+Machine-readable migration graph: [`MIGRATIONS.json`](../../MIGRATIONS.json) —
+it has no entry for this pair, because nothing was renamed or removed. Every
+class, token, attribute, and export valid in 0.7 is still valid.
+
+0.8.0 comes from auditing one real consumer's stylesheet in full. It repairs an
+accessibility floor, adds three surfaces that consumer had to hand-write, and
+changes what a colorway does. Only the last of those needs a decision from you.
+
+## 1. Decide what your skins should look like — the one breaking change
+
+**Only affects you if you set `data-bronto-skin`.** If you don't, skip to §2.
+
+Until 0.7, a colorway moved `--accent` and nothing else; the neutral canvas
+stayed grey, and ADR-0001 step 4 said so. From 0.8 a colorway also re-points ten
+canvas tokens per theme:
+
+```
+--bg  --bg-elevated  --panel  --panel-strong  --panel-soft
+--line  --line-strong  --text  --text-soft  --text-dim
+```
+
+So "Amber CRT" now actually renders amber. Nothing in your source changes and no
+checker will flag anything — the break is purely visual, which is why it is
+worth reading rather than discovering.
+
+**Contrast is not a regression risk.** Each neutral keeps the core token's OKLCH
+*lightness* exactly and moves only hue plus a small chroma, and `check-contrast`
+re-measures all 21 gated pairings per skin per theme. Status colours
+(`--success` / `--warning` / `--danger` / `--info`) are untouched by design: a
+warning must look like a warning in every skin.
+
+### If you already hand-wrote a canvas for a skin
+
+Delete it. That workaround is what motivated this change, and a hand-rolled
+version is almost certainly not contrast-gated, probably covers one theme, and
+probably misses whichever skin nobody opened.
+
+### If you want the 0.7 look back
+
+Re-declare the ten tokens after the skin import. They are ordinary custom
+properties on a `:root[data-bronto-skin=…]` selector inside `@layer bronto`, so
+un-layered app CSS wins without a specificity fight:
+
+```css
+@import '@ponchia/ui';
+@import '@ponchia/ui/css/skins.css';
+
+/* Keep the neutral canvas grey under every colorway. */
+:root[data-bronto-skin] {
+  --bg: #f4f4f2;
+  --bg-elevated: #fbfbfa;
+  --panel: #ffffff;
+  --panel-strong: #ffffff;
+  --panel-soft: #ececea;
+  --line: #d8d8d4;
+  --line-strong: #a8a8a2;
+  --text: #0a0a0a;
+  --text-soft: #353533;
+  --text-dim: #686863;
+}
+```
+
+(Those are the 0.7 light values; take the dark set from `tokens/resolved.json`
+and repeat under `:root[data-theme='dark'][data-bronto-skin]`.)
+
+## 2. Delete your tap-target workaround
+
+The coarse-pointer floor was written as a bare `2.9rem`, and `css/base.css` sets
+`html { font-size: 0.9375rem }` — so it resolved to **43.5px**, half a pixel
+under the 44 that WCAG 2.5.5 and both platform HIGs require, and less than that
+under any host with a smaller root. If you noticed and declared your own 44px
+floor, you can now drop it:
+
+```diff
+-:root { --touch-target: 44px; }
+-
+-@media (pointer: coarse) {
+-  .my-control { min-block-size: var(--touch-target); }
+-}
+```
+
+Bronto's controls float to `var(--tap-target)` — `max(44px, 2.9rem)` — on their
+own. For your *own* controls, consume the token rather than a literal:
+
+```css
+@media (pointer: coarse) {
+  .my-control {
+    min-block-size: var(--tap-target); /* 44px floor, WCAG 2.5.5 */
+  }
+}
+```
+
+`--tap-target-min` is the WCAG 2.5.8 AA 24px floor, for controls that only have
+to clear the smaller bar. Both clamp in px on purpose: **keep the clamp if you
+override them.** A bare rem is how a 44px floor quietly becomes 43.5px.
+
+## 3. Delete your safe-area declarations
+
+0.7 had no `env()` awareness at all. If you declared your own insets, drop them —
+the same four names now ship:
+
+```diff
+-:root {
+-  --safe-area-top: env(safe-area-inset-top, 0px);
+-  --safe-area-bottom: env(safe-area-inset-bottom, 0px);
+-}
+```
+
+Eight viewport-anchored surfaces now read them: the app rail and topbar, a
+sticky site header, the skip link, both toast stacks, the drawer modal, and the
+lightbox. Every rule uses `max(<authored>, var(--safe-area-*))`, so **desktop
+rendering is unchanged**.
+
+They are indirected through custom properties rather than calling `env()` at the
+point of use, which matters twice: a desktop test runner cannot emulate `env()`
+but can override a property, and a host running inside its own chrome (an
+embedded webview, a kiosk frame) can declare the real insets. Follow the same
+convention for your own floating chrome:
+
+```css
+.my-floating-bar {
+  inset-block-end: max(1rem, var(--safe-area-bottom));
+}
+```
+
+## 4. Two new opt-in ergonomics
+
+Neither is required; both replace a common workaround.
+
+**`ui-button__label`** — an icon button can keep its words for the accessible
+name and for text-based test selectors while giving back the pixels. One markup
+shape serves both forms, and no `aria-label` can drift out of sync with the
+visible wording:
+
+```html
+<button class="ui-button ui-button--icon">
+  <span class="ui-icon" style="--icon-mask: …"></span>
+  <span class="ui-button__label">Delete</span>
+</button>
+```
+
+Drop `--icon` and the same markup renders glyph + word. The slot ellipsises
+rather than wrapping, so a labelled button in a tight bar shrinks instead of
+pushing its neighbours out.
+
+**`ui-button--dense`** — for bars whose *height* is the constraint: a pane title
+bar, a packed toolbar, a table row's actions. It lowers only the visual floor,
+to `--tap-target-min`. The coarse-pointer block still floats it to the full
+`--tap-target`, so a control you shrink for a mouse is never shrunk for a
+finger. `ui.button({ size: 'dense' })` in the recipe API.
+
+## 5. Retire your own severity vocabulary
+
+Nothing forces this, but it is the reason most likely to have produced
+divergent code. Bronto shipped the tones without the **scale**, so consumers
+invented tier names — and inside one app they drift, because each surface was
+written on a different day. If you have more than one, `css/state.css` now
+publishes the canonical ladder:
+
+```
+critical › error › warning › notice › ok      (+ unknown, outside the order)
+```
+
+```js
+import { severity, SEVERITY_LEVELS } from '@ponchia/ui/classes';
+
+severity('critical');                  // { class: 'ui-severity', 'data-level': 'critical' }
+severity('warning', { part: 'row' });  // { class: 'ui-severity-row', … }
+SEVERITY_LEVELS;                       // sort and filter from this, not a local copy
+```
+
+The level travels on `data-level` — one attribute name — so a chip, a row, a
+dot, and your own element all read the same selector, and your own element can
+take `var(--severity-tone)` without copying a colour table.
+
+Map your existing tiers onto it rather than keeping both. `unknown` is the
+landing spot for anything unmeasured or stale; do **not** map it to `ok`, which
+is an assertion of health and is how a dead collector reads as a healthy system.
+
+## 6. Other surfaces you may be hand-rolling
+
+Each of these replaced something a real consumer had built locally. None is
+required.
+
+- **`.ui-pane`** — a grab header, an in-place rename input, and an actions slot
+  that scrolls rather than pushing its last control past the clipped edge. If
+  you have a node/window/panel with a draggable title bar, this is it.
+  `.ui-panel` is still just a padded card.
+- **`.ui-toolstrip--pane`** — a control bar belonging to one pane rather than to
+  the app: no frame of its own, and it refuses to wrap so a second row cannot
+  resize live content underneath. Mark the shrinking element with
+  `.ui-toolstrip__fill`.
+- **`.ui-selectionbar--anchored`** (and the same on `.ui-toolstrip`) — viewport
+  anchoring for a floating bar, safe-area aware. Use
+  `--anchor-block-start` for the bar that must *not* sit under the thumb.
+- **`.ui-empty-state__glyph/__lead/__hint`** and **`--invite`** — the three
+  parts every empty surface re-invents, plus the distinction between reporting
+  absence and offering the next action.
+
+## 7. If you read `tokens.dtcg.json`
+
+Six new scale tokens are **deliberately absent** from it, listed in the root
+extension's `omittedCssVariables`: the two tap-target floors are `max()`
+comparisons and the four safe-area insets are `env()` reads, and neither has a
+conforming DTCG shape. Emitting one arm of a clamp, or the 0px fallback of an
+`env()`, would publish a value that is wrong everywhere it matters. Read
+`tokens.json` for the authored CSS. This is the same treatment `--shadow` and
+the em trackings already get.
+
+## Nothing else changed
+
+No class was renamed or removed. No export moved. `bronto-ui-check` will not
+report anything new for a 0.7-clean consumer — which is worth stating plainly,
+because the one breaking change in this release is invisible to it.

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

@@ -0,0 +1,66 @@
+# Migrating 0.8 to 0.9
+
+Machine-readable migration graph: [`MIGRATIONS.json`](../../MIGRATIONS.json).
+
+One required change, and it is a one-word addition.
+
+## 1. Add `ui-menu--dropdown` to your menus
+
+`.ui-menu` used to weld its placement into the surface: `position: absolute`
+plus an offset relative to its trigger. That made the class unusable for a menu
+opened at a POINT — a canvas context menu, a long-press sheet — so a consumer
+with one re-declared the panel, border, radius and shadow just to get a surface.
+
+Placement is now opted into:
+
+```diff
+ <details class="ui-menu-host" data-bronto-menu>
+   <summary class="ui-button ui-button--subtle">Menu</summary>
+-  <div class="ui-menu">
++  <div class="ui-menu ui-menu--dropdown">
+```
+
+Without the modifier the surface renders in normal flow. Nothing else changed:
+`--dropdown` carries exactly the declarations that used to be unconditional.
+
+For a menu you position yourself, use `ui-menu--at-pointer` and set `left`/`top`
+(or the logical equivalents) from the host — Bronto only takes it out of flow
+and gives it the popover layer.
+
+## 2. Optional: adopt `ui-row`
+
+New in the default bundle, so it costs nothing to try. If you have a list of
+selectable lines that is not a table and not a menu — search results, an
+explorer, an outline, backlinks, commits — that is `ui-row`:
+
+```html
+<button class="ui-row ui-row--ruled" type="button" aria-selected="true">
+  <span class="ui-row__mark" aria-hidden="true">◆</span>
+  <span class="ui-row__title">apps/server/src/collab/room.ts</span>
+  <span class="ui-row__meta">4m</span>
+</button>
+```
+
+`__title` truncates; `__meta` does not. Selection reads `aria-selected` or
+`aria-current`, so the visual state cannot disagree with what a screen reader
+announces. Rows carrying a severity want `ui-severity-row` instead.
+
+`ui-menu__item` composes it, so menu items and rows cannot drift apart.
+
+## 3. Know what `data-density` actually does
+
+No change in behaviour — a correction to what the docs claimed. The preset
+re-points the `--space-*` scale, so it moves the ~40 components whose padding is
+expressed in that scale and **none** of the rest. `ui-alert` and
+`ui-menu__item` are the two most likely to surprise you.
+
+The others carry tuned pairs like `0.5rem 0.55rem` that a seven-step scale
+cannot express; flattening them would change the default rendering everyone
+uses. If you need a denser variant of a component that does not respond,
+override its padding — and if you do that repeatedly for the same component,
+report it, because that is evidence for a real `--dense` modifier.
+
+## Nothing else changed
+
+No class was removed or renamed. `bronto-ui-check` will not report anything new
+for a 0.8-clean consumer.

package/docs/package-contract.md

@@ -49,6 +49,7 @@ semantic versioning contract for the surfaces listed here.
 | `./css/skins.css` | `./dist/css/skins.css` | Opt-in layered CSS leaf | Stable additive | Generated layered direct-import leaf. Opt-in and not included in dist/bronto.css. |
 | `./css/dataviz.css` | `./dist/css/dataviz.css` | Opt-in layered CSS leaf | Stable additive | Generated layered direct-import leaf. Opt-in and not included in dist/bronto.css. |
 | `./css/report.css` | `./dist/css/report.css` | Opt-in layered CSS leaf | Stable additive | Generated layered direct-import leaf. Opt-in and not included in dist/bronto.css. |
+| `./css/row.css` | `./dist/css/row.css` | Bundled layered CSS leaf | Stable additive | Generated layered direct-import leaf. Also included in dist/bronto.css. |
 | `./css/figure.css` | `./dist/css/figure.css` | Opt-in layered CSS leaf | Stable additive | Generated layered direct-import leaf. Opt-in and not included in dist/bronto.css. |
 | `./css/annotations.css` | `./dist/css/annotations.css` | Opt-in layered CSS leaf | Stable additive | Generated layered direct-import leaf. Opt-in and not included in dist/bronto.css. |
 | `./css/legend.css` | `./dist/css/legend.css` | Opt-in layered CSS leaf | Stable additive | Generated layered direct-import leaf. Opt-in and not included in dist/bronto.css. |
@@ -94,6 +95,7 @@ semantic versioning contract for the surfaces listed here.
 | `./css/unlayered/skins.css` | `./css/skins.css` | Unlayered CSS leaf | Stable path | Raw authored CSS leaf for consumers that deliberately opt out of @layer bronto on that leaf. |
 | `./css/unlayered/dataviz.css` | `./css/dataviz.css` | Unlayered CSS leaf | Stable path | Raw authored CSS leaf for consumers that deliberately opt out of @layer bronto on that leaf. |
 | `./css/unlayered/report.css` | `./css/report.css` | Unlayered CSS leaf | Stable path | Raw authored CSS leaf for consumers that deliberately opt out of @layer bronto on that leaf. |
+| `./css/unlayered/row.css` | `./css/row.css` | Unlayered CSS leaf | Stable path | Raw authored CSS leaf for consumers that deliberately opt out of @layer bronto on that leaf. |
 | `./css/unlayered/figure.css` | `./css/figure.css` | Unlayered CSS leaf | Stable path | Raw authored CSS leaf for consumers that deliberately opt out of @layer bronto on that leaf. |
 | `./css/unlayered/annotations.css` | `./css/annotations.css` | Unlayered CSS leaf | Stable path | Raw authored CSS leaf for consumers that deliberately opt out of @layer bronto on that leaf. |
 | `./css/unlayered/legend.css` | `./css/legend.css` | Unlayered CSS leaf | Stable path | Raw authored CSS leaf for consumers that deliberately opt out of @layer bronto on that leaf. |
@@ -299,6 +301,8 @@ always includes `package.json`, `README.md`, `LICENSE`, and
 | `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/migrations/0.7-to-0.8.md` | Shipped documentation | Curated Markdown reading asset shipped in the npm tarball. |
+| `docs/migrations/0.8-to-0.9.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. |
@@ -315,7 +319,7 @@ result. The listed gates are part of `npm run check`.
 | Package manifest | `package.json` | docs/package-contract.md | `npm run package-contract:build` | check:fresh; check:exports; check:pack; check:consumer-surface; check:consumer-types; check:publint; check:attw | The complete export/file matrix in this document is generated from the manifest; packed tarball imports, concrete file resolution, and package-level type resolution are smoke-tested in clean consumers. |
 | Token model | `tokens/index.js` | css/tokens.css; tokens/index.json; tokens/tokens.dtcg.json; tokens/resolved.json; tokens/figma.variables.json; tokens/index.d.ts | `npm run tokens:css:build; tokens:build; dtcg:build; resolved:build; figma:variables:build; dts:build` | check:fresh; check:contrast | Token names/roles are public. Resolved and Figma handoff values are visual tuning before 1.0. |
 | Class registry | `classes/index.js plus css/*.css selectors` | classes/classes.json; classes/index.d.ts; classes/vscode.css-custom-data.json; docs/reference.md | `npm run classes:json:build; dts:build; vscode:build; reference:build` | check:fresh; check:classes; check:contract | The typed registry, JSON vocabulary, and generated reference stay aligned with real selectors. |
-| Authored CSS graph | `css/core.css plus css/*.css leaves` | dist/bronto.css; dist/css/*.css (46 layered outputs) | `npm run dist:build` | check:dist; check:exports; check:component-matrix | Default bundle and direct layered leaf imports are generated from authored CSS, size-gated, and coverage-owned as foundation or component leaves. |
+| Authored CSS graph | `css/core.css plus css/*.css leaves` | dist/bronto.css; dist/css/*.css (47 layered outputs) | `npm run dist:build` | check:dist; check:exports; check:component-matrix | Default bundle and direct layered leaf imports are generated from authored CSS, size-gated, and coverage-owned as foundation or component leaves. |
 | JSDoc-authored public JS | `behaviors/; annotations/; connectors/; react/; solid/; qwik/; svelte/; vue/` | adjacent *.d.ts and *.d.ts.map files | `npm run dts:emit` | check:dts-emit; check:types; check:consumer-surface; check:consumer-types; check:behavior-matrix; check:attw; check:publint | Declarations are emitted from the shipped JS, package subpath imports are compiled from a packed clean consumer, and public behavior exports are docs/unit/browser owned. |
 | Glyph registry | `glyphs/glyphs.js` | glyphs/glyphs.d.ts | `npm run glyphs:build` | check:glyphs; check:unit | Glyph names and render options are public. The registry stays sorted and type-covered. |
 | Display colorways | `tokens/skins.js` | css/skins.css; tokens/skins.d.ts | `npm run skins:build` | check:skins; check:contrast | Skins are opt-in root-level choices and never part of dist/bronto.css. |

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).
 
-- 669 classes across 183 component groups
+- 677 classes across 184 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`,
@@ -874,6 +874,8 @@ each one matches a real selector in the stylesheet.
 | `cls.menuItem` | `ui-menu__item` | part |
 | `cls.menuLabel` | `ui-menu__label` | part |
 | `cls.menuSep` | `ui-menu__sep` | part |
+| `cls.menuAtPointer` | `ui-menu--at-pointer` | modifier |
+| `cls.menuDropdown` | `ui-menu--dropdown` | modifier |
 
 ### `.ui-menu-host`
 
@@ -1117,6 +1119,17 @@ each one matches a real selector in the stylesheet.
 | --- | --- | --- |
 | `cls.reveal` | `ui-reveal` | base |
 
+### `.ui-row`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.row` | `ui-row` | base |
+| `cls.rowMark` | `ui-row__mark` | part |
+| `cls.rowMeta` | `ui-row__meta` | part |
+| `cls.rowTitle` | `ui-row__title` | part |
+| `cls.rowRuled` | `ui-row--ruled` | modifier |
+| `cls.rowStacked` | `ui-row--stacked` | modifier |
+
 ### `.ui-screen-only`
 
 | Registry key | Class | Kind |

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.8.0/dist/bronto.css" />
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.8.0/dist/css/report-kit.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.9.0/dist/bronto.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.9.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.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" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.9.0/dist/bronto.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.9.0/dist/css/report.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.9.0/dist/css/dataviz.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.9.0/dist/css/annotations.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.9.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.8.0/schemas/report-claims.v1.schema.json",
+  "$schema": "https://cdn.jsdelivr.net/npm/@ponchia/ui@0.9.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.8.x`) are
+patches are non-breaking. In practical terms: **PATCH releases (`0.9.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
@@ -140,6 +140,7 @@ current public-surface matrix and the release policy above still applies.
 | Connectors (`@ponchia/ui/connectors`, `css/connectors.css`, `.ui-connector*`, `initConnectors`) | Stable additive | Connector class names, the `data-bronto-connector` attribute contract, geometry helper function names, and recipe options are public. Helper internals/heuristics may tune before 1.0. Opt-in, not in the default bundle. |
 | Spotlight (`css/spotlight.css`, `.ui-spotlight*`, `.ui-tour-note*`, `initSpotlight`) | Stable additive | Spotlight/tour-note class names, the `--spot-*` custom-property contract, and the `data-bronto-spotlight`/`data-target` attributes are public. Opt-in, not in the default bundle. Not a tour engine. |
 | Crosshair (`css/crosshair.css`, `.ui-crosshair*`, `.ui-readout`, `initCrosshair`) | Stable additive | Crosshair/readout class names, the `--crosshair-x/y` properties, the `data-bronto-crosshair` attribute, and the `bronto:crosshair:move`/`:leave` event contract are public. Opt-in. Reports pointer position only — no data mapping. |
+| Rows (`css/row.css`, `.ui-row*`) | Stable additive | Class names, the `__title` / `__meta` / `__mark` parts, the `--stacked` / `--ruled` modifiers, and the selection contract are public: `aria-selected`, `aria-current` and `.is-selected` all paint the selected state, so the visual state cannot disagree with the announced one. `__title` is the part that truncates and `__meta` is the part that does not — that asymmetry is the contract, not a detail. **In the default bundle**, unusually for a new surface: `.ui-menu__item` composes it, so a core component depends on it. Also exported standalone, which is why it appears here, but it is NOT opt-in. |
 | Selection states (`css/selection.css`, `.ui-sel*`) | Stable additive | The `.ui-sel`/`--on`/`--off`/`--maybe` emphasis classes and recipe options are public. Opt-in, cross-cutting. The host owns selection logic; Bronto only styles the states. |
 | Analytical roll-up (`css/analytical.css`) | Stable additive | A convenience `@import` of the nine analytical leaves (figure, annotations, legend, marks, connectors, spotlight, crosshair, selection, highlights). The set of leaves it bundles may grow additively; each leaf also stays individually exported. Opt-in, not in the default bundle. |
 | Sources / provenance (`css/sources.css`, `.ui-citation*`, `.ui-source-card*`, `.ui-source-list*`, `.ui-provenance*`, `.ui-src--*`, `initSources`) | Stable additive | Citation/source/provenance class names, the cross-cutting `.ui-src--*` trust-state modifiers (always paired with an author label), the optional `data-bronto-sources` / `data-bronto-source-ref` behavior contract, `bronto:source:focus`, and the `ui.citation`/`ui.source`/`ui.provenance` recipes + `cls.sourceList` are public. Opt-in, not in the default bundle. |

package/docs/theming.md

@@ -130,6 +130,22 @@ you change CSS `--accent` later.
 - **Spacing** — override the `--space-2xs … --space-2xl` scale, or use a
   preset: `data-density="compact"` / `data-density="comfortable"` on any
   element (defaults to the middle scale).
+
+  **Read this before relying on the preset.** It re-points the `--space-*`
+  scale, and only components whose padding is *expressed in that scale* move
+  with it — around 40 of them, including `ui-panel`, `ui-modal__body`,
+  `ui-evidence-item`, `ui-claim`, `ui-job`, `ui-code__body` and the report
+  surfaces. The rest carry tuned padding pairs like `0.5rem 0.55rem`, which the
+  seven-step scale cannot express, so **they do not respond at all** —
+  `ui-alert` and `ui-menu__item` are the two most likely to surprise you.
+
+  That is a real limit, not an oversight to work around: flattening a tuned pair
+  onto the nearest scale step would change how those components look at the
+  default density, which is the one nearly everyone uses. If you need a denser
+  variant of a component that does not respond, override its padding directly —
+  and if you find yourself doing that repeatedly for the same component, that is
+  worth reporting, because it is evidence for a real `--dense` modifier rather
+  than a preset that half-works.
 - **Dark surface** — the dark theme's base is a deliberately *elevated*
   near-black (`--bg: #121212`) for readability: pure black + bright text
   causes halation, and near-black-on-black surface steps are imperceptible.

package/docs/usage.md

@@ -186,6 +186,48 @@ a `.ui-legend` key, and fallback data. Full LLM/static report cookbook:
   spinner is CSS. This is the ARIA-driven contract — see reference.md
   → "Composition & state".
 
+## Rows: `ui-row` vs table vs menu item
+
+Three shapes look alike and are not interchangeable:
+
+- **`ui-table`** when the data has columns and a header. A table promises that
+  the third cell means the same thing on every line.
+- **`ui-menu__item`** when the list is a menu: it dismisses on choice, and it is
+  reached through `ui-menu-host`.
+- **`ui-row`** for everything else — a search result, a file in an explorer, an
+  outline entry, a backlink, a commit. A full-width clickable line that
+  *persists*.
+
+```html
+<button class="ui-row ui-row--ruled" type="button" aria-current="true">
+  <span class="ui-row__mark" aria-hidden="true">◆</span>
+  <span class="ui-row__title">apps/server/src/collab/room.ts</span>
+  <span class="ui-row__meta">4m</span>
+</button>
+```
+
+The one rule worth knowing: **`__title` is what truncates.** It takes the slack
+and gives it back first; `__meta` never shrinks, because a half-rendered number
+is worse than no number.
+
+**Pick the right attribute, and it is probably not `aria-selected`.** That one
+is only valid on a row whose role accepts it — `option` inside a `listbox`, or
+`row` / `tab` / `gridcell` / `treeitem`. On a bare `<button>` it is invalid ARIA
+and axe rates it *critical*; this project shipped that mistake in its own demo
+and the a11y gate caught it before release.
+
+- `aria-current="true"` — the row is the current one. The common case, and valid
+  on any element.
+- `aria-selected="true"` — only when the row really is an `option` in a
+  `listbox`, or another role that accepts it.
+- `.is-selected` — when neither fits.
+
+All three paint the same, so the visual state cannot disagree with the announced
+one. Rows carrying a severity should use `ui-severity-row` (`css/state.css`)
+instead, which adds the tone gutter.
+
+`ui-menu__item` composes `ui-row`, which is why they cannot drift.
+
 ## Empty state vs invite
 
 Both use `ui-empty-state`, and the slots are the same three parts — a quiet

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.8.0/dist/css/<leaf>.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.9.0/dist/css/<leaf>.css" />
 ```
 
 The flattened default bundle is `dist/bronto.css` (bundler shorthand

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@ponchia/ui",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "type": "module",
-  "description": "CSS-first identity and UI layer for services, tools, sites, and reports — works in HTML, every framework, and PDF, no component runtime. Shared app shell, forms, tables, workflow chrome, plus opt-in analytical/report primitives. Monochrome with one rationed accent. Zero runtime dependencies.",
+  "description": "CSS-first identity and UI layer for services, tools, sites, and reports \u2014 works in HTML, every framework, and PDF, no component runtime. Shared app shell, forms, tables, workflow chrome, plus opt-in analytical/report primitives. Monochrome with one rationed accent. Zero runtime dependencies.",
   "keywords": [
     "css",
     "ui",
@@ -113,6 +113,8 @@
     "docs/migrations/0.4-to-0.5.md",
     "docs/migrations/0.5-to-0.6.md",
     "docs/migrations/0.6-to-0.7.md",
+    "docs/migrations/0.7-to-0.8.md",
+    "docs/migrations/0.8-to-0.9.md",
     "docs/adr/0001-color-system.md",
     "docs/adr/0002-scope-and-2026-baseline.md",
     "docs/adr/0003-theme-model.md",
@@ -213,24 +215,24 @@
     "prepublishOnly": "npm run build:artifacts && npm run check"
   },
   "devDependencies": {
-    "@arethetypeswrong/cli": "^0.18.4",
+    "@arethetypeswrong/cli": "^0.18.5",
     "@axe-core/playwright": "^4.11.3",
     "@builder.io/qwik": "^1.20.0",
     "@playwright/test": "1.60.0",
     "github-actionlint": "^1.7.12",
-    "jsdom": "^29.1.1",
-    "knip": "^6.23.0",
-    "pdfjs-dist": "^6.1.200",
-    "prettier": "^3.9.1",
-    "publint": "^0.3.21",
-    "react": "^19.2.7",
-    "react-dom": "^19.2.7",
-    "solid-js": "^1.9.13",
-    "stylelint": "^17.14.0",
+    "jsdom": "^30.0.1",
+    "knip": "^6.32.1",
+    "pdfjs-dist": "^6.2.108",
+    "prettier": "^3.9.6",
+    "publint": "^0.3.23",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8",
+    "solid-js": "^1.9.14",
+    "stylelint": "^17.14.1",
     "stylelint-config-standard": "^40.0.0",
     "stylelint-use-logical": "^2.1.3",
     "typescript": "^6.0.3",
-    "vega": "^6.2.0",
+    "vega": "^6.3.1",
     "vega-lite": "^6.4.3"
   },
   "peerDependencies": {
@@ -278,6 +280,7 @@
     "./css/skins.css": "./dist/css/skins.css",
     "./css/dataviz.css": "./dist/css/dataviz.css",
     "./css/report.css": "./dist/css/report.css",
+    "./css/row.css": "./dist/css/row.css",
     "./css/figure.css": "./dist/css/figure.css",
     "./css/annotations.css": "./dist/css/annotations.css",
     "./css/legend.css": "./dist/css/legend.css",
@@ -323,6 +326,7 @@
     "./css/unlayered/skins.css": "./css/skins.css",
     "./css/unlayered/dataviz.css": "./css/dataviz.css",
     "./css/unlayered/report.css": "./css/report.css",
+    "./css/unlayered/row.css": "./css/row.css",
     "./css/unlayered/figure.css": "./css/figure.css",
     "./css/unlayered/annotations.css": "./css/annotations.css",
     "./css/unlayered/legend.css": "./css/legend.css",