@adia-ai/web-components 0.7.5 → 0.7.7

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # Changelog — @adia-ai/web-components
 
+## [0.7.7] — 2026-06-02
+
+### Fixed
+
+- **`[verse]` register now scales `--a-toggle-size` (check / radio / switch) down with its type + controls.** Companion to the 0.7.6 `[verse]` icon/caret fix (`91460aae2`). `--a-toggle-size` (the check / radio / switch control size) is declared at `:root` (`styles/foundation/size.css` = `--a-size-sm − --a-space-1` = 20px @md) and shifted by the global `[size]` rules (`styles/api/sizing.css` = 16/24 at sm/lg), but was **absent from `styles/verse.css`** — so in a verse context check / radio / switch chrome stayed the `:root`-computed 20px against verse's smaller (18/20/24) controls and 11/12/13px type. Added `--a-toggle-size` to all three verse sites (base `[verse]` + `[verse][size="lg"]` + `[verse][size="sm"]`) on clean `--a-space` rungs, one tier down: verse toggle is now **12 / 16 / 20px** at sm/md/lg (was a flat 20px); the regular register is unchanged (16/20/24). The explicit `[size]` tier rules are **required** — verse's `context` layer shadows the lower-layer global `[size]` `--a-toggle-size` rules, the same reason `--a-size` and the icon/caret tokens need them. `--a-space` rungs (not literal px like icon/caret) because the toggle targets land exactly on rungs, keeping the values density-aware and consistent with verse's inset/gap. Verified by `scripts/qa/register-scale-probe.mjs` (extended with a toggle axis): verse 12/16/20, regular 16/20/24, all other registers/axes unchanged. Showcased on the `check` / `radio` / `switch` demos (a "Typography registers" section, mirroring the card / button / text / field / badge / stat pages). File: `styles/verse.css`.
+- **`<agent-artifact-ui>` no longer strands `.map()`-rendered action buttons in the body.** `#build()` grabbed the author's `slot="primary"` / `slot="secondary"` buttons with a `:scope > [slot]` direct-child query, then `this.innerHTML = ''`. Buttons supplied via interpolation (`${actions.map(…)}`) arrive nested in the template engine's `display:contents` / `role="presentation"` wrapper spans, so the direct-child grab missed them and the wipe left them rendered in the artifact *body* instead of the header actions cluster. `#build()` now partitions children with a wrapper-piercing logical walk (the FB-92/96/98 pattern, mirroring `select-ui` `#logicalOptionChildren`), so interpolated AND static action buttons both reach the actions cluster. +2 regression tests. Surfaced by `audit-wrapper-trap` arm 2. File: `components/agent-artifact/agent-artifact.class.js`.
+
+### Changed
+
+- **`<drawer-ui>` body inset is now register / size-aware (`--drawer-inset` → `var(--a-inset)`).** `--drawer-inset` hardcoded `var(--a-space-4)` (a literal 16px rung); it now reads `var(--a-inset)`, matching its sibling `card-ui` (`--card-inset: var(--a-inset)`). **Behavior-neutral at the default tier** (`--a-inset-md` == `--a-space-4` == 16px); the change is that the drawer body / header / footer inset (header & footer padding derive from `--drawer-inset`) now scales with `[size]` (sm 14 / lg 18), `[verse]` (12), and `[prose]` (40). drawer's `[padding]` / `[bleed]` are layout *modes* (canvas-bg / no-pad), not a value scale — unchanged. Part of the 0.7.7 inset-alignment audit, which left `page` / `canvas` / `table` filter / `richtext` `pre` as intentional fixed rungs (their literals aren't 16px, so a swap would change behavior). Files: `components/drawer/drawer.css`, `components/drawer/drawer.examples.html`.
+- **CDN bundle rebuilt** — `dist/web-components.min.css` regenerated so the `[verse]` `--a-toggle-size` fix + the drawer inset reach `@adia-ai/web-components@0.7` CDN consumers.
+
+## [0.7.6] — 2026-06-02
+
+### Added
+
+- **`[padding]` / `[margin]` named scale (`xs`–`xl`) — complete + parametric.** Previously the named padding/margin vocabulary was only `sm`/`md`/`lg` (literal `--a-space-4`/`6`/`8`). Now the full `xs`–`xl` set, each `calc(--a-space-N × --a-{padding,margin}-k)` — mirroring the `[gap]` scale's `value × --a-*-k` form. New `@property --a-padding-k` / `--a-margin-k` knobs (`<number>`, init 1, inherits — a root/provider-level control, subtree-inert like `--a-gap-k`/`--a-density`) retune all named padding/margin at once, per-dimension. `sm`/`md`/`lg` keep their prior values (16/24/32px @k=1) — **behavior-neutral**; `xs` (8px) + `xl` (40px) are new. Integer rungs (`[padding="4"]`) stay literal space-rungs (k-independent). Composes on `--a-density`. Verified: 8/16/24/32/40 @k=1; root `--a-padding-k:2` → md 48 / xl 80; `--a-margin-k` independent of padding. Files: `styles/foundation/space.css`, `styles/api/sizing.css`.
+
+### Changed
+
+- **`styles/host.css` is now foundation-only (tokens + resets + page-frame); `styles/index.css` becomes the primitives barrel.** Previously `host.css` bundled the full library (tokens + all 120 component styles + resets, via `index.css`) plus the page-frame. Now: `host.css` = `tokens.css` + `resets.css` + `:where(html)` page-frame only; `styles/index.css` = `components.css` wrapped in `layer(components)` (the primitives barrel). Pages link both in order. The package-root `index.css` (`@adia-ai/web-components/css`) imports both and preserves the existing full-stack published entry — no change for consumers using the package entry. All 119 component dev shells and `site/index.html` updated. **Migration for `host.css`-only consumers:** add `<link rel="stylesheet" href="@adia-ai/web-components/styles/index.css" />` after the `host.css` link.
+- **`<block-ui>` padding/margin unified with the global `[padding]`/`[margin]` scale — now parametric (behavior change).** `block-ui` carried its own literal padding/margin scale (`none`/`xs`/`sm`/`md`/`lg`/`xl` = `0`/`--a-space-1/2/4/6/10` = 0/4/8/16/24/40px, k-independent), duplicated across `block.css` (static `:scope[padding=…]` rules) and `block.class.js` `_SPACE` (the `@bp` responsive path), and diverging from the global `[padding]`/`[margin]` attribute API — `<block-ui padding="md">` rendered 16px while `[padding="md"]` is 24px (same vocabulary, different sizes). Both paths now reference the parametric `--a-{padding,margin}-{xs..xl}` tokens (`foundation/space.css`), so the two grammars AGREE (the same "one named scale" principle as the `[gap]` unification), `block-ui` tracks the `--a-padding-k`/`--a-margin-k` knobs, and the scale is no longer duplicated. **Behavior change** — `block-ui` spacing grows at `xs`/`sm`/`md`/`lg`: `xs` 4→8, `sm` 8→16, **`md` (the default) 16→24**, `lg` 24→32px; `xl` (40) + `none` (0) unchanged. Verified by computed-style probe (8/16/24/32/40 @k=1, default 24, `--a-padding-k:2` → md 48, `@bp` responsive + margins all correct, 0 console errors) + dev-shell visual QA. Files: `components/block/block.css`, `components/block/block.class.js`. **Migration:** a `<block-ui>` that relied on the prior tighter spacing should step the named value one rung down (`md`→`sm`, `lg`→`md`, …) or use the integer rungs (`padding="4"` = literal 16px, k-independent).
+- **CDN bundles rebuilt** — `dist/host.min.css`, `dist/web-components.min.css`, and `dist/web-components.min.js` regenerated so the barrel split + `<block-ui>` + parametric `[padding]`/`[margin]` + `[verse]` re-scaling reach `@adia-ai/web-components@0.7` CDN consumers.
+
+### Fixed
+
+- **`[verse]` register now scales icon + caret sizes down with its type + controls.** The compact `[verse]` register (`styles/verse.css`) shifted inset, gap, radius, control-size (`--a-size`), and every type role down — but left `--a-icon-size` (16px @md) and `--a-caret-size` (14px @md) at their regular-register values. So in a verse context a `<select-ui>` caret (an `<icon-ui>` reading `--a-icon-size`) stayed 16×16 against verse's 12px text in a 43px-tall control, and form-element chrome icons read full size — visually oversized. Added a one-tier-down icon/caret scale to `[verse]`, mirroring how it already re-implements `--a-size`: base `[verse]` = 14/12px (= regular-`sm`), `[verse][size="lg"]` = 16/14px (= regular-`md`), `[verse][size="sm"]` = 12/10px. The explicit `[size]` tier rules are **required** because the global `[size]` icon/caret rules live in the `utilities` layer, which verse's `context` layer shadows (same reason `--a-size` needs them). Covers both `<icon-ui>`-based carets (select / combobox, via `--a-icon-size`) and CSS-drawn carets (calendar-grid / calendar-picker / nav-group / pane, via `--a-caret-size`). Verified by computed-style + render-box probe: verse(md) caret 16→14px, verse-`sm` 14→12px, verse-`lg` 20→16px; regular register unchanged. File: `styles/verse.css`.
+- **`<command-ui>` now parses `.map()`/`repeat()`-rendered `<option>`/`<optgroup>` palette items (5th sighting of the `display:contents` wrapper trap).** `#parseOptions()` walked `this.children` directly, so options rendered via `.map()` arrived nested in the template engine's `display:contents`/`role="presentation"` wrapper span and were missed — leaving an empty palette ("No results found.") when the consumer interpolated its option list. New `#logicalOptionChildren()` walks direct children and pierces wrapper spans, mirroring `select-ui#logicalOptionChildren` (FB-98). Eight other `for (const x of this.children)` loops across 8 components (context-menu, field, fields, integration-card, list, menu, swatch, toolbar) were audited and marked `// wrapper-trap-ok` — all read component-stamped or single-literal children that are never consumer-interpolated. `audit:wrapper-trap:strict` added to `check:dogfood-audits:strict`; the audit now reports 0 un-allowlisted loops. File: `components/command/command.class.js`.
+- **`<select-ui>` now parses `.map()`/`repeat()`-rendered `<option>` children (FB-98).** `#parseOptions()` walked `this.children` and matched only `tagName === 'OPTION'`/`'OPTGROUP'`, so interpolated options — each nested in the template engine's `display:contents`/`role="presentation"` wrapper span (`core/template.js` Array branch) — were invisible, leaving the popover empty ("No options"); static-literal options worked (direct children, no wrapper). New `#logicalOptionChildren()` collects `<option>`/`<optgroup>` direct OR nested inside the wrapper spans (skipping component-stamped `[slot]` children), and a re-entrancy-guarded `MutationObserver` re-parses options that arrive after `connected()` (the template's `update()` pass) so the empty-state clears. The same `display:contents` wrapper trap fixed for `menu-ui#show()` (FB-92) and `tree-item-ui#stamp()` (FB-96), now in the third component; mirrors tree's `#logicalSlotChildren`. Static-literal selects + the FB-36 `<option selected>` initial-value path are unchanged. +2 regression tests. File: `components/select/select.class.js`. (Tokens Studio / color-app FB-98)
+- **`<menu-ui>` — a closed declarative menu no longer takes layout space (FB-97).** The closed-state hide rule (`menu.css`) used a child combinator (`:scope > menu-item-ui`), so `.map()`/`repeat()`-rendered items — nested in the template engine's `display:contents`/`role="presentation"` wrapper span — escaped it on the initial (never-opened) render and laid out in flow, ballooning a compact menu to its widest item's width (a 388px file menu displaced a centered toolbar tab-row until a tab became un-clickable). Added wrapper-piercing descendant selectors (`:scope > [role="presentation"] menu-item-ui`, + `menu-divider-ui`); safe vs. the open state since `#show()` appendChild's the bare items into `[data-menu-popover]` (never the wrappers). Verified: a closed `.map()` menu collapses 388px → trigger width (~41px), items `display:none`, neighbour un-displaced; open still renders all items. The CSS instance of the FB-92/96/98 `display:contents` wrapper trap; makes the FB-92/95 "render menu items declaratively" guidance safe for compact menus. File: `components/menu/menu.css`. (Tokens Studio / color-app FB-97)
+- **`button.yaml` `aria-label` prop marked `dynamic: true` — clears dogfood drift.** `aria-label` is a native ARIA attribute managed via `setAttribute` in `connected()` and deliberately kept out of `static properties` (would clobber native `ariaLabel` reflection via `installProps`). The `static-properties-vs-yaml` dogfood audit flagged the yaml declaration as a drift; `dynamic: true` is the established opt-out (same pattern as the `text` prop). `button.a2ui.json` regenerated (`aria-label` → `DynamicString $ref`); dogfood advisory count: 43 → 42.
+- **`<button-ui>` trailing slot kbd-pill now tracks the button's label color on every variant.** A `<kbd-ui slot="trailing">` pill rendered `kbd-ui`'s dark default even on a primary (white-label) button. `kbd-ui` styles its own `color`/`background`/`border` inside `@scope (kbd-ui)`, which wins over the button's `[slot="trailing"]` rule by **scope proximity** (closer scope root) — so setting `color` (even `inherit`) on the slot is inert. Fix: the button overrides `kbd-ui`'s own *tokens* — `[slot="trailing"] { --kbd-fg: currentColor; --kbd-bg / --kbd-border: color-mix(in oklab, currentColor …, transparent) }`. `kbd-ui` declares those tokens at `:where(:scope)` (specificity 0,0,0), so the button's `[slot]` decls (0,1,0) win on **specificity — which the cascade resolves before proximity** — and the pill (text + translucent fill + border) tracks the label: white on primary/colored fills, dark on outline/ghost. Verified on a fresh serve (kbd computed `color` == button label across variants). File: `components/button/button.css`.
+
 ## [0.7.5] — 2026-06-02
 
 ### Fixed

