@adia-ai/web-components 0.8.34 → 0.8.35

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog — @adia-ai/web-components
 
+## [0.8.35] — 2026-08-13
+
+### Maintenance
+- **Source fixes this window are carried per-file below; the narrative CHANGELOG entries live with the substantive packages.** Bumped in lockstep per `scripts/release/check-lockstep.mjs`. Headline v0.8.35 work shipped in factory-DX program (scaffold boot+CSS fixes, class-B npm marketplace, consumer CI recipe, DX sweep) + audit-wave plugin hardening + ~20 component/pattern fixes. See `packages/plugins/adia-ui-factory/CHANGELOG.md#0835--2026-08-13` for details.
+- **`components/` touched in this release window** (58 file(s), e.g. `agent-questions/agent-questions.class.js`) — carried by the entries above.
+- **`dist/` bundles rebuilt** in this cut's window (4 file(s)) — regenerated from the source changes described above, not independent edits.
+- **`patterns/` touched in this release window** (43 file(s), e.g. `access-requests/access-requests.examples.html`) — carried by the entries above.
+- **`traits/` touched in this release window** (5 file(s), e.g. `anchor-positioning/anchor-positioning.examples.html`) — carried by the entries above.
+
 ## [0.8.34] — 2026-08-11
 
 ### Fixed

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

@@ -133,7 +133,6 @@ export class UIAgentQuestions extends UIElement {
     this.#submitEl = document.createElement('button-ui');
     this.#submitEl.setAttribute('text', this.submitLabel || 'Continue');
     this.#submitEl.setAttribute('variant', 'primary');
-    this.#submitEl.setAttribute('size', 'sm');
     this.#submitEl.setAttribute('disabled', '');
     if (!this.multi) this.#submitEl.hidden = true;
     this.#submitEl.addEventListener('press', this.#onSubmit);

package/components/badge/badge.css

@@ -20,8 +20,22 @@
        only radius moved. */
     --badge-radius:    var(--a-radius-full);
     --badge-px:        var(--a-space-1-5);
-    --badge-py:        var(--a-space-0-5);
+    /* gh#1084: block padding flattened toward 1px per tier — the
+       --badge-min-h floor (below) now owns the chip's vertical size, so
+       py no longer has to carry it. Was --a-space-0-5 (2px); mirrors the
+       identical tag-ui change (same rationale, tag.css). */
+    --badge-py:        var(--a-space-px);
     --badge-gap:       var(--a-space-1);
+    /* gh#1084 — min-height floor, decoupled from padding (mirrors
+       tags-input-ui's --tags-input-min-h, and tag-ui's own --tag-min-h
+       added in the same change). Component-owned fixed rem constants
+       (not density-scaled) calibrated to badge's CURRENT rendered
+       height at each tier — measured 12/15/20px sm/md/lg before this
+       change — so this is a non-regressing addition: shrinking py
+       toward 1px no longer shrinks the badge, the floor holds the line. */
+    --badge-min-h:     0.9375rem; /* 15px @ d=1 — md */
+    --badge-min-h-sm:  0.75rem;   /* 12px @ d=1 */
+    --badge-min-h-lg:  1.25rem;   /* 20px @ d=1 */
     /* One rung down the --a-ui-* scale (gh#965) — ladder shifts with it
        (sm=2xs, lg=sm) so tiers stay one rung apart. Mirrors tag-ui. */
     --badge-font-size: var(--a-ui-xs);
@@ -45,8 +59,11 @@
        and tag share this md baseline and this exact reasoning). */
     --badge-px-sm:  var(--a-space-1);
     --badge-px-lg:  var(--a-space-2);
+    /* gh#1084: py flattened toward 1px/tier now that --badge-min-h
+       floors the box — was --a-space-px/--a-space-1 (1px/4px); mirrors
+       the identical tag-ui change (tag.css). */
     --badge-py-sm:  var(--a-space-px);
-    --badge-py-lg:  var(--a-space-1);
+    --badge-py-lg:  var(--a-space-0-5);
     --badge-font-size-sm: var(--a-ui-2xs);
     --badge-font-size-lg: var(--a-ui-sm);
     text-align: start;  /* §text-align-reset — blocks inheritance from centered ancestors */
@@ -60,6 +77,10 @@
     justify-content: center;
     gap: var(--badge-gap);
     width: fit-content;
