@ponchia/ui 0.6.0 → 0.6.3

package/docs/code.md

@@ -0,0 +1,76 @@
+# Code
+
+`@ponchia/ui/css/code.css` is an opt-in chrome for **fenced code** — the surface
+for code-as-evidence in changelogs, version history, config snippets, and
+generated reports. It paints the frame, an optional line-number gutter, and
+add / remove / highlight line states. Its sibling is [diff.css](diff.md)
+(multi-column line/row diffs); the two share one change vocabulary —
+`--add` / `--remove` (`ui-code__line--remove` ↔ `ui-diff__row--remove`).
+
+```css
+@import '@ponchia/ui';
+@import '@ponchia/ui/css/code.css';
+```
+
+## Boundary — it never parses
+
+Bronto owns the chrome; it does **not** tokenize or highlight syntax. The host
+supplies the coloured token spans — hand-written, or from a real highlighter.
+The shipped [`shiki/nothing.json`](../shiki/nothing.json) theme makes Shiki emit
+spans with bronto token colours, so Shiki output drops straight in. A bronto
+class that tried to parse source would cross the same line that removed the
+chart renderer in 0.6.0.
+
+## Markup
+
+```html
+<figure class="ui-code ui-code--numbered">
+  <figcaption class="ui-code__head">theme.css</figcaption>
+  <pre class="ui-code__body"><code><span class="ui-code__line">.ui-diff {</span>
+<span class="ui-code__line ui-code__line--remove">  font-size: var(--text-sm);</span>
+<span class="ui-code__line ui-code__line--add">  font-size: var(--text-xs);</span>
+<span class="ui-code__line ui-code__line--hl">  line-height: 1.6;</span>
+<span class="ui-code__line">}</span></code></pre>
+</figure>
+```
+
+- `ui-code--numbered` turns on the gutter; it numbers each `.ui-code__line` with
+  a CSS counter (no host bookkeeping).
+- Each token span the host emits lives **inside** `.ui-code__line`; Bronto never
+  touches it.
+- Plain text inside `.ui-code__body` (no `.ui-code__line` wrappers) renders as an
+  unnumbered code block — the line grammar is opt-in.
+
+## Class reference
+
+| Class | Role |
+| --- | --- |
+| `.ui-code` | The `<figure>` frame. |
+| `.ui-code--numbered` | Show the line-number gutter. |
+| `.ui-code__head` | A filename / language bar (use on `<figcaption>`). |
+| `.ui-code__body` | The `<pre>` scroll/wrap region. |
+| `.ui-code__line` | One line — the unit numbered + state-tinted. |
+| `.ui-code__line--add` | Added line (green wash). |
+| `.ui-code__line--remove` | Removed line (red wash). |
+| `.ui-code__line--hl` | Neutral highlight / call-out (accent wash, not a change). |
+
+## Recipes
+
+```js
+import { ui } from '@ponchia/ui/classes';
+
+ui.code({ numbered: true });     // "ui-code ui-code--numbered"
+ui.codeLine({ change: 'add' });  // "ui-code__line ui-code__line--add"
+ui.codeLine({ change: 'hl' });   // "ui-code__line ui-code__line--hl"
+ui.codeLine();                   // "ui-code__line"
+```
+
+## Accessibility & robustness
+
+- **Line states never rely on colour.** In forced-colors mode each
+  add/remove/hl line gains an inline-start border, and the tints are forced through
+  `print-color-adjust: exact`.
+- **Long lines wrap** rather than scroll, so the block prints cleanly.
+- **Line numbers** are generated content (`user-select: none`), so copying the
+  block yields clean code with no line numbers.
+- Keep real text in the `<code>`; don't encode meaning only in a tint.

package/docs/d2.md

