@ponchia/ui 0.6.0 → 0.6.4

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/dots.md

@@ -0,0 +1,146 @@
+# Dot surfaces
+
+The dot-matrix is the library's signature: one lit/dim/accent dot vocabulary
+expressed across backgrounds, dividers, indicators, loaders, and a family of
+data-bound reporting surfaces. Everything here lives in the core stylesheet
+(`@ponchia/ui` / `@ponchia/ui/css`); the glyph icon set built on the same
+primitive is documented in `docs/glyphs.md`.
+
+All classes are in the typed registry (`@ponchia/ui/classes`) and the
+language-neutral `classes.json`; those are authoritative.
+
+## Tokens
+
+Density and expression are token-driven, so a surface re-skins without new CSS:
+
+| Token | Role |
+| --- | --- |
+| `--field-dot` | the dim (unlit) dot |
+| `--field-dot-hot` | a lit cell |
+| `--field-dot-accent` | the accented lit cell |
+| `--dot-gap` / `--dot-size` | `.ui-dotgrid` background density |
+| `--dotmatrix-cols` / `--dotmatrix-gap` / `--dotmatrix-dot` | matrix density |
+| `--dotmatrix-dot-radius` | `0` fuses dots into crisp pixels |
+
+The Tier-3 **display-expression** knobs speak in brightness + time rather than
+hue (a dot-matrix display has no decorative colour). They default to a no-op, so
+the base render is unchanged; the opt-in colorways (`@ponchia/ui/css/skins.css`)
+set them:
+
+| Knob | Default | Effect |
+| --- | --- | --- |
+| `--dotmatrix-glow` | `0` (off) | phosphor bloom around lit cells |
+| `--dotmatrix-pulse-min` | `0.55` | the floor the `--pulse` animation dips to |
+| `--dotmatrix-reveal-step` | `3ms` | per-cell cadence of the `--reveal` scan |
+
+## Decorative surfaces
+
+- `.ui-dotgrid` — a tiled dot-grid background (`--accent`, `--dense` modifiers).
+- `.ui-dotfield` — a fixed full-bleed dot backdrop.
+- `.ui-dotrule` — a dotted divider in place of a plain rule.
+- `.ui-halftone` — render host content (an `<img>` or a box with its own
+  background) through a dot lattice, so a thumbnail takes on the dot look. A
+  **style filter**, not a data viz — the dots are a fixed lattice, not
+  value-modulated. Tune with `--halftone-dot` / `--halftone-gap`.
+
+## Indicators & loaders
+
+- `.ui-dot` — a status dot with tones (`--accent/--success/--warning/--danger/--info`)
+  and a `--live` pulse ring; `.ui-status` is the dot + label row.
+- `.ui-dotloader` — three blinking dots.
+- `.ui-dotspinner` — the signature comet loader (`--sm` / `--lg`).
+- `.ui-dotbar` — a segmented LED progress bar; light a segment with `is-on`,
+  or `--indeterminate` for the sweep.
+
+## Data-bound reporting surfaces
+
+These map data onto the dot vocabulary. The boundary is the same as `ui-spark`
+and `ui-meter`: **the host normalises the data** (lights `is-on`, sets
+`data-level`, or writes `--v` 0..1) and the leaf only lays out + tones. None
+compute a scale, bin, or threshold. Each is opaque to assistive tech, so the
+container MUST carry a host-written `role="img"` + `aria-label` with the exact
+value — rounding to whole cells is presentation-only, so keep the figure in the
+label (WCAG 1.4.1).
+
+### `.ui-matrix` cell grid
+
+`.ui-dotmatrix` is the raw data-bound grid (the one the glyphs render on): a grid
+of `.ui-dotmatrix__cell` (with `--hot` / `--accent` tones) plus the `--reveal` /
+`--pulse` animations. You map data → cell class.
+
+### `.ui-waffle` — unit / part-to-whole
+
+An N×N field of dots ("73 of 100"). The host marks the lit cells with `is-on`.
+
+```html
+<div class="ui-waffle" role="img" aria-label="73 of 100 quota met" style="--waffle-cols: 10">
+  <i class="is-on"></i><i class="is-on"></i><!-- … 73 lit, 27 dim … --><i></i>
+</div>
+```
+
+Knobs: `--waffle-cols` (default 10), `--waffle-gap`, `--waffle-size`.
+
+### `.ui-activity` — contribution / calendar heatmap
+
+A GitHub-style density-over-time grid. Day cells flow down each weekday column
+(`grid-auto-flow: column`); intensity is `data-level="0..4"`, a 5-step ramp the
+host bins the data into.
+
+```html
+<div class="ui-activity" role="img" aria-label="commits, last 12 weeks">
+  <i data-level="0"></i><i data-level="3"></i><i data-level="4"></i><!-- … -->
+</div>
+```
+
+Knobs: `--activity-rows` (default 7), `--activity-cell`, `--activity-gap`.
+
+### `.ui-level` — LED level / VU meter
+
+A vertical column of discrete segments lit to a threshold (signal, load, VU). It
+fills from the bottom; the host lights segments with `is-on`. `--warn` /
+`--danger` re-point the lit colour for the whole meter when the host crosses a
+threshold (the host owns the threshold).
+
+```html
+<div class="ui-level ui-level--warn" role="img" aria-label="CPU 82%, high">
+  <i class="is-on"></i><i class="is-on"></i><i></i><!-- … --></div>
+```
+
+Knobs: `--level-segments` count is up to your markup; `--level-height`,
+`--level-size`, `--level-gap`.
+
+### `.ui-dotgauge` — radial dot gauge
+
+A 0..1 reading (`--v`) drawn as a ring of dots filling along an arc.
+
+```html
+<div class="ui-dotgauge" role="img" aria-label="Health 64%" style="--v: .64"></div>
+```
+
+Knobs: `--v`, `--gauge-size`, `--gauge-sweep` (default 270deg), `--gauge-from`,
+`--gauge-dot`.
+
+### `.ui-readout` — big dot-matrix numeric
+
+The row wrapper produced by `renderReadout` (see `docs/glyphs.md`) — a Nothing-style
+hero numeric composed from digit glyphs. Tune character spacing with
+`--readout-gap`; spaces render as a `.ui-readout__spacer` of width `--readout-space`.
+
+### `.ui-spark--dots`
+
+A modifier on the inline `ui-spark` dataword (`@ponchia/ui/css/spark.css`) that
+renders each bar as a stack of dots instead of a solid bar — same `--v` contract.
+
+## Responsive density — `.ui-dotfit`
+
+Wrap a dot surface in `.ui-dotfit` to make it respond to its **container** (the
+card) rather than the viewport, via a container query — so the same component
+reads well in a wide hero and a narrow tile without per-instance overrides.
+
+## Accessibility, forced colors & print
+
+Lit/dim/accent encode meaning via background-color, which Windows High Contrast
+Mode flattens — the dot surfaces opt out of forced-color remapping and pin lit
+states to distinct system colours (the activity ramp collapses to present vs
+absent). The data surfaces also set `print-color-adjust: exact` so their fills
+survive printing. Animations honour `prefers-reduced-motion`.

package/docs/glyphs.md

@@ -0,0 +1,114 @@
+# Display glyphs
+
+`@ponchia/ui/glyphs` is a small, frozen bitmap icon set rendered on the same
+`.ui-dotmatrix` dot primitive as every other dot surface (see `docs/dots.md`).
+CSS-first to the core: a glyph is just a grid of dot cells — `.` off, `#` hot,
+`*` accent — so it re-skins with the same `--field-dot*` tokens and the Tier-3
+display knobs as the rest of the dot family. No icon font, no SVG sprite, no
+runtime dependency. The module is side-effect-free and SSR-safe (`renderGlyph`
+returns a string; nothing touches the DOM).
+
+```js
+import { renderGlyph } from '@ponchia/ui/glyphs';
+el.innerHTML = renderGlyph('check', { label: 'Done' });
+```
+
+The authoritative API is the generated, CI-drift-checked `glyphs/glyphs.d.ts`.
+Read it before guessing a name — `GlyphName` is a literal union, so a typo is a
+type error.
+
+## Three render paths
+
+A glyph can be drawn three ways; pick by size regime.
+
+| Path | Call | DOM | When |
+| --- | --- | --- | --- |
+| Dot display | `renderGlyph(name)` | `GLYPH_SIZE²` cells (256) | the signature dot-matrix look at display sizes |
+| Solid pixel | `renderGlyph(name, { solid: true })` | 256 cells, fused | legible crisp icon at small/inline sizes (~16–24px) |
+| Mask icon | `renderGlyph(name, { render: 'mask' })` | **one** `.ui-icon` node | icon-at-scale (e.g. one per table row): inherits `currentColor`, scales with the text |
+
+The mask path is the lightest — one node instead of 256 — and the right default
+for an icon repeated many times. It is single-tone: an accent `*` cell renders
+the same as a hot `#` cell (both become opaque mask regions).
+
+> Pixel-crisp sizes: the bitmap is a 16-unit grid, so the dot/solid paths look
+> sharpest at integer multiples (16/32/48/64px). The mask path scales smoothly
+> with the text; arbitrary `em` sizes soften the edges slightly, which is fine
+> for inline use.
+
+### `renderGlyph(name, options)`
+
+| Option | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `grid` | boolean | `true` | show the unlit panel dots; `false` → glyph-only |
+| `solid` | boolean | `false` | square, gapless pixels (implies glyph-only) |
+| `anim` | `'reveal' \| 'pulse'` | — | decorative animation (reduced-motion-safe) |
+| `label` | string | — | expose as `role="img"` with this name; omit → decorative (`aria-hidden`) |
+| `dot` | CSS length | `0.08em` | one dot size (`--dotmatrix-dot`; sanitized) |
+| `gap` | CSS length | — | gap between dots (`--dotmatrix-gap`; sanitized) |
+| `render` | `'mask'` | — | the one-node `.ui-icon` path |
+| `size` | CSS length | `1em` | with `render: 'mask'`, the icon size (`--icon-size`) |
+
+## Big numeric readout — `renderReadout`
+
+Compose digits and punctuation into a row of dot-matrix glyphs — the
+Nothing-style hero numeric for a KPI, clock, countdown, or percentage.
+
+```js
+import { renderReadout } from '@ponchia/ui/glyphs';
+el.innerHTML = renderReadout('12:48', { label: '12:48 remaining' });
+el.innerHTML = renderReadout('73%', { label: '73 percent of quota', render: 'mask' });
+```
+
+Recognised characters: `0-9`, `:`, `,`, `.`, `%`, `-`, `+`, and space (a blank
+advance). Anything else is skipped. Every per-glyph option (`solid`, `render`,
+`dot`, `gap`, `anim`) passes through to each character; `gap` sets the spacing
+between characters. The digits are decorative — the readout's **value** is its
+accessible name, so pass a `label` (it defaults to the raw text). Output wraps
+in `.ui-readout` (see `docs/dots.md`).
+
+## Finding a glyph — `findGlyphs` / `GLYPH_TAGS`
+
+Names follow the "depict, don't name the purpose" convention (`trash`, not
+`delete`). `findGlyphs(query)` resolves an intent word to real names by matching
+the name OR a curated search alias (`GLYPH_TAGS`), case-insensitively:
+
+```js
+import { findGlyphs } from '@ponchia/ui/glyphs';
+findGlyphs('delete'); // → ['trash']
+findGlyphs('chart'); // → ['bar-chart']
+findGlyphs(''); // → every name
+```
+
+## DOM placeholders — `initDotGlyph`
+
+When you would rather drop a placeholder than inline markup, the optional
+`initDotGlyph` behavior (`@ponchia/ui/behaviors`) expands
+`[data-bronto-glyph="name"]` in place. It is idempotent and returns a cleanup.
+
+| Attribute | Value | Effect |
+| --- | --- | --- |
+| `data-bronto-glyph` | glyph name | expand into a `.ui-dotmatrix` grid |
+| `data-bronto-glyph-label` | text | expose as `role="img"`; omit → decorative |
+| `data-bronto-glyph-solid` | — | square, gapless pixel glyph |
+| `data-bronto-glyph-anim` | `reveal \| pulse` | decorative animation |
+| `data-bronto-glyph-render` | `mask` | the one-node `.ui-icon` path (not 256 cells) |
+| `data-bronto-glyph-size` | CSS length | with `render="mask"`, sets `--icon-size` |
+
+An unknown name is left untouched.
+
+## Accessibility
+
+- A glyph next to a text label is redundant → keep it decorative (`aria-hidden`,
+  the default).
+- An icon-only control labels the **control** (`aria-label` on the `<button>`),
+  not the glyph.
+- A standalone meaningful glyph passes `label` → `role="img"` + `aria-label`.
+- A cell-mode glyph is a sea of 256 nodes; the wrapper carries the single
+  `role="img"`/`aria-hidden`, so assistive tech never walks the cells.
+
+## Two-tone glyphs
+
+The accent (`*`) tone lifts one feature of a glyph onto `--field-dot-accent`.
+The curated two-tone set is `spark`, `warning`, and `info`; every other glyph is
+monotone. Two-tone only shows in the cell render — the mask path is single-tone.

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