@ponchia/ui 0.4.1 → 0.5.0

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).
 
-- 303 classes across 121 component groups
+- 474 classes across 148 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'`
 
@@ -66,6 +66,46 @@ each one matches a real selector in the stylesheet.
 | --- | --- | --- |
 | `cls.animateMatrix` | `ui-animate-matrix` | base |
 
+### `.ui-annotation`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.annotation` | `ui-annotation` | base |
+| `cls.annotationBadge` | `ui-annotation__badge` | part |
+| `cls.annotationConnector` | `ui-annotation__connector` | part |
+| `cls.annotationConnectorEnd` | `ui-annotation__connector-end` | part |
+| `cls.annotationLabel` | `ui-annotation__label` | part |
+| `cls.annotationNote` | `ui-annotation__note` | part |
+| `cls.annotationNoteLine` | `ui-annotation__note-line` | part |
+| `cls.annotationSubject` | `ui-annotation__subject` | part |
+| `cls.annotationTitle` | `ui-annotation__title` | part |
+| `cls.annotationAccent` | `ui-annotation--accent` | modifier |
+| `cls.annotationAxis` | `ui-annotation--axis` | modifier |
+| `cls.annotationBadgeVariant` | `ui-annotation--badge` | modifier |
+| `cls.annotationBand` | `ui-annotation--band` | modifier |
+| `cls.annotationBracket` | `ui-annotation--bracket` | modifier |
+| `cls.annotationCallout` | `ui-annotation--callout` | modifier |
+| `cls.annotationCircle` | `ui-annotation--circle` | modifier |
+| `cls.annotationCluster` | `ui-annotation--cluster` | modifier |
+| `cls.annotationCompare` | `ui-annotation--compare` | modifier |
+| `cls.annotationCurve` | `ui-annotation--curve` | modifier |
+| `cls.annotationDanger` | `ui-annotation--danger` | modifier |
+| `cls.annotationDraw` | `ui-annotation--draw` | modifier |
+| `cls.annotationElbow` | `ui-annotation--elbow` | modifier |
+| `cls.annotationEvidence` | `ui-annotation--evidence` | modifier |
+| `cls.annotationFocus` | `ui-annotation--focus` | modifier |
+| `cls.annotationInfo` | `ui-annotation--info` | modifier |
+| `cls.annotationLabelVariant` | `ui-annotation--label` | modifier |
+| `cls.annotationMuted` | `ui-annotation--muted` | modifier |
+| `cls.annotationPulse` | `ui-annotation--pulse` | modifier |
+| `cls.annotationRect` | `ui-annotation--rect` | modifier |
+| `cls.annotationReveal` | `ui-annotation--reveal` | modifier |
+| `cls.annotationSlope` | `ui-annotation--slope` | modifier |
+| `cls.annotationSuccess` | `ui-annotation--success` | modifier |
+| `cls.annotationThreshold` | `ui-annotation--threshold` | modifier |
+| `cls.annotationTimeline` | `ui-annotation--timeline` | modifier |
+| `cls.annotationWarning` | `ui-annotation--warning` | modifier |
+
 ### `.ui-app-content`
 
 | Registry key | Class | Kind |
@@ -172,6 +212,17 @@ each one matches a real selector in the stylesheet.
 | `cls.badgeSuccess` | `ui-badge--success` | modifier |
 | `cls.badgeWarning` | `ui-badge--warning` | modifier |
 
+### `.ui-bracket-note`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.bracketNote` | `ui-bracket-note` | base |
+| `cls.bracketNoteLabel` | `ui-bracket-note__label` | part |
+| `cls.bracketNoteAccent` | `ui-bracket-note--accent` | modifier |
+| `cls.bracketNoteDanger` | `ui-bracket-note--danger` | modifier |
+| `cls.bracketNoteInfo` | `ui-bracket-note--info` | modifier |
+| `cls.bracketNoteWarning` | `ui-bracket-note--warning` | modifier |
+
 ### `.ui-breadcrumb`
 
 | Registry key | Class | Kind |
@@ -248,9 +299,7 @@ each one matches a real selector in the stylesheet.
 | `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`
