@adia-ai/web-components 0.5.14 → 0.5.15

package/CHANGELOG.md

@@ -11,6 +11,193 @@ runtime ships in the sibling `@adia-ai/a2ui-runtime` package
 
 _No pending changes._
 
+## [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/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/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);
 }

package/components/stepper/stepper.css

@@ -20,13 +20,13 @@
     --stepper-weight:          var(--a-weight-medium);
     --stepper-border-size:     2px;
 
-    --stepper-active-bg:       var(--a-bg);
-    --stepper-active-border:   var(--a-accent);
-    --stepper-active-fg:       var(--a-accent);
+    --stepper-bg-active:       var(--a-bg);
+    --stepper-border-active:   var(--a-accent);
+    --stepper-fg-active:       var(--a-accent);
 
-    --stepper-done-bg:         var(--a-accent);
-    --stepper-done-border:     var(--a-accent);
-    --stepper-done-fg:         var(--a-accent-fg);
+    --stepper-bg-done:         var(--a-accent);
+    --stepper-border-done:     var(--a-accent);
+    --stepper-fg-done:         var(--a-accent-fg);
 
     --stepper-line:            var(--a-border-subtle);
     --stepper-line-done:       var(--a-accent);
@@ -76,13 +76,13 @@
     --stepper-item-weight:         var(--stepper-weight, var(--a-weight-medium));
     --stepper-item-border-size:    var(--stepper-border-size, 2px);
 
-    --stepper-item-active-bg:      var(--stepper-active-bg, var(--a-bg));
-    --stepper-item-active-border:  var(--stepper-active-border, var(--a-accent));
-    --stepper-item-active-fg:      var(--stepper-active-fg, var(--a-accent));
+    --stepper-item-bg-active:      var(--stepper-bg-active, var(--a-bg));
+    --stepper-item-border-active:  var(--stepper-border-active, var(--a-accent));
+    --stepper-item-fg-active:      var(--stepper-fg-active, var(--a-accent));
 
-    --stepper-item-done-bg:        var(--stepper-done-bg, var(--a-accent));
-    --stepper-item-done-border:    var(--stepper-done-border, var(--a-accent));
-    --stepper-item-done-fg:        var(--stepper-done-fg, var(--a-accent-fg));
+    --stepper-item-bg-done:        var(--stepper-bg-done, var(--a-accent));
+    --stepper-item-border-done:    var(--stepper-border-done, var(--a-accent));
+    --stepper-item-fg-done:        var(--stepper-fg-done, var(--a-accent-fg));
 
     --stepper-item-line:           var(--stepper-line, var(--a-border-subtle));
     --stepper-item-line-done:      var(--stepper-line-done, var(--a-accent));
