@ponchia/ui 0.11.0 → 0.12.0

package/docs/renderer.md

@@ -0,0 +1,100 @@
+# Renderer tokens
+
+`@ponchia/ui/renderer` resolves the live bronto theme for renderers that cannot
+read CSS: Vega, xterm.js, a canvas or WebGL graph, a map, a 3D scene. Those
+engines take literal colours, so a page that switches theme, skin, contrast or
+the OLED surface has to resolve its tokens again before each repaint that
+matters.
+
+```js
+import { readTokens, observeTokens, vegaConfig, xtermTheme } from '@ponchia/ui/renderer';
+
+const tokens = readTokens(); // { scheme, bg, panel, text, line, accent, categorical, … }
+view = await embed(el, spec, { config: vegaConfig(tokens, { narrow: el.clientWidth < 480 }) });
+terminal.options.theme = xtermTheme(tokens);
+
+const stop = observeTokens((next) => {
+  terminal.options.theme = xtermTheme(next);
+  rebuildChart(vegaConfig(next));
+});
+```
+
+The static exports serve a different host. [`charts.json`](./theming.md#data-viz-palette)
+and [`tokens/vega.js`](./vega.md) are snapshots per light/dark theme for a
+report, a `file://` document or a build step. They cannot follow a skin or the
+OLED preset; this module reads the page.
+
+## What `readTokens()` returns
+
+Every colour is a renderer literal: `#rrggbb` when opaque, `rgba(r, g, b, a)`
+when translucent. Canvas, SVG, d3-color, xterm.js, three.js and MapLibre all
+accept both.
+
+| Field | Token | Use |
+| --- | --- | --- |
+| `scheme` | luminance of `--bg` | `'light'` or `'dark'` |
+| `bg`, `bgElevated`, `panel`, `panelStrong` | `--bg`, `--bg-elevated`, `--panel`, `--panel-strong` | Backgrounds; draw on `panel` |
+| `text`, `textSoft`, `textDim` | `--text`, `--text-soft`, `--text-dim` | Labels, secondary and tertiary ink |
+| `line`, `lineStrong` | `--line`, `--line-strong` | Grid and hairlines; axes and rules |
+| `accent`, `accentText`, `onAccent`, `focus` | accent family | The one emphasis, its text forms, focus |
+| `selection` | `--accent` at 27% | A translucent selection wash |
+| `success`, `warning`, `danger`, `info` | status tier | Status only, never categories |
+| `sans`, `mono` | `--sans`, `--mono` | Font stacks for a canvas renderer |
+| `categorical` | `--cat-1..8` | Eight hues in fixed order |
+| `categoricalTint` | `--cat-N-tint` | Each hue as a wash over `panel` |
+| `categoricalInk` | `--cat-N-ink` | Each hue as text, 4.5:1 on panel and tint |
+| `sequential`, `diverging` | `--chart-seq-*`, `--chart-div-*` | Ramps for magnitude and ± data |
+
+`readTokens(element)` reads the custom properties as computed on `element`, so a
+subtree that re-points tokens is honoured. Without `css/dataviz.css` on the
+page, the categorical set and the ramps fall back to the packaged palette for
+the resolved scheme, and the tint is computed over the live panel. Without a
+DOM (SSR, tests) it returns the packaged values; pass `{ scheme: 'dark' }` to
+choose.
+
+## Following changes
+
+`observeTokens(callback, { element, signal })` calls back with fresh tokens
+when the root's `data-theme`, `data-bronto-skin`, `data-contrast`,
+`data-surface`, `data-density`, `class` or `style` changes and a token's value
+moved with it, or when the system colour-scheme or contrast preference flips.
+A host that writes its own inline properties on the root every frame (a canvas
+zoom, say) costs one computed-style read per frame and no callback. Calls are
+coalesced to one per animation frame. It returns a stop function; an
+`AbortSignal` also stops it.
+
+A host that already announces its own settled appearance change can read
+`readTokens()` on that event instead and skip the observer.
+
+## Mappings
+
+- **`vegaConfig(tokens, { mode, narrow, background })`** — a Vega-Lite (default)
+  or Vega `config`. Quiet chrome in the bronto inks, no plot frame, the
+  categorical palette as `range.category` (a single series takes its first
+  hue), the sequential ramp for `ordinal`/`ramp`/`heatmap`, the diverging ramp
+  for `diverging`. `narrow` moves the legend under the plot and thins ticks;
+  `background` defaults to transparent so the host panel shows. A spec's own
+  `config` still wins where Vega merges it. The static
+  [`tokens/vega.js`](./vega.md) is this mapping applied to each theme's
+  packaged tokens.
+- **`xtermTheme(tokens)`** — an xterm.js `ITheme`: page ink on the page
+  background, the accent as cursor, the status colours for red, green, yellow
+  and blue, and the categorical magenta and aqua inks for magenta and cyan, so
+  all six ANSI hues differ.
+
+For any other engine, map the fields yourself: they are already the roles a
+renderer needs.
+
+## Conversions
+
+- **`parseColor(value)`** — a resolved CSS colour to `{ r, g, b, alpha }`,
+  clipped into sRGB: hex, `rgb()`, `hsl()`, `oklch()`, `oklab()`, `lab()`,
+  `lch()` and `color(srgb | srgb-linear | display-p3 | xyz-d65 | xyz-d50 …)`.
+  It returns null for `var()`, `color-mix()`, `light-dark()` and named colours,
+  which only a browser can compute.
+- **`formatColor(rgba)`** — `#rrggbb` or `rgba(r, g, b, a)`.
+- **`resolveColor(value, { element })`** — any colour expression to a literal,
+  asking the browser for what `parseColor()` cannot compute.
+
+The module is SSR-safe: it touches the DOM only inside a call that needs it.
+It owns no renderer and imports none.

package/docs/reporting.md

@@ -60,18 +60,18 @@ 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.11.0/dist/bronto.css" />
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.11.0/dist/css/report-kit.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.12.0/dist/bronto.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.12.0/dist/css/report-kit.css" />
 ```
 
 Leaf-by-leaf CDN imports use the same `dist/css/` paths:
 
 ```html
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.11.0/dist/bronto.css" />
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.11.0/dist/css/report.css" />
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.11.0/dist/css/dataviz.css" />
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.11.0/dist/css/annotations.css" />
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.11.0/dist/css/legend.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.12.0/dist/bronto.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.12.0/dist/css/report.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.12.0/dist/css/dataviz.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.12.0/dist/css/annotations.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.12.0/dist/css/legend.css" />
 ```
 
 The CDN serves the package's own `fonts/` next to the CSS, so font URLs resolve
@@ -649,7 +649,7 @@ directly; for a Vega chart, the same colours arrive through
 `brontoVegaConfig`'s `range.*` ramps, projected from `@ponchia/ui/charts.json`.
 
 For a **sequential** figure (a heatmap, a choropleth, a magnitude ramp) fill the
-cells from the single-hue ramp tokens `--chart-seq-1` … `--chart-seq-6`
+cells from the single-hue ramp tokens `--chart-seq-1` … `--chart-seq-5`
 (low → high); for a **diverging** figure (−…0…+) use `--chart-div-1` …
 `--chart-div-7` (the middle band is the neutral midpoint). Both ramps live in
 `css/dataviz.css`, and their resolved per-theme hexes are in
@@ -885,7 +885,7 @@ or validation runtime.
 
 ```json
 {
-  "$schema": "https://cdn.jsdelivr.net/npm/@ponchia/ui@0.11.0/schemas/report-claims.v1.schema.json",
+  "$schema": "https://cdn.jsdelivr.net/npm/@ponchia/ui@0.12.0/schemas/report-claims.v1.schema.json",
   "schemaVersion": "bronto-report-claims.v1",
   "report": { "title": "Decision readiness", "type": "decision" },
   "claims": [

package/docs/stability.md

@@ -1,7 +1,7 @@
 # Public API stability
 
 `@ponchia/ui` is pre-1.0. Breaking changes ship in the minor (`0.x.0`), and
-patches are non-breaking. In practical terms: **PATCH releases (`0.11.x`) are
+patches are non-breaking. In practical terms: **PATCH releases (`0.12.x`) are
 non-breaking bug-fixes and additive changes — safe to upgrade without review;
 MINOR releases (`0.x.0`) may include breaking changes and consumers should
 review the CHANGELOG before upgrading.** Pin `~0.x` (tilde) to accept only
@@ -93,7 +93,8 @@ current public-surface matrix and the release policy above still applies.
 | 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. |
 | Skins (`@ponchia/ui/skins`, `css/skins.css`) | Stable additive | Existing skin names stay valid. New skins are additive. Skins are root-level choices. Skin CSS is opt-in, not in the default bundle. |
-| Charts (`@ponchia/ui/charts`, `charts.json`, `css/dataviz.css`) | Stable additive | Token names, JSON shape, and 8 categorical slots are public. `css/dataviz.css` is opt-in, not in the default bundle. Exact palette values may tune if gates and release notes justify it. |
+| Charts (`@ponchia/ui/charts`, `charts.json`, `css/dataviz.css`) | Stable additive | Token names (`--chart-*`, `--cat-N`, `--cat-N-tint`, `--cat-N-ink`), `CATEGORICAL_HUES`, the JSON shape, and the 8 categorical slots in fixed hue order are public. `css/dataviz.css` is opt-in, not in the default bundle. Exact palette values may tune if gates and release notes justify it. |
+| Renderer tokens (`@ponchia/ui/renderer`) | Stable additive | Function names, option names and the `RendererTokens` field names are public; new fields are additive. Colours are returned as `#rrggbb` or `rgba()` literals. The exact Vega/xterm mapping may tune with the token model. |
 | External renderer themes (`@ponchia/ui/mermaid`, `@ponchia/ui/mermaid.json`, `@ponchia/ui/d2`, `@ponchia/ui/d2.json`, `@ponchia/ui/vega`, `@ponchia/ui/vega.json`) | Stable additive | Theme helper names, JSON shapes, and supported renderer theme slots are public. Values are resolved colours because Mermaid, D2, and Vega cannot consume Bronto CSS variables directly. Exact colours may tune with token changes, but `check:mermaid`, `check:d2`, and `check:vega` must prove every exported theme resolves with no `var()` leaks. No renderer runtime ships. |
 | Shiki theme data (`@ponchia/ui/shiki/nothing.json`) | Stable additive | The bundled Shiki theme JSON shape and token-derived scope roles are public for syntax-highlighting consumers. Exact colours may tune with the token model and must stay generated from the governed palette. |
 | Reports (`css/report.css`, `.ui-report*`, print utilities) | Stable additive | Report class names, BEM part names, and print utility names are public. Report CSS is opt-in and not imported by the default bundle. The data key now lives in the standalone Legends layer (below), not `css/report.css`; charting is via the Vega theme target (`@ponchia/ui/vega`, see [vega](./vega.md)) or a token-themed inline SVG, not a shipped renderer. |

package/docs/theming.md

@@ -309,9 +309,11 @@ you have, so the one-accent discipline holds.
 
 ## Data-viz palette
 
-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.
+Opt-in Tier-4 categorical colour — **never UI chrome** (a build gate fails on
+`var(--chart-*)` or `var(--cat-*)` in component CSS), and never in the default
+bundle. One leaf carries eight fixed hues in two namespaces: `--chart-*` for
+data-viz series and ramps, and `--cat-*` for categorical **identity** — a tag,
+a participant, a user-chosen tint.
 
 ```html
 <link rel="stylesheet" href="@ponchia/ui/css/dataviz.css" />
@@ -320,28 +322,36 @@ default bundle.
 ```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
+const series = charts.dark.categorical; // ['#3987e5', '#d95926', …] — blue first
 ```
 
-- **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).
-  **Caveat — the CVD gate measures the SHIPPED default accent.** Series 1 is
-  `var(--accent)`, so if you re-skin `--accent` you change series 1 but not the
-  Okabe-Ito 2–8, and the gate never re-checks your custom hue: a brand close to
-  series 3's orange can collide for a deuteranope. If a re-brand drives data-viz,
-  re-verify your accent against the set, or pin `--chart-1` to a fixed Okabe-Ito
-  value (`--chart-1: #0072b2`) and let your brand lead the UI only.
-- **Sequential `--chart-seq-1..6`** — single-hue light→dark, for
-  heatmaps/intensity. **Diverging `--chart-div-1..7`** — blue↔neutral↔orange,
-  for ±/gains-losses.
+For a page that switches theme, skin, contrast or the OLED surface at runtime,
+read the live values with [`@ponchia/ui/renderer`](renderer.md) instead of the
+static JSON.
+
+- **Categorical `--chart-1..8` = `--cat-1..8`** — blue, orange, aqua, yellow,
+  magenta, green, violet, red, in that fixed order (`CATEGORICAL_HUES` names
+  them). No slot is the accent, so an ordinary first series never reads as an
+  alert. `check:charts` measures each theme against the panel, the page and
+  the OLED surfaces: OKLCH lightness inside the theme's band, chroma above the
+  grey floor, adjacent slots separated under simulated protanopia and
+  deuteranopia and in normal vision. Slots under 3:1 against a surface are
+  reported in the gate output; relief is the pattern fill or a direct label.
+  Any two slots can meet in a scatter or a map, so pair colour with pattern
+  there.
+- **Identity `--cat-N-tint` / `--cat-N-ink`** — a 16% wash of the hue over
+  `--panel` (it follows a skin's or OLED's panel) and a text colour that holds
+  4.5:1 on the panel, the page and its own tint. Use them for a tag chip, a
+  participant's name, or a user-chosen highlight — never for status.
+- **Sequential `--chart-seq-1..5`** — one blue hue; step 1 sits nearest the
+  surface (pale in light, deep in 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.
+  [contrast.md](contrast.md) (a fill is not body text) — for thin lines or
+  points use the slot's `--cat-N-ink`, or lean on the pattern.
 
 ## Accessibility markup contracts
 

package/docs/usage.md

@@ -584,18 +584,22 @@ phosphor-green | e-ink"` — a **root-level** colorway (apply on `<html>`, like
 
 `@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).
+`--chart-div-*` (diverging), and `--chart-pattern-1..8` (dot-matrix fills), plus
+the same eight hues as categorical identity: `--cat-N`, `--cat-N-tint` and
+`--cat-N-ink` for tags, participants and user-chosen tints.
+
+- **Use it for categories, never for chrome or status.** A build gate fails if
+  `var(--chart-*)` or `var(--cat-*)` appears in component CSS. Style buttons
+  and badges with the accent/status tiers.
+- **No slot is the accent.** The order is fixed (blue, orange, aqua, yellow,
+  magenta, green, violet, red) and adjacent slots are gated for separation
+  under simulated protanopia/deuteranopia and in normal vision.
 - **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).
+  `@ponchia/ui/charts.json` (`{ hues, light, dark }`), or read the live page
+  with [`@ponchia/ui/renderer`](renderer.md) when it can change skin or theme.
   Cap a chart at ~8 series. Full detail in [theming.md](theming.md) →
   "Data-viz palette".
 

package/docs/vega.md

@@ -113,18 +113,23 @@ colours are **baked into the output** and parsed by `d3-color`, which understand
 real hex/rgb but **not** `var()` (nor `oklch()`). So the config ships **resolved
 hex per theme**, projected from the same token source as
 [`tokens/resolved.json`](./architecture.md) / [`charts.json`](./theming.md).
-Re-call `brontoVegaConfig()` when the theme toggles and re-embed.
+Re-call `brontoVegaConfig()` when the theme toggles and re-embed. A page that
+switches skin, contrast or the OLED surface at runtime cannot be served by a
+per-theme snapshot: build the config from the live page with
+[`@ponchia/ui/renderer`](./renderer.md) — `vegaConfig(readTokens())` is the
+same mapping these files are generated from.
 
 ### What the slots paint
 
-The config keeps a chart **monochrome by default** — the rationed accent is the
-one chromatic default (series 1 / the lone mark), never the chrome:
+The chrome stays quiet and neutral; colour is spent on data. The plot has no
+frame (a chart already sits on a panel), and a single series takes the first
+categorical hue rather than the alert accent:
 
 | Slot | Paint | bronto token |
 | --- | --- | --- |
-| `background` | Chart canvas | `--bg` |
-| `view.stroke` | Plot frame | `--line` |
-| `mark.color` | Default / single-series mark | `--accent` |
+| `background` | Chart canvas | `--bg` (runtime default: transparent) |
+| `view.stroke` | Plot frame | none (`null`) |
+| `mark.color` | Default / single-series mark | `--chart-1` |
 | `rule.color` | Reference rules, annotations | `--line-strong` |
 | `axis.domainColor` · `tickColor` | Axis line · ticks | `--line-strong` |
 | `axis.gridColor` | Gridlines | `--line` |
@@ -132,7 +137,8 @@ one chromatic default (series 1 / the lone mark), never the chrome:
 | `text.color` | Free `text`/`label` marks | `--text` |
 | `legend.*` · `header.*` · `title.*` | Legend, facet headers, title | `--text-soft` / `--text` / `--text-dim` |
 | `*.font` / `*Font` | All text | `--sans` |
-| `range.category` | 8-series categorical palette | `charts.json` categorical (series 1 = accent) |
+| `rect`/`arc`/`area` `.stroke` | Gap between adjacent fills | `--panel` |
+| `range.category` | 8-series categorical palette | `charts.json` categorical (blue first) |
 | `range.ordinal` · `ramp` · `heatmap` | Single-hue sequential ramp | `charts.json` sequential |
 | `range.diverging` | − … neutral … + ramp | `charts.json` diverging |
 
@@ -143,14 +149,12 @@ series needs the redundant second channel, drive the mark's fill from the
 
 ### Spending the accent
 
-Series 1 of `range.category` resolves to the accent (per theme), so a single-series
-chart and the first category carry the accent automatically — baked into the
-generated `config`, so regenerate the config and re-render to change it (Vega output
-does not live-reskin from `--accent`). To emphasise one mark in a
-multi-series chart, paint just that mark with the accent and leave the rest
-neutral — the same "reserve the accent for the one thing a reader must not miss"
-rule the rest of the system follows. Two small helpers hand you the exact
-per-theme hexes so you never hard-code a palette array index:
+No categorical slot is the accent, so an ordinary chart never reads as an
+alert. To emphasise one mark, paint just that mark with the accent and leave
+the rest neutral — the same "reserve the accent for the one thing a reader must
+not miss" rule the rest of the system follows. Two small helpers hand you the
+exact per-theme hexes (baked into the generated files; Vega output does not
+live-reskin from `--accent`):
 
 ```js
 import { brontoVegaAccent, brontoVegaNeutral } from '@ponchia/ui/vega';
@@ -171,14 +175,11 @@ const spec = {
 };
 ```
 
-`brontoVegaAccent(theme)` is `range.category[0]` (the resolved accent) and
-`brontoVegaNeutral(theme)` is the last category (the quiet neutral); re-read both
-when the theme toggles. Prefer them over digging the hex out of
-`tokens/resolved.json` — they are guaranteed to match the palette the config
-already ships. In token terms the accent is `--chart-1` and the neutral is
-`--chart-8`, so a [legend](./legends.md#swatch-colour) for an accent-rationed
-chart keys those two series with `ui-legend__swatch--1` and
-`ui-legend__swatch--8` — the swatches mirror the marks exactly.
+`brontoVegaAccent(theme)` is the resolved `--accent` and `brontoVegaNeutral(theme)`
+the resolved `--text-dim`; re-read both when the theme toggles. A
+[legend](./legends.md#swatch-colour) for an accent-rationed chart keys the two
+with inline swatch colours (`style="--chart-color: …"`), not with categorical
+slots.
 
 ### Selecting the themed ramp in a spec
 

package/llms.txt

@@ -45,7 +45,7 @@ the path changes from source `css/` to built `dist/css/`:
 <!-- installed locally -->
 <link rel="stylesheet" href="./node_modules/@ponchia/ui/dist/css/<leaf>.css" />
 <!-- or from a CDN; pin the version (pre-1.0, breaking changes ship in the minor) -->
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.11.0/dist/css/<leaf>.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.12.0/dist/css/<leaf>.css" />
 ```
 
 The flattened default bundle is `dist/bronto.css` (bundler shorthand
@@ -183,7 +183,9 @@ Charting is the same path: bronto does NOT ship a chart component (a chart needs
 scales + data binding, which the analytical layer refuses). For charts, recommend
 Vega-Lite — a declarative JSON spec an external system can emit — themed by the
 on-brand `config` (resolved hex; Vega bakes colours into SVG/canvas, can't read
-`var()`). `range.category` is the `--chart-*` palette, series 1 = accent:
+`var()`). `range.category` is the `--chart-*` palette (blue first; no slot is the
+accent). For a live page that switches skin or theme, build the same config at
+runtime with `vegaConfig(readTokens())` from `@ponchia/ui/renderer`:
 
 ```js
 import { brontoVegaConfig, brontoVegaAccent, brontoVegaNeutral } from '@ponchia/ui/vega';
@@ -204,8 +206,10 @@ accent-filled DOM control, set `--button-text`. Details: `docs/vega.md`. (Observ
 Plot works too — it inherits the page CSS, so it needs even less theming;
 Vega-Lite is the recommended LLM-emittable path.)
 
-`--chart-1..8` (categorical; series 1 = accent; colourblind-safe, gated under
-simulated protan/deutan/tritan), `--chart-seq-*` (sequential), `--chart-div-*`
+`--chart-1..8` (categorical: blue, orange, aqua, yellow, magenta, green, violet,
+red; adjacent slots gated under simulated protan/deutan), `--cat-N` /
+`--cat-N-tint` / `--cat-N-ink` (the same hues as tag/participant identity),
+`--chart-seq-*` (sequential), `--chart-div-*`
 (diverging), and `--chart-pattern-1..8` (dot-matrix fills — pair colour N with
 pattern N; colour is never the sole signal). Details in `docs/theming.md`.
 

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@ponchia/ui",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "type": "module",
-  "description": "CSS-first identity and UI layer for services, tools, sites, and reports \u2014 works in HTML, every framework, and PDF, no component runtime. Shared app shell, forms, tables, workflow chrome, plus opt-in analytical/report primitives. Monochrome with one rationed accent. Zero runtime dependencies.",
+  "description": "CSS-first identity and UI layer for services, tools, sites, and reports — works in HTML, every framework, and PDF, no component runtime. Shared app shell, forms, tables, workflow chrome, plus opt-in analytical/report primitives. Monochrome with one rationed accent. Zero runtime dependencies.",
   "keywords": [
     "css",
     "ui",
@@ -58,6 +58,7 @@
     "schemas",
     "annotations",
     "connectors",
+    "renderer",
     "shiki",
     "llms.txt",
     "CHANGELOG.md",
@@ -82,6 +83,7 @@
     "docs/legends.md",
     "docs/marks.md",
     "docs/connectors.md",
+    "docs/renderer.md",
     "docs/spotlight.md",
     "docs/crosshair.md",
     "docs/selection.md",
@@ -119,7 +121,8 @@
     "docs/adr/0005-productive-tools-and-editorial-reports.md",
     "docs/migrations/0.9-to-0.10.md",
     "docs/adr/0006-trusted-publishing.md",
-    "docs/migrations/0.10-to-0.11.md"
+    "docs/migrations/0.10-to-0.11.md",
+    "docs/migrations/0.11-to-0.12.md"
   ],
   "style": "./dist/bronto.css",
   "scripts": {
@@ -364,6 +367,7 @@
     "./docs/legends.md": "./docs/legends.md",
     "./docs/marks.md": "./docs/marks.md",
     "./docs/connectors.md": "./docs/connectors.md",
+    "./docs/renderer.md": "./docs/renderer.md",
     "./docs/spotlight.md": "./docs/spotlight.md",
     "./docs/crosshair.md": "./docs/crosshair.md",
     "./docs/selection.md": "./docs/selection.md",
@@ -500,6 +504,10 @@
       "types": "./connectors/index.d.ts",
       "default": "./connectors/index.js"
     },
+    "./renderer": {
+      "types": "./renderer/index.d.ts",
+      "default": "./renderer/index.js"
+    },
     "./skins": {
       "types": "./tokens/skins.d.ts",
       "default": "./tokens/skins.js"
@@ -530,6 +538,7 @@
     "./docs/migrations/0.9-to-0.10.md": "./docs/migrations/0.9-to-0.10.md",
     "./docs/adr/0006-trusted-publishing.md": "./docs/adr/0006-trusted-publishing.md",
     "./docs/migrations/0.10-to-0.11.md": "./docs/migrations/0.10-to-0.11.md",
+    "./docs/migrations/0.11-to-0.12.md": "./docs/migrations/0.11-to-0.12.md",
     "./css/discussion.css": "./dist/css/discussion.css",
     "./css/unlayered/discussion.css": "./css/discussion.css",
     "./docs/discussion.md": "./docs/discussion.md"