@@ -43,9 +43,10 @@ For a build step or non-JS host, read `@ponchia/ui/d2.json` directly.
 > [Vega](./vega.md#from-a-cdn-no-bundler) and [Mermaid](./mermaid.md#theme-a-diagram).
 > This is rarely an issue for D2, whose native path is **build-time
 > pre-rendering** to a frozen SVG (no client runtime — see below), but if you do
-> theme D2 in the browser over `file://`, **inline** the slot map (paste the
-> object from `d2.json`) rather than importing it. Over `http(s)` the
-> `import`/`fetch` forms both work.
+> theme D2 in the browser over `file://`, **inline** the slot map (generate the
+> paste-ready literal with `npm run emit:theme d2 light` / `dark`, and guard it
+> against token drift with `npm run emit:theme:check <file>`) rather than
+> importing it. Over `http(s)` the `import`/`fetch` forms both work.
 
 ### Why resolved colours, not `var(--x)`
 

package/docs/diff.md

@@ -0,0 +1,146 @@
+# Diff
+
+`@ponchia/ui/css/diff.css` is an opt-in change-review grammar — the surface for
+showing what **changed**: code review, changelogs, version history, config
+diffs, and generated reports. Marks call out a sentence; diff calls out a line.
+Its sibling is [code.css](code.md) (single-file fenced code); the two share one
+change vocabulary — `--add` / `--remove` (`ui-diff__row--remove` ↔
+`ui-code__line--remove`).
+
+```css
+@import '@ponchia/ui';
+@import '@ponchia/ui/css/diff.css';
+```
+
+```html
+<!-- node_modules / CDN: source css/ → built dist/css/ -->
+<link rel="stylesheet" href="./node_modules/@ponchia/ui/dist/css/diff.css" />
+```
+
+## Boundary — what Bronto owns vs. what you own
+
+Bronto paints the gutter grammar. **You** pre-classify each row (`add` /
+`remove` / `context`), compute the hunks, and align the two sides in split
+view. Bronto never parses or diffs source — that needs your tokenizer and your
+alignment, the same line that removed the local chart renderer in `0.6.0`. Feed
+it rows that are already classified by your diff engine (`jsdiff`, `git`, a
+language server, …).
+
+## Unified view — `.ui-diff`
+
+Rows are direct children of `.ui-diff` (optionally grouped in a
+`.ui-diff__hunk`). Columns are `[old-ln] [new-ln] [code]`. Mark each changed row
+`--add` / `--remove`, and leave unchanged rows `--context`. Line numbers are
+decorative — keep them `aria-hidden`; the `__code` cell carries the content.
+
+```html
+<div class="ui-diff">
+  <div class="ui-diff__hunk">
+    <div class="ui-diff__head">@@ -12,6 +12,6 @@ .ui-diff</div>
+
+    <div class="ui-diff__row ui-diff__row--context">
+      <span class="ui-diff__ln" aria-hidden="true">12</span>
+      <span class="ui-diff__ln" aria-hidden="true">12</span>
+      <code class="ui-diff__code">  border: 1px solid var(--line);</code>
+    </div>
+
+    <div class="ui-diff__row ui-diff__row--remove">
+      <span class="ui-diff__ln" aria-hidden="true">13</span>
+      <span class="ui-diff__ln" aria-hidden="true"></span>
+      <code class="ui-diff__code">  font-size: var(--text-sm);</code>
+    </div>
+
+    <div class="ui-diff__row ui-diff__row--add">
+      <span class="ui-diff__ln" aria-hidden="true"></span>
+      <span class="ui-diff__ln" aria-hidden="true">13</span>
+      <code class="ui-diff__code">  font-size: var(--text-xs);</code>
+    </div>
+  </div>
+</div>
+```
+
+A removed row leaves the **new** line-number cell empty; an added row leaves the
+**old** one empty. The `+` / `−` gutter glyph is painted for you from the row
+modifier.
+
+## Split view — `.ui-diff--split`
+
+`.ui-diff--split` lays two `.ui-diff__pane` columns side by side (old | new),
+each its own `[ln] [code]` grid. Put `--remove` / `--context` rows in the left
+pane and `--add` / `--context` rows in the right. You align the panes by
+emitting matching row counts (filler `--context` rows where one side is empty).
+
+```html
+<div class="ui-diff ui-diff--split">
+  <div class="ui-diff__pane">
+    <div class="ui-diff__row ui-diff__row--context">
+      <span class="ui-diff__ln" aria-hidden="true">1</span>
+      <code class="ui-diff__code">retries: 3</code>
+    </div>
+    <div class="ui-diff__row ui-diff__row--remove">
+      <span class="ui-diff__ln" aria-hidden="true">2</span>
+      <code class="ui-diff__code">timeout: 30</code>
+    </div>
+  </div>
+  <div class="ui-diff__pane">
+    <div class="ui-diff__row ui-diff__row--context">
+      <span class="ui-diff__ln" aria-hidden="true">1</span>
+      <code class="ui-diff__code">retries: 3</code>
+    </div>
+    <div class="ui-diff__row ui-diff__row--add">
+      <span class="ui-diff__ln" aria-hidden="true">2</span>
+      <code class="ui-diff__code">timeout: 10</code>
+    </div>
+  </div>
+</div>
+```
+
+For a hard before/after of two whole files, you can also drop two plain
+`.ui-diff` blocks into a [`.ui-compare--2up`](./reporting.md) layout.
+
+## Class reference
+
+| Class | Role |
+| --- | --- |
+| `.ui-diff` | The grid container (unified view). |
+| `.ui-diff--split` | Two-pane (old \| new) layout modifier. |
+| `.ui-diff__pane` | One column in split view; its own `[ln] [code]` grid. |
+| `.ui-diff__hunk` | Optional `role="rowgroup"` wrapper for a hunk (layout-transparent). |
+| `.ui-diff__head` | A hunk / file header row, spanning all columns. |
+| `.ui-diff__row` | A line row (layout-transparent; the cells are the grid items). |
+| `.ui-diff__row--add` | Added line — green tint + `+` gutter glyph. |
+| `.ui-diff__row--remove` | Removed line — red tint + `−` gutter glyph. |
+| `.ui-diff__row--context` | Unchanged line — no tint, blank gutter. |
+| `.ui-diff__ln` | A line-number gutter cell (`tabular-nums`, `user-select:none`; keep it `aria-hidden`). |
+| `.ui-diff__code` | A code cell. Long lines wrap (no horizontal scroll), so it prints cleanly. |
+
+## Recipes
+
+```js
+import { ui } from '@ponchia/ui/classes';
+
+ui.diff();                       // "ui-diff"
+ui.diff({ split: true });        // "ui-diff ui-diff--split"
+ui.diffRow({ change: 'add' });   // "ui-diff__row ui-diff__row--add"
+ui.diffRow({ change: 'remove' }); // "ui-diff__row ui-diff__row--remove"
+ui.diffRow();                    // "ui-diff__row"  (use --context for an explicit unchanged row)
+```
+
+## Accessibility & robustness
+
+- **Redundant channel (WCAG 1.4.1).** Add/remove is never colour-only: the
+  `+` / `−` gutter glyph is generated content, so it survives **forced colours**
+  and **print**, where the tone tint is dropped. In forced-colors mode the
+  changed code cell also gains an inline-start border.
+- **Print.** Tints are forced through with `print-color-adjust: exact`, and long
+  lines wrap rather than clip — the diff survives the PDF pipeline.
+- **Line numbers** are decorative: `aria-hidden` them and they stay out of a
+  copy selection (`user-select: none`), so copying the diff yields clean code.
+- **Semantics** live in your markup. By default the surface is role-free: with
+  the line numbers `aria-hidden`, a screen reader reads the `__code` lines in
+  DOM order, which is a faithful reading of the diff. If you want grid/table
+  semantics, use a real `<table>` or add the full ARIA chain
+  (`role="table" > rowgroup > row > cell`) — a bare `role="row"` without
+  `role="cell"` children is an ARIA violation. If the change kind itself must be
+  announced, add an off-screen label per changed row; do not rely on the glyph
+  alone.

package/docs/legends.md

@@ -48,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>
@@ -90,9 +90,13 @@ 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`
-(e.g. `style="--icon-mask: var(--glyph-dot)"`) or it paints a solid square, like
-any [icon](./reference.md). And an **interactive** legend entry must be a real
+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.
 

package/docs/mermaid.md

@@ -38,14 +38,31 @@ 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** (paste the object for your theme
-> from `mermaid.json` into the init directive) 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.
+> 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

package/docs/reference.md

@@ -9,7 +9,7 @@ rendering of every class is the kitchen-sink demo:
 **<https://ponchia.github.io/bronto-ui/>**. Theming knobs and the token
 contract: [docs/theming.md](theming.md).
 
-- 477 classes across 149 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`,
@@ -37,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 |
@@ -245,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 |
@@ -319,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 |
@@ -392,6 +417,12 @@ 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 |
@@ -402,6 +433,22 @@ each one matches a real selector in the stylesheet.
 | `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 |
@@ -519,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 |
@@ -639,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 |
@@ -689,6 +750,9 @@ 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 |
@@ -936,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 |
@@ -995,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 |
@@ -1126,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`
@@ -1134,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`
 
@@ -1156,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 |
@@ -1200,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 |
@@ -1232,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 |
@@ -1283,8 +1395,11 @@ 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`
@@ -1302,7 +1417,9 @@ works in any framework without a binding layer:
   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 } }`) on selection; the interactive
+  `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.
@@ -1321,8 +1438,10 @@ works in any framework without a binding layer:
   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 (driven by `initDotGlyph`/`uiBlink`). For a disclosure/affordance