@@ -158,9 +158,9 @@
 
   /* Active state */
   :scope[status="active"]::after {
-    border-color: var(--stepper-item-active-border);
-    color: var(--stepper-item-active-fg);
-    background: var(--stepper-item-active-bg);
+    border-color: var(--stepper-item-border-active);
+    color: var(--stepper-item-fg-active);
+    background: var(--stepper-item-bg-active);
   }
 
   :scope[status="active"] [slot="label"] {
@@ -171,9 +171,9 @@
   /* Completed state — checkmark replaces number */
   :scope[status="completed"]::after {
     content: '\2713';
-    background: var(--stepper-item-done-bg);
-    border-color: var(--stepper-item-done-border);
-    color: var(--stepper-item-done-fg);
+    background: var(--stepper-item-bg-done);
+    border-color: var(--stepper-item-border-done);
+    color: var(--stepper-item-fg-done);
   }
 
   :scope[status="completed"]::before {
@@ -214,15 +214,15 @@
   }
 
   :scope[status="active"] [slot="icon"] {
-    border-color: var(--stepper-item-active-border);
-    color: var(--stepper-item-active-fg);
-    background: var(--stepper-item-active-bg);
+    border-color: var(--stepper-item-border-active);
+    color: var(--stepper-item-fg-active);
+    background: var(--stepper-item-bg-active);
   }
 
   :scope[status="completed"] [slot="icon"] {
-    background: var(--stepper-item-done-bg);
-    border-color: var(--stepper-item-done-border);
-    color: var(--stepper-item-done-fg);
+    background: var(--stepper-item-bg-done);
+    border-color: var(--stepper-item-border-done);
+    color: var(--stepper-item-fg-done);
   }
 
   /* ── Content slots ── */

package/components/swatch/class.js

@@ -226,6 +226,17 @@ export class UISwatch extends UIElement {
     // Capture pre-existing default-slot content so consumer-authored
     // children (e.g. <swatch-ui>Forecast</swatch-ui>) survive stamping.
     // `[slot="chrome"]` children are already removed above, so won't appear here.
+    //
+    // §325 (v0.5.16, FB-36): filter pure-whitespace text nodes from the
+    // capture. Pre-§325, indented multi-line HTML (`<swatch-ui
+    // label="500">\n  <span>tip</span>\n</swatch-ui>`) captured the
+    // leading whitespace text node, which then made #labelEl.firstChild
+    // a nodeType=3 text node. #syncCore()'s "stale-text-node" branch
+    // matched the whitespace + did textContent = this.label, wiping
+    // BOTH the whitespace AND the consumer's <span>. Filter here so
+    // #labelEl.firstChild is the actual element/non-whitespace text,
+    // and #syncCore's stale-text branch only fires for genuinely
+    // attr-driven cases.
     const slotted = Array.from(this.childNodes).filter(n =>
       !(n.nodeType === 1 && n.dataset && (
         n.dataset.tile !== undefined ||
@@ -233,7 +244,7 @@ export class UISwatch extends UIElement {
         n.dataset.detail !== undefined ||
         n.dataset.badge !== undefined ||
         n.dataset.copy !== undefined
-      ))
+      )) && !(n.nodeType === 3 && !n.textContent.trim())
     );
     this.innerHTML = '';
 
@@ -282,9 +293,53 @@ export class UISwatch extends UIElement {
 
   // ── Sync ──────────────────────────────────────────────────────────
 
+  /**
+   * §326 (v0.5.16, FB-37): Late-arriving `[slot="chrome"]` children may
+   * land on the host AFTER `#stamp()` runs — happens in any template
+   * engine (lit-html, AdiaUI `html\`\``, etc.) that batches child appends
+   * separately from element creation. `#stamp()` is gated by
+   * `this.#stamped` and won't re-run; this method picks up the late
+   * arrivals on every `render()` pass + moves them to the canonical
+   * sibling-of-tile position (between `#tileEl` and `#badgeEl`).
+   *
+   * Idempotent: chrome children already in the right slot are left
+   * alone (the `insertBefore` only moves them if they're not the
+   * #badgeEl's immediate previousSibling chain).
+   */
+  #absorbChromeSlot() {
+    if (!this.#tileEl || !this.#badgeEl) return;
+    const chromeChildren = [];
+    for (const child of this.children) {
+      if (child === this.#tileEl) continue;
+      if (child === this.#badgeEl) break; // hit the badge — done scanning the head region
+      if (child.getAttribute?.('slot') === 'chrome') chromeChildren.push(child);
+    }
+    // Walk the rest of the children looking for chrome children that landed
+    // AFTER the internal structure (the common template-late-append case).
+    for (const child of Array.from(this.children)) {
+      if (
+        child !== this.#tileEl &&
+        child !== this.#badgeEl &&
+        child !== this.#labelEl &&
+        child !== this.#detailEl &&
+        child !== this.#copyEl &&
+        child.getAttribute?.('slot') === 'chrome'
+      ) {
+        // Move to the canonical position: immediately after #tileEl.
+        // insertBefore is idempotent — moving an already-positioned child
+        // to the same spot is a no-op.
+        this.insertBefore(child, this.#badgeEl);
+      }
+    }
+  }
+
   #syncCore() {
     if (!this.#tileEl || !this.#labelEl) return;
 
+    // §326 (v0.5.16, FB-37): pick up `[slot="chrome"]` children that
+    // landed after #stamp() ran (template-render path).
+    this.#absorbChromeSlot();
+
     // Normalize enum values; fall back silently when a consumer sets a typo.
     const shape = SHAPES.has(this.shape) ? this.shape : 'square';
     const size  = SIZES.has(this.size)   ? this.size  : 'md';

package/components/swatch/swatch.css

@@ -291,7 +291,7 @@
     line-height: 1;
     cursor: pointer;
     border-radius: var(--a-radius-xs);
-    transition: color 100ms ease-out, background 100ms ease-out;
+    transition: color var(--a-duration-fast) var(--a-easing-out), background var(--a-duration-fast) var(--a-easing-out);
   }
   :scope > [data-copy]:hover { color: var(--a-fg); background: var(--a-bg-muted); }
   :scope > [data-copy]:focus-visible {
@@ -308,7 +308,7 @@
   :scope[selectable] {
     cursor: pointer;
     border-radius: var(--a-radius-sm);
-    transition: box-shadow 120ms ease-out;
+    transition: box-shadow var(--a-duration-fast) var(--a-easing-out);
   }
   :scope[selectable]:focus { outline: none; }
   :scope[selectable]:focus-visible {

package/components/swatch/swatch.test.js

@@ -0,0 +1,163 @@
+/**
+ * <swatch-ui> behavioral tests.
+ *
+ * Currently scoped to FB-36 / §325 regression coverage. Future tests for
+ * #stamp() lifecycle, chrome-slot composition, auto-contrast probe,
+ * etc. land here.
+ *
+ * Test setup note: happy-dom connects custom elements synchronously
+ * during innerHTML parsing — BEFORE sibling children inside the same
+ * element are appended. Real browsers connect after the full innerHTML
+ * is parsed. To exercise the FB-36 path (children present at connect
+ * time), tests use `document.createElement` + `appendChild` to build
+ * the full subtree FIRST, then attach to the document — guaranteeing
+ * the children are in `this.childNodes` when `connectedCallback()` fires.
+ */
+
+import { describe, it, expect, beforeAll, beforeEach } from 'vitest';
+
+beforeAll(async () => {
+  await import('./swatch.js');
+});
+
+function buildSwatch({ label, defaultSlot, shape = 'block', labelPosition = 'overlay', color = '#3b82f6' }) {
+  const swatch = document.createElement('swatch-ui');
+  swatch.setAttribute('shape', shape);
+  swatch.setAttribute('label-position', labelPosition);
+  swatch.setAttribute('color', color);
+  if (label !== undefined) swatch.setAttribute('label', label);
+  if (defaultSlot) {
+    // Mimic indented HTML's whitespace text nodes — the FB-36 trigger.
+    swatch.appendChild(document.createTextNode('\n      '));
+    const child = document.createElement('span');
+    child.id = defaultSlot.id;
+    child.textContent = defaultSlot.text;
+    swatch.appendChild(child);
+    swatch.appendChild(document.createTextNode('\n    '));
+  }
+  return swatch;
+}
+
+describe('<swatch-ui> default-slot + label-attr precedence (FB-36 / §325)', () => {
+  let host;
+
+  beforeEach(() => {
+    host = document.createElement('div');
+    document.body.appendChild(host);
+  });
+
+  it('preserves default-slot element when label="X" is also present (FB-36 §325 fix)', async () => {
+    const swatch = buildSwatch({
+      label: '500',
+      defaultSlot: { id: 'probe-default', text: 'richlabel' },
+    });
+    host.appendChild(swatch);
+    await new Promise((r) => setTimeout(r, 80));
+
+    const label = swatch.querySelector('[data-label]');
+    const span = swatch.querySelector('#probe-default');
+
+    // Pre-§325 the span was wiped + label="500" took precedence.
+    // Post-§325 the default-slot wins (yaml spec: "richer content").
+    expect(span).not.toBeNull();
+    expect(label.textContent.trim()).toBe('richlabel');
+  });
+
+  it('renders label-attr text when no default-slot is present', async () => {
+    const swatch = buildSwatch({ label: '500' });
+    host.appendChild(swatch);
+    await new Promise((r) => setTimeout(r, 80));
+    const label = swatch.querySelector('[data-label]');
+    expect(label.textContent.trim()).toBe('500');
+  });
+
+  it('renders default-slot text when no label-attr is present', async () => {
+    const swatch = buildSwatch({
+      defaultSlot: { id: 'probe-only', text: 'defaultonly' },
+    });
+    host.appendChild(swatch);
+    await new Promise((r) => setTimeout(r, 80));
+    const label = swatch.querySelector('[data-label]');
+    const span = swatch.querySelector('#probe-only');
+    expect(span).not.toBeNull();
+    expect(label.textContent.trim()).toBe('defaultonly');
+  });
+
+  it('syncs label-attr changes when there is no default-slot (no whitespace regression)', async () => {
+    const swatch = buildSwatch({ label: '500' });
+    host.appendChild(swatch);
+    await new Promise((r) => setTimeout(r, 80));
+    swatch.label = '600';
+    await new Promise((r) => setTimeout(r, 80));
+    const label = swatch.querySelector('[data-label]');
+    expect(label.textContent.trim()).toBe('600');
+  });
+});
+
+describe('<swatch-ui> late-arriving [slot="chrome"] children (FB-37 / §326)', () => {
+  let host;
+
+  beforeEach(() => {
+    host = document.createElement('div');
+    document.body.appendChild(host);
+  });
+
+  it('absorbs chrome child appended AFTER connectedCallback (template-render path)', async () => {
+    // Mimic the template-engine timing: create the swatch + connect it FIRST
+    // (children empty), then append the chrome child + trigger a render.
+    const swatch = document.createElement('swatch-ui');
+    swatch.setAttribute('shape', 'block');
+    swatch.setAttribute('label-position', 'overlay');
+    swatch.setAttribute('color', '#3b82f6');
+    swatch.setAttribute('label', '500');
+    host.appendChild(swatch);
+    await new Promise((r) => setTimeout(r, 80));
+
+    // At this point #stamp() has run + chromeSlot was empty.
+    // Append a chrome child LATER — this is what template engines do.
+    const chrome = document.createElement('span');
+    chrome.setAttribute('slot', 'chrome');
+    chrome.id = 'late-chrome';
+    chrome.textContent = '★';
+    swatch.appendChild(chrome);
+
+    // Trigger a re-render via property mutation (template engines typically
+    // set props after appending — this nudge fires render → #syncCore →
+    // #absorbChromeSlot picks up the late chrome child). Must use a value
+    // DIFFERENT from current to actually fire the signal write.
+    swatch.label = '999';
+    await new Promise((r) => setTimeout(r, 80));
+
+    const found = swatch.querySelector('#late-chrome');
+    expect(found).not.toBeNull();
+    // Chrome child should be a direct host sibling positioned between tile + badge.
+    const tile = swatch.querySelector('[data-tile]');
+    const badge = swatch.querySelector('[data-badge]');
+    expect(found.previousElementSibling).toBe(tile);
+    expect(found.nextElementSibling).toBe(badge);
+  });
+
+  it('still handles chrome child appended BEFORE connect (static-HTML path)', async () => {
+    // Build swatch with chrome child present at connect time — the canonical
+    // FB-34 / §314 path should still work post-§326.
+    const swatch = document.createElement('swatch-ui');
+    swatch.setAttribute('shape', 'block');
+    swatch.setAttribute('label-position', 'overlay');
+    swatch.setAttribute('color', '#3b82f6');
+    swatch.setAttribute('label', '500');
+    const chrome = document.createElement('span');
+    chrome.setAttribute('slot', 'chrome');
+    chrome.id = 'early-chrome';
+    chrome.textContent = '⚑';
+    swatch.appendChild(chrome);
+    host.appendChild(swatch);
+    await new Promise((r) => setTimeout(r, 80));
+
+    const found = swatch.querySelector('#early-chrome');
+    expect(found).not.toBeNull();
+    const tile = swatch.querySelector('[data-tile]');
+    const badge = swatch.querySelector('[data-badge]');
+    expect(found.previousElementSibling).toBe(tile);
+    expect(found.nextElementSibling).toBe(badge);
+  });
+});

package/components/text/text.a2ui.json

@@ -36,7 +36,7 @@
       "default": false
     },
     "variant": {
-      "description": "Typography variant — sets role tokens (size/weight/tracking/color).",
+      "description": "Typography variant — sets design-role tokens (size / weight /\ntracking / color / leading) per the L0 typography token family.\n**PRESENTATIONAL-ONLY (§247, FB-23 §2).** `<text-ui variant=\"heading\">`\ndoes NOT set `role=\"heading\"` + `aria-level` on the host. Document-\noutline assistive technology will treat the element as `role=\"generic\"`.\nFor semantic headings, wrap with native `<h1>`-`<h6>` OR add\n`role=\"heading\" aria-level=\"N\"` on the host directly. For visual-only\nlabels (eyebrows, kickers, captions, deck), the presentational default\nis correct. The §221k chooser guide in USAGE.md documents picker heuristics.",
       "type": "string",
       "enum": [
         "body",
@@ -52,7 +52,21 @@
         "metric",
         "code"
       ],
-      "default": "body"
+      "default": "body",
+      "enum_descriptions": {
+        "title": "Page title (visual rank H1). Largest under display. Use at the top of an authoritative page or dialog.",
+        "body": "Default body copy. 14px / regular. Paragraphs, multi-line content, running prose.",
+        "caption": "Annotation under a primary line — smaller + muted. Use for image captions, footnotes.",
+        "code": "Inline monospace code reference. Use for inline code within prose.",
+        "deck": "Sub-title under a `title`. One-line lead, slightly larger than body. Use for the lead sentence after a title.",
+        "display": "Top-level hero / brand display. Tallest visual rank. Use for page-level hero one-liners.",
+        "heading": "Major page heading (visual rank H2). 16-18px / bold. Use for major sub-section dividers.",
+        "kicker": "Eyebrow text above a `title`. UPPERCASE + small + tracking. Use for content eyebrows (NOT form labels — use `label` for those).",
+        "label": "Form-control label (above an `<input-ui>` / `<select-ui>` etc). UI-sized + medium-weight. Use for field labels bound to form controls.",
+        "metric": "Numeric KPI / big-number stat. Bold + large. Use for dashboard metric numbers.",
+        "section": "Inline form-group / navlist heading (visual rank H4). Small-cap. Use for form group labels, nav list headings.",
+        "subsection": "Sub-landmark within a section (visual rank H3). 14px / semibold. Use for card titles within a section."
+      }
     }
   },
   "required": [

package/components/text/text.d.ts

@@ -1,41 +1,28 @@
 /**
- * `<text-ui>` — Typography wrapper that applies role tokens. Supports
- * truncation and line clamping.
+ * `<text-ui>` — Typography wrapper that applies role tokens. Supports truncation and line clamping.
  *
  * @see https://ui-kit.exe.xyz/site/components/text
  *
- * HAND-AUTHORED (not codegen'd) per §247 (v0.5.10) — the yaml `enum:` schema
- * carries variant names but not per-value descriptions; codegen emits a
- * single property-level JSDoc and loses the per-variant disambiguation that
- * the §221k chooser guide documents. Hand-authored .d.ts carries per-variant
- * JSDoc inline so IDE hover surfaces the disambiguation at authoring time.
- * Also carries the FB-23 §2 ARIA-role disclaimer on the property doc.
- * `dts-codegen.mjs` keeps this file in its `HAND_AUTHORED_DTS` skip list.
+ * Type declarations generated by scripts/build/dts-codegen.mjs from
+ * the component's `.a2ui.json` sidecar(s). Edit the source `.yaml`,
+ * run `npm run build:components`, then `npm run codegen:dts` to
+ * regenerate; or hand-author this file fully if rich event types are
+ * needed beyond what the yaml `events:` block can express.
  */
 
 import { UIElement } from '../../core/element.js';
 
-/**
- * Typography variants — visual rank from `display` (largest, hero) to
- * `code` (inline monospace). Pick by intent, not by visual size — every
- * variant has a distinct typographic role per §221k chooser guide.
- *
- * See `packages/web-components/USAGE.md` "v0.5.9 — Consumer-feedback
- * discoverability sweep" §221k for the picker heuristics.
- */
 export type UITextVariant =
   /** Default body copy. 14px / regular. Paragraphs, multi-line content, running prose. */
   | 'body'
-  /** Top-level hero / brand display. Tallest visual rank. Use for page-level hero one-liners. */
-  | 'display'
-  /** Page title (visual rank H1). Largest under display. Use at the top of an authoritative page or dialog. */
-  | 'title'
   /** Major page heading (visual rank H2). 16-18px / bold. Use for major sub-section dividers. */
   | 'heading'
+  /** Page title (visual rank H1). Largest under display. Use at the top of an authoritative page or dialog. */
+  | 'title'
   /** Sub-landmark within a section (visual rank H3). 14px / semibold. Use for card titles within a section. */
   | 'subsection'
-  /** Inline form-group / navlist heading (visual rank H4). Small-cap. Use for form group labels, nav list headings. */
-  | 'section'
+  /** Top-level hero / brand display. Tallest visual rank. Use for page-level hero one-liners. */
+  | 'display'
   /** Annotation under a primary line — smaller + muted. Use for image captions, footnotes. */
   | 'caption'
   /** Form-control label (above an `<input-ui>` / `<select-ui>` etc). UI-sized + medium-weight. Use for field labels bound to form controls. */
@@ -44,34 +31,30 @@ export type UITextVariant =
   | 'kicker'
   /** Sub-title under a `title`. One-line lead, slightly larger than body. Use for the lead sentence after a title. */
   | 'deck'
+  /** Inline form-group / navlist heading (visual rank H4). Small-cap. Use for form group labels, nav list headings. */
+  | 'section'
   /** Numeric KPI / big-number stat. Bold + large. Use for dashboard metric numbers. */
   | 'metric'
-  /** Inline monospace code reference. Use for `\`code\`` inline within prose. */
+  /** Inline monospace code reference. Use for inline code within prose. */
   | 'code';
 
 export class UIText extends UIElement {
-  /**
-   * Typography variant — sets design-role tokens (size / weight / tracking /
-   * color / leading) per the L0 typography token family.
-   *
-   * **PRESENTATIONAL-ONLY (§247, FB-23 §2).** `<text-ui variant="heading">`
-   * does NOT set `role="heading"` + `aria-level` on the host. Document-outline
-   * assistive technology will treat the element as `role="generic"`. For
-   * **semantic** headings (screen-reader heading-navigation, document
-   * outline), wrap with native `<h1>`-`<h6>` OR add
-   * `role="heading" aria-level="N"` on the host element directly.
-   *
-   * For visual-only labels (eyebrows, kickers, captions, deck), the
-   * presentational default is correct. The §221k chooser guide in USAGE.md
-   * documents the picker heuristics.
-   */
-  variant: UITextVariant;
-  /** When true, applies stronger emphasis (heavier weight + accent color). Styled via `:scope[strong]` in text.css. Use instead of `variant="heading"` when you want a single emphasized word inline in body copy. */
-  strong: boolean;
-  /** Single-line truncation with ellipsis. Ignored when `lines` is set. */
-  truncate: boolean;
-  /** Multi-line clamp count (0 = no clamp). Sets `--_text-lines` for `-webkit-line-clamp`. */
+  /** Multi-line clamp count (0 = no clamp) */
   lines: number;
+  /** When true, applies stronger emphasis (heavier weight + accent color). Styled via :scope[strong] in text.css. Use instead of variant=heading when you want a single emphasized word inline in body copy. */
+  strong: boolean;
   /** Display text content. The main payload field for Text components extracted from HTML. */
   textContent: string;
+  /** Single-line truncation with ellipsis. Ignored when `lines` is set. */
+  truncate: boolean;
+  /** Typography variant — sets design-role tokens (size / weight /
+tracking / color / leading) per the L0 typography token family.
+**PRESENTATIONAL-ONLY (§247, FB-23 §2).** `<text-ui variant="heading">`
+does NOT set `role="heading"` + `aria-level` on the host. Document-
+outline assistive technology will treat the element as `role="generic"`.
+For semantic headings, wrap with native `<h1>`-`<h6>` OR add
+`role="heading" aria-level="N"` on the host directly. For visual-only
+labels (eyebrows, kickers, captions, deck), the presentational default
+is correct. The §221k chooser guide in USAGE.md documents picker heuristics. */
+  variant: UITextVariant;
 }

package/components/text/text.yaml

@@ -28,7 +28,16 @@ props:
     default: ""
     dynamic: true
   variant:
-    description: Typography variant — sets role tokens (size/weight/tracking/color).
+    description: |-
+      Typography variant — sets design-role tokens (size / weight /
+      tracking / color / leading) per the L0 typography token family.
+      **PRESENTATIONAL-ONLY (§247, FB-23 §2).** `<text-ui variant="heading">`
+      does NOT set `role="heading"` + `aria-level` on the host. Document-
+      outline assistive technology will treat the element as `role="generic"`.
+      For semantic headings, wrap with native `<h1>`-`<h6>` OR add
+      `role="heading" aria-level="N"` on the host directly. For visual-only
+      labels (eyebrows, kickers, captions, deck), the presentational default
+      is correct. The §221k chooser guide in USAGE.md documents picker heuristics.
     type: string
     default: body
     enum:
@@ -44,6 +53,21 @@ props:
       - section
       - metric
       - code
+    # §324 (v0.5.15, FB-23 §3 retire): per-variant JSDoc surfaces at IDE
+    # hover via codegen. Retires the HAND_AUTHORED_DTS skip for text.d.ts.
+    enum_descriptions:
+      body: Default body copy. 14px / regular. Paragraphs, multi-line content, running prose.
+      display: Top-level hero / brand display. Tallest visual rank. Use for page-level hero one-liners.
+      title: Page title (visual rank H1). Largest under display. Use at the top of an authoritative page or dialog.
+      heading: Major page heading (visual rank H2). 16-18px / bold. Use for major sub-section dividers.
+      subsection: Sub-landmark within a section (visual rank H3). 14px / semibold. Use for card titles within a section.
+      section: Inline form-group / navlist heading (visual rank H4). Small-cap. Use for form group labels, nav list headings.
+      caption: Annotation under a primary line — smaller + muted. Use for image captions, footnotes.
+      label: Form-control label (above an `<input-ui>` / `<select-ui>` etc). UI-sized + medium-weight. Use for field labels bound to form controls.
+      kicker: Eyebrow text above a `title`. UPPERCASE + small + tracking. Use for content eyebrows (NOT form labels — use `label` for those).
+      deck: Sub-title under a `title`. One-line lead, slightly larger than body. Use for the lead sentence after a title.
+      metric: Numeric KPI / big-number stat. Bold + large. Use for dashboard metric numbers.
+      code: Inline monospace code reference. Use for inline code within prose.
 events: {}
 slots: {}
 states:

package/components/toolbar/toolbar.css

@@ -104,7 +104,7 @@ toolbar-ui [data-toolbar-spillover-menu]:popover-open {
   min-width: 10rem;
   font-family: inherit;
   font-size: var(--a-ui-size);
-  color: var(--a-fg);
+  color: var(--toolbar-fg);
   /* Stack overflow items as rows (each row can be a group with its own gap). */
   display: flex;
   flex-direction: column;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adia-ai/web-components",
-  "version": "0.5.14",
+  "version": "0.5.15",
   "description": "AdiaUI web components — vanilla custom elements. A2UI runtime (renderer, registry, streams, wiring) lives in @adia-ai/a2ui-runtime.",
   "type": "module",
   "types": "./index.d.ts",

package/styles/colors/semantics.css

@@ -116,20 +116,21 @@
   --a-fg-muted:      var(--a-canvas-text-muted);
   --a-fg-strong:     var(--a-canvas-text-strong);
   --a-fg-hover:      var(--a-canvas-text-strong);
-  --a-fg-active:     var(--a-canvas-text-strong);
+  /* ADR-0028: --a-fg-{active,invalid} retired (zero consumers). Use
+     `--a-ui-text-active` / `--a-ui-text-invalid` for form-control state,
+     or define a per-primitive `--<comp>-fg-{active,invalid}` token. */
   --a-fg-selected:   var(--a-canvas-text-strong);
   --a-fg-disabled:   var(--a-canvas-text-disabled);
-  --a-fg-invalid:    var(--a-danger-text);
   --a-fg-inverse:    var(--a-canvas-text-inverse);
 
   --a-border:          var(--a-canvas-border);
   --a-border-subtle:   var(--a-canvas-border-subtle);
   --a-border-strong:   var(--a-canvas-border-strong);
   --a-border-hover:    var(--a-canvas-border-strong);
-  --a-border-active:   var(--a-accent-border);
-  --a-border-selected: var(--a-accent-border);
-  --a-border-disabled: var(--a-canvas-border-subtle);
-  --a-border-invalid:  var(--a-danger-border);
+  /* ADR-0028: --a-border-{active,selected,disabled,invalid} retired (zero
+     consumers). Per-primitive `--<comp>-border-{state}` is the override
+     surface; `--a-focus-ring` carries focus-active borders for form
+     controls. */
 
   /* ══════════════════════════════════════════════════════════════
      ACCENT — Interactive, links, focus (source for --a-primary-*)
@@ -172,23 +173,12 @@
   --a-primary-bg:           var(--a-accent-strong);
   --a-primary-bg-hover:     var(--a-accent-hover);
   --a-primary-bg-active:    var(--a-accent-active);
-  --a-primary-bg-selected:  var(--a-accent-selected);
-  --a-primary-bg-disabled:  var(--a-accent-muted);
-  --a-primary-bg-invalid:   var(--a-danger-muted);
 
   --a-primary-fg:           var(--a-accent-05-tint);
   --a-primary-fg-hover:     var(--a-accent-text-strong);
-  --a-primary-fg-active:    var(--a-accent-text-strong);
-  --a-primary-fg-selected:  var(--a-accent-text-strong);
-  --a-primary-fg-disabled:  var(--a-accent-text-disabled);
-  --a-primary-fg-invalid:   var(--a-danger-text);
 
   --a-primary-border:           var(--a-accent-border);
   --a-primary-border-hover:     var(--a-accent-border-strong);
-  --a-primary-border-active:    var(--a-accent-border-strong);
-  --a-primary-border-selected:  var(--a-accent-border-strong);
-  --a-primary-border-disabled:  var(--a-accent-border-subtle);
-  --a-primary-border-invalid:   var(--a-danger-border);
 
   /* Legacy shorthand — keep until all components migrate to --a-primary-* */
   --a-primary:       var(--a-primary-bg);
@@ -200,16 +190,9 @@
   --a-accent-bg:           var(--a-primary-bg);
   --a-accent-bg-hover:     var(--a-primary-bg-hover);
   --a-accent-bg-active:    var(--a-primary-bg-active);
-  --a-accent-bg-selected:  var(--a-primary-bg-selected);
-  --a-accent-bg-disabled:  var(--a-primary-bg-disabled);
-  --a-accent-bg-invalid:   var(--a-primary-bg-invalid);
 
   --a-accent-fg:           var(--a-primary-fg);
   --a-accent-fg-hover:     var(--a-primary-fg-hover);
-  --a-accent-fg-active:    var(--a-primary-fg-active);
-  --a-accent-fg-selected:  var(--a-primary-fg-selected);
-  --a-accent-fg-disabled:  var(--a-primary-fg-disabled);
-  --a-accent-fg-invalid:   var(--a-primary-fg-invalid);
 
   /* accent border is already defined at L2 (--a-accent-border*);
      L3 matches L2 since both resolve to the same scheme-aware value. */
@@ -239,24 +222,12 @@
   /* L3 — Brand surface role matrix */
   --a-brand-bg:           var(--a-brand-strong);
   --a-brand-bg-hover:     var(--a-brand-hover);
-  --a-brand-bg-active:    var(--a-brand-active);
-  --a-brand-bg-selected:  var(--a-brand-selected);
-  --a-brand-bg-disabled:  var(--a-brand-muted);
-  --a-brand-bg-invalid:   var(--a-danger-muted);
 
   --a-brand-fg:           var(--a-brand-text-strong);
   --a-brand-fg-hover:     var(--a-brand-text-strong);
-  --a-brand-fg-active:    var(--a-brand-text-strong);
-  --a-brand-fg-selected:  var(--a-brand-text-strong);
-  --a-brand-fg-disabled:  var(--a-brand-text-disabled);
-  --a-brand-fg-invalid:   var(--a-danger-text);
 
   /* L3 border state matrix — rest state is --a-brand-border (L2 above). */
   --a-brand-border-hover:    var(--a-brand-border-strong);
-  --a-brand-border-active:   var(--a-brand-border-strong);
-  --a-brand-border-selected: var(--a-brand-border-strong);
-  --a-brand-border-disabled: var(--a-brand-border-subtle);
-  --a-brand-border-invalid:  var(--a-danger-border);
 
   /* ══════════════════════════════════════════════════════════════
      INFO
@@ -283,24 +254,12 @@
   /* L3 — Info surface role matrix */
   --a-info-bg:           var(--a-info-strong);
   --a-info-bg-hover:     var(--a-info-hover);
-  --a-info-bg-active:    var(--a-info-active);
-  --a-info-bg-selected:  var(--a-info-selected);
-  --a-info-bg-disabled:  var(--a-info-muted);
-  --a-info-bg-invalid:   var(--a-danger-muted);
 
   --a-info-fg:           var(--a-info-text-strong);
   --a-info-fg-hover:     var(--a-info-text-strong);
-  --a-info-fg-active:    var(--a-info-text-strong);
-  --a-info-fg-selected:  var(--a-info-text-strong);
-  --a-info-fg-disabled:  var(--a-info-text-disabled);
-  --a-info-fg-invalid:   var(--a-danger-text);
 
   /* L3 border state matrix — rest state is --a-info-border (L2 above). */
   --a-info-border-hover:    var(--a-info-border-strong);
-  --a-info-border-active:   var(--a-info-border-strong);
-  --a-info-border-selected: var(--a-info-border-strong);
-  --a-info-border-disabled: var(--a-info-border-subtle);
-  --a-info-border-invalid:  var(--a-danger-border);
 
   /* ══════════════════════════════════════════════════════════════
      SUCCESS
@@ -327,24 +286,12 @@
   /* L3 — Success surface role matrix */
   --a-success-bg:           var(--a-success-strong);
   --a-success-bg-hover:     var(--a-success-hover);
-  --a-success-bg-active:    var(--a-success-active);
-  --a-success-bg-selected:  var(--a-success-selected);
-  --a-success-bg-disabled:  var(--a-success-muted);
-  --a-success-bg-invalid:   var(--a-danger-muted);
 
   --a-success-fg:           var(--a-success-text-strong);
   --a-success-fg-hover:     var(--a-success-text-strong);
-  --a-success-fg-active:    var(--a-success-text-strong);
-  --a-success-fg-selected:  var(--a-success-text-strong);
-  --a-success-fg-disabled:  var(--a-success-text-disabled);
-  --a-success-fg-invalid:   var(--a-danger-text);
 
   /* L3 border state matrix — rest state is --a-success-border (L2 above). */
   --a-success-border-hover:    var(--a-success-border-strong);
-  --a-success-border-active:   var(--a-success-border-strong);
-  --a-success-border-selected: var(--a-success-border-strong);
-  --a-success-border-disabled: var(--a-success-border-subtle);
-  --a-success-border-invalid:  var(--a-danger-border);
 
   /* ══════════════════════════════════════════════════════════════
      WARNING
@@ -372,24 +319,12 @@
   /* L3 — Warning surface role matrix */
   --a-warning-bg:           var(--a-warning-strong);
   --a-warning-bg-hover:     var(--a-warning-hover);
-  --a-warning-bg-active:    var(--a-warning-active);
-  --a-warning-bg-selected:  var(--a-warning-selected);
-  --a-warning-bg-disabled:  var(--a-warning-muted);
-  --a-warning-bg-invalid:   var(--a-danger-muted);
 
   --a-warning-fg:           var(--a-warning-text-strong);
   --a-warning-fg-hover:     var(--a-warning-text-strong);
-  --a-warning-fg-active:    var(--a-warning-text-strong);
-  --a-warning-fg-selected:  var(--a-warning-text-strong);
-  --a-warning-fg-disabled:  var(--a-warning-text-disabled);
-  --a-warning-fg-invalid:   var(--a-danger-text);
 
   /* L3 border state matrix — rest state is --a-warning-border (L2 above). */
   --a-warning-border-hover:    var(--a-warning-border-strong);
-  --a-warning-border-active:   var(--a-warning-border-strong);
-  --a-warning-border-selected: var(--a-warning-border-strong);
-  --a-warning-border-disabled: var(--a-warning-border-subtle);
-  --a-warning-border-invalid:  var(--a-danger-border);
 
   /* ══════════════════════════════════════════════════════════════
      DANGER
@@ -418,24 +353,12 @@
   /* L3 — Danger surface role matrix */
   --a-danger-bg:           var(--a-danger-strong);
   --a-danger-bg-hover:     var(--a-danger-hover);
-  --a-danger-bg-active:    var(--a-danger-active);
-  --a-danger-bg-selected:  var(--a-danger-selected);
-  --a-danger-bg-disabled:  var(--a-danger-muted);
-  --a-danger-bg-invalid:   var(--a-danger-muted);
 
   --a-danger-fg:           var(--a-danger-text-strong);
   --a-danger-fg-hover:     var(--a-danger-text-strong);
-  --a-danger-fg-active:    var(--a-danger-text-strong);
-  --a-danger-fg-selected:  var(--a-danger-text-strong);
-  --a-danger-fg-disabled:  var(--a-danger-text-disabled);
-  --a-danger-fg-invalid:   var(--a-danger-text);
 
   /* L3 border state matrix — rest state is --a-danger-border (L2 above). */
   --a-danger-border-hover:    var(--a-danger-border-strong);
-  --a-danger-border-active:   var(--a-danger-border-strong);
-  --a-danger-border-selected: var(--a-danger-border-strong);
-  --a-danger-border-disabled: var(--a-danger-border-subtle);
-  --a-danger-border-invalid:  var(--a-danger-border);
 
   /* ══════════════════════════════════════════════════════════════
      BUCKETS — sequential 5-step ramp per family for data-vis consumers