@@ -266,6 +315,13 @@ each one matches a real selector in the stylesheet.
 | `cls.chip` | `ui-chip` | base |
 | `cls.chipAccent` | `ui-chip--accent` | modifier |
 
+### `.ui-citation`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.citation` | `ui-citation` | base |
+| `cls.citationChip` | `ui-citation--chip` | modifier |
+
 ### `.ui-cluster`
 
 | Registry key | Class | Kind |
@@ -283,6 +339,35 @@ each one matches a real selector in the stylesheet.
 | `cls.comboboxList` | `ui-combobox__list` | part |
 | `cls.comboboxOption` | `ui-combobox__option` | part |
 
+### `.ui-command`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.command` | `ui-command` | base |
+| `cls.commandEmpty` | `ui-command__empty` | part |
+| `cls.commandGroup` | `ui-command__group` | part |
+| `cls.commandInput` | `ui-command__input` | part |
+| `cls.commandItem` | `ui-command__item` | part |
+| `cls.commandList` | `ui-command__list` | part |
+| `cls.commandMeta` | `ui-command__meta` | part |
+| `cls.commandShortcut` | `ui-command__shortcut` | part |
+
+### `.ui-connector`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.connector` | `ui-connector` | base |
+| `cls.connectorEnd` | `ui-connector__end` | part |
+| `cls.connectorPath` | `ui-connector__path` | part |
+| `cls.connectorAccent` | `ui-connector--accent` | modifier |
+| `cls.connectorDanger` | `ui-connector--danger` | modifier |
+| `cls.connectorDashed` | `ui-connector--dashed` | modifier |
+| `cls.connectorDraw` | `ui-connector--draw` | modifier |
+| `cls.connectorInfo` | `ui-connector--info` | modifier |
+| `cls.connectorMuted` | `ui-connector--muted` | modifier |
+| `cls.connectorSuccess` | `ui-connector--success` | modifier |
+| `cls.connectorWarning` | `ui-connector--warning` | modifier |
+
 ### `.ui-container`
 
 | Registry key | Class | Kind |
@@ -297,6 +382,17 @@ each one matches a real selector in the stylesheet.
 | --- | --- | --- |
 | `cls.cq` | `ui-cq` | base |
 
+### `.ui-crosshair`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.crosshair` | `ui-crosshair` | base |
+| `cls.crosshairBadge` | `ui-crosshair__badge` | part |
+| `cls.crosshairLine` | `ui-crosshair__line` | part |
+| `cls.crosshairLineX` | `ui-crosshair__line--x` | modifier |
+| `cls.crosshairLineY` | `ui-crosshair__line--y` | modifier |
+| `cls.crosshairMuted` | `ui-crosshair--muted` | modifier |
+
 ### `.ui-display`
 
 | Registry key | Class | Kind |
@@ -407,6 +503,13 @@ each one matches a real selector in the stylesheet.
 | --- | --- | --- |
 | `cls.file` | `ui-file` | base |
 
+### `.ui-generated`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.generated` | `ui-generated` | base |
+| `cls.generatedLabel` | `ui-generated__label` | part |
+
 ### `.ui-grid`
 
 | Registry key | Class | Kind |
@@ -447,6 +550,14 @@ each one matches a real selector in the stylesheet.
 | `cls.inputIconSlot` | `ui-input-icon__icon` | part |
 | `cls.inputIconEnd` | `ui-input-icon--end` | modifier |
 
+### `.ui-inspector`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.inspector` | `ui-inspector` | base |
+| `cls.inspectorBody` | `ui-inspector__body` | part |
+| `cls.inspectorHeader` | `ui-inspector__header` | part |
+
 ### `.ui-kbd`
 
 | Registry key | Class | Kind |
@@ -471,6 +582,39 @@ each one matches a real selector in the stylesheet.
 | --- | --- | --- |
 | `cls.label` | `ui-label` | base |
 
