@adia-ai/web-components 0.6.49 → 0.7.0

package/components/otp-input/otp-input.css

@@ -1,9 +1,13 @@
 @scope (otp-input-ui) {
   :where(:scope) {
     /* ── Tokens ── */
-    --otp-input-size-default:         var(--a-size);
+    /* Digit boxes grow to fill the row, capped at ~1.75× the base control size
+       (~52px) so they read as comfortable single-digit boxes. Radius is the
+       plain --a-radius-lg token (no min()/clamp expression — radius patterns
+       stay simple). Scales with [size] + density (relative to --a-size). */
+    --otp-input-size-default:         calc(var(--a-size) * 1.75);
     --otp-input-gap-default:          var(--a-space-2);
-    --otp-input-radius-default:       var(--a-radius-md);
+    --otp-input-radius-default:       var(--a-radius-lg);
     --otp-input-border-default:       var(--a-ui-border);
     --otp-input-border-hover-default: var(--a-ui-border-hover);
     --otp-input-border-focus-default: var(--a-accent);
@@ -24,15 +28,27 @@
     /* ── Base ── */
     box-sizing: border-box;
     display: flex;
-    justify-content: space-around;
+    justify-content: center;
     gap: var(--otp-input-gap, var(--otp-input-gap-default));
+    /* Fill the container (a block-level control per ADR-0037) so the digit
+       boxes grow to use the available width instead of sitting content-width
+       on the left. Boxes flex to fill up to their cap; once capped (very wide
+       container) the group centers rather than packing left. (bug-37 follow-up) */
+    width: 100%;
   }
 
   /* ── Digit inputs ── */
+  /* Boxes grow equally to fill the row (flex), staying square (aspect-ratio)
+     and capped at --otp-input-size so they read as digit boxes — not huge on a
+     wide container, not cramped on a narrow one. The cap keeps --a-radius-md
+     proportional (a rounded square, ~25-30%), which is the whole point of the
+     bug-37 sizing. */
   [slot="digit"] {
     box-sizing: border-box;
-    width: var(--otp-input-size, var(--otp-input-size-default));
-    height: var(--otp-input-size, var(--otp-input-size-default));
+    flex: 1 1 0;
+    min-width: 0;
+    max-width: var(--otp-input-size, var(--otp-input-size-default));
+    aspect-ratio: 1;
     text-align: center;
     border: 1px solid var(--otp-input-border, var(--otp-input-border-default));
     border-radius: var(--otp-input-radius, var(--otp-input-radius-default));
@@ -67,12 +83,11 @@
   :scope[disabled] [slot="digit"] {
     background: var(--otp-input-bg-disabled, var(--otp-input-bg-disabled-default));
     color: var(--otp-input-fg-disabled, var(--otp-input-fg-disabled-default));
-    /* Dashed border rendered via SVG border-image for consistent ~8px
-       dashes across browsers (native `border-style: dashed` is too short
-       and varies by engine). The border-color fallback is used when
-       border-image isn't supported. */
+    /* Native dashed border — it follows the box's border-radius (a rounded
+       dashed square, matching the enabled state). An SVG border-image would
+       give more uniform dashes but is clipped to a SQUARE — it ignores
+       border-radius — so the disabled corners wouldn't round. */
     border: 1px dashed var(--otp-input-border-disabled, var(--otp-input-border-disabled-default));
-    border-image: url("data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' width='28' height='28' preserveAspectRatio='none'><rect x='0.5' y='0.5' width='27' height='27' fill='none' stroke='%23999' stroke-width='1' stroke-dasharray='8 6'/></svg>") 1 repeat;
     cursor: not-allowed;
   }
 }

package/components/page/page.css

@@ -9,6 +9,15 @@
     /* ── Padding default (when [padding] is set without a value) ── */
     --page-padding-default:  var(--a-space-6);
 
+    /* ── Region rhythm — vertical gap between header / section / footer,
+       mirroring card-ui's section inset. The page [padding] supplies the
+       outer frame; this is the inter-region spacing. ── */
+    --page-inset-default:    var(--a-space-5);
+
+    /* ── Padded-region sub-surface (a section[padding] inside the page) ── */
+    --page-region-bg-default:     var(--a-bg-subtle);
+    --page-region-radius-default: var(--a-radius-md);
+
     /* ── Surfaces ── */
     --page-bg-default:               var(--a-canvas-0);
     --page-fg-default:               var(--a-fg);
@@ -23,6 +32,9 @@
     box-sizing: border-box;
     display: block;
     width: 100%;
+    /* --page-pad carries the resolved [padding] value so the sticky header can
+       bleed back over it (card-ui pattern) — see the sticky-header rule. */
+    padding: var(--page-pad, 0);
     background: var(--page-bg, var(--page-bg-default));
     color: var(--page-fg, var(--page-fg-default));
   }
