@ponchia/ui 0.3.6 → 0.4.1

package/docs/reporting.md

@@ -0,0 +1,270 @@
+# Static reports
+
+`@ponchia/ui` can dress static, LLM-authored HTML reports without a component
+runtime. Load the normal bundle, then opt in to the report layer and the chart
+palette only when the report needs them.
+
+In a bundled app, package specifiers are fine because Vite or another bundler
+rewrites them:
+
+```css
+@import '@ponchia/ui';
+@import '@ponchia/ui/css/report.css';
+@import '@ponchia/ui/css/dataviz.css';
+```
+
+For standalone browser HTML, use real stylesheet URLs. Package specifiers like
+`@ponchia/ui/css/report.css` do not resolve in a saved `.html` file:
+
+```html
+<link rel="stylesheet" href="./node_modules/@ponchia/ui/dist/bronto.css" />
+<link rel="stylesheet" href="./node_modules/@ponchia/ui/dist/css/report.css" />
+<link rel="stylesheet" href="./node_modules/@ponchia/ui/dist/css/dataviz.css" />
+```
+
+If you copy the built CSS next to the report, keep the same relationship between
+`dist/bronto.css`, `dist/css/report.css`, `dist/css/dataviz.css`, and `fonts/`
+so font URLs continue to resolve.
+
+The report layer is static and PDF-first. It does not initialize behaviors and
+does not sanitize content. If a report includes arbitrary LLM, CMS, or user HTML,
+sanitize that content before rendering it and do not initialize
+`data-bronto-*` behaviors on the generated region.
+
+## Canonical skeleton
+
+```html
+<main class="ui-report ui-report--numbered">
+  <header class="ui-report__cover">
+    <p class="ui-eyebrow">Quarterly review</p>
+    <h1 class="ui-report__title">Personal systems report</h1>
+    <p class="ui-report__subtitle">A static report generated from trusted data.</p>
+    <ul class="ui-report__meta">
+      <li><time datetime="2026-06-01">2026-06-01</time></li>
+      <li>Static HTML</li>
+      <li>Chromium PDF-ready</li>
+    </ul>
+  </header>
+
+  <nav class="ui-report__toc" aria-label="Report contents">
+    <p class="ui-eyebrow ui-eyebrow--muted">Contents</p>
+    <ol>
+      <li><a href="#summary">Executive summary</a></li>
+      <li><a href="#findings">Findings</a></li>
+    </ol>
+  </nav>
+
+  <section id="summary" class="ui-report__section">
+    <h2 class="ui-report__section-head">Executive summary</h2>
+    <div class="ui-report__summary">
+      <p>The summary block is for the decision-level conclusion.</p>
+    </div>
+    <div class="ui-statgrid">
+      <div class="ui-stat">
+        <span class="ui-stat__label">Open risks</span>
+        <span class="ui-stat__value">3</span>
+        <span class="ui-stat__delta is-neg">+1 this week</span>
+      </div>
+    </div>
+  </section>
+
+  <section id="findings" class="ui-report__section">
+    <h2 class="ui-report__section-head">Findings</h2>
+    <article class="ui-report__finding" aria-labelledby="finding-1">
+      <p class="ui-eyebrow" id="finding-1">Finding 1 — short title</p>
+      <div class="ui-prose">
+        <p>Use prose only for narrative body content.</p>
+      </div>
+    </article>
+  </section>
+</main>
+```
+
+## Composition rules
+
+- Use `ui-report` as the page-level wrapper. Add `ui-report--numbered` when
+  section headings should auto-number. Add `ui-report--compact` to tighten the
+  whole report's vertical rhythm (gap + page padding) for dense briefs — this
+  is the document-level density toggle, distinct from `ui-report__cover--compact`
+  below, which only shrinks the cover.
+- Use `ui-report__cover` for title, subtitle, author/date, and generation
+  metadata. Add `ui-report__cover--compact` for short screen-first reports.
+  Use `ui-report__header` for a compact in-page header instead of a full cover
+  (same role, no tall hero block). Author `ui-report__meta` as a `<ul>` — the
+  facts it lists are unordered.
+- Use `ui-report__section` and `ui-report__section-head` for report chapters.
+  Keep one `h1` for the report title; use ordered `h2`/`h3` headings after it.
+- Add `ui-report__section--unnumbered` to appendices, sources, or footnotes
+  when the report uses `ui-report--numbered` but the section should not count as
+  a numbered chapter.
+- Use `ui-prose` only around narrative HTML you do not fully control, such as
+  Markdown output. Do not wrap structured app/report UI in `ui-prose`.
+- Use existing primitives for shared meanings: `ui-statgrid` for KPIs,
+  `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.
+- 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
+  multi-part `ui-report__evidence` block; a single evidence table is already
+  named by its own `<caption>`.
+- Name the `ui-report__sources` and `ui-report__footnotes` blocks
+  (`aria-labelledby` on their `ui-eyebrow`), and link footnotes both ways:
+  an in-text `<sup><a id="fnref1" href="#fn1">1</a></sup>` to an
+  `<ol><li id="fn1">… <a href="#fnref1">↩</a></li></ol>`. They are real
+  regions, not decoration.
+- Every `<table>` that carries report data should have a `<caption>`, header
+  cells, and `.is-num` on numeric columns. (`.is-num`, `.is-pos`, `.is-neg`
+  and `.is-key` only take effect inside `.ui-table` cells and `.ui-stat`
+  deltas — they are not free-standing utilities.) Keep raw Markdown tables
+  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.
+- Every `<figure>` should include a `figcaption` using
+  `ui-chart__caption` (chart figures) or `ui-report__caption` (any other
+  report figure); the two are interchangeable in style.
+- Do not use raw color values. Theme with `--accent`; use status tones for
+  status; use chart tokens only in chart figures.
+
+## Chart figure recipe
+
+The report layer supplies chart containers, legends, and a small static bar
+pattern, not a chart engine. For CSS/HTML/SVG charts, pair each chart color with
+a direct label, a pattern, or a fallback table.
+
+```html
+<figure class="ui-report__figure ui-chart ui-print-exact" role="group" aria-labelledby="chart-title">
+  <figcaption id="chart-title" class="ui-chart__caption">
+    Fig 1 - Weekly focus split
+  </figcaption>
+  <ul class="ui-chart__legend" aria-label="Series">
+    <li>
+      <span
+        class="ui-chart__swatch"
+        style="--chart-color: var(--chart-1); --chart-pattern: var(--chart-pattern-1)"
+        aria-hidden="true"
+      ></span>
+      Research
+    </li>
+    <li>
+      <span
+        class="ui-chart__swatch"
+        style="--chart-color: var(--chart-2); --chart-pattern: var(--chart-pattern-2)"
+        aria-hidden="true"
+      ></span>
+      Delivery
+    </li>
+  </ul>
+  <div class="ui-chart__plot" aria-hidden="true">
+    <div
+      class="ui-chart__bar"
+      style="--chart-value: 72%; --chart-color: var(--chart-1); --chart-pattern: var(--chart-pattern-1)"
+    >
+      <div class="ui-chart__label"><span>Research</span><span>18 h</span></div>
+      <div class="ui-chart__track"><div class="ui-chart__fill"></div></div>
+    </div>
+    <div
+      class="ui-chart__bar"
+      style="--chart-value: 44%; --chart-color: var(--chart-2); --chart-pattern: var(--chart-pattern-2)"
+    >
+      <div class="ui-chart__label"><span>Delivery</span><span>11 h</span></div>
+      <div class="ui-chart__track"><div class="ui-chart__fill"></div></div>
+    </div>
+  </div>
+  <div class="ui-chart__fallback">
+    <div class="ui-table-wrap">
+      <table class="ui-table ui-table--dense">
+        <caption>Chart source data</caption>
+        <thead>
+          <tr><th>Series</th><th class="is-num">Hours</th></tr>
+        </thead>
+        <tbody>
+          <tr><td>Research</td><td class="is-num">18</td></tr>
+          <tr><td>Delivery</td><td class="is-num">11</td></tr>
+        </tbody>
+      </table>
+    </div>
+  </div>
+</figure>
+```
+
+For canvas or SVG libraries, import resolved series colors from
+`@ponchia/ui/charts.json` and keep the same legend/caption/fallback structure in
+the surrounding HTML.
+
+## Timeline recipe
+
+Incident reviews and research logs should use the existing timeline primitive
+with its required item and time parts. Do not emit a bare list and expect it to
+style itself.
+
+```html
+<ol class="ui-timeline">
+  <li class="ui-timeline__item">
+    <time class="ui-timeline__time" datetime="2026-06-01T09:12:00">09:12</time>
+    <span>Latency alert fired for p95 over threshold.</span>
+  </li>
+  <li class="ui-timeline__item" aria-current="step">
+    <time class="ui-timeline__time" datetime="2026-06-01T09:54:00">09:54</time>
+    <span>Latency returned to baseline.</span>
+  </li>
+</ol>
+```
+
+## Common templates
+
+- Executive brief: compact cover, one summary block, KPI `ui-statgrid`, short
+  findings, and sources.
+- Research brief: compact header, decision frame, evidence table, quotes or
+  prose excerpts, and sources.
+- Incident review: compact cover, summary, `ui-timeline`, corrective-action
+  evidence table, and footnotes.
+- Project status: compact header, KPI `ui-statgrid`, chart figure with fallback
+  data, print-only notes, and unnumbered appendix.
+
+## Print and PDF
+
+The supported export target is modern Chromium print/PDF. Two ways to produce
+the file:
+
+- **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`.
+- **Headless (agents/CI):** `await page.pdf({ format: 'A4', printBackground: true })`
+  with Playwright or Puppeteer.
+
+The report prints ink-on-white regardless of the on-screen theme. Older
+HTML-to-PDF engines are not part of the browser floor and may not support
+cascade layers, `oklch()`, `color-mix()`, `:has()`, or modern paged-media
+behavior.
+
+- Use `ui-print-only` for content that should appear only in print.
+- Use `ui-screen-only` for navigation or helper content that should not print.
+- Use `ui-break-before` and `ui-break-after` for deliberate page boundaries.
+- Use `ui-keep` on short figures, findings, and summary blocks that should not
+  split across pages.
+- Use `ui-print-exact` on charts whose fills and patterns must survive PDF
+  export.
+- External links inside `ui-prose` print their URL automatically through the
+  base print stylesheet.
+
+**Not provided** (use the browser's paged-media features, or author the markup
+yourself): running headers/footers with "Page X of Y", automatic table-of-contents
+pagination, multi-column layout, and automatic citation/footnote numbering. The
+report layer is a document grammar, not a paged-media or citation engine — do not
+fake page numbers with inert markup.
+
+## LLM checklist
+
+Before returning a report, an LLM should verify:
+
+- All `ui-*` classes exist in `@ponchia/ui/classes`.
+- The document has one `h1`, ordered headings, and a single main report region.
+- Tables have captions and header cells.
+- Charts have captions, direct labels or legends, and fallback data.
+- 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.

