npm - @ponchia/ui - Versions diffs - 0.4.1 → 0.6.0 - Mend

@ponchia/ui 0.4.1 → 0.6.0

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 (153) hide show

package/CHANGELOG.md +552 -8
package/MIGRATIONS.json +106 -0
package/README.md +34 -8
package/annotations/index.d.ts +402 -0
package/annotations/index.d.ts.map +1 -0
package/annotations/index.js +792 -0
package/behaviors/carousel.js +198 -0
package/behaviors/combobox.js +226 -0
package/behaviors/command.js +190 -0
package/behaviors/connectors.js +95 -0
package/behaviors/crosshair.js +57 -0
package/behaviors/dialog.js +74 -0
package/behaviors/disclosure.js +26 -0
package/behaviors/dismissible.js +25 -0
package/behaviors/forms.js +186 -0
package/behaviors/glyph.js +108 -0
package/behaviors/index.d.ts +79 -0
package/behaviors/index.js +18 -1409
package/behaviors/internal.js +97 -0
package/behaviors/legend.js +67 -0
package/behaviors/menu.js +47 -0
package/behaviors/popover.js +179 -0
package/behaviors/spotlight.js +52 -0
package/behaviors/table.js +136 -0
package/behaviors/tabs.js +103 -0
package/behaviors/theme.js +84 -0
package/behaviors/toast.js +164 -0
package/classes/classes.json +1857 -0
package/classes/index.d.ts +306 -13
package/classes/index.js +339 -12
package/classes/vscode.css-custom-data.json +12 -0
package/connectors/index.d.ts +191 -0
package/connectors/index.d.ts.map +1 -0
package/connectors/index.js +275 -0
package/css/analytical.css +21 -0
package/css/annotations.css +292 -0
package/css/app.css +43 -13
package/css/base.css +15 -10
package/css/command.css +97 -0
package/css/connectors.css +110 -0
package/css/content.css +7 -1
package/css/crosshair.css +100 -0
package/css/dataviz.css +5 -1
package/css/disclosure.css +38 -6
package/css/dots.css +57 -0
package/css/feedback.css +111 -2
package/css/fonts.css +11 -7
package/css/forms.css +42 -1
package/css/generated.css +117 -0
package/css/legend.css +272 -0
package/css/marks.css +174 -0
package/css/motion.css +24 -44
package/css/navigation.css +7 -0
package/css/overlay.css +31 -1
package/css/primitives.css +109 -5
package/css/report.css +39 -81
package/css/selection.css +46 -0
package/css/site.css +16 -2
package/css/sources.css +221 -0
package/css/spotlight.css +104 -0
package/css/state.css +121 -0
package/css/tokens.css +60 -37
package/css/workbench.css +83 -0
package/dist/bronto.css +1 -1
package/dist/css/analytical.css +1 -0
package/dist/css/annotations.css +1 -0
package/dist/css/app.css +1 -1
package/dist/css/base.css +1 -1
package/dist/css/command.css +1 -0
package/dist/css/connectors.css +1 -0
package/dist/css/content.css +1 -1
package/dist/css/crosshair.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/fonts.css +1 -1
package/dist/css/forms.css +1 -1
package/dist/css/generated.css +1 -0
package/dist/css/legend.css +1 -0
package/dist/css/marks.css +1 -0
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/selection.css +1 -0
package/dist/css/site.css +1 -1
package/dist/css/sources.css +1 -0
package/dist/css/spotlight.css +1 -0
package/dist/css/state.css +1 -0
package/dist/css/tokens.css +1 -1
package/dist/css/workbench.css +1 -0
package/docs/adr/0003-theme-model.md +7 -4
package/docs/annotations.md +425 -0
package/docs/architecture.md +246 -0
package/docs/command.md +95 -0
package/docs/connectors.md +91 -0
package/docs/contrast.md +116 -92
package/docs/crosshair.md +63 -0
package/docs/d2.md +195 -0
package/docs/generated.md +91 -0
package/docs/legends.md +184 -0
package/docs/marks.md +93 -0
package/docs/mermaid.md +152 -0
package/docs/reference.md +385 -23
package/docs/reporting.md +436 -63
package/docs/selection.md +40 -0
package/docs/sources.md +137 -0
package/docs/spotlight.md +78 -0
package/docs/stability.md +24 -2
package/docs/state.md +85 -0
package/docs/usage.md +123 -4
package/docs/vega.md +225 -0
package/docs/workbench.md +78 -0
package/fonts/doto-400.woff2 +0 -0
package/fonts/doto-500.woff2 +0 -0
package/fonts/doto-600.woff2 +0 -0
package/fonts/doto-700.woff2 +0 -0
package/fonts/doto-800.woff2 +0 -0
package/fonts/doto-900.woff2 +0 -0
package/glyphs/glyphs.js +6 -4
package/llms.txt +362 -14
package/package.json +115 -12
package/qwik/index.d.ts +42 -54
package/qwik/index.d.ts.map +1 -0
package/qwik/index.js +75 -3
package/react/index.d.ts +39 -56
package/react/index.d.ts.map +1 -0
package/react/index.js +67 -3
package/solid/index.d.ts +64 -56
package/solid/index.d.ts.map +1 -0
package/solid/index.js +70 -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 +23 -5
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/fonts/doto-400.ttf +0 -0
package/fonts/doto-500.ttf +0 -0
package/fonts/doto-600.ttf +0 -0
package/fonts/doto-700.ttf +0 -0
package/fonts/doto-800.ttf +0 -0
package/fonts/doto-900.ttf +0 -0