@@ -33,17 +45,47 @@
   :scope[max-width="wide"]   { max-width: var(--page-max-width-wide, var(--page-max-width-wide-default));   margin-inline: auto; }
   :scope[max-width="full"]   { max-width: var(--page-max-width-full, var(--page-max-width-full-default)); }
 
-  /* ── Padding scale (mirrors --a-space-N) ── */
-  :scope[padding=""]  { padding: var(--page-padding-default); }
-  :scope[padding="0"] { padding: 0; }
-  :scope[padding="1"] { padding: var(--a-space-1); }
-  :scope[padding="2"] { padding: var(--a-space-2); }
-  :scope[padding="3"] { padding: var(--a-space-3); }
-  :scope[padding="4"] { padding: var(--a-space-4); }
-  :scope[padding="5"] { padding: var(--a-space-5); }
-  :scope[padding="6"] { padding: var(--a-space-6); }
-  :scope[padding="7"] { padding: var(--a-space-7); }
-  :scope[padding="8"] { padding: var(--a-space-8); }
+  /* ── Padding scale (mirrors --a-space-N) — sets --page-pad, applied above ── */
+  :scope[padding=""]  { --page-pad: var(--page-padding-default); }
+  :scope[padding="0"] { --page-pad: 0; }
+  :scope[padding="1"] { --page-pad: var(--a-space-1); }
+  :scope[padding="2"] { --page-pad: var(--a-space-2); }
+  :scope[padding="3"] { --page-pad: var(--a-space-3); }
+  :scope[padding="4"] { --page-pad: var(--a-space-4); }
+  :scope[padding="5"] { --page-pad: var(--a-space-5); }
+  :scope[padding="6"] { --page-pad: var(--a-space-6); }
+  :scope[padding="7"] { --page-pad: var(--a-space-7); }
+  :scope[padding="8"] { --page-pad: var(--a-space-8); }
+
+  /* ═══════ Region model — header / section / footer ═══════
+     Mirrors card-ui's section model, adapted to the page's [padding] frame:
+     the page [padding] is the OUTER inset; these rules add the vertical
+     rhythm BETWEEN regions plus the [bleed] / [padding] modifiers. The
+     page's own @scope styling the slot primitives is what the docs promise
+     ([<header>] / [<section>] / [<footer>] and their -ui variants). */
+
+  /* Vertical rhythm: every region after the first picks up a top margin so
+     header → body → footer breathe consistently (the first region hugs the
+     padding edge). */
+  :scope > :where(header, header-ui, section, section-ui, footer, footer-ui)
+    ~ :where(header, header-ui, section, section-ui, footer, footer-ui) {
+    margin-block-start: var(--page-inset, var(--page-inset-default));
+  }
+
+  /* [bleed] — edge-to-edge region: cancel the page's inline [padding] so
+     full-width content (hero, banner, table, chart) reaches the page edges.
+     Resolves to 0 (no-op) when the page has no padding. */
+  :scope > :where(header, header-ui, section, section-ui, footer, footer-ui)[bleed] {
+    margin-inline: calc(-1 * var(--page-pad, 0));
+  }
+
+  /* [padding] on a region — a padded sub-surface with its own background +
+     radius, like card-ui's section[padding]. */
+  :scope > :where(section, section-ui)[padding] {
+    padding: var(--page-inset, var(--page-inset-default));
+    background: var(--page-region-bg, var(--page-region-bg-default));
+    border-radius: var(--page-region-radius, var(--page-region-radius-default));
+  }
 
   /* ── Scroll container ── */
   :scope[scroll] {
@@ -53,11 +95,22 @@
   }
 
   /* ── Sticky-header support ── */
