@adia-ai/web-components 0.5.14 → 0.5.16

package/CHANGELOG.md

@@ -11,6 +11,240 @@ runtime ships in the sibling `@adia-ai/a2ui-runtime` package
 
 _No pending changes._
 
+## [0.5.16] - 2026-05-16
+
+### v0.5.16 §331 — `<swatch-ui>` chrome-slot wrapper-span deep-walk (FB-39; P1)
+
+Closes FB-39. P1 lifecycle gap that FB-38's "C1.3 unblocked" close-out missed: §326 (v0.5.15) fixed the late-direct-append case but NOT the template-render wrapper-span case. AdiaUI's `html\`\`` template engine wraps each interpolated child fragment in a `<span style="display: contents">` (per `core/template.js:212` `wrap()`). When consumer writes `html\`<swatch-ui>${badgeFrag}</swatch-ui>\``, the `<span slot="chrome">` ends up nested INSIDE the wrapper, not as a direct child. `#stamp()`'s `Array.from(this.children).filter(n => n.getAttribute?.('slot') === 'chrome')` returned `[]`; `innerHTML = ''` wiped the wrapper spans + chrome content; `#absorbChromeSlot()` ran on destroyed DOM.
+
+Blocked Tokens Studio's C1.3 dogfood migration (chrome elements silently destroyed) + >95% of AdiaUI consumers using `html\`\`` templates.
+
+#### Fixed — `components/swatch/class.js` (dual-site deep-walk)
+
+- `#stamp()`'s chrome extraction extends from direct-children-only to also walk `querySelectorAll('[slot="chrome"]')` on non-chrome wrapper-span children. Catches both static-HTML (direct child) AND template-render (nested in wrapper) paths.
+- `#absorbChromeSlot()` gains a parallel deep-walk for wrapper-spanned chrome children that arrive AFTER `#stamp()` (parent template re-render path). Hoists nested chrome out of any non-internal wrapper into the canonical sibling-of-tile slot via `this.insertBefore(child, this.#badgeEl)`.
+- Wrapper spans stay in place post-hoist (`display: contents` makes them invisible to CSS layout; removing them risks interfering with the parent template engine's diff tracking via the `PART` symbol).
+
+#### Added — `components/swatch/swatch.test.js` (6 → 9 cases)
+
+3 NEW vitest cases under "FB-39 / §331":
+- `hoists chrome child from inside wrapper span at #stamp() time (template-interpolation path)` — single-wrapper-single-chrome case.
+- `handles MULTIPLE chrome children nested in separate wrapper spans` — multi-`${...}` template interpolation; each fragment lands in its own wrapper.
+- `hoists chrome from late-arriving wrapper span (post-stamp template re-render)` — parent re-renders + appends a new wrapper-span carrying chrome after `#stamp()` already ran.
+
+Total `swatch.test.js`: 9/9 passing (4 §325 + 2 §326 + 3 §331).
+
+#### Migration
+
+Consumers using `<swatch-ui>` with chrome-slot composition via `html\`\`` templates (`<swatch-ui>${badge}${dot}</swatch-ui>`) now get chrome children placed at canonical position post-§331. The consumer-side workaround (skip chrome composition or use bare `<swatch-ui>` without chrome) can be retired. No consumer code changes required — the §331 fix is invisible to consumers writing canonical templates.
+
+### v0.5.x (Unreleased) §330 — `slider-ui` "Next" design + `segmented-ui` initial-render fix
+
+**`slider-ui`** — full visual redesign to iOS/macOS-style pill slider. Pill-shaped track (`var(--a-toggle-size)` = 16/20/24px for sm/md/lg), primary-color progressive fill (`--a-primary-bg`), white chrome thumb (`--a-chrome-light`) with 2:1 width:height ratio and 2px internal padding on all sides. Mathematical geometry documented inline in CSS: `fill_width(p) = t + p·(W−t)`, `thumb_center(p) = t/2 + p·(W−t)`; fill starts at thumb-width (p=0) and grows incrementally to full track width (p=1). Two-layer thumb architecture: transparent full-height container provides grab area; `::before` renders the inward-padded white pill. `class.js` `#valueFromX()` maps full track width to [min,max]; `#valueFromX()` simplified back to direct rect ratio. `data-dragging` CSS transition lock kills the `left` transition during pointer moves for instant visual feedback. `slider.examples.html` gains Sizes section (lg/md/sm/14px/12px) + updated CSS token table.
+
+**`segmented-ui`** — initial rendering race fix. Added `ResizeObserver` on self + `document.fonts.ready` promise in `connected()`; both call `#updateIndicator()` when layout stabilizes so the animated pill positions correctly after font load or resize. Previously the indicator computed once at mount and stayed misaligned — only corrected on next user interaction.
+
+Files: `slider.css`, `slider.class.js`, `slider.examples.html`, `slider.yaml`, `segmented.class.js`.
+
+### Added
+- §333 `<color-input>` gains canonical demo-shell loader pair to restore catalog symmetry with the other 92 primitives. NEW `color-input.html` (52-line shell pattern matching `color-picker.html`: tokens base + composed primitive CSS + composed primitive JS per ADR-0027 + `fetch('./color-input.examples.html')`) + NEW `color-input.examples.html` (7 sections: default · initial values · format hex vs oklch · popover placement · §313 generation constraints `max-chroma`/`max-l`/`min-l`/`hue-drift-max`/`base-hue` · disabled · inside a form). Closes gemini-review refactor-backlog P3-1.
+- §332 `<swiper-ui>` gains `chrome="toolbar"` layout mode with companion `label` + `counter` props. Default chrome (overlay paddles + centered dots below) is unchanged. Toolbar chrome stamps a header row (label on the left, paddles on the right) above the track and a footer row (counter on the left, dots on the right) below — supports gallery-style compositions where consumers want the chrome out of the slide area. `#stampToolbarChrome()` builds the head + foot rows; `#updateCounter()` writes "N / M" (page-based, snap-aware) into `[data-swiper-counter]` on every scroll. New examples at `/site/components/swiper` § chrome (photo gallery / featured products / autoplay testimonials). Counter is page-based so it tracks the dot count correctly for multi-column + center-snap.
+- §329 `<code-ui>` gains a `<template>`-child authoring path — wrap the source in `<template>…</template>` and write literal `<` / `>` without entity-escaping. `#stampBlock` reads `template.innerHTML`, dedents the wrapper column via a new static `#dedent()` helper, and feeds the result to CodeMirror. The HTML parser treats `<template>` content as inert (it lives in a `DocumentFragment`, not rendered), so embedded `<nav-ui>` / `<button-ui>` / etc. don't get upgraded inside the template. Three authoring paths now in priority order: (1) `[text]` attribute, (2) `<template>` child, (3) escaped textContent (back-compat — existing examples unchanged). Demo at `/site/components/code` § "escape-free authoring via &lt;template&gt;"; dogfooded on `patterns/app-nav` structure example. (Carry-forward from worktree §318.)
+
+### Fixed
+- §332 `<swiper-ui>` — comprehensive consumer-feedback hardening pass (9 distinct fixes consolidated). (a) **Click-and-drag preempted by native HTML5 image-drag**: `<img>` inside slide cards fired `dragstart` before our 5px pointermove threshold was reached, suspending pointer events. Fix: `dragstart` listener gated on `this.#drag !== null` (set by `#onPointerDown`) so genuine drag-out of intentionally draggable slide content stays available. (b) **Pagination dots ignored `--swiper-columns`**: stamping one dot per slide regardless of `slides-per-view`. New `#getPageCount()` returns `max(1, slides − cols + 1)` for start/end snap (reads `--swiper-columns` via `getComputedStyle(track)`); `ResizeObserver` on the host re-stamps when container queries shift the cv across breakpoints. `next/prev/play` cap at last page; dot labels read "Page N" (was "Slide N", misleading once dot-index ≠ slide-index). (c) **CSS `container-type` on the wrong element** — `container-type: inline-size` was on `[data-swiper-track]` but `@container` rules targeted `:scope` (the host = track's PARENT, not a descendant). Container queries match descendants of the container, so the rules fell through to whatever further-up ancestor had a container set (the docs shell) and incorrectly stamped `cols=2-3` on every swiper. Moved `container-type: inline-size; container-name: swiper;` to host; `@container swiper (...)` rules now target `:scope > [data-swiper-track]` (a real descendant). JS `#getColumns()` reads from the track via `getComputedStyle` so both `[slides-per-view]` (cascades from host) and `@container` (writes on track) converge. (d) **Snap-aware active tracking** — IntersectionObserver "leftmost intersecting" couldn't distinguish the last two snap positions for center/end snap (both kept the last two slides >50% visible). Replaced with `scroll` listener + `#computeActiveIndex()` that walks every slide, computes its snap target (`left` / `left + width/2 − trackWidth/2` / `left + width − trackWidth` per snap mode), clamps to `[0, maxScroll]`, and picks the closest target to `scrollLeft`. `#pageToSlideIndex` / `#slideToPageIndex` map between page and slide indices (identity for start/center; end-snap shifts by `cols − 1`); snap-aware `goTo()` scrolls to the computed target so dot clicks land without a "scroll to left edge, then scroll-snap re-correct" jank step. `#getPageCount()` returns `slides.length` for `snap="center"` (each slide is its own page; 4-slides-@-cols=2 now stamps 4 dots, not 3). (e) **Loop / autoplay demos didn't visibly demonstrate looping** — at responsive widths (≥960px → cols=3) the 3-slide demos had `pageCount=1`, paddles produced no visible effect. Pinned demos to `slides-per-view="1"`; added a new combined "loop + autoplay" example. (f) **`gap` only accepted token indices despite docs claiming "any CSS length"**: `render()` blindly wrapped `gap` in `var(--a-space-${gap})`. For `gap="1rem"` that became `var(--a-space-1rem)` (undefined token) → property invalidated → CSS gap fell back to 0; three demo variants (`gap=0/1rem/2rem`) all rendered identically. Fix: numeric-only strings resolve to space tokens, anything else used as a raw CSS length. (g) **Dot CSS lost in toolbar chrome**: `:scope > [data-swiper-dots] > button` (direct-child combinator) stopped matching when dots moved inside `[data-swiper-foot]`; buttons fell back to browser defaults (wide gray bars). Relaxed all five dot rules to `:scope [data-swiper-dots]` (descendant combinator). (h) **Active dot rendered much larger than inactive** — `background: <color>` shorthand in `:hover` and `[aria-current="true"]` rules silently RESET `background-clip` back to its initial `border-box`, so the colored area filled the full 1rem outer hitbox and `border-radius: 100rem` rounded that into a ~16px circle (vs the 6px content-box-clipped circle for inactive). Fix: longhand `background-color: <color>` so `background-clip: content-box` from the base rule is preserved. Active dot now has a deliberate +4px (`--a-space-1`) size delta via NEW `--swiper-dot-size-active` token; padding back-computed so the 1rem hitbox stays invariant. Focus ring moved from outer `var(--a-focus-ring)` to inset 2px shadow so focus doesn't change footprint either. **Pitfall worth knowing for future CSS work: `background: <color>` shorthand resets `background-clip`/`background-origin`/`background-position`/etc. to initial — use `background-color: <color>` to preserve them.**
+- §327 P2 correctness — `<code-ui language="…">` (every `/site/patterns/*` page) rendered as flow-wrapped plain text with chrome header below the content + no syntax highlighting. Root cause: the `textContent` key in `static properties` of `code/class.js`, `button/class.js`, `tag/class.js`, `badge/class.js` made `UIElement.installProps()` shadow the native `HTMLElement.prototype.textContent` setter. `this.textContent = ''` in `code-ui`'s `#stampBlock` became a signal-write no-op — original authored HTML-escaped source stayed in the element above the stamped chrome, and CodeMirror mounted with an empty doc (1 cm-line, 19.5px tall editor below leftover authored text). Same hazard on `<tag-ui>` produced visible empty pills across every `/site/traits/*` page's API table (the `chip()` helper in `traits/_api-table.js` and 3 other call sites all do `t.textContent = text` after `createElement('tag-ui')`). Fix: removed the `textContent` entry from each of the 4 class.js files. Yaml + `.d.ts` entries kept (renderer routes via `setAttribute('text', …)` for non-text-bearing tags; doesn't depend on JS prop declarations). New drift class #7 (native-DOM-accessor collision). **Carry-forward note:** initially staged as §316 on a worktree branch (2026-05-15) before v0.5.14 cut; §316-§318 were claimed by parallel peer work that shipped via v0.5.15. Renumbered to §327 on re-apply to main against v0.5.15 HEAD (2026-05-16).
+
+### Docs
+- §328 source-side polish: re-flowed 6 one-line `<code-ui>` blocks across `stat`/`pagination`/`rating`/`count-up`/`theme-panel`/`theming` USAGE sections — multi-attribute single tags now author each attribute on its own line for readability + consistency with how the rest of the corpus is authored. (Carry-forward from worktree §317.)
+
+## [0.5.15] - 2026-05-16
+
+> **Scope note:** §325 + §326 were originally planned as a separate v0.5.16 cycle (see retired `docs/plans/0.5.16-release-plan.md`); absorbed into v0.5.15 since both landed within the same release window (same-day commits prior to bump). The peer's v0.5.16 plan-doc explicitly anticipated this absorption option ("Hermes's call per `/lockstep-release`"). v0.5.16 plan-doc marked SHIPPED-IN-V0.5.15.
+
+### v0.5.15 §326 — `<swatch-ui>` `[slot="chrome"]` lost in template contexts (FB-37; P1)
+
+Closes FB-37. Pre-§326, `<swatch-ui>` consumed via any `html\`\`` template engine (or any engine that batches child appends separately from element creation) lost its `[slot="chrome"]` children entirely. Root cause: `#stamp()` is gated by a `#stamped` once-only guard + scans `this.children` for chrome slots at `connectedCallback` time. Template engines create the host via `createElement` + connect it FIRST (children empty), then batch-append children AFTER. `#stamp()`'s chrome scan returns `[]`; the `#stamped` guard prevents re-runs; chrome children landed at the END of host's children (after `data-copy`) instead of the canonical sibling-of-tile position. Blocked Tokens Studio's C1.3 dogfood migration (9 failing Playwright tests root-caused to this) — and >95% of AdiaUI consumers using `html\`\`` templates.
+
+#### Fixed — `components/swatch/class.js`
+
+- NEW `#absorbChromeSlot()` helper. Idempotent. Walks `this.children`; for any child with `slot="chrome"` that's not one of the internal stamped elements + not in the canonical position, calls `this.insertBefore(child, this.#badgeEl)` to move it to the slot between `#tileEl` + `#badgeEl`.
+- `#syncCore()` calls `#absorbChromeSlot()` at the top of every render pass. Late-arriving chrome children (template-render path) get picked up on the next reactive cycle; pre-positioned chrome children (static-HTML path) are no-op-moves.
+- `#stamp()`'s once-only eager scan stays intact for the static-HTML path; `#absorbChromeSlot()` is the safety net for late-append.
+
+#### Added — `components/swatch/swatch.test.js`
+
+- 2 NEW vitest cases under "FB-37 / §326":
+  - `absorbs chrome child appended AFTER connectedCallback (template-render path)` — mimics the bug's exact timing (create + connect with empty children → late append → property mutation triggers render → fix picks up the chrome child).
+  - `still handles chrome child appended BEFORE connect (static-HTML path)` — regression check that §314's original behavior still works.
+- Total suite: 6 cases (4 from §325 + 2 from §326).
+
+#### Migration
+
+Consumers using `<swatch-ui>` via `html\`\`` template engines (lit-html, AdiaUI's own `html\`\``, Preact, Vue, etc.) get the §314 chrome-slot feature working as documented in v0.5.13's `swatch.yaml slots:` block. No consumer-side changes required — the §326 fix is invisible to consumers writing canonical templates.
+
+### v0.5.15 §325 — `<swatch-ui>` default-slot wiped by label-attr (FB-36)
+
+Closes FB-36 + FB-36-followup. Pre-§325, `<swatch-ui label="500"><span>tip</span></swatch-ui>` written as indented multi-line HTML dropped the default-slot child entirely; only `label="500"` rendered. Root cause: `#stamp()`'s `Array.from(this.childNodes).filter(...)` captured pure-whitespace text nodes from the indentation; those landed in `#labelEl.firstChild`; `#syncCore()`'s "stale text-node" branch (designed for runtime `el.label = 'X'` mutations on attr-only swatches) then matched the whitespace + did `textContent = this.label`, wiping both the whitespace AND the consumer's `<span>`.
+
+Pre-§325 the yaml spec ("Use the default slot for richer content" — `swatch.yaml:40`) and the implementation contradicted each other; post-§325 they agree.
+
+#### Fixed — `components/swatch/class.js`
+
+- `#stamp()`'s `slotted` filter chain gains `&& !(n.nodeType === 3 && !n.textContent.trim())` — strips pure-whitespace text nodes from the capture. `#labelEl.firstChild` now becomes the consumer's element (or non-whitespace text), so `#syncCore`'s stale-text-node branch fires only for genuinely attr-driven cases.
+
+#### Added — `components/swatch/swatch.test.js`
+
+- NEW 4-case vitest suite covering FB-36's 3 input axes (default-slot present/absent × label-attr present/absent × runtime mutation). Locks the §325 fix structurally — future regressions of any of the 4 paths fail CI.
+
+#### Migration
+
+`<swatch-ui label="500"><span>tip</span></swatch-ui>` now behaves per yaml spec: default-slot wins, label-attr drops. Consumers using the workaround `.label=` property binding (per FB-36-followup) to bypass the bug can switch back to the canonical `[label]` attribute form post-upgrade.
+
+### v0.5.15 §324 — Yaml `enum_descriptions:` codegen extension (v0.6.0 FB-23 §3 retire carry-forward, PATCH-eligible)
+
+Closes the v0.6.0 carry-forward "Codegen yaml `enum:` per-member descriptions (FB-23 §3 retire)" from the RESPONSE-29 carry-forwards table. v0.5.15 ships the additive codegen surface on PATCH cadence; v0.6.0 no longer needs to carry this item.
+
+**The surface change:** `scripts/schemas/component.yaml.schema.json` `Prop` definition gains an optional `enum_descriptions:` object field — when present alongside `enum:`, dts-codegen emits an exported type alias (e.g. `UITextVariant`) above the class declaration with per-variant JSDoc carrying each description. IDE hover surfaces the disambiguation at authoring time without requiring hand-authored .d.ts.
+
+#### Added
+
+- `scripts/schemas/component.yaml.schema.json` — NEW optional `enum_descriptions: { type: object, additionalProperties: { type: string } }` field per prop. Backward-compatible: existing yamls without the field continue to emit inline enum unions.
+- `scripts/build/components.mjs` — forwards `enum_descriptions:` through `compileProp()` into the a2ui.json sidecar.
+- `scripts/build/dts-codegen.mjs` — `emitEnumTypeAlias()` helper detects props with both `enum:` and `enum_descriptions:`; emits a typed union alias `${className}${PascalCase(propName)}` with per-variant JSDoc; class property references the alias instead of inlining the union.
+
+#### Changed — `components/text/text.yaml`
+
+- `variant:` prop gains 12-entry `enum_descriptions:` block (one description per variant). Prop `description:` block also gains the FB-23 §2 ARIA-role disclaimer that previously lived in the hand-authored .d.ts.
+
+#### Changed — `scripts/build/dts-codegen.mjs` `HAND_AUTHORED_DTS`
+
+- `text` removed from skip-list. `text.d.ts` now codegen-driven; per-variant JSDoc surfaces via the new `enum_descriptions:` field. Net effect: 1 of 3 remaining `HAND_AUTHORED_DTS` entries closed (`toast` + `feed` remain — both carry runtime API the yaml shape can't express).
+
+#### Regenerated — `components/text/text.d.ts`
+
+- Replaces hand-authored .d.ts with codegen output. `UITextVariant` type alias preserved as exported type; per-variant JSDoc preserved verbatim. Net result: zero consumer-facing diff in the .d.ts surface; codegen takes over maintenance.
+
+### v0.5.15 §322 — NEW audit slot 32: `check-dead-constants.mjs`
+
+Graduates the FB-35 bug class (declared-but-unread module-level consts) to a CI gate. Walks every `.js` file under `packages/<pkg>/`; extracts SCREAMING_SNAKE_CASE / PascalCase `const NAME = ...;` declarations at module level; flags zero-reference cases. Skips `export const NAME` (consumed externally) + test/spec/examples/config files.
+
+First sweep surfaced + removed 2 real dead constants:
+- `packages/a2ui/validator/validator.js:38` — `WIRING_WEIGHTS` (vestigial from planned weighted-scoring system; safe deletion).
+- `packages/llm/adapters/openai.js:10` — `DEFAULT_MAX_TOKENS = 4096` (replaced by explicit `opts.max_tokens` plumbing).
+
+### v0.5.15 §323 — NEW audit slot 33: `check-hover-guard-discipline.mjs`
+
+Graduates the `analyze-css` bare-`:hover` discipline class to a CI gate. Detects `:hover` rules on host primitives + interactive slots/roles that lack a `:not([disabled])` guard AND set visual properties (background/color/border/box-shadow/etc.). Skips cursor-only / outline-style-only rule bodies.
+
+First sweep surfaced 19 findings across 11 components — all baselined in EXPECTED_DRIFT for cycle-by-cycle close:
+- **Real drift** (rely on `pointer-events: none` for click-suppression but hover styles still apply): action-list (4×), menu (1×), nav-item (2×), nav-group (1×).
+- **Slotted-trigger drift** (mitigated via parent guard rules; cosmetic-OK but worth tightening): select (5×), calendar-picker (1×), range (2×), tag (1×).
+- **Decorative-pop hover** (intentional): avatar (1×). Long-term whitelist candidate.
+- **@scope-Safari-17.x-workaround**: action-list (3 of 4) + nav-item (2) + rating (1) — guard can't live inside @scope; lift alongside the hover rule.
+
+#### Removed — dead module-level constants
+
+- `packages/a2ui/validator/validator.js` — `WIRING_WEIGHTS` constant (zero refs).
+- `packages/llm/adapters/openai.js` — `DEFAULT_MAX_TOKENS` constant (zero refs).
+
+### v0.5.15 §319 — NEW audit slot 29: `check-exports-map-resolves.mjs`
+
+Graduates the FB-32 bug class to a CI gate. Closes the recurring drift where a package.json `exports` map entry resolves (via wildcard expansion or static path) to a file that doesn't exist on disk — consumer TS imports fail with `TS2882` even though Vite/Node can fall through `node_modules/<pkg>/<path>` directly.
+
+#### Added — `scripts/release/check-exports-map-resolves.mjs`
+
+- ~270 LOC. Walks every `packages/<pkg>/package.json` `exports` map. For each STATIC entry, verifies the referenced file path exists. For each WILDCARD entry matching the FB-32 shape (`./X/*` key + `./X/*/*.<ext>` value), enumerates filesystem candidates that would match the wildcard + verifies each resolved path exists.
+- Skips wildcard expansions where an explicit non-wildcard entry overrides the resolution (Node exports-map resolution algorithm precedence).
+- Skips CSS-only / no-JS components (header / footer / section / aside / various web-modules shells) — these intentionally ship no `.js`.
+- Result: 9 packages / 52 static + 39 wildcard exports entries / 59 resolutions verified / 0 unresolved.
+
+### v0.5.15 §320 — NEW audit slot 30: `check-composes-passthrough.mjs`
+
+Graduates the FB-33 bug class to a CI gate. Closes the recurring drift where a form-bearing primitive that programmatically creates ANOTHER form-bearing primitive in its lifecycle (light-DOM composition) doesn't expose / forward the composed primitive's documented prop + event-detail surface.
+
+#### Added — `scripts/release/check-composes-passthrough.mjs`
+
+- ~270 LOC. Static `COMPOSITION_PAIRS` list declares the required pass-through surface per pair. For each pair: verifies composing primitive's yaml `composes:` block lists the composed primitive; verifies yaml `props:` block exposes every required prop; verifies yaml `events:` block declares each event with required detail keys.
+- Initial pair: `color-input → color-picker` (8 props + 12 event-detail keys across `change` + `input`).
+- Adding a new pair: any new primitive that programmatically wraps a form-bearing primitive declares its contract in `COMPOSITION_PAIRS`; the audit fires at PR time.
+- Companion to slot 23 (`check-form-bearing-dts.mjs`): that audit checks .d.ts type-coverage; this audit checks yaml-declared shape.
+
+### v0.5.15 §321 — NEW audit slot 31: `check-token-name-canonical-shape.mjs`
+
+Graduates the stepper / list state-first naming drift class to a CI gate. Closes the recurring drift where a component-local CSS token uses state-first (`--stepper-active-bg`) or color-infix-state (`--link-color-hover`) naming instead of the canonical property-first state-suffix shape (`--<comp>(-<sub>)*-<prop>(-<state>)?`).
+
+#### Added — `scripts/release/check-token-name-canonical-shape.mjs`
+
+- ~210 LOC. Extracts `--<comp>-*` declarations from each component CSS file. Classifies each by segment shape: canonical-prop / canonical-prop-state / canonical-leaf / canonical-domain / drift-state-first / drift-infix-color-state.
+- Vocabularies (PROP_TOKENS + STATE_TOKENS) capture the catalog's recognized property + state terms (bg/fg/border/ring/shadow/color/outline/size + hover/active/selected/disabled/focus/checked/done/...).
+- Result: 92 components / 1809 component-local tokens audited / 0 drift findings.
+- `link.css` `--link-color-hover` not flagged at v0.5.15 ship: `color` is a recognized PROP_TOKEN + `hover` is a recognized STATE_TOKEN — the shape matches canonical. A future, stricter audit (alternative-property-naming) could flag the `color` vs `fg` divergence; deferred to v0.6.0 BREAKING window since link.css's `--link-color-*` are documented public API.
+
+### v0.5.15 §316 — Naming-convention drift fix (stepper + list state-first → property-first)
+
+`<stepper-ui>` and `<list-ui>` declared internal tokens with state-first naming (`--stepper-active-bg`, `--list-selected-fg`, etc.) — the catalog convention is property-first (`--<comp>-{prop}-{state}`). 18 token names renamed; usage sites updated in-place. `<link-ui>` skipped — its `--link-color-*` tokens are documented public API per `link.yaml tokens:` block; renaming is BREAKING and defers to v0.6.0.
+
+#### Changed — `components/stepper/`, `components/list/`
+
+- `stepper.css` — 12 tokens renamed: `--stepper-{active,done}-{bg,border,fg}` + `--stepper-item-{active,done}-{bg,border,fg}` → `--stepper-{bg,border,fg}-{active,done}` + `--stepper-item-{bg,border,fg}-{active,done}`.
+- `list.css` — 3 tokens renamed: `--list-selected-{bg,fg,border}` → `--list-{bg,fg,border}-selected`.
+
+### v0.5.15 §316 — Hand-rolled transition-duration literals → token references (swatch + heatmap + page)
+
+Three components hand-rolled `100ms ease-out` / `120ms ease-out` / `0.1s ease-out` / `150ms ease` instead of routing through the canonical `var(--a-duration-fast)` + `var(--a-easing*)` token chain. Theme designers couldn't swap transition cadence centrally.
+
+#### Changed — `components/swatch/`, `components/heatmap/`, `components/page/`
+
+- `swatch.css:294,311` — `100ms ease-out` + `120ms ease-out` → `var(--a-duration-fast) var(--a-easing-out)`.
+- `heatmap.css:80` — `0.1s ease-out` → `var(--a-duration-fast) var(--a-easing-out)`.
+- `page.css:61` — `150ms ease` → `var(--a-duration-fast) var(--a-easing)`.
+
+### v0.5.15 §317 — NEW audit slot 27: `check-raw-fg-in-component-css.mjs`
+
+Graduates the §313/§315/§316 bug class to a CI gate. Closes the recurring drift class where component CSS rules bypass their own `--<comp>-<family>-<state>` semantic-layer token and reference the raw global `--a-<family>-<state>` token directly. The audit slot found 5 additional bypass instances across the codebase (nav-group + select + toolbar) — all routed through the component-local semantic layer in this commit.
+
+#### Added — `scripts/release/check-raw-fg-in-component-css.mjs`
+
+- ~190 LOC audit script. Parses each `<comp>.css` for the `:where(:scope) { ... }` declaration block + the set of `--<comp>-*` tokens defined therein. Scans the remainder for `<standard-css-property>: var(--a-<family>-<state>?)` usage where the parallel `--<comp>-<family>-<state>?` is defined — emits a finding per bypass.
+- Whitelisted CSS properties: `color`, `background`, `background-color`, `border` (+ all sub-axis variants), `outline`, `fill`, `stroke`, `caret-color`, `accent-color`, `text-decoration-color`, `column-rule-color`.
+- Distinguishes declaration sites (`--<comp>-X: var(--a-X)`) from usage sites mechanically — declaration sites are NOT flagged (those are correct semantic-layer aliasing).
+- Companion to slot 25 (`check-component-css-vs-styles-tokens.mjs`): that audit catches orphan references (`var(--a-X)` where `--a-X` doesn't exist); this audit catches the inverse (`var(--a-X)` where it exists but `--<comp>-X` should be preferred).
+- EXPECTED_FINDINGS baseline: 0 entries at v0.5.15 ship (sweep landed every concrete bypass).
+
+#### Fixed — 5 component CSS bypass sites
+
+- `nav-group.css:243,252` — `background: var(--a-bg-hover)` → `var(--nav-group-bg-hover)`.
+- `select.css:199` — listbox container `color: var(--a-fg)` → `var(--select-fg)`.
+- `select.css:319` — hint slot fallback `var(--a-fg-muted)` → `var(--select-fg-muted)`.
+- `toolbar.css:107` — overflow popover `color: var(--a-fg)` → `var(--toolbar-fg)`.
+
+### v0.5.15 §317 — NEW audit slot 28: `check-form-bearing-events-symmetric.mjs`
+
+Graduates the FB-31/§315 bug class to a CI gate. Closes the recurring drift class where UIFormElement-extending primitives emit only `input` (or only `complete`/`search`/`pick`) without the canonical `change` event with `detail.value`. The audit confirms all 17 form-bearing primitives are now symmetric post-v0.5.14 §315.
+
+#### Added — `scripts/release/check-form-bearing-events-symmetric.mjs`
+
+- ~145 LOC audit script. Walks every `class.js` for classes that `extends UIFormElement`. For each, verifies a `dispatchEvent(new CustomEvent('change', { detail: { value: ... } }))` occurs (statically or via dynamic-name dispatch + nearby `'change'` string literal + `detail = { value: ... }` construction).
+- Heuristic limitations documented: false negatives possible if event name is computed via complex variable assignment; manual review at addition time required.
+- ALLOW_LIST mechanism for primitives where the commit model legitimately omits `change` (none at v0.5.15 ship).
+- Companion to slot 23 (`check-form-bearing-dts.mjs`): that audit verifies typed `<Comp>ChangeEvent` exists in `.d.ts`; this audit verifies the runtime dispatch.
+
+### v0.5.15 §318 — ADR-0028: L3 state-matrix orphan retirement (78 unused tokens deleted)
+
+ADR-0028 ratifies the deletion of 78 orphaned L3 state-matrix tokens from `semantics.css`. The `maintain-tokens` skill audit during v0.5.14 §315 surfaced that 73 of ~80 L3 `--a-{family}-{prop}-{state}` tokens have zero consumers across the entire codebase. The per-primitive `--<comp>-*` token pattern (validated across v0.5.13/14/15 sweeps) is the actual consumer-facing API.
+
+#### Removed — `styles/colors/semantics.css`
+
+- 78 `--a-{accent,primary,brand,info,success,warning,danger,fg,border}-{fg,bg,border}-{active,selected,disabled,invalid}` declarations deleted. ~80 LOC reduction.
+- Token count dropped 1301 → 1217 (-6.5%).
+- Kept (have consumers): `--a-bg-{active,selected,disabled,invalid}`, `--a-fg-{selected,disabled}`, `--a-accent-bg-active`, `--a-primary-bg-active` (transitive via accent-bg-active).
+- Kept (consumer-facing hover state): all `--a-*-hover` variants — hover is the only state where the generic-L3 layer is load-bearing.
+
+#### Added — `.brain/adrs/0028-l3-state-matrix-orphan-retirement.md`
+
+- ADR documents the audit-driven discovery, the retention rationale for the 7 used tokens, the deletion rationale for the 78 orphans, alternatives considered (keep all / delete only family-specific / add audit), and the per-primitive convention as the canonical consumer-facing override surface.
+
 ## [0.5.14] - 2026-05-15
 
 ### v0.5.14 — Form-control hover-fg token unification (precursor to §315; commit `178418525`)

package/components/badge/class.js

@@ -40,7 +40,11 @@ const STATUS_MAP = {
 export class UIBadge extends UIElement {
   static properties = {
     text:    { type: String,  default: '', reflect: true },
-    textContent: { type: String, default: '' },
+    // NOTE: `textContent` is intentionally NOT declared as a reactive
+    // prop — `installProps()` would override the native DOM setter, so
+    // `el.textContent = '…'` would silently no-op. Yaml keeps the prop
+    // entry for renderer metadata, but the JS class must not declare
+    // it. v0.5.x §327.
     variant: { type: String,  default: 'default', reflect: true },
     size:    { type: String,  default: 'md', reflect: true },
     icon:    { type: String,  default: '',        reflect: true },

package/components/button/class.js

@@ -19,7 +19,11 @@ import { getIcon } from '../../core/icons.js';
 export class UIButton extends UIElement {
   static properties = {
     text:     { type: String,  default: '', reflect: true },
-    textContent: { type: String, default: '' },
+    // NOTE: `textContent` is intentionally NOT declared as a reactive
+    // prop — `installProps()` would override the native DOM setter, so
+    // `el.textContent = '…'` would silently no-op instead of updating
+    // child text. Yaml keeps the prop entry for renderer metadata, but
+    // the JS class must not declare it. v0.5.x §327.
     variant:  { type: String,  default: 'solid', reflect: true },
     color:    { type: String,  default: '', reflect: true },
     size:     { type: String,  default: 'md', reflect: true },

package/components/code/class.js

@@ -62,7 +62,13 @@ export class UICode extends UIElement {
     language:     { type: String,  default: '', reflect: true },
     inline:       { type: Boolean, default: false, reflect: true },
     text:         { type: String,  default: '', reflect: true },
-    textContent:  { type: String,  default: '' },
+    // NOTE: `textContent` is intentionally NOT declared as a reactive prop.
+    // `installProps()` would override the native DOM setter with a signal
+    // setter, breaking `this.textContent = ''` in #stampBlock (the wipe
+    // becomes a no-op, leaving the authored HTML-escaped source visible
+    // above the stamped chrome and feeding an empty doc to CodeMirror).
+    // Initial content is read via the native getter in #stampBlock; live
+    // updates flow through the reactive `text` property. v0.5.x §327.
     lineNumbers:  { type: Boolean, default: false, reflect: true, attribute: 'line-numbers' },
     editable:     { type: Boolean, default: false, reflect: true },
     bare:         { type: Boolean, default: false, reflect: true },
@@ -132,10 +138,25 @@ export class UICode extends UIElement {
   }
 
   #stampBlock() {
-    // Prefer the `text` attribute when present; otherwise read the authored
-    // textContent. Either way, the block is rebuilt from semantic elements
-    // so whitespace in source HTML doesn't leak into the rendered <code>.
-    const raw = (this.text || this.textContent || '').trim();
+    // Content-source priority:
+    //   1. `text` attribute  — reactive, programmatic.
+    //   2. `<template>` child — escape-free authoring path. The HTML parser
+    //      treats `<template>` content as inert (DocumentFragment, not
+    //      rendered); we read `template.innerHTML` to recover the literal
+    //      source. Author can write `<code-ui language="html"><template>
+    //      <nav-ui>…</nav-ui></template></code-ui>` without `&lt;`/`&gt;`
+    //      escaping. Indent is normalized via #dedent() so the inner block
+    //      doesn't carry the wrapper's indentation. (v0.5.x §329)
+    //   3. Authored textContent — original path, requires HTML entities
+    //      for `<` and `>` (same constraint as `<pre><code>`).
+    // The block is rebuilt from semantic elements so whitespace in source
+    // HTML doesn't leak into the rendered <code>.
+    const tmpl = this.querySelector(':scope > template');
+    const raw = this.text
+      ? this.text.trim()
+      : tmpl
+        ? UICode.#dedent(tmpl.innerHTML)
+        : (this.textContent || '').trim();
     this.textContent = '';
 
     // Header — omitted in [bare] mode. Consumers that need zero chrome
@@ -206,6 +227,22 @@ export class UICode extends UIElement {
     this.appendChild(pre);
   }
 
+  /** Normalize indentation pulled from a `<template>` child. Strips
+   *  the common leading whitespace from every non-empty line so the
+   *  inner block reads as if it were authored at column 0. Equivalent
+   *  in spirit to Python's `textwrap.dedent` or a tagged-template
+   *  `dedent` helper. (v0.5.x §329) */
+  static #dedent(s) {
+    const trimmed = s.replace(/^\n+|\n+$/g, '');
+    if (!trimmed) return '';
+    const lines = trimmed.split('\n');
+    const indents = lines
+      .filter((l) => l.trim().length > 0)
+      .map((l) => l.match(/^[ \t]*/)[0].length);
+    const min = indents.length ? Math.min(...indents) : 0;
+    return min > 0 ? lines.map((l) => l.slice(min)).join('\n') : trimmed;
+  }
+
   async #mountEditor() {
     if (this.#pendingMount || this.#cmView) return;
     const gen = this.#mountGen;

package/components/code/code.a2ui.json

@@ -156,7 +156,7 @@
     ],
     "slots": {
       "default": {
-        "description": "Raw text fallback when the text property is not set"
+        "description": "Raw text fallback when the text property is not set. Two authoring shapes:\n(a) HTML-entity-escaped text (`&lt;nav-ui&gt;`) — same constraint as `<pre><code>`,\nsince the HTML parser treats unescaped tags as child elements; or\n(b) a `<template>` child whose `innerHTML` carries the literal source —\nescape-free authoring path. Indentation is dedented from the wrapper\ncolumn so the template's inner block reads at column 0. (v0.5.x §329)\n"
       }
     },
     "states": [

package/components/code/code.d.ts

@@ -40,6 +40,33 @@ export interface CodeLanguageLoadErrorEventDetail {
 }
 export type CodeLanguageLoadErrorEvent = CustomEvent<CodeLanguageLoadErrorEventDetail>;
 
+/**
+ * `<code-ui>` — syntax-highlighted code block (CodeMirror 6 under the hood).
+ *
+ * Three content-source paths in priority order:
+ *
+ *   1. `[text]` attribute — reactive, programmatic; updates re-render the block.
+ *
+ *   2. `<template>` child — escape-free authoring path (v0.5.x §329). Author
+ *      the source with literal `<` / `>` (the HTML parser treats `<template>`
+ *      content as inert; it lives in a `DocumentFragment` instead of being
+ *      upgraded into DOM elements). The wrapper indent is dedented so the
+ *      inner block reads at column 0.
+ *
+ *      ```html
+ *      <code-ui language="html">
+ *        <template>
+ *          <nav-ui>
+ *            <nav-item-ui text="Home"></nav-item-ui>
+ *          </nav-ui>
+ *        </template>
+ *      </code-ui>
+ *      ```
+ *
+ *   3. Authored textContent — original path. HTML samples require entity
+ *      escaping (`&lt;`/`&gt;`/`&amp;`), same constraint as `<pre><code>`,
+ *      since the parser treats unescaped tags as child elements.
+ */
 export class UICode extends UIFormElement {
   /** CodeMirror language slug — `javascript` / `typescript` / `html` / `css` / `json` / `markdown` / `python` etc. */
   language: string;

package/components/code/code.yaml

@@ -93,7 +93,13 @@ events:
         description: The underlying load failure.
 slots:
   default:
-    description: Raw text fallback when the text property is not set
+    description: |
+      Raw text fallback when the text property is not set. Two authoring shapes:
+      (a) HTML-entity-escaped text (`&lt;nav-ui&gt;`) — same constraint as `<pre><code>`,
+      since the HTML parser treats unescaped tags as child elements; or
+      (b) a `<template>` child whose `innerHTML` carries the literal source —
+      escape-free authoring path. Indentation is dedented from the wrapper
+      column so the template's inner block reads at column 0. (v0.5.x §329)
 states:
   - name: idle
     description: Default, ready for interaction.

package/components/heatmap/heatmap.css

@@ -77,7 +77,7 @@
     min-height: var(--heatmap-cell-min-size);
     aspect-ratio: 1 / 1;
     cursor: default;
-    transition: transform 0.1s ease-out;
+    transition: transform var(--a-duration-fast) var(--a-easing-out);
   }
 
   :scope [data-cell][data-v] {

package/components/list/list.css

@@ -2,9 +2,9 @@
   :where(:scope) {
     /* ── Colors ── */
     --list-divider-color: var(--a-border-subtle);
-    --list-selected-bg:   var(--a-accent-muted);
-    --list-selected-fg:   var(--a-accent-strong);
-    --list-selected-border: var(--a-accent-strong);
+    --list-bg-selected:   var(--a-accent-muted);
+    --list-fg-selected:   var(--a-accent-strong);
+    --list-border-selected: var(--a-accent-strong);
   }
 
   :scope {
@@ -68,9 +68,9 @@
   }
 
   :scope[selectable] > [role="listitem"][aria-selected="true"] {
-    background: var(--list-selected-bg);
-    color: var(--list-selected-fg);
-    border-inline-start-color: var(--list-selected-border);
+    background: var(--list-bg-selected);
+    color: var(--list-fg-selected);
+    border-inline-start-color: var(--list-border-selected);
   }
 
   :scope[selectable] > [role="listitem"]:focus-visible {

package/components/nav-group/nav-group.css

@@ -240,7 +240,7 @@ nav-group-ui [slot="popover"] [role="option"] {
 }
 
 nav-group-ui [slot="popover"] [role="option"]:hover {
-  background: var(--a-bg-hover);
+  background: var(--nav-group-bg-hover);
   color: var(--nav-group-fg-hover);
 }
 
@@ -249,7 +249,7 @@ nav-group-ui [slot="popover"] [role="option"]:hover {
 nav-group-ui [slot="popover"] [role="option"][aria-current="page"],
 nav-group-ui [slot="popover"] [role="option"][aria-selected="true"] {
   position: relative;
-  background: var(--a-bg-hover);
+  background: var(--nav-group-bg-hover);
   color: var(--nav-group-fg-selected);
   font-weight: var(--a-weight-medium);
 }

package/components/page/page.css

@@ -58,7 +58,7 @@
     top: 0;
     z-index: 1;
     background: var(--page-sticky-bg);
-    transition: border-color 150ms ease, box-shadow 150ms ease;
+    transition: border-color var(--a-duration-fast) var(--a-easing), box-shadow var(--a-duration-fast) var(--a-easing);
   }
 
   :scope[data-header-stuck] > :where(header, header-ui) {

package/components/segmented/class.js

@@ -36,6 +36,8 @@ export class UISegmented extends UIFormElement {
   #indicator = null;
   #bound = false;
   #transitionRaf = null;
+  #resizeObs = null;
+  #fontWait = null;
 
   connected() {
     super.connected();
@@ -52,6 +54,20 @@ export class UISegmented extends UIFormElement {
       const first = this.querySelector('segment-ui:not([disabled])');
       if (first) this.value = first.value || first.getAttribute('value') || '';
     }
+
+    // Recalculate indicator when layout shifts (font load, resize, content change)
+    if (typeof ResizeObserver !== 'undefined') {
+      this.#resizeObs = new ResizeObserver(() => this.#updateIndicator(this.#segments));
+      this.#resizeObs.observe(this);
+    }
+
+    // Also wait for fonts to settle — a common source of initial-layout drift
+    if (document.fonts?.ready) {
+      this.#fontWait = document.fonts.ready.then(() => {
+        this.#fontWait = null;
+        this.#updateIndicator(this.#segments);
+      });
+    }
   }
 
   disconnected() {
@@ -60,6 +76,12 @@ export class UISegmented extends UIFormElement {
       cancelAnimationFrame(this.#transitionRaf);
       this.#transitionRaf = null;
     }
+    this.#resizeObs?.disconnect();
+    this.#resizeObs = null;
+    if (this.#fontWait) {
+      // Promise can't be cancelled; the then-handler checks this.isConnected
+      this.#fontWait = null;
+    }
     this.removeEventListener('click', this.#handleClick);
     this.removeEventListener('keydown', this.#handleKeydown);
     this.#indicator = null;

package/components/select/select.css

@@ -196,7 +196,7 @@ select-ui [slot="listbox"] {
   overflow-y: auto;
   font-family: inherit;
   font-size: var(--a-ui-size);
-  color: var(--a-fg);
+  color: var(--select-fg);
 
   /* Positioned by JS (#positionListbox) — fixed to viewport */
   width: max-content;
@@ -316,6 +316,6 @@ select-ui > [slot="hint"] {
   display: block;
   margin-top: var(--select-hint-mt, var(--a-space-1));
   font-size: var(--select-hint-size, var(--a-ui-xs));
-  color: var(--select-hint-fg, var(--a-fg-muted));
+  color: var(--select-hint-fg, var(--select-fg-muted));
   line-height: var(--select-hint-lh, 1.4);
 }