-  arrow use `ui-link--arrow` (`ui.link({ arrow: true })`).
+  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
 

package/docs/reporting.md

@@ -37,11 +37,11 @@ No install? Link the same files from a CDN. Pin the version — pre-1.0, breakin
 changes ship in the minor (see [stability.md](./stability.md)):
 
 ```html
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.0/dist/bronto.css" />
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.0/dist/css/report.css" />
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.0/dist/css/dataviz.css" />
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.0/dist/css/annotations.css" />
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.0/dist/css/legend.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.3/dist/bronto.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.3/dist/css/report.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.3/dist/css/dataviz.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.3/dist/css/annotations.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.3/dist/css/legend.css" />
 ```
 
 The CDN serves the package's own `fonts/` next to the CSS, so font URLs resolve
@@ -218,13 +218,17 @@ Direction tone follows the common case (up = good, green; down = bad, red). When
 
 The arrow is visual; always include the number and unit in the text.
 
-A stat card's own `ui-stat__delta is-pos` / `is-neg` carries **tone only** (good
-vs bad, as colour). That is fine on screen, but tone is a single channel: in a
-greyscale PDF or for a colour-blind reader a positive and a negative delta look
-identical, and the tone is deliberately decoupled from direction (a *dropped*
-latency is `is-pos`). When the change must read without colour — most printed
-reports — prefer `ui-delta` for the card's delta line, because its `--up`/`--down`
-arrow is a real non-colour channel:
+A stat card's own `ui-stat__delta is-pos` / `is-neg` carries **tone** (good vs
+bad, as colour) and auto-prepends a `▲`/`▼` glyph — but that glyph follows the
+**tone**, not the real direction: `is-pos` always renders `▲` and `is-neg`
+always `▼`, regardless of whether the number went up or down. The tone is
+deliberately decoupled from direction (a *dropped* latency is good, so `is-pos`),
+so the auto-arrow can contradict the words: write `is-pos` on a "−48 ms" and it
+prints `▲ −48 ms`. Do **not** add your own direction word/arrow on top, or you
+double it. When the change must read by direction — most printed reports —
+prefer `ui-delta` for the card's delta line, because its `--up`/`--down` arrow is
+a real (author-controlled) non-colour channel; reach for the arrow-free `ui-num`
+if you want neither tone nor glyph:
 
 ```html
 <span class="ui-stat__label">p95 latency</span>
@@ -343,8 +347,9 @@ raster).
 > and even then `import`/`fetch` of the config only works over an `http(s)`
 > origin. A static report **opened from disk (`file://`) cannot import the module
 > nor fetch `vega.json`** (CORS) — load Vega + Vega-Lite + vega-embed from pinned