+  /* Drop the page's TOP padding when the header is sticky — that gap is where
+     scrolling content used to peek ABOVE the pinned header. The header then
+     sits flush at the scroll-container top and supplies its own top spacing
+     (padding-block below). */
+  :scope[sticky-header] { padding-top: 0; }
   :scope[sticky-header] > :where(header, header-ui) {
     position: sticky;
     top: 0;
     z-index: 1;
     background: var(--page-sticky-bg, var(--page-sticky-bg-default));
+    /* Bleed horizontally over the page's inline [padding] so the opaque band
+       spans the full scroll width, then re-inset the content so it stays
+       aligned with the body. Vertical = its own breathing room. Card-ui
+       header pattern. (No negative margin-top — that breaks position:sticky.) */
+    margin-inline: calc(-1 * var(--page-pad, 0));
+    padding: var(--a-space-3) var(--page-pad, 0);
     transition: border-color var(--a-duration-fast) var(--a-easing), box-shadow var(--a-duration-fast) var(--a-easing);
   }
 

package/components/pagination/pagination.class.js

@@ -37,7 +37,7 @@ export class UIPagination extends UIElement {
     size:     { type: String, default: 'md', reflect: true },
   };
 
-  // Phosphor icons stamped by this primitive (prev/next chevrons inside
+  // Phosphor icons stamped by this primitive (prev/next carets inside
   // the nested <button-ui>). Audited by check-required-icons.mjs.
   static requiredIcons = ['caret-left', 'caret-right'];
 

package/components/pagination/pagination.css

@@ -23,9 +23,12 @@
   :scope {
     /* ── Base ── */
     box-sizing: border-box;
-    display: inline-flex;
+    display: flex;
   }
 
+  /* Display convention (ADR-0037): block-level by default; [inline] opts back to inline-level. */
+  :scope[inline] { display: inline-flex; }
+
   /* ── Nav container ── */
   [slot="nav"] {
     display: flex;
@@ -66,5 +69,10 @@
      aspect-ratio 1 here for the bordered-cell look). */
   :scope[variant="button"] [slot="nav"] button-ui {
     aspect-ratio: 1;
+    /* 1:1 cells inherit button-ui's --a-radius-md (~13px), which on a square
+       cell is ~37% of the side → a circle, not the "square 1:1 bordered button"
+       the variant promises. Tighten to -sm so the bordered cells read as rounded
+       squares. Same square+large-radius trap as otp-input (bug-37 / bug-39). */
+    --button-radius: var(--a-radius-sm);
   }
 }

package/components/pane/pane.a2ui.json

@@ -82,6 +82,9 @@
       "text-area"
     ],
     "slots": {
+      "caret": {
+        "description": "Collapse caret inside the header. Auto-stamped as `<icon-ui slot=\"caret\" name=\"caret-right\">` (rotates on `[collapsed]`). Supply your own `slot=\"caret\"` child in the header to customize — adopt-or-stamp honors a declarative caret instead of stamping."
+      },
       "header": {
         "description": "Auto-created header element with label text and toggle arrow"
       }

package/components/pane/pane.class.js

@@ -100,12 +100,13 @@ export class UIPane extends UIElement {
       header.setAttribute('tabindex', '0');
       header.setAttribute('aria-expanded', String(!this.collapsed));
 
-      // Stamp chevron icon if not present
-      if (!header.querySelector('[slot="chevron"]')) {
-        const chevron = document.createElement('icon-ui');
-        chevron.setAttribute('slot', 'chevron');
-        chevron.setAttribute('name', 'caret-right');
-        header.append(chevron);
+      // Stamp the caret icon if not present (adopt-or-stamp: a declarative
+      // [slot="caret"] child is honored, else we stamp the default).
+      if (!header.querySelector('[slot="caret"]')) {
+        const caret = document.createElement('icon-ui');
+        caret.setAttribute('slot', 'caret');
+        caret.setAttribute('name', 'caret-right');
+        header.append(caret);
       }
     }
   }

package/components/pane/pane.css

@@ -29,7 +29,7 @@
 
     /* ── Header interaction ── */
     --pane-header-bg-hover-default: var(--a-bg-subtle);
-    --pane-chevron-fg-default:      var(--a-fg-muted);
+    --pane-caret-fg-default:        var(--a-fg-muted);
 
     /* ── Section header ── */
     --pane-section-header-weight-default: var(--a-weight-medium);
@@ -107,17 +107,17 @@
     box-shadow: var(--a-focus-ring) inset;
   }
 
