@ponchia/ui 0.4.1 → 0.6.0

package/docs/annotations.md

@@ -0,0 +1,425 @@
+# SVG annotations
+
+`@ponchia/ui/css/annotations.css` is an opt-in SVG annotation layer for charts,
+reports, and analytical figures. It follows the same grammar as
+d3-annotation: a **subject** marks the thing being discussed, a **connector**
+points away from it, and a **note** carries the visible explanation.
+
+```css
+@import '@ponchia/ui';
+@import '@ponchia/ui/css/annotations.css';
+```
+
+Use it with any SVG renderer. Bronto supplies classes and tiny geometry helpers;
+it does not own chart scales, mutate the DOM, or provide draggable edit mode.
+
+```js
+import {
+  annotationParts,
+  annotationTransform,
+  axisThresholdPath,
+  bracketSubjectPath,
+  circleSubjectPath,
+  connectorLine,
+  evidenceMarkerPath,
+  notePlacement,
+  noteTransform,
+} from '@ponchia/ui/annotations';
+
+const transform = annotationTransform({ x: 180, y: 72 });
+const subject = circleSubjectPath({ radius: 18 });
+const connector = connectorLine({
+  dx: 88,
+  dy: -42,
+  subject: { type: 'circle', radius: 18, radiusPadding: 4 },
+});
+const parts = annotationParts({
+  x: 180,
+  y: 72,
+  dx: 88,
+  dy: -42,
+  subject: { type: 'circle', radius: 18, radiusPadding: 4 },
+});
+const note = notePlacement({
+  x: 180,
+  y: 72,
+  width: 96,
+  height: 44,
+  bounds: { x: 0, y: 0, width: 360, height: 180 },
+  preferred: 'right',
+});
+```
+
+## Markup model
+
+Author annotation groups at the subject anchor. Use `dx` / `dy` as the note
+offset, matching d3-annotation's mental model.
+
+```html
+<svg viewBox="0 0 360 180" role="img" aria-labelledby="chart-title chart-desc">
+  <title id="chart-title">Annotated delivery chart</title>
+  <desc id="chart-desc">A callout marks the delivery peak.</desc>
+
+  <g
+    class="ui-annotation ui-annotation--circle ui-annotation--accent"
+    transform="translate(180, 72)"
+  >
+    <path class="ui-annotation__subject" d="M0,-18A18,18 0 1 1 0,18A18,18 0 1 1 0,-18Z" />
+    <path class="ui-annotation__connector" d="M15.556,-7.424L88,-42" />
+    <g class="ui-annotation__note" transform="translate(88, -42)">
+      <path class="ui-annotation__note-line" d="M0,0H76" />
+      <text class="ui-annotation__title" y="-8">Peak</text>
+      <text class="ui-annotation__label" y="12">Delivery spike</text>
+    </g>
+  </g>
+</svg>
+```
+
+The visible note text should also be represented in the figure caption,
+`<desc>`, fallback table, or surrounding prose when the figure is complex.
+
+Match the accessibility treatment to the annotation's job, in both directions:
+a **data** annotation (a peak, a threshold, a watched region — it says something
+the reader needs) must stay readable, so represent its text as above and do
+**not** `aria-hidden` it; a purely **decorative** mark (a cover flourish, a
+margin doodle that carries no data) should be `aria-hidden="true"` and
+`focusable="false"` on the whole SVG so a screen reader skips the decoration.
+The one thing to avoid is the middle: a meaningful callout hidden from assistive
+tech, or decoration announced as if it were data.
+
+## Variants and motion
+
+Use one variant class per annotation group. Variants describe the visual
+grammar, not data semantics:
+
+| Variant | Use |
+| --- | --- |
+| `ui-annotation--label` | Direct label with no connector. |
+| `ui-annotation--callout` | Plain point-to-note callout. |
+| `ui-annotation--elbow` | Dogleg connector around dense marks. |
+| `ui-annotation--curve` | Softer connector for paths or flows. |
+| `ui-annotation--circle` | Circular subject around a point or local cluster. |
+| `ui-annotation--rect` | Rectangular subject around a bar, block, or region. |
+| `ui-annotation--threshold` | Horizontal or vertical limit rule. |
+| `ui-annotation--badge` | Compact numbered or categorical mark. |
+| `ui-annotation--bracket` | Range span on one axis. |
+| `ui-annotation--band` | Interval, confidence band, or risk window. |
+| `ui-annotation--slope` | Trend or slope segment. |
+| `ui-annotation--compare` | Before/after or A/B grouping. |
+| `ui-annotation--cluster` | Several nearby outliers. |
+| `ui-annotation--axis` | Axis milestone or reference tick. |
+| `ui-annotation--timeline` | Event pin on a timeline. |
+| `ui-annotation--evidence` | Proof, source, or evidence marker. |
+
+Tones are `accent`, `muted`, `success`, `warning`, `danger`, and `info`.
+Status tones (`success`, `warning`, `danger`, `info`) are only for annotations
+that carry that status meaning.
+
+Motion is opt-in and respects `prefers-reduced-motion`:
+
+| Motion class | Effect |
+| --- | --- |
+| `ui-annotation--draw` | Connectors draw in once; subjects reveal without losing dashed variant styling. |
+| `ui-annotation--reveal` | Note fades into place. |
+| `ui-annotation--pulse` | Subject or badge pulses gently. |
+| `ui-annotation--focus` | Static emphasis with a stronger subject stroke. |
+
+The class recipe mirrors this surface:
+
+```js
+ui.annotation({ variant: 'bracket', tone: 'info', motion: 'draw' });
+// "ui-annotation ui-annotation--bracket ui-annotation--info ui-annotation--draw"
+```
+
+## Geometry helpers
+
+The helper module returns SVG strings only. It does not know about scales,
+selections, DOM nodes, or frameworks.
+
+| Helper | Returns |
+| --- | --- |
+| `annotationTransform({ x, y })` | Group transform for the subject anchor. |
+| `noteTransform({ dx, dy, align, valign, width, height })` | Note transform from the subject anchor, with optional alignment. |
+| `notePlacement({ x, y, width, height, bounds, preferred, inset })` | Bounded note offset, alignment and transform for one annotation. `inset` reserves an extra margin (e.g. the title stroke-halo, ~3) so a placement that "fits" doesn't clip. |
+| `declutterLabels(items, { gap, min, max })` | Adjusted centres for `items` (`[{ pos, size }]`) so labels don't overlap along one axis (order-preserving). |
+| `directLabels(items, { axis, cross, gap, min, max, shape })` | Decluttered label points **and** a leader path per item: `[{ x, y, anchor, key, d }]`. |
+| `circleSubjectPath({ radius })` | Circle subject path. |
+| `rectSubjectPath({ x, y, width, height, padding })` | Rect subject path. |
+| `thresholdPath({ x1, y1, x2, y2 })` | Arbitrary threshold/rule path. |
+| `axisThresholdPath({ orientation, value, start, end })` | Horizontal or vertical axis-aligned threshold. |
+| `bracketSubjectPath({ x1, y1, x2, y2, depth })` | Dogleg bracket path. |
+| `bandSubjectPath({ x, y, width, height, padding })` | Band or interval path. |
+| `slopeSubjectPath({ x1, y1, x2, y2 })` | Trend segment path. |
+| `comparisonBracePath({ x1, y1, x2, y2, depth })` | Comparison brace path. |
+| `outlierClusterPath({ points, radius })` | Repeated circle subjects for a cluster. |
+| `timelineEventPath({ size, direction })` | Event pin marker path. |
+| `evidenceMarkerPath({ x, y, width, height, padding })` | Centered square/rect evidence marker path. |
+| `connectorLine({ dx, dy, subject })` | Straight connector, trimmed against circle/rect subjects. |
+| `connectorElbow({ dx, dy, subject, mid })` | Right-angle dogleg connector (H/V/H); `mid` (0..1, default 0.5) sets the turn position along the dominant axis. |
+| `connectorCurve({ dx, dy, subject })` | Deterministic cubic connector. |
+| `connectorEndDot({ x, y, radius })` | Dot marker path. |
+| `connectorEndArrow({ x1, y1, x2, y2, size, spread })` | Arrow marker path. `x1,y1`→`x2,y2` sets the direction (the head sits at `x2,y2`); `spread` is the half-angle (default 0.32 ≈ a crisp 37° head). |
+| `annotationParts(options)` | Convenience object with `transform`, `subject`, `connector`, and `note`. |
+
+`declutterLabels` is a deliberately small, deterministic **1-D** declutter for
+direct labels or axis ticks — sort, push overlaps apart by `size + gap`, slide
+to fit under `max`. It is **not** a general 2-D collision solver: if more labels
+are requested than the axis can hold, the overflow is yours to resolve (fewer
+labels, a longer axis, or rotation). It returns numbers; you own the scale and
+the DOM.
+
+`directLabels` is the **direct-labeling** companion: it declutters labels along
+one axis _and_ draws the leader from each true anchor to its placed label,
+reusing the connector kernel. Each `items[i]` is `{ anchor: {x, y}, size, key? }`
+in figure coordinates; labels declutter along `axis` (`'y'` = a vertical column,
+the default) and sit at the fixed `cross` coordinate. It returns, in input
+order, the placed label point `{ x, y }`, the echoed `anchor`/`key`, and the
+leader path `d` (`shape`: `straight` · `elbow` · `curve`). Like everything here
+it owns no scales, no DOM, and no 2-D placement — map data → figure coordinates
+first, then drop each `d` into a `<path class="ui-annotation__connector">` and
+position the label at `{ x, y }`:
+
+```js
+import { directLabels } from '@ponchia/ui/annotations';
+
+// anchors are data points already projected into the figure's SVG coords
+const labels = directLabels(
+  points.map((p) => ({ anchor: p, size: 18, key: p.id })),
+  { axis: 'y', cross: width - 8, gap: 6, min: 12, max: height - 12 },
+);
+// labels[i] → { x, y, anchor, key, d }
+```
+
+All numeric inputs must be finite. Negative radius, width, height, padding, and
+marker size throw `RangeError`; non-finite values throw `TypeError`. Path
+numbers are rounded to three decimals with trailing zeros removed so snapshots
+and unit tests stay stable.
+
+`notePlacement()` is intentionally small: it places one note inside explicit SVG
+bounds using a preferred side (`right`, `left`, `top`, or `bottom`) and falls
+back to another side or a clamped note transform. It is not a collision solver
+for a whole chart. For dense annotation sets, pre-compute positions or author a
+mobile-specific SVG.
+
+### Using the helpers in a static, no-JS report
+
+The [report layer](./reporting.md) is static and ships no behavior JS, but these
+helpers are JS — so in a hand- or LLM-authored report you can't call them at
+render time. Bridge the gap by running them **once, at author/build time**, and
+pasting the returned strings straight into the SVG. The output is deterministic
+(path numbers are rounded to three decimals), so the strings are stable and
+diff-friendly.
+
+```js
+// author-time only — copy the logged strings into the static HTML
+import { circleSubjectPath, connectorLine } from '@ponchia/ui/annotations';
+
+circleSubjectPath({ radius: 15 });
+// "M0,-15A15,15 0 1 1 0,15A15,15 0 1 1 0,-15Z"
+connectorLine({ dx: 78, dy: -38, subject: { type: 'circle', radius: 15, radiusPadding: 0 } });
+// "M13.485,-6.57L78,-38"
+```
+
+The static markup then carries only the resolved strings — no runtime, no
+import:
+
+```html
+<g class="ui-annotation ui-annotation--circle ui-annotation--accent" transform="translate(34, 58)">
+  <path class="ui-annotation__subject" d="M0,-15A15,15 0 1 1 0,15A15,15 0 1 1 0,-15Z" />
+  <path class="ui-annotation__connector" d="M13.485,-6.57L78,-38" />
+  <g class="ui-annotation__note" transform="translate(78, -38)">…</g>
+</g>
+```
+
+## Using annotations off-chart
+
+Annotations are not only for charts. Two report uses worth calling out:
+
+- **A decorative margin mark.** A small `ui-annotation` group — a circled point
+  with a short note — adds a hand-annotated feel to a report cover or section
+  opener. It carries no data, so mark the whole SVG `aria-hidden="true"` and
+  `focusable="false"`: a screen reader should not read decoration.
+
+```html
+<svg width="440" height="92" viewBox="0 0 440 92" aria-hidden="true" focusable="false">
+  <g class="ui-annotation ui-annotation--circle ui-annotation--accent" transform="translate(34, 58)">
+    <path class="ui-annotation__subject" d="M0,-15A15,15 0 1 1 0,15A15,15 0 1 1 0,-15Z" />
+    <circle r="3.5" fill="var(--accent)" />
+    <path class="ui-annotation__connector" d="M13.485,-6.57L78,-38" />
+    <g class="ui-annotation__note" transform="translate(78, -38)">
+      <path class="ui-annotation__note-line" d="M0,0H188" />
+      <text class="ui-annotation__title" y="-8">You are here</text>
+      <text class="ui-annotation__label" y="12">a short, terse label</text>
+    </g>
+  </g>
+</svg>
+```
+
+- **Bracketing a passage of prose belongs to marks, not here.** To bracket a
+  sentence or paragraph in running text, use `.ui-bracket-note` from the
+  [marks layer](./marks.md) — it is the prose analogue of
+  `ui-annotation--bracket`. SVG annotations are for SVG figures.
+
+## Sizing: the user-unit trap
+
+Annotation text (`__title`, `__label`) is sized in **SVG user units**, so it
+scales with the figure. A 360-unit-wide chart stretched across a full report
+column is scaled roughly 2.5–3×, and the callout text scales with it — long
+notes turn huge and overflow the `viewBox` (SVG text is clipped, not wrapped).
+Two rules keep callouts readable:
+
+- **Keep note text terse** — a title and a few words, like the recipe examples
+  (`Peak`, `Limit`, `80 kB cap`). Push the full sentence into the figure caption,
+  the `<desc>`, or the fallback table.
+- **Constrain the figure width** so the user-unit → pixel scale stays near
+  1–1.5×: set a `max-inline-size` on the SVG instead of letting it stretch to the
+  whole column, or author the `viewBox` at roughly the rendered pixel size.
+
+## Density and responsive rules
+
+Annotations are strongest when they explain the few things a reader would miss.
+As a default, keep a single chart to three to five visible callouts. Use direct
+labels for stable context, one accent callout for the main insight, and status
+tones only for genuine status.
+
+Dense SVGs should not shrink until the notes become unreadable. Use one of
+these patterns:
+
+- Keep the chart wide in a horizontally scrollable figure and provide fallback
+  table text.
+- Author a simpler mobile SVG with fewer annotations.
+- Move low-priority annotation text into the caption or fallback table on small
+  screens.
+
+## Recipes
+
+### Label
+
+Use `ui-annotation--label` for direct labels when the subject is already clear.
+
+```html
+<g class="ui-annotation ui-annotation--label ui-annotation--muted" transform="translate(112, 48)">
+  <g class="ui-annotation__note">
+    <text class="ui-annotation__title">Baseline</text>
+    <text class="ui-annotation__label" y="16">Previous quarter</text>
+  </g>
+</g>
+```
+
+### Circle callout
+
+Use a circle subject when the referenced point or local cluster matters.
+
+```html
+<g class="ui-annotation ui-annotation--circle ui-annotation--accent" transform="translate(180, 72)">
+  <path class="ui-annotation__subject" d="M0,-18A18,18 0 1 1 0,18A18,18 0 1 1 0,-18Z" />
+  <path class="ui-annotation__connector" d="M15.556,-7.424L88,-42" />
+  <g class="ui-annotation__note" transform="translate(88, -42)">
+    <path class="ui-annotation__note-line" d="M0,0H84" />
+    <text class="ui-annotation__title" y="-8">Spike</text>
+    <text class="ui-annotation__label" y="12">Investigate change</text>
+  </g>
+</g>
+```
+
+### Rect callout
+
+Use a rect subject for a band, bar, table region, or evidence block inside an
+SVG figure.
+
+```html
+<g class="ui-annotation ui-annotation--rect ui-annotation--warning" transform="translate(206, 92)">
+  <path class="ui-annotation__subject" d="M-34,-16H34V16H-34Z" />
+  <path class="ui-annotation__connector" d="M34,-16L72,-46" />
+  <g class="ui-annotation__note" transform="translate(72, -46)">
+    <path class="ui-annotation__note-line" d="M0,0H96" />
+    <text class="ui-annotation__title" y="-8">Watch</text>
+    <text class="ui-annotation__label" y="12">Lower confidence</text>
+  </g>
+</g>
+```
+
+### Threshold
+
+Use `ui-annotation--threshold` when a horizontal or vertical rule is the
+subject.
+
+```html
+<g class="ui-annotation ui-annotation--threshold ui-annotation--danger" transform="translate(0, 96)">
+  <path class="ui-annotation__subject" d="M36,0L324,0" />
+  <path class="ui-annotation__connector" d="M240,0L282,-32" />
+  <g class="ui-annotation__note" transform="translate(282, -32)">
+    <text class="ui-annotation__title">Limit</text>
+    <text class="ui-annotation__label" y="16">Do not exceed</text>
+  </g>
+</g>
+```
+
+### Badge
+
+Use badges for compact numbered or categorical markers. Do not rely on the badge
+color alone; pair it with visible text, a caption, or a table row.
+
+```html
+<g class="ui-annotation ui-annotation--badge ui-annotation--info" transform="translate(72, 84)">
+  <circle class="ui-annotation__badge" r="12" />
+  <text class="ui-annotation__title" text-anchor="middle" dominant-baseline="central">1</text>
+</g>
+```
+
+## Chart figure recipe
+
+Inside a report, keep the existing chart structure: caption, legend or direct
+labels, annotated SVG, and fallback data. A useful annotated figure should show
+more than one annotation family when the story needs it: direct labels for
+stable references, threshold annotations for limits, circle/rect subjects for
+specific data, and badge markers for compact index points.
+
+```html
+<figure class="ui-report__figure ui-print-exact" role="group" aria-labelledby="annotated-chart">
+  <figcaption id="annotated-chart" class="ui-report__caption">
+    Fig 2 - Weekly throughput, annotated at the peak
+  </figcaption>
+  <svg viewBox="0 0 360 160" role="img" aria-labelledby="throughput-title throughput-desc">
+    <title id="throughput-title">Weekly throughput with a peak callout</title>
+    <desc id="throughput-desc">Annotations mark the baseline, limit and highest research week.</desc>
+    <line x1="36" y1="112" x2="324" y2="112" stroke="var(--line)" />
+    <rect x="88" y="42" width="72" height="70" fill="var(--chart-1)" />
+    <rect x="188" y="70" width="72" height="42" fill="var(--chart-2)" />
+    <g class="ui-annotation ui-annotation--label ui-annotation--muted" transform="translate(36, 132)">
+      <g class="ui-annotation__note">
+        <text class="ui-annotation__title">Baseline</text>
+        <text class="ui-annotation__label" y="16">Previous quarter</text>
+      </g>
+    </g>
+    <g class="ui-annotation ui-annotation--threshold ui-annotation--danger" transform="translate(0, 66)">
+      <path class="ui-annotation__subject" d="M36,0L324,0" />
+      <path class="ui-annotation__connector" d="M272,0L304,-28" />
+      <g class="ui-annotation__note" transform="translate(234, -52)">
+        <text class="ui-annotation__title">Limit</text>
+        <text class="ui-annotation__label" y="16">Watch capacity</text>
+      </g>
+    </g>
+    <g class="ui-annotation ui-annotation--circle ui-annotation--accent" transform="translate(124, 42)">
+      <path class="ui-annotation__subject" d="M0,-18A18,18 0 1 1 0,18A18,18 0 1 1 0,-18Z" />
+      <path class="ui-annotation__connector" d="M16,-8L76,-36" />
+      <g class="ui-annotation__note" transform="translate(76, -36)">
+        <path class="ui-annotation__note-line" d="M0,0H80" />
+        <text class="ui-annotation__title" y="-8">Peak</text>
+        <text class="ui-annotation__label" y="12">Research high</text>
+      </g>
+    </g>
+  </svg>
+  <div class="ui-table-wrap">
+    <table class="ui-table ui-table--dense">
+      <caption>Annotated chart source data</caption>
+      <thead><tr><th>Week</th><th class="is-num">Hours</th></tr></thead>
+      <tbody><tr><td>Week 4</td><td class="is-num">18</td></tr></tbody>
+    </table>
+  </div>
+</figure>
+```
+
+Status tones (`success`, `warning`, `danger`, `info`) are only for annotations
+that carry that status meaning. Use `accent` for the primary insight and
+`muted` for secondary callouts.