package/docs/stability.md

@@ -0,0 +1,37 @@
+# Public API Stability
+
+`@ponchia/ui` is pre-1.0. Breaking changes ship in the minor (`0.x.0`), and
+patches are non-breaking. This matrix defines what counts as public API.
+
+| Surface | Stability | Contract |
+| --- | --- | --- |
+| CSS package root (`@ponchia/ui`) | Stable | CSS-only entrypoint. CSS side-effect imports are supported in CSS-aware bundlers; Node/runtime JS root imports are not. |
+| JS module format | Stable | JS subpaths are ESM-only. CommonJS consumers use dynamic `import()`. |
+| CSS class names (`.ui-*`) | Stable | Names and documented modifier semantics are public. Internal selector structure and leaf-file boundaries may change. |
+| Class recipes (`@ponchia/ui/classes`) | Stable | Exported `cls`, `ui`, `cx`, recipe names, and option unions are public. |
+| Design tokens | Stable names/roles | Token names and documented roles are public. Exact values and generated colour math outputs may change for visual tuning before 1.0. |
+| `--accent-1..6` | Stable names/roles | A subtle-to-bold accent ramp derived from `--accent`. Exact resolved values are visual tuning; algorithm changes require release-note visibility and resolver/browser checks. |
+| Behavior attributes (`data-bronto-*`) | Stable | Attribute names and documented markup relationships are public. Behavior internals are not. |
+| Behavior functions (`@ponchia/ui/behaviors`) | Stable | Exported function names, option names, custom events, SSR no-op behavior, idempotency, and cleanup-returning contract are public. |
+| Glyph registry/renderers (`@ponchia/ui/glyphs`) | Stable additive | Existing glyph names stay valid. New glyphs are additive. Renderer option names and accessibility defaults are public. |
+| `.ui-icon` mask renderer | Stable | Class name, `--icon-size`, currentColor inheritance, and `--icon-mask` contract are public. The internal data URL encoding is not. |
+| React/Solid/Qwik bindings | Stable thin adapters | Hook/primitive names, optional peer behavior, root ref/signal/resolver support, and cleanup lifecycle are public. They remain wrappers over vanilla behaviors, not component APIs. |
+| Skins (`@ponchia/ui/skins`, `css/skins.css`) | Stable additive | Existing skin names stay valid. New skins are additive. Skins are root-level choices. |
+| Charts (`@ponchia/ui/charts`, `charts.json`, `css/dataviz.css`) | Stable additive | Token names, JSON shape, and 8 categorical slots are public. Exact palette values may tune if gates and release notes justify it. |
+| Reports (`css/report.css`, `.ui-report*`, `.ui-chart*`, print utilities) | Stable additive | Report class names, BEM part names, chart helper class names, and print utility names are public. Report CSS is opt-in and not imported by the default bundle. |
+| 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`. |
+
+## Trust Boundary
+
+Behaviors assume trusted application markup. If a delegated root includes
+untrusted CMS or user HTML, sanitize it first or do not initialize behaviors on
+that root. The behavior layer intentionally lets authored `data-bronto-*`,
+`aria-controls`, and `id` relationships control elements inside the root.
+Dialog, disclosure, and popover targets resolve root-first and then
+document-wide for body/portal-mounted overlays; scoped roots are not a sandbox
+for untrusted markup.
+
+The one-node glyph mask renderer emits inline style/custom-property data. Apps
+with a strict CSP should either allow the required `data:` mask/image source and
+inline custom-property style path, or use the DOM dot/solid renderers.

package/docs/theming.md

@@ -4,13 +4,15 @@
 This is the **stable, supported surface** for re-branding without forking.
 Anything not listed here is internal and may change between minor versions.
 
-## The one knob: `--accent`
+## The brand knob: `--accent`
 
-The whole accent family derives from `--accent` via `color-mix()`:
+The accent family derives from `--accent` via `color-mix()` and the
+theme-owned neutral ramp endpoint:
 
 | Token                 | Derivation (light / dark)                    | Role |
 | --------------------- | -------------------------------------------- | ---- |
 | `--accent-strong`     | `--accent` mixed 83% with black / 84% white  | darker/lighter accent for hover, emphasis |
+| `--accent-ramp-end`   | white / black                                | neutral endpoint for the low-chroma OKLCH ramp |
 | `--accent-text`       | `var(--accent-strong)` (alias)               | **accent used as foreground text** — the on-surface, AA-safe one |
 | `--accent-soft`       | `--accent` at 10% / 14% over transparent     | tinted fills |
 | `--bg-accent`         | `--accent` at 6% / 8%                         | faint accent backgrounds |
@@ -49,6 +51,14 @@ fills — follows automatically, in both light and dark.
 - **Spacing** — override the `--space-2xs … --space-2xl` scale, or use a
   preset: `data-density="compact"` / `data-density="comfortable"` on any
   element (defaults to the middle scale).
+- **Dark surface** — the dark theme's base is a deliberately *elevated*
+  near-black (`--bg: #121212`) for readability: pure black + bright text
+  causes halation, and near-black-on-black surface steps are imperceptible.
+  For OLED power-saving or the original true-black "Nothing" look, opt in with
+  `data-surface="oled"` on `:root` (a root-level attribute like `data-theme`).
+  It only affects the dark theme and is a CSS-only preset (not in the JS token
+  model), so it never blacks out the light theme. See
+  [ADR-0003](adr/0003-theme-model.md) for the theme-model rationale.
 - **Radius** — `--radius-sm … --radius-xl`, `--radius-pill`. The Nothing
   default is near-sharp; raise these for a softer brand.
 - **Type** — `--display` (dot-matrix face), `--mono`, `--sans`. Override