package/llms.txt CHANGED Viewed

@@ -16,8 +16,8 @@
 CSS (pick one; do not import both):
 ```css
-@import '@ponchia/ui';        /* dist/bronto.css — flattened, minified, one file (recommended) */
-@import '@ponchia/ui/css';    /* css/core.css — @import fan-out, needs a bundler */
+@import '@ponchia/ui'; /* dist/bronto.css — flattened, minified, one file (recommended) */
+@import '@ponchia/ui/css'; /* css/core.css — @import fan-out, needs a bundler */
 ```
 `import '@ponchia/ui'` is supported only as a CSS side-effect import in a
@@ -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,12 +86,35 @@ 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`):
 ```html
 <link rel="stylesheet" href="@ponchia/ui/css/skins.css" />
-<html data-bronto-skin="amber-crt | phosphor-green | e-ink">
+<html data-bronto-skin="amber-crt | phosphor-green | e-ink"></html>
 ```
 Each re-points the one `--accent` (OKLCH, per-theme, contrast-gated); status
@@ -92,11 +132,277 @@ 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
 pattern N; colour is never the sole signal). Details in `docs/theming.md`.
+Building analytical / generated-report UI? Import the roll-up
+`@ponchia/ui/css/analytical.css` (bundles annotations + legend + marks +
+connectors + spotlight + crosshair + selection) instead of the seven leaves;
+add `css/dataviz.css` for chart colours and `css/report.css` for the document
+grammar. The individual layers (each opt-in, none in the default bundle):
+Optional SVG annotations for charts/reports — opt-in, never in the default
+bundle. This is Bronto's subject / connector / note grammar inspired by
+d3-annotation, not an authoring engine:
+```html
+<link rel="stylesheet" href="@ponchia/ui/css/annotations.css" />
+```
+```js
+import { annotationParts, connectorLine, circleSubjectPath } from '@ponchia/ui/annotations';
+```
+Use `ui-annotation` groups inside SVG with `ui-annotation__subject`,
+`ui-annotation__connector`, `ui-annotation__note`, `ui-annotation__title`, and
+`ui-annotation__label`. `ui.annotation({ variant, tone, motion })` builds the
+base class string. Variants cover labels, callouts, elbow/curve connectors,
+circle/rect/threshold subjects, badges, brackets, bands, slopes, comparisons,
+clusters, axis marks, timeline pins, and evidence markers. Motion is opt-in
+(`draw`, `reveal`, `pulse`, `focus`) and respects reduced-motion preferences.
+Use `notePlacement()` for one-note bounded placement, but do not treat it as a
+whole-chart collision solver. `declutterLabels(items,{gap,min,max})` is a
+deterministic 1-D declutter; `directLabels(items,{axis,cross,gap,min,max,shape})`
+adds the leader line (it declutters labels along an axis and returns each placed
+point plus a leader path `d` for `ui-annotation__connector`) — neither owns
+scales, DOM, or 2-D placement. Status tones are only for status-bearing callouts.
+Keep charts sparse; dense mobile figures need horizontal scrolling, a simplified
+SVG, or complete caption/fallback text. Details: `docs/annotations.md`.
+Optional legends / data keys for charts and figures — opt-in, never in the
+default bundle. Reads the `--chart-*` tokens, so a key never drifts from its
+series:
+```html
+<link rel="stylesheet" href="@ponchia/ui/css/legend.css" />
+```
+Use a `ui-legend` container with `ui-legend__item` rows, each holding a
+`ui-legend__swatch` (decorative, `aria-hidden`) and a `ui-legend__label` (the
+required non-colour channel — WCAG 1.4.1; colour alone never carries meaning).
+Set the swatch colour inline (`style="--chart-color: var(--chart-3)"`, plus
+`--chart-pattern` to match a patterned mark) or with a `ui-legend__swatch--1..8`
+index helper. Variants: `ui-legend--vertical`/`--compact`/`--with-values`,
+`ui-legend--gradient` (+`--diverging`, with `ui-legend__track`/`__ticks`/`__tick`),
+and `ui-legend--threshold`. `ui.legend()`/`ui.legendItem()`/`ui.legendSwatch()`
+build the class strings. Interactive (series-toggling) legends are opt-in:
+author entries as `<button aria-pressed>` under `[data-bronto-legend]`, run
+`initLegend()` (or `useLegend()`), and listen for `bronto:legend:toggle`
+(`{ series, active }`) — Bronto flips the control state; you hide the series and
+own the `aria-live` announcement. Details: `docs/legends.md`.
+Optional text marks / evidence emphasis for running prose — opt-in, never in
+the default bundle. The prose counterpart to annotations (annotations call out a
+figure; marks call out a sentence):
+```html
+<link rel="stylesheet" href="@ponchia/ui/css/marks.css" />
+```
+Put `ui-mark` on a `<mark>` for inline emphasis (semantic, not just visual).
+Styles: default highlight, `ui-mark--underline`, `ui-mark--box`,
+`ui-mark--strike`. Tones: `ui-mark--accent` (the rationed accent),
+`--success`/`--warning`/`--danger`/`--info` (status-bearing only), `--muted`.
+`ui-mark--draw` sweeps the highlight in (reduced-motion-safe). `ui-bracket-note`
+(+ `ui-bracket-note__label`, tones `--accent`/`--warning`/`--danger`/`--info`)
+brackets a whole passage — the prose analogue of `ui-annotation--bracket`.
+`ui.mark({ style, tone, motion })` / `ui.bracketNote({ tone })` build the class
+strings. A mark is visual only; if the emphasis carries meaning the words don't,
+state it in the text (WCAG 1.4.1). Details: `docs/marks.md`.
+Optional connectors / leader lines between two DOM elements — opt-in, never in
+the default bundle. Pure geometry + an optional draw/track behavior; owns no
+layout:
+```html
+<link rel="stylesheet" href="@ponchia/ui/css/connectors.css" />
+```
+Place a `ui-connector` SVG (`data-bronto-connector`, `aria-hidden`) as an
+overlay inside a `position: relative` container holding both endpoints; set
+`data-from`/`data-to` (element ids), optional `data-shape`
+(straight|elbow|curve), `data-from-side`/`data-to-side`, and `data-end`
+(arrow|dot|none). `initConnectors()` (or `useConnectors()`) draws the path and
+redraws on resize/scroll. Tones `ui-connector--accent`/`--muted`/status,
+`ui-connector--dashed`, `ui-connector--draw`. Pure helpers from
+`@ponchia/ui/connectors` (`connectRects`, `connectorPath`, `arrowHead`,
+`anchorPoint`, …) return SVG strings for SSR/canvas. Details: `docs/connectors.md`.
+Optional spotlight / guided-focus overlay — opt-in, never in the default
+bundle. The visual language of a tour, NOT a tour engine (the host owns step
+order/advancing/visibility):
+```html
+<link rel="stylesheet" href="@ponchia/ui/css/spotlight.css" />
+```
+A `ui-spotlight` overlay (`data-bronto-spotlight`, `data-target=<element id>`)
+contains a `ui-spotlight__hole` (the box-shadow cutout) and a `ui-tour-note`
+callout (`__step`/`__title`/`__body`/`__actions`). `initSpotlight()` (or
+`useSpotlight()`) measures the target and sets `--spot-x/y/w/h`, re-placing on
+resize/scroll and when `data-target` changes — so advance a tour by updating
+`data-target`. `ui-spotlight--ring` adds a ring. The overlay is non-blocking by
+design; put the real guidance text in the focusable `ui-tour-note`. Details:
+`docs/spotlight.md`.
+Optional crosshair / readout for reading a value off a plot — opt-in, never in
+the default bundle. Reports the pointer position; the host maps it to data:
+```html
+<link rel="stylesheet" href="@ponchia/ui/css/crosshair.css" />
+```
+Mark the plot `[data-bronto-crosshair]` (position: relative) and put a
+`ui-crosshair` overlay inside it with `ui-crosshair__line ui-crosshair__line--x`
+and/or `--y`, optional `ui-crosshair__badge`, and a `ui-readout` chip.
+`initCrosshair()` (or `useCrosshair()`) sets `--crosshair-x/y` (px) on pointer
+move, toggles `is-active`, and dispatches `bronto:crosshair:move`
+({ x, y, fx, fy } — px + 0..1 fractions) / `bronto:crosshair:leave`. It does NOT
+find the nearest datum or map pixels→data (that needs your scales). `ui.crosshair({ muted })`.
+Details: `docs/crosshair.md`.
+Optional selection-state vocabulary — opt-in, cross-cutting, CSS only. The carve
+from brush/lasso: Bronto does not do region selection/hit-testing; it ships only
+the states an item can be in:
+```html
+<link rel="stylesheet" href="@ponchia/ui/css/selection.css" />
+```
+Apply `ui-sel` + `ui-sel--on` (selected), `ui-sel--off` (excluded), or
+`ui-sel--maybe` (live-brush candidate) to any data element (chart mark, table
+row, list item, map region) from YOUR selection/brush logic — Bronto only styles
+them. `ui.sel({ state: 'on'|'off'|'maybe' })`. Details: `docs/selection.md`.
+Optional source/citation/provenance trust layer — opt-in, CSS only, never in
+the default bundle. The grammar for "where did this come from?" in generated
+reports/AI output:
+```html
+<link rel="stylesheet" href="@ponchia/ui/css/sources.css" />
+```
+`ui-citation` (inline ref on a real `<a>`/`<button>`; `--chip` = named-source
+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
+default bundle. The states apps live in (saving/saved/queued/offline/stale/
+conflict/error/locked/reviewed/needs-review):
+```html
+<link rel="stylesheet" href="@ponchia/ui/css/state.css" />
+```
+`ui-state` (+`__label`/`__detail`) carries a tone dot + the canonical label;
+the `ui-state--saving`/`--saved`/… modifier bakes the tone, `ui-state--busy`
+pulses the indicator for
+in-progress states (reduced-motion-safe). `ui-syncbar` is a page/document
+save-status strip. The label IS the state (never colour alone); the host owns
+the state machine, retry, and persistence — persistent state gets persistent UI,
+not a toast. `ui.state({ state, busy })`. Details: `docs/state.md`.
+Optional generated-content / AI-trust surfaces — opt-in, CSS only, never in the
+default bundle. NOT a chat kit; the trust surfaces around generated content:
+```html
+<link rel="stylesheet" href="@ponchia/ui/css/generated.css" />
+```
+`ui-generated` (+`__label`) marks a machine-authored region; `ui-origin-label`
+(+`--ai`) tags origin ("AI generated" / "Human reviewed"); `ui-reasoning`
+(+`__body`) and `ui-tool-log` / `ui-tool-call` (+`__name`/`__status`/`__body`)
+are quiet native-`<details>` collapsibles for reasoning + tool traces. Bronto
+styles disclosure/origin/trace; the host owns model metadata, redaction, and
+safety. No confidence/verdict widget (don't fabricate precision). `ui.originLabel({ ai })`.
+Details: `docs/generated.md`.
+Optional workbench primitives for tool UIs — opt-in, CSS only, never in the
+default bundle:
+```html
+<link rel="stylesheet" href="@ponchia/ui/css/workbench.css" />
+```
+`ui-inspector` (+`__header`/`__body`) is a selected-object detail panel;
+`ui-property` (+`__label`/`__value`) is a denser key/value row for it;
+`ui-selectionbar` (+`__count`/`__actions`) is a raised action bar for the current
+selection (pair with `ui-sel` states on the items). Layout/affordances only —
+resizable split panes and drag handles are deferred. Class-only. Details:
+`docs/workbench.md`.
+Optional command palette — opt-in CSS shell (`css/command.css`) + `initCommand`
+behavior. Filter + keyboard-navigate a DOM-authored command list:
+```html
+<link rel="stylesheet" href="@ponchia/ui/css/command.css" />
+```
+`ui-command` (+`__input`/`__list`/`__group`/`__item`/`__shortcut`/`__meta`/
+`__empty`); `initCommand()` owns filtering, roving focus (Down/Up/Home/End),
+Enter→`bronto:command:select` ({value,label}) and Escape→`bronto:command:close`.
+The HOST owns the action registry + execution; NO global Cmd/Ctrl+K (open it
+yourself, e.g. a <dialog> via initDialog). Pairs with `ui-shortcut`. Binding:
+`useCommand()` (react/solid/qwik). Details: `docs/command.md`.
 Optional static report layer for LLM-authored HTML reports — opt-in, never in
 the default bundle. Pair it with the normal bundle, and add data-viz only when
 the report contains charts. For standalone browser HTML, use real URLs; package
@@ -119,7 +425,10 @@ Canonical report skeleton:
     <p class="ui-eyebrow">Report</p>
     <h1 class="ui-report__title">System review</h1>
     <p class="ui-report__subtitle">Static HTML, Chromium PDF-ready.</p>
-    <ol class="ui-report__meta"><li>2026-06-01</li><li>Generated</li></ol>
+    <ol class="ui-report__meta">
+      <li>2026-06-01</li>
+      <li>Generated</li>
+    </ol>
   </header>
   <section class="ui-report__section">
     <h2 class="ui-report__section-head">Executive summary</h2>
@@ -133,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)
@@ -145,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.
@@ -158,6 +480,15 @@ Read these from `node_modules/@ponchia/ui/` — no network needed:
 - `docs/reporting.md` — static/PDF-first report cookbook for LLM-authored
   reports, including report skeletons, chart rules, print utilities, and safety
   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.
@@ -165,12 +496,17 @@ 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,
   `initDotGlyph`, is declared in `behaviors/index.d.ts`.)
+- `annotations/index.d.ts` — no-dependency SVG path helpers for Bronto
+  annotation geometry.
 - `classes/vscode.css-custom-data.json` — editor autocomplete for tokens.
 ## Human-browsable references (not shipped in the npm tarball, by design)
@@ -182,12 +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.
+  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
@@ -195,4 +543,4 @@ Read these from `node_modules/@ponchia/ui/` — no network needed:
   tokens — re-point `--accent` (or a `data-bronto-skin` colorway), use status
   tokens for status, and `--chart-*` (from `css/dataviz.css`) for charts only.
   Don't add raw hues to components; `check:color-policy` enforces this.
-- Pre-1.0 SemVer: breaking changes ship in the *minor*. Pin `~0.x`.
+- Pre-1.0 SemVer: breaking changes ship in the _minor_. Pin `~0.x`.