+    /* gh#1084: floor, not a fixed size — mirrors tags-input-ui's own
+       min-height and tag-ui's identical addition (tag.css). Decouples
+       the badge's vertical size from --badge-py. */
+    min-height: var(--badge-min-h);
     padding: var(--badge-py) var(--badge-px);
     background: var(--badge-bg);
     color: var(--badge-fg);
@@ -239,15 +260,18 @@
     --badge-px:        var(--badge-px-sm);
     --badge-py:        var(--badge-py-sm);
     --badge-font-size: var(--badge-font-size-sm);
+    --badge-min-h:     var(--badge-min-h-sm);
   }
   :scope[size="md"] {
     --badge-px:        var(--a-space-1-5);
-    --badge-py:        var(--a-space-0-5);
+    --badge-py:        var(--a-space-px);
     --badge-font-size: var(--a-ui-xs);
+    --badge-min-h:     0.9375rem; /* 15px @ d=1 — matches the :where(:scope) default */
   }
   :scope[size="lg"] {
     --badge-px:        var(--badge-px-lg);
     --badge-py:        var(--badge-py-lg);
     --badge-font-size: var(--badge-font-size-lg);
+    --badge-min-h:     var(--badge-min-h-lg);
   }
 }

package/components/badge/badge.examples.md

