@adia-ai/web-components 0.8.33 → 0.8.35

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/demo-toggle/demo-toggle.css

@@ -39,6 +39,10 @@
 
   /* -- Header bar -- */
   [slot="bar"] {
+    /* ensure('bar') APPENDS the bar after the authored slot content —
+       flex order puts it visually first (gh#1075: it rendered at the
+       bottom of the card, under the stage, without this). */
+    order: -1;
     width: 100%;
     padding: var(--demo-toggle-bar-py) var(--demo-toggle-bar-px);
     background: var(--demo-toggle-bar-bg);

package/components/demo-toggle/demo-toggle.examples.md

@@ -4,8 +4,8 @@
 
 ```html
 <demo-toggle-ui label-on="With trait" label-off="Without trait" initial="off">
-  <div slot="off" style="padding:var(--a-space-4);text-align:center;color:var(--a-fg-muted);">Bare surface — no trait attached.</div>
-  <div slot="on" style="padding:var(--a-space-4);text-align:center;color:var(--md-sys-color-neutral-on-surface);">Same surface, with trait attached.</div>
+  <div slot="off" style="text-align:center;color:var(--a-fg-muted);">Bare surface — no trait attached.</div>
+  <div slot="on" style="text-align:center;color:var(--md-sys-color-neutral-on-surface);">Same surface, with trait attached.</div>
 </demo-toggle-ui>
 ```
 
@@ -13,7 +13,7 @@
 
 ```html
 <demo-toggle-ui label-on="With shimmer-loading" label-off="Without shimmer-loading">
-  <div slot="off" style="padding:var(--a-space-4);">Placeholder content (no trait)</div>
-  <div slot="on" style="padding:var(--a-space-4);">Placeholder content (shimmer active)</div>
+  <div slot="off">Placeholder content (no trait)</div>
+  <div slot="on">Placeholder content (shimmer active)</div>
 </demo-toggle-ui>
 ```

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/feed/feed-item.a2ui.json

@@ -47,14 +47,15 @@
       "default": ""
     },
     "variant": {
-      "description": "Semantic variant",
+      "description": "Semantic variant — `default | info | success | warning | danger | primary`. `primary` is the brand-emphasis fill (accent-filled bg + on-accent text), ported from toast.css's `primary` variant (gh#1104) now that feed-item-ui is the real paint site for posted toasts.",
       "type": "string",
       "enum": [
         "default",
         "info",
         "success",
         "warning",
-        "danger"
+        "danger",
+        "primary"
       ],
       "default": "default"
     }

package/components/feed/feed-item.yaml

@@ -25,7 +25,12 @@ props:
     type: string
     default: ""
   variant:
