Migrating 0.4 → 0.5

0.5.0 builds out the analytical & communication identity: an opt-in suite of primitives for interfaces that explain themselves — SVG annotations, standalone legends, text/evidence marks, leader-line connectors, a guided-focus spotlight, a crosshair/readout, a selection vocabulary (rolled up in css/analytical.css), plus standalone sources/provenance, lifecycle state, AI-trust generated, workbench and a command palette.

Almost all of it is additive and opt-in — the default dist/bronto.css renders identically and needs no change. There are three breaking changes, and every one of them lives in the opt-in report / analytical layer. The machine-readable map is MIGRATIONS.json (now shipped in the package).

1. The report kit's chart key moved to the standalone Legends layer

.ui-chart__legend / .ui-chart__swatch were removed from css/report.css. The data key is now the standalone Legends layer (css/legend.css), which is richer (categorical / gradient / threshold / pattern keys, an optional interactive series toggle) and reusable outside reports.

Migration: add the legend leaf next to the report kit and rework the wrapper.

+ <link rel="stylesheet" href="@ponchia/ui/css/legend.css">

- <ul class="ui-chart__legend">
-   <li><span class="ui-chart__swatch" style="--chart-color: var(--chart-1)"></span> Research</li>
- </ul>
+ <ul class="ui-legend">
+   <li class="ui-legend__item">
+     <span class="ui-legend__swatch" style="--chart-color: var(--chart-1)"></span>
+     <span class="ui-legend__label">Research</span>
+   </li>
+ </ul>

The swatch's --chart-color / --chart-pattern inline contract is unchanged; the categorical colour is also available via .ui-legend__swatch--1..8. Full grammar: docs/legends.md. Quick rename:

rg -l 'ui-chart__legend|ui-chart__swatch' .
# s/ui-chart__swatch/ui-legend__swatch/g  + rework the <ul> wrapper as above

2. The marks rationed-accent tone `evidence` → `accent`

To match the connector/annotation tone vocabulary, the tone modifier on text marks and bracket notes was renamed:

0.4	0.5
`.ui-mark--evidence`	`.ui-mark--accent`
`.ui-bracket-note--evidence`	`.ui-bracket-note--accent`
`ui.mark({ tone: 'evidence' })`	`ui.mark({ tone: 'accent' })`
`ui.bracketNote({ tone: 'evidence' })`	`ui.bracketNote({ tone: 'accent' })`

Do not rewrite ui.annotation({ variant: 'evidence' }) or the .ui-annotation--evidence subject marker — those are a marker shape, not a tone, and are unchanged.

rg -l 'ui-mark--evidence|ui-bracket-note--evidence' .
# s/ui-mark--evidence/ui-mark--accent/g ; s/ui-bracket-note--evidence/ui-bracket-note--accent/g

3. Annotation arrowheads share the connectors geometry kernel

No API change — connectorEndArrow and the annotation arrowhead recipes keep their signatures. Only the rendered arrowhead path differs slightly now that it reuses the shared @ponchia/ui/connectors geometry kernel.

Migration: nothing to change in code. If you keep exact-path SVG snapshot tests of annotation arrowheads, re-baseline them.

What's new (all opt-in, nothing to change)

Analytical suite — @ponchia/ui/css/analytical.css rolls up annotations, legend, marks, connectors, spotlight, crosshair and selection. Each owns only its visual grammar + pure geometry (no chart engine, no state, no hit-testing).
App-tier leaves — css/sources.css (citation/provenance trust), css/state.css (lifecycle/system state), css/generated.css (AI-trust), css/workbench.css (inspector/property/selection bar), and css/command.css
- initCommand (a filter/keyboard command palette).
.ui-shortcut — a keyboard-hint chord/sequence primitive in the core layer.

Re-pin

// package.json — 0.5 is a breaking minor under the pre-1.0 policy
"@ponchia/ui": "~0.5.0"