@adia-ai/web-components 0.6.48 → 0.6.50

package/CHANGELOG.md

@@ -1,5 +1,44 @@
 # Changelog — @adia-ai/web-components
 
+## [0.6.50] — 2026-05-30
+
+### Changed — `slot="caret"` disclosure-indicator convention + FEEDBACK-89 (ADR-0036)
+
+- **`components/tree/` (`tree-item-ui`) + `components/pane/` (`pane-ui`)** — renamed the expand/collapse indicator slot `slot="chevron"` → **`slot="caret"`** (and tokens `--*-chevron-*` → `--*-caret-*`, e.g. `--tree-caret-size`, `--pane-caret-fg`), standardizing on the slot name already used by `accordion-item-ui` / `nav-group-ui` / `select-ui` and matching the Phosphor `caret-*` icon vocabulary. **No backward-compat alias** (hard rename; the caret is auto-stamped, so blast radius is small). See [ADR-0036](../../.brain/adrs/0036-caret-slot-disclosure-convention.md).
+- **`tree-item-ui` adopt-or-stamp (FEEDBACK-89)** — `#stamp()` now adopts a consumer's declarative `slot="caret"` and `slot="actions"` children into the auto-stamped row instead of leaving them as siblings below it. A `<button-ui slot="actions">` (the natural way to add a per-row action — add / rename / overflow) now lands inline in the styled, hover-revealed actions area. The host `#onClick` already excludes `[slot="actions"] *` from row selection, so adoption is click-safe. +3 unit tests.
+- **`dist/` CDN bundles** (`web-components.min.css` + `web-components.min.js`) regenerated to carry the renamed `--*-caret-*` tokens + caret stamp logic.
+
+## [0.6.49] — 2026-05-30
+
+### Changed — card-ui header slot sweep + `nav-group-ui` fixes (demos)
+
+- **`patterns/*` + catalog demo HTML** — card-ui header anatomy swept to the canonical `<header>` slot grammar across admin-dashboard + 5 catalog patterns; `nav-group-ui` `label=` → `text=` + icon fixes. Demo/corpus-facing; absorbed into the chunk corpus regen.
+- **31 module demos** — `<!-- design-plan -->` blocks retrofitted across the composite-demo-protocol campaign (Phase 1+3 artifacts embedded).
+
+### Maintenance
+
+- **`dist/web-components.min.js` + `dist/icons-manifest.js`** — bundle rebuild reflecting the calendar-grid `month` prop + date-range-picker class changes.
+
+### Fixed — `<date-range-picker>` showed the same month in both panes
+
+- **`components/calendar-grid/calendar-grid.{class.js,yaml}`** — new `month`
+  attribute (`YYYY-MM`): sets the displayed month when no `value` is selected, so
+  a consumer can show a specific month independent of selection. A selected value
+  always takes precedence.
+- **`components/date-range-picker/date-range-picker.class.js`** — the end pane now
+  defaults to **one month after** the start pane (via the new `month` hint), so a
+  fresh range picker shows two consecutive months (e.g. May + June) instead of the
+  current month twice. A selected `to` date still drives its own pane. Propagates
+  to `<date-range-selector>` (embeds the picker).
+
+### Fixed — `drop-target` demo card-structure violation
+
+- **`traits/drop-target/drop-target.examples.html`** — the 4 `<card-ui>` drop
+  surfaces held `<text-ui>` / `<col-ui>` directly (bypassing the card body slot),
+  failing `check:card-structure` (a `check`-chain gate). Wrapped each in
+  `<section bleed style="display:grid;place-items:center">` — clears the gate while
+  keeping the centered drop-zone appearance. `audit:card-structure` now clean.
+
 ## [0.6.48] — 2026-05-29
 
 ### Demos — library-wide consolidation sweep (HTML-first)

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