-  /* Collapse indicator — stamped by JS as icon-ui */
-  & > header > [slot="chevron"] {
+  /* Collapse indicator (caret) — stamped by JS as icon-ui */
+  & > header > [slot="caret"] {
     --a-icon-size: var(--a-caret-size);
     flex-shrink: 0;
     margin-inline-start: auto;
-    color: var(--pane-chevron-fg, var(--pane-chevron-fg-default));
+    color: var(--pane-caret-fg, var(--pane-caret-fg-default));
     transition: transform var(--pane-duration, var(--pane-duration-default)) var(--pane-easing, var(--pane-easing-default));
     transform: rotate(90deg);
   }
 
-  :scope[collapsed] > header > [slot="chevron"] {
+  :scope[collapsed] > header > [slot="caret"] {
     transform: rotate(0deg);
   }
 

package/components/pane/pane.yaml

@@ -62,6 +62,12 @@ events:
 slots:
   header:
     description: Auto-created header element with label text and toggle arrow
+  caret:
+    description: >-
+      Collapse caret inside the header. Auto-stamped as
+      `<icon-ui slot="caret" name="caret-right">` (rotates on `[collapsed]`).
+      Supply your own `slot="caret"` child in the header to customize —
+      adopt-or-stamp honors a declarative caret instead of stamping.
 states:
 - name: idle
   description: Default, ready for interaction.

package/components/pipeline-status/pipeline-status.css

@@ -96,11 +96,17 @@
     transition:          background var(--pipeline-status-duration, var(--pipeline-status-duration-default)) var(--pipeline-status-easing, var(--pipeline-status-easing-default));
   }
 
+  /* State colors: the -active (accent) / -complete (success) dot-bg tokens were
+     defined but never applied — these rules only set animation, so every dot
+     stayed the default gray (--a-border). Now active dots read accent + pulse,
+     complete dots read success. (bug-40 — "use color more") */
   [data-pipeline-dot="active"] {
+    background:           var(--pipeline-status-dot-bg-active, var(--pipeline-status-dot-bg-active-default));
     animation:           pipeline-pulse var(--pipeline-status-pulse-duration, var(--pipeline-status-pulse-duration-default)) var(--pipeline-status-pulse-easing, var(--pipeline-status-pulse-easing-default)) infinite;
   }
 
   [data-pipeline-dot="complete"] {
+    background:           var(--pipeline-status-dot-bg-complete, var(--pipeline-status-dot-bg-complete-default));
     animation:           none;
   }
 

package/components/popover/popover.css

@@ -14,10 +14,13 @@
 
   :scope {
     box-sizing: border-box;
-    display: inline-flex;
+    display: flex;
     position: relative;
   }
 
+  /* Display convention (ADR-0037): block-level by default; [inline] opts back to inline-level. */
+  :scope[inline] { display: inline-flex; }
+
   [slot="trigger"] {
     display: inline-flex;
   }
@@ -81,6 +84,14 @@
     box-shadow: var(--popover-shadow, var(--popover-shadow-default));
   }
 