@@ -11,8 +11,8 @@
 ```html
 <row-ui gap="6" align="start" wrap>
   <col-ui gap="2">
-    <text-ui variant="caption" color="muted">verse</text-ui>
-    <div verse>
+    <text-ui variant="caption" color="muted">scale="ui-sm"</text-ui>
+    <div scale="ui-sm">
       <row-ui gap="2">
         <badge-ui text="New" variant="success"></badge-ui>
         <badge-ui text="Beta" variant="info"></badge-ui>
@@ -31,8 +31,8 @@
     </div>
   </col-ui>
   <col-ui gap="2">
-    <text-ui variant="caption" color="muted">prose</text-ui>
-    <div prose>
+    <text-ui variant="caption" color="muted">scale="content-md"</text-ui>
+    <div scale="content-md">
       <row-ui gap="2">
         <badge-ui text="New" variant="success"></badge-ui>
         <badge-ui text="Beta" variant="info"></badge-ui>

package/components/card/card.css

@@ -80,6 +80,18 @@
     margin-top: auto;
   }
 
+  /* Flex containers never collapse adjacent margins the way block flow
+     does (gh#1098) — once :has(> footer) above switches the card to
+     flex-column, a plain header followed by a plain section stacks BOTH
+     regions' --card-inset margins into a doubled gap instead of the
+     single inset block flow would have collapsed them to. The leading
+     region's own margin-bottom already supplies that inset; zero the
+     trailing region's margin-top. footer is excluded — its margin-top is
+     handled above (bottom-pin `auto`) or by [divider] below. */
+  :scope:has(> footer) > :is(header, section) + :is(header, section) {
+    margin-block-start: 0;
+  }
+
   /* ═══════ Variants — token-only overrides ═══════ */
 
   /* `outline` is a documented alias for `outlined` (yaml). */
@@ -385,6 +397,30 @@
     border-radius: 0;
   }
 
+  /* Guide/value/legend safety inset (gh#1095) — [bleed]'s zero-inset is
+     only collision-free for the bare-marks case: a sparkline (its
+     renderer never emits axis ticks, gridlines, value labels, or a
+     legend — chart.class.js #renderSparkline), or any other chart-ui
+     type with BOTH [hide-grid] and [hide-values] set (the author opted
+     out of every text element). A chart that still draws guides or
+     value text — or is paired with a <chart-legend-ui> — needs
+     clearance from the card's frame, or that text collides with the
+     card edge and clips under the corner-rounded `overflow: hidden`
+     (:scope, top of file). Restore the card's own inset automatically
+     for those cases rather than relying on every author to remember —
+     the :has() selector's specificity already beats the plain [bleed]
+     reset above regardless of source order. Pairing a legend with a
+     genuinely full-bleed chart still works — put the legend in its OWN
+     section below, wired via chart-legend-ui[for="<chart id>"], which
+     never enters this selector (see chart-in-card.examples.html's
+     "Full-bleed chart + legend band" example). */
+  & > section[bleed]:has(> chart-ui:not([type="sparkline"]):not([hide-grid])),
+  & > section[bleed]:has(> chart-ui:not([type="sparkline"]):not([hide-values])),
+  & > section[bleed]:has(> chart-legend-ui) {
+    margin: var(--card-inset);
+    padding: 0;
+  }
+
   /* ═══════ Footer ═══════
      Margin-based inset. Flex row for actions.
      [divider] adds top border.
@@ -414,8 +450,15 @@
     justify-content: flex-end;
   }
 
+  /* Divider clearance is padding-only (matches header[divider]'s
+     padding-bottom pattern) — the space above the line already comes from
+     the preceding section's own trailing margin. An explicit margin-top
+     here on top of that stacked with the footer's base margin instead of
+     collapsing into it (footer/section are flex-column siblings once the
+     card has a footer — see the :has(> footer) rule above — so adjacent
+     margins never collapse), tripling the gap to the divider vs. the
+     content gaps around it (gh#1096). */
   & > footer[divider] {
-    margin-top: var(--card-inset);
     padding-top: var(--card-inset);
     border-top: 1px solid var(--card-divider);
   }

package/components/check/check.a2ui.json

@@ -46,6 +46,11 @@
       "type": "string",
       "default": ""
     },
+    "labelHidden": {
+      "description": "When true, [label] still sets the accessible name (aria-label) but the visible text is suppressed via the canonical sr-only technique (gh#1010). Use when a sibling element already shows the same name visually (e.g. a title next to a check-ui used as a list-item icon) and the plain-visible label would paint it twice.",
+      "type": "boolean",
+      "default": false
+    },
     "name": {
       "description": "Form field name",
       "type": "string",
@@ -123,26 +128,35 @@
     },
     "tag": "check-ui",
     "tokens": {
-      "--check-box-background": {
+      "--check-bg": {
         "description": "Unchecked background"
       },
-      "--check-box-border-color": {
-        "description": "Unchecked border color"
+      "--check-bg-checked": {
+        "description": "Checked/indeterminate background"
       },
-      "--check-box-radius": {
-        "description": "Checkbox border radius"
+      "--check-bg-checked-hover": {
+        "description": "Checked/indeterminate background on hover"
       },
-      "--check-box-size": {
-        "description": "Checkbox indicator size"
+      "--check-bg-hover": {
+        "description": "Unchecked background on hover"
       },
-      "--check-checked-background": {
-        "description": "Checked/indeterminate background"
+      "--check-border": {
+        "description": "Unchecked border color"
       },
-      "--check-checked-border-color": {
+      "--check-border-checked": {
         "description": "Checked/indeterminate border"
       },
-      "--check-checked-foreground": {
+      "--check-border-hover": {
+        "description": "Unchecked border color on hover"
+      },
+      "--check-fg-checked": {
         "description": "Checkmark/dash color"
+      },
+      "--check-radius": {
+        "description": "Checkbox border radius"
+      },
+      "--check-size": {
+        "description": "Checkbox indicator size"
       }
     },
     "traits": [],

package/components/check/check.class.js

@@ -26,6 +26,11 @@ export class UICheck extends UIFormElement {
     checked:       { type: Boolean, default: false, reflect: true },
     indeterminate: { type: Boolean, default: false, reflect: true },
     label:         { type: String,  default: '', reflect: true },
+    /* gh#1010: keeps [label] as the accessible name (aria-label, set
+       below) while suppressing the VISIBLE `::after` text — for
+       compositions that already show the name elsewhere (e.g. a
+       sibling title) and would otherwise paint it twice. */
+    labelHidden:   { type: Boolean, default: false, reflect: true, attribute: 'label-hidden' },
   };
 
   static template = () => html`<span slot="box"></span>`;

package/components/check/check.css

@@ -122,6 +122,27 @@ check-ui[indeterminate] {
   /* Label */
   :scope[label]::after { content: attr(label); }
 
+  /* Visually-hidden label (gh#1010) — [label-hidden] keeps the a11y name
+     (aria-label, set from [label] in check.class.js render()) but drops
+     the visible text, for compositions that already show the name
+     elsewhere. Same canonical sr-only recipe as <visually-hidden-ui>
+     (visually-hidden.css) — clip-path does the real hiding; the rest is
+     belt-and-suspenders for cross-UA. More specific than the bare
+     `[label]::after` rule above, so it wins whenever both are set. */
+  :scope[label][label-hidden]::after {
+    content: attr(label);
+    position: absolute !important;
+    width: 1px !important;
+    height: 1px !important;
+    padding: 0 !important;
+    margin: -1px !important;
+    overflow: hidden !important;
+    clip: rect(0, 0, 0, 0) !important;
+    clip-path: inset(100%) !important;
+    white-space: nowrap !important;
+    border: 0 !important;
+  }
+
   /* Focus */
   :scope:focus-visible [slot="box"] { box-shadow: var(--check-focus-ring); border-color: transparent; }
 

package/components/check/check.d.ts

@@ -20,6 +20,8 @@ export class UICheck extends UIFormElement {
   /** Indeterminate (mixed) state — visual only; cleared on click. */
   indeterminate: boolean;
   label: string;
+  /** When true, [label] still sets the accessible name but the visible text is sr-only hidden (gh#1010). */
+  labelHidden: boolean;
 
   addEventListener<K extends keyof HTMLElementEventMap>(
     type: K,

package/components/check/check.examples.md

@@ -11,8 +11,8 @@
 ```html
 <row-ui gap="6" align="start" wrap>
   <col-ui gap="2">