package/components/action-list/action-list.a2ui.json

@@ -66,8 +66,8 @@
       "Button"
     ],
     "slots": {
-      "default (action-item-ui children)": {
-        "description": "Child content region for the `default (action-item-ui children)` slot."
+      "default": {
+        "description": "Holds the list's `<action-item-ui>` children (the action items)."
       }
     },
     "states": [

package/components/action-list/action-list.yaml

@@ -28,8 +28,8 @@ events:
         type: object
         description: The triggering list-item element.
 slots:
-  default (action-item-ui children):
-    description: "Child content region for the `default (action-item-ui children)` slot."
+  default:
+    description: "Holds the list's `<action-item-ui>` children (the action items)."
 states:
   - name: idle
     description: Default, ready for interaction.

package/components/agent-artifact/agent-artifact.class.js

@@ -139,19 +139,35 @@ export class UIAgentArtifact extends UIElement {
     // To keep the Light-DOM approach consistent, we wrap existing children
     // into a body container if one isn't already present.
 
-    // Capture any existing non-slotted children to put into the body wrapper
-    const existingBodyNodes = Array.from(this.childNodes).filter((n) => {
-      if (n.nodeType === 1) {
-        const slot = /** @type {Element} */ (n).getAttribute?.('slot') || '';
-        return slot !== 'primary' && slot !== 'secondary';
+    // Partition the author's children by LOGICAL slot, piercing the template
+    // engine's display:contents / role="presentation" wrapper spans. A consumer
+    // that interpolates the action buttons — `${actions.map(a => html`<button-ui
+    // slot="primary">…`)}` — gets them nested in wrapper spans (core/template.js
+    // wrap()), so the old `:scope > [slot="primary"]` direct-child grab returned
+    // nothing and `innerHTML = ''` stranded them in the body. This is the
+    // wrapper-trap class (FB-92/96/98); walk + pierce so wrapped action buttons
+    // reach the header actions cluster. Wrappers are flattened (display:contents
+    // is layout-transparent); everything non-action becomes body.
+    const primaryBtns = [];
+    const secondaryBtns = [];
+    const bodyNodes = [];
+    const isWrapper = (el) =>
+      el.getAttribute('role') === 'presentation' || el.style?.display === 'contents';
+    const partition = (nodes) => {
+      for (const n of nodes) {
+        if (n.nodeType === 1) {
+          const el = /** @type {Element} */ (n);
+          if (isWrapper(el)) { partition(el.childNodes); continue; } // pierce; drop the wrapper
+          const slot = el.getAttribute('slot') || '';
+          if (slot === 'primary') { primaryBtns.push(el); continue; }
+          if (slot === 'secondary') { secondaryBtns.push(el); continue; }
+        }
+        bodyNodes.push(n);
       }
-      return true;
-    });
-
-    // Clear — we'll rebuild, preserving slotted action buttons
-    const primaryBtns = this.querySelectorAll(':scope > [slot="primary"]');
-    const secondaryBtns = this.querySelectorAll(':scope > [slot="secondary"]');
+    };
+    partition(Array.from(this.childNodes));
 
+    // Clear — we'll rebuild around the captured (now-detached) children.
     this.innerHTML = '';
 
     // Header — keyboard-focusable button-style row that toggles collapsed.
@@ -197,7 +213,7 @@ export class UIAgentArtifact extends UIElement {
     // Body
     this.#bodyEl = document.createElement('div');
     this.#bodyEl.setAttribute('data-artifact-body', '');
-    for (const n of existingBodyNodes) this.#bodyEl.appendChild(n);
+    for (const n of bodyNodes) this.#bodyEl.appendChild(n);
     if (this.collapsed) this.#bodyEl.hidden = true;
 
     this.append(this.#headerEl, this.#bodyEl);

package/components/agent-artifact/agent-artifact.test.js

@@ -0,0 +1,61 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import '../../core/element.js';
+import './agent-artifact.js';
+
+const tick = () => new Promise((r) => queueMicrotask(r));
+
+function mount(html) {
+  const wrap = document.createElement('div');
+  wrap.innerHTML = html;
+  document.body.appendChild(wrap);
+  return wrap.firstElementChild;
+}
+
+describe('agent-artifact-ui', () => {
+  beforeEach(() => { document.body.innerHTML = ''; });
+
+  // Baseline — static slot="primary"/"secondary" buttons route into the header
+  // actions cluster, and the default-slot content lands in the body.
+  it('routes static action buttons into the header actions cluster (not the body)', async () => {
+    const a = mount(`
+      <agent-artifact-ui title="Build">
+        <button-ui slot="primary">Run</button-ui>
+        <button-ui slot="secondary">Cancel</button-ui>
+        <p>Body content</p>
+      </agent-artifact-ui>
+    `);
+    await tick();
+    const actions = a.querySelector('[data-artifact-actions]');
+    const body = a.querySelector('[data-artifact-body]');
+    expect(actions).toBeTruthy();
+    expect(actions.querySelectorAll('[slot="primary"], [slot="secondary"]').length).toBe(2);
+    expect(body.querySelectorAll('[slot="primary"], [slot="secondary"]').length).toBe(0);
+    expect(body.textContent).toContain('Body content');
+  });
+
+  // Wrapper-trap regression (audit-wrapper-trap arm 2): action buttons rendered
+  // via `.map()`/`repeat()` arrive nested in the template engine's
+  // display:contents / role="presentation" wrapper spans. The old `:scope >
+  // [slot="primary"]` direct-child grab missed them, so `innerHTML = ''`
+  // stranded them in the body. They must reach the actions cluster.
+  it('routes WRAPPED (interpolated) action buttons into the actions cluster, not the body', async () => {
+    const a = mount(`
+      <agent-artifact-ui title="Build">
+        <span style="display:contents" role="presentation">
+          <span style="display:contents" role="presentation"><button-ui slot="primary">Run</button-ui></span>
+          <span style="display:contents" role="presentation"><button-ui slot="secondary">Cancel</button-ui></span>
+        </span>
+        <p>Body content</p>
+      </agent-artifact-ui>
+    `);
+    await tick();
+    const actions = a.querySelector('[data-artifact-actions]');
+    const body = a.querySelector('[data-artifact-body]');
+    expect(actions.querySelectorAll('[slot="primary"], [slot="secondary"]').length).toBe(2);
+    // The regression: before the wrapper-pierce fix these landed in the body.
+    expect(body.querySelectorAll('[slot="primary"], [slot="secondary"]').length).toBe(0);
+    expect(body.textContent).toContain('Body content');
+    // No empty wrapper spans left dangling — they're flattened, not re-appended.
+    expect(a.querySelectorAll('[role="presentation"]').length).toBe(0);
+  });
+});

package/components/badge/badge.yaml

@@ -90,6 +90,7 @@ props:
       - muted
       - solid
       - outline
+    reflect: false  # declarative presentational attribute — CSS/author-time read, non-reactive by design
 events: {}
 slots: {}
 states:

package/components/block/block.class.js

@@ -19,13 +19,29 @@
  * Properties:
  *   padding — none | xs | sm | md | lg | xl (default 'md')
  *   margin  — none | xs | sm | md | lg | xl (default 'none')
+ *
+ * Values resolve to the parametric --a-{padding,margin}-{xs..xl} scale
+ * (foundation/space.css), unified with the global [padding]/[margin] attribute
+ * API: md = 24px @k=1, tracks --a-{padding,margin}-k. The `@bp` responsive
+ * path below emits the same tokens as the static block.css rules.
  */
 
 import { UIElement } from '../../core/element.js';
 import { parseResponsive, breakpoint } from '../../core/responsive.js';
 
-const _SPACE = { none: '0', xs: 'var(--a-space-1)', sm: 'var(--a-space-2)', md: 'var(--a-space-4)', lg: 'var(--a-space-6)', xl: 'var(--a-space-10)' };
-function _spaceToCss(v) { return _SPACE[v] ?? (/^\d+$/.test(v ?? '') ? `var(--a-space-${v})` : v ?? ''); }
+const _NAMED = new Set(['xs', 'sm', 'md', 'lg', 'xl']);
+/** Resolve a (responsive-parsed) padding/margin value to CSS for dimension
+ *  `dim` ('padding' | 'margin'). Named rungs map to the parametric
+ *  --a-{dim}-{xs..xl} scale (foundation/space.css) so this responsive JS path
+ *  AGREES with the static block.css rules + the global [padding]/[margin]
+ *  attribute API; bare integers stay literal --a-space-N rungs; 'none' → 0. */
+function _spaceToCss(v, dim) {
+  if (v == null || v === '') return '';
+  if (v === 'none') return '0';
+  if (_NAMED.has(v)) return `var(--a-${dim}-${v})`;
+  if (/^\d+$/.test(v)) return `var(--a-space-${v})`;
+  return v;
+}
 
 export class UIBlock extends UIElement {
   static properties = {
@@ -42,13 +58,13 @@ export class UIBlock extends UIElement {
     const bp      = anyR ? breakpoint.value : '';
 
     if (padding?.includes('@')) {
-      this.style.setProperty('--block-padding', _spaceToCss(parseResponsive(padding, bp)));
+      this.style.setProperty('--block-padding', _spaceToCss(parseResponsive(padding, bp), 'padding'));
     } else {
       this.style.removeProperty('--block-padding');
     }
 
     if (margin?.includes('@')) {
-      this.style.setProperty('--block-margin', _spaceToCss(parseResponsive(margin, bp)));
+      this.style.setProperty('--block-margin', _spaceToCss(parseResponsive(margin, bp), 'margin'));
     } else {
       this.style.removeProperty('--block-margin');
     }

package/components/block/block.css

@@ -1,6 +1,6 @@
 @scope (block-ui) {
   :where(:scope) {
-    --block-padding: var(--a-space-4);
+    --block-padding: var(--a-padding-md);
     --block-margin:  0;
   }
 
@@ -11,19 +11,24 @@
     margin: var(--block-margin);
   }
 
-  /* ── Padding variants ── */
+  /* ── Padding variants — the parametric --a-padding-{xs..xl} scale
+     (foundation/space.css), unified with the global [padding] attribute API
+     (api/sizing.css) so <block-ui padding="md"> == [padding="md"] == 24px @k=1,
+     and block-ui now tracks the --a-padding-k knob. Was a literal --a-space-N
+     scale (md=16px, k-independent) — see CHANGELOG 0.7.7 behavior change. ── */
   :scope[padding="none"] { --block-padding: 0; }
-  :scope[padding="xs"]   { --block-padding: var(--a-space-1); }
-  :scope[padding="sm"]   { --block-padding: var(--a-space-2); }
-  :scope[padding="md"]   { --block-padding: var(--a-space-4); }
-  :scope[padding="lg"]   { --block-padding: var(--a-space-6); }
-  :scope[padding="xl"]   { --block-padding: var(--a-space-10); }
+  :scope[padding="xs"]   { --block-padding: var(--a-padding-xs); }
+  :scope[padding="sm"]   { --block-padding: var(--a-padding-sm); }
+  :scope[padding="md"]   { --block-padding: var(--a-padding-md); }
+  :scope[padding="lg"]   { --block-padding: var(--a-padding-lg); }
+  :scope[padding="xl"]   { --block-padding: var(--a-padding-xl); }
 
-  /* ── Margin variants ── */
+  /* ── Margin variants — the parametric --a-margin-{xs..xl} scale, unified
+     with the global [margin] attribute API (tracks --a-margin-k). ── */
   :scope[margin="none"] { --block-margin: 0; }
-  :scope[margin="xs"]   { --block-margin: var(--a-space-1); }
-  :scope[margin="sm"]   { --block-margin: var(--a-space-2); }
-  :scope[margin="md"]   { --block-margin: var(--a-space-4); }
-  :scope[margin="lg"]   { --block-margin: var(--a-space-6); }
-  :scope[margin="xl"]   { --block-margin: var(--a-space-10); }
+  :scope[margin="xs"]   { --block-margin: var(--a-margin-xs); }
+  :scope[margin="sm"]   { --block-margin: var(--a-margin-sm); }
+  :scope[margin="md"]   { --block-margin: var(--a-margin-md); }
+  :scope[margin="lg"]   { --block-margin: var(--a-margin-lg); }
+  :scope[margin="xl"]   { --block-margin: var(--a-margin-xl); }
 }

package/components/button/button.a2ui.json

@@ -20,8 +20,7 @@
     },
     "aria-label": {
       "description": "Accessible label for screen readers. Auto-set from `text` when text is non-empty; meaningful override for icon-only buttons.",
-      "type": "string",
-      "default": ""
+      "$ref": "common_types.json#/$defs/DynamicString"
     },
     "color": {
       "description": "Semantic intent — composes with [variant]. `<button-ui variant=\"solid\" color=\"danger\">` = filled destructive action; `<button-ui variant=\"outline\" color=\"success\">` = outlined success affordance.",

package/components/button/button.css

@@ -71,11 +71,12 @@ button-ui[color="danger"]:not([disabled]):hover {
 
     /* ── Trailing slot ── */
     --button-trailing-font-size:  var(--a-ui-sm);
-    /* kbd-pill tracks the button's OWN text color (currentColor) so it reads
-       on any variant fill — on a primary button the fixed --a-fg-muted gray
-       was nearly invisible against the white label. Border is a translucent
-       slice of the same color so the pill outline adapts too. */
-    --button-trailing-fg:         currentColor;
+    /* kbd-ui styles its color/bg/border inside `@scope (kbd-ui)`, which beats
+       this scope by PROXIMITY — so setting `color`/`border` on [slot="trailing"]
+       here is inert for a kbd pill. The pill is recolored through kbd's OWN
+       tokens (--kbd-fg/-bg/-border) in the rule below instead. The
+       --button-trailing-* tokens remain the fallback for non-kbd trailing
+       content (badges, plain spans). */
     --button-trailing-border:     color-mix(in oklab, currentColor 28%, transparent);
     --button-trailing-radius:     var(--a-radius-sm);
     --button-trailing-px:         var(--a-space-0-5);
@@ -142,12 +143,22 @@ button-ui[color="danger"]:not([disabled]):hover {
     order: 99;
     margin-inline-start: auto;
     font-size: var(--button-trailing-font-size);
-    color: var(--button-trailing-fg);
+    color: inherit;
     font-family: inherit;
     border: 1px solid var(--button-trailing-border);
     border-radius: var(--button-trailing-radius);
     padding: 0 var(--button-trailing-px);
     line-height: 1;
+    /* Recolor a <kbd-ui slot="trailing"> pill via kbd's OWN tokens so it tracks
+       the button label color on every variant (primary white, ghost subtle,
+       colored fills). kbd-ui's `:scope { color: var(--kbd-fg) }` wins over the
+       `color: inherit` above by scope proximity, but its tokens are declared at
+       :where(:scope) (0,0,0) — these (0,1,0) decls win on specificity, which the
+       cascade resolves BEFORE proximity. currentColor here is the inherited
+       button label color. */
+    --kbd-fg:     currentColor;
+    --kbd-bg:     color-mix(in oklab, currentColor 16%, transparent);
+    --kbd-border: color-mix(in oklab, currentColor 30%, transparent);
   }
 
   /* :scope:active moved outside @scope — see Safari 17.x bug note at top. */

package/components/button/button.yaml

@@ -18,6 +18,7 @@ props:
     description: Accessible label for screen readers. Auto-set from `text` when text is non-empty; meaningful override for icon-only buttons.
     type: string
     default: ""
+    dynamic: true  # native ARIA attr — managed in connected() (setAttribute), deliberately NOT in `static properties` (would clobber native ariaLabel reflection per the installProps memory)
   type:
     description: HTML button type (button, submit, reset)
     type: string

package/components/card/card.yaml

@@ -16,6 +16,7 @@ props:
       rung ("1"…"16").
     type: string
     default: md
+    reflect: false  # declarative presentational attribute — CSS/author-time read, non-reactive by design
   draggable:
     description: Enables drag handle + cursor:grab. Wires the draggable trait; dispatches drag-end.
     type: boolean

package/components/chart/chart.a2ui.json

@@ -55,8 +55,7 @@
     },
     "data": {
       "description": "JS property (set programmatically — `el.data = [...]`). An array of plain objects; each object's keys are named by the `x` and `y` attributes — e.g. `<chart-ui x=\"month\" y=\"revenue\">` consumes `[{month:'Jan', revenue:3200}, {month:'Feb', revenue:4100}]`. The Chart.js `{labels, datasets}` envelope is NOT chart-ui's API — passing it (or any non-array value) renders an empty chart. May also be supplied declaratively as a JSON-array `data=\"[…]\"` attribute, hydrated once at connect. Custom accessor on the element class, not a reflected attribute.",
-      "type": "array",
-      "default": []
+      "$ref": "common_types.json#/$defs/DynamicStringList"
     },
     "format": {
       "description": "Number-format mode applied to axis labels + value overlays + donut total + gauge value + treemap value + funnel value + internal tooltip. `abbr` is the legacy 1.2K / 3M format; `decimal` fixes 2 decimals; `currency` prefixes via `--chart-currency-prefix` token (default \"$\"); `percent` multiplies × 100 and adds a % suffix.",

package/components/chart/chart.d.ts

@@ -23,7 +23,7 @@ export class UIChart extends UIElement {
   /** Color scheme */
   color: 'accent' | 'success' | 'warning' | 'danger' | 'info';
   /** JS property (set programmatically — `el.data = [...]`). An array of plain objects; each object's keys are named by the `x` and `y` attributes — e.g. `<chart-ui x="month" y="revenue">` consumes `[{month:'Jan', revenue:3200}, {month:'Feb', revenue:4100}]`. The Chart.js `{labels, datasets}` envelope is NOT chart-ui's API — passing it (or any non-array value) renders an empty chart. May also be supplied declaratively as a JSON-array `data="[…]"` attribute, hydrated once at connect. Custom accessor on the element class, not a reflected attribute. */
-  data: unknown[];
+  data: string;
   /** Number-format mode applied to axis labels + value overlays + donut total + gauge value + treemap value + funnel value + internal tooltip. `abbr` is the legacy 1.2K / 3M format; `decimal` fixes 2 decimals; `currency` prefixes via `--chart-currency-prefix` token (default "$"); `percent` multiplies × 100 and adds a % suffix. */
   format: 'abbr' | 'decimal' | 'currency' | 'percent';
   /** When true, suppress the overlaid average line */

package/components/chart/chart.yaml

@@ -123,6 +123,7 @@ props:
       reflected attribute.
     type: array
     default: []
+    dynamic: true  # JS-set collection prop with a custom setter — deliberately not in static properties
 events:
   chart-hover:
     description: >-

package/components/check/check.a2ui.json

@@ -98,9 +98,6 @@
       "box": {
         "description": "Visual checkbox indicator"
       },
-      "hint": {
-        "description": "Help text below the label"
-      },
       "label": {
         "description": "Label text beside the checkbox"
       }

package/components/check/check.yaml

@@ -58,8 +58,6 @@ events:
 slots:
   box:
     description: Visual checkbox indicator
-  hint:
-    description: Help text below the label
   label:
     description: Label text beside the checkbox
 states:

package/components/combobox/combobox.a2ui.json

@@ -93,8 +93,7 @@
     },
     "options": {
       "description": "Programmatic option list. Array of {value, label, disabled?, group?} or grouped {label, options:[…]}. Alternative to declarative <option> / <optgroup> children.",
-      "type": "array",
-      "default": []
+      "$ref": "common_types.json#/$defs/DynamicStringList"
     },
     "placeholder": {
       "description": "Placeholder text in the input when value is empty",

package/components/combobox/combobox.yaml

@@ -84,6 +84,7 @@ props:
       <option> / <optgroup> children.
     type: array
     default: []
+    dynamic: true  # JS-set collection prop with a custom setter — deliberately not in static properties
   open:
     description: Reflects popover open / closed state
     type: boolean

package/components/command/command.a2ui.json

@@ -103,9 +103,6 @@
       },
       "list": {
         "description": "Container for command items and groups"
-      },
-      "search": {
-        "description": "Search input with combobox role"
       }
     },
     "states": [

package/components/command/command.class.js

@@ -140,9 +140,27 @@ export class UICommand extends UIElement {
 
   // ── Parse declarative <option>/<optgroup> ──
 
+  // Wrapper-piercing walk for consumer-authored <option>/<optgroup> children.
+  // Mirrors select-ui's #logicalOptionChildren (FB-98): .map()/repeat()-rendered
+  // options arrive in display:contents/role="presentation" wrapper spans; a plain
+  // this.children iteration misses them (FB-98 class, 5th sighting in command-ui).
+  #logicalOptionChildren() {
+    const out = [];
+    const walk = (parent) => {
+      for (const ch of parent.children) {
+        if (ch.hasAttribute('slot')) continue;            // component-stamped — skip
+        if (ch.tagName === 'OPTION' || ch.tagName === 'OPTGROUP') { out.push(ch); continue; }
+        if (ch.matches('[role="presentation"]') || ch.style?.display === 'contents') { walk(ch); continue; }
+        // unknown authored child — ignore (command-ui only uses option/optgroup)
+      }
+    };
+    walk(this);
+    return out;
+  }
+
   #parseOptions() {
     const items = [];
-    for (const child of this.children) {
+    for (const child of this.#logicalOptionChildren()) {
       if (child.tagName === 'OPTGROUP') {
         const groupLabel = child.label;
         const group = { label: groupLabel, items: [] };

package/components/command/command.yaml

@@ -51,8 +51,6 @@ slots:
     description: Keyboard hint bar
   list:
     description: Container for command items and groups
-  search:
-    description: Search input with combobox role
 states:
 - name: idle
   description: Default, ready for interaction.

package/components/context-menu/context-menu.class.js

@@ -105,6 +105,7 @@ export class UIContextMenu extends UIElement {
         return [];
       }
     }
+    // wrapper-trap-ok: detects non-menu-item children as custom content; context-menu items are always static declarative children (right-click actions are not .map()'d)
     for (const child of this.children) {
       const tag = child.tagName.toLowerCase();
       if (tag !== 'menu-item-ui' && tag !== 'menu-divider-ui') return [child];

package/components/description-list/description-list.a2ui.json

@@ -15,8 +15,7 @@
   "properties": {
     "items": {
       "description": "Optional JSON array of {term, description} — alternative to declarative <dt>/<dd> children",
-      "type": "array",
-      "default": []
+      "$ref": "common_types.json#/$defs/DynamicStringList"
     },
     "align": {
       "description": "Alignment for inline layout. `start` (default): term and value pack to the term column edge. `between`: term left, value right-aligned with `text-align: end`. `stretch`: value fills the remaining track width (e.g. for a `<slider-ui>` / `<select-ui>` / `<color-picker-ui>` as `<dd>` that should span the full row). Sets `justify-self: stretch` and `width: 100%` on `dd` so block-level form controls inside reach the column edge rather than shrink-wrapping to content.\n",

package/components/description-list/description-list.d.ts

@@ -14,7 +14,7 @@ import { UIElement } from '../../core/element.js';
 
 export class UIDescriptionList extends UIElement {
   /** Optional JSON array of {term, description} — alternative to declarative <dt>/<dd> children */
-  items: unknown[];
+  items: string;
   /** Alignment for inline layout. `start` (default): term and value pack to the term column edge. `between`: term left, value right-aligned with `text-align: end`. `stretch`: value fills the remaining track width (e.g. for a `<slider-ui>` / `<select-ui>` / `<color-picker-ui>` as `<dd>` that should span the full row). Sets `justify-self: stretch` and `width: 100%` on `dd` so block-level form controls inside reach the column edge rather than shrink-wrapping to content.
  */
   align: 'start' | 'between' | 'stretch';

package/components/description-list/description-list.yaml

@@ -30,6 +30,7 @@ props:
     description: Optional JSON array of {term, description} — alternative to declarative <dt>/<dd> children
     type: array
     default: []
+    dynamic: true  # JS-set collection prop with a custom setter — deliberately not in static properties
   layout:
     description: "stacked: term above description. inline: term and description on one row."
     type: string

package/components/drawer/drawer.css

@@ -19,7 +19,7 @@
   /* ── Geometry ── */
   --drawer-width:       24rem;
   --drawer-height:      24rem;
-  --drawer-inset:       var(--a-space-4);
+  --drawer-inset:       var(--a-inset);
   --drawer-header-pad:  var(--drawer-inset);
   --drawer-footer-pad:  var(--drawer-inset);
   --drawer-header-gap:  var(--a-space-2);

package/components/field/field.class.js

@@ -245,6 +245,7 @@ export class UIField extends UIElement {
 
   /** The default-slot control — first child without a `slot` attribute. */
   #findControl() {
+    // wrapper-trap-ok: field control is always a single literal child (one <input>/<textarea>/<select>); interpolating the control via .map() is not a documented field pattern
     for (const ch of this.children) {
       if (!ch.hasAttribute('slot')) return ch;
     }

package/components/fields/fields.class.js

@@ -81,6 +81,7 @@ export class UIFields extends UIElement {
 
   #syncInline() {
     const inline = this.hasAttribute('inline');
+    // wrapper-trap-ok: fields-ui children are authored as static field-ui literals within a form group; dynamic .map() field collections use the programmatic API
     for (const child of this.children) {
       if (child.localName !== 'field-ui') continue;
       if (inline) {

package/components/grid/grid.yaml

@@ -23,6 +23,7 @@ props:
       in a 2-column hero. Sets grid-item alignment, NOT text alignment.
     type: string
     default: stretch
+    reflect: false  # declarative presentational attribute — CSS/author-time read, non-reactive by design
   columnGap:
     description: Column gap override
     type: string
@@ -50,6 +51,7 @@ props:
       justify-items. Default stretch (items fill their column track).
     type: string
     default: stretch
+    reflect: false  # declarative presentational attribute — CSS/author-time read, non-reactive by design
   minColumnWidth:
     description: >-
       Minimum track width for columns="auto-fit"/"auto-fill" (any CSS length,

package/components/input/input.a2ui.json

@@ -40,8 +40,7 @@
     },
     "autocomplete": {
       "description": "Browser autofill behavior per HTML autocomplete spec. Routed via setAttribute to the host element. Common values: off, on, cc-number, cc-exp, cc-csc, cc-name, email, username, current-password, new-password, one-time-code, given-name, family-name, street-address, postal-code.",
-      "type": "string",
-      "default": ""
+      "$ref": "common_types.json#/$defs/DynamicString"
     },
     "component": {
       "const": "Input"
@@ -58,18 +57,7 @@
     },
     "inputmode": {
       "description": "Mobile keyboard hint per HTML inputmode spec. Routed via setAttribute to the host element. Values: text, decimal, numeric, tel, search, email, url.",
-      "type": "string",
-      "enum": [
-        "text",
-        "decimal",
-        "numeric",
-        "tel",
-        "search",
-        "email",
-        "url",
-        "none"
-      ],
-      "default": null
+      "$ref": "common_types.json#/$defs/DynamicString"
     },
     "label": {
       "description": "Inline label rendered as a leading caption inside the input chrome, between any prefix and the value. Wires aria-labelledby on the editable surface. For stacked label / hint / error compositions, wrap with field-ui.",