+  /* Prose margin reset on the content's edge children — a slotted <p> / <h*>
+     carries the UA stylesheet's margin-block (~1em), which lands inside the
+     panel padding and adds asymmetric top/bottom space (a single-line <p> looked
+     like it had a stray bottom margin). Zero the leading/trailing margins so the
+     panel padding alone frames the content. (bug — Popover single-line space) */
+  [slot="content"] > :first-child { margin-block-start: 0; }
+  [slot="content"] > :last-child  { margin-block-end: 0; }
+
   [slot="content"]:popover-open {
     @starting-style {
       opacity: 0;

package/components/preview/preview.css

@@ -39,16 +39,42 @@
      by the frame's overflow:hidden. Most demos fit (the component's overflow
      check stacks split→full-width first), so the scrollbar only appears when a
      demo is genuinely wider than the docs column. */
+  /* Column flow is the default: each example stacks in DOM order and fills the
+     stage width (align-items: stretch), so block-level demos (progress / bars /
+     accordion / cards / pages …) read at full width without a per-component
+     list. Text-flow atoms (button / badge / tag / …) opt back to content-width
+     via align-self below. (bug-46 — replaces the old flex-row + :only-child
+     block-flow hack, which only filled single-child demos.) */
   [data-preview-render] {
     display: flex;
-    flex-wrap: wrap;
-    align-items: center;
+    flex-direction: column;
+    align-items: stretch;
     gap: var(--preview-render-gap, var(--preview-render-gap-default));
     padding: var(--preview-render-pad, var(--preview-render-pad-default));
     background: var(--preview-render-bg, var(--preview-render-bg-default));
     overflow-x: auto;
   }
-
+  /* Lone text-flow atoms shouldn't span the whole stage — keep them
+     content-width + leading-aligned (the ADR-0037 inline-display set). */
+  [data-preview-render] > :is(button-ui, badge-ui, tag-ui, chip-ui, kbd-ui, icon-ui, swatch-ui, spinner-ui, switch-ui, avatar-ui) {
+    align-self: start;
+  }
+  /* Form-field demos collapse to content-width as flex items in the render
+     cell — a placeholder-only combobox shrank to a ~52px "Sel…" stub — so
+     stretch form controls to the cell width with width:100%.
+       • <field-ui> is a full-width form ROW: let it fill the whole stage,
+         NO measure cap. The prior 28rem cap read as "not using available
+         space" on wide single-block demos (bug-55 follow-up).
+       • Bare atomic controls (input/select/…) keep the 28rem measure cap so
+         a lone control doesn't sprawl into an unrealistic bar on a wide stage.
+     Non-form demos (buttons, badges, etc.) are untouched — content-width. */
+  [data-preview-render] field-ui {
+    width: 100%;
+  }
+  [data-preview-render] > :is(input-ui, select-ui, combobox-ui, textarea-ui, tags-input-ui, color-input-ui) {
+    width: 100%;
+    max-width: 28rem;
+  }
   /* Code pane — divider line between panes; flatten the nested code-ui
      chrome so the preview frame owns the outer border + radius. */
   [data-preview-code] {
@@ -151,6 +177,7 @@
     color: var(--a-fg-muted);
     background: var(--a-bg-muted);
     padding: 0.125rem 0.375rem;
+    margin-bottom: 0.5rem;
     border-radius: var(--a-radius-sm);
   }
   /* Narrow: collapse each row to stacked render-over-code. */

package/components/progress-row/progress-row.css

@@ -1,7 +1,9 @@
 @scope (progress-row-ui) {
   :where(:scope) {
     /* ── Tokens ── */
-    --progress-row-gap-default:           var(--a-space-1);
+    /* Row-gap between the label/meta row and the bar. Bumped --a-space-1 →
+       --a-space-2 so the bar isn't crammed under the label. (bug-42) */
+    --progress-row-gap-default:           var(--a-space-2);
     --progress-row-column-gap-default:    var(--a-space-2);
     --progress-row-label-size-default:    var(--a-ui-size);
     --progress-row-label-fg-default:      var(--a-fg);

package/components/qr-code/qr-code.css

@@ -10,7 +10,7 @@
 
   :scope {
     box-sizing: border-box;
-    display: inline-block;
+    display: block;
     /* The SVG itself carries explicit width/height; this is a fallback
        for cases where the SVG hasn't stamped yet (empty value/matrix). */
     line-height: 0;
@@ -18,6 +18,9 @@
     background: var(--qr-code-bg, var(--qr-code-bg-default));
   }
 
+  /* Display convention (ADR-0037): block-level by default; [inline] opts back to inline-level. */
+  :scope[inline] { display: inline-block; }
+
   :scope svg {
     display: block;
     /* Width / height come from the explicit SVG attributes set by JS

package/components/segmented/segmented.css

@@ -28,7 +28,7 @@
   :scope {
     /* ── Base ── */
     box-sizing: border-box;
-    display: inline-grid;
+    display: grid;
     grid-auto-flow: column;
     grid-auto-columns: 1fr;
     align-items: stretch;
@@ -55,6 +55,9 @@
     border-radius: var(--segmented-radius, var(--segmented-radius-default));
   }
 
+  /* Display convention (ADR-0037): block-level by default; [inline] opts back to inline-level. */
+  :scope[inline] { display: inline-grid; }
+
   /* -- Indicator (hidden until first selection) -- */
   :scope > [data-indicator] {
     display: none;

package/components/select/select.a2ui.json

@@ -107,7 +107,7 @@
       "default": false
     },
     "options": {
-      "description": "Option list. Array of {value, label, disabled?} or grouped {label, options: [...]}. Alternative to declarative <option> / <optgroup> children.",
+      "description": "Option list. Array of {value, label, disabled?, icon?, avatar?} or grouped {label, options: [...]}. Alternative to declarative <option> / <optgroup> children. Per-option icon/avatar render in the list AND reflect in the trigger's selected state.",
       "type": "array",
       "default": []
     },

package/components/select/select.class.js

@@ -71,6 +71,7 @@ export class UISelect extends UIFormElement {
   static template = () => null;
 
   #options = [];
+  #ownTrigger = false; // true when WE stamped the trigger (vs a consumer-custom one)
   #listbox = null;
   #anchorCleanup = null;
   #query = '';
@@ -386,14 +387,18 @@ export class UISelect extends UIFormElement {
 
     // Stamp default trigger if none provided
     if (!this.querySelector('[slot="trigger"]')) {
+      this.#ownTrigger = true;
       // Detach listbox before innerHTML wipe so it isn't destroyed
       const lb = this.#listbox;
       if (lb?.parentNode === this) this.removeChild(lb);
 
+      // Initial leading reflects the host [avatar]/[icon]; #syncLeading() then
+      // reconciles it to the SELECTED option's icon/avatar on every render. The
+      // `data-select-leading` marker scopes that reconciliation to our element.
       const leading = this.avatar
-        ? `<img slot="leading" src="${this.avatar}" alt="" />`
+        ? `<img slot="leading" data-select-leading src="${escapeHTML(this.avatar)}" alt="" />`
         : this.icon
-          ? `<icon-ui slot="leading" name="${this.icon}"></icon-ui>`
+          ? `<icon-ui slot="leading" data-select-leading name="${escapeHTML(this.icon)}"></icon-ui>`
           : '';
       const displayMarkup = this.searchable
         ? `<input slot="display" type="text" role="combobox" aria-autocomplete="list" autocomplete="off" placeholder="${escapeHTML(this.placeholder || '')}" value="${escapeHTML(this.#displayText() === this.placeholder ? '' : this.#displayText())}" />`
@@ -470,6 +475,9 @@ export class UISelect extends UIFormElement {
       }
     }
 
+    // Reflect the selected option's icon/avatar in the trigger leading.
+    this.#syncLeading();
+
     // SPEC-040 — stamp / reconcile chips + "+N more" pill on every render.
     if (this.multiple) this.#stampChips();
     // Show clear-all only in multi-select mode when [clearable] + chips present.
@@ -548,12 +556,12 @@ export class UISelect extends UIFormElement {
       if (child.tagName === 'OPTGROUP') {
         const group = { label: child.label || child.getAttribute('label') || '', options: [] };
         for (const opt of child.querySelectorAll('option')) {
-          group.options.push({ value: opt.value, label: opt.textContent.trim(), disabled: opt.disabled });
+          group.options.push({ value: opt.value, label: opt.textContent.trim(), disabled: opt.disabled, icon: opt.getAttribute('icon') || '', avatar: opt.getAttribute('avatar') || '' });
           if (opt.hasAttribute('selected')) preSelectedArr.push(opt.value);
         }
         this.#options.push(group);
       } else if (child.tagName === 'OPTION') {
-        this.#options.push({ value: child.value, label: child.textContent.trim(), disabled: child.disabled });
+        this.#options.push({ value: child.value, label: child.textContent.trim(), disabled: child.disabled, icon: child.getAttribute('icon') || '', avatar: child.getAttribute('avatar') || '' });
         if (child.hasAttribute('selected')) preSelectedArr.push(child.value);
       } else if (
         // §225: skip [slot="display"] / [slot="listbox"] / [slot="action"] etc. — these are
@@ -614,6 +622,52 @@ export class UISelect extends UIFormElement {
 
   get options() { return this.#options; }
 
+  // Per-option leading markup: avatar (img) beats icon (icon-ui). Shared by
+  // the listbox rows AND the trigger (resolved against the selected option).
+  static #optionLeadHTML(opt) {
+    if (!opt) return '';
+    if (opt.avatar) return `<img data-option-avatar src="${escapeHTML(opt.avatar)}" alt="" />`;
+    if (opt.icon) return `<icon-ui name="${escapeHTML(opt.icon)}"></icon-ui>`;
+    return '';
+  }
+
+  /**
+   * Reflect the SELECTED option's icon/avatar in the trigger's leading slot.
+   * Single-select only (multi-select shows chips). Falls back to the host
+   * [avatar]/[icon] when the selected option carries neither. Only manages the
+   * leading WE stamped (`[data-select-leading]`) — a consumer-custom trigger
+   * owns its own leading.
+   */
+  #syncLeading() {
+    if (this.multiple || !this.#ownTrigger) return;
+    const trigger = this.querySelector('[slot="trigger"]');
+    if (!trigger) return;
+    const flat = this.#options.flatMap((o) => o.options || [o]);
+    const sel = flat.find((o) => !o.header && !o.separator && o.value === this.value);
+    const avatar = (sel && sel.avatar) || this.avatar || '';
+    const icon = (sel && sel.icon) || this.icon || '';
+    const existing = trigger.querySelector(':scope > [data-select-leading]');
+    let html = '';
+    if (avatar) html = `<img slot="leading" data-select-leading src="${escapeHTML(avatar)}" alt="" />`;
+    else if (icon) html = `<icon-ui slot="leading" data-select-leading name="${escapeHTML(icon)}"></icon-ui>`;
+    if (!html) { existing?.remove(); return; }
+    const tmp = document.createElement('template');
+    tmp.innerHTML = html;
+    const next = tmp.content.firstElementChild;
+    if (!existing) {
+      trigger.insertBefore(next, trigger.firstChild);
+    } else if (existing.tagName === next.tagName) {
+      // Same element type — update the changing attribute in place.
+      if (next.tagName === 'IMG') {
+        if (existing.getAttribute('src') !== next.getAttribute('src')) existing.setAttribute('src', next.getAttribute('src'));
+      } else if (existing.getAttribute('name') !== next.getAttribute('name')) {
+        existing.setAttribute('name', next.getAttribute('name'));
+      }
+    } else {
+      existing.replaceWith(next); // icon ↔ avatar switch
+    }
+  }
+
   #renderOptions() {
     if (!this.#listbox) return;
     this.#listbox.innerHTML = '';
@@ -653,6 +707,8 @@ export class UISelect extends UIFormElement {
       // SPEC-040 — multi-select option rows render a leading checkbox
       // indicator (CSS-driven via [data-multi-option]); the `check` icon
       // shows when aria-selected="true".
+      // Per-option leading glyph — avatar (img) wins over icon (icon-ui).
+      const lead = UISelect.#optionLeadHTML(opt);
       if (this.multiple) {
         el.setAttribute('data-multi-option', '');
         const box = document.createElement('span');
@@ -661,11 +717,11 @@ export class UISelect extends UIFormElement {
         el.appendChild(box);
         const label = document.createElement('span');
         label.setAttribute('data-option-label', '');
-        if (opt.icon) label.innerHTML = `<icon-ui name="${escapeHTML(opt.icon)}"></icon-ui>${escapeHTML(opt.label)}`;
+        if (lead) label.innerHTML = `${lead}${escapeHTML(opt.label)}`;
         else label.textContent = opt.label;
         el.appendChild(label);
-      } else if (opt.icon) {
-        el.innerHTML = `<icon-ui name="${escapeHTML(opt.icon)}"></icon-ui>${escapeHTML(opt.label)}`;
+      } else if (lead) {
+        el.innerHTML = `${lead}${escapeHTML(opt.label)}`;
       } else {
         el.textContent = opt.label;
       }

package/components/select/select.css

@@ -191,6 +191,11 @@
   :scope[data-multi-chips] [slot="trigger"] {
     flex-wrap: wrap;
     align-items: center;
+    /* Pack chips left with a small gap — override the base trigger's
+       `space-between` (which is for the single-select content↔caret split),
+       otherwise the chips spread across the full trigger width. The display
+       slot flex-grows (below) to push the caret to the trailing edge. */
+    justify-content: flex-start;
     gap: var(--a-space-1);
     /* min-height tracks single-row height when empty; flex-wrap allows
        it to grow as chips overflow. */
@@ -290,6 +295,8 @@ select-ui [slot="listbox"]:popover-open {
 }
 
 select-ui [role="option"] {
+  display: flex;
+  align-items: center;
   padding: var(--a-space-1) var(--a-ui-px);
   border-radius: var(--a-radius-sm);
   white-space: nowrap;
@@ -325,6 +332,17 @@ select-ui [role="option"] icon-ui {
   vertical-align: -0.125em;
 }
 
+/* Option with avatar — small inline image (matches the trigger leading
+   avatar radius), sized to the option line-height. */
+select-ui [role="option"] img[data-option-avatar] {
+  width: var(--a-ui-size);
+  height: var(--a-ui-size);
+  border-radius: var(--select-leading-radius, var(--select-leading-radius-default));
+  object-fit: cover;
+  margin-inline-end: var(--a-space-1);
+  vertical-align: -0.2em;
+}
+
 /* Separator */
 select-ui [data-separator] {
   height: 1px;

package/components/select/select.yaml

@@ -23,7 +23,7 @@ description: |
 # Per ADR-0027 — primitives that programmatically create other primitives
 # do NOT auto-import them. Consumer (or demo shell) must explicitly import.
 composes:
-  - icon-ui   # chevron + option-row affixes (created in render)
+  - icon-ui   # caret + option-row affixes (created in render)
   - tag-ui    # multi-select chip per selected option in the trigger
 props:
   name:
@@ -151,7 +151,7 @@ props:
     default: false
     reflect: true
   options:
-    description: "Option list. Array of {value, label, disabled?} or grouped {label, options: [...]}. Alternative to declarative <option> / <optgroup> children."
+    description: "Option list. Array of {value, label, disabled?, icon?, avatar?} or grouped {label, options: [...]}. Alternative to declarative <option> / <optgroup> children. Per-option icon/avatar render in the list AND reflect in the trigger's selected state."
     type: array
     default: []
   pattern:
@@ -249,6 +249,13 @@ a2ui:
       tag names are silently ignored (per §225 v0.5.9) and warned once
       at runtime. Or set `.options` programmatically as an array of
       `{value, label, disabled?}` (grouped form: `{label, options:[…]}`).
+    - >-
+      Per-option visuals: give each <option> an `icon` (Phosphor name) or
+      `avatar` (image URL) — `<option value="light" icon="sun">`. Each row
+      renders its glyph in the list AND the trigger reflects the SELECTED
+      option's icon/avatar (theme pickers, assignee/account switchers).
+      `avatar` wins over `icon`; a host-level [icon]/[avatar] is the
+      fallback when the selected option carries neither.
     - >-
       For dynamic option lists rendered inside <editor-shell>, set the
       JSON via the [data-options] attribute — <editor-shell>'s