@@ -115,7 +125,7 @@ is not. The values above are *measured* (white label on `#a8431a` =
 the same check. Don't set one global `--accent` and hope — that is why
 this example is split per theme.
 
-## Token tiers (0.3.1)
+## Token tiers
 
 Three additive, non-breaking tiers sit on top of the primitives. The
 short legacy names (`--panel`, `--line`, `--accent`, …) keep working
@@ -131,9 +141,11 @@ coarser-grained handles.
   primitives, so light/dark still Just Works.
 - **Accent ramp — `--accent-1 … --accent-6`.** A stepped family
   (subtle → bold) derived from the single `--accent` knob via
-  `color-mix` against the theme background. Re-brands and theme-adapts
-  automatically. This is the palette for charts / data-viz / multi-state
-  surfaces (the use case the JS token export advertises).
+  `color-mix(in oklch, …)` against a per-theme white/black endpoint
+  (`--accent-ramp-end`). Re-brands and theme-adapts automatically. Steps
+  1–4 are subtle surfaces; steps 5–6 are the accent and strong accent.
+  Exact hex outputs are visual tuning, but the token names and roles are
+  stable.
 - **Neutral ramp — `--surface-1 … --surface-6`** (low → high contrast
   against `--bg`) for layered surfaces without hand-picking greys.
 - **Stacking scale — `--z-base / -raised / -sticky / -overlay /
@@ -141,7 +153,72 @@ coarser-grained handles.
   these; override one to slot your app's own layers around the
   framework's without specificity/`z-index` wars.
 
-All four tiers are in the DTCG export and the JS token model.
+All four tiers are in the DTCG export and the JS token model. The full
+five-tier colour model and its rules live in
+[ADR-0001](adr/0001-color-system.md).
+
+## Display colorways (`data-bronto-skin`)
+
+Opt-in single-hue colorways, shipped as a **separate** entrypoint (never in
+the default bundle):
+
+```html
+<link rel="stylesheet" href="@ponchia/ui/css/skins.css" />
+<html data-theme="dark" data-bronto-skin="phosphor-green">
+  …
+</html>
+```
+
+`data-bronto-skin="amber-crt | phosphor-green | e-ink"` is a **root-level**
+choice, like `data-theme` — put it on `:root`/`<html>`. It re-points the one
+`--accent` (per theme, authored in OKLCH); the derived family, focus ring,
+dot-matrix and glyphs follow automatically, and status colours + the neutral
+canvas are untouched. A colorway is _not_ a second accent — it swaps the one
+you have, so the one-accent discipline holds.
+
+- **Root-level only.** The accent's derived family (`--accent-strong`/`-text`,
+  `--field-dot-accent`, `--accent-1..6`, …) is `color-mix(… var(--accent) …)`
+  declared on `:root`; it only re-evaluates on the element that carries it. A
+  skin on a subtree would leave that family stale, so the selectors are
+  `:root`-anchored and a subtree skin simply no-ops.
+- **Phosphor bloom.** The `amber-crt` / `phosphor-green` skins set
+  `--dotmatrix-glow` (a Tier-3 display knob, default `0`) in dark, so the
+  dot-matrix gains a CRT-style glow. Set it yourself on any `.ui-dotmatrix`
+  to tune the bloom.
+- **Contrast-gated.** Every shipped skin accent meets the same WCAG AA / 3:1
+  floors as the core palette — see [contrast.md](contrast.md) → "Display
+  colorways". (Your _own_ `--accent` re-brand is still your obligation; the
+  guarantee covers the shipped palettes and skins.)
+
+## Data-viz palette (`@ponchia/ui/css/dataviz.css`)
+
+Opt-in Tier-4 chart colours for dashboards — **charts only, never UI chrome**
+(a build gate fails on `var(--chart-*)` in component CSS), and never in the
+default bundle.
+
+```html
+<link rel="stylesheet" href="@ponchia/ui/css/dataviz.css" />
+```
+
+```js
+// resolved hex for canvas / SVG / Chart.js etc.
+import charts from '@ponchia/ui/charts.json' with { type: 'json' };
+const series = charts.dark.categorical; // ['#ff3b41', '#e69f00', …] — series 0 = accent
+```
+
+- **Categorical `--chart-1..8`** — hybrid accent-led: series 1 is the live
+  `var(--accent)` (your brand leads), series 2–8 are the Okabe-Ito
+  colourblind-safe set. The set is **gated for mutual distinguishability under
+  normal + simulated protanopia/deuteranopia/tritanopia** (OKLab ΔE).
+- **Sequential `--chart-seq-1..6`** — single-hue light→dark, for
+  heatmaps/intensity. **Diverging `--chart-div-1..7`** — blue↔neutral↔orange,
+  for ±/gains-losses.
+- **Pattern fills `--chart-pattern-1..8`** — a dot-matrix second channel so
+  colour is never the sole signal (WCAG 1.4.1). Pair colour N with pattern N:
+  `background: var(--chart-2); background-image: var(--chart-pattern-2); background-size: var(--chart-pattern-size); --chart-pattern-ink: rgb(0 0 0 / .34);`
+- A chart colour's WCAG ratio vs the background is published **advisory** in
+  [contrast.md](contrast.md) (a fill is not body text) — pick a darker series
+  for thin lines/points, or lean on the pattern.
 
 ## Accessibility markup contracts
 

package/docs/usage.md

@@ -60,6 +60,22 @@ Rule of thumb: state → dot, classification → badge, user-controlled value
   `.ui-card` itself, so card padding/border stays the card's and prose
   rhythm stays the content's. One responsibility per element.
 
+## Static reports
+
+Use the opt-in `@ponchia/ui/css/report.css` layer for static, PDF-first
+reports. A report composes `ui-report` + existing primitives: `ui-statgrid`
+for KPIs, `ui-alert` for persistent notices, `ui-table` for evidence,
+`ui-timeline` for events, `ui-meter` for measured values, and `ui-prose` only
+for narrative body content you do not fully control.
+
+Do not turn every report block into a card. Use `ui-report__summary`,
+`ui-report__finding`, and `ui-report__evidence` for document structure; use
+`ui-card` only when the block is genuinely a repeated card item. Charts use
+the report `ui-chart*` wrappers plus the opt-in data-viz tokens; simple static
+bar charts can use `ui-chart__plot`, `ui-chart__bar`, and `ui-chart__fill`.
+Always include a caption and fallback data. Full LLM/static report cookbook:
+[reporting.md](reporting.md).
+
 ## Buttons: variant and size
 
 - **primary** — the single most important action in a view. Aim for one.
@@ -148,12 +164,14 @@ infinite-clone track). It's a gallery: the user drives it.
 
 ## Display glyphs: when (and when not)
 
-`@ponchia/ui/glyphs` is a 43-glyph dot-matrix icon set — navigation
+`@ponchia/ui/glyphs` is a 48-glyph dot-matrix icon set — navigation
 (`arrow-*`, `chevron-*`), actions (`check`, `close`, `plus`, `minus`,
 `search`, `menu`, `gear`), status (`info`, `warning`, `bell`, `lock`) and
-common marks (`home`, `user`, `heart`, `star`, `spark`) — rendered on the
+common marks (`home`, `user`, `heart`, `star`, `spark`, circle-family marks) — rendered on the
 `.ui-dotmatrix` primitive, so they re-skin with the same `--field-dot*`
-tokens as every other dot surface (no SVG, no icon font).
+tokens as every other dot surface. The default and `solid` renderers emit
+dot-matrix DOM, not an icon font; the dense `.ui-icon` renderer uses an
+internal SVG data URL as a CSS mask so it can stay one DOM node.
 
 **Two rendering modes — pick by size.** The dots need physical room to
 read, so the default _dot_ look is for **display** sizes (~40px up: hero
@@ -198,11 +216,52 @@ A few sharp edges to know:
 - **Directional glyphs are physical, not logical.** `arrow-left/right`,
   `chevron-left/right` are fixed bitmaps; in an RTL context flip them yourself
   (e.g. swap the name, or `transform: scaleX(-1)`), the framework won't.
-- **Cost.** Each glyph is a 16×16 grid = 256 cells (DOM nodes / spans),
-  regardless of mode; `anim: 'reveal'` adds a per-cell `--i` (≈doubles the
-  string size). Fine for display marks and the odd inline icon — but don't
-  render hundreds at once (e.g. one in every row of a long table) without
-  measuring.
+- **Cost / icon-at-scale.** The default (cell) render is a 16×16 grid = 256
+  cells (DOM nodes), regardless of `solid`/`grid`; `anim: 'reveal'` adds a
+  per-cell `--i`. That's the dot-matrix display look — but for **many** icons
+  (one in every row of a long table) use **`renderGlyph(name, { render: 'mask' })`**:
+  it returns a **single** `.ui-icon` element masked by the bitmap (one node, not
+  256), sizes to `size` / `--icon-size` (default `1em`) and inherits
+  `currentColor` — a normal inline icon. Pick `render: 'mask'` for icons,
+  the cell render for display marks/animation.
+
+## Colorways: when to reach for a skin
+
+`@ponchia/ui/css/skins.css` adds `data-bronto-skin="amber-crt |
+phosphor-green | e-ink"` — a **root-level** colorway (apply on `<html>`, like
+`data-theme`) that re-points the one accent to a different single hue.
+
+- **Use a skin** when you want a distinct, on-brand _look_ (a phosphor/CRT or
+  e-ink feel) for the whole page or app — it's the supported, contrast-gated
+  way to recolour without leaving the design system.
+- **Use a raw `--accent` override** when you just need _your_ brand hue: it's
+  one declaration (see "Re-brand obligations" below) — but then contrast is
+  yours, whereas the shipped skins are pre-gated.
+- **Don't** put `data-bronto-skin` on a subtree — it's root-level by design
+  (the derived accent family only recomputes at `:root`); a subtree skin
+  no-ops. For a one-section recolour, scope a raw `--accent` override instead.
+- It's **opt-in**: a separate stylesheet, never in `dist/bronto.css`. No skin
+  imported → zero cost. Full detail in [theming.md](theming.md) → "Display
+  colorways".
+
+## Data-viz colours: charts, not chrome
+
+`@ponchia/ui/css/dataviz.css` (opt-in) adds a Tier-4 chart palette for
+dashboards: `--chart-1..8` (categorical), `--chart-seq-*` (sequential),
+`--chart-div-*` (diverging), and `--chart-pattern-1..8` (dot-matrix fills).
+
+- **Use it for charts only.** These are not UI tokens — a build gate fails if
+  `var(--chart-*)` appears in component CSS. Style buttons/badges with the
+  accent/status tiers, not chart colours.
+- **Series 1 is the accent**, so your brand leads the palette; series 2–8 are a
+  colourblind-safe set (gated for distinctness under protan/deutan/tritan).
+- **Always pair colour with pattern** (`--chart-pattern-N`) and/or a direct
+  label — never colour alone (WCAG 1.4.1):
+  `background: var(--chart-3); background-image: var(--chart-pattern-3); background-size: var(--chart-pattern-size);`
+- **In JS** (Chart.js, canvas, SVG): import resolved hex from
+  `@ponchia/ui/charts.json` (`{ light, dark }`, series 1 = the resolved accent).
+  Cap a chart at ~8 series. Full detail in [theming.md](theming.md) →
+  "Data-viz palette".
 
 ## When to add a behavior
 