-    description: Semantic variant
+    description: >-
+      Semantic variant — `default | info | success | warning | danger |
+      primary`. `primary` is the brand-emphasis fill (accent-filled bg +
+      on-accent text), ported from toast.css's `primary` variant
+      (gh#1104) now that feed-item-ui is the real paint site for
+      posted toasts.
     type: string
     default: default
     enum:
@@ -34,6 +39,7 @@ props:
       - success
       - warning
       - danger
+      - primary
   duration:
     description: Auto-fade timer in ms; null/0 = sticky (requires user input)
     type: number

package/components/feed/feed.css

@@ -99,7 +99,16 @@ feed-item-ui[data-closing] {
 /* Item — atomic feed entry. */
 @scope (feed-item-ui) {
   :where(:scope) {
-    --feed-item-bg:       var(--md-sys-color-neutral-background);
+    /* -container-high (NOT plain -background/-container) — a top-layer
+       overlay item needs a tonal step strong enough to read as its own
+       elevated surface against arbitrary page content behind it
+       (gh#1091). Plain -background is literally the page's own bg
+       token, so an un-varianted item had ZERO tonal separation. Every
+       family (incl. neutral) has a generated -container-high role in
+       colors/material-static.css — the same tier `--a-{family}-subtle`
+       aliases to (component-token-contract.md's `-strong` semantics
+       note). */
+    --feed-item-bg:       var(--md-sys-color-neutral-container-high);
     --feed-item-fg:       var(--md-sys-color-neutral-on-surface);
     --feed-item-border:   var(--md-sys-color-neutral-outline-variant);
     --feed-item-radius:   var(--a-radius-md);
@@ -117,10 +126,20 @@ feed-item-ui[data-closing] {
      NOT --a-{variant}-fg (= --a-{variant}-text-strong, locked for solid
      --variant-strong fills) — pairing a locked fg with a flipping bg goes
      low-contrast in one scheme. Mirrors alert.css + toast.css wiring. */
-  :scope[variant="info"]    { --feed-item-fg: var(--md-sys-color-info-on-surface);    --feed-item-bg: var(--md-sys-color-info-container); }
-  :scope[variant="success"] { --feed-item-fg: var(--md-sys-color-success-on-surface); --feed-item-bg: var(--md-sys-color-success-container); }
-  :scope[variant="warning"] { --feed-item-fg: var(--md-sys-color-warning-on-surface); --feed-item-bg: var(--md-sys-color-warning-container); }
-  :scope[variant="danger"]  { --feed-item-fg: var(--md-sys-color-danger-on-surface);  --feed-item-bg: var(--md-sys-color-danger-container); }
+  :scope[variant="info"]    { --feed-item-fg: var(--md-sys-color-info-on-surface);    --feed-item-bg: var(--md-sys-color-info-container-high); }
+  :scope[variant="success"] { --feed-item-fg: var(--md-sys-color-success-on-surface); --feed-item-bg: var(--md-sys-color-success-container-high); }
+  :scope[variant="warning"] { --feed-item-fg: var(--md-sys-color-warning-on-surface); --feed-item-bg: var(--md-sys-color-warning-container-high); }
+  :scope[variant="danger"]  { --feed-item-fg: var(--md-sys-color-danger-on-surface);  --feed-item-bg: var(--md-sys-color-danger-container-high); }
+  /* `primary` — the accent-filled "branded" tone (welcome banners,
+     feature-launch nudges), ported from toast.css's `primary` variant
+     (gh#1104 — toast.css documented this but its rules never paint;
+     feed-item-ui is the real render surface post-migration). No
+     border override, matching this block's existing two-property
+     shape (unlike toast.css's variant block, which does override
+     border). Deliberately NOT the -container-high convention above —
+     primary is a stronger/bolder branded solid-fill per gh#1104's own
+     acceptance criteria, not a softer semantic-status tone. */
+  :scope[variant="primary"] { --feed-item-fg: var(--md-sys-color-primary-on-primary); --feed-item-bg: var(--a-primary-bg); }
 
   :scope {
     box-sizing: border-box;
@@ -143,6 +162,10 @@ feed-item-ui[data-closing] {
     opacity: 0;
     transform: translateY(0.5rem);
     pointer-events: auto;
+    /* Elevated-surface separation over busy page content (gh#1091) —
+       mirrors loading-overlay.css's [variant="blur"] treatment. */
+    backdrop-filter: blur(4px);
+    -webkit-backdrop-filter: blur(4px);
   }
   :scope [slot="body"] {
     flex: 1;

package/components/field/field.examples.md

@@ -13,8 +13,8 @@
 ```html
 <row-ui gap="6" align="start" wrap>
   <col-ui gap="2">
-    <text-ui variant="caption" color="muted">verse</text-ui>
-    <div verse style="width:220px">
+    <text-ui variant="caption" color="muted">scale="ui-sm"</text-ui>
+    <div scale="ui-sm" style="width:220px">
       <field-ui label="Email">
         <input-ui type="email" placeholder="you@example.com"></input-ui>
       </field-ui>
@@ -29,8 +29,8 @@
     </div>
   </col-ui>
   <col-ui gap="2">
-    <text-ui variant="caption" color="muted">prose</text-ui>
-    <div prose style="width:220px">
+    <text-ui variant="caption" color="muted">scale="content-md"</text-ui>
+    <div scale="content-md" style="width:220px">
       <field-ui label="Email">
         <input-ui type="email" placeholder="you@example.com"></input-ui>
       </field-ui>

package/components/image/image.class.js

@@ -66,6 +66,14 @@ export class UIImage extends UIElement {
     }
     this.#img.addEventListener('load', this.#onLoad);
     this.#img.addEventListener('error', this.#onError);
+    // Missed-load guard (gh#999): an image already complete when these
+    // listeners attach — a parse-time-loaded authored [slot="image"], or a
+    // cache hit racing the upgrade — fired `load` before we were listening.
+    // Without this check [data-loaded] never stamps and the reveal
+    // (skeleton → img opacity 1) never happens: the permanent blank box
+    // gh#988 reported. naturalWidth guards the broken-image case, which
+    // fires `error` (still listened) rather than a false reveal.
+    if (this.#img.complete && this.#img.naturalWidth > 0) this.#onLoad();
 
     this.#applySize();
   }

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,15 +10,32 @@
     --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);
+    /* Continuous indent rail color (gh#1016) — was referenced at the
+       ::after usage site below but never given a base value here, the
+       same empty-var failure class --nav-gap already documents in this
+       file: an undefined custom property resolves to the guaranteed-
+       invalid value, so `background: var(--nav-group-indent-rail-bg)`
+       painted nothing. Same house role accordion, agent- components,
+       chart etc. use for subtle structural lines. */
+    --nav-group-indent-rail-bg: var(--md-sys-color-neutral-outline-variant);
 
     --nav-item-child-height:    var(--a-size-sm);
     --nav-item-child-font:      var(--nav-group-font-size);
@@ -48,7 +65,10 @@
     top: var(--nav-group-row-height);
     bottom: calc(var(--nav-group-row-height) / 2);
     width: 1px;
-    background: var(--nav-group-indent-rail-bg);
+    /* Explicit fallback — same defensive shape --nav-gap got above —
+       so an ancestor/override cascade that sets this token to an empty
+       string still paints a rail instead of silently disappearing. */
+    background: var(--nav-group-indent-rail-bg, var(--md-sys-color-neutral-outline-variant));
     pointer-events: none;
   }
   /* Selected-look header treatment keys on [selected] — the CSS half of
@@ -119,7 +139,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;

package/components/nav-item/nav-item.css

@@ -40,11 +40,19 @@ nav-item-ui[selected] [slot="icon"]:empty::before {
     --nav-item-font-size-sm:    var(--a-ui-sm);
     --nav-item-font-size-lg:    var(--a-ui-lg);
     --nav-item-font-weight:     var(--a-weight-normal);
-    --nav-item-fg:              var(--a-ui-text-subtle);
+    /* State color spec (gh#968, operator ruling 2026-08-11):
+         idle     — bg transparent · icon NEUTRAL · text NEUTRAL-HIGH
+         hover    — bg container-low · icon + text ON-SURFACE
+         selected — bg container · icon + text ON-SURFACE
+       Idle sits two quiet steps down (icon quieter than text); hover and
+       selected converge on on-surface. The selected ICON no longer takes
+       the primary accent (supersedes gh#522 for the glyph) — the accent
+       BAR remains the primary selection marker. */
+    --nav-item-fg:              var(--md-sys-color-neutral-high);
     --nav-item-fg-hover:        var(--a-ui-text-hover);
     --nav-item-fg-selected:     var(--a-ui-text-selected);
-    --nav-item-icon-fg:         var(--a-ui-text-muted);
-    --nav-item-icon-fg-selected: var(--nav-item-accent);
+    --nav-item-icon-fg:         var(--md-sys-color-neutral);
+    --nav-item-icon-fg-selected: var(--a-ui-text-selected);
     /* Two real container roles, one mechanism — no opacity synth.
        hover    = --a-bg-muted    (--md-sys-color-neutral-container-low, 10%),
                   matching nav-group-ui's own --nav-group-bg-hover exactly.

package/components/option-card/option-card.a2ui.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://adiaui.dev/a2ui/v0_9/components/OptionCard.json",
   "title": "OptionCard",
-  "description": "Selectable card with radio semantics. A \"rich radio\" — single-select one of N where each option carries a heading, optional description, and optional leading icon. Siblings sharing a `name` form a radiogroup. The whole card is the click target; a CSS-rendered radio circle in the top-left signals state. Form-associated, so `name=value` submits with the parent form when checked.",
+  "description": "Selectable card with radio semantics. A \"rich radio\" — single-select one of N where each option carries a heading, optional description, and an optional icon at the trailing end of the header row. Siblings sharing a `name` form a radiogroup. The whole card is the click target; a CSS-rendered radio circle in the top-left signals state. Renders on a container-low tonal surface (no outline as the primary boundary); the checked state keeps an accent border + fill so selection stays unmistakable. Form-associated, so `name=value` submits with the parent form when checked.",
   "type": "object",
   "allOf": [
     {
@@ -42,12 +42,12 @@
       "default": ""
     },
     "icon": {
-      "description": "Optional Phosphor icon name. Stamped as a leading <icon-ui slot=\"icon\"> when set.",
+      "description": "Optional Phosphor icon name. Stamped as a trailing <icon-ui slot=\"icon\"> when set.",
       "type": "string",
       "default": ""
     },
     "layout": {
-      "description": "Internal layout. `default` puts the indicator on the left and the icon adjacent. `tile` stacks vertically — icon top-left, indicator top-right, heading + description below — for hero pickers (source / role / plan tiles) where the icon is a primary brand cue.",
+      "description": "Internal layout. `default` puts the indicator on the left and, when [icon] is set, the icon at the trailing end of the header row alongside the heading. `tile` stacks vertically — icon top-left, indicator top-right, heading + description below — for hero pickers (source / role / plan tiles) where the icon is a primary brand cue.",
       "type": "string",
       "enum": [
         "default",
@@ -171,22 +171,22 @@
     "tag": "option-card-ui",
     "tokens": {
       "--option-card-bg": {
-        "description": "Default background."
+        "description": "Default background (container-low tonal surface, gh#1018)."
       },
       "--option-card-bg-checked": {
         "description": "Background when checked."
       },
       "--option-card-bg-hover": {
-        "description": "Hover background (non-checked)."
+        "description": "Hover background (non-checked) — one tonal step up from --option-card-bg so hover stays visibly distinct."
       },
       "--option-card-border": {
-        "description": "Default border color."
+        "description": "Default border color (transparent — the tonal bg is the primary boundary, not an outline; gh#1018)."
       },
       "--option-card-border-checked": {
         "description": "Border color when checked."
       },
       "--option-card-border-hover": {
-        "description": "Hover border color (non-checked)."
+        "description": "Hover border color (non-checked; transparent by default, matching the no-outline base)."
       },
       "--option-card-desc-color": {
         "description": "Description text color."
@@ -228,13 +228,13 @@
         "description": "Heading font weight."
       },
       "--option-card-icon-color": {
-        "description": "Leading icon color when the card is not checked."
+        "description": "Trailing icon color when the card is not checked."
       },
       "--option-card-icon-color-checked": {
-        "description": "Leading icon color when the card is checked."
+        "description": "Trailing icon color when the card is checked."
       },
       "--option-card-icon-size": {
-        "description": "Leading icon size (sets `--a-icon-size` on the slotted icon-ui)."
+        "description": "Trailing icon size (sets `--a-icon-size` on the slotted icon-ui)."
       },
       "--option-card-padding-block": {
         "description": "Vertical padding inside the card."