@adia-ai/web-components 0.8.32 → 0.8.34

package/components/command/command.class.js

@@ -85,10 +85,15 @@ export class UICommand extends UIElement {
   render() {
     // Stamp internal structure once
     if (!this.#inputEl) {
-      // Parse options + capture author-provided slot="empty" content
-      // before replacing innerHTML (dogfood-status yaml-drift finding:
-      // yaml documented an overridable empty state that was never wired).
-      this.#parseOptions();
+      // Parse declarative <option>/<optgroup> children once, unless
+      // `.options` was already set programmatically before first render
+      // (mirrors combobox-ui's connected()-time guard) + capture
+      // author-provided slot="empty" content before replacing innerHTML
+      // (dogfood-status yaml-drift finding: yaml documented an overridable
+      // empty state that was never wired).
+      if (this.#items.length === 0) {
+        this.#parseOptions();
+      }
       this.#emptyNodes = logicalSlotted(this, 'empty');
 
       this.innerHTML = `
@@ -143,6 +148,51 @@ export class UICommand extends UIElement {
     this.#renderItems();
   }
 
+  // ── Programmatic options (gh#887) ──
+  //
+  // Public API mirroring combobox-ui's `options` prop: an array of flat
+  // {value, label, icon?, shortcut?, disabled?} entries, or grouped
+  // {label, options:[…]} entries — same field names as the data-icon/
+  // data-shortcut attributes on declarative <option> children. Normalized
+  // into the internal #items shape #renderItems() already consumes (flat
+  // items carry `category`; groups carry `.items` not `.options`), so
+  // programmatic and declarative authoring render identically.
+
+  set options(list) {
+    this.#items = this.#normalizeOptions(Array.isArray(list) ? list : []);
+    // Only re-render if the internal list has already been stamped —
+    // otherwise the pending #items feed the first render() pass directly.
+    if (this.#listEl) this.#renderItems(this.#inputEl?.value || '');
+  }
+
+  get options() { return this.#items; }
+
+  #normalizeOptions(list) {
+    const out = [];
+    for (const entry of list) {
+      if (entry && Array.isArray(entry.options)) {
+        const label = entry.label || '';
+        out.push({ label, items: entry.options.map((opt) => this.#optionObjectToItem(opt, label)) });
+      } else if (entry) {
+        out.push(this.#optionObjectToItem(entry, ''));
+      }
+    }
+    return out;
+  }
+
+  /** Plain-object counterpart of #optionToItem (which reads a DOM <option>). */
+  #optionObjectToItem(opt, category = '') {
+    return {
+      value: opt.value,
+      label: opt.label ?? opt.value,
+      icon: opt.icon || '',
+      shortcut: opt.shortcut || '',
+      keywords: opt.keywords || '',
+      disabled: !!opt.disabled,
+      category,
+    };
+  }
+
   // ── Parse declarative <option>/<optgroup> ──
 
   // Wrapper-piercing walk for consumer-authored <option>/<optgroup> children.

package/components/command/command.d.ts

@@ -35,6 +35,8 @@ export type CommandSelectEvent = CustomEvent<CommandSelectEventDetail>;
 export class UICommand extends UIElement {
   /** Whether the command palette is visible */
   open: boolean;
+  /** Programmatic item list. Array of {value, label, icon?, shortcut?, disabled?} or grouped {label, options:[…]}. `icon` renders as a leading icon-ui, `shortcut` as a trailing keyboard-shortcut hint — the same fields as the data-icon/data-shortcut attributes on declarative <option> children. Alternative to declarative <option data-icon data-shortcut> / <optgroup label> children. */
+  options: string;
   /** Placeholder text for the search input */
   placeholder: string;
 

package/components/command/command.yaml

@@ -24,6 +24,24 @@ props:
     description: Placeholder text for the search input
     type: string
     default: Type a command...
+  options:
+    description: >-
+      Programmatic item list. Array of {value, label, icon?, shortcut?,
+      disabled?} or grouped {label, options:[…]}. `icon` renders as a
+      leading icon-ui, `shortcut` as a trailing keyboard-shortcut hint —
+      the same fields as the data-icon/data-shortcut attributes on
+      declarative <option> children. Alternative to declarative
+      <option data-icon data-shortcut> / <optgroup label> children.
+    type: array
+    # Rich option OBJECTS ({value, label, icon?, …} / grouped) — declares
+    # items.type so the a2ui catalog maps to DynamicObjectList, not the
+    # string-list default (components.mjs TKT-0010 mapping). Without this
+    # the dialect validator rejected every harvested rich-options palette
+    # (exit-gate.corpus caught it at release pre-flight).
+    items:
+      type: object
+    default: []
+    dynamic: true  # JS-set collection prop with a custom setter — mirrors combobox-ui's `options`
 events:
   dismiss:
     description: Fired when Escape is pressed
@@ -69,9 +87,13 @@ a2ui:
       shortcut. Do NOT hand-roll a <dialog> + Cmd+K key listener.
     - >-
       Author items as native <option value data-icon data-shortcut>
-      elements inside <optgroup label="…"> for grouped sections. The
-      `select` event's detail.category mirrors the parent optgroup's
-      label. Detail = { value, label, category }.
+      elements inside <optgroup label="…"> for grouped sections, OR set
+      `.options` programmatically as an array of
+      `{value, label, icon?, shortcut?, disabled?}` (grouped form:
+      `{label, options:[…]}`) — same fields, alternative to declarative
+      children. The `select` event's detail.category mirrors the parent
+      optgroup's label (or the group's `label` when authored via
+      `options`). Detail = { value, label, category }.
     - >-
       Decision rule vs adjacent surfaces. Use <menu-ui> for small
       NON-searchable popover menus (≤10 actions, triggered by a

package/components/date-range-picker/date-range-picker.a2ui.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://adiaui.dev/a2ui/v0_9/components/DateRangePicker.json",
   "title": "DateRangePicker",
-  "description": "Compound form primitive for selecting a start + end date pair with optional named preset shortcuts (\"Today\", \"Last 7 days\", \"This month\", ...). Default presentation is a trigger button showing the formatted range; on activation a popover opens with two synchronized calendar panes + a preset side rail. Composes <calendar-picker-ui> twice; emits {from, to} ISO 8601 dates. Optional comparison-range mode emits a secondary range for analytics surfaces.",
+  "description": "Compound form primitive for selecting a start + end date pair with optional named preset shortcuts (\"Today\", \"Last 7 days\", \"This month\", ...). Default presentation is a trigger button showing the formatted range; on activation a popover opens with two synchronized calendar panes + a preset side rail. Composes <calendar-grid-ui> twice; emits {from, to} ISO 8601 dates. Both panes are ONE selection surface: first click = start, second click = end, in either grid; a second click earlier than the start restarts the range there. Optional comparison-range mode emits a secondary range for analytics surfaces.",
   "type": "object",
   "allOf": [
     {

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

@@ -15,9 +15,12 @@
  * <date-range-picker-ui>
  *
  * Compound form primitive for selecting a start + end date pair with
- * optional preset shortcuts. Composes <calendar-picker-ui> (two
- * instances — start + end pane) + <popover-ui> + <button-ui> for the
- * trigger and preset rail.
+ * optional preset shortcuts. Composes <calendar-grid-ui> (two panes
+ * showing adjacent months) + <popover-ui> + <button-ui> for the
+ * trigger and preset rail. Selection is click-start-then-click-end
+ * across BOTH panes as one surface (gh#948) — the panes differ only
+ * in which month they display, never in which half of the range a
+ * click writes.
  *
  * Form participation:
  *   ElementInternals serializes the selected range as JSON:
@@ -345,8 +348,8 @@ export class UIDateRangePicker extends UIFormElement {
       this.#triggerRef.addEventListener('keydown', this.#onTriggerKey, true);
       this.#popoverRef.addEventListener('click', this.#onPopoverClick);
       this.#popoverRef.addEventListener('keydown', this.#onPopoverKey);
-      this.#calFromRef.addEventListener('change', this.#onCalFromChange);
-      this.#calToRef.addEventListener('change', this.#onCalToChange);
+      this.#calFromRef.addEventListener('change', this.#onDaySelect);
+      this.#calToRef.addEventListener('change', this.#onDaySelect);
     }
     // Wire form value on first connect.
     this.syncValue();
@@ -364,8 +367,8 @@ export class UIDateRangePicker extends UIFormElement {
       this.#popoverRef.removeEventListener('keydown', this.#onPopoverKey);
       this.#popoverRef.hidePopover?.();
     }
-    if (this.#calFromRef) this.#calFromRef.removeEventListener('change', this.#onCalFromChange);
-    if (this.#calToRef) this.#calToRef.removeEventListener('change', this.#onCalToChange);
+    if (this.#calFromRef) this.#calFromRef.removeEventListener('change', this.#onDaySelect);
+    if (this.#calToRef) this.#calToRef.removeEventListener('change', this.#onDaySelect);
     document.removeEventListener('pointerdown', this.#onOutside);
     document.removeEventListener('keydown', this.#onDocKey);
     this.#anchorCleanup?.();
@@ -449,14 +452,16 @@ export class UIDateRangePicker extends UIFormElement {
     // Cascade min/max + selection state into the calendar panes.
     const range = parseRange(this.value);
     const pending = this.#pending;
-    // Effective endpoints — pending (mid-click) takes precedence over
-    // value. Push the SAME from/to onto BOTH grids so each independently
-    // lights up its in-range cells via `[data-in-range]`. Without this,
-    // only the two endpoint cells got `[data-selected]` and the days
-    // between them rendered as plain background — the "fill the cells
-    // between start and end dates" trap.
-    const effFrom = pending?.from || range?.from || '';
-    const effTo   = pending?.to   || range?.to   || '';
+    // Effective endpoints — an in-flight pending selection REPLACES the
+    // committed value wholesale (no per-half fallback: mixing the new
+    // start with the old committed end would light a range the user
+    // never picked, gh#948). Push the SAME from/to onto BOTH grids so
+    // each independently lights up its in-range cells via
+    // `[data-in-range]`. Without this, only the two endpoint cells got
+    // `[data-selected]` and the days between them rendered as plain
+    // background — the "fill the cells between start and end dates" trap.
+    const effFrom = pending ? pending.from : (range?.from || '');
+    const effTo   = pending ? pending.to   : (range?.to   || '');
     const setRangeAttrs = (cal) => {
       if (effFrom) cal.setAttribute('range-start', effFrom);
       else cal.removeAttribute('range-start');
@@ -466,13 +471,13 @@ export class UIDateRangePicker extends UIFormElement {
     if (this.#calFromRef) {
       if (this.min) this.#calFromRef.setAttribute('min', this.min);
       if (this.max) this.#calFromRef.setAttribute('max', this.max);
-      this.#calFromRef.value = pending?.from || range?.from || '';
+      this.#calFromRef.value = effFrom;
       setRangeAttrs(this.#calFromRef);
     }
     if (this.#calToRef) {
       if (this.min) this.#calToRef.setAttribute('min', this.min);
       if (this.max) this.#calToRef.setAttribute('max', this.max);
-      this.#calToRef.value = pending?.to || range?.to || '';
+      this.#calToRef.value = effTo;
       setRangeAttrs(this.#calToRef);
     }
 
@@ -680,37 +685,31 @@ export class UIDateRangePicker extends UIFormElement {
     }
   };
 
-  #onCalFromChange = (e) => {
+  // Unified day selection across BOTH grids — first click = start,
+  // second click = end, whichever pane the click lands in (gh#948).
+  // The panes' [data-cal-from]/[data-cal-to] roles are display-only
+  // (left month / next month); they no longer lock which half of the
+  // range a click writes. A second click EARLIER than the pending start
+  // restarts the selection at that day (the industry-standard dual-pane
+  // model) instead of emitting a reversed-range `invalid`. A click
+  // while a range is already committed starts a fresh selection.
+  #onDaySelect = (e) => {
     if (this.readonly) return;
     e.stopPropagation();
-    const iso = e.detail?.value || this.#calFromRef?.value || '';
+    const iso = e.detail?.value || '';
     if (!iso) return;
-    const existing = parseRange(this.value);
-    if (!this.#pending) this.#pending = { from: '', to: '' };
-    this.#pending.from = iso;
-    // Live emit `input` for pending state.
-    this.dispatchEvent(new CustomEvent('input', { bubbles: true, detail: { value: { from: iso, to: null } } }));
-    // Attempt commit when both halves are set (in either order). The
-    // commit path handles reversed-range invalidation.
-    const toCandidate = this.#pending.to || existing?.to || null;
-    if (toCandidate) {
-      this.#commitRange({ from: iso, to: toCandidate });
+    const startFresh =
+      !this.#pending?.from ||           // nothing pending (incl. committed-value state)
+      this.#pending.to ||               // previous selection fully picked
+      iso < this.#pending.from;         // earlier than pending start → restart there
+    if (startFresh) {
+      this.#pending = { from: iso, to: '' };
+      this.dispatchEvent(new CustomEvent('input', { bubbles: true, detail: { value: { from: iso, to: null } } }));
+      return;
     }
-  };
-
-  #onCalToChange = (e) => {
-    if (this.readonly) return;
-    e.stopPropagation();
-    const iso = e.detail?.value || this.#calToRef?.value || '';
-    if (!iso) return;
-    const existing = parseRange(this.value);
-    if (!this.#pending) this.#pending = { from: '', to: '' };
     this.#pending.to = iso;
-    this.dispatchEvent(new CustomEvent('input', { bubbles: true, detail: { value: { from: this.#pending.from || existing?.from || null, to: iso } } }));
-    const fromCandidate = this.#pending.from || existing?.from || null;
-    if (fromCandidate) {
-      this.#commitRange({ from: fromCandidate, to: iso });
-    }
+    this.dispatchEvent(new CustomEvent('input', { bubbles: true, detail: { value: { from: this.#pending.from, to: iso } } }));
+    this.#commitRange({ from: this.#pending.from, to: iso });
   };
 
   #onOutside = (e) => {

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

@@ -158,6 +158,17 @@ date-range-picker-ui [slot="popover"] {
   /* Opt into a wider anchor.js max-width cap so both month panes fit side-by-side
      (the 32rem default clipped the second month). Viewport safety still applies. */
   --popover-max-width: var(--date-range-picker-popover-max-width);
+  /* Content sizing lives in the STYLESHEET, not only in anchor.js inline
+     styles (gh#948): only the native-anchor path applies width/max-width
+     hints inline — the JS fallback (Safari/Firefox) and any placement
+     where anchoring fails otherwise leave the popover's size to whatever
+     the surrounding cascade produces, which is how the viewport-huge
+     mostly-empty panel renders. These caps make the popover content-sized
+     in every path; anchor.js inline styles still win where they apply. */
+  width: max-content;
+  max-width: min(calc(100vw - 1rem), var(--date-range-picker-popover-max-width));
+  max-height: calc(100vh - 2rem);
+  overflow: auto;
   padding: var(--date-range-picker-py) var(--date-range-picker-px);
   border: 1px solid var(--date-range-picker-popover-border);
   border-radius: var(--date-range-picker-popover-radius);

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

@@ -10,9 +10,12 @@ description: >-
   optional named preset shortcuts ("Today", "Last 7 days", "This month",
   ...). Default presentation is a trigger button showing the formatted
   range; on activation a popover opens with two synchronized calendar
-  panes + a preset side rail. Composes <calendar-picker-ui> twice;
-  emits {from, to} ISO 8601 dates. Optional comparison-range mode
-  emits a secondary range for analytics surfaces.
+  panes + a preset side rail. Composes <calendar-grid-ui> twice;
+  emits {from, to} ISO 8601 dates. Both panes are ONE selection
+  surface: first click = start, second click = end, in either grid;
+  a second click earlier than the start restarts the range there.
+  Optional comparison-range mode emits a secondary range for
+  analytics surfaces.
 # Per ADR-0027 — primitives that programmatically create other primitives
 # do NOT auto-import them. Consumer (or demo shell) must explicitly import.
 composes:

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

@@ -6,10 +6,21 @@
     --description-list-term-min-width: 8rem;
 
     /* ── Typography ── */
-    --description-list-term-font-size: var(--a-ui-sm);
-    --description-list-term-weight:    var(--a-weight-medium);
-    --description-list-desc-font-size: var(--a-ui-sm);
-    --description-list-desc-weight:    var(--a-weight-normal);
+    /* Term reads as a kicker/data-label (operator ruling 2026-08-11,
+       matching the docs site's [data-label] convention): code family at
+       label size, normal weight — a quiet technical eyebrow the medium-
+       weight desc answers. */
+    --description-list-term-font-family: var(--a-font-family-code);
+    --description-list-term-font-size: var(--a-label-size);
+    --description-list-term-weight:    var(--a-weight-normal);
+    /* 1em, not a fixed step — the desc inherits the surrounding body/
+       context size (operator ruling 2026-08-11), so a dl inside prose
+       matches the prose and inside a compact card matches the card. */
+    --description-list-desc-font-size: 1em;
+    /* Semibold — the desc (value) carries the pair's content and reads
+       clearly bolder than the muted normal-weight kicker term (operator
+       rulings 2026-08-11: first normal → medium, then medium → semibold). */
+    --description-list-desc-weight:    var(--a-weight-semibold);
 
     /* ── Colors ── */
     --description-list-term-fg:        var(--a-fg-muted);
@@ -29,6 +40,7 @@
   [data-dl-term],
   dt {
     margin: 0;
+    font-family: var(--description-list-term-font-family);
     font-size: var(--description-list-term-font-size);
     font-weight: var(--description-list-term-weight);
     color: var(--description-list-term-fg);

package/components/integration-card/integration-card.class.js

@@ -48,11 +48,14 @@ const ACTION_FOR_STATUS = Object.freeze({
   pending:       { event: 'press',     emits: '',           label: 'Connecting…', variant: 'outline', icon: '' },
 });
 
+// `coming-soon` is a family-less badge, tone="muted" — `variant="muted"`
+// retired (variant/color/tone convention cut, gh#873/874); `#renderStatusBadge()`
+// below branches on `variant` vs. absent.
 const BADGE_FOR_STATUS = Object.freeze({
   connected:    { variant: 'success', text: 'Connected',   icon: 'check' },
   error:        { variant: 'danger',  text: 'Error',       icon: 'warning-circle' },
   pending:      { variant: 'info',    text: 'Connecting…', icon: '' },
-  'coming-soon':{ variant: 'muted',   text: 'Coming soon', icon: '' },
+  'coming-soon':{ text: 'Coming soon', icon: '' },
 });
 
 // Fallback glyph per known provider when no explicit [logo] is supplied, so
@@ -312,7 +315,13 @@ export class UIIntegrationCard extends UIElement {
       return;
     }
     this.#statusEl.hidden = false;
-    this.#statusEl.setAttribute('variant', cfg.variant);
+    if (cfg.variant) {
+      this.#statusEl.setAttribute('variant', cfg.variant);
+      this.#statusEl.removeAttribute('tone');
+    } else {
+      this.#statusEl.removeAttribute('variant');
+      this.#statusEl.setAttribute('tone', 'muted');
+    }
     this.#statusEl.setAttribute('text', cfg.text);
     this.#statusEl.setAttribute('size', 'sm');
     if (cfg.icon) this.#statusEl.setAttribute('icon', cfg.icon);

package/components/mark/mark.a2ui.json

@@ -17,14 +17,13 @@
       "const": "Mark"
     },
     "variant": {
-      "description": "Highlight color variant. Default `warning` is the conventional yellow-marker tone.",
+      "description": "Highlight color family — the only color axis mark exposes. Default `warning` is the conventional yellow-marker tone and IS mark's family-less identity, so there is no `default` member. For a neutral (non-semantic) highlight, override the public tokens instead of the variant: `--mark-bg: var(--a-bg-muted); --mark-fg: var(--md-sys-color-neutral-on-surface)` — the successor to the retired `variant=\"muted\"` (gh#881).",
       "type": "string",
       "enum": [
         "warning",
         "info",
         "success",
-        "danger",
-        "muted"
+        "danger"
       ],
       "default": "warning"
     }
@@ -87,12 +86,12 @@
     "tag": "mark-ui",
     "tokens": {
       "--mark-bg": {
-        "description": "Background color of the highlight.",
-        "default": "var(--a-warning-muted)"
+        "description": "Background color of the highlight. Override for a non-semantic (e.g. neutral) highlight — see [variant].",
+        "default": "var(--md-sys-color-warning-container)"
       },
       "--mark-fg": {
-        "description": "Foreground (text) color inside the highlight.",
-        "default": "var(--a-warning-text)"
+        "description": "Foreground (text) color inside the highlight. Pair every [--mark-bg] override with a matching fg so contrast holds in both schemes.",
+        "default": "var(--md-sys-color-warning-on-surface)"
       },
       "--mark-px": {
         "description": "Horizontal padding around the highlighted text.",

package/components/mark/mark.class.js

@@ -8,7 +8,7 @@ import { UIElement } from '../../core/element.js';
 
 export class UIMark extends UIElement {
   static properties = {
-    variant: { type: String, default: 'warning', reflect: true }, // warning | info | success | danger | muted
+    variant: { type: String, default: 'warning', reflect: true }, // warning | info | success | danger
   };
 
   static template = () => null;

package/components/mark/mark.css

@@ -32,8 +32,11 @@
     --mark-bg: var(--md-sys-color-danger-container);
     --mark-fg: var(--md-sys-color-danger-on-surface);
   }
-  :scope[variant="muted"] {
-    --mark-bg: var(--a-bg-muted);
-    --mark-fg: var(--md-sys-color-neutral-on-surface);
-  }
+
+  /* NB `variant` is mark's ONLY color axis and it is family-only
+     (gh#881, the two-axis convention). The former `variant="muted"`
+     neutral highlight is retired; its successor is the public token
+     override — `--mark-bg: var(--a-bg-muted); --mark-fg:
+     var(--md-sys-color-neutral-on-surface)` — so a non-semantic
+     highlight no longer needs an enum member of its own. */
 }

package/components/mark/mark.d.ts

@@ -22,6 +22,6 @@ background highlight behind the matched span.
 import { UIElement } from '../../core/element.js';
 
 export class UIMark extends UIElement {
-  /** Highlight color variant. Default `warning` is the conventional yellow-marker tone. */
-  variant: 'warning' | 'info' | 'success' | 'danger' | 'muted';
+  /** Highlight color family — the only color axis mark exposes. Default `warning` is the conventional yellow-marker tone and IS mark's family-less identity, so there is no `default` member. For a neutral (non-semantic) highlight, override the public tokens instead of the variant: `--mark-bg: var(--a-bg-muted); --mark-fg: var(--md-sys-color-neutral-on-surface)` — the successor to the retired `variant="muted"` (gh#881). */
+  variant: 'warning' | 'info' | 'success' | 'danger';
 }

package/components/mark/mark.examples.md

@@ -42,10 +42,6 @@
     <mark-ui variant="danger">danger</mark-ui>
     — removed line, conflict.
   </text-ui>
-  <text-ui>
-    <mark-ui variant="muted">muted</mark-ui>
-    — neutral emphasis.
-  </text-ui>
 </col-ui>
 ```
 

package/components/mark/mark.yaml

@@ -17,7 +17,14 @@ description: |
   background highlight behind the matched span.
 props:
   variant:
-    description: Highlight color variant. Default `warning` is the conventional yellow-marker tone.
+    description: >-
+      Highlight color family — the only color axis mark exposes. Default
+      `warning` is the conventional yellow-marker tone and IS mark's
+      family-less identity, so there is no `default` member. For a
+      neutral (non-semantic) highlight, override the public tokens
+      instead of the variant: `--mark-bg: var(--a-bg-muted);
+      --mark-fg: var(--md-sys-color-neutral-on-surface)` — the successor
+      to the retired `variant="muted"` (gh#881).
     type: string
     default: warning
     enum:
@@ -25,7 +32,6 @@ props:
       - info
       - success
       - danger
-      - muted
     reflect: true
 events: {}
 slots:
@@ -37,11 +43,15 @@ states:
 traits: []
 tokens:
   --mark-bg:
-    description: Background color of the highlight.
-    default: var(--a-warning-muted)
+    description: >-
+      Background color of the highlight. Override for a non-semantic
+      (e.g. neutral) highlight — see [variant].
+    default: var(--md-sys-color-warning-container)
   --mark-fg:
-    description: Foreground (text) color inside the highlight.
-    default: var(--a-warning-text)
+    description: >-
+      Foreground (text) color inside the highlight. Pair every [--mark-bg]
+      override with a matching fg so contrast holds in both schemes.
+    default: var(--md-sys-color-warning-on-surface)
   --mark-px:
     description: Horizontal padding around the highlighted text.
     default: var(--a-space-0-5)

package/components/modal/modal.class.js

@@ -51,6 +51,12 @@ export class UIModal extends UIElement {
   #closeTimer = null;
   #dialogRef = null;
 
+  // Monotonic, instance-agnostic counter for the fallback aria-labelledby
+  // id stamped onto an author's [slot="heading"] (see render()) — multiple
+  // <modal-ui> instances on one page must not collide on the same id.
+  // (Extracted from PR #944 — gh#947.)
+  static #headingIdSeq = 0;
+
   // Phosphor icons this primitive auto-stamps (without consumer markup).
   // Aggregated by installIconLoadersForRegistered() across all defined
   // elements. Audited by check-required-icons.mjs.
@@ -150,8 +156,25 @@ export class UIModal extends UIElement {
     const panel = this.ensure('panel');
     if (panel.parentElement !== dialog) dialog.appendChild(panel);
 
-    const header = this.ensure('header');
-    if (header.parentElement !== panel) panel.prepend(header);
+    // Header — accept an authored bare <header> or [slot="header"] child
+    // (card-ui style), mirroring the footer contract below. Without this
+    // branch an authored <header> fell through to the loose-children
+    // migration and rendered inside the BODY, displacing icon/heading to
+    // the bottom of the modal (gh#941).
+    const userHeader = [...this.children].find(c =>
+      c.getAttribute('slot') === 'header' || (!c.getAttribute('slot') && c.localName === 'header')
+    );
+    let header;
+    if (userHeader) {
+      if (userHeader.getAttribute('slot') !== 'header') userHeader.setAttribute('slot', 'header');
+      if (userHeader.parentElement !== panel) panel.prepend(userHeader);
+      panel.querySelector(':scope > [slot="header"][data-stamped]')?.remove();
+      header = userHeader;
+    } else {
+      header = this.ensure('header');
+      header.setAttribute('data-stamped', '');
+      if (header.parentElement !== panel) panel.prepend(header);
+    }
     // Only set `text=` when actually present — the CSS rule
     // `:scope [slot="header"][text]:not([text=""])::before { content: attr(text); flex: 1 }`
     // generates a flex:1 pseudo-element. Setting `text=""` unconditionally
@@ -165,6 +188,24 @@ export class UIModal extends UIElement {
       header.removeAttribute('text');
     }
 
+    // Accessible name — [text] stamps aria-label (host + dialog), the
+    // long-standing contract above. Absent that, fall back to the author's
+    // [slot="heading"] via aria-labelledby so a heading-only modal (e.g.
+    // destructive-confirm-modal, gh#941) still satisfies the WAI-ARIA APG
+    // dialog-modal pattern's accessible-name requirement. Re-evaluated
+    // every render so a later `text=` set, or the heading being removed,
+    // clears the reference instead of leaving it stale. (gh#947, from
+    // PR #944.)
+    const authoredHeading = header.querySelector(':scope > [slot="heading"]');
+    if (!this.text && authoredHeading) {
+      if (!authoredHeading.id) authoredHeading.id = `modal-heading-${++UIModal.#headingIdSeq}`;
+      if (dialog.getAttribute('aria-labelledby') !== authoredHeading.id) {
+        dialog.setAttribute('aria-labelledby', authoredHeading.id);
+      }
+    } else {
+      dialog.removeAttribute('aria-labelledby');
+    }
+
     if (!this.permanent) {
       const close = this.ensure('close');
       if (close.parentElement !== header) header.appendChild(close);

package/components/modal/modal.css

@@ -131,6 +131,29 @@
     flex: 1;
   }
 
+  /* ═══════ Header icon + heading pair (drawer-ui/card-ui parity) ═══════
+     Author-supplied icon/heading content nested inside <header> — an
+     alternative to [text]. Positioned by tag + DOM order, not by reading
+     [slot="icon"]/[slot="heading"] (AGENTS.md: "slot= attributes are
+     decorative metadata; positioning is CSS by tag + ancestor + DOM
+     order") — `button-ui` identifies the stamped auto-close affordance by
+     TAG, and render() guarantees it's the header's trailing child when
+     present. The header's last non-button child claims the row's free
+     space (heading position); any earlier content child (a leading
+     icon/avatar) stays fixed-width. (gh#947, from PR #944.) */
+  :scope [slot="header"] > :not(button-ui):has(~ :not(button-ui)) {
+    display: flex;
+    align-items: center;
+    flex-shrink: 0;
+  }
+  :scope [slot="header"] > :not(button-ui):not(:has(~ :not(button-ui))) {
+    display: flex;
+    align-items: center;
+    gap: var(--a-space-2);
+    flex: 1;
+    min-width: 0;
+  }
+
   /* ═══════ Close button (button-ui) ═══════ */
   :scope [slot="close"] {
     flex-shrink: 0;

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

@@ -10,13 +10,22 @@
     --nav-group-font-size-sm:  var(--a-ui-sm);
     --nav-group-font-size-lg:  var(--a-ui-lg);
     --nav-group-font-weight:   var(--a-weight-normal);
-    --nav-group-fg:            var(--md-sys-color-neutral-on-surface);
+    /* State color spec (gh#968, operator ruling 2026-08-11) — one
+       language with nav-item-ui:
+         idle     — bg transparent · icon NEUTRAL · text NEUTRAL-HIGH
+         hover    — bg container-low · icon + text ON-SURFACE
+         selected — bg container · icon + text ON-SURFACE
+       The selected icon no longer takes primary (supersedes gh#522's
+       glyph ruling); Figma's neutral/surfaceBright was considered for the
+       selected fill and RULED OUT — container stays (gh#795's mirror). */
+    --nav-group-fg:            var(--md-sys-color-neutral-high);
     --nav-group-fg-hover:      var(--a-fg-strong);
     --nav-group-fg-muted:      var(--a-fg-muted);
     --nav-group-fg-selected:   var(--a-fg-strong);
-    --nav-group-icon-fg-selected: var(--md-sys-color-primary); /* one selection color with --nav-item-accent (gh#522) */
+    --nav-group-icon-fg:       var(--md-sys-color-neutral);
+    --nav-group-icon-fg-selected: var(--a-fg-strong);
     --nav-group-bg-hover:      var(--a-bg-muted);
-    --nav-group-bg-selected:   var(--a-bg-selected); /* mirrors --nav-item-bg-selected — the missing container fill (gh#795) */
+    --nav-group-bg-selected:   var(--a-bg-selected); /* mirrors --nav-item-bg-selected (gh#795) */
     --nav-group-icon-size:     calc(var(--nav-group-row-height) - var(--a-space-2));
     --nav-group-badge-size:    var(--a-ui-sm);
 
@@ -119,7 +128,9 @@
     width: var(--nav-group-icon-size);
     height: var(--nav-group-icon-size);
     flex-shrink: 0;
-    color: var(--nav-group-fg-muted);
+    /* idle icon = NEUTRAL (gh#968 state spec), one step quieter than the
+       header's neutral-high text. */
+    color: var(--nav-group-icon-fg);
     transition: color var(--nav-duration-fast) var(--nav-easing);
     display: flex;
     align-items: center;