-    <text-ui variant="caption" color="muted">verse</text-ui>
-    <div verse>
+    <text-ui variant="caption" color="muted">scale="ui-sm"</text-ui>
+    <div scale="ui-sm">
       <check-ui label="Notify me" checked></check-ui>
     </div>
   </col-ui>
@@ -23,8 +23,8 @@
     </div>
   </col-ui>
   <col-ui gap="2">
-    <text-ui variant="caption" color="muted">prose</text-ui>
-    <div prose>
+    <text-ui variant="caption" color="muted">scale="content-md"</text-ui>
+    <div scale="content-md">
       <check-ui label="Notify me" checked></check-ui>
     </div>
   </col-ui>

package/components/check/check.yaml

@@ -48,6 +48,17 @@ props:
     required: true
     type: string
     default: ""
+  labelHidden:
+    description: >-
+      When true, [label] still sets the accessible name (aria-label) but
+      the visible text is suppressed via the canonical sr-only technique
+      (gh#1010). Use when a sibling element already shows the same name
+      visually (e.g. a title next to a check-ui used as a list-item icon)
+      and the plain-visible label would paint it twice.
+    type: boolean
+    default: false
+    reflect: true
+    attribute: label-hidden
   value:
     description: Form value (submitted as 'on' when checked)
     type: string
@@ -68,23 +79,31 @@ states:
     attribute: disabled
 traits: []
 tokens:
-  --check-box-background:
+  --check-bg:
     description: Unchecked background
-  --check-box-border-color:
+  --check-border:
     description: Unchecked border color
-  --check-box-radius:
+  --check-radius:
     description: Checkbox border radius
-  --check-box-size:
+  --check-size:
     description: Checkbox indicator size
-  --check-checked-background:
+  --check-bg-checked:
     description: Checked/indeterminate background
-  --check-checked-border-color:
+  --check-border-checked:
     description: Checked/indeterminate border
-  --check-checked-foreground:
+  --check-fg-checked:
     description: Checkmark/dash color
+  --check-border-hover:
+    description: Unchecked border color on hover
+  --check-bg-hover:
+    description: Unchecked background on hover
+  --check-bg-checked-hover:
+    description: Checked/indeterminate background on hover
 a2ui:
   rules:
     - "Self-labeling widget — use the [label] attribute directly; do NOT wrap in <field-ui>. The widget renders its own label inline via CSS attr() pattern. Wrapping breaks the consent-row layout (see field-ui anti_patterns)."
+    - rule: 'When check-ui is used as a list-item icon/indicator beside a separate title element carrying the same name (a title column, a list-item-ui slot="text"), set [label-hidden] alongside [label] so the accessible name is preserved without painting the name twice.'
+      reason: 'gh#1010 — the visible ::after label and an adjacent title both showed the step name, and the visible labels varied width, producing a ragged title column.'
     - rule: 'Three states supported: unchecked (default), checked (via [checked]), and indeterminate (via [indeterminate]); form-associated.'
       reason: 'Per ADR-0025 — host IS the control, no wrapped <input>.'
     - rule: 'For binary on/off toggles where visual switch metaphor matters, use <switch-ui> instead; check-ui is for multi-select sets and form-acceptance gates.'

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/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/nav-group/nav-group.css

@@ -28,6 +28,14 @@
     --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);
@@ -57,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

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."