@ponchia/ui 0.4.0 → 0.4.1

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).
 
-- 263 classes across 110 component groups
+- 303 classes across 121 component groups
 - Import the typed registry: `import { cls, ui, cx } from '@ponchia/ui/classes'`
 - Tokens as data: `import { cssVars, tokens, themeColor } from '@ponchia/ui/tokens'`
 
@@ -179,6 +179,18 @@ each one matches a real selector in the stylesheet.
 | `cls.breadcrumb` | `ui-breadcrumb` | base |
 | `cls.breadcrumbItem` | `ui-breadcrumb__item` | part |
 
+### `.ui-break-after`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.breakAfter` | `ui-break-after` | base |
+
+### `.ui-break-before`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.breakBefore` | `ui-break-before` | base |
+
 ### `.ui-button`
 
 | Registry key | Class | Kind |
@@ -226,6 +238,21 @@ each one matches a real selector in the stylesheet.
 | --- | --- | --- |
 | `cls.center` | `ui-center` | base |
 
+### `.ui-chart`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.chart` | `ui-chart` | base |
+| `cls.chartBar` | `ui-chart__bar` | part |
+| `cls.chartCaption` | `ui-chart__caption` | part |
+| `cls.chartFallback` | `ui-chart__fallback` | part |
+| `cls.chartFill` | `ui-chart__fill` | part |
+| `cls.chartLabel` | `ui-chart__label` | part |
+| `cls.chartLegend` | `ui-chart__legend` | part |
+| `cls.chartPlot` | `ui-chart__plot` | part |
+| `cls.chartSwatch` | `ui-chart__swatch` | part |
+| `cls.chartTrack` | `ui-chart__track` | part |
+
 ### `.ui-check`
 
 | Registry key | Class | Kind |
@@ -426,6 +453,12 @@ each one matches a real selector in the stylesheet.
 | --- | --- | --- |
 | `cls.kbd` | `ui-kbd` | base |
 
+### `.ui-keep`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.keep` | `ui-keep` | base |
+
 ### `.ui-key-value`
 
 | Registry key | Class | Kind |
@@ -553,6 +586,18 @@ each one matches a real selector in the stylesheet.
 | --- | --- | --- |
 | `cls.popover` | `ui-popover` | base |
 
+### `.ui-print-exact`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.printExact` | `ui-print-exact` | base |
+
+### `.ui-print-only`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.printOnly` | `ui-print-only` | base |
+
 ### `.ui-progress`
 
 | Registry key | Class | Kind |
@@ -587,12 +632,56 @@ each one matches a real selector in the stylesheet.
 | --- | --- | --- |
 | `cls.ratio` | `ui-ratio` | base |
 
+### `.ui-report`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.report` | `ui-report` | base |
+| `cls.reportAppendix` | `ui-report__appendix` | part |
+| `cls.reportCaption` | `ui-report__caption` | part |
+| `cls.reportCover` | `ui-report__cover` | part |
+| `cls.reportCoverCompact` | `ui-report__cover--compact` | modifier |
+| `cls.reportEvidence` | `ui-report__evidence` | part |
+| `cls.reportFigure` | `ui-report__figure` | part |
+| `cls.reportFinding` | `ui-report__finding` | part |
+| `cls.reportFootnotes` | `ui-report__footnotes` | part |
+| `cls.reportHeader` | `ui-report__header` | part |
+| `cls.reportMeta` | `ui-report__meta` | part |
+| `cls.reportSection` | `ui-report__section` | part |
+| `cls.reportSectionUnnumbered` | `ui-report__section--unnumbered` | modifier |
+| `cls.reportSectionHead` | `ui-report__section-head` | part |
+| `cls.reportSources` | `ui-report__sources` | part |
+| `cls.reportSubtitle` | `ui-report__subtitle` | part |
+| `cls.reportSummary` | `ui-report__summary` | part |
+| `cls.reportTitle` | `ui-report__title` | part |
+| `cls.reportToc` | `ui-report__toc` | part |
+| `cls.reportCompact` | `ui-report--compact` | modifier |
+| `cls.reportNumbered` | `ui-report--numbered` | modifier |
+
 ### `.ui-reveal`
 
 | Registry key | Class | Kind |
 | --- | --- | --- |
 | `cls.reveal` | `ui-reveal` | base |
 