+### `.ui-legend`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.legend` | `ui-legend` | base |
+| `cls.legendCaption` | `ui-legend__caption` | part |
+| `cls.legendItem` | `ui-legend__item` | part |
+| `cls.legendLabel` | `ui-legend__label` | part |
+| `cls.legendSwatch` | `ui-legend__swatch` | part |
+| `cls.legendSwatch1` | `ui-legend__swatch--1` | modifier |
+| `cls.legendSwatch2` | `ui-legend__swatch--2` | modifier |
+| `cls.legendSwatch3` | `ui-legend__swatch--3` | modifier |
+| `cls.legendSwatch4` | `ui-legend__swatch--4` | modifier |
+| `cls.legendSwatch5` | `ui-legend__swatch--5` | modifier |
+| `cls.legendSwatch6` | `ui-legend__swatch--6` | modifier |
+| `cls.legendSwatch7` | `ui-legend__swatch--7` | modifier |
+| `cls.legendSwatch8` | `ui-legend__swatch--8` | modifier |
+| `cls.legendSwatchCircle` | `ui-legend__swatch--circle` | modifier |
+| `cls.legendSwatchLine` | `ui-legend__swatch--line` | modifier |
+| `cls.legendSymbol` | `ui-legend__symbol` | part |
+| `cls.legendTick` | `ui-legend__tick` | part |
+| `cls.legendTicks` | `ui-legend__ticks` | part |
+| `cls.legendTitle` | `ui-legend__title` | part |
+| `cls.legendTrack` | `ui-legend__track` | part |
+| `cls.legendValue` | `ui-legend__value` | part |
+| `cls.legendCompact` | `ui-legend--compact` | modifier |
+| `cls.legendDiverging` | `ui-legend--diverging` | modifier |
+| `cls.legendGradient` | `ui-legend--gradient` | modifier |
+| `cls.legendInteractive` | `ui-legend--interactive` | modifier |
+| `cls.legendThreshold` | `ui-legend--threshold` | modifier |
+| `cls.legendVertical` | `ui-legend--vertical` | modifier |
+| `cls.legendWithValues` | `ui-legend--with-values` | modifier |
+
 ### `.ui-lightbox`
 
 | Registry key | Class | Kind |
@@ -486,6 +630,22 @@ each one matches a real selector in the stylesheet.
 | `cls.linkArrow` | `ui-link--arrow` | modifier |
 | `cls.linkCta` | `ui-link--cta` | modifier |
 
+### `.ui-mark`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.mark` | `ui-mark` | base |
+| `cls.markAccent` | `ui-mark--accent` | modifier |
+| `cls.markBox` | `ui-mark--box` | modifier |
+| `cls.markDanger` | `ui-mark--danger` | modifier |
+| `cls.markDraw` | `ui-mark--draw` | modifier |
+| `cls.markInfo` | `ui-mark--info` | modifier |
+| `cls.markMuted` | `ui-mark--muted` | modifier |
+| `cls.markStrike` | `ui-mark--strike` | modifier |
+| `cls.markSuccess` | `ui-mark--success` | modifier |
+| `cls.markUnderline` | `ui-mark--underline` | modifier |
+| `cls.markWarning` | `ui-mark--warning` | modifier |
+
 ### `.ui-matrix`
 
 | Registry key | Class | Kind |
@@ -558,6 +718,13 @@ each one matches a real selector in the stylesheet.
 | `cls.numNeg` | `ui-num--neg` | modifier |
 | `cls.numPos` | `ui-num--pos` | modifier |
 
+### `.ui-origin-label`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.originLabel` | `ui-origin-label` | base |
+| `cls.originLabelAi` | `ui-origin-label--ai` | modifier |
+
 ### `.ui-pagehead`
 
 | Registry key | Class | Kind |
@@ -606,6 +773,14 @@ each one matches a real selector in the stylesheet.
 | `cls.progressBar` | `ui-progress__bar` | part |
 | `cls.progressIndeterminate` | `ui-progress--indeterminate` | modifier |
 
+### `.ui-property`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.property` | `ui-property` | base |
+| `cls.propertyLabel` | `ui-property__label` | part |
+| `cls.propertyValue` | `ui-property__value` | part |
+
 ### `.ui-prose`
 
 | Registry key | Class | Kind |