package/docs/architecture.md

@@ -0,0 +1,246 @@
+# Architecture & Decisions
+
+Status: accepted · 2026-05-15 · applies from v0.2.0
+
+> **Separate ADRs.** Larger, self-contained decisions live under
+> [`docs/adr/`](./adr/):
+>
+> - [ADR-0001 — Color system: governed evolution beyond monochrome](./adr/0001-color-system.md)
+>   (accepted; steps 1–8 implemented in 0.4.0) — the five-tier color
+>   constitution, the `check:color-policy`/`check:skins`/`check:charts`
+>   gates, opt-in colorways, data-viz, APCA advisory reporting, and the
+>   OKLCH core accent ramp.
+
+## Context
+
+`@ponchia/ui` is the shared design layer for several projects on
+different stacks: Astro, SvelteKit, and an
+open-ended set of future apps (React, Solid, Qwik, plain HTML, server-rendered
+templates). The question driving this document: is plain CSS the right
+universal substrate, or should the framework ship per-framework components?
+
+## Decision
+
+**Plain, class-based CSS is the canonical and only universal layer.** It is
+the single artifact every target consumes natively with zero adapter. A
+per-framework component library would make every non-chosen framework a
+second-class citizen and multiply the maintenance surface for the same button.
+
+The known gaps of a pure-CSS framework — contract visibility, a home for
+unavoidable JS, and distribution — are addressed as **thin, optional layers
+on top of the CSS, none of which require a framework commitment**:
+
+```
+@ponchia/ui
+├── css/         canonical universal layer (the framework)          [required]
+├── tokens/      design tokens as JS/JSON, for JS/canvas/tooling     [optional]
+├── classes/     typed class-name contract + recipe builders         [optional]
+├── behaviors/   vanilla, SSR-safe JS for stateful widgets           [optional]
+├── connectors/  pure SVG leader-line geometry kernel (no DOM)        [optional]
+├── annotations/ pure SVG callout geometry (builds on connectors)     [optional]
+├── glyphs/      dot-matrix glyph registry/renderers                 [optional]
+├── react/       thin React hooks over behaviors                     [optional peer]
+├── solid/       thin Solid primitives over behaviors                [optional peer]
+└── qwik/        thin Qwik hooks over behaviors (useVisibleTask$)     [optional peer]
+```
+
+### Consequences of each layer
+
+- **css/** — wrapped in a single `@layer bronto`. Any un-layered CSS in a
+  consumer wins the cascade without specificity wars or `!important`. This is
+  a deliberate behavioural change vs. unlayered v0.1.0; consumers pin a tag
+  so it ships only on the next version bump.
+- **Fonts** — `@font-face` moved out of `tokens.css` into `css/fonts.css`
+  with URLs relative to the package (`../fonts/*`), so font hosting is
+  decoupled from the token layer and resolves through bundlers or static
+  serving without an absolute `/fonts` assumption.
+- **tokens/** — `index.js` (`cssVars`) is the single source of truth for token
+  values. The four `:root` palette blocks of `css/tokens.css` are **generated**
+  from it (`scripts/gen-tokens-css.mjs`), as are the JSON artifacts (`index.json`,
+  `tokens.dtcg.json`, `resolved.json`). So the dark palette is authored once,
+  not in three places (the two CSS dark blocks are now identical by
+  construction), resolving the duplication ADR-0003 flagged. The CSS-only
+  presets (density / contrast / OLED) stay hand-authored below a marker and are
+  preserved across regeneration. `scripts/check-fresh.mjs` fails CI if
+  `css/tokens.css` drifts from the model.
+- **classes/** — `cls` is the flat registry; recipes only emit from it;
+  `scripts/check-classes.mjs` enforces a bidirectional match with the
+  stylesheet's `.ui-*` selectors. The class contract cannot silently rot.
+- **behaviors/** — vanilla, dependency-free, side-effect-free on import,
+  SSR-safe. Chosen over Web Components (SSR/hydration friction with Astro
+  islands and SvelteKit) and over per-framework packages (maintenance
+  multiplier). Revisit Web Components only if stateful widgets accumulate.
+  `index.js` is a barrel; each behavior lives in its own module
+  (`dialog.js`, `combobox.js`, …) over a shared `internal.js` of DOM helpers,
+  so the public import surface is unchanged.
+- **glyphs/** — static bitmap data and SSR-safe render helpers. The
+  256-cell DOM renderers are for display and solid inline icons; the `.ui-icon`
+  mask renderer is for dense icon-at-scale use.
+- **react/** / **solid/** / **qwik/** — optional lifecycle adapters over `behaviors/`.
+  They do not define markup, own state, or fork behavior logic; they only run
+  the vanilla initializers on mount and cleanup on unmount/dispose.
+- **`css/analytical.css` — the analytical roll-up.** This convenience file
+  `@import`s exactly **seven** analytical-figure leaves: `annotations`,
+  `legend`, `marks`, `connectors`, `spotlight`, `crosshair`, and `selection`.
+  The adjacent opt-in leaves — `sources`, `state`, `generated`, `workbench`,
+  and `command` — are report/tooling/trust surfaces that are intentionally
+  **not** part of the analytical roll-up and must be imported individually.
+  Importing `analytical.css` does not pull in any of those five.
+- **Root export (`.`) is CSS-only.** `exports["."]` resolves to the CSS
+  bundle (`dist/bronto.css`). It is a CSS side-effect import for CSS-aware
+  bundlers (`@import '@ponchia/ui'` in CSS, or a side-effect
+  `import '@ponchia/ui'` in Vite/Astro/SvelteKit). There is no runtime JS at
+  the package root — Node/runtime JS imports of `.` are not supported. All JS
+  entrypoints are explicit subpaths (`/behaviors`, `/classes`, `/tokens`,
+  `/glyphs`, `/react`, `/solid`, `/qwik`, `/skins`, `/charts`). This is a
+  permanent, intentional contract.
+
+## Repository layout
+
+The repo root mixes five kinds of directory that look alike but follow very
+different rules. Two distinctions matter most: several are **path-frozen
+published subpaths** — the directory name _is_ the public import specifier
+(`@ponchia/ui/react` resolves to `./react/`), so they cannot be moved or
+renamed — and several are **generated** and must never be hand-edited (a
+generator overwrites them and a drift gate fails CI).
+
+| Path | Kind | Edit here? | Notes |
+| --- | --- | --- | --- |
+| `css/` | source | yes | The framework. Hand-authored `@layer bronto` CSS. (`css/tokens.css` palette blocks and `css/generated.css` are generated — see below.) |
+| `tokens/index.js` | source | yes | The single source of truth for token **values** (`cssVars`). |
+| `classes/index.js`, `behaviors/`, `annotations/`, `connectors/`, `react/`, `solid/`, `qwik/`, `glyphs/`, `shiki/` | source · published-subpath (path-frozen) | yes — but **do not move** | Authored ESM shipped as-is; the dir name is the public import path. The `.d.ts` beside them are generated/drift-checked: `connectors`/`annotations`/`react`/`solid`/`qwik` are emitted from JSDoc by `tsc` (`npm run dts:emit`), `classes`/`tokens`/`glyphs` from the runtime; only `behaviors/index.d.ts` is still hand-maintained (its barrel + destructured-param shape emit poorly), guarded by `check-behaviors`. |
+| `dist/` | generated | no | Build of `css/` (`npm run dist:build`); byte-checked by `check:dist`. |
+| `tokens/index.json`, `tokens/resolved.json`, `tokens/tokens.dtcg.json`, `tokens/charts.json`, `classes/index.d.ts`, `tokens/index.d.ts`, `tokens/{skins,charts}.d.ts`, `glyphs/glyphs.d.ts`, `classes/vscode.css-custom-data.json`, `docs/reference.md` | generated | no | Committed build artifacts; regenerate with `npm run prepack`, never hand-edit. Drift-checked in `npm run check`. |
+| `fonts/` | vendored | — | The Doto webfont (woff2) + its OFL license. |
+| `scripts/` | tooling | yes | `gen-*` regenerate artifacts, `check-*` are the drift/contract gates wired into `npm run check`, plus `build-dist`, `serve`, `size-report`. |
+| `docs/` | source (mostly) | yes | Hand-authored docs + ADRs; the curated subset in `package.json` `files` ships in the tarball. `docs/reference.md` is generated. |
+| `demo/`, `test/`, `examples/` | fixtures | yes | The self-driving demo/showcase, the unit + Playwright e2e suite, and consumer example apps built against the packed tarball. |
+| `.github/`, `*.config.mjs`, `.prettierrc`, `.stylelintrc.json`, `tsconfig.json`, `.editorconfig` | config | yes | CI workflows and tool config. |
+| `package.json`, `llms.txt`, `CHANGELOG.md`, `MIGRATIONS.json`, `README.md`, `CONTRIBUTING.md`, `ROADMAP.md`, `LICENSE` | meta | yes | Manifest, the agent entrypoint, the curated changelog, the rename map, and project docs. |
+
+The **path-frozen** dirs are the cost of zero-build, path-stable publishing:
+`files` map 1:1 to published paths and the consumer's own bundler tree-shakes
+the ESM, so there is no `src/` indirection (and no JS bundler — see the
+distribution decision below). **Generated** files are regenerated from their
+source and policed by a drift gate — edit the source, run the generator, commit
+the result.
+
+## Drift control
+
+Every data mirror is backed by a check wired into `npm run check`, run by CI
+on every push/PR and again by `release.yml` before publish (see "Release
+gating" below), so a version that fails any invariant never reaches npm.
+
+| Invariant                                       | Enforced by         |
+| ----------------------------------------------- | ------------------- |
+| exports / import graph / `files` consistent     | `check-exports.mjs` |
+| pure generated mirrors fresh — `tokens.css`/`index.json`, `dtcg.json`, `resolved.json`, `classes`/`tokens` `.d.ts`, `reference.md`, vscode data — each byte-equal to its generator (registry: `scripts/lib/artifacts.mjs`) | `check-fresh.mjs` |
+| `classes` `cls` ⇄ `.ui-*` selectors             | `check-classes.mjs` |
+| `connectors`/`annotations`/`react`/`solid`/`qwik` `.d.ts` (+ maps) == fresh `tsc` emit of their JSDoc | `check-dts-emit.mjs` |
+| `behaviors/index.d.ts` ⇄ `behaviors/*` exports (the one hand-maintained leaf `.d.ts`) | `check-behaviors.mjs` |
+| legend swatch colours ⊆ `charts.js` · opt-in   | `check-legend.mjs`  |
+| color tokens tiered · no raw chromatic color in components | `check-color-policy.mjs` |
+| `css/skins.css` ⇄ `tokens/skins.js` · colorways opt-in | `check-skins.mjs` |
+| every shipped colorway accent meets its WCAG floor | `check-contrast.mjs` |
+| `dataviz.css`/`charts.json`/`charts.d.ts` ⇄ `tokens/charts.js` · CVD-distinguishable · opt-in | `check-charts.mjs` |
+| `shiki/nothing.json` valid + on rationed palette | `check-shiki.mjs`  |
+| `dist/*.css` == fresh build of `css/` + budget  | `check-dist.mjs`    |
+| published tarball == intended `files` only      | `check-pack.mjs`    |
+| published `.d.ts` compile + reject typos        | `tsc` (`check:types`) |
+| CSS style/correctness                           | Stylelint           |
+| non-CSS source style                            | Prettier (`check:format`) |
+
+`check-dist` is the most supply-chain-critical row: `dist/bronto.css` is
+the default `exports["."]` consumers actually load, so its byte-equality
+to a fresh build of `css/` is what makes the committed bundle trustworthy.
+The `check-dist` size ceiling (`BUDGET` in `build-dist.mjs`) is calibrated
+to the current bundle with deliberate headroom — it is the consumer-facing
+payload contract, raised only intentionally with a CHANGELOG note.
+`check:types` compiles the published declarations against
+`test/types.test-d.ts`, whose `@ts-expect-error`s would fail to compile
+if the generated literal `cls`/token types stopped rejecting typos —
+so the *value* of the generated `.d.ts` is itself gated, not just their
+freshness (`check-fresh`).
+
+## Release gating
+
+`release.yml` (on a pushed `v*` tag) is a five-job DAG, serialized by a
+`concurrency: release-publish` group so two tags can't race the dist-tag
+pointer:
+
+- `validate` — read-only: `npm run check` + tag↔version match. `check`
+  includes `check:release`; for a prerelease tag the base version's
+  CHANGELOG section need only exist (`## Unreleased — x.y.z` is fine) —
+  only a stable release must carry a dated heading.
+- `e2e` — Playwright (visual + axe a11y, both themes, cross-engine) in
+  the pinned `mcr.microsoft.com/playwright` container.
+- `examples` — `needs: validate`: builds the downstream example
+  apps against the **packed tarball**, mirroring CI. Catches a broken
+  published surface (exports map / missing file / unresolved subpath)
+  that `check:pack`'s file-allowlist inspection cannot — so the release
+  path runs the same consumer smoke as merge-to-main.
+- `publish-npm` — `needs: [validate, e2e, examples]`: `npm publish` with
+  provenance. Runs in the `npm-publish` **Environment** (required-reviewer
+  protection), so after the gates pass the run pauses for a manual approval
+  in the Actions UI before anything reaches npm — a guard against an
+  accidental tag push publishing. Dist-tag is derived from the tag: stable
+  (`v0.4.0`) → `latest`; SemVer prerelease (`v0.4.0-rc.1`, any hyphenated
+  identifier) → `next`, so the default `npm i @ponchia/ui` never moves onto
+  an unstable build (opt in with `@ponchia/ui@next`).
+- `release-notes` — `needs: publish-npm`: a GitHub Release for visibility
+  (transitively gated on a successful publish, hence on the gates above);
+  prerelease tags are flagged so they aren't surfaced as "Latest". The Release
+  **body is the curated `CHANGELOG.md` section** for the tag
+  (`scripts/changelog-section.mjs`), not GitHub's auto-generated PR list — one
+  source of truth, surfaced where readers look.
+
+Because the documented install path is the npm package, **the npm publish
+is a real gate**: if `validate`, `e2e`, *or* `examples` fails,
+`publish-npm` never runs, the version never reaches the registry, and
+consumers never resolve it.
+(Corollary: a flaky `e2e` blocks releases — that is deliberate; fix the
+flake, don't bypass the gate.) Permissions are least-privilege per job
+(only `release-notes` gets `contents: write`; only `publish-npm` gets
+`id-token: write` for provenance).
+
+GitHub still serves the raw tag tarball `archive/refs/tags/vX.Y.Z.tar.gz`
+for any tag, ungated — that path is legacy/fallback, deliberately *not* the
+documented install, so it is no longer the safeguard-critical surface.
+Process still applies: bump `package.json`, land on `main`, go green, tag.
+
+## Decision — distribution: npm public `@ponchia/ui`
+
+Decided 2026-05-15. The framework is consumed by a growing set of
+heterogeneous web frontends (Astro, SvelteKit, React, Solid, Qwik, vanilla),
+several deploying via third-party CI. The only option where onboarding a new
+frontend is `npm i @ponchia/ui` with zero per-consumer config is **npm
+public**, and it uniquely also closes the release-gating gap (publish *is*
+the gate). GitHub Packages was rejected: it requires auth to install even
+public packages, i.e. an `.npmrc` + token on every frontend and CI runner —
+the exact friction to avoid. The raw tag tarball is kept as an ungated
+legacy/fallback only.
+
+The npm scope `@bronto` is not ownable, so the package name is
+**`@ponchia/ui`**. Naming layers, intentionally distinct:
+
+- **npm package**: `@ponchia/ui` (registry identity).
+- **CSS cascade layer**: `@layer bronto` and `data-bronto-*` behavior
+  attributes (the design-system namespace — unchanged; renaming gains
+  nothing and risks consumer overrides).
+- **Workspace / brand**: "Bronto" (repo `Ponchia/bronto-ui`) — unchanged.
+
+This split is deliberate; the README states it so the apparent mismatch is
+explained, not surprising.
+
+### Post-publish checklist
+
+- Confirm npm `latest` points at the tagged version and the package page shows
+  provenance.
+- Run `npm pack --dry-run --json` locally or from CI logs and confirm the
+  intended file count/payload.
+- Build the packed examples matrix (vanilla, Astro, SvelteKit, React, Solid, Qwik)
+  from the tarball, not a workspace link.
+- Confirm the GitHub Release body matches the curated changelog section.
+- If a bad package is published, deprecate that exact version on npm, publish a
+  patched version, and link the deprecation note to the changelog/security
+  advisory as appropriate.