@adia-ai/web-components 0.8.22 → 0.8.24

package/CHANGELOG.md

@@ -1,5 +1,64 @@
 # Changelog — @adia-ai/web-components
 
+## [0.8.24] — 2026-07-30
+
+### Fixed
+- **`list-item-ui` two-line items center the leading glyph on the whole item** (gh#558, operator screenshot). The icon was pinned to the title row, hanging 9–18px above the item center on title+description rows — Material's two-line convention centers it. Explicit `grid-row: 1 / span 2` scoped by `:has([slot="description"])` (with no `grid-template-rows` the explicit grid has zero rows, so the old `1 / -1` collapsed to one row — the reason the earlier anatomy comment called them "identical"); single-line items untouched (probe: two-line offset 0/0/0, single-line 24px rows unchanged).
+- **`card-ui` pins a direct `<footer>` to the card bottom** (gh#559, operator screenshot). In an equal-height grid row, a shorter card's CTA floated at content end (Free tier 42px above the edge vs 17px on its siblings) — the buttons were already in footers; the card just had no pinning rule. `:has(> footer)` promotes the card to a flex column with `margin-top: auto` on the footer; footerless cards keep block flow. Probe: 17/17/17.
+- **`requiredIcons` drift cleared across 16 components** (gh#550). Eight primitives that auto-stamp icons (alert/drawer/feed/modal `x`, input steppers `caret-up`/`caret-down`, nav-group `caret-right`, swiper `caret-left`/`caret-right`, toolbar overflow `dots-three`) now declare `static requiredIcons`, mirrored in their yaml SoTs (calendar-grid and pagination gained the missing yaml blocks); four stale declarations pruned (combobox `check`, date-range-picker `arrow-right`, datetime-picker `clock`, select `magnifying-glass` — none ever stamped) and agent-questions' leftover yaml block removed (options render via option-card-ui since gh#276). Checker itself hardened: `//` line comments no longer read as stamp sites (button `plus` false positive) and yaml list entries may carry trailing `#` comments (select's three phantom mismatches). 125/125 components clean.
+- **`toolbar-ui` overflow measurement traps closed** (gh#528). (1) Flex-grow children (spacers, stretched groups) measured at their EXPANDED width, so the row always read "full" and the last action spilled unrecoverably — grow is zeroed for the read and restored. (2) A `display:none` mount committed a spill from a 0-width reading and stranded the bar collapsed — a zero-width guard now leaves everything visible until the ResizeObserver delivers a real size. Browser-verified both ways.
+- **Corpus/demo enum drift swept** (gh#529): 41 uses of never-implemented values (Tag `muted`/`primary`, Text `primary`/`muted`/`xxl`, Card `soft`/`primary`, Badge `subtle`, Chart `muted`, Button `danger`) mapped to their nearest real values across 15 harvest sources — they silently rendered as defaults. `verify:corpus` warnings 138 → 97.
+- **10 standalone example routes actually render** (gh#530): the sitemap pointed iframe-served routes at headless `.contents.html` fragments; thin standalone wrappers added (single-source fetch-inject), annotations repointed, `frame`/`theme-provider` demos wired for phosphor. 108/108 clean. The `check-required-icons` checker also now reads `<comp>.class.js` and all stamp shapes — 20 false positives gone, 19 real findings exposed → gh#550.
+
+### Maintenance
+- **`dist/` bundles rebuilt** in this cut's window (4 file(s)) — regenerated from the source changes described above, not independent edits.
+- **`patterns/` touched in this release window** (7 file(s), e.g. `admin-keys-and-export/admin-keys-and-export.examples.html`) — carried by the entries above.
+
+## [0.8.23] — 2026-07-30
+
+### Removed
+- **BREAKING — the `--a-font` back-compat alias** (operator ruling 2026-07-30; ships in **0.8.23** as an operator-ruled PATCH exception to the removals-are-MINOR convention). The pre-ADR-0035 name is gone from `type/scale.css`; surviving `var(--a-font)` references resolve to UA serif. Consumer sweep is mechanical (`var(--a-font)` → `var(--a-font-family)`); `audit-font-family-floor` Check B and the plugin lint hooks flag any stragglers. MIGRATION GUIDE §v0.8.23.
+
+### Fixed
+- **`richtext-ui` lists inherit the body font spec** (gh#546, operator chat screenshot). `p` was pinned to `--richtext-body-size` while `ul`/`li` carried no font rule and inherited the HOST page's larger base — chat-rendered bullet items read bigger than the paragraph beside them. The body size + leading now sit once on `[data-richtext-body]` and everything inherits (headings/code still override). Probe: p and li both 14px inside an 18px host.
+- **Deployed-site freeze class eliminated** (gh#534, operator repro + live-browser diagnosis). Cold loads of the deployed site could stall the ~250-file raw module graph on one hung fetch, leaving the page as un-upgraded markup — visible, scrollable, zero interactivity, no error. Two-part fix: (1) on https (or `?force-bundle`) the prebuilt everything-bundle loads in PARALLEL with the module graph, so element registration rides one request; every registration is now `defineIfFree` (22 bare `customElements.define` calls guarded across components + modules — the parallel load surfaced each collision); (2) an 8s registration watchdog surfaces a plain-DOM reload prompt instead of an indefinite freeze. Probe-verified: three heavy routes clean under bundle+graph with zero collisions, dev path untouched, and a stalled-graph negative control trips the banner.
+- **A2UI runtime registry gains `ToolbarGroup → toolbar-group-ui`** (gh#535, operator screenshot). The missing entry made toolbar-group an unknown tag, so the docs transpiler Column-wrapped every toolbar group — the floating bulk-action bar rendered as vertical col-ui stacks on its site route. Rows regenerated; surface-verified warm (groups render, bars 67–75px, main thread responsive — the earlier freeze signal was cold-Vite first-compile noise, not a loop).
+- **`table-ui` perimeter is three-sided — no top edge** (gh#537, operator report). A line above the header read as a stray divider under a card edge or empty-state; the header row's own border-bottom is the table's top structure. Sides + bottom keep the standalone silhouette; `[frameless]` unchanged.
+- **`select-ui [searchable]` matches underscores as spaces** (gh#538) — typing "Los Angeles" now finds `America/Los_Angeles`; the timezone-selector pattern also displays humanized (de-underscored) labels while values keep exact IANA ids.
+- **`approvals` pattern: priority tag leads the request context** (gh#539, operator ruling) — the High tag moves from the trailing action cluster to the front of the requester/department/age line; trailing cluster is Reject · Approve only.
+- **`list-item-ui` iconless items no longer indent behind a ghost grid track** (gh#524, operator devtools screenshot). The `auto 1fr` grid charged its `column-gap` beside the empty leading track. The gap now rides the icon's own `margin-inline-end` (and the action's `margin-inline-start`); empty stamped icon spans hide. Surface-verified: Playwright measurement on /site/patterns/search-discovery — text indent 0 on iconless rows.
+- **`select-ui [mark]` implies the no-radio menu treatment** (gh#498 REOPENED — the first fix applied `[no-radio]` to the playground switcher and closed green while the site chrome switcher kept its radios; operator caught it same-day). A mark declares an identity switcher, so the semantic attribute now carries the treatment; `[no-radio]` remains for markless menus. Surface-verified this time: Playwright probe of the site chrome `#workspace-select` — 2 rows, 0 radio indicators. Tests 38 → 39.
+- **Nav selection icon color is one language** (gh#522, operator ruling). A nav-group containing the selected route filled its header glyph (gh#501) in plain label color — reading as unselected beside nav-item's primary accent glyph. The contains-selection state now reflects as `[data-selected-within]` (set by the gh#501 sync, observer-safe), and the header icon paints `--nav-group-icon-fg-selected` (default `--md-sys-color-primary`, one token language with `--nav-item-accent`) whenever the group is selected or contains the selection. Sub-items keep their own accent-bar system. Tests 9 → 10.
+- **`patterns/wizard-drawer` works on the site route** (gh#506, operator report). The open/cancel affordances were inline `onclick` handlers, which the site's A2UI render path does not execute — the drawer could never open on /site/patterns/wizard-drawer, so the whole three-step use case was dead there. All interactivity now lives in the pattern's `examples.js` setup module (which the route does run); verified end-to-end in a real browser: trigger opens → Next/Back swap panels with the stepper → Create closes.
+- **`tag-ui` no longer top-pins in table cells** (gh#503, adia-v2 report — measured −34px off-center). The TKT-0021 guard `align-self: start` acted on the PARENT's cross axis: correct in a col-ui stack, but vertical in every flex-row parent (table cells, row-ui, toolbars). Re-cut as `width: fit-content` — defeats column-stretch identically (stretch applies only at auto cross size), while row parents' `align-items: center` regains vertical control. Tag-only; badge/button never carried the rule.
+- **`alert-ui` variant icons clear legibility on their own tinted surface** (gh#507, operator screenshot). Icon fg moves from `--a-<family>-strong` (an on-SURFACE color, near-invisible against the family's dark-scheme container tint) to the gh#434 gate-proven `--md-sys-color-<family>-on-<family>-container` role (dark leg measured 5.6–9.2:1).
+
+- **`nav-group-ui` header glyph fills when a CHILD is selected** (gh#501, operator report). gh#459 ruled "the group CONTAINING the selected route fills" but relied on consumers setting `[selected]` on the group; a MutationObserver (subtree, `[selected]` filter + childList) now makes it self-enforcing — targeted weight sync only, since a full re-render from the observer would loop on its own textContent writes. Symmetric disconnect. Tests 7 → 9.
+- **`progress-row-ui` authored `[slot="meta"]` content survives render** (gh#502). `render()` unconditionally wrote `textContent` from the `[meta]` attr and hid the element when the attr was empty, so authored meta content (text + a trailing delta badge) was wiped — the slot was effectively attr-only. The attr still owns the text when set; absent, authored children are kept and only a genuinely empty meta hides. New test file, 4 passing. The `conversion-funnel` pattern's step-over-step variant now rides its delta badges inside the meta slot instead of a sibling column misaligned against the row.
+
+### Added
+- **`table-ui [frameless]` + the `--table-perimeter` token split** (gh#511, adia-v2 console tables). The 1px perimeter and the row dividers both read `--table-border` (TKT-0026), so a card-composed table always double-bordered — the card's rounded outline plus the table's square frame — and consumers couldn't drop one without the other. The perimeter now reads its own `--table-perimeter` (default: `var(--table-border)` — standalone tables unchanged); `[frameless]` blanks just that token. Pattern rule: inside `card-ui`, set frameless — the container owns the frame. Tests 45 → 49.
+- **`patterns/bulk-action-toolbar`: a floating, bottom-anchored variant** (gh#494, operator ruling — adia-v2 evidence-console + independent kit-side report, ADIA2-7028). Long/paginated tables scroll the top-swap bar out of view exactly when a mid-scroll selection needs it; the floating variant is a card-like elevated bar (`card-ui[elevation="3"]`) that rises `position: sticky` from the bottom of the table's own scroll container — never the browser viewport — driven by `table-ui`'s existing `select` event. Anatomy: `aria-live="polite"` selection count, an optional per-flow controls slot, actions with destructive last, an explicit Clear. Composed entirely from existing primitives (`card-ui` + `toolbar-ui` + `toolbar-group-ui`) — the anchored-surface primitive filed as gh#495 was not needed. The pattern doc now states which variant to pick and why (floating default once a table runs taller than ~one viewport). The top-swap variant stays valid and unchanged in shape; fixed alongside it: a real defect where its trailing action (Delete) silently spilled into an unreachable "more" menu (a flex-grow spacer inflates `toolbar-ui`'s own overflow-width measurement) — both variants now push their action group right via `toolbar-group-ui` + `align="space-between"` instead.
+- **`table-ui [valign]` — host + per-column vertical alignment** (gh#505, adia-v2 evidence-sources/organizations console tables). Every body-cell `align-items` was unconditionally `center`, which floats single-line neighbors (dates, status chips) at a different vertical center than a tall/wrapped primary cell — no way to opt into the Gmail/Linear/Notion "top-align, shared first-line scan anchor" convention. `<table-ui valign="top">` flips body cells to `align-items: flex-start` (default stays `center` — zero behavioral change for existing consumers); `columns[].valign` (or `<col-def valign="…">`) overrides the host per column, e.g. a `valign="center"` checkbox column inside a `valign="top"` table. Header cells and the structural checkbox/expand-toggle columns always stay centered regardless — they're single-line/fixed-size by contract, immune to the new token. New `--table-valign` mode token, added to the Sanctioned Mode Attributes table (`component-token-contract.md`). Tests 31 → 45.
+- **`alert-ui` sectioned content anatomy** (gh#507) — card-ui's rhythm inside the content slot: semantic `<header>`/`<section>`/`<footer>` children of the slotted wrapper, component-owned gaps (`--alert-section-gap`, `--alert-footer-gap`), footer right-aligned with its own step of air. Free-form content is untouched (the column engages only when structural children are present). The system-banners pattern's six banners now compose this way.
+- **`select-ui [no-radio]`** (gh#498, operator report). Opt-out for the single-select radio indicator on menu-shaped switchers — workspace/user identity menus — where the trigger already shows the committed value and a per-row radio reads as redundant. Drops only the dot: rows keep `[data-single-option]` layout and `aria-selected` (trigger + selected-row weight carry the signal); no effect under `[multiple]`. Applied to the admin-shell playground's workspace switcher, the reported surface. Tests 36 → 38.
+
+### Changed
+- **Carded tables adopt `[frameless]`** (gh#500 resolution) — the 11 card-composed `table-ui` instances across six patterns drop their doubled perimeter per the gh#511 rule: inside card-ui, the container owns the frame. Standalone tables unchanged.
+- **Default radius band: 6px–14px** (operator ruling 2026-07-30). `--a-radius-min` 0.25rem → 0.375rem, `--a-radius-max` 1.25rem → 0.875rem in `foundation/radius.css` and its `scale.css` ui-md byte-copy — every `--a-radius-xs/sm/md/lg` step re-clamps into the new band kit-wide. The ui-sm/ui-lg and content registers keep their own authored bands.
+- **`drawer-ui`: a leading `stepper-ui` in the body is sticky wizard chrome** (operator ruling 2026-07-30) — pins just below the sticky header on the panel's own background, padded and bled to the body edges so panels scroll cleanly beneath; `--drawer-sticky-offset` overridable for taller headers.
+- **`stepper-ui` state system re-cut** (operator ruling 2026-07-30, with mock): completed = `primary-container` bg + `primary` glyph, transparent border; current = `primary` bg + `on-primary` glyph, transparent border; next = transparent bg, `on-surface-variant` glyph, `outline-variant` border. Labels: current `on-surface`, completed/next `on-surface-variant` (new `--stepper-item-label-fg-done` token). All existing `--stepper-*` overrides keep working — only default values moved.
+- **`field-ui` labels read at 13-14px** (operator ruling 2026-07-30): `--field-label-size` moves `--a-ui-sm` → `--a-ui-md` (12px → 13px base register; 14px in larger registers) — labels no longer read smaller than the control text beside them.
+- **`description-list-ui [layout="inline"]` collapses responsively** — the two-column property|value grid stacks under 480px instead of squeezing the value column; pairs with the wizard-drawer review step's new settings-style layout.
+- **`patterns/wizard-drawer` restructured** (operator rulings): stepper moves from header chrome to the FIRST content block (`header / content (stepper) / content / footer`); the review step swaps its stacked list for `description-list-ui layout="inline"` — the responsive two-column settings layout. Anatomy sample + rules updated; browser-probe green end-to-end.
+- **`code-ui` color tokens map directly to `--md-sys-color-*` roles** (operator ask 2026-07-30). All 25 color refs (syntax `--code-tok-*`, editor chrome, lint markers) drop the `--a-*` alias hop for the md-sys role each alias already resolved to — value-identical except `--code-tok-function`: brand has no md-sys mirror, so it moves to `--md-sys-color-tertiary-active` (the identity-adjacent family). Layout/typography/motion tokens untouched; per-instance overrides work exactly as before.
+- **`table-ui` sort carets render larger** (gh#496, operator report). The header sort indicator (`caret-up-down` idle, `arrow-up`/`arrow-down` active) moves `--a-icon-size` 0.75em → 0.95em — ~+2px at the heading's `--a-ui-xs` size, em-based so it keeps scaling with the register. `--table-sort-*` overrides untouched.
+
+### Maintenance
+- **`core/` touched in this release window** (1 file(s), e.g. `core/provider.js`) — carried by the entries above.
+- **`dist/` bundles rebuilt** in this cut's window (8 file(s)) — regenerated from the source changes described above, not independent edits.
+- **`styles/` touched in this release window** (3 file(s), e.g. `foundation/radius.css`) — carried by the entries above.
+
 ## [0.8.22] — 2026-07-29
 
 ### Fixed

package/MIGRATION.md

@@ -46,12 +46,21 @@ Version cuts and migration scope:
 
 - **`0.8.0`** — MINOR lockstep cut (2026-07-15). Internal ranges `^0.7.0` → `^0.8.0`. **BREAKING (3 items):** the Material color-token adoption — `--md-sys-color-*` (a static export) is now the color system's source of truth and public API. Removed: the 19 `--a-accent-*` back-compat aliases (→ `--a-primary-*`), the 189 raw per-family `--a-{family}-{0..6}-{tint-|shade-}scrim` primitives (→ the static `--md-sys-color-{family}-scrim-*` ladder), and the `primitives-accent.css` deep-import path (→ `primitives-primary.css`). **Behavioral:** the 8 named `[theme]` presets no longer re-color components (only brand hue + radius/density/shadow knobs still respond). See [§ v0.8.0 section below](#migrating-to-adia-aiv080-2026-07-15).
 
+- **`0.8.23`** — PATCH lockstep cut (2026-07-30; operator ruling — an operator-ruled PATCH exception to the removals-are-MINOR convention). **BREAKING (1 item):** the `--a-font` back-compat alias is removed. See [§ v0.8.23 section below](#migrating-to-adia-aiv0823-2026-07-30).
+
 - **`0.8.11`** — PATCH lockstep cut (2026-07-23). Internal ranges stay at `^0.8.0`. **BREAKING: the size model.** Every component `size` enum is now exactly `sm | md | lg`; the removed tiers (`xs`, `xl`, icon's `2xl/3xl/4xl/fill`) are served by the new ancestor **`[scale]`** context — six hand-tabled tiers (`ui-sm · ui-md · ui-lg · content-sm · content-md · content-lg`): scale picks the table, `size` picks the row. `[verse]`/`[prose]` are deprecated aliases of `ui-sm`/`content-md` (removed at v1.0). Also new: `<adia-wordmark-ui>`. See [§ v0.8.11 section below](#migrating-to-adia-aiv0811-2026-07-23).
 
 Live demos and per-component docs at [ui-kit.exe.xyz/site/](https://ui-kit.exe.xyz/site/). The `adia-ui-migration` skill (in `.agents/skills/`) automates most of the mechanical sweeps in this guide.
 
 ---
 
+## Migrating to `@adia-ai/*@v0.8.23` (2026-07-30)
+
+- **Removed: the `--a-font` alias** (pre-ADR-0035 name, DEPRECATED since the 0.8.x line). Any surviving `font-family: var(--a-font)` goes invalid-at-computed-value-time → `inherit` → UA **serif** — the visible symptom is Times-faced labels on an otherwise-correct page.
+  - **Mechanical sweep:** replace `var(--a-font)` → `var(--a-font-family)` — exact match only; `--a-font-family` / `--a-font-*` names are current API and must not be touched. The kit's own sweep used `codemod-demo-host-css.mjs --token-only`, which consumers can run against their tree.
+  - **Detection:** `audit-font-family-floor.mjs` Check B flags any `var(--a-font)` usage as CRITICAL; the forge/factory lint hooks flag it at write time.
+  - The 0.8.16 font-family floors on text-bearing primitives remain, so kit components stay sans even beside a broken host declaration — only YOUR selectors referencing the dead token regress.
+
 ## Migrating to `@adia-ai/*@v0.8.11` (2026-07-23)
 
 **PATCH lockstep cut.** Internal ranges stay at `^0.8.0`. One breaking theme: **the size model contracts to `sm | md | lg` everywhere, and an ancestor `[scale]` attribute takes over everything the extra tiers did.** `styles/scale.css` (new, opt-in like verse/prose; `dist/scale.min.css` + `dist/scale.sheet.js`) defines six explicit tiers — `ui-sm` (≡ old `[verse]`), `ui-md` (≡ base), `ui-lg`, `content-sm`, `content-md` (≡ old `[prose]`), `content-lg` — each a full hand-tabled re-declaration of the `--a-size/-inset/-gap/-radius/-icon/-caret/-toggle` families and all 13 type roles. Scale picks the table, `[size]` picks the row; an unscaled page renders byte-identically to v0.8.10.

package/components/agent-questions/agent-questions.yaml

@@ -56,8 +56,6 @@ states:
     description: Default, ready for interaction.
 traits: []
 tokens: {}
-requiredIcons:
-  - check
 a2ui:
   rules:
     - rule: 'Multi-choice clarifying-question card emitted by an agent when it needs disambiguation before proceeding.'

package/components/agent-trace/agent-trace.js

@@ -34,6 +34,7 @@
  *   trace-toggle — summary opened/closed
  */
 
+import { defineIfFree } from '../../core/register.js';
 import { UIElement } from '../../core/element.js';
 
 class UIAgentTrace extends UIElement {
@@ -220,5 +221,7 @@ function escapeAttr(s) {
   return String(s).replace(/"/g, '"');
 }
 
-customElements.define('agent-trace-ui', UIAgentTrace);
+// defineIfFree (gh#534): the prod bundle + module graph load in parallel;
+// second registration must no-op, not throw.
+defineIfFree('agent-trace-ui', UIAgentTrace);
 export { UIAgentTrace };

package/components/alert/alert.a2ui.json

@@ -179,7 +179,7 @@
         "description": "Close button. Stamped automatically when `closable` is set; the stamped element is `<button-ui slot=\"close\" icon=\"x\" variant=\"ghost\" size=\"sm\">`. Override by passing a custom `slot=\"close\"` button."
       },
       "content": {
-        "description": "Alert body. For single-line text use the `text=` attribute (alert.js stamps a `<span slot=\"content\">` automatically). For rich content with title + description, wrap in `<col-ui slot=\"content\">` — the alert root is `display: flex` row, so multiple bare children would lay out side-by-side instead of stacking."
+        "description": "Alert body. For single-line text use the `text=` attribute (alert.js stamps a `<span slot=\"content\">` automatically). For structured banners use card-ui's section rhythm INSIDE the content element (gh#507): semantic `<header>` (title), `<section>` (body), and `<footer>` (actions — right-aligned with its own step of air) children of the slotted wrapper; the component owns the gaps (`--alert-section-gap`, `--alert-footer-gap`), so spacing balances without per-banner col-ui/row-ui improvisation. Free-form content without those children lays out exactly as before."
       },
       "leading": {
         "description": "Leading icon. Stamped automatically from the `icon=` attribute; consumers can override by passing a custom `<icon-ui slot=\"leading\">`."

package/components/alert/alert.class.js

@@ -42,6 +42,11 @@ function _warnOnce(key, message) {
 }
 
 export class UIAlert extends UIElement {
+  // Phosphor icons this primitive auto-stamps (without consumer markup).
+  // Aggregated by installIconLoadersForRegistered() across all defined
+  // elements. Audited by check-required-icons.mjs.
+  static requiredIcons = ['x'];
+
   static properties = {
     text:        { type: String,  default: '', reflect: true },
     title:       { type: String,  default: '', reflect: true },

package/components/alert/alert.css

@@ -42,33 +42,38 @@
     background: var(--alert-bg);
   }
 
-  /* ── Variants ── */
+  /* ── Variants ──
+     Icon fg = the family's on-container tonal-text role (gh#507): the icon
+     sits ON the -container tint, and the gh#434 gate-proven on-container
+     stops clear AA on both legs there (dark leg measured 5.6-9.2:1). The
+     former --a-<family>-strong is an on-SURFACE color — near-invisible
+     against its own family's dark-scheme container tint. */
   :scope[variant="info"] {
     --alert-bg:      var(--md-sys-color-info-container);
     --alert-fg:      var(--md-sys-color-info-on-surface);
     --alert-border:  var(--md-sys-color-info-outline-variant);
-    --alert-icon-fg: var(--a-info-strong);
+    --alert-icon-fg: var(--md-sys-color-info-on-info-container);
   }
 
   :scope[variant="success"] {
     --alert-bg:      var(--md-sys-color-success-container);
     --alert-fg:      var(--md-sys-color-success-on-surface);
     --alert-border:  var(--md-sys-color-success-outline-variant);
-    --alert-icon-fg: var(--a-success-strong);
+    --alert-icon-fg: var(--md-sys-color-success-on-success-container);
   }
 
   :scope[variant="warning"] {
     --alert-bg:      var(--md-sys-color-warning-container);
     --alert-fg:      var(--md-sys-color-warning-on-surface);
     --alert-border:  var(--md-sys-color-warning-outline-variant);
-    --alert-icon-fg: var(--a-warning-strong);
+    --alert-icon-fg: var(--md-sys-color-warning-on-warning-container);
   }
 
   :scope[variant="danger"] {
     --alert-bg:      var(--md-sys-color-danger-container);
     --alert-fg:      var(--md-sys-color-danger-on-surface);
     --alert-border:  var(--md-sys-color-danger-outline-variant);
-    --alert-icon-fg: var(--a-danger-strong);
+    --alert-icon-fg: var(--md-sys-color-danger-on-danger-container);
   }
 
   /* `muted` and `neutral` are semantic aliases of the base — same tokens
@@ -105,6 +110,40 @@
     min-width: 0;
   }
 
+  /* ── Sectioned content (gh#507) — card-ui's header/section/footer rhythm,
+     owned by the component so banner spacing stops being per-author col-ui/
+     row-ui gap improvisation. Authors write semantic children inside the
+     content slot:
+       <div slot="content">
+         <header>…title…</header>
+         <section>…body…</section>
+         <footer><button-ui …></footer>
+       </div>
+     The wrapper columnizes only when structural children are present, so
+     existing free-form content is untouched. */
+  :scope [slot="content"]:has(> header, & > section, & > footer) {
+    display: flex;
+    flex-direction: column;
+    gap: var(--alert-section-gap, var(--a-space-1));
+  }
+  :scope [slot="content"] > header,
+  :scope [slot="content"] > section,
+  :scope [slot="content"] > footer {
+    margin: 0;
+    padding: 0;
+  }
+  :scope [slot="content"] > header {
+    font-weight: var(--a-weight-medium);
+  }
+  /* Footer = the action band: right-aligned, its own step of air above so
+     a CTA never crowds the body (the live-update banner's reported cram). */
+  :scope [slot="content"] > footer {
+    display: flex;
+    gap: var(--a-space-2);
+    justify-content: flex-end;
+    margin-top: var(--alert-footer-gap, var(--a-space-1));
+  }
+
   /* Trailing action area — optional single button or small button group.
      flex-shrink:0 keeps it from collapsing; align-self:start anchors it
      to the first text line under the `align-items:start` root.

package/components/alert/alert.yaml

@@ -140,10 +140,14 @@ slots:
   content:
     description: >-
       Alert body. For single-line text use the `text=` attribute (alert.js
-      stamps a `<span slot="content">` automatically). For rich content
-      with title + description, wrap in `<col-ui slot="content">` — the
-      alert root is `display: flex` row, so multiple bare children would
-      lay out side-by-side instead of stacking.
+      stamps a `<span slot="content">` automatically). For structured
+      banners use card-ui's section rhythm INSIDE the content element
+      (gh#507): semantic `<header>` (title), `<section>` (body), and
+      `<footer>` (actions — right-aligned with its own step of air)
+      children of the slotted wrapper; the component owns the gaps
+      (`--alert-section-gap`, `--alert-footer-gap`), so spacing balances
+      without per-banner col-ui/row-ui improvisation. Free-form content
+      without those children lays out exactly as before.
   leading:
     description: >-
       Leading icon. Stamped automatically from the `icon=` attribute;
@@ -169,6 +173,8 @@ states:
     description: Default, ready for interaction.
 traits: []
 tokens: {}
+requiredIcons:
+  - x
 a2ui:
   rules:
     - rule: 'Inline alert/banner for status messages within a content region. Severity via variant (info, success, warn, error).'

package/components/calendar-grid/calendar-grid.yaml

@@ -108,6 +108,9 @@ tokens:
   --calendar-grid-day-today-color:
     description: Accent color used for the today-indicator dot + numeral tint.
     default: var(--md-sys-color-primary)
+requiredIcons:
+  - caret-left
+  - caret-right
 a2ui:
   rules:
     - >-

package/components/canvas/canvas.js

@@ -1,3 +1,4 @@
+import { defineIfFree } from '../../core/register.js';
 import { UIElement } from '../../core/element.js';
 // NOTE: the A2UI renderer (<a2ui-root>) lives in @adia-ai/web-modules and is
 // loaded lazily + guarded inside #ensureRenderer() (kicked off from connected()).
@@ -243,4 +244,6 @@ export class UICanvas extends UIElement {
   }
 }
 
-customElements.define('canvas-ui', UICanvas);
+// defineIfFree (gh#534): the prod bundle + module graph load in parallel;
+// second registration must no-op, not throw.
+defineIfFree('canvas-ui', UICanvas);

package/components/card/card.css

@@ -68,6 +68,18 @@
     flex: 1 1 auto;
   }
 
+  /* A card with a direct footer pins it to the bottom edge (gh#559):
+     in an equal-height grid/flex row, a shorter card's CTA otherwise
+     floats at content end while its siblings' sit lower. Scoped via
+     :has(> footer) so footerless cards keep plain block flow. */
+  :scope:has(> footer) {
+    display: flex;
+    flex-direction: column;
+  }
+  :scope > footer {
+    margin-top: auto;
+  }
+
   /* ═══════ Variants — token-only overrides ═══════ */
 
   /* `outline` is a documented alias for `outlined` (yaml). */

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

@@ -1,3 +1,4 @@
+import { defineIfFree } from '../../core/register.js';
 import { UIElement } from '../../core/element.js';
 
 /**
@@ -272,6 +273,8 @@ class UIChatInput extends UIElement {
     this.#fileInput = null;
   }
 }
-customElements.define('chat-input-ui', UIChatInput);
+// defineIfFree (gh#534): the prod bundle + module graph load in parallel;
+// second registration must no-op, not throw.
+defineIfFree('chat-input-ui', UIChatInput);
 
 export { UIChatInput };

package/components/code/code.css

@@ -13,9 +13,9 @@
     --code-bg:          var(--md-sys-color-neutral-background);
     --code-fg:          var(--md-sys-color-neutral-on-surface);
     --code-border:      var(--md-sys-color-neutral-outline-variant);
-    --code-header-bg:   var(--a-bg-scrim);
-    --code-header-fg:   var(--a-fg-muted);
-    --code-copy-hover-bg: var(--a-bg-muted);
+    --code-header-bg:   var(--md-sys-color-neutral-scrim-weakest);
+    --code-header-fg:   var(--md-sys-color-neutral-on-surface-variant);
+    --code-copy-hover-bg: var(--md-sys-color-neutral-container-low);
     --code-copy-hover-fg: var(--md-sys-color-neutral-on-surface);
 
     /* ── Typography ── */
@@ -31,47 +31,50 @@
        Active only when `[language]` triggers the CM mount. Still safe
        to emit in read-only mode; unused until `.cm-editor` is in the
        DOM. See docs/specs/code-editor.md §6. */
-    --code-gutter-bg:        var(--a-bg-subtle);
-    --code-gutter-fg:        var(--a-fg-muted);
+    --code-gutter-bg:        var(--md-sys-color-neutral-surface);
+    --code-gutter-fg:        var(--md-sys-color-neutral-on-surface-variant);
     /* Transparency-mixing in oklab — Safari < 18 has an OKLCH bug where
        the transparent operand's hue resolves to 0, red-shifting the mix.
        oklab is hue-agnostic and visually identical in fixed engines. */
     --code-active-line-bg:   color-mix(in oklab, var(--md-sys-color-primary-container) 40%, transparent);
     --code-selection-bg:     color-mix(in oklab, var(--md-sys-color-primary-container) 60%, transparent);
     --code-selection-match:  color-mix(in oklab, var(--md-sys-color-primary-container) 30%, transparent);
-    --code-cursor:           var(--a-primary-strong);
+    --code-cursor:           var(--md-sys-color-primary-active);
     --code-focus-ring:       var(--a-focus-ring);
 
     /* ── Syntax highlight tokens ──
        Map Lezer/CodeMirror highlight tag names to AdiaUI semantic
-       tokens. Overridable per-instance by setting `--code-tok-*` on
+       tokens — mapped DIRECTLY to --md-sys-color-* roles (operator ask
+       2026-07-30; the --a-* alias hop removed). tok-function uses
+       tertiary-active: brand has no md-sys mirror, and tertiary is the
+       identity-adjacent md-sys family. Overridable per-instance by setting `--code-tok-*` on
        any ancestor. See docs/specs/code-editor.md §6.3 for the tag →
        class → role map. */
     --code-tok-comment:      var(--md-sys-color-neutral-on-surface-variant);
-    --code-tok-keyword:      var(--a-primary-strong);
-    --code-tok-string:       var(--a-success-strong);
-    --code-tok-number:       var(--a-info-strong);
-    --code-tok-boolean:      var(--a-info-strong);
+    --code-tok-keyword:      var(--md-sys-color-primary-active);
+    --code-tok-string:       var(--md-sys-color-success-active);
+    --code-tok-number:       var(--md-sys-color-info-active);
+    --code-tok-boolean:      var(--md-sys-color-info-active);
     --code-tok-operator:     var(--md-sys-color-neutral-on-surface);
-    --code-tok-punctuation:  var(--a-fg-muted);
-    --code-tok-function:     var(--a-brand-strong);
+    --code-tok-punctuation:  var(--md-sys-color-neutral-on-surface-variant);
+    --code-tok-function:     var(--md-sys-color-tertiary-active);
     --code-tok-variable:     var(--md-sys-color-neutral-on-surface);
-    --code-tok-type:         var(--a-warning-strong);
+    --code-tok-type:         var(--md-sys-color-warning-active);
     --code-tok-property:     var(--md-sys-color-neutral-on-surface);
-    --code-tok-tag:          var(--a-primary-strong);
-    --code-tok-attribute:    var(--a-warning-strong);
-    --code-tok-url:          var(--a-info-strong);
-    --code-tok-invalid:      var(--a-danger-strong);
+    --code-tok-tag:          var(--md-sys-color-primary-active);
+    --code-tok-attribute:    var(--md-sys-color-warning-active);
+    --code-tok-url:          var(--md-sys-color-info-active);
+    --code-tok-invalid:      var(--md-sys-color-danger-active);
 
     /* ── Lint markers (Phase 3 — editable JSON) ──
        `@codemirror/lint` paints gutter markers + diagnostic tooltips
        + inline underlines. Only fires in editable mode with a linter
        attached; read-only instances never see these selectors. */
-    --code-lint-gutter-bg:   var(--a-bg-subtle);
-    --code-lint-error:       var(--a-danger-strong);
-    --code-lint-warning:     var(--a-warning-strong);
-    --code-lint-info:        var(--a-info-strong);
-    --code-lint-tooltip-bg:  var(--a-bg-strong);  /* §230-bundle (v0.5.9): elevated panel surface. Was orphaned --a-surface-floating. */
+    --code-lint-gutter-bg:   var(--md-sys-color-neutral-surface);
+    --code-lint-error:       var(--md-sys-color-danger-active);
+    --code-lint-warning:     var(--md-sys-color-warning-active);
+    --code-lint-info:        var(--md-sys-color-info-active);
+    --code-lint-tooltip-bg:  var(--md-sys-color-neutral-surface-high);  /* §230-bundle (v0.5.9): elevated panel surface. Was orphaned --a-surface-floating. */
     --code-lint-tooltip-fg:  var(--md-sys-color-neutral-on-surface);
     --code-lint-tooltip-border: var(--md-sys-color-neutral-outline-variant);
   }
@@ -268,13 +271,13 @@
     pointer-events: none;
   }
   :scope[readonly] .cm-editor {
-    background: var(--a-bg-subtle);
+    background: var(--md-sys-color-neutral-surface);
   }
   :scope[aria-invalid="true"] {
-    border-color: var(--a-danger-strong);
+    border-color: var(--md-sys-color-danger-active);
   }
   :scope[aria-invalid="true"] .cm-focused {
-    outline: 2px solid var(--a-danger-strong);
+    outline: 2px solid var(--md-sys-color-danger-active);
     outline-offset: -1px;
   }
 

package/components/combobox/combobox.class.js

@@ -58,7 +58,7 @@ export class UICombobox extends UIFormElement {
   // base-class deprecation warning that targets inert above-field labels.
   static labelDeprecated = false;
 
-  static requiredIcons = ['caret-down', 'x-circle', 'check'];
+  static requiredIcons = ['caret-down', 'x-circle'];
 
   static properties = {
     ...UIFormElement.properties,

package/components/combobox/combobox.yaml

@@ -257,7 +257,6 @@ tokens:
 requiredIcons:
   - caret-down
   - x-circle
-  - check
 a2ui:
   rules:
     - >-

package/components/date-range-picker/date-range-picker.class.js

@@ -130,7 +130,7 @@ export class UIDateRangePicker extends UIFormElement {
   // §154: Phosphor icons this primitive auto-stamps (without consumer
   // markup). Aggregated by installIconLoadersForRegistered() across all
   // defined elements. Audited by check-required-icons.mjs.
-  static requiredIcons = ['calendar', 'caret-down', 'arrow-right'];
+  static requiredIcons = ['calendar', 'caret-down'];
 
   static get properties() {
     return {

package/components/date-range-picker/date-range-picker.yaml

@@ -195,7 +195,6 @@ tokens:
 requiredIcons:
   - calendar
   - caret-down
-  - arrow-right
 a2ui:
   rules:
     - rule: 'DateRangePicker.value MUST be `{from, to}` with both ISO 8601 dates, OR null. Either side null is invalid mid-state and the validator should reject it (use `input` event for partial state).'

package/components/datetime-picker/datetime-picker.class.js

@@ -122,7 +122,7 @@ export class UIDatetimePicker extends UIFormElement {
   // §154: Phosphor icons this primitive auto-stamps (without consumer
   // markup). Aggregated by installIconLoadersForRegistered() across all
   // defined elements. Audited by check-required-icons.mjs.
-  static requiredIcons = ['calendar', 'clock', 'caret-down'];
+  static requiredIcons = ['calendar', 'caret-down'];
 
   static get properties() {
     return {

package/components/datetime-picker/datetime-picker.yaml

@@ -210,7 +210,6 @@ tokens:
     default: var(--a-easing)
 requiredIcons:
   - calendar
-  - clock
   - caret-down
 a2ui:
   rules:

package/components/description-list/description-list.css

@@ -54,6 +54,15 @@
     margin-bottom: var(--description-list-gap-row);
   }
 
+  /* Responsive collapse (operator ruling 2026-07-30, the wizard-drawer
+     review step's settings layout): the two-column property|value grid
+     stacks on narrow viewports rather than squeezing the value column. */
+  @media (max-width: 480px) {
+    :scope[layout="inline"] {
+      grid-template-columns: 1fr;
+    }
+  }
+
   /* Inline: term and desc on one row */
   :scope[layout="inline"] {
     grid-template-columns: minmax(var(--description-list-term-min-width), max-content) 1fr;

package/components/drawer/drawer.class.js

@@ -60,6 +60,11 @@ export class UIDrawer extends UIElement {
   // doesn't carry a stale reason. Per FEEDBACK-06 §2.
   #closeReason = 'programmatic';
 
+  // Phosphor icons this primitive auto-stamps (without consumer markup).
+  // Aggregated by installIconLoadersForRegistered() across all defined
+  // elements. Audited by check-required-icons.mjs.
+  static requiredIcons = ['x'];
+
   static properties = {
     text:      { type: String,  default: '', reflect: true },
     side:      { type: String,  default: 'right', reflect: true },

package/components/drawer/drawer.css

@@ -286,6 +286,22 @@ drawer-ui [slot="panel"] > [slot="header"] > :is([slot="action"], [slot="close"]
   gap: var(--drawer-header-gap);
 }
 
+/* ═══════ Sticky progress block (operator ruling 2026-07-30) ═══════
+   A stepper-ui LEADING a drawer body is wizard chrome: it pins just below
+   the sticky header while the step panels scroll beneath — padded, on the
+   panel's own background so content can't ghost through, bled to the body
+   edges so the background spans full width. --drawer-sticky-offset
+   defaults to a one-line header's height (2×header-pad + one line +
+   divider); override for taller headers. */
+drawer-ui [slot="panel"] > [slot="body"] > stepper-ui:first-child {
+  position: sticky;
+  top: var(--drawer-sticky-offset, calc(2 * var(--drawer-header-pad) + 1lh + 1px));
+  z-index: 1;
+  background: var(--drawer-bg);
+  margin: calc(-1 * var(--drawer-inset)) calc(-1 * var(--drawer-inset)) 0;
+  padding: var(--a-space-3) var(--drawer-inset);
+}
+
 /* ═══════ Body (section) ═══════
    Padded by default. Multiple <section> siblings are allowed — they stack
    inside the panel's own scroll region (see panel's overflow-y + sticky

package/components/drawer/drawer.yaml

@@ -131,6 +131,8 @@ states:
     description: Default, ready for interaction.
 traits: []
 tokens: {}
+requiredIcons:
+  - x
 a2ui:
   rules:
     - >-

package/components/feed/feed.class.js

@@ -43,6 +43,11 @@ import { UIElement, html } from '../../core/element.js';
 /* ── Container — one per position, mounted into document.body ── */
 
 export class UIFeedContainer extends UIElement {
+  // Phosphor icons this primitive auto-stamps (without consumer markup).
+  // Aggregated by installIconLoadersForRegistered() across all defined
+  // elements. Audited by check-required-icons.mjs.
+  static requiredIcons = ['x'];
+
   static properties = {
     position: { type: String, default: 'bottom-right', reflect: true },
     max:      { type: Number, default: 5,              reflect: true },

package/components/feed/feed.yaml

@@ -57,6 +57,8 @@ related:
   - Toast
   - Alert
 
+requiredIcons:
+  - x
 a2ui:
   rules:
     - rule: 'Top-layer notification feed channel — singleton per position (top-right, bottom-center, etc.) mounted lazily into document.body.'

package/components/field/field.css

@@ -3,7 +3,10 @@
     /* ── Tokens ── */
     --field-gap:             var(--a-space-2);
     --field-label-color:     var(--md-sys-color-neutral-on-surface);
-    --field-label-size:      var(--a-ui-sm);
+    /* --a-ui-md, not -sm (operator ruling 2026-07-30): 13px base register /
+       14px in larger registers — 12px labels read too small beside 13-14px
+       control text. */
+    --field-label-size:      var(--a-ui-md);
     --field-label-weight:    var(--a-weight-medium);
     --field-required-color:  var(--a-danger-strong);
     --field-trailing-color:  var(--md-sys-color-neutral-on-surface-variant);

package/components/input/input.class.js

@@ -66,6 +66,11 @@ export class UIInput extends UIFormElement {
   // motivated the deprecation.
   static labelDeprecated = false;
 
+  // Phosphor icons this primitive auto-stamps (without consumer markup).
+  // Aggregated by installIconLoadersForRegistered() across all defined
+  // elements. Audited by check-required-icons.mjs.
+  static requiredIcons = ['caret-up', 'caret-down'];
+
   static properties = {
     ...UIFormElement.properties,
     placeholder: { type: String,  default: '', reflect: true },

package/components/input/input.yaml

@@ -238,6 +238,9 @@ tokens:
     description: Override border radius
   --input-transition:
     description: Override transition timing
+requiredIcons:
+  - caret-up
+  - caret-down
 a2ui:
   rules:
     - >-