@ponchia/ui 0.5.0 → 0.6.3

package/docs/legends.md

@@ -13,8 +13,9 @@ drifts from the series it describes.
 ```
 
 Bronto **paints and positions** the key; it owns no scales, no data→pixel
-mapping, and no series state. Pair it with Bronto's own `.ui-chart` bars, an
-SVG/canvas figure, or any external chart engine — the host owns the chart.
+mapping, and no series state. Pair it with any chart — a token-themed inline
+SVG, or an external engine like [Vega-Lite](./vega.md) — the host owns the
+chart.
 
 ## What it is not
 
@@ -47,7 +48,7 @@ Recommended structure: wrap the figure and its key in a `<figure>` with a
     <li class="ui-legend__item">
       <span
         class="ui-legend__swatch"
-        style="--chart-color: var(--chart-1); --chart-pattern: var(--chart-pattern-1)"
+        style="--chart-color: var(--chart-3); --chart-pattern: var(--chart-pattern-3)"
         aria-hidden="true"
       ></span>
       <span class="ui-legend__label">Research</span>
@@ -89,6 +90,25 @@ chart mark uses, or with a `--N` index helper for the categorical palette.
 `ui-legend__swatch--circle` and `ui-legend__swatch--line` change the chip shape
 (dot series, line series).
 
+A `ui-legend__symbol` chip is an `.ui-icon` mask — it needs a `--icon-mask` or it
+paints a solid square, like any [icon](./reference.md). There is **no `--glyph-*`
+token**: build the mask value with
+[`renderGlyph(name, { render: 'mask' })`](./reference.md) from `@ponchia/ui/glyphs`,
+e.g. `el.style.setProperty('--icon-mask', renderGlyph('circle', { render: 'mask' }).match(/--icon-mask:([^"]+)/)[1])`,
+or render the whole chip with `renderGlyph('circle', { render: 'mask', label })` and
+add the `ui-legend__symbol` class to it. And an **interactive** legend entry must be a real
+`<button>` (as in the example below) — a non-button `ui-legend__item` carrying
+`data-series` is not keyboard-reachable.
+
+**Keying the de-emphasised series.** In an accent-rationed chart — one mark
+painted with [`brontoVegaAccent`](./vega.md#spending-the-accent), the rest left
+quiet with `brontoVegaNeutral` — the quiet neutral **is** the last categorical
+series, `--chart-8` (`#4d5358`). So a legend that honestly mirrors that chart
+uses `ui-legend__swatch--1` for the highlighted entry and
+`ui-legend__swatch--8` for the "everything else" entry — both are real palette
+tokens, so the key never drifts from the marks and `check:legend` stays happy.
+Don't hand-roll a grey: `--chart-8` is the neutral by construction.
+
 ## Variants
 
 | Modifier | Effect |

package/docs/marks.md

@@ -44,6 +44,13 @@ Put `.ui-mark` on a `<mark>` so the emphasis is semantic, not just visual.
 `prefers-reduced-motion` (reduced motion shows the resting full highlight). It
 applies to the highlight fill, so pair it with the default (no style modifier).
 
+> **A mark is a behind-text highlight, not a filled chip.** The fill is a
+> low-alpha gradient *behind* the running text, so the text keeps its normal ink
+> and the contrast stays text-on-background — even `ui-mark--accent` is
+> contrast-safe by construction. Don't reach for `--on-accent` here (that ink is
+> for a *solid* accent fill, like a button or a D2 node); a `<mark>` never needs
+> it.
+
 ## Passage bracket — `.ui-bracket-note`
 
 Brackets a whole block and optionally labels it — the prose analogue of
@@ -56,8 +63,8 @@ Brackets a whole block and optionally labels it — the prose analogue of
 </blockquote>
 ```
 
-Tones: `--accent` (the rationed accent), `--warning`, `--danger`, `--info`. The
-default is a neutral bracket.
+Tones: `--accent` (the rationed accent), `--success`, `--warning`, `--danger`,
+`--info`. The default is a neutral bracket.
 
 ## Recipes
 

package/docs/mermaid.md

@@ -0,0 +1,169 @@
+# Mermaid
+
+[Mermaid](https://mermaid.js.org) renders diagrams (flowcharts, sequence, pie,
+git, gantt…) from text to **SVG**. `@ponchia/ui` does not render diagrams — it
+**themes** the ones you already have and lets you **annotate** them, the same way
+it dresses any other SVG figure in a report. Two things ship:
+
+- `@ponchia/ui/mermaid` — a resolved Mermaid `base` theme, per bronto theme.
+- `@ponchia/ui/mermaid.json` — the same data as plain JSON, for any consumer.
+
+Mermaid stays the consumer's renderer. This is config only: bronto never imports
+or runs Mermaid, and Mermaid is **not** a dependency.
+
+## Theme a diagram
+
+Mermaid's `base` theme is the only one meant to be customized. Hand it the
+bronto theme variables:
+
+```js
+import mermaid from 'mermaid';
+import { brontoMermaidTheme } from '@ponchia/ui/mermaid';
+
+mermaid.initialize(brontoMermaidTheme()); // light
+await mermaid.run();
+```
+
+`brontoMermaidTheme(theme)` returns `{ theme: 'base', themeVariables }` ready to
+spread into `initialize`. Pass `'dark'` for the dark palette, or read the active
+bronto theme:
+
+```js
+const theme = document.documentElement.dataset.theme === 'dark' ? 'dark' : 'light';
+mermaid.initialize(brontoMermaidTheme(theme));
+```
+
+You can also splice the variables into a single diagram via an init directive,
+or read the raw maps (`import { mermaid } from '@ponchia/ui/mermaid'` →
+`{ light, dark }`). For a build step or non-JS host, read
+`@ponchia/ui/mermaid.json` directly.
+
+**Over `http(s)`, import the helper from a CDN as an ES module** — no bundler.
+`tokens/mermaid.js` (the `@ponchia/ui/mermaid` entry) has **zero dependencies**,
+so it loads directly as a browser ES module; you get `brontoMermaidTheme(theme)`
+itself, not a frozen object to keep in sync. Pin the package version; this needs
+a real origin (not `file://` — inline or pre-render to SVG there, per the note
+below):
+
+```html
+<script type="module">
+  import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
+  import { brontoMermaidTheme } from 'https://cdn.jsdelivr.net/npm/@ponchia/ui@VERSION/tokens/mermaid.js';
+  mermaid.initialize(brontoMermaidTheme('light'));
+  await mermaid.run();
+</script>
+```
+
+> **file:// portability.** A report opened straight from disk (`file://`) cannot
+> `import` the `@ponchia/ui/mermaid` module **nor** `fetch('…/mermaid.json')` —
+> the browser blocks both across the `null`/file origin (CORS), exactly as with
+> [Vega](./vega.md#from-a-cdn-no-bundler). So for a double-clickable or PDF-bound
+> report either **inline the theme variables** (generate the paste-ready literal
+> with `npm run emit:theme mermaid light` / `dark` — guard it from token drift
+> with `npm run emit:theme:check <file>`) or, better, **pre-render to a frozen
+> SVG** with the Mermaid CLI (`mmdc`, below) so there is no runtime at all. Over
+> an `http(s)` origin the `import`/`fetch` forms both work.
+
+The result is monochrome surfaces and lines with the rationed accent reserved
+for notes — a diagram that looks like the rest of a bronto surface and
+**re-skins for free** when you change `--accent`, exactly like the chart palette.
+
+### Why resolved colours, not `var(--x)`
+
+Mermaid's theming engine derives shades (lighten/darken) from your seed colours,
+so it only understands real colours — a `var(--accent)` string breaks
+derivation. The theme map therefore ships **resolved hex/rgba per theme**,
+projected from the same token source that feeds
+[`tokens/resolved.json`](./architecture.md) and `charts.json`. That projection
+is the bridge a CSS-first system needs until Mermaid can read CSS variables
+directly. It also means the theme is **static per theme**: on a light/dark
+switch, re-`initialize` with the other palette and re-render.
+
+### Which diagrams get the palette
+
+- **Chart-like** diagrams carry a categorical series palette — **pie**
+  (`pie1`…`pie12`), **git** (`git0`…`git7`), and **user-journey**
+  (`fillType0`…`fillType7`) are wired to the CVD-safe
+  [charts palette](./legends.md) (series 1 = the live accent).
+- **Structural** diagrams — flowchart, sequence, class, ER, state — use the
+  monochrome node/edge/cluster grammar and spend the accent only on notes.
+- **Not themed: `gantt` and `timeline`.** Their colours come from
+  diagram-specific slots (`taskBkgColor`, `sectionBkgColor*`, `gridColor`,
+  `todayLineColor`, …) that the base `themeVariables` map does **not** set, so a
+  gantt/timeline renders with Mermaid's own off-brand defaults (red/grey bars),
+  not the bronto palette. For a **report timeline**, prefer the native,
+  fully-themed [`ui-timeline`](./reporting.md) primitive (it also prints and
+  needs no renderer); reach for a Mermaid gantt only when you specifically need
+  its scheduling layout, and accept its default colours.
+
+Pie wedge labels (`pieSectionTextColor`) sit on arbitrary palette colours; if a
+label is hard to read on a given wedge, prefer a legend or direct labels over
+recolouring.
+
+### Fit to small screens
+
+The theme map sets colours, not size — sizing stays Mermaid's. Keep `useMaxWidth`
+on (the default for most diagram types) so each SVG scales to its container
+instead of forcing page-wide horizontal scroll:
+
+```js
+mermaid.initialize({
+  ...brontoMermaidTheme(theme),
+  flowchart: { useMaxWidth: true },
+  sequence: { useMaxWidth: true },
+});
+```
+
+A genuinely wide diagram (a long flowchart, a big ER) can still be unreadable
+once squeezed onto a phone. Rather than let it overflow the page, wrap the render
+in a scroll container so the *diagram* scrolls, not the document — the same
+pattern the report layer uses for wide figures and tables:
+
+```css
+.diagram-scroll {
+  overflow-x: auto;
+}
+```
+
+## Annotate a diagram
+
+Mermaid output is SVG, and the [annotation layer](./annotations.md) is
+renderer-agnostic SVG — so a `<g class="ui-annotation">` callout composes onto a
+rendered diagram the same as onto any figure. bronto supplies the geometry and
+the styling; **placing a callout on a specific node is yours**, because that
+means reading Mermaid's laid-out coordinates, which bronto deliberately does not
+own (no scales, no DOM, no hit-testing — see [annotations.md](./annotations.md)).
+
+The robust path is **build-time**, mirroring the
+[static-report recipe](./annotations.md#using-the-helpers-in-a-static-no-js-report):
+
+1. Pre-render the diagram to a frozen SVG with the Mermaid CLI
+   (`mmdc -t base -i diagram.mmd -o diagram.svg`, feeding the same
+   `themeVariables`).
+2. From that SVG, read the target node's box (`getBBox()` / the node's
+   `transform`), accounting for the diagram's root `<g>` translate and the
+   `viewBox`.
+3. Compute the callout strings with `@ponchia/ui/annotations` and paste a
+   `<g class="ui-annotation …">` into the SVG at those coordinates.
+
+The output is a static, on-brand, annotated SVG with no runtime — ideal for the
+[report layer](./reporting.md).
+
+To annotate a **live** client render instead, run the same measure-and-inject
+pass on the SVG returned by `mermaid.render()`, after it is in the DOM. Two
+honest caveats, both inherent to overlaying a foreign renderer (not bronto
+limitations):
+
+- **Mermaid's internal SVG structure is not a public contract.** Node ids and
+  classes are undocumented and have changed across major versions. Match nodes
+  by your own author-supplied id substring, measure positions rather than
+  hard-coding them, and **pin your Mermaid version**.
+- **Every re-render replaces the SVG**, discarding injected overlays. Re-apply
+  the annotation pass after each `render()` / theme switch / resize.
+
+## Scope
+
+bronto owns the theme map (gated: every value resolves to a colour, both themes,
+no `var()` leaks) and the annotation geometry. It does **not** own Mermaid's
+rendering, its internal DOM, or its re-render lifecycle — those stay Mermaid's,
+and the overlay above is a documented composition, not a shipped runtime binding.

package/docs/reference.md

@@ -9,8 +9,11 @@ rendering of every class is the kitchen-sink demo:
 **<https://ponchia.github.io/bronto-ui/>**. Theming knobs and the token
 contract: [docs/theming.md](theming.md).
 
-- 474 classes across 148 component groups
+- 529 classes across 161 component groups
 - Import the typed registry: `import { cls, ui, cx } from '@ponchia/ui/classes'`
+- Validate markup as data (no JS/TS): `@ponchia/ui/classes.json` — the same
+  vocabulary as language-neutral JSON (`groups`, `classes`, `states`,
+  `customProperties`), for an external linter or non-JS host
 - Tokens as data: `import { cssVars, tokens, themeColor } from '@ponchia/ui/tokens'`
 
 ## Classes
@@ -34,7 +37,7 @@ each one matches a real selector in the stylesheet.
 | --- | --- | --- |
 | `cls.alert` | `ui-alert` | base |
 | `cls.alertBody` | `ui-alert__body` | part |
-| `cls.alertDismiss` | `ui-alert__dismiss` | part |
+| `cls.alertClose` | `ui-alert__close` | part |
 | `cls.alertTitle` | `ui-alert__title` | part |
 | `cls.alertAccent` | `ui-alert--accent` | modifier |
 | `cls.alertDanger` | `ui-alert--danger` | modifier |
@@ -162,7 +165,6 @@ each one matches a real selector in the stylesheet.
 | `cls.appRailAccount` | `ui-app-rail__account` | part |
 | `cls.appRailBrand` | `ui-app-rail__brand` | part |
 | `cls.appRailFoot` | `ui-app-rail__foot` | part |
-| `cls.appRailToggle` | `ui-app-rail__toggle` | part |
 
 ### `.ui-app-shell`
 
@@ -221,6 +223,7 @@ each one matches a real selector in the stylesheet.
 | `cls.bracketNoteAccent` | `ui-bracket-note--accent` | modifier |
 | `cls.bracketNoteDanger` | `ui-bracket-note--danger` | modifier |
 | `cls.bracketNoteInfo` | `ui-bracket-note--info` | modifier |
+| `cls.bracketNoteSuccess` | `ui-bracket-note--success` | modifier |
 | `cls.bracketNoteWarning` | `ui-bracket-note--warning` | modifier |
 
 ### `.ui-breadcrumb`
@@ -242,6 +245,18 @@ each one matches a real selector in the stylesheet.
 | --- | --- | --- |
 | `cls.breakBefore` | `ui-break-before` | base |
 
+### `.ui-bullet`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.bullet` | `ui-bullet` | base |
+| `cls.bulletLabel` | `ui-bullet__label` | part |
+| `cls.bulletMeasure` | `ui-bullet__measure` | part |
+| `cls.bulletMeasureAccent` | `ui-bullet__measure--accent` | modifier |
+| `cls.bulletMeasureNeg` | `ui-bullet__measure--neg` | modifier |
+| `cls.bulletMeasurePos` | `ui-bullet__measure--pos` | modifier |
+| `cls.bulletTarget` | `ui-bullet__target` | part |
+
 ### `.ui-button`
 
 | Registry key | Class | Kind |
@@ -289,19 +304,6 @@ each one matches a real selector in the stylesheet.
 | --- | --- | --- |
 | `cls.center` | `ui-center` | base |
 
-### `.ui-chart`
-
-| Registry key | Class | Kind |
-| --- | --- | --- |
-| `cls.chart` | `ui-chart` | base |
-| `cls.chartBar` | `ui-chart__bar` | part |
-| `cls.chartCaption` | `ui-chart__caption` | part |
-| `cls.chartFallback` | `ui-chart__fallback` | part |
-| `cls.chartFill` | `ui-chart__fill` | part |
-| `cls.chartLabel` | `ui-chart__label` | part |
-| `cls.chartPlot` | `ui-chart__plot` | part |
-| `cls.chartTrack` | `ui-chart__track` | part |
-
 ### `.ui-check`
 
 | Registry key | Class | Kind |
@@ -329,6 +331,19 @@ each one matches a real selector in the stylesheet.
 | `cls.cluster` | `ui-cluster` | base |
 | `cls.clusterBetween` | `ui-cluster--between` | modifier |
 
+### `.ui-code`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.code` | `ui-code` | base |
+| `cls.codeBody` | `ui-code__body` | part |
+| `cls.codeHead` | `ui-code__head` | part |
+| `cls.codeLine` | `ui-code__line` | part |
+| `cls.codeLineAdd` | `ui-code__line--add` | modifier |
+| `cls.codeLineHl` | `ui-code__line--hl` | modifier |
+| `cls.codeLineRemove` | `ui-code__line--remove` | modifier |
+| `cls.codeNumbered` | `ui-code--numbered` | modifier |
+
 ### `.ui-combobox`
 
 | Registry key | Class | Kind |
@@ -352,6 +367,15 @@ each one matches a real selector in the stylesheet.
 | `cls.commandMeta` | `ui-command__meta` | part |
 | `cls.commandShortcut` | `ui-command__shortcut` | part |
 
+### `.ui-compare`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.compare` | `ui-compare` | base |
+| `cls.compareCol` | `ui-compare__col` | part |
+| `cls.compareHead` | `ui-compare__head` | part |
+| `cls.compare2up` | `ui-compare--2up` | modifier |
+
 ### `.ui-connector`
 
 | Registry key | Class | Kind |
@@ -393,6 +417,38 @@ each one matches a real selector in the stylesheet.
 | `cls.crosshairLineY` | `ui-crosshair__line--y` | modifier |
 | `cls.crosshairMuted` | `ui-crosshair--muted` | modifier |
 
+### `.ui-def`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.def` | `ui-def` | base |
+
+### `.ui-delta`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.delta` | `ui-delta` | base |
+| `cls.deltaDown` | `ui-delta--down` | modifier |
+| `cls.deltaFlat` | `ui-delta--flat` | modifier |
+| `cls.deltaInvert` | `ui-delta--invert` | modifier |
+| `cls.deltaUp` | `ui-delta--up` | modifier |
+
+### `.ui-diff`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.diff` | `ui-diff` | base |
+| `cls.diffCode` | `ui-diff__code` | part |
+| `cls.diffHead` | `ui-diff__head` | part |
+| `cls.diffHunk` | `ui-diff__hunk` | part |
+| `cls.diffLn` | `ui-diff__ln` | part |
+| `cls.diffPane` | `ui-diff__pane` | part |
+| `cls.diffRow` | `ui-diff__row` | part |
+| `cls.diffRowAdd` | `ui-diff__row--add` | modifier |
+| `cls.diffRowContext` | `ui-diff__row--context` | modifier |
+| `cls.diffRowRemove` | `ui-diff__row--remove` | modifier |
+| `cls.diffSplit` | `ui-diff--split` | modifier |
+
 ### `.ui-display`
 
 | Registry key | Class | Kind |
@@ -510,6 +566,14 @@ each one matches a real selector in the stylesheet.
 | `cls.generated` | `ui-generated` | base |
 | `cls.generatedLabel` | `ui-generated__label` | part |
 
+### `.ui-glossary`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.glossary` | `ui-glossary` | base |
+| `cls.glossaryDef` | `ui-glossary__def` | part |
+| `cls.glossaryTerm` | `ui-glossary__term` | part |
+
 ### `.ui-grid`
 
 | Registry key | Class | Kind |
@@ -556,7 +620,7 @@ each one matches a real selector in the stylesheet.
 | --- | --- | --- |
 | `cls.inspector` | `ui-inspector` | base |
 | `cls.inspectorBody` | `ui-inspector__body` | part |
-| `cls.inspectorHeader` | `ui-inspector__header` | part |
+| `cls.inspectorHead` | `ui-inspector__head` | part |
 
 ### `.ui-kbd`
 
@@ -630,6 +694,12 @@ each one matches a real selector in the stylesheet.
 | `cls.linkArrow` | `ui-link--arrow` | modifier |
 | `cls.linkCta` | `ui-link--cta` | modifier |
 
+### `.ui-marginnote`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.marginnote` | `ui-marginnote` | base |
+
 ### `.ui-mark`
 
 | Registry key | Class | Kind |
@@ -680,8 +750,12 @@ each one matches a real selector in the stylesheet.
 | --- | --- | --- |
 | `cls.meter` | `ui-meter` | base |
 | `cls.meterFill` | `ui-meter__fill` | part |
+| `cls.meterLabel` | `ui-meter__label` | part |
+| `cls.meterRow` | `ui-meter__row` | part |
+| `cls.meterValue` | `ui-meter__value` | part |
 | `cls.meterAccent` | `ui-meter--accent` | modifier |
 | `cls.meterDanger` | `ui-meter--danger` | modifier |
+| `cls.meterInfo` | `ui-meter--info` | modifier |
 | `cls.meterSuccess` | `ui-meter--success` | modifier |
 | `cls.meterWarning` | `ui-meter--warning` | modifier |
 
@@ -840,7 +914,7 @@ each one matches a real selector in the stylesheet.
 | `cls.reportFigure` | `ui-report__figure` | part |
 | `cls.reportFinding` | `ui-report__finding` | part |
 | `cls.reportFootnotes` | `ui-report__footnotes` | part |
-| `cls.reportHeader` | `ui-report__header` | part |
+| `cls.reportHead` | `ui-report__head` | part |
 | `cls.reportMeta` | `ui-report__meta` | part |
 | `cls.reportSection` | `ui-report__section` | part |
 | `cls.reportSectionUnnumbered` | `ui-report__section--unnumbered` | modifier |
@@ -926,6 +1000,13 @@ each one matches a real selector in the stylesheet.
 | --- | --- | --- |
 | `cls.sidebar` | `ui-sidebar` | base |
 
+### `.ui-sidenote`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.sidenote` | `ui-sidenote` | base |
+| `cls.sidenoteRef` | `ui-sidenote__ref` | part |
+
 ### `.ui-sitefooter`
 
 | Registry key | Class | Kind |
@@ -985,6 +1066,16 @@ each one matches a real selector in the stylesheet.
 | `cls.sourceList` | `ui-source-list` | base |
 | `cls.sourceListItem` | `ui-source-list__item` | part |
 
+### `.ui-spark`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.spark` | `ui-spark` | base |
+| `cls.sparkBar` | `ui-spark__bar` | part |
+| `cls.sparkBarAccent` | `ui-spark__bar--accent` | modifier |
+| `cls.sparkBarNeg` | `ui-spark__bar--neg` | modifier |
+| `cls.sparkBarPos` | `ui-spark__bar--pos` | modifier |
+
 ### `.ui-spinner`
 
 | Registry key | Class | Kind |
@@ -1003,6 +1094,7 @@ each one matches a real selector in the stylesheet.
 
 | Registry key | Class | Kind |
 | --- | --- | --- |
+| `cls.src` | `ui-src` | base |
 | `cls.srcConflict` | `ui-src--conflict` | modifier |
 | `cls.srcGenerated` | `ui-src--generated` | modifier |
 | `cls.srcReviewed` | `ui-src--reviewed` | modifier |
@@ -1115,7 +1207,6 @@ each one matches a real selector in the stylesheet.
 | `cls.tableComfortable` | `ui-table--comfortable` | modifier |
 | `cls.tableDense` | `ui-table--dense` | modifier |
 | `cls.tableLined` | `ui-table--lined` | modifier |
-| `cls.tableLoading` | `ui-table--loading` | modifier |
 | `cls.tableSelectable` | `ui-table--selectable` | modifier |
 
 ### `.ui-table-wrap`
@@ -1123,6 +1214,7 @@ each one matches a real selector in the stylesheet.
 | Registry key | Class | Kind |
 | --- | --- | --- |
 | `cls.tableWrap` | `ui-table-wrap` | base |
+| `cls.tableLoading` | `ui-table-wrap--loading` | modifier |
 
 ### `.ui-tabs`
 
@@ -1145,12 +1237,24 @@ each one matches a real selector in the stylesheet.
 | --- | --- | --- |
 | `cls.tags` | `ui-tags` | base |
 
+### `.ui-term`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.term` | `ui-term` | base |
+
 ### `.ui-textarea`
 
 | Registry key | Class | Kind |
 | --- | --- | --- |
 | `cls.textarea` | `ui-textarea` | base |
 
+### `.ui-textref`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.textref` | `ui-textref` | base |
+
 ### `.ui-themetoggle`
 
 | Registry key | Class | Kind |
@@ -1189,6 +1293,15 @@ each one matches a real selector in the stylesheet.
 | `cls.toastStack` | `ui-toast-stack` | base |
 | `cls.toastStackAssertive` | `ui-toast-stack--assertive` | modifier |
 
+### `.ui-toc`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.toc` | `ui-toc` | base |
+| `cls.tocLink` | `ui-toc__link` | part |
+| `cls.tocList` | `ui-toc__list` | part |
+| `cls.tocTitle` | `ui-toc__title` | part |
+
 ### `.ui-tool-call`
 
 | Registry key | Class | Kind |
@@ -1221,6 +1334,16 @@ each one matches a real selector in the stylesheet.
 | `cls.tourNoteStep` | `ui-tour-note__step` | part |
 | `cls.tourNoteTitle` | `ui-tour-note__title` | part |
 
+### `.ui-tree`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.tree` | `ui-tree` | base |
+| `cls.treeBranch` | `ui-tree__branch` | part |
+| `cls.treeLabel` | `ui-tree__label` | part |
+| `cls.treeLeaf` | `ui-tree__leaf` | part |
+| `cls.treeSummary` | `ui-tree__summary` | part |
+
 ### `.ui-visually-hidden`
 
 | Registry key | Class | Kind |
@@ -1244,11 +1367,19 @@ registry consumer should reach for these instead of re-implementing
 | Class | Where | Effect |
 | --- | --- | --- |
 | `.ui-table .is-num` | numeric `<td>`/`<th>` | tabular figures + end-aligned (the canonical numeric cell) |
-| `.ui-table .is-pos` | numeric `<td>` | positive-delta tone |
-| `.ui-table .is-neg` | numeric `<td>` | negative-delta tone |
+| `.ui-table .is-pos` | numeric `<td>`, `.ui-stat__delta` | positive-delta tone |
+| `.ui-table .is-neg` | numeric `<td>`, `.ui-stat__delta` | negative-delta tone |
+| `.ui-table .is-key` | `<td>`/`<th>` | emphasised key column |
 
 For numeric text *outside* a table, use the `ui-num` primitive
-(`ui.num({ tone })`), which carries the same tabular/aligned/tone intent.
+(`ui.num({ tone })`), which carries the same tabular/aligned/tone intent; for
+a trend figure use `ui-delta` (`ui.delta({ dir, invert })`). The full,
+machine-readable list of these `is-*` state hooks — and the author-set inline
+custom properties (`--chart-color`, `--chart-pattern`, `--value`, and the
+**required** `--icon-mask` on `.ui-icon` and `--ui-vt-name` on `.ui-vt` —
+without which those classes render a solid square / do nothing) — is in
+[`@ponchia/ui/classes.json`](../classes/classes.json)
+(`states` / `customProperties`).
 
 ## Composition & state (read before re-implementing glue)
 
@@ -1264,18 +1395,58 @@ works in any framework without a binding layer:
 - **Button loading** — set `aria-busy="true"` (and `disabled`) on
   `ui-button`; the leading spinner is injected by CSS with no extra
   markup or class. `ui-button--sm`/`--lg` size it.
-- **Badge tone** — `ui.badge({ tone })` emits the framework tone
-  (`accent|success|warning|danger|info|muted`). Mapping an app's own variant
+- **Badge tone** — `ui.badge({ tone })` emits the badge tone
+  (`accent|success|warning|danger|info|muted`). The set is badge-specific, not a
+  universal vocabulary — `muted` is a badge/neutral tone, absent from the status
+  families (`ui-alert`/`ui-toast`/`ui-meter`/`ui-dot`); the builders warn on an
+  out-of-set tone (see usage.md). Mapping an app's own variant
   vocabulary onto a tone is application logic, not a framework class.
 - **Modal** — native `<dialog>` gets backdrop + top-layer + focus-trap
   free. For a controlled/portal modal, add `is-open`
   (`ui.modal({ open: true })`) for the same skin/layout; the
-  backdrop and focus-trap are then yours.
+  backdrop, top-layer stacking AND focus-trap are then yours (`.is-open`
+  is a bare grid — it does not float or stack on its own).
+- **Current page** — mark the active link with `aria-current="page"`; it is
+  the programmatic cue the navs honour (`ui-sitenav`, `ui-app-nav`). The
+  `.is-active` class is the visual-only equivalent on `ui-app-nav`/`ui-tab`;
+  prefer `aria-current` so assistive tech announces the current page.
+- **Form validation wiring** — `initFormValidation` (`@ponchia/ui/behaviors`)
+  reads these attributes; they ARE the contract, not styling. Markup that omits
+  them renders but the behavior silently no-ops: `data-bronto-validate` on the
+  `<form>`; an optional empty `[data-bronto-error]` node per field (it falls
+  back to the field's `.ui-hint`, restoring the help text when valid again); a
+  `[data-bronto-error-summary]` (`.ui-error-summary`) block. The combobox
+  reads `[data-bronto-combobox]` + per-option `data-value` and emits
+  `bronto:change` (`{ detail: { value, label } }`) on selection — `label` is the
+  chosen option's text, so a live region can announce it without re-reading the DOM;
+  the interactive
+  legend emits `bronto:legend:toggle` (`{ detail: { series, active } }`).
+- **Status indicator** — `ui-status` carries no dot of its own: compose it with
+  a `.ui-dot` child + a text label, e.g.
+  `<span class="ui-status"><span class="ui-dot ui-dot--success"></span> Live</span>`.
+  (`ui-state` instead bakes in its own dot + the full tone vocabulary — pick
+  one.) A semantic `ui-dot--success|warning|danger|info` is colour-only outside
+  forced-colors, so it ALWAYS needs an adjacent text/aria label — never ship a
+  bare coloured dot as the sole signal.
+- **Opt-in component CSS** — a few classes are not in the core bundle and need
+  their leaf imported, or they render unstyled: `ui-property`/`ui-readout` →
+  `@ponchia/ui/css/workbench.css`; `ui-mark`/`ui-bracket-note` →
+  `@ponchia/ui/css/marks.css`; the analytical leaves (`ui-annotations`,
+  `ui-crosshair`, `ui-spotlight`, …) → their matching leaf.
+- **Loaders need their children** — `ui-dotspinner` requires exactly eight
+  `<i>` children, `ui-dotloader` three `<span>`, and a static `ui-dotbar`
+  lights a segment with `<i class="is-on">`. A childless
+  `<span class="ui-dotspinner">` renders nothing.
+- **`ui-caret` is a typing cursor**, not a dropdown chevron — a blinking block
+  caret. It is **pure CSS** (a `uiBlink` keyframe on `::after`); it needs no
+  behavior — do NOT call `initDotGlyph` to animate it — and it is decorative, so
+  keep it out of the a11y tree (`aria-hidden`). For a disclosure/affordance arrow
+  use `ui-link--arrow` (`ui.link({ arrow: true })`).
 
 ## Tokens
 
 Exact mirror of the `:root` blocks in `css/tokens.css`
-(`check-tokens` enforces parity). DTCG export:
+(`check-fresh` enforces parity). DTCG export:
 [`@ponchia/ui/tokens.dtcg.json`](../tokens/tokens.dtcg.json).
 
 ### Global (scales — shared by both themes)
@@ -1298,6 +1469,8 @@ Exact mirror of the `:root` blocks in `css/tokens.css`
 | `--sans` | `'Inter', 'SF Pro Text', -apple-system, BlinkMacSystemFont, 'Segoe UI', system-ui, sans-serif` |
 | `--dot-font` | `'Doto', var(--mono)` |
 | `--display` | `var(--dot-font)` |
+| `--display-weight` | `700` |
+| `--display-weight-strong` | `800` |
 | `--text-2xs` | `0.68rem` |
 | `--text-xs` | `0.76rem` |
 | `--text-sm` | `0.86rem` |
@@ -1371,6 +1544,7 @@ Exact mirror of the `:root` blocks in `css/tokens.css`
 | `--accent-ramp-end` | `#ffffff` |
 | `--accent-strong` | `color-mix(in srgb, var(--accent) 83%, #000)` |
 | `--accent-text` | `var(--accent-strong)` |
+| `--on-accent` | `var(--button-text)` |
 | `--accent-soft` | `color-mix(in srgb, var(--accent) 10%, transparent)` |
 | `--success` | `#2f7d4f` |
 | `--success-soft` | `rgb(47, 125, 79, 0.12)` |
@@ -1408,6 +1582,7 @@ Exact mirror of the `:root` blocks in `css/tokens.css`
 | `--accent-ramp-end` | `#000000` |
 | `--accent-strong` | `color-mix(in srgb, var(--accent) 84%, #fff)` |
 | `--accent-text` | `var(--accent-strong)` |
+| `--on-accent` | `var(--button-text)` |
 | `--accent-soft` | `color-mix(in srgb, var(--accent) 14%, transparent)` |
 | `--success` | `#4ec27e` |
 | `--success-soft` | `rgb(78, 194, 126, 0.14)` |