npm - @ponchia/ui - Versions diffs - 0.5.0 → 0.6.3 - Mend

@ponchia/ui 0.5.0 → 0.6.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (196) hide show

package/CHANGELOG.md +386 -4
package/MIGRATIONS.json +14 -0
package/README.md +29 -6
package/annotations/index.d.ts +398 -276
package/annotations/index.d.ts.map +1 -0
package/annotations/index.js +350 -77
package/behaviors/carousel.d.ts +28 -0
package/behaviors/carousel.d.ts.map +1 -0
package/behaviors/carousel.js +20 -16
package/behaviors/combobox.d.ts +40 -0
package/behaviors/combobox.d.ts.map +1 -0
package/behaviors/combobox.js +111 -29
package/behaviors/command.d.ts +41 -0
package/behaviors/command.d.ts.map +1 -0
package/behaviors/command.js +27 -15
package/behaviors/connectors.d.ts +17 -0
package/behaviors/connectors.d.ts.map +1 -0
package/behaviors/connectors.js +7 -5
package/behaviors/crosshair.d.ts +42 -0
package/behaviors/crosshair.d.ts.map +1 -0
package/behaviors/crosshair.js +23 -6
package/behaviors/dialog.d.ts +20 -0
package/behaviors/dialog.d.ts.map +1 -0
package/behaviors/dialog.js +6 -2
package/behaviors/disclosure.d.ts +10 -0
package/behaviors/disclosure.d.ts.map +1 -0
package/behaviors/disclosure.js +6 -2
package/behaviors/dismissible.d.ts +10 -0
package/behaviors/dismissible.d.ts.map +1 -0
package/behaviors/dismissible.js +6 -2
package/behaviors/forms.d.ts +27 -0
package/behaviors/forms.d.ts.map +1 -0
package/behaviors/forms.js +54 -13
package/behaviors/glyph.d.ts +14 -0
package/behaviors/glyph.d.ts.map +1 -0
package/behaviors/glyph.js +28 -5
package/behaviors/index.d.ts +31 -237
package/behaviors/index.d.ts.map +1 -0
package/behaviors/index.js +17 -0
package/behaviors/inert.d.ts +20 -0
package/behaviors/inert.d.ts.map +1 -0
package/behaviors/inert.js +46 -0
package/behaviors/internal.d.ts +25 -0
package/behaviors/internal.d.ts.map +1 -0
package/behaviors/internal.js +77 -1
package/behaviors/legend.d.ts +35 -0
package/behaviors/legend.d.ts.map +1 -0
package/behaviors/legend.js +32 -2
package/behaviors/menu.d.ts +16 -0
package/behaviors/menu.d.ts.map +1 -0
package/behaviors/menu.js +6 -2
package/behaviors/modal.d.ts +41 -0
package/behaviors/modal.d.ts.map +1 -0
package/behaviors/modal.js +124 -0
package/behaviors/popover.d.ts +28 -0
package/behaviors/popover.d.ts.map +1 -0
package/behaviors/popover.js +78 -7
package/behaviors/spotlight.d.ts +17 -0
package/behaviors/spotlight.d.ts.map +1 -0
package/behaviors/spotlight.js +7 -5
package/behaviors/table.d.ts +36 -0
package/behaviors/table.d.ts.map +1 -0
package/behaviors/table.js +84 -17
package/behaviors/tabs.d.ts +20 -0
package/behaviors/tabs.d.ts.map +1 -0
package/behaviors/tabs.js +17 -14
package/behaviors/theme.d.ts +54 -0
package/behaviors/theme.d.ts.map +1 -0
package/behaviors/theme.js +22 -3
package/behaviors/toast.d.ts +49 -0
package/behaviors/toast.d.ts.map +1 -0
package/behaviors/toast.js +47 -3
package/classes/classes.json +2527 -0
package/classes/index.d.ts +134 -15
package/classes/index.js +280 -80
package/classes/vscode.css-custom-data.json +12 -0
package/connectors/index.d.ts +201 -69
package/connectors/index.d.ts.map +1 -0
package/connectors/index.js +142 -25
package/css/app.css +69 -13
package/css/base.css +15 -10
package/css/bullet.css +108 -0
package/css/code.css +98 -0
package/css/connectors.css +17 -0
package/css/content.css +22 -3
package/css/crosshair.css +7 -7
package/css/dataviz.css +5 -1
package/css/diff.css +153 -0
package/css/disclosure.css +53 -7
package/css/dots.css +94 -7
package/css/feedback.css +97 -7
package/css/forms.css +113 -4
package/css/legend.css +16 -9
package/css/marks.css +38 -8
package/css/motion.css +98 -53
package/css/navigation.css +7 -0
package/css/overlay.css +90 -3
package/css/primitives.css +158 -13
package/css/report.css +73 -56
package/css/sidenote.css +67 -0
package/css/site.css +16 -2
package/css/sources.css +43 -1
package/css/spark.css +62 -0
package/css/spotlight.css +1 -1
package/css/table.css +9 -2
package/css/term.css +110 -0
package/css/textref.css +63 -0
package/css/toc.css +91 -0
package/css/tokens.css +49 -1
package/css/tree.css +134 -0
package/css/workbench.css +1 -1
package/dist/bronto.css +1 -1
package/dist/css/analytical.css +1 -1
package/dist/css/app.css +1 -1
package/dist/css/base.css +1 -1
package/dist/css/bullet.css +1 -0
package/dist/css/code.css +1 -0
package/dist/css/connectors.css +1 -1
package/dist/css/content.css +1 -1
package/dist/css/crosshair.css +1 -1
package/dist/css/diff.css +1 -0
package/dist/css/disclosure.css +1 -1
package/dist/css/dots.css +1 -1
package/dist/css/feedback.css +1 -1
package/dist/css/forms.css +1 -1
package/dist/css/legend.css +1 -1
package/dist/css/marks.css +1 -1
package/dist/css/motion.css +1 -1
package/dist/css/navigation.css +1 -1
package/dist/css/overlay.css +1 -1
package/dist/css/primitives.css +1 -1
package/dist/css/report.css +1 -1
package/dist/css/sidenote.css +1 -0
package/dist/css/site.css +1 -1
package/dist/css/sources.css +1 -1
package/dist/css/spark.css +1 -0
package/dist/css/spotlight.css +1 -1
package/dist/css/table.css +1 -1
package/dist/css/term.css +1 -0
package/dist/css/textref.css +1 -0
package/dist/css/toc.css +1 -0
package/dist/css/tokens.css +1 -1
package/dist/css/tree.css +1 -0
package/dist/css/workbench.css +1 -1
package/docs/adr/0003-theme-model.md +1 -1
package/docs/annotations.md +133 -14
package/docs/architecture.md +49 -6
package/docs/bullet.md +78 -0
package/docs/code.md +76 -0
package/docs/contrast.md +116 -92
package/docs/d2.md +196 -0
package/docs/diff.md +146 -0
package/docs/legends.md +23 -3
package/docs/marks.md +9 -2
package/docs/mermaid.md +169 -0
package/docs/reference.md +201 -26
package/docs/reporting.md +416 -57
package/docs/sidenote.md +64 -0
package/docs/sources.md +27 -0
package/docs/spark.md +78 -0
package/docs/stability.md +10 -2
package/docs/term.md +81 -0
package/docs/textref.md +78 -0
package/docs/theming.md +44 -5
package/docs/toc.md +83 -0
package/docs/tree.md +74 -0
package/docs/usage.md +354 -16
package/docs/vega.md +244 -0
package/docs/workbench.md +7 -1
package/glyphs/glyphs.js +13 -5
package/llms.txt +285 -14
package/package.json +95 -17
package/qwik/index.d.ts +44 -59
package/qwik/index.d.ts.map +1 -0
package/qwik/index.js +65 -3
package/react/index.d.ts +41 -61
package/react/index.d.ts.map +1 -0
package/react/index.js +63 -3
package/solid/index.d.ts +68 -61
package/solid/index.d.ts.map +1 -0
package/solid/index.js +66 -3
package/tokens/d2.d.ts +38 -0
package/tokens/d2.js +71 -0
package/tokens/d2.json +43 -0
package/tokens/index.d.ts +5 -5
package/tokens/index.js +15 -1
package/tokens/index.json +9 -0
package/tokens/mermaid.d.ts +23 -0
package/tokens/mermaid.js +181 -0
package/tokens/mermaid.json +163 -0
package/tokens/resolved.json +45 -1
package/tokens/skins.js +3 -2
package/tokens/tokens.dtcg.json +26 -0
package/tokens/vega.d.ts +34 -0
package/tokens/vega.js +155 -0
package/tokens/vega.json +179 -0

