@adia-ai/web-components 0.5.12 → 0.5.14

package/CHANGELOG.md

@@ -11,6 +11,123 @@ runtime ships in the sibling `@adia-ai/a2ui-runtime` package
 
 _No pending changes._
 
+## [0.5.14] - 2026-05-15
+
+### v0.5.14 — Form-control hover-fg token unification (precursor to §315; commit `178418525`)
+
+Form-control primitives diverged on hover-text token routing. `button-ui` correctly used `--a-ui-text-hover` (resolves to `--a-fg-strong` — canonical hover-lift for form-control text); every other form-control primitive used the generic `--a-fg` (no actual lift from default `--a-canvas-text`) — so "hover" had zero text-color effect on `input`/`textarea`/`segment`, and `select-ui`'s listbox/caret hover paths bypassed the `--select-*` token layer entirely with raw `--a-fg-*` references.
+
+#### Fixed — `components/{input,textarea,segment,select}/`
+
+- `input-ui`: `--input-fg-hover: var(--a-fg)` → `var(--a-ui-text-hover)`; `--input-affix-fg-hover: var(--a-fg-subtle)` → `var(--a-ui-text-subtle)`.
+- `textarea-ui`: matching routing on hover/affix-hover.
+- `segment-ui`: same routing change.
+- `select-ui`: listbox + caret + option-hover tokens previously raw `--a-fg-*` references now route through their `--select-*` semantic layer (which itself anchors at `--a-ui-text-*` family).
+
+Net effect: hover-text colors now consistent across all form-control primitives + theme designers can swap them all by changing one semantic token (`--a-ui-text-hover`) at the `--a-ui-*` family root in `semantics.css`.
+
+### v0.5.14 §315 — Drift-class sweep follow-up (`ui-audit-coherence` + `maintain-tokens` + `analyze-css` triple-pass)
+
+Three parallel skill-driven audits surfaced 7 mechanical drift-classes; landed as a single sweep in one commit (`025a981db`). Follow-up to the form-control hover-fg unification at `178418525` — same bug shape (component CSS bypassing its own semantic-layer routing through raw global tokens), broader scope.
+
+#### Fixed — `components/select/`, `components/nav-group/`, `components/chat-thread/chat-input.css`
+
+- `select.css:254,286,293,300` — 4 raw `var(--a-fg-*)` callsites routed through `--select-fg-{muted,fg,muted,muted}` (semantic layer already existed but was bypassed).
+- `nav-group.css:225,234,244,253,286,298` — 6 raw `var(--a-fg-{muted,subtle,strong})` callsites routed through `--nav-group-fg-{muted,muted,hover,selected,muted,muted}`.
+- `chat-input.css:40,50,58` — placeholder/hover/disabled tokens routed through the canonical `--a-ui-text-{placeholder,hover,disabled}` field-family chain instead of the generic `--a-fg-*` family. Continues the v0.5.13 hover-fg unification arc.
+
+#### Fixed — `components/{check,radio,switch,tabs,action-list,calendar-picker,menu}/`
+
+- 6 form-adjacent primitives' `--{comp}-fg-disabled` token routed through canonical `--a-ui-text-disabled` instead of `--a-fg-muted` (the disabled-text version of the v0.5.13 hover-fg drift class).
+- `menu.css:96,99` also fixed `--menu-item-fg-disabled` + `--menu-item-icon-disabled` (the third variant `--a-fg-disabled` shape; same canonical target).
+
+#### Added — `components/otp-input/`, `components/search/`
+
+- `<otp-input-ui>` + `<search-ui>` now dispatch `change` alongside `input` on every value-altering event. Both primitives previously emitted only `input` (the sole exceptions across all UIFormElement-bearing primitives). Closes consumer event-binding gap — `@change=${handler}` now works against every form-bearing tag uniformly.
+- `.d.ts` files gain `OtpInputChangeEvent` + `SearchChangeEvent` type exports (reuse existing detail interfaces; matches v0.5.10 `check-form-bearing-dts` audit convention).
+- yaml `events:` blocks declare the new `change` event with `detail.value`.
+
+#### Fixed — `styles/typography.css`
+
+- `:where(mark)` background reference fixed: `var(--a-highlight-default)` → `var(--a-highlight)` (`--a-highlight-default` token does not exist; pre-fix `<mark>` silently fell back to UA-default highlight). Single-line typo discovered via `maintain-tokens` skill sweep.
+
+#### Fixed — `components/{textarea,upload,option-card,pagination}/` transition consistency
+
+- `textarea.css:76` transition list expanded from `border-color` only → `background + border-color + color + box-shadow` (matches `input-ui`'s 4-property parity; pre-fix hover/focus slammed in instead of easing).
+- `upload.css:64-67` + `option-card.css:102-104` + `pagination.css:71-73` each gain `box-shadow` (and `border-color` for pagination) so focus-ring eases in alongside the other state changes. Cross-primitive hover/focus polish parity restored.
+
+#### Fixed — `components/input/`, `components/select/` `-active` token routing
+
+- `--input-fg-focus: var(--a-fg-strong)` → `var(--a-ui-text-active)` (closes orphan: `--a-ui-text-active` semantic-layer alias existed at `semantics.css:552` with zero consumers).
+- `--select-option-fg-active: var(--a-fg)` → `var(--a-ui-text-active)` (same routing; cross-primitive form-control consistency).
+
+#### Fixed — `components/heatmap/`
+
+- `class.js:disconnected()` now cancels `#raf` via `cancelAnimationFrame()`. Pre-fix the `requestAnimationFrame` handle was stored but never cleaned up on detach — minor memory leak in scroll-heavy demos. ~3 LOC.
+
+## [0.5.13] - 2026-05-15
+
+### v0.5.13 §310 — `apcaContrast` soft-clamp constant fix (FEEDBACK-35; P2 correctness)
+
+`@adia-ai/web-components/color`'s `apcaContrast()` was using `APCA_LO_CLAMP = 0.06` for the soft-clamp threshold where the canonical APCA spec (`apca-w3@0.1.9`'s `SAPC_BLACK_THRESHOLD`) calls for `0.022`. The cubic-root soft-clamp `Math.pow(threshold - Y, 1.414)` operating on the wrong threshold lifted near-black luminance too aggressively. Pre-fix `apcaContrast('#000','#fff')` returned 99.49; post-fix returns 106.04 — matches canonical reference within ±0.01 Lc across all 8 reference pairs. Consumers using `<swatch-ui auto-contrast>` (which transitively calls `pickContrastingFg → apcaContrast`) silently got wrong contrast verdicts for any swatch with `Y < 0.06`.
+
+#### Fixed — `color/`
+
+- `color/index.js` `apcaContrast()` soft-clamp now uses `APCA_LO_FG`/`APCA_LO_BG = 0.022` (declared correctly since v0.5.12 but never read). Dead constants (`APCA_NORM_L`, `APCA_REVERSE_FACTOR`, `APCA_NORM_FACTOR`, `APCA_LO_CLAMP`, `APCA_RESCALE`) removed; new `APCA_BLACK_CLAMP = 1.414` factored out for readability.
+
+### v0.5.13 §311 — `@adia-ai/web-components/color` P3 helpers (FEEDBACK-31)
+
+`@adia-ai/web-components/color` (v0.5.12 §301) shipped sRGB-only gamut helpers; the v0.6.0 §301 plan-doc spec lines 121-126 committed both sRGB AND Display-P3. v0.5.13 §311 closes the gap.
+
+#### Added — `color/`
+
+- `inP3Gamut(L, C, H): boolean` — returns true if the OKLCH triple is inside Display-P3 gamut (tolerance `0.001`).
+- `gamutMapChromaP3(L, C, H): number` — 8-iteration chroma bisection in P3 (matches `gamutMapChroma`'s shape).
+- Internal `linearSrgbToLinearP3()` matrix sourced from CSS Color 4 § 12.3 (D65 → D65; no Bradford chromatic adaptation needed).
+- `color/index.d.ts` ships matching declarations.
+
+### v0.5.13 §312 — `<stat-ui>` explicit exports map entries (FEEDBACK-32)
+
+v0.5.12 §253a hand-authored `stat-ui.d.ts` on disk but the package.json wildcard `./components/*` expanded `./components/stat` → `./components/stat/stat.js` (non-existent; actual file is `stat-ui.js`). Consumer TS imports failed at the package-export layer with `TS2882` even though the file exists + Vite resolved at runtime.
+
+#### Changed — `package.json`
+
+- `exports` map adds 2 explicit entries: `./components/stat` + `./components/stat/stat-ui.js` both pointing at `stat-ui.{d.ts,js}`.
+- **Drops at v0.6.0 §303** when the `git mv stat-ui.{js,css,d.ts} → stat.{js,css,d.ts}` rename normalizes the filename + the wildcard naturally covers `stat.{js,d.ts}`.
+
+### v0.5.13 §313 — `<color-input-ui>` constraint pass-through + parsed-detail forwarding (FEEDBACK-33)
+
+`<color-input-ui>` (v0.5.12 §302) composed `<color-picker-ui>` but dropped 5 generation-constraint props (`maxChroma` / `maxL` / `minL` / `hueDriftMax` / `baseHue`) and 3 parsed-OKLCH-channel-scalars (`{l, c, h}`) from the re-emitted event detail. Consumers using L-range constraints or OKLCH-native logic (Tokens Studio's `defaults.Lmin`/`Lmax`) couldn't migrate to `<color-input-ui>` without a UX regression.
+
+#### Added — `components/color-input/`
+
+- `class.js` adds 5 generation-constraint props to `static properties` + sets them on inner picker at `#mount()` + diff-detect re-set on `render()` (Object.is handles NaN-equality for `baseHue`/`hueDriftMax`).
+- `#commit()` re-emits with all 6 detail fields including parsed scalars `l: detail.l, c: detail.c, h: detail.h`.
+- `color-input.yaml` declares the 5 props + 3 new detail fields per `change`/`input` events.
+- `color-input.d.ts` `ColorInputChangeEventDetail` interface gains `l: number; c: number; h: number;` fields; class gains 5 typed prop declarations.
+
+### v0.5.13 §314 — `<swatch-ui>` `[slot="chrome"]` named slot (FEEDBACK-34)
+
+`<swatch-ui>`'s `#stamp()` lifecycle wiped `innerHTML` then funneled surviving children into `#labelEl`. Consumer chrome positioned absolutely against the swatch tile (gamut badges + override/tracked dots per C1.3 dogfood) landed inside the label's text bbox where `position: absolute; top/right/bottom/left` anchored to the small label geometry instead of the tile. v0.5.13 §314 adds a `[slot="chrome"]` named slot whose children survive stamping as direct host siblings of `#tileEl`.
+
+#### Added — `components/swatch/`
+
+- `class.js` `#stamp()` extracts `[slot="chrome"]` children BEFORE the wipe; re-attaches them as direct host siblings IMMEDIATELY after `#tileEl`. The host's `position: relative` anchor (when `shape="block"`) lets consumer absolute-positioning anchor to the tile's geometry.
+- `swatch.yaml` `slots:` block declares the `chrome` named slot + clarifies `default` slot's funnel-into-label behavior.
+
+#### Migration
+
+```diff
+ <swatch-ui shape="block" label-position="overlay" selectable>
+-  <badge-ui class="dts-gamut-badge" ...>P3</badge-ui>
+-  <span class="dts-override-dot"></span>
++  <badge-ui slot="chrome" class="dts-gamut-badge" ...>P3</badge-ui>
++  <span slot="chrome" class="dts-override-dot"></span>
+ </swatch-ui>
+```
+
+Single `slot="chrome"` attribute on each chrome element. Existing absolute-positioning CSS unchanged.
+
 ## [0.5.12] - 2026-05-15
 
 ### v0.5.12 §252 — `package.json` `files` array completion (FB-28 close-out)

package/color/index.d.ts

@@ -87,6 +87,22 @@ export function isOklchInGamut(L: number, C: number, H: number): boolean;
  */
 export function gamutMapChroma(L: number, C: number, H: number): number;
 
+// ── Display-P3 gamut (v0.5.13 §-TBD, FB-31) ──────────────────────────────
+
+/**
+ * Returns true if the OKLCH triple is inside Display-P3 gamut (tolerance
+ * `0.001`). sRGB-linear → P3-linear conversion uses the CSS Color 4 § 12.3
+ * matrix (D65 → D65; no Bradford adaptation needed).
+ */
+export function inP3Gamut(L: number, C: number, H: number): boolean;
+
+/**
+ * Bisect chroma to find the largest value that keeps `(L, _, H)` in
+ * Display-P3 gamut. 8 bisection iterations — same shape as the sRGB
+ * `gamutMapChroma`. Used by P3-aware design tooling.
+ */
+export function gamutMapChromaP3(L: number, C: number, H: number): number;
+
 // ── APCA (advanced perceptual contrast algorithm) ─────────────────────────
 
 /**

package/color/index.js

@@ -154,15 +154,67 @@ export function gamutMapChroma(L, C, H) {
   return lo;
 }
 
+// ── Display-P3 gamut ──────────────────────────────────────────────────────
+//
+// v0.5.13 §-TBD (FB-31). The v0.6.0 §301 plan-doc spec committed
+// `inP3Gamut(o)` + `gamutMapOklch(o, 'p3')`; the v0.5.12 §301 ship dropped
+// both (sRGB-only surface). FB-31 closes the gap with explicit P3 helpers
+// matching the existing scalar-channels signature shape.
+//
+// sRGB-linear → Display-P3-linear matrix sourced from CSS Color 4 § 12.3
+// (assumes both spaces share the D65 white point, which is true post-2018
+// browser implementations; no Bradford chromatic adaptation needed).
+
+function linearSrgbToLinearP3(r, g, b) {
+  return [
+    0.8224621 * r + 0.1775380 * g + 0.0000000 * b,
+    0.0331941 * r + 0.9668058 * g + 0.0000001 * b,
+    0.0170827 * r + 0.0723974 * g + 0.9105199 * b,
+  ];
+}
+
+/** Returns true if the OKLCH triple is inside Display-P3 gamut (tolerance `0.001`). */
+export function inP3Gamut(L, C, H) {
+  const { a, b } = oklchToOklab(L, C, H);
+  const [lr, lg, lb] = oklabToLinearSrgb(L, a, b);
+  const [p3r, p3g, p3b] = linearSrgbToLinearP3(lr, lg, lb);
+  return isInGamut(linearToSrgb(p3r), linearToSrgb(p3g), linearToSrgb(p3b));
+}
+
+/**
+ * Bisect chroma to find the largest value that keeps `(L, _, H)` in
+ * Display-P3 gamut. 8 bisection iterations — same shape as the sRGB
+ * `gamutMapChroma`. Used by P3-aware design tooling (Tokens Studio,
+ * theme designers targeting P3-display laptops + iPads).
+ */
+export function gamutMapChromaP3(L, C, H) {
+  if (inP3Gamut(L, C, H)) return C;
+  let lo = 0, hi = C;
+  for (let i = 0; i < 8; i++) {
+    const mid = (lo + hi) / 2;
+    if (inP3Gamut(L, mid, H)) lo = mid;
+    else hi = mid;
+  }
+  return lo;
+}
+
 // ── APCA (advanced perceptual contrast algorithm) ─────────────────────────
+//
+// Source of truth: Andrew Somers' SACAM specification + apca-w3@0.1.9 (the
+// W3C-pinned reference impl). The soft-clamp threshold is `0.022` for both
+// fg + bg luminance values (per `SAPC_BLACK_THRESHOLD` in apca-w3 source).
+// The 1.414 exponent is the APCA "BLACK_CLAMP" rescale constant.
+//
+// v0.5.13 §-TBD (FB-35): corrected the soft-clamp constant. v0.5.12 ship
+// used 0.06 (declared as APCA_LO_CLAMP) by mistake, producing Lc 99.49 for
+// black-on-white where canonical is 106.04 (-6.5pt bias for any pair
+// involving near-black). Constants APCA_LO_FG / APCA_LO_BG were declared
+// correctly but never read; the 0.06 constant was a stray from an earlier
+// draft. apcaSrgbY() unchanged.
 
-const APCA_NORM_L = 0.027;
 const APCA_LO_BG = 0.022;
 const APCA_LO_FG = 0.022;
-const APCA_REVERSE_FACTOR = 1.14;
-const APCA_NORM_FACTOR = 1.14;
-const APCA_LO_CLAMP = 0.06;
-const APCA_RESCALE = 1.14;
+const APCA_BLACK_CLAMP = 1.414;
 
 function apcaSrgbY(rNorm, gNorm, bNorm) {
   // sRGB → relative luminance via APCA Y (different coefficients than WCAG).
@@ -201,9 +253,10 @@ export function apcaContrast(fgHex, bgHex) {
   let Yfg = apcaSrgbY(fg.r, fg.g, fg.b);
   let Ybg = apcaSrgbY(bg.r, bg.g, bg.b);
 
-  // Soft clamp near black per APCA.
-  if (Yfg < APCA_LO_CLAMP) Yfg += Math.pow(APCA_LO_CLAMP - Yfg, 1.414);
-  if (Ybg < APCA_LO_CLAMP) Ybg += Math.pow(APCA_LO_CLAMP - Ybg, 1.414);
+  // Soft clamp near black per APCA spec — threshold 0.022 per SACAM /
+  // apca-w3@0.1.9 (`SAPC_BLACK_THRESHOLD`).
+  if (Yfg < APCA_LO_FG) Yfg += Math.pow(APCA_LO_FG - Yfg, APCA_BLACK_CLAMP);
+  if (Ybg < APCA_LO_BG) Ybg += Math.pow(APCA_LO_BG - Ybg, APCA_BLACK_CLAMP);
 
   let Lc;
   if (Ybg > Yfg) {

package/components/action-list/action-list.css

@@ -39,7 +39,7 @@ action-item-ui:hover [slot="icon"] {
     --action-item-fg:              var(--a-fg-subtle);
     --action-item-fg-hover:        var(--a-fg-strong);
     --action-item-bg-hover:        var(--a-bg-muted);
-    --action-item-fg-disabled:     var(--a-fg-muted);
+    --action-item-fg-disabled:     var(--a-ui-text-disabled);
     --action-item-icon-fg:         var(--a-fg-muted);
     --action-item-icon-fg-hover:   var(--a-fg);
     --action-item-danger-fg:       var(--a-danger-bg);

package/components/calendar-picker/calendar-picker.css

@@ -68,7 +68,7 @@
     --calendar-picker-day-bg-selected:        var(--a-accent);
     --calendar-picker-day-fg-selected:        var(--a-accent-fg);
     --calendar-picker-day-fg-outside:         var(--a-fg-muted);
-    --calendar-picker-day-fg-disabled:        var(--a-fg-muted);
+    --calendar-picker-day-fg-disabled:        var(--a-ui-text-disabled);
     --calendar-picker-day-today-border:       var(--a-accent);
     --calendar-picker-day-today-dot-size:     var(--a-space-0-5);
     --calendar-picker-day-today-dot-offset:   var(--a-space-1);

package/components/chat-thread/chat-input.css

@@ -37,7 +37,7 @@ chat-input-ui textarea-ui:not([disabled]) [slot="text"]:hover {
     --chat-input-fg:              var(--a-fg);
     --chat-input-border:          var(--a-border-subtle);
     --chat-input-caret-color:     var(--a-fg-subtle);
-    --chat-input-placeholder-fg:  var(--a-fg-muted);
+    --chat-input-placeholder-fg:  var(--a-ui-text-placeholder);
 
     /* Hover — matches input-ui's affordance (subtle alpha lift on the
        canvas surface + slightly stronger border + brightened fg). The
@@ -47,7 +47,7 @@ chat-input-ui textarea-ui:not([disabled]) [slot="text"]:hover {
        doesn't compound. */
     --chat-input-bg-hover:        var(--a-ui-bg-hover);
     --chat-input-border-hover:    var(--a-ui-border-hover);
-    --chat-input-fg-hover:        var(--a-fg);
+    --chat-input-fg-hover:        var(--a-ui-text-hover);
 
     /* Disabled — host-level chrome (background, border, pointer-events)
        lives on `:scope[disabled]` below. Inner-text disabled color is
@@ -55,7 +55,7 @@ chat-input-ui textarea-ui:not([disabled]) [slot="text"]:hover {
        leak through. */
     --chat-input-bg-disabled:     transparent;
     --chat-input-border-disabled: var(--a-border-subtle);
-    --chat-input-fg-disabled:     var(--a-fg-disabled);
+    --chat-input-fg-disabled:     var(--a-ui-text-disabled);
 
     /* Canonical focus ring — chat-input is a *nested-control host*.
        See semantics.css FOCUS block + the nested-control pattern

package/components/check/check.css

@@ -60,7 +60,7 @@ check-ui[indeterminate] {
     --check-bg-checked-hover: var(--a-primary-hover);
 
     /* ── State: disabled ── */
-    --check-fg-disabled:      var(--a-fg-muted);
+    --check-fg-disabled:      var(--a-ui-text-disabled);
 
     /* ── Check icon (CSS border trick, no SVG) ── */
     --_icon-w:    0;

package/components/color-input/class.js

@@ -40,10 +40,20 @@ export class UIColorInput extends UIFormElement {
   static get properties() {
     return {
       ...UIFormElement.properties,
-      value:     { type: String,  default: '#3b82f6', reflect: true },
-      format:    { type: String,  default: 'hex', reflect: true },
-      placement: { type: String,  default: 'bottom-start', reflect: true },
-      open:      { type: Boolean, default: false, reflect: true },
+      value:       { type: String,  default: '#3b82f6', reflect: true },
+      format:      { type: String,  default: 'hex', reflect: true },
+      placement:   { type: String,  default: 'bottom-start', reflect: true },
+      open:        { type: Boolean, default: false, reflect: true },
+      // Generation-constraint props forwarded to the inner <color-picker-ui>.
+      // v0.5.13 §-TBD (FB-33 §1) — full parity with color-picker's 5 constraint
+      // props (`maxChroma` / `maxL` / `minL` / `hueDriftMax` / `baseHue`) so
+      // <color-input-ui> adoption doesn't force a UX regression on consumers
+      // already using L-range / chroma / hue-drift constraints.
+      maxChroma:   { type: Number,  default: Infinity, reflect: true },
+      maxL:        { type: Number,  default: 1, reflect: true },
+      minL:        { type: Number,  default: 0, reflect: true },
+      hueDriftMax: { type: Number,  default: NaN, reflect: true },
+      baseHue:     { type: Number,  default: NaN, reflect: true },
     };
   }
 
@@ -66,8 +76,16 @@ export class UIColorInput extends UIFormElement {
     if (this.#popover && this.#popover.open !== this.open) {
       this.#popover.open = this.open;
     }
-    if (this.#picker && this.#picker.format !== this.format) {
-      this.#picker.format = this.format;
+    if (this.#picker) {
+      if (this.#picker.format !== this.format) this.#picker.format = this.format;
+      // Forward live changes to the 5 generation-constraint props (FB-33 §1).
+      // Object.is handles the NaN-equality case correctly so `baseHue`/
+      // `hueDriftMax` don't reassign on every render.
+      if (!Object.is(this.#picker.maxChroma, this.maxChroma))   this.#picker.maxChroma = this.maxChroma;
+      if (!Object.is(this.#picker.maxL, this.maxL))             this.#picker.maxL = this.maxL;
+      if (!Object.is(this.#picker.minL, this.minL))             this.#picker.minL = this.minL;
+      if (!Object.is(this.#picker.hueDriftMax, this.hueDriftMax)) this.#picker.hueDriftMax = this.hueDriftMax;
+      if (!Object.is(this.#picker.baseHue, this.baseHue))       this.#picker.baseHue = this.baseHue;
     }
     if (this.#button) {
       if (this.disabled) this.#button.setAttribute('disabled', '');
@@ -115,6 +133,13 @@ export class UIColorInput extends UIFormElement {
     picker.setAttribute('slot', 'content');
     picker.setAttribute('format', this.format);
     picker.setAttribute('value', this.value);
+    // Set generation-constraint props directly (numeric — attribute-reflection
+    // would round-trip but properties cover NaN/Infinity correctly).
+    picker.maxChroma = this.maxChroma;
+    picker.maxL = this.maxL;
+    picker.minL = this.minL;
+    picker.hueDriftMax = this.hueDriftMax;
+    picker.baseHue = this.baseHue;
 
     popover.append(button, picker);
     this.append(popover);
@@ -162,10 +187,20 @@ export class UIColorInput extends UIFormElement {
       this.syncValue(next);
     }
     this.#syncFromValue();
+    // Forward the inner picker's parsed OKLCH channel scalars (v0.5.13 §-TBD,
+    // FB-33 §1-adjacent). Consumers writing OKLCH-native logic get the parsed
+    // {l, c, h} for free, matching <color-picker-ui>'s detail shape.
     this.dispatchEvent(new CustomEvent(kind, {
       bubbles: true,
       composed: true,
-      detail: { value: next ?? this.value, hex: detail.hex, oklch: detail.oklch },
+      detail: {
+        value: next ?? this.value,
+        hex: detail.hex,
+        oklch: detail.oklch,
+        l: detail.l,
+        c: detail.c,
+        h: detail.h,
+      },
     }));
   }
 

package/components/color-input/color-input.a2ui.json

@@ -13,6 +13,11 @@
     }
   ],
   "properties": {
+    "baseHue": {
+      "description": "Reference hue (degrees) for the hueDriftMax constraint, forwarded to inner picker. Default NaN — picker falls back to its hue at first commit.",
+      "type": "number",
+      "default": "NaN"
+    },
     "component": {
       "const": "ColorInput"
     },
@@ -30,6 +35,26 @@
       ],
       "default": "hex"
     },
+    "hueDriftMax": {
+      "description": "Generation constraint forwarded to inner picker — maximum allowed signed-shortest-path hue deviation (degrees) from baseHue. Default NaN (no constraint).",
+      "type": "number",
+      "default": "NaN"
+    },
+    "maxChroma": {
+      "description": "Generation constraint forwarded to the inner `<color-picker-ui>` (v0.5.13\n§-TBD, FB-33 §1). Clamp the OKLCH chroma channel to at most this value.\nDefault Infinity (no constraint).\n",
+      "type": "number",
+      "default": "Infinity"
+    },
+    "maxL": {
+      "description": "Generation constraint forwarded to inner picker — clamp OKLCH lightness to at most this value (0..1). Default 1.",
+      "type": "number",
+      "default": 1
+    },
+    "minL": {
+      "description": "Generation constraint forwarded to inner picker — clamp OKLCH lightness to at least this value (0..1). Default 0.",
+      "type": "number",
+      "default": 0
+    },
     "name": {
       "description": "Form field name.",
       "type": "string",
@@ -77,10 +102,22 @@
       "change": {
         "description": "Fired when the color is committed (pointerup / Enter / picker close). Bubbles from inner picker.",
         "detail": {
+          "c": {
+            "description": "Parsed OKLCH chroma scalar.",
+            "type": "number"
+          },
+          "h": {
+            "description": "Parsed OKLCH hue scalar (degrees, NaN ok for achromatic).",
+            "type": "number"
+          },
           "hex": {
             "description": "Hex form (`#rrggbb`).",
             "type": "string"
           },
+          "l": {
+            "description": "Parsed OKLCH lightness scalar (0..1). v0.5.13 §-TBD (FB-33 §1-adjacent).",
+            "type": "number"
+          },
           "oklch": {
             "description": "OKLCH string (`oklch(L C H)`).",
             "type": "string"
@@ -94,9 +131,18 @@
       "input": {
         "description": "Fired during continuous drag of the inner picker. Bubbles from inner picker.",
         "detail": {
+          "c": {
+            "type": "number"
+          },
+          "h": {
+            "type": "number"
+          },
           "hex": {
             "type": "string"
           },
+          "l": {
+            "type": "number"
+          },
           "oklch": {
             "type": "string"
           },

package/components/color-input/color-input.d.ts

@@ -38,6 +38,12 @@ export interface ColorInputChangeEventDetail {
   hex: string;
   /** OKLCH string (`oklch(L C H)`, fixed precision). */
   oklch: string;
+  /** Parsed OKLCH lightness (0..1). v0.5.13 §-TBD (FB-33 §1-adjacent). */
+  l: number;
+  /** Parsed OKLCH chroma. */
+  c: number;
+  /** Parsed OKLCH hue (degrees, NaN ok for achromatic). */
+  h: number;
 }
 export type ColorInputChangeEvent = CustomEvent<ColorInputChangeEventDetail>;
 export type ColorInputInputEvent = CustomEvent<ColorInputChangeEventDetail>;
@@ -55,6 +61,16 @@ export class UIColorInput extends UIFormElement {
   placement: 'top' | 'bottom' | 'left' | 'right' | 'top-start' | 'top-end' | 'bottom-start' | 'bottom-end';
   /** Reflects the inner popover's open state. Set programmatically to open/close without a click. */
   open: boolean;
+  /** Generation constraint forwarded to inner picker: clamp OKLCH chroma to at most this value. `Infinity` = unconstrained. v0.5.13 §-TBD (FB-33 §1). */
+  maxChroma: number;
+  /** Generation constraint forwarded to inner picker: clamp OKLCH lightness to at most this value (0..1). `1` = unconstrained. */
+  maxL: number;
+  /** Generation constraint forwarded to inner picker: clamp OKLCH lightness to at least this value (0..1). `0` = unconstrained. */
+  minL: number;
+  /** Generation constraint forwarded to inner picker: maximum allowed signed-shortest-path hue drift in degrees from `baseHue`. `NaN` = unconstrained. */
+  hueDriftMax: number;
+  /** Reference hue (degrees) for `hueDriftMax`, forwarded to inner picker. `NaN` = picker falls back to its hue at first commit. */
+  baseHue: number;
 
   /** Open the picker programmatically. */
   showPicker(): void;

package/components/color-input/color-input.yaml

@@ -61,6 +61,34 @@ props:
     type: boolean
     default: false
     reflect: true
+  maxChroma:
+    description: |
+      Generation constraint forwarded to the inner `<color-picker-ui>` (v0.5.13
+      §-TBD, FB-33 §1). Clamp the OKLCH chroma channel to at most this value.
+      Default Infinity (no constraint).
+    type: number
+    default: Infinity
+    reflect: true
+  maxL:
+    description: Generation constraint forwarded to inner picker — clamp OKLCH lightness to at most this value (0..1). Default 1.
+    type: number
+    default: 1
+    reflect: true
+  minL:
+    description: Generation constraint forwarded to inner picker — clamp OKLCH lightness to at least this value (0..1). Default 0.
+    type: number
+    default: 0
+    reflect: true
+  hueDriftMax:
+    description: Generation constraint forwarded to inner picker — maximum allowed signed-shortest-path hue deviation (degrees) from baseHue. Default NaN (no constraint).
+    type: number
+    default: NaN
+    reflect: true
+  baseHue:
+    description: Reference hue (degrees) for the hueDriftMax constraint, forwarded to inner picker. Default NaN — picker falls back to its hue at first commit.
+    type: number
+    default: NaN
+    reflect: true
 events:
   change:
     description: Fired when the color is committed (pointerup / Enter / picker close). Bubbles from inner picker.
@@ -74,6 +102,15 @@ events:
       oklch:
         type: string
         description: OKLCH string (`oklch(L C H)`).
+      l:
+        type: number
+        description: Parsed OKLCH lightness scalar (0..1). v0.5.13 §-TBD (FB-33 §1-adjacent).
+      c:
+        type: number
+        description: Parsed OKLCH chroma scalar.
+      h:
+        type: number
+        description: Parsed OKLCH hue scalar (degrees, NaN ok for achromatic).
   input:
     description: Fired during continuous drag of the inner picker. Bubbles from inner picker.
     detail:
@@ -84,6 +121,12 @@ events:
         type: string
       oklch:
         type: string
+      l:
+        type: number
+      c:
+        type: number
+      h:
+        type: number
 slots: {}
 states:
   - name: idle

package/components/heatmap/class.js

@@ -86,6 +86,10 @@ export class UIHeatmap extends UIElement {
     this.removeEventListener('pointerleave', this.#onLeave);
     this.removeEventListener('click', this.#onClick);
     this.#bound = false;
+    if (this.#raf != null) {
+      cancelAnimationFrame(this.#raf);
+      this.#raf = null;
+    }
   }
 
   #raf = null;

package/components/input/input.css

@@ -37,9 +37,9 @@ input-ui:not([disabled]) [slot="field"]:hover [slot="suffix"] {
 
     /* ── State: hover/focus ── */
     --input-bg-hover:        var(--a-ui-bg-hover);
-    --input-fg-hover:        var(--a-fg);
-    --input-affix-fg-hover:  var(--a-fg-subtle);
-    --input-fg-focus:        var(--a-fg-strong);
+    --input-fg-hover:        var(--a-ui-text-hover);
+    --input-affix-fg-hover:  var(--a-ui-text-subtle);
+    --input-fg-focus:        var(--a-ui-text-active);
 
     /* ── State: disabled ── */
     --input-bg-disabled:     var(--a-ui-bg-disabled);

package/components/menu/menu.css

@@ -93,10 +93,10 @@ menu-item-ui[variant="danger"]:hover [slot="icon"] {
     --menu-item-fg:             var(--a-fg-subtle);
     --menu-item-fg-hover:       var(--a-fg);
     --menu-item-bg-hover:       var(--a-bg-muted);
-    --menu-item-fg-disabled:    var(--a-fg-disabled);
+    --menu-item-fg-disabled:    var(--a-ui-text-disabled);
     --menu-item-icon-fg:        var(--a-fg-muted);
     --menu-item-icon-fg-hover:  var(--a-fg);
-    --menu-item-icon-disabled:  var(--a-fg-disabled);
+    --menu-item-icon-disabled:  var(--a-ui-text-disabled);
     --menu-item-danger-fg:      var(--a-danger-bg);
     --menu-item-danger-bg:      var(--a-danger-muted);
 

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

@@ -222,7 +222,7 @@ nav-group-ui [slot="popover"] {
 nav-group-ui [slot="popover-label"] {
   padding: var(--a-space-1) var(--a-space-2);
   font-weight: var(--a-weight-medium);
-  color: var(--a-fg-muted);
+  color: var(--nav-group-fg-muted);
   font-size: var(--a-ui-tiny);
   text-transform: uppercase;
   letter-spacing: 0.06em;
@@ -231,7 +231,7 @@ nav-group-ui [slot="popover-label"] {
 nav-group-ui [slot="popover"] [role="option"] {
   padding: var(--a-space-1) var(--a-space-2);
   border-radius: var(--a-radius);
-  color: var(--a-fg-subtle);
+  color: var(--nav-group-fg-muted);
   cursor: pointer;
   white-space: nowrap;
   transition:
@@ -241,7 +241,7 @@ nav-group-ui [slot="popover"] [role="option"] {
 
 nav-group-ui [slot="popover"] [role="option"]:hover {
   background: var(--a-bg-hover);
-  color: var(--a-fg-strong);
+  color: var(--nav-group-fg-hover);
 }
 
 /* Selected / current option — mirrors the main rail's nav-item selection:
@@ -250,7 +250,7 @@ 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);
-  color: var(--a-fg-strong);
+  color: var(--nav-group-fg-selected);
   font-weight: var(--a-weight-medium);
 }
 
@@ -283,7 +283,7 @@ nav-ui[variant="section"] > nav-group-ui:not([variant]) > [slot="header"] {
   padding: var(--a-space-3) var(--a-space-2) var(--a-space-1);
   font-size: var(--a-kicker-sm, var(--a-ui-tiny));
   font-weight: var(--a-weight-medium);
-  color: var(--a-fg-muted);
+  color: var(--nav-group-fg-muted);
   text-transform: uppercase;
   letter-spacing: 0.06em;
   cursor: default;
@@ -295,7 +295,7 @@ nav-group-ui[variant="section"] > [slot="header"]:focus-visible,
 nav-ui[variant="section"] > nav-group-ui:not([variant]) > [slot="header"]:hover,
 nav-ui[variant="section"] > nav-group-ui:not([variant]) > [slot="header"]:focus-visible {
   background: transparent;
-  color: var(--a-fg-muted);
+  color: var(--nav-group-fg-muted);
 }
 
 nav-group-ui[variant="section"] > [slot="header"] [slot="caret"],

package/components/option-card/option-card.css

@@ -101,7 +101,8 @@ option-card-ui[checked] > [slot="icon"] {
     outline: none;
     transition:
       background var(--option-card-duration) var(--option-card-easing),
-      border-color var(--option-card-duration) var(--option-card-easing);
+      border-color var(--option-card-duration) var(--option-card-easing),
+      box-shadow var(--option-card-duration) var(--option-card-easing);
   }
 
   /* When an icon slot is present, insert a third column for it

package/components/otp-input/class.js

@@ -18,7 +18,7 @@
  * Each digit gets its own input — auto-advances on entry,
  * backs up on delete, distributes pasted values.
  *
- * Events: 'complete' (detail: {value}), 'input'
+ * Events: 'complete' (detail: {value}), 'input' (detail: {value}), 'change' (detail: {value})
  */
 
 import { UIFormElement } from '../../core/form.js';
@@ -107,6 +107,7 @@ export class UIOtpInput extends UIFormElement {
 
     this.#syncCombined();
     this.dispatchEvent(new CustomEvent('input', { bubbles: true, detail: { value: this.value } }));
+    this.dispatchEvent(new CustomEvent('change', { bubbles: true, detail: { value: this.value } }));
 
     if (input.value && index < this.#inputs.length - 1) {
       this.#inputs[index + 1].focus();
@@ -121,6 +122,7 @@ export class UIOtpInput extends UIFormElement {
       this.#inputs[index - 1].value = '';
       this.#syncCombined();
       this.dispatchEvent(new CustomEvent('input', { bubbles: true, detail: { value: this.value } }));
+    this.dispatchEvent(new CustomEvent('change', { bubbles: true, detail: { value: this.value } }));
     }
   }
 
@@ -132,6 +134,7 @@ export class UIOtpInput extends UIFormElement {
     }
     this.#syncCombined();
     this.dispatchEvent(new CustomEvent('input', { bubbles: true, detail: { value: this.value } }));
+    this.dispatchEvent(new CustomEvent('change', { bubbles: true, detail: { value: this.value } }));
 
     // Focus last filled or first empty
     const firstEmpty = this.#inputs.findIndex(inp => !inp.value);

package/components/otp-input/otp-input.a2ui.json

@@ -46,6 +46,15 @@
     "category": "input",
     "composes": [],
     "events": {
+      "change": {
+        "description": "Fired alongside `input` on every digit change. Provides form-bearing-primitive event-shape parity (every UIFormElement emits `change` with `detail.value`).",
+        "detail": {
+          "value": {
+            "description": "Combined digits at the moment of the change.",
+            "type": "string"
+          }
+        }
+      },
       "complete": {
         "description": "Fired exactly once when the user fills the last digit slot. detail.value is the combined string.",
         "detail": {

package/components/otp-input/otp-input.d.ts

@@ -11,6 +11,8 @@ export interface OtpInputEventDetail {
   value: string;
 }
 export type OtpInputEvent = CustomEvent<OtpInputEventDetail>;
+export type OtpInputInputEvent = CustomEvent<OtpInputEventDetail>;
+export type OtpInputChangeEvent = CustomEvent<OtpInputEventDetail>;
 
 /**
  * Detail payload for the `complete` event — fired exactly once when the
@@ -32,5 +34,6 @@ export class UIOtpInput extends UIFormElement {
     options?: boolean | AddEventListenerOptions,
   ): void;
   addEventListener(type: 'input', listener: (ev: OtpInputEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'change', listener: (ev: OtpInputEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
   addEventListener(type: 'complete', listener: (ev: OtpInputCompleteEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }

package/components/otp-input/otp-input.yaml

@@ -36,6 +36,12 @@ events:
       value:
         type: string
         description: Combined digits at the moment of the change.
+  change:
+    description: Fired alongside `input` on every digit change. Provides form-bearing-primitive event-shape parity (every UIFormElement emits `change` with `detail.value`).
+    detail:
+      value:
+        type: string
+        description: Combined digits at the moment of the change.
 slots:
   field:
     description: Container for the digit input boxes and optional separator

package/components/pagination/pagination.css

@@ -70,7 +70,9 @@
     line-height: 1;
     transition:
       background var(--pagination-duration) var(--pagination-easing),
-      color var(--pagination-duration) var(--pagination-easing);
+      border-color var(--pagination-duration) var(--pagination-easing),
+      color var(--pagination-duration) var(--pagination-easing),
+      box-shadow var(--pagination-duration) var(--pagination-easing);
   }
 
   [slot="nav"] button:not([disabled]):hover {

package/components/radio/radio.css

@@ -39,7 +39,7 @@ radio-ui[checked] [slot="dot"]::after {
     --radio-bg-checked-hover: var(--a-primary-hover);
 
     /* ── State: disabled ── */
-    --radio-fg-disabled:      var(--a-fg-muted);
+    --radio-fg-disabled:      var(--a-ui-text-disabled);
 
     /* ── State: focus ── */
     --radio-focus-ring:       var(--a-focus-ring);

package/components/search/class.js

@@ -76,6 +76,7 @@ export class UISearch extends UIFormElement {
     this.value = this.#inputEl.value;
     this.syncValue(this.value);
     this.dispatchEvent(new CustomEvent('input', { bubbles: true, detail: { value: this.value } }));
+    this.dispatchEvent(new CustomEvent('change', { bubbles: true, detail: { value: this.value } }));
 
     clearTimeout(this.#timer);
     this.#timer = setTimeout(() => {
@@ -106,6 +107,7 @@ export class UISearch extends UIFormElement {
     this.syncValue('');
     this.setAttribute('value', '');
     this.dispatchEvent(new CustomEvent('input', { bubbles: true, detail: { value: this.value } }));
+    this.dispatchEvent(new CustomEvent('change', { bubbles: true, detail: { value: this.value } }));
     this.dispatchEvent(new CustomEvent('search', {
       bubbles: true,
       detail: { value: '' },

package/components/search/search.a2ui.json

@@ -56,6 +56,15 @@
     "category": "input",
     "composes": [],
     "events": {
+      "change": {
+        "description": "Fired alongside `input` on every keystroke + on clear. Provides form-bearing-primitive event-shape parity (every UIFormElement emits `change` with `detail.value`).",
+        "detail": {
+          "value": {
+            "description": "Current search-input value.",
+            "type": "string"
+          }
+        }
+      },
       "clear": {
         "description": "Fired when the clear button is clicked"
       },

package/components/search/search.d.ts

@@ -10,6 +10,7 @@ export interface SearchInputEventDetail {
   value: string;
 }
 export type SearchInputEvent = CustomEvent<SearchInputEventDetail>;
+export type SearchChangeEvent = CustomEvent<SearchInputEventDetail>;
 
 export interface SearchEventDetail {
   value: string;
@@ -31,5 +32,6 @@ export class UISearch extends UIFormElement {
     options?: boolean | AddEventListenerOptions,
   ): void;
   addEventListener(type: 'input', listener: (ev: SearchInputEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'change', listener: (ev: SearchInputEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
   addEventListener(type: 'search', listener: (ev: SearchEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }

package/components/search/search.yaml

@@ -39,6 +39,12 @@ events:
     description: Fired when the clear button is clicked
   input:
     description: "Fired on each input change during typing."
+  change:
+    description: Fired alongside `input` on every keystroke + on clear. Provides form-bearing-primitive event-shape parity (every UIFormElement emits `change` with `detail.value`).
+    detail:
+      value:
+        type: string
+        description: Current search-input value.
   search:
     description: Debounced CustomEvent with detail.query containing the search string
 slots:

package/components/segment/segment.css

@@ -20,10 +20,10 @@ segment-ui[selected] {
     --segment-font-weight:     var(--a-ui-weight);
 
     /* ── Colors ── */
-    --segment-fg:              var(--a-fg-subtle);
-    --segment-fg-hover:        var(--a-fg);
+    --segment-fg:              var(--a-ui-text-subtle);
+    --segment-fg-hover:        var(--a-ui-text-hover);
     --segment-fg-selected:     var(--a-chrome-dark);
-    --segment-fg-disabled:     var(--a-fg-muted);
+    --segment-fg-disabled:     var(--a-ui-text-disabled);
 
     /* ── Transition ── */
     --segment-duration:        var(--a-duration-fast);

package/components/select/select.css

@@ -24,6 +24,7 @@
     --select-placeholder-fg:    var(--a-ui-text-placeholder);
     --select-caret-fg:          var(--a-ui-text-muted);
     --select-fg:                var(--a-ui-text);
+    --select-fg-hover:          var(--a-ui-text-hover);
     --select-fg-selected:       var(--a-ui-text-selected);
     --select-fg-subtle:         var(--a-ui-text-subtle);
     --select-fg-muted:          var(--a-ui-text-muted);
@@ -38,7 +39,7 @@
     --select-option-px:         var(--a-ui-px);
     --select-option-py:         var(--a-ui-py);
     --select-option-bg-hover:   var(--a-bg-hover);
-    --select-option-fg-active:  var(--a-fg);
+    --select-option-fg-active:  var(--a-ui-text-active);
     --select-option-fg-disabled: var(--a-ui-text-disabled);
     --select-group-label-size:  var(--a-ui-size);
   }
@@ -223,7 +224,7 @@ select-ui [role="option"] {
   padding: var(--a-space-1) var(--a-ui-px);
   border-radius: var(--a-radius-sm);
   white-space: nowrap;
-  color: var(--a-fg-subtle);
+  color: var(--select-fg-subtle);
   cursor: pointer;
   transition:
     background var(--a-duration-fast) var(--a-easing),
@@ -231,8 +232,8 @@ select-ui [role="option"] {
 }
 select-ui [role="option"]:hover,
 select-ui [role="option"][data-focused] {
-  background: var(--a-bg-hover);
-  color: var(--a-fg-hover);
+  background: var(--select-option-bg-hover);
+  color: var(--select-fg-hover);
 }
 select-ui [role="option"][aria-selected="true"] {
   color: var(--select-fg-selected);
@@ -240,7 +241,7 @@ select-ui [role="option"][aria-selected="true"] {
   font-weight: var(--a-ui-weight);
 }
 select-ui [role="option"][aria-disabled="true"] {
-  color: var(--a-fg-muted);
+  color: var(--select-option-fg-disabled);
   cursor: not-allowed;
 }
 select-ui [role="option"][aria-disabled="true"]:hover {
@@ -250,7 +251,7 @@ select-ui [role="option"][aria-disabled="true"]:hover {
 /* Option with icon */
 select-ui [role="option"] icon-ui {
   --a-icon-size: var(--a-ui-size);
-  color: var(--a-fg-muted);
+  color: var(--select-fg-muted);
   margin-inline-end: var(--a-space-1);
   vertical-align: -0.125em;
 }
@@ -282,21 +283,21 @@ select-ui [data-menu-header] img {
 select-ui [data-menu-header] strong {
   display: block;
   font-weight: var(--a-weight-medium);
-  color: var(--a-fg);
+  color: var(--select-fg);
   font-size: var(--a-ui-size);
 }
 
 select-ui [data-menu-header] span {
   display: block;
   font-size: var(--a-ui-sm);
-  color: var(--a-fg-muted);
+  color: var(--select-fg-muted);
 }
 
 select-ui [role="group"] [slot="group-label"] {
   padding: var(--a-space-1) var(--a-ui-px);
   font-size: var(--a-ui-tiny);
   font-weight: var(--a-ui-weight);
-  color: var(--a-fg-muted);
+  color: var(--select-fg-muted);
   text-transform: uppercase;
   letter-spacing: 0.05em;
   white-space: nowrap;

package/components/swatch/class.js

@@ -212,8 +212,20 @@ export class UISwatch extends UIElement {
 
   #stamp() {
     if (this.#stamped) return;
+
+    // v0.5.13 §-TBD (FB-34 §1) — `[slot="chrome"]` children are sibling-of-tile
+    // chrome (gamut badges, override/tracked dots, custom indicators) that must
+    // survive stamping as direct host siblings, NOT funnel into #labelEl where
+    // absolute-positioning anchors against the label text bbox. Pull them out
+    // FIRST so the innerHTML='' wipe below doesn't lose them.
+    const chromeSlot = Array.from(this.children).filter(
+      n => n.getAttribute && n.getAttribute('slot') === 'chrome'
+    );
+    for (const n of chromeSlot) n.remove();
+
     // 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.
     const slotted = Array.from(this.childNodes).filter(n =>
       !(n.nodeType === 1 && n.dataset && (
         n.dataset.tile !== undefined ||
@@ -230,6 +242,14 @@ export class UISwatch extends UIElement {
     this.#tileEl.setAttribute('aria-hidden', 'true');
     this.appendChild(this.#tileEl);
 
+    // Chrome-slot children re-attach IMMEDIATELY after the tile so they can
+    // position absolutely against the host (host carries position: relative
+    // when shape="block" + label-position="overlay" per swatch.css). Keeping
+    // them sibling-of-tile (not descendant-of-tile) lets consumer CSS use
+    // `position: absolute; top: 2px; right: 2px` and anchor against the host's
+    // padding-box, which matches the tile's geometry in the block layout.
+    for (const n of chromeSlot) this.appendChild(n);
+
     // Badge container — holds one or more <span data-badge-variant="..."> children.
     // Multi-badge support added in v0.4.9 §92 (FEEDBACK-04 follow-up).
     this.#badgeEl = document.createElement('span');

package/components/swatch/swatch.a2ui.json

@@ -149,7 +149,10 @@
     ],
     "slots": {
       "default": {
-        "description": "Optional rich label content. When present, replaces the [label] attribute's text."
+        "description": "Optional rich label content. When present, replaces the [label]\nattribute's text. Consumer chrome positioned absolutely against the\nswatch tile should use `[slot=\"chrome\"]` instead — default-slot\nchildren are funneled into the label region.\n"
+      },
+      "chrome": {
+        "description": "§-TBD (v0.5.13, FB-34 §1). Sibling-of-tile chrome — gamut badges,\noverride/tracked dots, custom indicators — that survives stamping as\na direct host sibling rather than being funneled into the label. Pair\nwith consumer-authored CSS `position: absolute` against the host\n(the host carries `position: relative` when `shape=\"block\"`, so\n`top/right/bottom/left` offsets anchor to the tile's geometry).\nCloses the C1.3 dogfood chrome-overlay composition gap.\n"
       }
     },
     "states": [

package/components/swatch/swatch.yaml

@@ -119,7 +119,20 @@ events:
         description: The [label] attribute value.
 slots:
   default:
-    description: Optional rich label content. When present, replaces the [label] attribute's text.
+    description: |
+      Optional rich label content. When present, replaces the [label]
+      attribute's text. Consumer chrome positioned absolutely against the
+      swatch tile should use `[slot="chrome"]` instead — default-slot
+      children are funneled into the label region.
+  chrome:
+    description: |
+      §-TBD (v0.5.13, FB-34 §1). Sibling-of-tile chrome — gamut badges,
+      override/tracked dots, custom indicators — that survives stamping as
+      a direct host sibling rather than being funneled into the label. Pair
+      with consumer-authored CSS `position: absolute` against the host
+      (the host carries `position: relative` when `shape="block"`, so
+      `top/right/bottom/left` offsets anchor to the tile's geometry).
+      Closes the C1.3 dogfood chrome-overlay composition gap.
 states:
   - name: idle
     description: Default, ready for display.

package/components/switch/switch.css

@@ -59,7 +59,7 @@ switch-ui[checked] [slot="thumb"] {
     --switch-thumb-travel:         calc(var(--switch-track-width) - var(--switch-thumb-size) - 2 * var(--switch-thumb-inset) - 2px);
 
     /* ── State: disabled ── */
-    --switch-fg-disabled:          var(--a-fg-muted);
+    --switch-fg-disabled:          var(--a-ui-text-disabled);
   }
 
   :scope {

package/components/tabs/tabs.css

@@ -13,7 +13,7 @@
     --tabs-fg:              var(--a-fg-subtle);
     --tabs-fg-hover:        var(--a-fg);
     --tabs-fg-active:       var(--a-fg-selected);
-    --tabs-fg-disabled:     var(--a-fg-muted);
+    --tabs-fg-disabled:     var(--a-ui-text-disabled);
 
     /* ── Spacing ── */
     --tabs-vertical-gap:    var(--a-space-4);

package/components/textarea/textarea.css

@@ -32,7 +32,7 @@ textarea-ui:not([disabled]) [slot="text"]:hover {
 
     /* ── State ── */
     --textarea-bg-hover:        var(--a-ui-bg-hover);
-    --textarea-fg-hover:        var(--a-fg);
+    --textarea-fg-hover:        var(--a-ui-text-hover);
     --textarea-label-fg-focus:  var(--a-fg-subtle);
     --textarea-bg-disabled:     var(--a-ui-bg-disabled);
     --textarea-fg-disabled:     var(--a-ui-text-disabled);
@@ -73,7 +73,11 @@ textarea-ui:not([disabled]) [slot="text"]:hover {
     overflow-y: auto;
     cursor: text;
     outline: none;
-    transition: border-color var(--textarea-duration) var(--textarea-easing);
+    transition:
+      background   var(--textarea-duration) var(--textarea-easing),
+      border-color var(--textarea-duration) var(--textarea-easing),
+      color        var(--textarea-duration) var(--textarea-easing),
+      box-shadow   var(--textarea-duration) var(--textarea-easing);
   }
   /* hover rule moved outside @scope — see Safari 17.x bug note at top. */
   :scope:not([disabled]) [slot="text"]:focus {

package/components/upload/upload.css

@@ -64,7 +64,8 @@
     transition:
       border-color var(--upload-duration) var(--upload-easing),
       background var(--upload-duration) var(--upload-easing),
-      color var(--upload-duration) var(--upload-easing);
+      color var(--upload-duration) var(--upload-easing),
+      box-shadow var(--upload-duration) var(--upload-easing);
   }
   [data-dropzone]:hover {
     border-color: var(--upload-border-hover);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adia-ai/web-components",
-  "version": "0.5.12",
+  "version": "0.5.14",
   "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",
@@ -23,6 +23,14 @@
       "types": "./components/*/*.d.ts",
       "default": "./components/*/*.js"
     },
+    "./components/stat": {
+      "types": "./components/stat/stat-ui.d.ts",
+      "default": "./components/stat/stat-ui.js"
+    },
+    "./components/stat/stat-ui.js": {
+      "types": "./components/stat/stat-ui.d.ts",
+      "default": "./components/stat/stat-ui.js"
+    },
     "./components/*/class": {
       "types": "./components/*/*.d.ts",
       "default": "./components/*/class.js"

package/styles/typography.css

@@ -584,7 +584,7 @@
 
 /* ── Mark — system highlight tokens ── */
 :where(mark) {
-  background: var(--a-highlight-default);
+  background: var(--a-highlight);
   color: var(--a-highlight-text);
   padding-inline: 0.125em;
   border-radius: 0.125em;