-> `/build/*.min.js` CDN tags and **inline the resolved `config` object**, the
-> file://-safe recipe in [vega.md](./vega.md#from-a-cdn-no-bundler). For a report
+> `/build/*.min.js` CDN tags and **inline the resolved `config` object**
+> (generate it with `npm run emit:theme vega light`), the file://-safe recipe in
+> [vega.md](./vega.md#from-a-cdn-no-bundler). For a report
 > you intend to **print/PDF**, prefer the frozen inline `<svg>` below — it has no
 > runtime, prints exactly, and sidesteps all of this.
 
@@ -478,6 +483,22 @@ it (never rely on the bar alone — WCAG 1.4.1):
 reading (e.g. 112 % of plan) shows a full bar — put the true figure in the
 written label beside it (`ui-num`), which is the data of record anyway.
 
+For a block of meters — SLO burn, error budgets, capacity — lay each out as
+**label | bar | value** with `ui-meter__row`; `ui-meter__label` names it and
+`ui-meter__value` carries the reading (the data of record — never the bar
+alone). The row collapses to a stack on a narrow screen, so you don't hand-roll
+the grid:
+
+```html
+<div class="ui-meter__row">
+  <span class="ui-meter__label">Write availability</span>
+  <div class="ui-meter ui-meter--danger" role="presentation">
+    <span class="ui-meter__fill" style="--value: 90"></span>
+  </div>
+  <span class="ui-meter__value ui-num">90% of budget burned</span>
+</div>
+```
+
 A **pull-quote** lifts a source sentence out of the prose — `ui-quote` is the
 block, `ui-quote__cite` attributes it: