@ponchia/ui 0.6.0 → 0.6.4

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
+- 540 classes across 167 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`,
@@ -31,13 +31,19 @@ each one matches a real selector in the stylesheet.
 | `cls.accordionItem` | `ui-accordion__item` | part |
 | `cls.accordionSummary` | `ui-accordion__summary` | part |
 
+### `.ui-activity`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.activity` | `ui-activity` | base |
+
 ### `.ui-alert`
 
 | Registry key | Class | Kind |
 | --- | --- | --- |
 | `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 +251,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 +337,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 +423,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 +439,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 |
@@ -439,6 +492,18 @@ each one matches a real selector in the stylesheet.
 | --- | --- | --- |
 | `cls.dotfield` | `ui-dotfield` | base |
 
+### `.ui-dotfit`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.dotfit` | `ui-dotfit` | base |
+
+### `.ui-dotgauge`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.dotgauge` | `ui-dotgauge` | base |
+
 ### `.ui-dotgrid`
 
 | Registry key | Class | Kind |
@@ -519,12 +584,26 @@ 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 |
 | --- | --- | --- |
 | `cls.grid` | `ui-grid` | base |
 
+### `.ui-halftone`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.halftone` | `ui-halftone` | base |
+
 ### `.ui-hint`
 
 | Registry key | Class | Kind |
@@ -624,6 +703,14 @@ each one matches a real selector in the stylesheet.
 | `cls.legendVertical` | `ui-legend--vertical` | modifier |
 | `cls.legendWithValues` | `ui-legend--with-values` | modifier |
 
+### `.ui-level`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.level` | `ui-level` | base |
+| `cls.levelDanger` | `ui-level--danger` | modifier |
+| `cls.levelWarn` | `ui-level--warn` | modifier |
+
 ### `.ui-lightbox`
 
 | Registry key | Class | Kind |
@@ -639,6 +726,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 +782,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 |
@@ -829,6 +925,7 @@ each one matches a real selector in the stylesheet.
 | Registry key | Class | Kind |
 | --- | --- | --- |
 | `cls.readout` | `ui-readout` | base |
+| `cls.readoutSpacer` | `ui-readout__spacer` | part |
 
 ### `.ui-reasoning`
 
@@ -936,6 +1033,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 +1099,17 @@ 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 |
+| `cls.sparkDots` | `ui-spark--dots` | modifier |
+
 ### `.ui-spinner`
 
 | Registry key | Class | Kind |
@@ -1123,10 +1238,10 @@ each one matches a real selector in the stylesheet.
 | `cls.tableSelect` | `ui-table__select` | part |
 | `cls.tableSort` | `ui-table__sort` | part |
 | `cls.tableToolbar` | `ui-table__toolbar` | part |
+| `cls.tableBreakAnywhere` | `ui-table--break-anywhere` | modifier |
 | `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 +1249,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 +1272,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 +1328,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 +1369,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,6 +1391,12 @@ each one matches a real selector in the stylesheet.
 | --- | --- | --- |
 | `cls.vt` | `ui-vt` | base |
 
+### `.ui-waffle`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.waffle` | `ui-waffle` | base |
+
 ## Table-local state classes
 
 Not in `cls` by design — these are plain `is-*` state hooks scoped to
@@ -1283,8 +1436,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 +1458,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 +1479,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.4/dist/bronto.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.4/dist/css/report.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.4/dist/css/dataviz.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.4/dist/css/annotations.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.6.4/dist/css/legend.css" />
 ```
 
 The CDN serves the package's own `fonts/` next to the CSS, so font URLs resolve
@@ -150,6 +150,10 @@ they are all safe in the static, PDF-first report path.
   `ui-alert` for persistent notices, `ui-table` for structured evidence,
   `ui-timeline` for events, `ui-meter` for measured values, and `ui-num` for
   non-table numeric values.
+- In alerts, put the readable message in `<p class="ui-alert__body">…</p>`
+  and use `ui-alert__title` only for a separate title line. `ui-alert` is a
+  grid with a leading status dot; raw text or loose inline children such as
+  `<strong>` / `<code>` become separate grid items and can fragment in print.
 - Give `ui-report__finding` blocks an accessible name so the visual grouping is
   also programmatic: point `aria-labelledby` at the block's `ui-eyebrow` label
   (give it an `id`), or lead with a real heading. Do the same for a
@@ -167,6 +171,10 @@ they are all safe in the static, PDF-first report path.
   inside `ui-prose`; use `.ui-table` for curated evidence tables. If a
   `ui-report__evidence` block contains only a `ui-table-wrap`, the report layer
   removes the inner frame so evidence tables do not look double-boxed.
+  Report tables preserve words by default so identifiers and headings do not
+  split into unreadable fragments in PDF. Add `ui-table--break-anywhere` only
+  for machine-token tables where avoiding horizontal overflow matters more than
+  preserving words.
 - Every `<figure>` should include a `figcaption` using `ui-report__caption`.
 - Do not use raw color values. Theme with `--accent`; use status tones for
   status; use chart tokens only in chart figures.
@@ -218,13 +226,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 +355,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 +491,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:
 
@@ -568,9 +597,10 @@ need a full automatable browser, only a Chromium-class layout+print pass.
 - **By hand:** open the report in Chrome/Edge → Print (Cmd/Ctrl+P) → "Save as
   PDF". In **More settings**, enable **Background graphics** (the dialog's
   equivalent of `printBackground` — without it chart fills and swatches drop
-  out), and pick the paper size there. Paper size is a browser print setting,
-  not a token; the layer only themes the page _margin_ via
-  `--report-page-margin`.
+  out), and pick the paper size there. Paper size and page margins are browser
+  print settings; the report stylesheet uses a fixed 18mm `@page` margin because
+  Chromium-class print engines do not reliably resolve custom properties inside
+  `@page` rules.
 - **Headless, lightweight:** use **`chrome-headless-shell`** — the minimal
   headless-Chromium binary built for exactly this, a fraction of a full
   browser's weight. Drive it through Playwright/Puppeteer (or raw CDP) and
@@ -641,3 +671,5 @@ Before returning a report, an LLM should verify:
 - No raw chromatic colors appear in inline styles.
 - No remote scripts, styles, iframes, or images are required for the report.
 - Generated/untrusted body HTML was sanitized before insertion.
+- Alert text is wrapped in `.ui-alert__body`; no loose text or inline-only
+  elements are direct children of `.ui-alert`.

package/docs/sidenote.md

@@ -0,0 +1,64 @@
+# Sidenote
+
+`@ponchia/ui/css/sidenote.css` is an opt-in **margin-note** grammar in the Tufte
+tradition — the channel for evidence, caveats, and provenance asides that belong
+*beside* the prose, not interrupting it. `ui-sidenote` is numbered;
+`ui-marginnote` is the unnumbered variant.
+
+```css
+@import '@ponchia/ui';
+@import '@ponchia/ui/css/sidenote.css';
+```
+
+## How it behaves
+
+- **Wide viewports** (≥ 60rem) float the note into the inline-end margin.
+- **Narrow viewports** collapse it to an indented inline block right after its
+  anchor, so nothing is lost on a phone or in a narrow column.
+- **Numbering** is a CSS counter — no host bookkeeping.
+
+## Wiring — two things the host owns
+
+1. **Where numbering restarts.** Put `counter-reset: ui-sidenote` on the article
+   (or a section) so the count starts at 1 there.
+2. **The margin gutter.** At the same breakpoint, give that container
+   `padding-inline-end: calc(var(--sidenote-width) + var(--sidenote-gap))` so the
+   floated note has room. `--sidenote-width` defaults to `12rem`.
+
+```html
+<article style="counter-reset: ui-sidenote">
+  <p>
+    The migration cut p95 latency by 38%<label class="ui-sidenote__ref"></label>.
+    <span class="ui-sidenote">
+      Measured over the first 24h after rollout; see the incident review §4.
+    </span>
+    The error budget held<span class="ui-marginnote">No paging events fired.</span>.
+  </p>
+</article>
+```
+
+The `.ui-sidenote__ref` renders the superscript number and increments the
+counter; place the `.ui-sidenote` immediately after it in the DOM so it reads
+the same number.
+
+## Class reference
+
+| Class | Role |
+| --- | --- |
+| `.ui-sidenote` | A numbered margin note. |
+| `.ui-marginnote` | An unnumbered margin note (no `__ref`). |
+| `.ui-sidenote__ref` | The inline superscript anchor; increments + prints the number. |
+
+| Custom property | On | Meaning |
+| --- | --- | --- |
+| `--sidenote-width` | `.ui-sidenote` / `.ui-marginnote` | Floated width on wide viewports (default `12rem`). |
+| `--sidenote-gap` | same | Gap between the text column and the note (default `2rem`). |
+
+## Accessibility & robustness
+
+- The note is **real DOM in reading order**, so a screen reader encounters it
+  right after the anchor — no off-screen trickery.
+- On narrow viewports the note is always visible (an indented block with an
+  inline-start rule), so there is no hidden-content trap.
+- Keep the note's meaning in its text; the number is a wayfinding aid, not the
+  content.

package/docs/spark.md

@@ -0,0 +1,78 @@
+# Spark
+
+`@ponchia/ui/css/spark.css` is an opt-in **inline dataword** — a word-sized
+microchart you drop into a sentence or a dense table cell to show a trend
+in-line. It is the inline counterpart to the scalar `ui-delta` / `ui-num` /
+`ui-stat`, and it fills a gap a block-level chart cannot.
+
+```css
+@import '@ponchia/ui';
+@import '@ponchia/ui/css/spark.css';
+```
+
+## Boundary — the host owns the numbers
+
+Bronto paints bars; it does **not** compute scales. The host normalises each
+data point to `0..1` and sets it as `--v` on a `.ui-spark__bar`. Bronto refuses
+raw values and min/max — that is the same boundary that keeps the analytical
+layer from owning chart state.
+
+## Markup
+
+```html
+<!-- "weekly signups, trending up" — the label IS the accessible content -->
+<span class="ui-spark" role="img" aria-label="weekly signups, trending up">
+  <span class="ui-spark__bar" style="--v: 0.2"></span>
+  <span class="ui-spark__bar" style="--v: 0.4"></span>
+  <span class="ui-spark__bar" style="--v: 0.35"></span>
+  <span class="ui-spark__bar" style="--v: 0.7"></span>
+  <span class="ui-spark__bar ui-spark__bar--accent" style="--v: 1"></span>
+</span>
+```
+
+A **win/loss** strip uses fixed-height bars with `--pos` / `--neg` tones:
+
+```html
+<span class="ui-spark" role="img" aria-label="last 5 deploys: 4 passed, 1 failed">
+  <span class="ui-spark__bar ui-spark__bar--pos" style="--v: 1"></span>
+  <span class="ui-spark__bar ui-spark__bar--pos" style="--v: 1"></span>
+  <span class="ui-spark__bar ui-spark__bar--neg" style="--v: 1"></span>
+  <span class="ui-spark__bar ui-spark__bar--pos" style="--v: 1"></span>
+  <span class="ui-spark__bar ui-spark__bar--pos" style="--v: 1"></span>
+</span>
+```
+
+## Class reference
+
+| Class | Role |
+| --- | --- |
+| `.ui-spark` | The inline container (sizes to ~1em tall, `max-content` wide). |
+| `.ui-spark__bar` | One bar — height from `--v` (`0..1`). Defaults to `currentColor`. |
+| `.ui-spark__bar--accent` | Emphasise one bar with the rationed accent. |
+| `.ui-spark__bar--pos` | Success tone (win). |
+| `.ui-spark__bar--neg` | Danger tone (loss). |
+
+| Custom property | On | Meaning |
+| --- | --- | --- |
+| `--v` | `.ui-spark__bar` | **Required.** Normalised height `0..1`; the host computes it. A bar with no `--v` collapses to a 1px floor. |
+
+## Recipes
+
+```js
+import { ui } from '@ponchia/ui/classes';
+
+ui.sparkBar({ tone: 'accent' }); // "ui-spark__bar ui-spark__bar--accent"
+ui.sparkBar({ tone: 'pos' });    // "ui-spark__bar ui-spark__bar--pos"
+ui.sparkBar();                   // "ui-spark__bar"
+```
+
+## Accessibility & robustness
+
+- **A bare spark is opaque.** The `.ui-spark` container **must** carry
+  `role="img"` and an `aria-label` that states the trend in words — colour and
+  shape are never the only channel (WCAG 1.4.1, 1.1.1).
+- **Forced colours:** the bars repaint in the system text colour so the shape
+  survives (the tone distinction lives in the label).
+- **Print:** bars are forced through `print-color-adjust: exact`.
+- No JS, no measurement — it renders identically server-side and in a static
+  report.

package/docs/stability.md

@@ -40,6 +40,7 @@ until `1.0.0` is tagged. This matrix defines what counts as public API.
 | Generated / AI-trust (`css/generated.css`, `.ui-generated*`, `.ui-origin-label*`, `.ui-reasoning*`, `.ui-tool-log`, `.ui-tool-call*`) | Stable additive | The generated-content, origin-label (incl. `--ai`), reasoning-trace and tool-log/tool-call class names and the `ui.originLabel` recipe are public. Opt-in, not in the default bundle. Not a chat kit; no confidence widget. |
 | Workbench (`css/workbench.css`, `.ui-inspector*`, `.ui-property*`, `.ui-selectionbar*`) | Stable additive | Inspector, property-row and selection-bar class + BEM part names are public (class-only — no recipe). Opt-in, not in the default bundle. Splitters/drag handles are out of scope. |
 | Command palette (`css/command.css`, `.ui-command*`, `initCommand`, `useCommand`) | Stable additive | Command class/part names, the `data-bronto-command` attribute, and the event contract — `bronto:command:select` (`detail: { value, label }`) and `bronto:command:close` — are public, plus the `useCommand` binding hook. Bronto filters + navigates (APG combobox/listbox); the host owns the action registry/execution. Opt-in, not in the default bundle, no global hotkey. |
+| Controlled-modal focus trap (`initModal`, `useModal`, `data-bronto-modal`) | Stable additive | For the `.ui-modal.is-open` (non-`<dialog>`) path: the `data-bronto-modal` opt-in marker, the `inert`-based focus trap + focus-return, and the cancelable `bronto:modal:close` (`detail: { reason }`) event are public. The consumer still owns the `is-open` class; the behavior never changes visibility. The native `<dialog>` path (`initDialog`) is the default and gets the trap for free. |
 | Keyboard-shortcut hint (`.ui-shortcut`, `.ui-shortcut__sep`) | Stable additive | Class names for the chord/sequence hint over `.ui-kbd` are public. Ships in the core layer (class-only, no recipe). |
 | Generated docs shipped in npm | Stable paths | `llms.txt` and exported docs paths stay shipped and resolvable within a compatible minor. Markdown/text assets are for reading unless your runtime has a loader. Generated content may change with the source contract. |
 | Demo, examples, tests, scripts | Internal | Useful for learning and verification, but not shipped runtime API unless a path is explicitly exported in `package.json`. |