@@ -613,6 +788,13 @@ each one matches a real selector in the stylesheet.
 | `cls.prose` | `ui-prose` | base |
 | `cls.proseCompact` | `ui-prose--compact` | modifier |
 
+### `.ui-provenance`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.provenance` | `ui-provenance` | base |
+| `cls.provenanceItem` | `ui-provenance__item` | part |
+
 ### `.ui-quote`
 
 | Registry key | Class | Kind |
@@ -632,6 +814,19 @@ each one matches a real selector in the stylesheet.
 | --- | --- | --- |
 | `cls.ratio` | `ui-ratio` | base |
 
+### `.ui-readout`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.readout` | `ui-readout` | base |
+
+### `.ui-reasoning`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.reasoning` | `ui-reasoning` | base |
+| `cls.reasoningBody` | `ui-reasoning__body` | part |
+
 ### `.ui-report`
 
 | Registry key | Class | Kind |
@@ -695,12 +890,36 @@ each one matches a real selector in the stylesheet.
 | `cls.segmented` | `ui-segmented` | base |
 | `cls.segmentedOption` | `ui-segmented__option` | part |
 
+### `.ui-sel`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.sel` | `ui-sel` | base |
+| `cls.selMaybe` | `ui-sel--maybe` | modifier |
+| `cls.selOff` | `ui-sel--off` | modifier |
+| `cls.selOn` | `ui-sel--on` | modifier |
+
 ### `.ui-select`
 
 | Registry key | Class | Kind |
 | --- | --- | --- |
 | `cls.select` | `ui-select` | base |
 
+### `.ui-selectionbar`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.selectionbar` | `ui-selectionbar` | base |
+| `cls.selectionbarActions` | `ui-selectionbar__actions` | part |
+| `cls.selectionbarCount` | `ui-selectionbar__count` | part |
+
+### `.ui-shortcut`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.shortcut` | `ui-shortcut` | base |
+| `cls.shortcutSep` | `ui-shortcut__sep` | part |
+
 ### `.ui-sidebar`
 
 | Registry key | Class | Kind |
@@ -748,12 +967,49 @@ each one matches a real selector in the stylesheet.
 | --- | --- | --- |
 | `cls.skiplink` | `ui-skiplink` | base |
 
+### `.ui-source-card`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.sourceCard` | `ui-source-card` | base |
+| `cls.sourceCardActions` | `ui-source-card__actions` | part |
+| `cls.sourceCardExcerpt` | `ui-source-card__excerpt` | part |
+| `cls.sourceCardOrigin` | `ui-source-card__origin` | part |
+| `cls.sourceCardTime` | `ui-source-card__time` | part |
+| `cls.sourceCardTitle` | `ui-source-card__title` | part |
+
+### `.ui-source-list`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.sourceList` | `ui-source-list` | base |
+| `cls.sourceListItem` | `ui-source-list__item` | part |
+
 ### `.ui-spinner`
 
 | Registry key | Class | Kind |
 | --- | --- | --- |
 | `cls.spinner` | `ui-spinner` | base |
 
+### `.ui-spotlight`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.spotlight` | `ui-spotlight` | base |
+| `cls.spotlightHole` | `ui-spotlight__hole` | part |
+| `cls.spotlightRing` | `ui-spotlight--ring` | modifier |
+
+### `.ui-src`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.srcConflict` | `ui-src--conflict` | modifier |
+| `cls.srcGenerated` | `ui-src--generated` | modifier |
+| `cls.srcReviewed` | `ui-src--reviewed` | modifier |
+| `cls.srcStale` | `ui-src--stale` | modifier |
+| `cls.srcUnverified` | `ui-src--unverified` | modifier |
+| `cls.srcVerified` | `ui-src--verified` | modifier |
+
 ### `.ui-stack`
 
 | Registry key | Class | Kind |
@@ -776,6 +1032,25 @@ each one matches a real selector in the stylesheet.
 | `cls.statLabel` | `ui-stat__label` | part |
 | `cls.statValue` | `ui-stat__value` | part |
 
