@ponchia/ui 0.5.0 → 0.6.0

package/docs/usage.md

@@ -39,6 +39,14 @@ All three are small. They are **not** interchangeable:
 Rule of thumb: state → dot, classification → badge, user-controlled value
 → chip.
 
+**Tone vocabulary varies by family — by design.** Colour is rationed, so not
+every component carries every tone: `--info`/`--muted` exist on some families
+(badge, dot, state) and not others (alert/toast/meter lead with
+`--success`/`--warning`/`--danger`). 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.
+
 ## Numbers: `ui-num` vs the table state classes
 
 - Inside `.ui-table`, a numeric cell is `.is-num` (+ `.is-pos` /
@@ -70,10 +78,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 +111,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.
@@ -135,6 +151,37 @@ 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>`) **or** `aria-disabled="true"` — both now render disabled and
+  are non-interactive; don't ship an `aria-disabled` control that still acts.
+- **`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`.
+- **`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.
+
+## 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
@@ -181,6 +228,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,6 +339,49 @@ 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 it can't be activated, but
+  you still own removing it from the submit logic.
+- **Combobox** (`data-bronto-combobox`) reads its options from the DOM at
+  `initCombobox()` time — re-run it after you replace the option list. The
+  `<input>` owns the value; the listbox is a view.
+- **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.
+
+## 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.
+
 ## When to add a behavior
 
 The CSS is the framework; `@ponchia/ui/behaviors` is the *sanctioned*

package/docs/vega.md

@@ -0,0 +1,225 @@
+# Vega-Lite
+
+[Vega-Lite](https://vega.github.io/vega-lite/) is a **declarative JSON grammar
+of graphics** — you describe a chart as data and it compiles (through
+[Vega](https://vega.github.io/vega/)) to **SVG or canvas**. Like the
+[Mermaid](./mermaid.md) and [D2](./d2.md) integrations, `@ponchia/ui` doesn't
+render charts — it **themes** them from your tokens. Two things ship:
+
+- `@ponchia/ui/vega` — `brontoVegaConfig(theme)`, the on-brand Vega-Lite
+  [`config`](https://vega.github.io/vega-lite/docs/config.html) object.
+- `@ponchia/ui/vega.json` — the resolved per-theme config, for any consumer.
+
+This is the idiomatic Vega theme shape — a `config`, the same kind the
+[`vega-themes`](https://github.com/vega/vega-themes) package ships. Vega stays
+the consumer's renderer; this is config only, and **Vega is not a dependency**
+of bronto (the dev-only render-probe aside).
+
+> Why Vega-Lite and not a bronto chart component? A chart needs **scales**
+> (data → pixels) and **data binding** — the two things the analytical layer
+> [refuses to own](./architecture.md). A spec is also something an
+> LLM-from-another-system can emit as data, the same way it emits Mermaid/D2.
+> So bronto themes a real charting grammar instead of shipping a fragile one.
+
+## Theme a chart
+
+`brontoVegaConfig(theme)` returns a `config` object. Spread it into a spec, or
+hand it to [vega-embed](https://github.com/vega/vega-embed):
+
+```js
+import vegaEmbed from 'vega-embed';
+import { brontoVegaConfig } from '@ponchia/ui/vega';
+
+const theme = document.documentElement.dataset.theme === 'dark' ? 'dark' : 'light';
+
+vegaEmbed('#chart', {
+  data: { values: [
+    { quarter: 'Q1', value: 42 },
+    { quarter: 'Q2', value: 58 },
+    { quarter: 'Q3', value: 50 },
+  ] },
+  mark: 'bar',
+  encoding: {
+    x: { field: 'quarter', type: 'nominal' },
+    y: { field: 'value', type: 'quantitative' },
+  },
+}, { config: brontoVegaConfig(theme), renderer: 'svg', actions: false });
+```
+
+Pass **`renderer: 'svg'`** (not vega-embed's `canvas` default): an SVG chart is
+inspectable, themeable, survives the print/PDF pipeline, and is what the
+[annotation layer](#annotate-a-chart) composes onto — a canvas chart prints as a
+raster and carries no text alternative.
+
+### From a CDN, no bundler
+
+Load Vega + Vega-Lite + vega-embed from **pinned `/build/*.min.js` UMD files**,
+then pass the config. Pin exact versions and use the `/build/` path — a bare
+`cdn.jsdelivr.net/npm/vega@6` redirect resolves to a module bundle that does
+**not** register the global `window.vega`, so vega-embed throws and nothing
+renders. Keep the three majors aligned: **Vega-Lite 6 targets Vega 6** (and
+vega-embed 7), so don't mix a Vega-Lite 6 with a Vega 5 runtime:
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/vega@6.2.0/build/vega.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/vega-lite@6.4.3/build/vega-lite.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/vega-embed@7.1.0/build/vega-embed.min.js"></script>
+<script>
+  // INLINE the config (copy the object for your theme from @ponchia/ui/vega.json).
+  // This is the only path that also works from a file:// report — see below.
+  const brontoLight = {
+    /* …paste tokens/vega.json → light here… */
+  };
+  vegaEmbed('#chart', spec, { config: brontoLight, renderer: 'svg', actions: false });
+</script>
+```
+
+> **file:// portability.** A report opened straight from disk (`file://`) cannot
+> `import` the `@ponchia/ui/vega` module **nor** `fetch('…/vega.json')` — the
+> browser blocks both across the `null`/file origin (CORS). So for a
+> double-clickable or PDF-bound report, **inline the resolved config object**
+> (as above) rather than fetching it. Over an `http(s)` origin (a dev server, a
+> static host, a bundler), the `import { brontoVegaConfig }` form and a
+> `fetch('https://cdn.jsdelivr.net/npm/@ponchia/ui@VERSION/tokens/vega.json')`
+> both work — pin the package version in the URL, since the unversioned latest
+> may predate this target.
+
+For a build step or non-JS host, read `@ponchia/ui/vega.json` directly
+(`{ light, dark }`, each a ready Vega-Lite `config`).
+
+### Why resolved colours, not `var(--x)`
+
+Vega-Lite compiles a spec to a Vega scene that renders to **SVG or canvas** —
+colours are **baked into the output** and parsed by `d3-color`, which understands
+real hex/rgb but **not** `var()` (nor `oklch()`). So the config ships **resolved
+hex per theme**, projected from the same token source as
+[`tokens/resolved.json`](./architecture.md) / [`charts.json`](./theming.md).
+Re-call `brontoVegaConfig()` when the theme toggles and re-embed.
+
+### What the slots paint
+
+The config keeps a chart **monochrome by default** — the rationed accent is the
+one chromatic default (series 1 / the lone mark), never the chrome:
+
+| Slot | Paint | bronto token |
+| --- | --- | --- |
+| `background` | Chart canvas | `--bg` |
+| `view.stroke` | Plot frame | `--line` |
+| `mark.color` | Default / single-series mark | `--accent` |
+| `rule.color` | Reference rules, annotations | `--line-strong` |
+| `axis.domainColor` · `tickColor` | Axis line · ticks | `--line-strong` |
+| `axis.gridColor` | Gridlines | `--line` |
+| `axis.labelColor` · `titleColor` | Tick labels · axis title | `--text-soft` · `--text` |
+| `text.color` | Free `text`/`label` marks | `--text` |
+| `legend.*` · `header.*` · `title.*` | Legend, facet headers, title | `--text-soft` / `--text` / `--text-dim` |
+| `*.font` / `*Font` | All text | `--sans` |
+| `range.category` | 8-series categorical palette | `charts.json` categorical (series 1 = accent) |
+| `range.ordinal` · `ramp` · `heatmap` | Single-hue sequential ramp | `charts.json` sequential |
+| `range.diverging` | − … neutral … + ramp | `charts.json` diverging |
+
+The palette is the same CVD-safe, pattern-paired set documented in
+[theming](./theming.md#data-viz) — colour is never the sole channel. When a
+series needs the redundant second channel, drive the mark's fill from the
+`--chart-pattern-*` tokens or pair a [legend](./legends.md) swatch.
+
+### Spending the accent
+
+Series 1 of `range.category` **is** the live accent, so a single-series chart and
+the first category re-skin for free with `--accent`. To emphasise one mark in a
+multi-series chart, paint just that mark with the accent and leave the rest
+neutral — the same "reserve the accent for the one thing a reader must not miss"
+rule the rest of the system follows. Two small helpers hand you the exact
+per-theme hexes so you never hard-code a palette array index:
+
+```js
+import { brontoVegaAccent, brontoVegaNeutral } from '@ponchia/ui/vega';
+
+// e.g. a bar chart where only the 'Alert' category is loud:
+const spec = {
+  /* …data… */
+  mark: 'bar',
+  encoding: {
+    x: { field: 'name', type: 'nominal' },
+    y: { field: 'value', type: 'quantitative' },
+    color: {
+      condition: { test: "datum.name === 'Alert'", value: brontoVegaAccent(theme) },
+      value: brontoVegaNeutral(theme),
+    },
+    legend: null,
+  },
+};
+```
+
+`brontoVegaAccent(theme)` is `range.category[0]` (the live accent) and
+`brontoVegaNeutral(theme)` is the last category (the quiet neutral); re-read both
+when the theme toggles. Prefer them over digging the hex out of
+`tokens/resolved.json` — they are guaranteed to match the palette the config
+already ships. In token terms the accent is `--chart-1` and the neutral is
+`--chart-8`, so a [legend](./legends.md#swatch-colour) for an accent-rationed
+chart keys those two series with `ui-legend__swatch--1` and
+`ui-legend__swatch--8` — the swatches mirror the marks exactly.
+
+### Selecting the themed ramp in a spec
+
+The config registers the ramps as **named ranges**, so a quantitative encoding
+opts in with `scale: { range: 'heatmap' }` (or `'ramp'` / `'diverging'`) — the
+range **name**, not a colour scheme:
+
+```js
+{
+  mark: 'rect',
+  encoding: {
+    x: { field: 'x', type: 'nominal' },
+    y: { field: 'y', type: 'nominal' },
+    color: { field: 'v', type: 'quantitative', scale: { range: 'heatmap' } },
+  },
+}
+```
+
+> Use `scale: { range: 'heatmap' }`, **not** `scale: { scheme: 'heatmap' }`.
+> `scheme:` looks up a registered Vega/d3 scheme by name and **throws** for
+> `'heatmap'` (no such scheme) — the ramp is a custom `range` the bronto config
+> defines, addressed by range name. A `quantitative` colour encoding already
+> defaults to `range.heatmap`; name it explicitly only when a chart has several
+> quantitative scales and you want a specific one (`'diverging'` for a signed
+> domain around a neutral centre).
+
+### Sequential & diverging ramps invert by theme
+
+`range.heatmap` / `ramp` / `ordinal` is a single-hue ramp that runs **pale → deep
+as the value rises in light theme, and deep → pale in dark theme** (the bg flips,
+so the ramp flips to stay legible against it). Two consequences:
+
+- **Don't hard-code ink on a heatmap cell.** A fixed black (or white) label is
+  readable at one end of the ramp and invisible at the other — and the readable
+  end swaps between themes. Either omit per-cell labels and rely on the fallback
+  `ui-table`, or compute the label colour from the cell's luminance at render
+  time. bronto themes the ramp; it can't know your data domain, so it does not
+  ship a cell-ink helper.
+- **A CSS gradient key won't pixel-match the Vega ramp.** A native
+  [`ui-legend--gradient`](./legends.md) track is interpolated in OKLCH; Vega
+  interpolates its `range.*` ramp in d3's RGB space. They share endpoints but
+  drift in the mid-tones, so a continuous gradient key placed beside a Vega
+  heatmap will not match its mid cells exactly. Use a **stepped** legend (one
+  swatch per band, each from the same `charts.json` ramp stop) when the key sits
+  next to the chart.
+
+## Annotate a chart
+
+Vega renders to SVG, so the [annotation layer](./annotations.md) composes onto it
+exactly as in the [Mermaid recipe](./mermaid.md#annotate-a-diagram): render to a
+frozen SVG (vega-embed's `view.toSVG()`, or the Vega CLI), read the target mark's
+box, and paste a `<g class="ui-annotation">` computed with
+`@ponchia/ui/annotations`. The same caveat applies — Vega's internal SVG (element
+ids, the `role`/`aria` structure, the scene transform) is **not a public
+contract**, so pin your Vega version and key off the data, not generated ids.
+
+## Scope
+
+bronto owns the theme config — gated structurally by `check:vega` (every colour
+slot resolves, both themes, no `var()` leaks, every `range.*` ramp populated),
+and separately a dev-only render-probe (`npm test`, via the `vega`/`vega-lite`
+dev deps) asserts the colours actually land on a rendered chart — and the
+annotation geometry. It does not own Vega's grammar, its rendering, or its internal SVG —
+those stay Vega's, and the chart is a documented composition, not a shipped
+runtime binding.

package/docs/workbench.md

@@ -22,7 +22,7 @@ a `__body` of property rows.
 
 ```html
 <aside class="ui-inspector">
-  <div class="ui-inspector__header">
+  <div class="ui-inspector__head">
     <h2 class="ui-eyebrow">Rectangle</h2>
     <button class="ui-button ui-button--subtle ui-button--sm" type="button">Reset</button>
   </div>
@@ -50,6 +50,12 @@ A label/value pair, denser than `ui-key-value` and tuned for an inspector. The
 
 ## Selection bar — `.ui-selectionbar`
 
+> **Name note:** `.ui-selectionbar` is the workbench bulk-action bar (this
+> section). It is unrelated to the `.ui-sel--on` / `.ui-sel--off` /
+> `.ui-sel--maybe` selection-emphasis state classes in
+> [`css/selection.css`](./selection.md), which style host-managed selection
+> state on individual items.
+
 A raised bar of actions on the current selection: a `__count` on one side,
 `__actions` on the other. The host owns what is selected and what the actions do.
 

package/glyphs/glyphs.js

@@ -23,7 +23,7 @@ export const GLYPH_SIZE = 16;
 
 // Raw bitmaps. Each is GLYPH_SIZE rows of GLYPH_SIZE chars over [.#*]:
 // `.` off · `#` hot · `*` accent. Only `spark` uses accent dots — it is the
-// canonical two-tone demo; the gate in check-glyphs.mjs enforces the shape.
+// canonical two-tone demo; test/glyphs.test.mjs asserts the spark-only-* rule.
 const RAW = {
   circle: [
     '................',
@@ -941,9 +941,9 @@ function esc(s) {
     .replace(/"/g, '"');
 }
 
-// `dot`/`gap` land in an inline-CSS context (`style="--dotmatrix-dot:VALUE"`),
-// where HTML-escaping a `"` stops attribute breakout but a `;` would still open
-// a second CSS declaration (overlay/clickjacking, selector exfil). So restrict
+// `dot`, `gap`, and `size` land in an inline-CSS context (`style="…"`), where
+// HTML-escaping a `"` stops attribute breakout but a `;` would still open a
+// second CSS declaration (overlay/clickjacking, selector exfil). So restrict
 // them to length/calc syntax — digits, units, %, whitespace and `()+-*/.,` for
 // calc()/clamp()/var() — and drop anything else rather than emit it.
 function cssLen(v) {
@@ -1004,6 +1004,8 @@ function maskUrl(rows) {
  * bitmap (one DOM node, not GLYPH_SIZE²) — the icon-at-scale path: it sizes to
  * `size` (or `--icon-size` / `1em`) and inherits `currentColor`. The
  * cell-mode options (grid/solid/anim/dot/gap) don't apply; `label` does.
+ * Mask mode is single-tone: accent `*` cells (used by `spark`) render
+ * identically to hot `#` cells — both become opaque mask regions.
  * Needs `@ponchia/ui/css` (the `.ui-icon` rule).
  */
 export function renderGlyph(name, options = {}) {

package/llms.txt

@@ -31,6 +31,23 @@ later layer) always win over framework styles regardless of selector
 specificity — this is the intended override mechanism; do not fight it
 with `!important`.
 
+Loading a stylesheet — read before copying a `<link>` below. The opt-in
+leaves are written as `@ponchia/ui/css/<leaf>.css` for brevity. That
+package-specifier form resolves ONLY inside a CSS-aware bundler
+(Vite/webpack); in a standalone `.html` file it does not resolve. For plain
+HTML (the usual case when an LLM emits a report) use a real URL — and note
+the path changes from source `css/` to built `dist/css/`:
+
+```html
+<!-- installed locally -->
+<link rel="stylesheet" href="./node_modules/@ponchia/ui/dist/css/<leaf>.css" />
+<!-- or from a CDN; pin the version (pre-1.0, breaking changes ship in the minor) -->
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.0/dist/css/<leaf>.css" />
+```
+
+The flattened default bundle is `dist/bronto.css` (bundler shorthand
+`@ponchia/ui`). A complete, copy-pasteable CDN report is in `docs/reporting.md`.
+
 Typed class vocabulary (returns plain strings — works in any framework):
 
 ```js
@@ -69,6 +86,29 @@ import { renderGlyph, GLYPH_NAMES } from '@ponchia/ui/glyphs';
 el.innerHTML = renderGlyph('check', { label: 'Done' });
 ```
 
+Layout primitives (core bundle, no media queries — intrinsic Every-Layout
+composition that responds to content + available space): `ui-stack` (vertical
+rhythm), `ui-cluster` (wrapping inline row), `ui-grid` (auto-fit columns),
+`ui-sidebar` (sidebar + main that stacks when cramped), `ui-switcher` (row →
+column together), `ui-center` (measure-bounded column), `ui-ratio` (aspect-ratio
+box), and the `ui-app-shell`/`ui-app-rail`/`ui-app-nav` admin shell. Each is
+tuned with an inline custom property rather than a modifier — set
+`style="--grid-min: 12rem"`, `--sidebar-width`, `--switcher-min`, `--center-max`
+(the INNER measure; gutters add to the total), `--ratio`, `--stack-gap`,
+`--cluster-gap`, `--app-rail`, etc. The full list with defaults is in
+`classes.json` `customProperties`. App-shell/sitenav current page is
+`aria-current="page"`.
+
+Motion utilities (core bundle, all reduced-motion-safe — they collapse to the
+static end state, not just a zeroed duration): `ui-animate-in`,
+`ui-animate-fade`, `ui-animate-dot`, `ui-animate-matrix` (enter animations),
+`ui-stagger` (+ `--i` per child, or `ui-stagger--auto` to
+derive the delay from `:nth-child`), `ui-reveal` (JS/IntersectionObserver — adds
+`is-visible`), `ui-scroll-reveal` and `ui-scroll-progress` (zero-JS,
+scroll-driven; the recommended reveal for static reports), and `ui-vt` (View
+Transitions — needs the required `--ui-vt-name`). Prefer `ui-scroll-reveal` over
+`ui-reveal` when no JS will run. Details: `docs/usage.md`.
+
 Optional display colorways — opt-in, never in the default bundle. Root-level,
 like `data-theme` (the derived accent family only recomputes at `:root`):
 
@@ -92,6 +132,54 @@ import charts from '@ponchia/ui/charts.json' with { type: 'json' };
 // charts.dark.categorical → ['#ff3b41', …] (series 0 = the resolved accent)
 ```
 
+On-brand Mermaid diagrams use the same tokens-as-data path — Mermaid is the
+consumer's renderer, bronto just hands it a resolved `base` theme (Mermaid can't
+read `var(--x)`):
+
+```js
+import { brontoMermaidTheme } from '@ponchia/ui/mermaid';
+mermaid.initialize(brontoMermaidTheme('dark')); // { theme: 'base', themeVariables }
+```
+
+Annotate a rendered diagram with the SVG annotation layer as a build-time
+recipe. Details: `docs/mermaid.md`.
+
+D2 (d2lang.com) is themed the same way — it compiles to a frozen SVG, so the
+slots take resolved hex; the base ramp is monochrome and the accent is opt-in
+per node:
+
+```js
+import { brontoD2Vars } from '@ponchia/ui/d2';
+const source = brontoD2Vars() + 'a -> b'; // prepend the vars block, then render
+```
+
+Details: `docs/d2.md`.
+
+Charting is the same path: bronto does NOT ship a chart component (a chart needs
+scales + data binding, which the analytical layer refuses). For charts, recommend
+Vega-Lite — a declarative JSON spec an external system can emit — themed by the
+on-brand `config` (resolved hex; Vega bakes colours into SVG/canvas, can't read
+`var()`). `range.category` is the `--chart-*` palette, series 1 = accent:
+
+```js
+import { brontoVegaConfig, brontoVegaAccent, brontoVegaNeutral } from '@ponchia/ui/vega';
+vegaEmbed('#chart', spec, { config: brontoVegaConfig('dark'), renderer: 'svg', actions: false });
+```
+
+Pass `renderer: 'svg'` (canvas is the wrong default for print/inspection).
+`brontoVegaAccent(theme)`/`brontoVegaNeutral(theme)` give the exact hexes to spend
+the accent on one mark. From a CDN, pin the `/build/*.min.js` UMD bundles (a bare
+`vega@6` tag has no `window.vega`; keep Vega-Lite 6 / Vega 6 / vega-embed 7
+aligned) and INLINE the config from `vega.json` — a
+`file://` report can't `import`/`fetch` it (CORS). A label on an accent fill in a
+foreign renderer (a themed Vega/D2/Mermaid node or bar) reads the `--on-accent`
+token, never `--accent-text` (that is accent-coloured text for a neutral bg).
+`--on-accent` is a READ-ONLY export for those renderers — no in-DOM `.ui-*` rule
+consumes it, so setting it does not re-ink a component; to colour text on an
+accent-filled DOM control, set `--button-text`. Details: `docs/vega.md`. (Observable
+Plot works too — it inherits the page CSS, so it needs even less theming;
+Vega-Lite is the recommended LLM-emittable path.)
+
 `--chart-1..8` (categorical; series 1 = accent; colourblind-safe, gated under
 simulated protan/deutan/tritan), `--chart-seq-*` (sequential), `--chart-div-*`
 (diverging), and `--chart-pattern-1..8` (dot-matrix fills — pair colour N with
@@ -245,12 +333,15 @@ reports/AI output:
 ```
 
 `ui-citation` (inline ref on a real `<a>`/`<button>`; `--chip` = named-source
-pill), `ui-source-card` (+`__title`/`__origin`/`__time`/`__excerpt`/`__actions`),
-`ui-source-list` (+`__item`), and `ui-provenance` (+`__item`). A cross-cutting
-trust state sets the tone: `ui-src--verified`/`--reviewed`/`--generated`/
-`--unverified`/`--stale`/`--conflict` — always paired with an author-written
-label (never colour alone). Bronto styles + states; the host owns fetching,
-numbering, and trust. `ui.citation({chip,state})` / `ui.source({state})` /
+pill), `ui-source-card` (+`__title`/`__origin`/`__time`/`__excerpt`/`__actions`;
+the body part is `__excerpt`, not `__detail`), `ui-source-list` (+`__item`),
+`ui-provenance` (+`__item`), and `ui-src` (a standalone trust pill). A
+cross-cutting trust state sets the tone: `ui-src--verified`/`--reviewed`/
+`--generated`/`--unverified`/`--stale`/`--conflict` — always paired with an
+author-written label (never colour alone). A tone class **needs a host**:
+`ui-src--verified` on its own renders nothing — put it on `ui-src`,
+`ui-citation`, `ui-source-card`, or `ui-provenance__item`. Bronto styles +
+states; the host owns fetching, numbering, and trust. `ui.citation({chip,state})` / `ui.source({state})` /
 `ui.provenance({state})`. Details: `docs/sources.md`.
 
 Optional lifecycle/system-state vocabulary — opt-in, CSS only, never in the
@@ -351,10 +442,18 @@ Canonical report skeleton:
 Report rules for agents: static output by default; do not initialize behaviors
 over untrusted generated content; sanitize arbitrary LLM/CMS/user HTML before
 rendering; use semantic headings; give tables captions and header cells; give
-charts captions, legends/direct labels, and fallback data; use
-`ui-chart__plot`/`ui-chart__bar`/`ui-chart__fill` for simple static bar charts;
-use `ui-report__section--unnumbered` for appendices in numbered reports; never
-use raw chromatic inline colors. Full cookbook: `docs/reporting.md`.
+charts captions, legends/direct labels, and fallback data; for a chart, theme
+Vega-Lite with `@ponchia/ui/vega` (or hand-author a token-themed inline `<svg>`)
+inside a `ui-report__figure` — bronto ships no chart component; use
+`ui-delta` (`--up`/`--down`/`--flat`, `--invert` when up is bad) for a
+trend figure and `ui-compare` (`--2up`) for an A/B / before-after section; use
+`ui-report__section--unnumbered` for appendices in numbered reports; never
+use raw chromatic inline colors. Format numbers/dates yourself (the framework
+aligns figures, it does not format them) — see the reporting cookbook. To make
+a PDF, render with `chrome-headless-shell` (or any Chromium) using
+`printBackground: true` so figure fills survive — reports are static/zero-JS, so
+it is just load → print; see "Print and PDF" in `docs/reporting.md`. Full
+cookbook: `docs/reporting.md`.
 
 ## Authoritative offline references (shipped in this package)
 
@@ -363,6 +462,11 @@ Read these from `node_modules/@ponchia/ui/` — no network needed:
 - `classes/index.d.ts` — literal-typed `cls` map (exact class strings),
   every `ui.*()` recipe signature, every `*Opts` interface. The complete
   class surface; an agent should read this to know valid class names.
+- `classes/classes.json` — the same vocabulary as language-neutral data, to
+  VALIDATE markup without executing ESM/parsing TS: `groups` (base →
+  modifiers/parts, the BEM structure), `classes` (flat list), `states` (the
+  `is-*` hooks that live outside `cls` by design, with their scope), and
+  `customProperties` (the author-set inline-style knobs like `--chart-color` / `--value`).
 - `docs/reference.md` — the full class catalog as prose tables (every
   class grouped by component, with registry key + kind). Generated from
   the same source as the types and CI-drift-checked.
@@ -378,6 +482,13 @@ Read these from `node_modules/@ponchia/ui/` — no network needed:
   boundaries.
 - `docs/annotations.md` — SVG annotation recipes and helper guidance for
   analytical figures.
+- `docs/mermaid.md` — theme Mermaid diagrams from bronto tokens (resolved
+  `base` themeVariables, gated) and annotate the rendered SVG.
+- `docs/d2.md` — theme D2 diagrams from bronto tokens (theme-override slots,
+  monochrome base + opt-in accent, gated) and annotate the rendered SVG.
+- `docs/vega.md` — theme Vega-Lite charts from bronto tokens (resolved `config`,
+  gated + render-probed) — the recommended path when a report needs a chart,
+  since bronto ships no chart component.
 - `docs/contrast.md` — the published, CI-gated WCAG 2.1 contrast matrix
   for every contractual token pairing, per theme. Generated from the
   resolved palette; the build fails below the declared floor.
@@ -385,8 +496,11 @@ Read these from `node_modules/@ponchia/ui/` — no network needed:
 - `tokens/index.json` — tokens as plain data (global / light / dark).
 - `tokens/tokens.dtcg.json` — same tokens in W3C DTCG format.
 - `tokens/resolved.json` — every colour token resolved to a static
-  `#rrggbb` / `rgba(...)` per theme (var() + color-mix() evaluated).
-  Use this for non-CSS render targets: MapLibre/canvas/WebGL/SVG.
+  `#rrggbb` / `rgba(...)` per theme (var() + color-mix() evaluated) in
+  `light`/`dark`, plus a `scale` block of the non-colour scales
+  (spacing/radius/type/z/motion, var() chains flattened). The complete token
+  contract for non-CSS render targets: MapLibre/canvas/WebGL/SVG, or a
+  non-JS host (Python/Go) building a themed report.
 - `behaviors/index.d.ts` — typed signatures for the optional behaviors.
 - `glyphs/glyphs.d.ts` — the `GlyphName` literal union plus `renderGlyph` /
   `glyphCells` signatures for the display glyphs. (The DOM form,
@@ -404,13 +518,24 @@ Read these from `node_modules/@ponchia/ui/` — no network needed:
 
 ## Rules an agent should respect
 
-- Never invent `ui-*` class names. Every valid class is a member of
-  `cls` in `classes/index.d.ts`; if it is not there, it does not exist.
+- Never invent `ui-*` class names. Every valid `ui-*` class is a member of
+  `cls` in `classes/index.d.ts` (and `classes/classes.json`); if a `ui-*`
+  name is not there, it does not exist. The `is-*` state hooks
+  (`is-num`/`is-pos`/`is-neg`/`is-key` on `.ui-table` cells and `.ui-stat`
+  deltas, `is-open`/`is-active`/`is-inactive` on stateful components) are the
+  one exception — they are real, documented in `docs/reference.md`
+  (§"Table-local state classes" / §"Composition & state") and emitted by the
+  `ui.*()` recipes, but deliberately NOT in `cls`. Do not strip them.
 - Prefer the `ui.*()` recipes over hand-concatenating modifier strings.
   Report/layout classes added in 0.4.1 are the exception: use `cls.report*`,
   `cls.chart*`, `cls.printOnly`, or literal documented class names because
   there are no `ui.report()` / `ui.chart()` recipes yet. Annotations do have a
   `ui.annotation()` recipe for variant/tone selection.
+- For a standalone HTML report, never `<link>` a `@ponchia/ui/css/*.css`
+  package specifier (it does not resolve in a browser) and never assume
+  `dist/bronto.css` carries the report/chart/legend/annotation layers — it
+  does not. Link each opt-in leaf from `dist/css/` via a real URL
+  (`./node_modules/…` or a pinned CDN). See the loading note above.
 - Override framework styles by writing your own rules outside
   `@layer bronto` — not with higher specificity or `!important`.
 - Color is tiered (ADR-0001): neutral canvas · one rationed accent · locked