+### `.ui-screen-only`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.screenOnly` | `ui-screen-only` | base |
+
+### `.ui-scroll-progress`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.scrollProgress` | `ui-scroll-progress` | base |
+
+### `.ui-scroll-reveal`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.scrollReveal` | `ui-scroll-reveal` | base |
+
 ### `.ui-search`
 
 | Registry key | Class | Kind |
@@ -832,6 +921,12 @@ each one matches a real selector in the stylesheet.
 | --- | --- | --- |
 | `cls.visuallyHidden` | `ui-visually-hidden` | base |
 
+### `.ui-vt`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.vt` | `ui-vt` | base |
+
 ## Table-local state classes
 
 Not in `cls` by design — these are plain `is-*` state hooks scoped to
@@ -919,10 +1014,10 @@ Exact mirror of the `:root` blocks in `css/tokens.css`
 | `--z-overlay` | `30` |
 | `--z-popover` | `50` |
 | `--z-toast` | `60` |
-| `--accent-1` | `color-mix(in oklch, var(--accent) 8%, var(--bg))` |
-| `--accent-2` | `color-mix(in oklch, var(--accent) 16%, var(--bg))` |
-| `--accent-3` | `color-mix(in oklch, var(--accent) 32%, var(--bg))` |
-| `--accent-4` | `color-mix(in oklch, var(--accent) 60%, var(--bg))` |
+| `--accent-1` | `color-mix(in oklch, var(--accent) 8%, var(--accent-ramp-end))` |
+| `--accent-2` | `color-mix(in oklch, var(--accent) 16%, var(--accent-ramp-end))` |
+| `--accent-3` | `color-mix(in oklch, var(--accent) 32%, var(--accent-ramp-end))` |
+| `--accent-4` | `color-mix(in oklch, var(--accent) 60%, var(--accent-ramp-end))` |
 | `--accent-5` | `var(--accent)` |
 | `--accent-6` | `var(--accent-strong)` |
 | `--surface-1` | `var(--bg)` |
@@ -967,6 +1062,7 @@ Exact mirror of the `:root` blocks in `css/tokens.css`
 | `--text-soft` | `#353533` |
 | `--text-dim` | `#686863` |
 | `--accent` | `#d71921` |
+| `--accent-ramp-end` | `#ffffff` |
 | `--accent-strong` | `color-mix(in srgb, var(--accent) 83%, #000)` |
 | `--accent-text` | `var(--accent-strong)` |
 | `--accent-soft` | `color-mix(in srgb, var(--accent) 10%, transparent)` |
@@ -991,18 +1087,19 @@ Exact mirror of the `:root` blocks in `css/tokens.css`
 
 | Token | Value |
 | --- | --- |
-| `--bg` | `#000000` |
-| `--bg-elevated` | `#0a0a0a` |
+| `--bg` | `#121212` |
+| `--bg-elevated` | `#181818` |
 | `--bg-accent` | `color-mix(in srgb, var(--accent) 8%, transparent)` |
-| `--panel` | `#0c0c0c` |
-| `--panel-strong` | `#141414` |
-| `--panel-soft` | `#1a1a1a` |
-| `--line` | `#2a2a2a` |
-| `--line-strong` | `#444444` |
-| `--text` | `#f2f2f2` |
-| `--text-soft` | `#c4c4c4` |
-| `--text-dim` | `#858585` |
+| `--panel` | `#1c1c1c` |
+| `--panel-strong` | `#222222` |
+| `--panel-soft` | `#242424` |
+| `--line` | `#383838` |
+| `--line-strong` | `#555555` |
+| `--text` | `#e6e6e6` |
+| `--text-soft` | `#c8c8c8` |
+| `--text-dim` | `#a0a0a0` |
 | `--accent` | `#ff3b41` |
+| `--accent-ramp-end` | `#000000` |
 | `--accent-strong` | `color-mix(in srgb, var(--accent) 84%, #fff)` |
 | `--accent-text` | `var(--accent-strong)` |
 | `--accent-soft` | `color-mix(in srgb, var(--accent) 14%, transparent)` |

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 /

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