@@ -379,7 +379,7 @@ export class UIAgentReasoning extends UIElement {
       <span data-reasoning-meta>
         ${total ? `<span data-reasoning-counter>${done}/${total}</span>` : ''}
         <span data-reasoning-time>${elapsed}s</span>
-        <icon-ui name="${this.collapsed ? 'caret-right' : 'caret-up'}" color="muted" data-reasoning-chevron></icon-ui>
+        <icon-ui name="${this.collapsed ? 'caret-right' : 'caret-up'}" color="muted" data-reasoning-caret></icon-ui>
       </span>
     `;
 

package/components/agent-trace/agent-trace.css

@@ -27,7 +27,7 @@
     --agent-trace-detail-label-col-default: 9rem;
 
     /* ── Motion ── */
-    --agent-trace-chevron-dur-default:   var(--a-duration-fast);
+    --agent-trace-caret-dur-default:   var(--a-duration-fast);
   }
 
   :scope {
@@ -50,7 +50,7 @@
     border-radius: var(--a-radius-sm);
     padding: var(--a-space-0-5) var(--a-space-1);
     margin: calc(var(--a-space-0-5) * -1) calc(var(--a-space-1) * -1);
-    transition: background var(--agent-trace-chevron-dur, var(--agent-trace-chevron-dur-default));
+    transition: background var(--agent-trace-caret-dur, var(--agent-trace-caret-dur-default));
   }
 
   [data-trace-root] > summary:hover {
@@ -94,12 +94,12 @@
     margin-inline: 2px;
   }
 
-  [data-trace-chevron] {
+  [data-trace-caret] {
     flex-shrink: 0;
-    transition: transform var(--agent-trace-chevron-dur, var(--agent-trace-chevron-dur-default));
+    transition: transform var(--agent-trace-caret-dur, var(--agent-trace-caret-dur-default));
   }
 
-  [data-trace-root][open] [data-trace-chevron] {
+  [data-trace-root][open] [data-trace-caret] {
     transform: rotate(90deg);
   }
 
@@ -225,20 +225,20 @@
     text-align: end;
   }
 
-  /* Chevron in the trailing column */
-  [data-trace-row-chevron] {
+  /* Caret in the trailing column */
+  [data-trace-row-caret] {
     --a-icon-size: 0.875em;
     justify-self: end;
     align-self: center;
-    transition: transform var(--a-duration-fast) var(--agent-trace-chevron-dur, var(--a-duration-fast));
+    transition: transform var(--a-duration-fast) var(--agent-trace-caret-dur, var(--a-duration-fast));
     color: var(--agent-trace-fg-muted, var(--agent-trace-fg-muted-default));
   }
 
-  details[data-trace-row][open] > summary > [data-trace-row-chevron] {
+  details[data-trace-row][open] > summary > [data-trace-row-caret] {
     transform: rotate(90deg);
   }
 
-  [data-trace-row-chevron-spacer] {
+  [data-trace-row-caret-spacer] {
     width: 0.875em;
     justify-self: end;
   }

package/components/agent-trace/agent-trace.js

@@ -128,7 +128,7 @@ class UIAgentTrace extends UIElement {
     this.#rootEl.innerHTML = `
       <summary>
         <span data-trace-status>${pillsHTML}</span>
-        <icon-ui name="caret-right" color="muted" size="sm" data-trace-chevron></icon-ui>
+        <icon-ui name="caret-right" color="muted" size="sm" data-trace-caret></icon-ui>
       </summary>
       <div data-trace-body>
         ${this.#metrics.length ? `<div data-trace-rows${hasAnyDetails ? ' data-has-details' : ''}>${headerRow}${rowsHTML}</div>` : ''}
@@ -156,8 +156,8 @@ class UIAgentTrace extends UIElement {
       <span data-trace-aux>${aux}</span>
       ${hasAnyDetails
         ? (hasDetails
-            ? '<icon-ui name="caret-right" color="muted" data-trace-row-chevron></icon-ui>'
-            : '<span data-trace-row-chevron-spacer aria-hidden="true"></span>')
+            ? '<icon-ui name="caret-right" color="muted" data-trace-row-caret></icon-ui>'
+            : '<span data-trace-row-caret-spacer aria-hidden="true"></span>')
         : ''}
     `;
 

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

@@ -31,6 +31,11 @@
       "type": "string",
       "default": ""
     },
+    "month": {
+      "description": "Displayed month (YYYY-MM) used when no value is selected — shows a specific month independent of selection. A selected value always takes precedence. Used by date-range-picker to show its end pane one month ahead of the start.",
+      "type": "string",
+      "default": ""
+    },
     "rangeEnd": {
       "description": "End of a date range (ISO YYYY-MM-DD). See `rangeStart` for the full contract.",
       "type": "string",

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

@@ -61,6 +61,10 @@ export class UICalendarGrid extends UIElement {
 
   static properties = {
     value:    { type: String,  default: '', reflect: true },
+    // Displayed month (`YYYY-MM`) when no `value` is selected — lets a consumer
+    // show a specific month independent of selection (e.g. a date-range picker
+    // showing its end pane one month ahead of the start pane). Selection wins.
+    month:    { type: String,  default: '', reflect: true },
     min:      { type: String,  default: '', reflect: true },
     max:      { type: String,  default: '', reflect: true },
     disabled: { type: Boolean, default: false, reflect: true },
@@ -90,11 +94,14 @@ export class UICalendarGrid extends UIElement {
     this.setAttribute('role', 'group');
     if (!this.hasAttribute('aria-label')) this.setAttribute('aria-label', 'Calendar');
 
-    // Initialize view to selected date or today.
+    // Initialize view to selected date, else the [month] hint, else today.
     const sel = parseISO(this.value);
     if (sel) {
       this.#viewYear = sel.getFullYear();
       this.#viewMonth = sel.getMonth();
+    } else {
+      const vm = /^(\d{4})-(\d{2})$/.exec(String(this.month || '').trim());
+      if (vm) { this.#viewYear = +vm[1]; this.#viewMonth = +vm[2] - 1; }
     }
 
     if (!this.#bound) {

package/components/calendar-grid/calendar-grid.d.ts

@@ -22,6 +22,8 @@ export class UICalendarGrid extends UIElement {
   max: string;
   /** Minimum selectable date in ISO format (YYYY-MM-DD). */
   min: string;
+  /** Displayed month (YYYY-MM) used when no value is selected — shows a specific month independent of selection. A selected value always takes precedence. Used by date-range-picker to show its end pane one month ahead of the start. */
+  month: string;
   /** End of a date range (ISO YYYY-MM-DD). See `rangeStart` for the full contract. */
   rangeEnd: string;
   /** Start of a date range (ISO YYYY-MM-DD). When both rangeStart and rangeEnd are set + ordered, day cells strictly between the endpoints get `[data-in-range]` stamped for visual continuity. Used by `<date-range-picker-ui>` which pushes the same from/to onto both calendar panes. Endpoints themselves render via the `value` prop's `[data-selected]` state. */

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

@@ -22,6 +22,14 @@ props:
     type: string
     default: ''
     reflect: true
+  month:
+    description: >-
+      Displayed month (YYYY-MM) used when no value is selected — shows a specific
+      month independent of selection. A selected value always takes precedence.
+      Used by date-range-picker to show its end pane one month ahead of the start.
+    type: string
+    default: ''
+    reflect: true
   min:
     description: Minimum selectable date in ISO format (YYYY-MM-DD).
     type: string

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

@@ -411,6 +411,15 @@ export class UIDateRangePicker extends UIFormElement {
     }
     if (!calArea.querySelector(':scope > [data-cal-to]')) {
       const calTo = this.constructor._pp.calTo.cloneNode(true);
+      // Default the end pane to one month after the start pane so a fresh range
+      // picker shows two consecutive months (not the same month twice). A `to`
+      // value, once selected, overrides this hint inside the grid.
+      const fromISO = parseRange(this.value)?.from;
+      let y, mo; // mo: 0-based month
+      if (fromISO) { const [yy, mm] = fromISO.split('-').map(Number); y = yy; mo = mm - 1; }
+      else { const now = new Date(); y = now.getFullYear(); mo = now.getMonth(); }
+      mo += 1; if (mo > 11) { mo = 0; y += 1; }
+      calTo.setAttribute('month', `${y}-${pad(mo + 1)}`);
       calArea.appendChild(calTo);
     }
     this.#calFromRef = calArea.querySelector(':scope > [data-cal-from]');

package/components/field/field.test.js

@@ -227,9 +227,14 @@ describe('field-ui', () => {
     expect(scopeBlock[0]).not.toMatch(/row-gap\s*:/);
   });
 
-  it('CSS source contract: `:scope:has(> [slot="hint"], > [slot="error"])` declares row-gap', () => {
+  it('CSS source contract: `:scope:has([slot="hint"], [slot="error"])` declares row-gap', () => {
+    // The `>` direct-child combinator is OPTIONAL — field.css uses the
+    // descendant form `:has([slot="hint"], [slot="error"])` (v0.6.x); either
+    // satisfies the FB-54 row-gap-presence-guard contract.
     expect(FIELD_CSS).toMatch(
-      /:scope:has\(>\s*\[slot="hint"\]\s*,\s*>\s*\[slot="error"\]\)\s*\{[^}]*row-gap:\s*var\(--field-gap\)/
+      // `var(--field-gap[,)]` accepts both the bare token and the override-aware
+      // `var(--field-gap, var(--field-gap-default))` chain (OD-5 token-shadowing).
+      /:scope:has\((?:>\s*)?\[slot="hint"\]\s*,\s*(?:>\s*)?\[slot="error"\]\)\s*\{[^}]*row-gap:\s*var\(--field-gap[,)]/
     );
   });
 });

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

@@ -65,6 +65,12 @@
       "Accordion"
     ],
     "slots": {
+      "actions": {
+        "description": "Per-row action buttons (rename / add / overflow menu), right-aligned and hover-revealed. A declarative `slot=\"actions\"` child is adopted into the auto-stamped row (FEEDBACK-89), so it sits inline in the row rather than wrapping below it."
+      },
+      "caret": {
+        "description": "Override slot for the expand/collapse caret. Auto-stamped as `<icon-ui slot=\"caret\" name=\"caret-right\">` (rotates on `[open]`, hidden for leaf nodes). Supply your own `slot=\"caret\"` child to customize — adopt-or-stamp moves a declarative caret into the row."
+      },
       "icon": {
         "description": "Override the leading [icon] glyph with a custom slotted element (custom icon-ui, folder open/closed glyph, file-type marker). Mutually exclusive with the [icon] attribute — slot child wins."
       }

package/components/tree/tree-item.yaml

@@ -47,6 +47,18 @@ slots:
       Override the leading [icon] glyph with a custom slotted element (custom
       icon-ui, folder open/closed glyph, file-type marker). Mutually exclusive
       with the [icon] attribute — slot child wins.
+  caret:
+    description: >-
+      Override slot for the expand/collapse caret. Auto-stamped as
+      `<icon-ui slot="caret" name="caret-right">` (rotates on `[open]`,
+      hidden for leaf nodes). Supply your own `slot="caret"` child to
+      customize — adopt-or-stamp moves a declarative caret into the row.
+  actions:
+    description: >-
+      Per-row action buttons (rename / add / overflow menu), right-aligned
+      and hover-revealed. A declarative `slot="actions"` child is adopted
+      into the auto-stamped row (FEEDBACK-89), so it sits inline in the row
+      rather than wrapping below it.
 
 a2ui:
   rules:
@@ -72,7 +84,7 @@ a2ui:
     - >-
       Nest further <tree-item-ui> in the default slot only — no
       <list-item-ui>, <nav-item-ui>, or arbitrary content inside a
-      tree row. The chevron is auto-stamped when the row has nested
+      tree row. The caret is auto-stamped when the row has nested
       tree-item-ui children.
 
 keywords:

package/components/tree/tree.a2ui.json

@@ -126,8 +126,8 @@
       "--tree-bg-selected": {
         "description": "Background color when selected"
       },
-      "--tree-chevron-size": {
-        "description": "Size of the collapse chevron icon"
+      "--tree-caret-size": {
+        "description": "Size of the collapse caret icon"
       },
       "--tree-duration": {
         "description": "Transition duration"
@@ -139,7 +139,7 @@
         "description": "Primary text color"
       },
       "--tree-fg-muted": {
-        "description": "Muted text color (icons, chevrons)"
+        "description": "Muted text color (icons, carets)"
       },
       "--tree-focus-ring": {
         "description": "Focus ring box-shadow"

package/components/tree/tree.class.js

@@ -293,11 +293,17 @@ export class UITreeItem extends UIElement {
     row.setAttribute('slot', 'row');
     row.setAttribute('tabindex', '0');
 
-    // Chevron
-    const chevron = document.createElement('icon-ui');
-    chevron.setAttribute('slot', 'chevron');
-    chevron.setAttribute('name', 'caret-right');
-    row.appendChild(chevron);
+    // Caret — adopt a declarative [slot="caret"] child if the consumer supplied
+    // one, else stamp the default. (Adopt-or-stamp; same pattern as actions.)
+    const declaredCaret = this.querySelector(':scope > [slot="caret"]');
+    if (declaredCaret) {
+      row.appendChild(declaredCaret);
+    } else {
+      const caret = document.createElement('icon-ui');
+      caret.setAttribute('slot', 'caret');
+      caret.setAttribute('name', 'caret-right');
+      row.appendChild(caret);
+    }
 
     // Icon
     if (this.icon) {
@@ -320,10 +326,19 @@ export class UITreeItem extends UIElement {
     if (this.badge) badgeEl.textContent = this.badge;
     row.appendChild(badgeEl);
 
-    // Actions slot placeholder
-    const actions = document.createElement('span');
-    actions.setAttribute('slot', 'actions');
-    row.appendChild(actions);
+    // Actions — adopt pre-existing declarative [slot="actions"] children into
+    // the row (FEEDBACK-89) so per-row action buttons land in the styled,
+    // hover-revealed actions area; else stamp an empty placeholder. The host
+    // #onClick already excludes [slot="actions"] * from row selection, so
+    // adoption is click-safe.
+    const declaredActions = this.querySelectorAll(':scope > [slot="actions"]');
+    if (declaredActions.length) {
+      for (const a of declaredActions) row.appendChild(a);
+    } else {
+      const actions = document.createElement('span');
+      actions.setAttribute('slot', 'actions');
+      row.appendChild(actions);
+    }
 
     this.prepend(row);
   }

package/components/tree/tree.css

@@ -7,7 +7,7 @@
     --tree-row-gap-default:         var(--a-space-1);
     --tree-actions-gap-default:     var(--a-space-0-5);
     --tree-indent-default:          var(--a-space-4);
-    --tree-chevron-size-default:    var(--a-space-2);
+    --tree-caret-size-default:      var(--a-space-2);
     --tree-icon-size-default:       var(--a-space-3);
 
     /* ── Typography ── */
@@ -47,7 +47,7 @@
     --tree-item-row-gap:       var(--tree-row-gap, var(--a-space-1));
     --tree-item-actions-gap:   var(--tree-actions-gap, var(--a-space-0-5));
     --tree-item-indent:        var(--tree-indent, var(--a-space-4));
-    --tree-item-chevron-size:  var(--tree-chevron-size, var(--a-space-2));
+    --tree-item-caret-size:    var(--tree-caret-size, var(--a-space-2));
     --tree-item-icon-size:     var(--tree-icon-size, var(--a-space-3));
 
     --tree-item-fg:            var(--tree-fg, var(--a-fg));
@@ -92,21 +92,21 @@
 
   /* :scope[selected] rules moved outside @scope — see tree-ui Safari note at end of file. */
 
-  /* ── Chevron ── */
-  [slot="chevron"] {
-    --a-icon-size: var(--tree-chevron-size, var(--tree-chevron-size-default));
+  /* ── Caret ── */
+  [slot="caret"] {
+    --a-icon-size: var(--tree-caret-size, var(--tree-caret-size-default));
     flex-shrink: 0;
     color: var(--tree-fg-muted, var(--tree-fg-muted-default));
     transition: transform var(--tree-duration, var(--tree-duration-default)) var(--tree-easing, var(--tree-easing-default));
     transform: rotate(90deg);
   }
 
-  :scope:not([open]) > [slot="row"] > [slot="chevron"] {
+  :scope:not([open]) > [slot="row"] > [slot="caret"] {
     transform: rotate(0deg);
   }
 
-  /* Hide chevron for leaf nodes */
-  :scope:not(:has(> tree-item-ui)) > [slot="row"] > [slot="chevron"] {
+  /* Hide caret for leaf nodes */
+  :scope:not(:has(> tree-item-ui)) > [slot="row"] > [slot="caret"] {
     visibility: hidden;
   }
 

package/components/tree/tree.test.js

@@ -101,3 +101,55 @@ describe('<tree-ui> tree-select forwards modifier keys (FB-46)', () => {
     expect(received.shiftKey).toBe(false);
   });
 });
+
+describe('<tree-item-ui> caret slot + actions adoption (caret convention + FB-89)', () => {
+  let host;
+  const settle = () => new Promise((r) => setTimeout(r, 30));
+
+  beforeEach(() => {
+    host = document.createElement('div');
+    document.body.appendChild(host);
+  });
+  afterEach(() => host.remove());
+
+  it('auto-stamps a slot="caret" icon (renamed from slot="chevron")', async () => {
+    const item = document.createElement('tree-item-ui');
+    item.setAttribute('text', 'Colors');
+    host.appendChild(item);
+    await settle();
+    const row = item.querySelector(':scope > [slot="row"]');
+    expect(row.querySelector('[slot="caret"]')).toBeTruthy();
+    expect(row.querySelector('[slot="chevron"]')).toBeNull();
+  });
+
+  it('adopts a declarative slot="actions" child into the stamped row (FB-89)', async () => {
+    const item = document.createElement('tree-item-ui');
+    item.setAttribute('text', 'Colors');
+    const btn = document.createElement('button-ui');
+    btn.setAttribute('slot', 'actions');
+    btn.setAttribute('icon', 'plus');
+    item.appendChild(btn);
+    host.appendChild(item);
+    await settle();
+    const row = item.querySelector(':scope > [slot="row"]');
+    // The action button is now INSIDE the row, not a sibling left below it.
+    expect(btn.parentElement).toBe(row);
+    expect(item.querySelector(':scope > [slot="actions"]')).toBeNull();
+  });
+
+  it('adopts a declarative slot="caret" child instead of stamping a default', async () => {
+    const item = document.createElement('tree-item-ui');
+    item.setAttribute('text', 'Colors');
+    const customCaret = document.createElement('icon-ui');
+    customCaret.setAttribute('slot', 'caret');
+    customCaret.setAttribute('name', 'folder');
+    item.appendChild(customCaret);
+    host.appendChild(item);
+    await settle();
+    const row = item.querySelector(':scope > [slot="row"]');
+    const carets = row.querySelectorAll('[slot="caret"]');
+    expect(carets.length).toBe(1);                    // no double-stamp
+    expect(carets[0]).toBe(customCaret);              // consumer's caret used
+    expect(carets[0].getAttribute('name')).toBe('folder');
+  });
+});

package/components/tree/tree.yaml

@@ -59,8 +59,8 @@ tokens:
     description: Background color on hover
   --tree-bg-selected:
     description: Background color when selected
-  --tree-chevron-size:
-    description: Size of the collapse chevron icon
+  --tree-caret-size:
+    description: Size of the collapse caret icon
   --tree-duration:
     description: Transition duration
   --tree-easing:
@@ -68,7 +68,7 @@ tokens:
   --tree-fg:
     description: Primary text color
   --tree-fg-muted:
-    description: Muted text color (icons, chevrons)
+    description: Muted text color (icons, carets)
   --tree-focus-ring:
     description: Focus ring box-shadow
   --tree-font-size:
@@ -121,7 +121,7 @@ a2ui:
       rows — selection is managed by the parent and bubbles once.
       Detail = {item, text, value, ctrlKey, metaKey, shiftKey}.
     - >-
-      Per ADR-0027, <tree-ui> composes <icon-ui> (for chevrons) but
+      Per ADR-0027, <tree-ui> composes <icon-ui> (for carets) but
       does NOT auto-import its children. Consumer pages must
       explicitly import both <tree-ui> and <tree-item-ui>.
 anti_patterns: []