+### `.ui-state`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.state` | `ui-state` | base |
+| `cls.stateDetail` | `ui-state__detail` | part |
+| `cls.stateLabel` | `ui-state__label` | part |
+| `cls.stateBusy` | `ui-state--busy` | modifier |
+| `cls.stateConflict` | `ui-state--conflict` | modifier |
+| `cls.stateError` | `ui-state--error` | modifier |
+| `cls.stateLocked` | `ui-state--locked` | modifier |
+| `cls.stateNeedsReview` | `ui-state--needs-review` | modifier |
+| `cls.stateOffline` | `ui-state--offline` | modifier |
+| `cls.stateQueued` | `ui-state--queued` | modifier |
+| `cls.stateReviewed` | `ui-state--reviewed` | modifier |
+| `cls.stateSaved` | `ui-state--saved` | modifier |
+| `cls.stateSaving` | `ui-state--saving` | modifier |
+| `cls.stateStale` | `ui-state--stale` | modifier |
+
 ### `.ui-statgrid`
 
 | Registry key | Class | Kind |
@@ -816,6 +1091,12 @@ each one matches a real selector in the stylesheet.
 | --- | --- | --- |
 | `cls.switcher` | `ui-switcher` | base |
 
+### `.ui-syncbar`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.syncbar` | `ui-syncbar` | base |
+
 ### `.ui-tab`
 
 | Registry key | Class | Kind |
@@ -908,6 +1189,21 @@ each one matches a real selector in the stylesheet.
 | `cls.toastStack` | `ui-toast-stack` | base |
 | `cls.toastStackAssertive` | `ui-toast-stack--assertive` | modifier |
 
+### `.ui-tool-call`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.toolCall` | `ui-tool-call` | base |
+| `cls.toolCallBody` | `ui-tool-call__body` | part |
+| `cls.toolCallName` | `ui-tool-call__name` | part |
+| `cls.toolCallStatus` | `ui-tool-call__status` | part |
+
+### `.ui-tool-log`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.toolLog` | `ui-tool-log` | base |
+
 ### `.ui-tooltip`
 
 | Registry key | Class | Kind |
@@ -915,6 +1211,16 @@ each one matches a real selector in the stylesheet.
 | `cls.tooltip` | `ui-tooltip` | base |
 | `cls.tooltipBubble` | `ui-tooltip__bubble` | part |
 
+### `.ui-tour-note`
+
+| Registry key | Class | Kind |
+| --- | --- | --- |
+| `cls.tourNote` | `ui-tour-note` | base |
+| `cls.tourNoteActions` | `ui-tour-note__actions` | part |
+| `cls.tourNoteBody` | `ui-tour-note__body` | part |
+| `cls.tourNoteStep` | `ui-tour-note__step` | part |
+| `cls.tourNoteTitle` | `ui-tour-note__title` | part |
+
 ### `.ui-visually-hidden`
 
 | Registry key | Class | Kind |

package/docs/reporting.md

@@ -1,8 +1,8 @@
 # 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.
+runtime. Load the normal bundle, then opt in to the report layer, chart palette,
+and annotation layer only when the report needs them.
 
 In a bundled app, package specifiers are fine because Vite or another bundler
 rewrites them:
@@ -11,6 +11,8 @@ rewrites them:
 @import '@ponchia/ui';
 @import '@ponchia/ui/css/report.css';
 @import '@ponchia/ui/css/dataviz.css';
+@import '@ponchia/ui/css/annotations.css';
+@import '@ponchia/ui/css/legend.css';
 ```
 
 For standalone browser HTML, use real stylesheet URLs. Package specifiers like
@@ -20,11 +22,14 @@ For standalone browser HTML, use real stylesheet URLs. Package specifiers like
 <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" />
+<link rel="stylesheet" href="./node_modules/@ponchia/ui/dist/css/annotations.css" />
+<link rel="stylesheet" href="./node_modules/@ponchia/ui/dist/css/legend.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.
+`dist/bronto.css`, `dist/css/report.css`, `dist/css/dataviz.css`,
+`dist/css/annotations.css`, `dist/css/legend.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,
@@ -128,31 +133,33 @@ sanitize that content before rendering it and do not initialize
 
 ## 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.