package/docs/usage.md CHANGED Viewed

@@ -26,6 +26,14 @@ into a preset on `<html>` or any subtree:
 Scope it, don't globalize blindly: a dashboard with one marketing-style
 hero can set `compact` on `<html>` and `comfortable` on the hero section.
+> **`data-density` is the global preset; per-component density verbs differ by
+> family.** Some components carry their own local density modifier, and the verb
+> is **not** uniform: it's `--dense` on `ui-table`/`ui-dotgrid` but `--compact`
+> on `ui-prose`/`ui-legend`/`ui-report`. So `ui-prose--dense` and
+> `ui-table--compact` both no-op. When in doubt, reach for the global
+> `data-density` preset; use the local modifier only where it exists (check the
+> base's `modifiers` in classes.json).
 ## Badge vs chip vs status dot
 All three are small. They are **not** interchangeable:
@@ -35,9 +43,38 @@ All three are small. They are **not** interchangeable:
 | **status dot** | a single piece of state on something else (row online, build ok). Smallest possible signal; pair with text for a11y, never color-only. |
 | **badge**      | a label *classifying* the thing it sits on (count, tone, "BETA"). Static, not actionable. `ui.badge({ tone })`. |
 | **chip**       | a discrete, often removable/selectable token the user manipulated (a filter, a tag input value). Interactive affordance implied. |
+| **tag**        | a static keyword/category label (`ui.tag`), like a badge but reads as a non-interactive tag. Use `chip` for anything the user selects/removes; `tag` for a fixed label. |
 Rule of thumb: state → dot, classification → badge, user-controlled value
-→ chip.
+→ chip, fixed keyword → tag. (`ui-property` is a **workbench** primitive — a
+key/value spec row scoped to `@ponchia/ui/css/workbench.css`, not a general
+content label; don't reach for it to tag prose.)
+**Tone vocabulary varies by family — by design.** Colour is rationed, so not
+every component carries every tone. The status tones
+(`--success`/`--warning`/`--danger`) plus `--info` ride the status families —
+`ui-alert`, `ui-toast`, `ui-meter`, `ui-dot`, and `ui-badge` all carry `--info`.
+The neutral `--muted` is **not** a status tone: it rides several *neutral*
+bases (`ui-badge`, `ui-num`, `ui-eyebrow`, `ui-mark`, `ui-annotation`,
+`ui-connector`, `ui-crosshair`) but is deliberately absent from the status
+families `ui-dot`/`ui-alert`/`ui-toast`/`ui-meter`. Because the CSS is a
+plain class list, a hand-written unknown modifier (e.g. `ui-dot--muted`,
+`ui-meter--muted`) **silently no-ops** — CSS can't warn. The `ui.*` builders are
+safer on both ends: TypeScript rejects an out-of-set tone at author time, and at
+runtime they `console.warn` (then drop the tone) so a JS caller sees the mistake
+rather than shipping a bare, untoned element. The authoritative
+per-component tone list is each base's `modifiers` array in
+[`@ponchia/ui/classes.json`](../classes/classes.json) — read it rather than
+extrapolating a tone you saw on one component onto another.
+**Tone is a colour channel, so it collapses under Windows High-Contrast Mode.**
+A `ui-badge--success` and a `ui-badge--danger` render identically once HCM
+remaps colours (the tinted background + tone border are flattened to one system
+colour). Status dots and the meter fill re-assert a distinct system colour, but
+the badge/chip/tag tints cannot carry five differentiable tones — so treat badge
+tone as **decorative emphasis** and make sure the badge's text label carries the
+status word ("Failed", not a bare red pill). Same WCAG 1.4.1 reasoning the dots
+follow.
 ## Numbers: `ui-num` vs the table state classes
@@ -49,6 +86,21 @@ Rule of thumb: state → dot, classification → badge, user-controlled value
   freed from the table. Do not hand-roll right-align + `text-green`;
   that's the duplication `ui-num` exists to kill.
+**The positive/negative vocabulary is spelled three ways — match the mechanism
+to the host, they are not interchangeable:**
+| Where | Positive / negative | Kind |
+| --- | --- | --- |
+| `ui-num` primitive (anywhere) | `ui-num--pos` / `ui-num--neg` (`ui.num({ tone: 'pos' })`) | **modifier** |
+| Inside `.ui-table` | `is-pos` / `is-neg` | **state hook** (table-scoped) |
+| `ui-delta` trend | `ui-delta--up` / `ui-delta--down` (`ui.delta({ dir })`) | **direction** |
+They share the same tone tokens but **don't cross over**: `ui-num is-pos`
+no-ops (the `is-pos` rule is scoped to table cells), and `ui-delta--pos` doesn't
+exist. Use the modifier on `ui-num`, the `is-*` state inside a table, and
+`--up`/`--down` on `ui-delta` (which also flips with `ui.delta({ invert })` when
+up is the *bad* direction — latency, error rate, cost).
 ## Prose vs primitives, and prose inside a card
 - `ui-prose` styles **raw, unclassed semantic HTML** (MDX / CMS / LLM
@@ -60,6 +112,42 @@ Rule of thumb: state → dot, classification → badge, user-controlled value
   `.ui-card` itself, so card padding/border stays the card's and prose
   rhythm stays the content's. One responsibility per element.
+## Centred width: `ui-center` vs `ui-container`
+Both cap a centred column, but they are **different primitives with different
+box models** — pick by intent:
+- **`ui-center`** — a *reading measure*. `--center-max` is the **inner** content
+  width (content-box); the `--center-gutter` padding adds *outside* it. Use it to
+  hold prose/body to a comfortable line length.
+- **`ui-container`** — a *page frame*. `--container` (/`--container-narrow`
+  /`--container-wide`) is the **total** max width (border-box). Use it as the
+  outer wrapper that aligns a page's sections to a shared edge.
+Rule of thumb: measure of text → `ui-center`; page-level frame → `ui-container`.
+Don't nest one inside the other expecting the caps to compose — they measure
+different boxes.
+## Container queries: `ui-cq`
+`ui-cq` is the one primitive that changes how *other* primitives respond. Add it
+to a wrapper and its descendants adapt to **that box's** inline size, not the
+viewport — so the same `ui-grid` / `ui-statgrid` / `ui-app-metrics` collapses to
+one column inside a slim panel even when the window is wide (island-safe; it
+nests). Two thresholds are built in: `ui-grid` drops to a single column at
+**34rem** and `ui-statgrid`/`ui-app-metrics` at **30rem**, measured on the `ui-cq`
+box. Note `rem` in a container query resolves against the **root** font size, not
+16px — at Bronto's 15px root that's ≈**510px** and ≈**450px**, ~6% tighter than a
+16px mental model. And be aware `ui-grid` already collapses on its own via an
+intrinsic `auto-fit` minmax, so `ui-cq` barely changes it — the primitive that
+genuinely *needs* `ui-cq` to collapse by container (not viewport) is
+`ui-statgrid`/`ui-app-metrics`. The container is named `bronto` (hardcoded — there
+is no `--cq-name` knob; an author-set one is ignored), so an outer query never
+accidentally matches an inner grid. `ui-cq` is inert until applied, so adding it
+never shifts an existing layout. Reach for it whenever a layout must respond to
+its container (a resizable pane, a sidebar widget, an embedded card) rather than
+the page.
 ## Static reports
 Use the opt-in `@ponchia/ui/css/report.css` layer for static, PDF-first
@@ -70,10 +158,11 @@ for narrative body content you do not fully control.
 Do not turn every report block into a card. Use `ui-report__summary`,
 `ui-report__finding`, and `ui-report__evidence` for document structure; use
-`ui-card` only when the block is genuinely a repeated card item. Charts use
-the report `ui-chart*` wrappers plus the opt-in data-viz tokens; simple static
-bar charts can use `ui-chart__plot`, `ui-chart__bar`, and `ui-chart__fill`.
-Always include a caption and fallback data. Full LLM/static report cookbook:
+`ui-card` only when the block is genuinely a repeated card item. bronto ships
+**no chart component**: for a chart, theme Vega-Lite (`@ponchia/ui/vega`, see
+[vega.md](vega.md)) or hand-author a token-themed inline SVG painted from the
+data-viz palette tokens. Always wrap it in a `ui-report__figure` with a caption,
+a `.ui-legend` key, and fallback data. Full LLM/static report cookbook:
 [reporting.md](reporting.md).
 ## Buttons: variant and size
@@ -102,6 +191,13 @@ destructive action).
 | toast    | transient, out-of-flow, system-initiated. Danger toasts route to an assertive live region; everything else polite. |
 | tooltip  | supplemental, hover/focus, never essential info (it's not announced reliably; don't hide required content in it). |
+The CSS `ui-tooltip` is hover/focus-only and CSS can't wire it to assistive
+tech for you — associate the bubble with its trigger yourself, or it conveys
+nothing to a screen reader: give `.ui-tooltip__bubble` an `id`, point the
+trigger's `aria-describedby` at it, and keep the bubble `role="tooltip"`. For a
+tooltip that must stay visible near a viewport edge or inside a scroll
+container, use `initPopover` (a real focus-managed panel) instead.
 ## Meter vs progress
 Both are a thin horizontal bar; they mean different things.
@@ -110,10 +206,22 @@ Both are a thin horizontal bar; they mean different things.
   indeterminate (`ui-progress--indeterminate`). The fill is always accent.
 - **`ui-meter`** — a *measured static value*: coverage, disk, capacity, a
   KPI against a target. Never indeterminate. Tone the fill by threshold
-  (`ui.meter({ tone })` → accent/success/warning/danger); the unset
-  default is neutral. Drive the width with the shared `--value` knob
-  (`style="--value: 72"`, 0–100) and author `role="meter"` +
-  `aria-valuenow/min/max` for AT.
+  (`ui.meter({ tone })` → accent/success/warning/danger/info); the unset
+  default is neutral. Drive the width with the shared `--value` knob — a
+  **unitless number 0–100** (`style="--value: 72"`, *not* `72%`: a `%` is
+  invalid against the registered `<number>` type and the fill drops to empty).
+  The class string paints a 0-width, unannounced bar on its own, so set the
+  value **and** its ARIA together with `attrs.meter(72)` (or `attrs.progress`)
+  from `@ponchia/ui/classes` — it returns `role="meter"` +
+  `aria-valuenow/min/max` + the `--value` style, normalized to your
+  `{ min, max }`. Spread it: `<div class={ui.meter({ tone })} {...attrs.meter(72)}>`.
+  **Indeterminate progress** is the one exception: call `attrs.progress()` with
+  **no argument**. ARIA requires `aria-valuenow` be *omitted* for an indeterminate
+  bar — emitting `0` would announce "0%", indistinguishable from a real stalled-at-
+  zero bar — so the helper returns just `role="progressbar"` + `aria-busy="true"`
+  (no `aria-valuenow`, no `--value`). Pair it with the class:
+  `<div class={ui.progress({ indeterminate: true })} {...attrs.progress()}>`.
 Rule of thumb: *something is happening* → progress; *something measures
 this much* → meter.
@@ -123,7 +231,10 @@ this much* → meter.
 - **`ui-steps`** — a stepper for a multi-step flow. Use an `<ol>`. State is
   ARIA-driven (the framework rule): the active step is `aria-current="step"`
   (no class); completed steps take `ui-steps__item--done`. Markers are
-  auto-numbered by CSS counter.
+  auto-numbered by CSS counter. `--done` is a **visual** state only — it isn't
+  announced, so if "completed" must reach AT, add visually-hidden text
+  (e.g. `<span class="ui-visually-hidden">completed</span>`) or an `aria-label`
+  on the step.
 - **`ui-timeline`** — a vertical event list on a hairline spine (`<ol>` of
   `ui-timeline__item`, optional `ui-timeline__time`). `aria-current` on an
   item marks the live/most-recent event.
@@ -135,14 +246,116 @@ this much* → meter.
   (`aria-hidden`) and the input keeps its full width. Don't hand-roll an
   absolute overlay.
+## Navigation: the landmarks and names the classes don't carry
+The navigation classes are styling only — the ARIA scaffolding is yours, and
+without it these widgets are unlabelled or unannounced:
+- **`ui-breadcrumb`** — wrap it in `<nav aria-label="Breadcrumb">` and mark the
+  last (current) crumb with `aria-current="page"`.
+- **`ui-pagination`** — wrap it in `<nav aria-label="Pagination">`; give the
+  current page `aria-current="page"`; label icon-only prev/next controls
+  (`aria-label="Previous page"`). Disable a control with native `disabled`
+  (a `<button>`) for full inertness, **or** `aria-disabled="true"` for a control
+  that stays focusable/announced (e.g. a disabled `<a>`). CSS dims both and makes
+  `aria-disabled` pointer-inert, but only native `disabled` is keyboard-inert on
+  its own — to stop an `aria-disabled` control from activating on Enter/Space,
+  wire `initDisabledGuard()` once near your root (see Behaviors).
+- **`ui-tabs`** — `initTabs` adds the full APG wiring (roles, roving tabindex,
+  `aria-selected`, panel `hidden`, focusable panel). If you wire tabs yourself,
+  name the `ui-tabs__list` (`role="tablist"` + an `aria-label`) and pair each
+  tab with its panel via `aria-controls`/`aria-labelledby`. Every tab needs a
+  matching panel — a tab with no `aria-controls` target is an orphan that
+  announces as selected but reveals nothing.
+- **Icon-only buttons** (`ui-button--icon` and any glyph-only control) carry no
+  text node, so they're nameless to AT — give them an `aria-label`
+  (`<button class="ui-button ui-button--icon" aria-label="Delete">`).
+- **`ui-sitenav` / `ui-app-nav`** — signal the current link with
+  `aria-current="page"` (both honour it; `ui-app-nav` also accepts the
+  visual-only `.is-active`, but prefer `aria-current`).
+- **`ui-skiplink`** — keep it the first focusable element and point its `href`
+  at the `id` of your main landmark.
+## App shell: the admin dashboard frame
+`ui-app-shell` is a CSS-only two-column admin frame (sidebar rail + main
+column) that collapses to a single column with a horizontal rail below 880px —
+no behavior required. The nesting matters; the rail is `ui-app-rail` and the
+content side is `ui-app-main`:
+```html
+<div class="ui-app-shell">
+  <aside class="ui-app-rail">
+    <span class="ui-app-rail__brand">Acme</span>
+    <nav class="ui-app-nav" aria-label="Primary">
+      <span class="ui-app-nav__section">Main</span>
+      <a href="/overview" aria-current="page">Overview</a>
+      <a href="/reports">Reports</a>
+    </nav>
+    <div class="ui-app-rail__account">…</div>
+  </aside>
+  <main class="ui-app-main">
+    <header class="ui-app-topbar"><h1 class="ui-app-topbar__title">Overview</h1></header>
+    <div class="ui-app-content">
+      <section class="ui-app-panel">
+        <div class="ui-app-panel__head"><h2 class="ui-app-panel__title">KPIs</h2></div>
+        <div class="ui-app-metrics">…<div class="ui-app-metric">…</div></div>
+      </section>
+    </div>
+  </main>
+</div>
+```
+Knobs: `--app-rail` sets the rail width (default 14rem); `ui-app-shell--full`
+drops the rail for a single-column app. `ui-app-nav` honours `aria-current="page"`
+(preferred) and the visual-only `.is-active`.
+## Menus: `data-bronto-menu` + `initMenu`
+A dropdown menu is a native `<details data-bronto-menu>` styled as
+`ui-menu-host` → `ui-menu` (with `ui-menu__item` / `ui-menu__sep` /
+`ui-menu__label`). It opens/closes natively, but `initMenu()` adds the close
+affordances a menu needs: outside-click close, Escape, and closing on item
+activation. Without the behavior the menu opens but never dismisses itself.
+**Clipping limitation.** The menu panel is positioned in normal flow (not the
+top layer), so an ancestor with `overflow: hidden`/`auto` or a transform
+**clips** it — the same edge case the tooltip has. If your menu lives inside a
+scroll container or a clipped card and the panel gets cut off, either lift the
+`ui-menu-host` out of the clipping ancestor, or reach for `initPopover` (which
+escapes to the browser top layer via the native `popover` attribute) for that
+control instead.
+## Avatar: it's an unlabelled blob until you name it
+`ui-avatar` is a presentation box. Give it an accessible name yourself: an
+image avatar needs real `alt` text (`alt=""` only if it's purely decorative
+beside a visible name); an initials avatar needs an accessible name on the
+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`
 Prefer the **native `<dialog>`** path — you get top-layer, backdrop and
-focus-trap free. Only use `ui-modal.is-open` (`ui.modal({ open: true })`)
-when a portal/React modal genuinely can't be a `<dialog>`; then the
-backdrop and focus-trap are **yours** to provide. A drawer is a modal
+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
+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.
 ## Carousel & lightbox: one primitive, two skins
 `ui-carousel` is a scroll-snap track of `__slide`s wired by `initCarousel`
@@ -181,6 +394,13 @@ that fuses the cells into a square, gapless pixel glyph that stays crisp and
 legible down to **~16px** — so the same set doubles as real inline UI icons,
 not just decoration. (Below the dot fragments into dot-soup; solid does not.)
+One caveat on ink: `solid` cells inherit the dot palette (`--field-dot-hot`,
+~40% alpha), so at small sizes a solid glyph reads as a soft grey, not full
+ink. When you want a crisp, full-strength small icon (toolbar, button affordance),
+use the one-node mask renderer instead — `renderGlyph(name, { render: 'mask' })`
+paints the glyph in `currentColor` on a `.ui-icon`, so it tracks text colour at
+any size.
 `renderGlyph(name, { label })` returns an SSR-safe string: decorative
 (`aria-hidden`) by default, or `role="img"` + `aria-label` when you pass a
 `label` — which is how it conveys meaning to assistive tech. Prefer the
@@ -285,13 +505,131 @@ authoring engine.
 - Annotation text must be visible or represented in the figure caption, SVG
   `<desc>`, or fallback table. Full detail in [annotations.md](annotations.md).
+## Forms: the contracts the markup alone won't tell you
+- **Disabled — pick one mechanism.** Use the native `disabled` attribute for a
+  genuinely inert control (`ui-input`, `ui-select`, `ui-textarea`, `ui-switch`
+  /`ui-check`/`ui-segmented` wrapping a native input, `ui-range`, `ui-file`,
+  `ui-button`): the browser greys it, blocks activation, and skips it in tab
+  order, and bronto styles the disabled cue. Use `aria-disabled="true"` **only**
+  when the control must stay focusable/announced — bronto then adds
+  `pointer-events: none` to `ui-button`/`ui-link` so the pointer can't activate
+  it. That is **pointer-inert, not keyboard-inert**: CSS can't stop Enter/Space,
+  so wire `initDisabledGuard()` (Behaviors) to block keyboard activation across
+  every `aria-disabled` control. Either way you still own removing it from the
+  submit logic.
+- **Read-only ≠ disabled.** A `readonly` input keeps its value in form submission
+  and stays focusable/selectable; `disabled` does neither. Bronto gives a
+  read-only field a quiet muted fill so it doesn't read as a live editable field —
+  reach for `readonly` when the value matters but mustn't be edited, `disabled`
+  when it should be inert and skipped.
+- **Combobox** (`data-bronto-combobox`) reads its options from the DOM at
+  `initCombobox()` time — re-run it after you replace the option list (or add
+  `data-bronto-combobox-live`). The selected **option's text label** is shown in
+  the input while the `bronto:change` event carries the option's `data-value`
+  code — so put the human label in the `<li>` text and the code in `data-value`.
+  The `.ui-combobox__empty` ("No matches") is hidden until a filter empties the
+  list. Two intentional single-select APG deviations: ArrowDown on a closed list
+  filters rather than pre-selecting the first option, and Tab closes without
+  committing a merely-highlighted option (Enter/click commits).
+- **Validation** is opt-in via `data-bronto-validate` on the form plus
+  `initFormValidation()`; it surfaces messages into a `ui-error-summary` you
+  provide. The summary's title is the legible sans, not the display face — it's
+  meant to be read.
+## 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
+or LLM-authored report. `ui-reveal` is the JS variant: it starts hidden and you
+toggle `is-visible` (e.g. from an `IntersectionObserver` you own) to play it in.
+With scripting disabled it degrades to fully visible, but if scripting is *on*
+and nothing toggles `is-visible`, the content stays hidden — so only use
+`ui-reveal` when you are wiring that toggle.
+**View transitions (`ui-vt`).** `ui-vt` names an element via `--ui-vt-name` so it
+morphs across a `document.startViewTransition()` or a cross-document navigation.
+The name must be **unique per document** at the moment a transition runs: applying
+`ui-vt` with one shared `--ui-vt-name` across every card in a list (the obvious
+loop) makes the browser skip the transition — and it is **not** silent: it logs a
+console error and **rejects `vt.ready`** (with an `InvalidStateError`). If you
+don't `vt.ready.catch(…)`, that surfaces as an unhandled promise rejection. Give
+each element its own name (`--ui-vt-name: card-7`) or only mark the single element
+that actually morphs.
+## Loading affordances need a role you supply
+`ui-spinner`, `ui-dotspinner`, `ui-skeleton`, and an indeterminate `ui-progress`
+are decorative animations — bronto can't know their semantics. Give the busy
+region `aria-busy="true"` (or `role="status"` with an `aria-live` text label like
+"Loading…"), and mark a purely decorative spinner `aria-hidden="true"`. Without
+one of these a screen reader announces nothing while the user waits.
+## Popover: prefer the native top layer
+`initPopover()` shows a `.ui-popover` in the browser **top layer** when the panel
+carries the native `popover` attribute (never clipped by `overflow`/stacking);
+without it, it falls back to an `is-open` class that a clipping ancestor can cut
+off. Add `popover` to the panel for the robust path — the `is-open` form is a
+fallback, not the default to copy.
+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
+*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.
+## Two tiers: CSS-native vs behavior-required
+Not every component works with JavaScript off — know which tier you are shipping
+before you rely on the no-JS path.
+**CSS-native — fully operable with JS off.** Safe in static or LLM-authored
+HTML, print/PDF, and before any hydration:
+| Component | How it works without JS |
+| --- | --- |
+| Tooltip (`ui-tooltip`) | `:hover` / `:focus-within` (+ anchor positioning where supported) |
+| Accordion | native `<details>` / `<summary>` |
+| Segmented control (`ui-segmented`) | `:has(input:checked)` over a radio group |
+| Scroll-reveal (`ui-scroll-reveal`) | scroll-driven animation, zero JS |
+| Modal via native `<dialog>` | the element brings focus-trap + Escape; `initDialog` only adds open-triggers + focus-return |
+**Behavior-required — a CSS skin that needs its `init*` to be interactive.**
+These are JS widgets wearing the Bronto look; without the behavior they are inert
+(and a couple are *worse* than inert — see the tabs row):
+| Component | Behavior | With the behavior absent |
+| --- | --- | --- |
+| Tabs (`ui-tabs`) | `initTabs` | **author panels visible** — ship `hidden` panels and if `initTabs` never runs the content is unreachable |
+| Combobox (`ui-combobox`) | `initCombobox` | a plain text input beside an unfiltered list |
+| Command palette (`ui-command`) | `initCommand` | a static, unfiltered list |
+| Table sort/select (`[data-bronto-sortable]`) | `initTableSort` | a static table (still readable) |
+| Popover (`ui-popover`) | `initPopover` | no placement/ARIA — prefer the native `popover` attribute |
+| Carousel (`ui-carousel`) | `initCarousel` | a native scroll-snap track (usable, no controls) |
+| Controlled modal (`ui-modal.is-open`) | `initModal` | no focus trap — provide one or use native `<dialog>` |
+| Menu (`data-bronto-menu`) | `initMenu` | a button next to a list with no open/close, outside-click, or Escape |
+| Toast | `toast()` | nothing — it is imperative-only |
+One cross-cutting guard, not tied to a single component:
+| Concern | Behavior | With the behavior absent |
+| --- | --- | --- |
+| `aria-disabled="true"` controls | `initDisabledGuard` | dimmed + pointer-inert via CSS, but still **keyboard**-activatable on Enter/Space (native `disabled` is already fully inert) |
+Rule of thumb: if a component needs ARIA-state sync, focus management, a keyboard
+model, or persisted/dynamic state, it is behavior-required — that is the exact
+boundary of what CSS alone cannot do.
 ## When to add a behavior
 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, toast, combobox, form-validation, table-sort).
-Reach for it instead of reimplementing — every initializer is SSR-safe,
-idempotent, and returns a cleanup. If you find yourself writing focus
+disclosure, dialog glue, modal focus-trap, toast, combobox, form-validation,
+table-sort). Reach for it instead of reimplementing — every initializer is
+SSR-safe, idempotent, and returns a cleanup. If you find yourself writing focus
 management or `aria-expanded` toggling by hand, there is probably already
 a behavior for it.