package/glyphs/glyphs.d.ts

@@ -10,10 +10,12 @@ export type GlyphName =
   | 'arrow-up'
   | 'bell'
   | 'check'
+  | 'check-circle'
   | 'chevron-down'
   | 'chevron-left'
   | 'chevron-right'
   | 'chevron-up'
+  | 'circle'
   | 'clock'
   | 'close'
   | 'download'
@@ -32,12 +34,14 @@ export type GlyphName =
   | 'mail'
   | 'menu'
   | 'minus'
+  | 'minus-circle'
   | 'moon'
   | 'more-horizontal'
   | 'more-vertical'
   | 'pause'
   | 'play'
   | 'plus'
+  | 'plus-circle'
   | 'refresh'
   | 'search'
   | 'spark'
@@ -46,7 +50,8 @@ export type GlyphName =
   | 'trash'
   | 'upload'
   | 'user'
-  | 'warning';
+  | 'warning'
+  | 'x-circle';
 
 /** A glyph name, or any string — for dynamic dispatch (a CMS/config value). The
  *  known names still autocomplete; an unknown name hits the runtime fallback
@@ -81,6 +86,14 @@ export interface RenderGlyphOptions {
   /** CSS length for the gap between dots (sets `--dotmatrix-gap`; sanitized
    *  the same way as `dot`). */
   gap?: string;
+  /** `'mask'` returns a single `.ui-icon` element masked by the glyph bitmap
+   *  (one DOM node, not GLYPH_SIZE²) — the icon-at-scale path. Inherits
+   *  `currentColor`; the cell-mode options above don't apply. Needs the
+   *  `.ui-icon` rule from `@ponchia/ui/css`. */
+  render?: 'mask';
+  /** With `render: 'mask'`, the icon size (sets `--icon-size`; defaults to
+   *  `1em`; sanitized to a length/calc allowlist). */
+  size?: string;
 }
 
 /** The grid edge length (rows = cols = 16). */