+The report layer supplies chart containers and a small static bar pattern, not a
+chart engine. The data key is the standalone, portable `.ui-legend`
+(`@ponchia/ui/css/legend.css`) — see [legends.md](./legends.md). 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>
+  <ul class="ui-legend" aria-label="Series">
+    <li class="ui-legend__item">
       <span
-        class="ui-chart__swatch"
+        class="ui-legend__swatch"
         style="--chart-color: var(--chart-1); --chart-pattern: var(--chart-pattern-1)"
         aria-hidden="true"
       ></span>
-      Research
+      <span class="ui-legend__label">Research</span>
     </li>
-    <li>
+    <li class="ui-legend__item">
       <span
-        class="ui-chart__swatch"
+        class="ui-legend__swatch"
         style="--chart-color: var(--chart-2); --chart-pattern: var(--chart-pattern-2)"
         aria-hidden="true"
       ></span>
-      Delivery
+      <span class="ui-legend__label">Delivery</span>
     </li>
   </ul>
   <div class="ui-chart__plot" aria-hidden="true">
@@ -192,6 +199,34 @@ 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.
 
+## Annotation recipe
+
+When a report chart needs an explicit callout, import
+`@ponchia/ui/css/annotations.css` and layer SVG annotations inside the same
+`ui-report__figure`. Keep the subject/connector/note text visible in the SVG or
+represented by the figure caption/fallback data.
+
+```html
+<svg viewBox="0 0 360 160" role="img" aria-labelledby="annotated-title annotated-desc">
+  <title id="annotated-title">Weekly focus chart with peak callout</title>
+  <desc id="annotated-desc">The annotation marks the research peak.</desc>
+  <g class="ui-annotation ui-annotation--circle ui-annotation--accent" transform="translate(210, 58)">
+    <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.424L84,-40" />
+    <g class="ui-annotation__note" transform="translate(84, -40)">
+      <path class="ui-annotation__note-line" d="M0,0H92" />
+      <text class="ui-annotation__title" y="-8">Peak</text>
+      <text class="ui-annotation__label" y="12">18 research hours</text>
+    </g>
+  </g>
+</svg>
+```
+
+For generated SVG, use `@ponchia/ui/annotations` to compute connector and
+subject path strings. Full annotation recipes and the complete variant list are
+in `docs/annotations.md`; the shipped `demo/annotations.html` page is the
+visual specimen.
+
 ## Timeline recipe
 
 Incident reviews and research logs should use the existing timeline primitive

package/docs/selection.md

@@ -0,0 +1,40 @@
+# Selection states
+
+`@ponchia/ui/css/selection.css` is a tiny, **cross-cutting selection-emphasis
+vocabulary** — the carve-out from "brush/lasso". Bronto does **not** do region
+selection or hit-testing (that needs your scales and geometry). It ships only
+the *states* an item can be in once your code has decided what's selected, so
+the same emphasis works on a chart mark, a table row, a list item, or a map
+region.
+
+```css
+@import '@ponchia/ui';
+@import '@ponchia/ui/css/selection.css';
+```
+
+| Class | State |
+| --- | --- |
+| `ui-sel` | Base — opt the element into the emphasis transitions. |
+| `ui-sel--on` | In the selection (accent outline). |
+| `ui-sel--off` | Excluded / filtered out (dimmed). |
+| `ui-sel--maybe` | A live-brush candidate (dashed outline). |
+
+```html
+<rect class="ui-sel ui-sel--on" … />
+<tr class="ui-sel ui-sel--off">…</tr>
+```
+
+```js
+import { ui } from '@ponchia/ui/classes';
+el.className = ui.sel({ state: inBrush ? 'maybe' : selected ? 'on' : 'off' });
+```
+
+Your code adds/removes these classes from its own brush, filter, or selection
+logic — Bronto only styles them. `--off` uses `opacity` (which survives
+forced-colors), and `--on` falls back to the system `Highlight` color in
+forced-colors so the selection stays visible.
+
+> **Why no brush behavior?** A rectangular brush or lasso must translate a
+> dragged region into a data domain (or test points against a polygon), which
+> requires owning the chart's scales/geometry — across Bronto's line. Bring your
+> own selection logic; use these classes to render the result.