@adia-ai/web-components 0.8.4 → 0.8.5

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

@@ -41,20 +41,11 @@
 
 import { UIElement } from '../../core/element.js';
 
-function escapeText(s) {
-  return String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
-}
-
-function escapeAttr(s) {
-  return String(s).replace(/"/g, '&quot;');
-}
-
 export class UIAgentQuestions extends UIElement {
-  // §154 (v0.5.3): Phosphor icons this primitive auto-stamps (without
-  // consumer markup). Aggregated by installIconLoadersForRegistered()
-  // across all defined elements. Audited by check-required-icons.mjs
-  // (slot 11). Per FEEDBACK-06 §4 + FEEDBACK-07 §4.
-  static requiredIcons = ['check'];
+  // gh issue 276 wave 4: options now render as <option-card-ui> (which
+  // composes icon-ui itself for the leading `icon` prop). This primitive
+  // no longer stamps any icon directly, so no requiredIcons entry is
+  // needed here — see check-required-icons.mjs (slot 11).
 
   static properties = {
     multi:       { type: Boolean, default: false, reflect: true },
@@ -87,6 +78,9 @@ export class UIAgentQuestions extends UIElement {
 
   disconnected() {
     this.#submitEl?.removeEventListener('press', this.#onSubmit);
+    this.#optionsEl?.removeEventListener('change', this.#onCardChange);
+    this.#optionsEl?.removeEventListener('click', this.#onOptionsClickCapture, true);
+    this.#optionsEl?.removeEventListener('keydown', this.#onOptionsKeydownCapture, true);
     this.#questionEl = this.#helperEl = this.#optionsEl = this.#submitEl = null;
   }
 
@@ -121,6 +115,20 @@ export class UIAgentQuestions extends UIElement {
 
     this.#optionsEl = document.createElement('div');
     this.#optionsEl.setAttribute('data-questions-options', '');
+    // Single-select: option-card-ui's own radiogroup machinery handles
+    // click + keyboard natively and fires `change` when a card becomes
+    // selected — we just listen for it.
+    this.#optionsEl.addEventListener('change', this.#onCardChange);
+    // Multi-select: option-card-ui is radio-only (its #select() no-ops
+    // once checked, and Enter/Space call that private method directly
+    // rather than dispatching a click), so there is no toggle-off hook
+    // to attach to. Intercept at the container's CAPTURE phase — before
+    // the card's own bubble-phase listeners ever run — and drive
+    // checked/aria state ourselves. Single mode never reaches these
+    // (guarded by `if (!this.multi) return`), so its native behavior is
+    // untouched.
+    this.#optionsEl.addEventListener('click', this.#onOptionsClickCapture, true);
+    this.#optionsEl.addEventListener('keydown', this.#onOptionsKeydownCapture, true);
 
     this.#submitEl = document.createElement('button-ui');
     this.#submitEl.setAttribute('text', this.submitLabel || 'Continue');
@@ -139,33 +147,28 @@ export class UIAgentQuestions extends UIElement {
     this.#optionsEl.innerHTML = '';
 
     for (const opt of this.#options) {
-      const card = document.createElement('button');
-      card.type = 'button';
+      const card = document.createElement('option-card-ui');
       card.setAttribute('data-questions-option', '');
-      card.setAttribute('role', this.multi ? 'checkbox' : 'radio');
-      card.setAttribute('aria-checked', this.#selected.has(opt.id) ? 'true' : 'false');
-      if (this.#selected.has(opt.id)) card.setAttribute('data-selected', '');
-      if (this.#answered) card.setAttribute('disabled', '');
-
-      const iconHTML = opt.icon
-        ? `<icon-ui name="${escapeAttr(opt.icon)}" color="muted" data-questions-option-icon></icon-ui>`
-        : '';
-      const checkHTML = `
-        <span data-questions-option-check aria-hidden="true">
-          <icon-ui name="check" size="sm" color="accent"></icon-ui>
-        </span>`;
-
-      card.innerHTML = `
-        ${iconHTML}
-        <span data-questions-option-body>
-          <span data-questions-option-label>${escapeText(opt.label || '')}</span>
-          ${opt.description ? `<span data-questions-option-desc>${escapeText(opt.description)}</span>` : ''}
-        </span>
-        ${checkHTML}
-      `;
-
-      card.addEventListener('click', () => this.#pick(opt));
+      card.setAttribute('data-questions-option-id', opt.id);
+      // Shared name → siblings form option-card-ui's own radiogroup
+      // (single mode). Inert in multi mode: #select() never runs there
+      // (see the capture-phase override below), so the shared name has
+      // no sibling-uncheck effect to guard against.
+      card.name = 'questions-option';
+      card.value = opt.id;
+      card.heading = opt.label || '';
+      card.description = opt.description || '';
+      card.icon = opt.icon || '';
+
       this.#optionsEl.appendChild(card);
+
+      // Multi mode: override the radio role option-card-ui sets on
+      // connect — this is a checkbox group, and aria-checked (which the
+      // primitive keeps in sync with `.checked` regardless of role) is
+      // valid for either.
+      if (this.multi) card.setAttribute('role', 'checkbox');
+      card.checked = this.#selected.has(opt.id);
+      card.disabled = this.#answered;
     }
 
     if (this.#submitEl) {
@@ -173,22 +176,62 @@ export class UIAgentQuestions extends UIElement {
     }
   }
 
-  #pick(opt) {
-    if (this.#answered) return;
-    if (this.multi) {
-      if (this.#selected.has(opt.id)) this.#selected.delete(opt.id);
-      else this.#selected.add(opt.id);
-      this.#render();
-    } else {
-      this.#selected.clear();
-      this.#selected.add(opt.id);
-      this.#answered = true;
-      this.#render();
-      this.dispatchEvent(new CustomEvent('questions-answer', {
-        bubbles: true,
-        detail: { selected: [opt.id], option: opt },
-      }));
+  /** Single mode — option-card-ui's own radiogroup fired `change` because
+   *  a card just became selected (it never fires on becoming unselected,
+   *  so this is always a genuine new pick). */
+  #onCardChange = (e) => {
+    if (this.multi || this.#answered) return;
+    const id = e.detail?.value;
+    const opt = this.#options.find((o) => o.id === id);
+    if (!opt) return;
+    this.#selected.clear();
+    this.#selected.add(opt.id);
+    this.#answered = true;
+    this.#render();
+    this.dispatchEvent(new CustomEvent('questions-answer', {
+      bubbles: true,
+      detail: { selected: [opt.id], option: opt },
+    }));
+  };
+
+  /** Multi mode — capture-phase click override (see #build). Stops the
+   *  event before option-card-ui's own bubble-phase click handler runs,
+   *  since that handler can only select, never deselect. */
+  #onOptionsClickCapture = (e) => {
+    if (!this.multi) return;
+    const card = e.target.closest?.('option-card-ui[data-questions-option]');
+    if (!card || !this.#optionsEl.contains(card)) return;
+    e.stopPropagation();
+    this.#toggleMulti(card);
+  };
+
+  /** Multi mode — capture-phase keydown override. Space/Enter toggle
+   *  (mirroring click); arrow keys are swallowed rather than forwarded
+   *  to option-card-ui's own forced-select navigation, since checkbox
+   *  groups here never had arrow-key nav (Tab-only, as before). */
+  #onOptionsKeydownCapture = (e) => {
+    if (!this.multi) return;
+    const card = e.target.closest?.('option-card-ui[data-questions-option]');
+    if (!card || !this.#optionsEl.contains(card)) return;
+    if (e.key === ' ' || e.key === 'Enter') {
+      e.preventDefault();
+      e.stopPropagation();
+      this.#toggleMulti(card);
+      return;
     }
+    if (e.key === 'ArrowDown' || e.key === 'ArrowUp' || e.key === 'ArrowLeft' || e.key === 'ArrowRight') {
+      e.stopPropagation();
+    }
+  };
+
+  #toggleMulti(card) {
+    if (this.#answered) return;
+    const id = card.dataset.questionsOptionId;
+    const opt = this.#options.find((o) => o.id === id);
+    if (!opt) return;
+    if (this.#selected.has(opt.id)) this.#selected.delete(opt.id);
+    else this.#selected.add(opt.id);
+    this.#render();
   }
 
   #onSubmit = () => {

package/components/agent-questions/agent-questions.css

@@ -18,8 +18,6 @@
     --agent-questions-option-bg-sel:   var(--md-sys-color-primary-container);
     --agent-questions-option-border:   var(--md-sys-color-neutral-outline-variant);
     --agent-questions-option-border-sel: var(--a-primary-bg);
-    --agent-questions-check-bg:        var(--a-primary-bg);
-    --agent-questions-check-fg:        var(--md-sys-color-primary-on-primary);
 
     /* ── Layout ── */
     --agent-questions-gap:             var(--a-space-2);
@@ -27,9 +25,6 @@
     --agent-questions-option-padding:  var(--a-space-3);
     --agent-questions-option-radius:   var(--a-radius);
     --agent-questions-q-padding:       var(--a-space-1);
-    --agent-questions-option-body-gap: var(--a-space-0-5);
-    /* Component-intrinsic measurement; no --a-space-* equivalent */
-    --agent-questions-check-size:      20px;
 
     /* ── Motion ── */
     --agent-questions-duration:        var(--a-duration-fast);
@@ -61,108 +56,34 @@
     gap: var(--agent-questions-gap);
   }
 
+  /* gh issue 276 wave 4: options render as <option-card-ui> now — it owns
+     its own box model, borders, hover/checked/disabled states, focus ring,
+     and heading/description/icon layout via its own @scope'd CSS. This
+     re-points its token surface to agent-questions' existing tokens so the
+     migration doesn't shift the look; it does not restyle the card itself.
+     One deliberate visual difference: the selected indicator is now
+     option-card-ui's authentic filled-radio-dot recipe (shared with
+     plan-picker-ui) rather than the bespoke check-glyph badge the native
+     buttons drew — that badge doesn't exist as an option-card-ui slot. */
   [data-questions-option] {
-    display: flex;
-    /* Top-align so the leading icon stays with the label's first line
-       when a description wraps below; we restore visual centering on
-       the icon and check by nudging them to the label's first-line
-       center via margin-top. Centering the whole row dragged the icon
-       down to the body's vertical midpoint, which sat between label
-       and description rather than on the label. */
-    align-items: start;
-    gap: var(--agent-questions-option-gap);
-    padding: var(--agent-questions-option-padding);
-    border: 1px solid var(--agent-questions-option-border);
-    border-radius: var(--agent-questions-option-radius);
-    background: var(--agent-questions-option-bg);
-    color: inherit;
-    cursor: pointer;
-    text-align: start;
-    font: inherit;
-    /* font-family floor — see segment.css rationale (inline default). */
-    font-family: var(--agent-questions-font-family, var(--a-font-family-ui));
-    transition:
-      background var(--agent-questions-duration) var(--agent-questions-easing),
-      border-color var(--agent-questions-duration) var(--agent-questions-easing);
-    min-width: 0;
+    --option-card-padding-block:  var(--agent-questions-option-padding);
+    --option-card-padding-inline: var(--agent-questions-option-padding);
+    --option-card-radius:         var(--agent-questions-option-radius);
+    --option-card-gap-x:          var(--agent-questions-option-gap);
+    --option-card-bg:             var(--agent-questions-option-bg);
+    --option-card-border:         var(--agent-questions-option-border);
+    --option-card-bg-hover:       var(--agent-questions-option-bg-hover);
+    /* Match prior behavior: hover changed background only, never border. */
+    --option-card-border-hover:   var(--agent-questions-option-border);
+    --option-card-bg-checked:     var(--agent-questions-option-bg-sel);
+    --option-card-border-checked: var(--agent-questions-option-border-sel);
+    --option-card-heading-color:  var(--agent-questions-label-fg);
+    --option-card-heading-weight: var(--agent-questions-label-weight);
+    --option-card-heading-size:   var(--agent-questions-label-size);
+    --option-card-desc-color:     var(--agent-questions-desc-fg);
+    --option-card-desc-size:      var(--agent-questions-desc-size);
+    --option-card-duration:       var(--agent-questions-duration);
+    --option-card-easing:         var(--agent-questions-easing);
     width: 100%;
   }
-
-  [data-questions-option]:hover {
-    background: var(--agent-questions-option-bg-hover);
-  }
-
-  [data-questions-option][data-selected] {
-    background: var(--agent-questions-option-bg-sel);
-    border-color: var(--agent-questions-option-border-sel);
-  }
-
-  [data-questions-option][disabled] {
-    cursor: default;
-    opacity: 0.7;
-  }
-
-  [data-questions-option]:focus-visible {
-    outline: 2px solid var(--agent-questions-option-border-sel);
-    outline-offset: 2px;
-  }
-
-  [data-questions-option-icon] {
-    flex-shrink: 0;
-    /* Align the leading icon's center with the label's first-line
-       center. `1.5em` matches the label's effective line-height
-       (label is `font-size:` only — line-height inherits as 1.5).
-       `var(--a-icon-size)` is icon-ui's rendered height. Centering
-       the icon inside one line-box of the label's height puts its
-       midpoint on the label's first-line midpoint. We use em on the
-       icon's own font-size (which icon-ui keeps at the option's
-       font-size) so the offset scales with whatever the consumer
-       sets `--agent-questions-label-size` to. */
-    margin-top: calc((1.5em - var(--a-icon-size, 1em)) / 2);
-  }
-
-  [data-questions-option-body] {
-    flex: 1;
-    min-width: 0;
-    display: flex;
-    flex-direction: column;
-    gap: var(--agent-questions-option-body-gap);
-  }
-
-  [data-questions-option-label] {
-    font-size: var(--agent-questions-label-size);
-    font-weight: var(--agent-questions-label-weight);
-    color: var(--agent-questions-label-fg);
-  }
-
-  [data-questions-option-desc] {
-    font-size: var(--agent-questions-desc-size);
-    color: var(--agent-questions-desc-fg);
-    line-height: 1.4;
-  }
-
-  [data-questions-option-check] {
-    width: var(--agent-questions-check-size);
-    height: var(--agent-questions-check-size);
-    border-radius: 50%;
-    flex-shrink: 0;
-    display: flex;
-    align-items: center;
-    justify-content: center;
-    background: transparent;
-    opacity: 0;
-    transition: opacity var(--agent-questions-duration) var(--agent-questions-easing);
-    /* Match the leading-icon offset so a row of [icon · label · check]
-       reads as one horizontal line aligned to the label's first line. */
-    margin-top: calc((1.5em - var(--agent-questions-check-size)) / 2);
-  }
-
-  [data-questions-option][data-selected] [data-questions-option-check] {
-    background: var(--agent-questions-check-bg);
-    opacity: 1;
-  }
-
-  [data-questions-option][data-selected] [data-questions-option-check] icon-ui {
-    color: var(--agent-questions-check-fg);
-  }
 }

package/components/agent-questions/agent-questions.yaml

@@ -19,6 +19,7 @@ description: |
 # do NOT auto-import them. Consumer (or demo shell) must explicitly import.
 composes:
   - button-ui
+  - option-card-ui  # gh issue 276 wave 4
 props:
   helper:
     description: Helper text.

package/components/button/button.class.js

@@ -50,7 +50,11 @@ export class UIButton extends UIElement {
   static template = () => null;
 
   connected() {
-    this.setAttribute('role', 'button');
+    // Respect consumer-authored ARIA — a composite may stamp button-ui as
+    // role="tab" (swiper dots), role="gridcell"-hosted day buttons
+    // (calendar), etc. Same contract as tabindex below: default only when
+    // the author said nothing (operator ruling 2026-07-17, gh#276 wave 4).
+    if (!this.hasAttribute('role')) this.setAttribute('role', 'button');
     // Respect a consumer-authored tabindex (e.g. a mouse-only tabindex="-1"
     // affordance like combobox's clear x, or a roving-tabindex composite) —
     // only default the focusable state when the author said nothing.

package/components/calendar-grid/calendar-grid.a2ui.json

@@ -70,7 +70,9 @@
       }
     ],
     "category": "input",
-    "composes": [],
+    "composes": [
+      "button-ui"
+    ],
     "events": {
       "change": {
         "description": "User selected a date. detail.value is the ISO string."

package/components/calendar-grid/calendar-grid.class.js

@@ -164,10 +164,13 @@ export class UICalendarGrid extends UIElement {
     const rangeTo   = (rs && re && rs <= re) ? re : null;
 
     // Header — Prev / Title / Next
+    // <button-ui variant="ghost" icon="…"> (gh issue 276 wave 4) — button-ui
+    // respects the consumer-authored tabindex="-1", so the nav carets stay
+    // out of the roving-tabindex day-grid's tab sequence exactly as before.
     let h = `<div data-cal-header>
-      <button data-cal-prev type="button" aria-label="Previous month" tabindex="-1"><icon-ui name="caret-left"></icon-ui></button>
+      <button-ui variant="ghost" size="xs" icon="caret-left" data-cal-prev aria-label="Previous month" tabindex="-1"></button-ui>
       <span data-cal-title>${MONTHS_LONG[month]} ${year}</span>
-      <button data-cal-next type="button" aria-label="Next month" tabindex="-1"><icon-ui name="caret-right"></icon-ui></button>
+      <button-ui variant="ghost" size="xs" icon="caret-right" data-cal-next aria-label="Next month" tabindex="-1"></button-ui>
     </div>`;
 
     // Day-of-week header
@@ -183,7 +186,7 @@ export class UICalendarGrid extends UIElement {
     // Previous-month trailing days (outside, disabled)
     for (let i = firstDay - 1; i >= 0; i--) {
       const day = daysInPrev - i;
-      h += `<button type="button" data-cal-day data-outside disabled tabindex="-1">${day}</button>`;
+      h += `<button-ui variant="ghost" data-cal-day data-outside disabled tabindex="-1" text="${day}"></button-ui>`;
     }
 
     // Current-month days
@@ -206,7 +209,6 @@ export class UICalendarGrid extends UIElement {
       const isRangeEnd   = !!(rangeTo   && sameDay(date, rangeTo));
 
       const attrs = [
-        'type="button"',
         'data-cal-day',
         `data-date="${iso}"`,
         isToday      ? 'data-today' : '',
@@ -219,14 +221,17 @@ export class UICalendarGrid extends UIElement {
         `tabindex="${isFocused ? '0' : '-1'}"`,
       ].filter(Boolean).join(' ');
 
-      h += `<button ${attrs}>${d}</button>`;
+      // <button-ui variant="ghost" text="…"> (gh issue 276 wave 4) — the day
+      // number moves from element text content to the `text` attribute,
+      // which button-ui renders via CSS attr(text) on its ::after.
+      h += `<button-ui variant="ghost" ${attrs} text="${d}"></button-ui>`;
     }
 
     // Next-month leading days
     const totalCells = firstDay + daysInMonth;
     const remaining  = (7 - (totalCells % 7)) % 7;
     for (let d = 1; d <= remaining; d++) {
-      h += `<button type="button" data-cal-day data-outside disabled tabindex="-1">${d}</button>`;
+      h += `<button-ui variant="ghost" data-cal-day data-outside disabled tabindex="-1" text="${d}"></button-ui>`;
     }
 
     h += '</div>';

package/components/calendar-grid/calendar-grid.css

@@ -115,14 +115,23 @@
     color: var(--calendar-grid-title-fg);
   }
 
-  [data-cal-prev],
-  [data-cal-next] {
+  /* Stamped <button-ui variant="ghost" size="xs" icon="caret-…"> (gh issue
+     276 wave 4) — icon-only (no [text], no child text) so button-ui's own
+     [data-icon-only] rule already squares it to --button-height; pointing
+     --button-height at the nav size (not just literal width/height) avoids
+     the min-width/min-height floor trap. Literal background/color below
+     out-specify button.css's own (via the `button-ui` type-selector bump —
+     same technique as swiper's dots), so the button-ui type-selector prefix
+     is load-bearing, not decorative. */
+  button-ui[data-cal-prev],
+  button-ui[data-cal-next] {
+    --button-height: var(--calendar-grid-nav-size);
+    --a-icon-size: var(--calendar-grid-nav-icon-size);
+
     display: inline-flex;
     align-items: center;
     justify-content: center;
-    width: var(--calendar-grid-nav-size);
     height: var(--calendar-grid-nav-size);
-    padding: 0;
     border: none;
     border-radius: var(--calendar-grid-nav-radius);
     background: var(--calendar-grid-nav-bg);
@@ -131,10 +140,9 @@
     transition:
       background var(--calendar-grid-duration) var(--calendar-grid-easing),
       color      var(--calendar-grid-duration) var(--calendar-grid-easing);
-    --a-icon-size: var(--calendar-grid-nav-icon-size);
   }
-  [data-cal-prev]:hover,
-  [data-cal-next]:hover {
+  button-ui[data-cal-prev]:hover,
+  button-ui[data-cal-next]:hover {
     background: var(--calendar-grid-nav-bg-hover);
     color: var(--calendar-grid-nav-fg-hover);
   }
@@ -164,7 +172,18 @@
     gap: var(--calendar-grid-day-grid-gap);
   }
 
-  [data-cal-day] {
+  /* Stamped <button-ui variant="ghost" text="…"> (gh issue 276 wave 4).
+     button-ui floors min-width/min-height at --button-height — point it at
+     the day-cell size (not just the literal width/height below) so the
+     floor never clamps a smaller [size] tier. The literal geometry/color
+     declarations below out-specify button-ui's own equivalents via the
+     `button-ui` type-selector bump (same technique as swiper's dots).
+     button-ui renders its label via `::after { content: attr(text) }` — the
+     today-indicator dot below therefore uses `::before` (kept free), not
+     `::after`, to avoid the two fighting over the same pseudo-element. */
+  button-ui[data-cal-day] {
+    --button-height: var(--calendar-grid-day-size);
+
     display: flex;
     align-items: center;
     justify-content: center;
@@ -188,25 +207,25 @@
   }
 
   /* ── State: hover ── */
-  [data-cal-day]:not([disabled]):not([data-outside]):hover {
+  button-ui[data-cal-day]:not([disabled]):not([data-outside]):hover {
     background: var(--calendar-grid-day-bg-hover);
     color: var(--calendar-grid-day-fg-hover);
   }
 
   /* ── State: focus ── */
-  [data-cal-day]:not([disabled]):not([data-outside]):focus-visible,
-  [data-cal-day][data-focused] {
+  button-ui[data-cal-day]:not([disabled]):not([data-outside]):focus-visible,
+  button-ui[data-cal-day][data-focused] {
     outline: none;
     box-shadow: var(--calendar-grid-day-focus-ring);
   }
 
   /* ── State: selected ── */
-  [data-cal-day][data-selected] {
+  button-ui[data-cal-day][data-selected] {
     background: var(--calendar-grid-day-bg-selected);
     color: var(--calendar-grid-day-fg-selected);
     font-weight: var(--calendar-grid-selected-weight);
   }
-  [data-cal-day][data-selected]:not([disabled]):hover {
+  button-ui[data-cal-day][data-selected]:not([disabled]):hover {
     background: var(--calendar-grid-day-bg-selected);
     color: var(--calendar-grid-day-fg-selected);
   }
@@ -217,21 +236,21 @@
      fill); the in-range middle is visually subordinate. `:not([data-selected])`
      guard prevents the muted fill from overriding the endpoint cells in
      consumer code that sets both `value` AND `range-start`/`range-end`. */
-  [data-cal-day][data-in-range]:not([data-selected]) {
+  button-ui[data-cal-day][data-in-range]:not([data-selected]) {
     background: var(--calendar-grid-day-bg-in-range);
     color: var(--calendar-grid-day-fg-in-range);
   }
-  [data-cal-day][data-in-range]:not([data-selected]):not([disabled]):hover {
+  button-ui[data-cal-day][data-in-range]:not([data-selected]):not([disabled]):hover {
     background: var(--calendar-grid-day-bg-in-range);
   }
 
   /* ── State: today (unselected) ── */
-  [data-cal-day][data-today]:not([data-selected]) {
+  button-ui[data-cal-day][data-today]:not([data-selected]) {
     position: relative;
     color: var(--calendar-grid-day-today-color);
     font-weight: var(--calendar-grid-today-weight);
   }
-  [data-cal-day][data-today]:not([data-selected])::after {
+  button-ui[data-cal-day][data-today]:not([data-selected])::before {
     content: "";
     position: absolute;
     left: 50%;
@@ -245,13 +264,16 @@
   }
 
   /* ── State: outside month ── */
-  [data-cal-day][data-outside] {
+  button-ui[data-cal-day][data-outside] {
     color: var(--calendar-grid-day-fg-outside);
     cursor: default;
   }
 
-  /* ── State: disabled (excluding outside) ── */
-  [data-cal-day]:disabled:not([data-outside]) {
+  /* ── State: disabled (excluding outside) ──
+     `[disabled]` — NOT the `:disabled` pseudo-class, which only matches
+     native form controls; button-ui is a custom element, so `:disabled`
+     silently never matches it. */
+  button-ui[data-cal-day][disabled]:not([data-outside]) {
     color: var(--calendar-grid-day-fg-disabled);
     cursor: not-allowed;
   }

package/components/calendar-grid/calendar-grid.yaml

@@ -16,6 +16,11 @@ description: >-
   (two side-by-side grids), and datetime-picker-ui (one grid + time pane).
   For a complete date-picker affordance (trigger + popover + form
   participation), use calendar-picker-ui.
+# Per ADR-0027 — primitives that programmatically create other primitives
+# in their render() do NOT auto-import them. Consumer (or demo shell) must
+# explicitly import each composed primitive.
+composes:
+  - button-ui  # day cells + month nav (gh issue 276 wave 4)
 props:
   value:
     description: Selected date in ISO format (YYYY-MM-DD).

package/components/calendar-picker/calendar-picker.a2ui.json

@@ -94,7 +94,9 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "input",
-    "composes": [],
+    "composes": [
+      "button-ui"
+    ],
     "events": {
       "change": {
         "description": "Fired when a date is selected"

package/components/calendar-picker/calendar-picker.class.js

@@ -191,10 +191,14 @@ export class UICalendarPicker extends UIFormElement {
     const maxDate = parseISO(this.max);
 
     // Header
+    // <button-ui variant="ghost" icon="…"> (gh issue 276 wave 4) — no
+    // tabindex here, matching the native version: these nav buttons stay in
+    // the default tab order (unlike calendar-grid-ui's, which are pulled out
+    // via tabindex="-1" for its inline roving-tabindex day grid).
     let h = `<div data-cal-header>
-      <button data-cal-prev type="button" aria-label="Previous month"><icon-ui name="caret-left"></icon-ui></button>
+      <button-ui variant="ghost" size="xs" icon="caret-left" data-cal-prev aria-label="Previous month"></button-ui>
       <span data-cal-title>${MONTHS_LONG[month]} ${year}</span>
-      <button data-cal-next type="button" aria-label="Next month"><icon-ui name="caret-right"></icon-ui></button>
+      <button-ui variant="ghost" size="xs" icon="caret-right" data-cal-next aria-label="Next month"></button-ui>
     </div>`;
 
     // Day-of-week header
@@ -210,7 +214,7 @@ export class UICalendarPicker extends UIFormElement {
     // Previous month trailing days
     for (let i = firstDay - 1; i >= 0; i--) {
       const day = daysInPrev - i;
-      h += `<button type="button" data-cal-day data-outside disabled tabindex="-1">${day}</button>`;
+      h += `<button-ui variant="ghost" data-cal-day data-outside disabled tabindex="-1" text="${day}"></button-ui>`;
     }
 
     // Current month days
@@ -223,7 +227,6 @@ export class UICalendarPicker extends UIFormElement {
       const isFocused = this.#focusedDay === d;
 
       const attrs = [
-        'type="button"',
         'data-cal-day',
         `data-date="${iso}"`,
         isToday ? 'data-today' : '',
@@ -233,14 +236,16 @@ export class UICalendarPicker extends UIFormElement {
         `tabindex="${isFocused ? '0' : '-1'}"`,
       ].filter(Boolean).join(' ');
 
-      h += `<button ${attrs}>${d}</button>`;
+      // <button-ui variant="ghost" text="…"> (gh issue 276 wave 4) — the day
+      // number moves from element text content to the `text` attribute.
+      h += `<button-ui variant="ghost" ${attrs} text="${d}"></button-ui>`;
     }
 
     // Next month leading days
     const totalCells = firstDay + daysInMonth;
     const remaining = (7 - (totalCells % 7)) % 7;
     for (let d = 1; d <= remaining; d++) {
-      h += `<button type="button" data-cal-day data-outside disabled tabindex="-1">${d}</button>`;
+      h += `<button-ui variant="ghost" data-cal-day data-outside disabled tabindex="-1" text="${d}"></button-ui>`;
     }
 
     h += '</div>';