@adia-ai/web-components 0.6.50 → 0.7.1

package/CHANGELOG.md

@@ -1,5 +1,139 @@
 # Changelog — @adia-ai/web-components
 
+## [0.7.1] — 2026-05-31
+
+### Fixed
+
+- **`<input-ui>` leading/trailing affordance vertical centering** — the affordance slots used `align-self: stretch`, which top-aligned any child carrying a definite `height` (a `<kbd-ui slot="trailing">` ⌘K hint sat ~4px high in a 30px chrome) and also overrode a `<button-ui>` child's own `--button-height`. Changed to `align-self: center` so each affordance keeps its token height and sits on the field's vertical center. Affects every intrinsic-height affordance (kbd / icon / badge); button affordances are unchanged (they already filled the chrome). (bug-60)
+- **`<tree-ui>` nested items now satisfy the WAI-ARIA tree pattern** — the `tree-item-ui` host is now `role="group"` and its focusable `[slot="row"]` is the `role="treeitem"` (with `aria-expanded`/`aria-selected` moved onto the row). Previously the host was the `treeitem` and nested items had no `group`/`tree` required parent, tripping axe-core `aria-required-parent` (critical) on every nested node. Done without re-homing children, so it holds for static markup AND template-engine `.map()` trees; no CSS/yaml change. Validated with real axe-core (0 violations). (FEEDBACK-91)
+- **`<menu-ui>` renders dynamically-generated items** — `#show()` collected items with a direct-child `:scope >` query, which missed `menu-item-ui` rendered via `.map()`/`repeat()` (the template engine nests them in `display:contents` wrapper spans) → the popover opened empty. Now uses a descendant query (skipping items already relocated into the popover), matching `#hide()` and resolving the show/hide asymmetry. Static children unaffected. (FEEDBACK-92)
+- **`<input-ui>` reactive `prefix=`/`suffix=` bindings resolve** — a reactive attribute binding (`suffix="${expr}"`) leaked the literal template placeholder `{{p:N}}` as affix text, because the shell was snapshotted once in `connected()` before the binding resolved and never re-synced. `render()` now re-resolves the prefix/suffix slots each cycle (handling text↔icon affixes), mirroring the slider-ui FB-45 fix. Literal and `.property` affixes are unchanged. (FEEDBACK-93)
+- **`dist/` CDN bundles regenerated** (`web-components.min.css` + `web-components.min.js`) to carry the input/tree/menu fixes above.
+
+### Changed — demos
+
+- **`<field-ui>` inline-layout demo** — the "Results: 12" count moved from a field-level `<span slot="trailing">` (beside the input) into the input's `suffix` prop, so it renders **in-chrome, left of the Clear button** (DOM order value → `suffix` → `trailing`). The demo now shows all three affordances inside the input chrome and the note explains the suffix-vs-trailing split. (bug-60)
+
+## [0.7.0] — 2026-05-31
+
+### Added — component features from the docs-QA pass
+
+- **`<stat-ui bleed>`** — horizontal-bleed KPI tile. With a `slot="chart"` child, value/label/change stack on the left while the chart fills the right column at full height and bleeds to the card's top/right/bottom edges (the horizontal counterpart to a chart in a `<section bleed>`). First-class reflected Boolean attr (yaml + `static properties`; not a `data-*` hook).
+- **`<page-ui>` region model** — `--page-inset` vertical rhythm between `header`/`section`/`footer` children + `[bleed]` (edge-to-edge, cancels the page `[padding]`) + `section[padding]` (padded sub-surface), mirroring card-ui's section model. The docs promised `@scope` styled the regions but no such rules existed — regions stacked with zero spacing.
+- **`<timeline-ui>` `--timeline-marker-box-size`** — unified marker footprint (1rem; 0.875rem at `size=sm`) the dot/icon/spinner center within; icon-mode chips gain a ring (`--timeline-icon-border`) so they read as markers even when the muted fill blends with the surface.
+- **`<integration-card-ui>` provider→icon fallback** — a card with only `[provider]` (no `[logo]`) now renders a per-provider Phosphor glyph (slack→chat-circle, github→git-branch, …) or a generic `plug`, instead of a blank logo disc.
+- **`<kbd-ui>` `size="lg"`** — added the missing `lg` to the size enum (CSS + docs already shipped three sizes; the yaml capped at sm/md).
+
+### Fixed — docs-QA pass (browser-verified)
+
+- **`<datetime-picker-ui>`** — committed value now uses the picker-family value color (`--a-ui-text`, bright) + `space-between` alignment (value left, caret right), matching input-ui/select-ui/time-picker (was a centered, dim default button); `[data-has-value]` gates the brightening.
+- **`<kbd-ui>`** — `md` glyph was `--a-ui-tiny` (10px), identical to `sm`; now `--a-ui-xs` (12px) for a real 10/12/14 sm/md/lg ramp.
+- **`<empty-state-ui>`** — heading moved from `--a-ui-lg` (15px control-label ramp; only 1.07× the description) to `--a-heading-md` (17px → 1.21×); the `[minimal]` inline variant keeps the heading bolder + non-muted so it stays distinct from the description.
+- **`<heatmap-ui>`** — `type="day-grid"` keeps fixed cell tracks + scrolls horizontally (GitHub-contributions model) instead of crushing fixed cells into an overlapping smear in narrow containers; `matrix`/`density` keep fitting-and-shrinking.
+- **`<option-card-ui>` `layout="tile"`** — DOM-order-independent (via `order`) with the radio pinned to the card's top-right (cleared the base `grid-area:indicator` that stranded it in a collapsed 8px gutter); token-driven padding. Fixes plan-picker's tile cards.
+- **`<preview-ui>` form-demo width** — the docs render cell capped `<field-ui>` at `max-width:28rem` (448px) together with bare form controls; since field-ui is a full-width form _row_ (its own CSS is `width:100%`), the cap stranded it mid-cell, reading as "not using the available space" on wide single-block demos. Split the rule: field-ui now fills the stage (no cap); bare atomic controls (input/select/combobox/textarea/tags-input/color-input) keep the 28rem measure cap so a lone control doesn't sprawl. (bug-55 follow-up)
+
+### Changed — demos + corpus hygiene (docs-QA pass)
+
+- **`<field-ui>` demos** — migrated in-chrome affordances (copy / clear / ⌘K) onto `input-ui`'s `leading`/`trailing` slots (inside the input box); field's `trailing`/`action` reserved for beside-field captions + submit buttons. Slots table + A2UI guidance now state the boundary. Short in-chrome _status_ text (e.g. "Required") now uses `input-ui`'s `suffix`/`prefix` attribute rather than a `<span slot="trailing">` _outside_ the input — keeps the status inside the field chrome and lets the input fill the full field width (demo `field-default-trailing-caption` → `field-default-inchrome-required`). (bug-55)
+- **`<inline-edit-ui>` form-participation demo** — key-labelled rows (title/description) + instructional placeholder so the form-field semantics are legible.
+- **`<integration-card-ui>` CRUD-drawer demo** — fixed an invisible drawer: the demo used `side="trailing"`, which is not in the `drawer-ui` `side` enum (`left|right|top|bottom`), so the panel `showModal()`'d but rendered at `opacity:0` collapsed in the top-left. Switched to `side="right"`. (bug-50)
+- **Dead `size="sm"` swept** off layout primitives (`row-ui`/`col-ui`/`grid-ui`) + bare `<span slot="action">` across `patterns/` demos (68 sites repo-wide) — the attribute is a no-op on those tags and polluted the gen-UI corpus.
+- **`dist/` CDN bundles regenerated** (`web-components.min.css` + `web-components.min.js`) for the docs-QA CSS/JS changes + the breaking removals.
+
+### Removed (BREAKING) — `<avatar-ui name="…">` deprecated alias retired
+
+- **`<avatar-ui>` no longer accepts the `name` attribute** — use `text` instead.
+  `name` was a deprecated alias for `text` since 0.4.x (`deprecated_since: "0.4.x"`,
+  scheduled for v0.6.0; the codebase reached v0.6.50 still carrying it). Retired in
+  full: removed from `avatar.yaml`, the `static properties` map + `displayName`
+  fallback + the one-shot deprecation `console.warn` + the `#nameWarned` flag in
+  `avatar.class.js`, the `name: string` typing in `avatar.d.ts`, and the
+  regenerated `avatar.a2ui.json` sidecar. The `<img>` `alt` now derives from
+  `displayName` (= `text`). **Migration:** `<avatar-ui name="Ada">` →
+  `<avatar-ui text="Ada">`. No in-repo markup, demo, or corpus chunk used the
+  alias (the corpus was swept long ago; the one stray demo was fixed in
+  `d3b482c61`). _Pre-1.0 breaking change — bump MINOR on the next cut._
+
+### Removed (BREAKING) — `<chart-ui>` `aspect` + `heading` retired (OD-CHART-02)
+
+- **`<chart-ui>` no longer accepts `aspect` or `heading`** — both were
+  deprecated-but-functional with no removal date; retired across yaml + class.js +
+  d.ts + css + sidecar.
+  - **`aspect`** (`std`/`wide`/`square`/`tall` — derived the chart's implicit
+    height from width): charts without an explicit height now always use the
+    standard 4:3 ratio (the prior default, so default charts are unchanged; only
+    explicit `aspect="wide|square|tall"` changes). **Migration:** size the chart
+    via its parent (width/height on the enclosing card/container).
+  - **`heading`** (rendered a title element + fed `aria-label`): **Migration:** put
+    the visual title in an enclosing `card-ui` `<header><span slot="heading">`; for
+    a descriptive accessible name set `aria-label` directly. With neither,
+    `aria-label` now falls back to `"<type> chart"` (e.g. "bar chart"). Verified:
+    69 demo charts render, 0 console errors. _Pre-1.0 breaking — bump MINOR._
+
+### Removed — `<avatar-ui size>` long-form aliases (were non-functional)
+
+- **`<avatar-ui size>` drops `small`/`medium`/`large`/`xlarge`** — use the
+  canonical `xs`/`sm`/`md`/`lg`/`xl`. These were declared in `avatar.yaml` +
+  `avatar.d.ts` "for back-compat" but had **no CSS implementation** (`avatar.css`
+  only defines `:scope[size="xs|sm|md|lg|xl"]`), so `size="small"` silently
+  rendered at the base default size — they never worked. Runtime behavior is
+  unchanged; this removes the misleading values from the typed API + the sidecar
+  the LLM prompt builder reads (training-data noise). No in-repo markup used them.
+
+### Changed — global styles assigned to `@layer` cascade layers (ADR-0038)
+
+- `packages/web-components/styles/` now assigns every rule to a named cascade layer — `@layer reset, tokens, elements, components, utilities, context, overrides` — so precedence is **declared once** instead of faked per-rule via specificity/`:where()`. The published bundle + barrel carry the layers; **rule content is unchanged** — only layer membership. Cuts: `resets.css` → `reset`; `colors/` + `foundation/` → `tokens`; `type/elements.css` → `elements`; the 128 scoped components → `components`; `api/{sizing,text,layout}` + `[variant]` → `utilities`; `themes.css` + `prose.css` → `context`; `overrides` declared topmost and **reserved (empty)** for consumer rules. A consumer rule in `@layer overrides` now wins by layer order with no `!important` and no specificity war (proven: a `(0,0,1)` `badge-ui{font-weight:321}` override beats both the component's `@scope` 500 and a `[weight="bold"]` 700).
+- **One intentional behavior change (IPC-04).** Utility attributes — `[weight]` `[color]` `[transform]` `[text-align]` `[variant]` — now **override** a component's own `@scope` rule (they sit in `utilities`, above `components`). Previously they lost to component `@scope` by scope-proximity, and api/text.css documented that limitation — now retired. Measured blast radius: **39 component×property honorings across 128 components** (25 `color`, 10 `font-weight`, 3 `text-align`, 1 `text-transform`), zero breakage. Every *other* cut is behavior-neutral (real-browser computed-style probe 0 diffs; token identity byte-identical). The `ul/ol[role="list"]` reset and the `h1–h6` role defaults were relocated into `type/elements.css` (element-default refinements that must win by specificity *within* the `elements` layer). See ADR-0038 + `docs/specs/cascade-layer-architecture.md`.
+
+### Added — `<select-ui>` per-option `icon` / `avatar`, reflected in the trigger
+
+- **`components/select/{select.class.js,select.css,select.yaml}`** — `<option>` now accepts `icon` (Phosphor name) and `avatar` (image URL): `<option value="light" icon="sun">`. Each option renders its glyph in the listbox row **and** the trigger reflects the **selected** option's icon/avatar (theme pickers, assignee/account switchers). Previously a host-level `[icon]` was static — selecting "Light" still showed the fixed `moon`. `#parseOptions` now captures `icon`/`avatar` from declarative `<option>`/`<optgroup>` children (and the `.options` array shape gains `icon?`/`avatar?`); a new `#syncLeading()` reconciles the trigger's `[slot="leading"]` to the selected option on every render (avatar beats icon; host `[icon]`/`[avatar]` is the fallback). Only manages the component-stamped trigger (`[data-select-leading]`) — a consumer-custom trigger owns its own leading. Multi-select is unaffected (chips). +CSS for `[role="option"] img[data-option-avatar]`; sidecar regenerated. Verified in-browser: trigger shows `sun` for selected "Light", updates to `moon` on selecting "Dark"; per-option avatars render in trigger + rows; 21/21 unit tests green.
+
+### Changed — block-level display by default + universal `[inline]` attribute (ADR-0037)
+
+- Composite / control / container primitives now default to a **block-level** host `display` (`flex`/`block`/`grid`); the new universal **`[inline]`** boolean opts back to inline-level (`inline-flex`/`inline-block`/`inline-grid`). Flipped 14 primitives: `button` (text → full-width block, icon-only held inline via `:not([text])`), `color-input`, `date-range-picker`, `datetime-picker`, `time-picker`, `breadcrumb`, `pagination`, `segmented`, `toggle-group`, `toggle-scheme`, `menu`, `popover`, `image`, `qr-code`. **Text-flow atoms stay inline** (`text` `link` `mark` `number-format` `relative-time` `inline-edit` `inline-message` `badge` `tag` `chip` `kbd` `icon` `radio` `check` `switch` `avatar` `swatch` `rating` `spinner`). CSS-only — per-component `:scope[inline]` (specificity 0,2,0 reliably overrides `:scope`); no yaml/JS/sidecar (universal-attribute precedent: `[grow]`/`[hidden]`). **Inside `row-ui`/`col-ui`/`grid-ui` the flip is a no-op** (flex/grid items are blockified), so real-composition rendering is unchanged — only standalone-in-block-flow goes full-width. `field`/`fields` carve out `[inline]` for their single-row *layout* mode. `api/layout.css` documents the per-component rationale. See ADR-0037 + `docs/specs/attribute-api-system.md` §5.
+
+### Changed — `chevron` → `caret` terminology sweep (FEEDBACK-90, ADR-0036 follow-up)
+
+- Renamed residual `chevron` terminology to `caret` across 14 component files so the codebase carries one vocabulary (matching the `slot="caret"` convention + the Phosphor `caret-*` icon names). **`agent-artifact`** is the only behavioral surface: `[data-artifact-chevron]` → `[data-artifact-caret]` + `#chevronEl` → `#caretEl` (internal-render collapse indicator — a data-attr styling hook, not a slot, same as `agent-trace`/`agent-reasoning`). The rest is comment/description terminology (`timeline`; `table`/`select` yaml + regenerated a2ui descriptions; `input`/`pagination`/`action-list`/`calendar-grid`/`calendar-picker` comments). **Carve-out:** kept breadcrumb's `data-chunk="…-chevron-sep"` corpus identifier — the separator is semantically a chevron, not a disclosure caret, and renaming a harvested chunk name is a separate re-harvest. No consumer-facing behavior change.
+
+### Fixed — form-field demos collapsed to content-width in `<preview-ui>` (demos)
+
+- **`components/preview/preview.css`** — a `<field-ui>` (and bare text-field controls) is a flex item in the render cell, so form-field demos sized to their content — a placeholder-only `combobox-ui` shrank to a ~52px "Sel…" stub (input/select were also content-width, just less obvious). The render cell now stretches `field-ui` + text-field controls (`input-ui`/`select-ui`/`combobox-ui`/`textarea-ui`/`tags-input-ui`/`color-input-ui`) to the cell width, capped at `28rem` so single-block stages don't sprawl. Lifts **every** form-field demo to a realistic width at once (combobox 52→202px rows / 448px single-block); non-form demos (buttons, badges, …) keep content-width. Verified 0 console errors across 12 component + pattern pages.
+
+### Fixed — `<combobox-ui>` `[size]` didn't step the field height
+
+- **`components/combobox/combobox.css`** — the editable `[data-input]` span picked up `8px` block padding from an outer source that out-cascaded the `@scope` rule, pinning the field to ~36px at **every** `[size]` (sm/md/lg measured 36.2 / 37.6 / 39px — barely distinguishable). A higher-specificity guard (`combobox-ui [data-field] [data-input] { padding-block: 0 }`) zeroes it so the field height tracks `--a-size` like `input-ui`/`select-ui` — now **24 / 30 / 36px** for sm/md/lg. (The 8px source isn't in combobox/global/inline CSS — likely a leaked reset or a `contenteditable="plaintext-only"` behavior; flagged for a follow-up audit.)
+
+### Added — `<combobox-ui>` demo depth (demos)
+
+- **`components/combobox/combobox.examples.html`** — +5 attribute sections closing the depth gap surfaced by the demo-coverage audit (was ~7/17 demonstrable attributes): `prefix`/`suffix` slot (search-icon prefix), `highlight-match`, `loading`, `disabled`, `readonly`. All render correctly now that the width fix above is in place (the prefix demo had appeared collapsed only because of the content-width bug).
+
+### Fixed — `<alert-ui>` `slot="action"` rendered wedged between icon and message
+
+- **`components/alert/alert.css`** — a trailing `[slot="action"]` button rendered on the **left** (between the leading icon and the message) instead of trailing right, contradicting the documented "right-aligned trailing affordance." Cause: `alert.js` appends the auto-stamped `[slot="content"]`/`[slot="leading"]` *after* any author-provided action button, and the standard render path (unlike the dunning path) gave the action/close slots no `order`, so they sorted in DOM order. Added explicit `order: 1` (action) + `order: 2` (close) so the layout is always `icon → content → action → close`, with content's `flex: 1` pushing both affordances to the trailing edge. Latent since the feature shipped — first exercised by the new demo (no prior `alert-ui` consumer used `slot="action"`). Verified via DOM geometry probe (`iconX < contentX < actionX ≤ closeX`).
+
+### Fixed — `<alert-ui>` dunning `due-at` showed the previous calendar day
+
+- **`components/alert/alert.class.js`** — `#formatDueDate()` parsed a date-only ISO string (`"2026-05-20"`) as UTC midnight, which a behind-UTC locale then formatted as the *previous* day ("May 19"). Date-only strings are now pinned to local midnight (`"…T00:00:00"`) so the authored calendar day is preserved; full timestamps (with time/offset) keep their exact instant. Invisible in jsdom (UTC) — only manifested in a real browser, so the lenient existing tests (`/May/`, `/2026/`) stayed green (30/30); also corrects the shared `billing-overview` dunning banner.
+
+### Added — `<alert-ui>` demo depth (demos)
+
+- **`components/alert/alert.examples.html`** — +3 sections taking attribute coverage 33% → **100%** (demo-coverage audit): `title`+`description` (two-line headline/body), `action slot` (trailing button), and the full `dunning` payment-failed pattern (SPEC-006 — `pattern`/`amount`/`currency`/`due-at`/`card-last4`/`reason` across all four reasons + a warning grace-period), plus the `dismissible` alias. Props/Events/Slots tables extended to document the dunning API (`actions` slot, `dunning-action` event). Grounded against SPEC-006 + the real `billing-overview` consumer; surfaced the two `alert-ui` fixes above.
+
+### Fixed — `<switch-ui>` `[hint]` rendered beside the label instead of below
+
+- **`components/switch/switch.css`** — the `[hint]` caption is documented (yaml + props table + the rule's own comment "Caption beneath the toggle row") as rendering BELOW the label, but the base `inline-flex` row laid the stamped `[slot="hint"]` out as a third inline item beside the label. A `:has([slot="hint"])`-scoped `flex-wrap` + `flex-basis: 100%` now wraps the hint onto its own full-width line, indented under the label. No display-model change (stays `inline-flex`); hint-less switches are 100% unchanged (the hint span is stamped only when `[hint]` is set). Latent since §184 — surfaced by the demo-depth pass.
+
+### Fixed — `<list-ui>` `[selectable]` selection chrome was never applied (upgrade race)
+
+- **`components/list/list.class.js`** — `selectable` + `selected-key` set no visual selection (`aria-selected` null on every row). Light-DOM upgrade race: `render()`'s `#items()` filtered children by `role="listitem"`, but each `<list-item-ui>` sets that role in its OWN `connected()`, which hasn't run when the parent first `render()`s → `#items()` returned `[]` → `aria-selected` never stamped → the `[aria-selected="true"]` selection CSS never matched. `#items()` now also matches by tag name (`LIST-ITEM-UI`, present pre-upgrade); the attribute persists through the child's later upgrade. Latent since the selection feature shipped (no demo exercised it); +0 test changes, 5/5 green.
+
+### Added — primitive demo-depth wave, Phase 3 (demos)
+
+- Drove six audit-`critical` primitives to full attribute coverage (demo-coverage audit), each authored from source/spec grounding and browser-probed (0 console errors, visual QA): **`swatch`** 27% → 100% (detail/copyable/copy-value, badge gamut pips, selectable/selected, label-position overlay + auto-contrast); **`color-picker`** 44% → 100% (OKLCH generation constraints — max-chroma / min-l·max-l / base-hue·hue-drift-max — plus corrected the `format` demo to the real `[hex, oklch]` enum and dropped a non-existent `required` prop from its table); **`switch`** 43% → 100% (hint, name/value/required); **`list`** 40% → 100% (contained, selectable/selected-key, + real `selection-change` event docs); **`context-menu`** 33% → 100% (open, long-press-ms); **`toggle-scheme`** 33% → 92% (scoped `target` + icon/label-light/dark + color + storage-prefix; the read-only reflected `active-scheme` is intentionally not authored, + corrected two table defaults vs yaml). Demo-only `examples.html` changes except the two `switch`/`list` fixes above.
+
 ## [0.6.50] — 2026-05-30
 
 ### Changed — `slot="caret"` disclosure-indicator convention + FEEDBACK-89 (ADR-0036)

package/components/action-list/action-list.css

@@ -98,7 +98,7 @@ action-item-ui:hover [slot="icon"] {
     text-overflow: ellipsis;
   }
 
-  /* Default slot (trailing content: kbd, badge, chevron) pushed to far right */
+  /* Default slot (trailing content: kbd, badge, caret) pushed to far right */
   & > :not([slot="icon"]):not([slot="text"]) {
     flex-shrink: 0;
     margin-inline-start: auto;

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

@@ -58,7 +58,7 @@ export class UIAgentArtifact extends UIElement {
     tone:      { type: String,  default: 'neutral', reflect: true },
   };
 
-  // §205 (v0.5.7): dynamic chevron icons stamped on collapse/expand state
+  // §205 (v0.5.7): dynamic caret icons stamped on collapse/expand state
   // transition (agent-artifact.class.js:119+188). Per FEEDBACK-16 §1 + §209 slot-11 ternary-
   // walker discovery. Note: `this.icon` consumer-supplied — not declared here.
   static requiredIcons = ['caret-right', 'caret-down'];
@@ -69,7 +69,7 @@ export class UIAgentArtifact extends UIElement {
   #iconEl = null;
   #titleEl = null;
   #kindEl = null;
-  #chevronEl = null;
+  #caretEl = null;
   #bodyEl = null;
 
   connected() {
@@ -80,7 +80,7 @@ export class UIAgentArtifact extends UIElement {
     this.#headerEl?.removeEventListener('click', this.#onHeaderClick);
     this.#headerEl?.removeEventListener('keydown', this.#onHeaderKey);
     this.#headerEl = this.#iconEl = this.#titleEl = null;
-    this.#kindEl = this.#chevronEl = this.#bodyEl = null;
+    this.#kindEl = this.#caretEl = this.#bodyEl = null;
   }
 
   #onHeaderClick = (e) => {
@@ -120,8 +120,8 @@ export class UIAgentArtifact extends UIElement {
       this.#kindEl.setAttribute('variant', TONE_TO_BADGE_VARIANT[this.tone] || 'default');
       this.#kindEl.hidden = !this.kind;
     }
-    if (this.#chevronEl) {
-      this.#chevronEl.setAttribute('name', this.collapsed ? 'caret-right' : 'caret-down');
+    if (this.#caretEl) {
+      this.#caretEl.setAttribute('name', this.collapsed ? 'caret-right' : 'caret-down');
     }
     if (this.#bodyEl) {
       this.#bodyEl.hidden = this.collapsed;
@@ -187,12 +187,12 @@ export class UIAgentArtifact extends UIElement {
     for (const btn of secondaryBtns) actions.appendChild(btn);
     for (const btn of primaryBtns) actions.appendChild(btn);
 
-    this.#chevronEl = document.createElement('icon-ui');
-    this.#chevronEl.setAttribute('color', 'muted');
-    this.#chevronEl.setAttribute('data-artifact-chevron', '');
-    this.#chevronEl.setAttribute('name', this.collapsed ? 'caret-right' : 'caret-down');
+    this.#caretEl = document.createElement('icon-ui');
+    this.#caretEl.setAttribute('color', 'muted');
+    this.#caretEl.setAttribute('data-artifact-caret', '');
+    this.#caretEl.setAttribute('name', this.collapsed ? 'caret-right' : 'caret-down');
 
-    this.#headerEl.append(this.#iconEl, this.#titleEl, this.#kindEl, actions, this.#chevronEl);
+    this.#headerEl.append(this.#iconEl, this.#titleEl, this.#kindEl, actions, this.#caretEl);
 
     // Body
     this.#bodyEl = document.createElement('div');

package/components/agent-artifact/agent-artifact.css

@@ -89,7 +89,7 @@
     flex-shrink: 0;
   }
 
-  [data-artifact-chevron] {
+  [data-artifact-caret] {
     flex-shrink: 0;
     transition: transform var(--agent-artifact-duration, var(--agent-artifact-duration-default));
   }

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

@@ -105,6 +105,8 @@ export class UIAgentReasoning extends UIElement {
   #summaryEl = null;
   #bodyEl = null;
   #bound = false;
+  #resizeObserver = null;
+  #spineRaf = 0;
 
   get entries() { return this.#entries; }
 
@@ -114,6 +116,19 @@ export class UIAgentReasoning extends UIElement {
     this.#startTime = Date.now();
     this.#timerInterval = setInterval(() => this.#tickTimers(), 1000);
     this.#buildShell();
+    // Re-measure the connector spine when row heights shift (text reflow on
+    // resize moves the dot Ys). The spine writes only absolutely-positioned
+    // ::before vars, so observing the host can't feed back into a resize loop.
+    if (typeof ResizeObserver !== 'undefined') {
+      this.#resizeObserver = new ResizeObserver(() => {
+        if (this.#spineRaf) return;
+        this.#spineRaf = requestAnimationFrame(() => {
+          this.#spineRaf = 0;
+          this.#layoutSpine();
+        });
+      });
+      this.#resizeObserver.observe(this);
+    }
   }
 
   // Single delegated handler for every nested timeline-item's toggle event.
@@ -136,6 +151,12 @@ export class UIAgentReasoning extends UIElement {
       clearTimeout(this.#finishTimer);
       this.#finishTimer = null;
     }
+    if (this.#spineRaf) {
+      cancelAnimationFrame(this.#spineRaf);
+      this.#spineRaf = 0;
+    }
+    this.#resizeObserver?.disconnect();
+    this.#resizeObserver = null;
     this.#summaryEl?.removeEventListener('click', this.#onSummaryClick);
     this.#summaryEl?.removeEventListener('keydown', this.#onSummaryKey);
     this.#bodyEl?.removeEventListener('timeline-toggle', this.#onStepToggle);
@@ -404,6 +425,36 @@ export class UIAgentReasoning extends UIElement {
         this.#bodyEl.appendChild(this.#renderNonStep(entry));
       }
     }
+
+    this.#layoutSpine();
+  }
+
+  // Draw one continuous connector line down the marker column from the first
+  // step dot to the last — bridging plan / thought / iteration interstitials
+  // that otherwise fragment the per-block timeline connectors into stubs. The
+  // endpoints are measured (not pure CSS) because interstitial row heights are
+  // dynamic; the per-item connectors are suppressed in CSS (the spine owns the
+  // line). No spine for 0–1 dots (nothing to connect → no trailing line).
+  #layoutSpine() {
+    const body = this.#bodyEl;
+    if (!body) return;
+    if (this.collapsed) { body.removeAttribute('data-spine'); return; }
+    const items = body.querySelectorAll('timeline-item-ui');
+    if (items.length < 2) { body.removeAttribute('data-spine'); return; }
+
+    const bodyTop = body.getBoundingClientRect().top;
+    // Dot center within an item = top:(1.4em − dot)/2 + 1px + dot/2 = 0.7em + 1px
+    // (the dot size cancels), where em is the item's computed font-size.
+    const dotY = (el) => {
+      const r = el.getBoundingClientRect();
+      const fs = parseFloat(getComputedStyle(el).fontSize) || 14;
+      return (r.top - bodyTop) + 0.7 * fs + 1;
+    };
+    const top = dotY(items[0]);
+    const height = Math.max(0, dotY(items[items.length - 1]) - top);
+    body.style.setProperty('--reasoning-spine-top', `${Math.round(top)}px`);
+    body.style.setProperty('--reasoning-spine-h', `${Math.round(height)}px`);
+    body.setAttribute('data-spine', '');
   }
 
   #makeTimeline() {

package/components/agent-reasoning/agent-reasoning.css

@@ -122,35 +122,56 @@
     grid-template-columns: subgrid;
     grid-column: 1 / -1;
     row-gap: var(--agent-reasoning-gap-row, var(--agent-reasoning-gap-row-default));
+    position: relative;
   }
 
   [data-reasoning-body][hidden] { display: none; }
 
+  /* ═══════ Connector spine ═══════
+     A single continuous line down the marker column from the first step dot to
+     the last, bridging plan / thought / iteration interstitials so the run
+     reads as one timeline rather than fragmented per-block stubs. Endpoints are
+     JS-measured into --reasoning-spine-top / -h (#layoutSpine) — interstitial
+     heights are dynamic, so pure CSS can't place them. The x matches the step
+     dot center (timeline-item uses var(--timeline-marker-w, 1.25rem) for its
+     dot math). Sits behind the dots (z-index 0 < the dots' z-index 1). The
+     per-item timeline connectors are suppressed below so they don't double-draw. */
+  [data-reasoning-body][data-spine]::before {
+    content: '';
+    position: absolute;
+    left: calc(var(--timeline-marker-w, 1.25rem) / 2 - var(--agent-reasoning-line-w, 1.5px) / 2);
+    top: var(--reasoning-spine-top, 0);
+    height: var(--reasoning-spine-h, 0);
+    width: var(--agent-reasoning-line-w, 1.5px);
+    background: var(--agent-reasoning-border, var(--agent-reasoning-border-default));
+    z-index: 0;
+  }
+
   /* All direct children of body span the grid */
   [data-reasoning-body] > * {
     grid-column: 1 / -1;
   }
 
+  /* Step rows + their readouts use the mono family — a technical step trace
+     (generate:/validate:/…) reads better fixed-width, matching the reference.
+     The iteration header ([data-reasoning-iter-n]) keeps the UI sans font. */
+  [data-reasoning-body] timeline-item-ui {
+    font-family: var(--a-font-family-code);
+  }
+
   /* ═══════ Thought — horizontal dash in marker column, text in content ═══════ */
 
+  /* Thoughts are free-form annotations beside the spine — text in the content
+     column, no marker dot/dash (the continuous spine passes behind them). */
   [data-reasoning-thought] {
     display: grid;
     grid-template-columns: subgrid;
     align-items: center;
     line-height: 1.5;
-    color: var(--agent-reasoning-fg, var(--agent-reasoning-fg-default));
+    color: var(--agent-reasoning-fg-muted, var(--agent-reasoning-fg-muted-default));
     animation: _ar-fade var(--agent-reasoning-duration, var(--agent-reasoning-duration-default)) var(--agent-reasoning-easing, var(--agent-reasoning-easing-default));
   }
 
-  [data-reasoning-thought]::before {
-    content: '';
-    grid-column: marker;
-    height: 1px;
-    background: var(--agent-reasoning-border, var(--agent-reasoning-border-default));
-    align-self: center;
-    width: 100%;
-  }
-
   [data-reasoning-thought] > [data-reasoning-thought-text] {
     grid-column: content / -1;
     min-width: 0;
@@ -159,15 +180,15 @@
 
   /* ═══════ Plan — card in content+aside, marker empty ═══════ */
 
+  /* Plan reads as a flat up-front checklist in the content column — no bordered
+     box (that competed with the now-flattened iteration sections, the original
+     bug-03 "inconsistent card hierarchy" complaint). The PLAN label + ordered
+     list carry the distinction; the spine passes down its left. */
   [data-reasoning-plan] {
     grid-column: content / -1;
     display: flex;
     flex-direction: column;
     gap: var(--a-space-1);
-    padding: var(--a-space-2) var(--a-space-3);
-    border: 1px solid var(--agent-reasoning-border, var(--agent-reasoning-border-default));
-    border-radius: var(--agent-reasoning-radius, var(--agent-reasoning-radius-default));
-    background: var(--agent-reasoning-iter-bg, var(--agent-reasoning-iter-bg-default));
   }
 
   [data-reasoning-plan-label] {
@@ -191,6 +212,10 @@
 
   /* ═══════ Iteration — card with its own grid ═══════ */
 
+  /* Iterations read as continuous timeline sections (a status-icon header row
+     + its nested steps tied by the timeline connector), NOT as bordered cards
+     that compete with the PLAN block. Flattened: no border / no fill / no box
+     padding — just the grid + row rhythm. (bug-03) */
   [data-reasoning-iteration] {
     display: grid;
     grid-template-columns:
@@ -199,14 +224,6 @@
       [aside] auto;
     column-gap: var(--agent-reasoning-gap-col, var(--agent-reasoning-gap-col-default));
     row-gap: var(--a-space-2);
-    padding: var(--agent-reasoning-iter-padding, var(--agent-reasoning-iter-padding-default));
-    border: 1px solid var(--agent-reasoning-iter-border, var(--agent-reasoning-iter-border-default));
-    border-radius: var(--agent-reasoning-radius, var(--agent-reasoning-radius-default));
-    background: var(--agent-reasoning-iter-bg, var(--agent-reasoning-iter-bg-default));
-  }
-
-  [data-reasoning-iteration][data-active] {
-    background: var(--agent-reasoning-iter-bg-active, var(--agent-reasoning-iter-bg-active-default));
   }
 
   [data-reasoning-iter-header] {
@@ -282,3 +299,13 @@
     [data-reasoning-spinner] { animation: none; }
   }
 }
+
+/* ═══════ Suppress timeline's own per-row connector inside agent-reasoning ═══════
+   The continuous body spine (see [data-reasoning-body][data-spine]::before)
+   owns the connector here; timeline-item's own ::after would double-draw and
+   fragment at every block boundary (each timeline-ui block stamps data-last on
+   its own last item, dropping that segment mid-run). This lives OUTSIDE @scope
+   and carries [data-step-id] (stamped on every step by #makeStepItem) to clear
+   timeline.css's :scope::after specificity ([0,1,1] → this is [0,1,3]). The
+   step dots (::before) are untouched. */
+agent-reasoning-ui timeline-item-ui[data-step-id]::after { display: none; }

package/components/alert/alert.class.js

@@ -331,7 +331,14 @@ export class UIAlert extends UIElement {
 
   #formatDueDate() {
     if (!this.dueAt) return '';
-    const d = new Date(this.dueAt);
+    // A date-only ISO string ("2026-05-20") parses as UTC midnight, which a
+    // behind-UTC locale then formats as the PREVIOUS calendar day. Consumers
+    // author these as plain calendar dates, so pin them to local midnight to
+    // preserve the authored day. Full timestamps (with time / offset) keep
+    // their exact instant.
+    const d = /^\d{4}-\d{2}-\d{2}$/.test(this.dueAt)
+      ? new Date(`${this.dueAt}T00:00:00`)
+      : new Date(this.dueAt);
     if (Number.isNaN(d.getTime())) return '';
     try {
       const lang = this.getAttribute('lang') || this.lang || undefined;

package/components/alert/alert.css

@@ -107,10 +107,18 @@
 
   /* Trailing action area — optional single button or small button group.
      flex-shrink:0 keeps it from collapsing; align-self:start anchors it
-     to the first text line under the `align-items:start` root. */
+     to the first text line under the `align-items:start` root.
+     `order: 1` sorts it AFTER the content slot regardless of DOM order:
+     alert.js appends the auto-stamped [slot="content"] / [slot="leading"]
+     *after* any author-provided [slot="action"], so without an explicit
+     order the action button renders wedged between the icon and the
+     message instead of trailing. content's `flex: 1` then pushes the
+     action (+ close) to the right edge. Mirrors the dunning path, which
+     already assigns explicit per-slot order integers. */
   :scope [slot="action"] {
     flex-shrink: 0;
     align-self: start;
+    order: 1;
   }
 
   /* Close button is a `<button-ui icon="x" variant="ghost" size="sm">`
@@ -123,6 +131,10 @@
      rather than disconnected grey. */
   :scope [slot="close"] {
     flex-shrink: 0;
+    /* Sort last (after content order:0 and action order:1) so the dismiss
+       button is the right-most affordance. content's flex:1 pushes both
+       action + close to the trailing edge. */
+    order: 2;
     min-height: calc(var(--alert-font, var(--alert-font-default)) * var(--alert-line-height, var(--alert-line-height-default)));
     --button-fg-ghost: var(--alert-fg, var(--alert-fg-default));
     --button-fg-ghost-hover: var(--alert-icon-fg, var(--alert-icon-fg-default));

package/components/avatar/avatar.a2ui.json

@@ -21,14 +21,6 @@
       "type": "string",
       "default": ""
     },
-    "name": {
-      "description": "Deprecated alias for `text` (logs a one-shot console warning; will be removed in a future release). New code should use `text=` instead.",
-      "type": "string",
-      "default": "",
-      "deprecated": true,
-      "deprecated_reason": "Use `text` instead. Will be removed in v0.6.0.",
-      "deprecated_since": "0.4.x"
-    },
     "shape": {
       "description": "Avatar shape",
       "type": "string",
@@ -39,18 +31,14 @@
       "default": "circle"
     },
     "size": {
-      "description": "Avatar size. Canonical scale (xs/sm/md/lg/xl); long-form aliases (small/medium/large/xlarge) accepted for back-compat.",
+      "description": "Avatar size — canonical scale.",
       "type": "string",
       "enum": [
         "xs",
         "sm",
         "md",
         "lg",
-        "xl",
-        "small",
-        "medium",
-        "large",
-        "xlarge"
+        "xl"
       ],
       "default": "md"
     },

package/components/avatar/avatar.class.js

@@ -16,7 +16,6 @@
  *
  * Fallback chain: image → initials → empty.
  * If src fails to load, falls back to initials derived from text.
- * `name` is a deprecated alias for `text` (warns on use).
  *
  * <avatar-group-ui max="4" size="md">
  *   <avatar-ui text="Alice"></avatar-ui>
@@ -35,33 +34,22 @@ export class UIAvatar extends UIElement {
   static properties = {
     src:   { type: String,  default: '', reflect: true },
     text:  { type: String,  default: '', reflect: true },
-    name:  { type: String,  default: '', reflect: true }, // backcompat alias for text
     icon:  { type: String,  default: '', reflect: true },
     size:  { type: String,  default: 'md', reflect: true },
     shape: { type: String,  default: 'circle', reflect: true },
   };
 
-  /** Display string — `text` takes priority, `name` is backcompat alias */
-  get displayName() { return this.text || this.name; }
+  /** Display string (full name or initials derived from it). */
+  get displayName() { return this.text; }
 
   static template = () => null;
 
-  static #nameWarned = false;
-
   #imgEl = null;
   #initialsEl = null;
   #iconEl = null;
 
   connected() {
     this.setAttribute('role', 'img');
-    if (this.name && !this.text && !UIAvatar.#nameWarned) {
-      UIAvatar.#nameWarned = true;
-      // eslint-disable-next-line no-console
-      console.warn(
-        `[AdiaUI] <avatar-ui name="…"> is deprecated — use text="…" instead. ` +
-        `Docs: https://ui-kit.exe.xyz/site/components/avatar`
-      );
-    }
   }
 
   render() {
@@ -78,7 +66,7 @@ export class UIAvatar extends UIElement {
         };
       }
       this.#imgEl.src = this.src;
-      this.#imgEl.alt = this.name || '';
+      this.#imgEl.alt = this.displayName || '';
       if (!this.#imgEl.parentElement) this.appendChild(this.#imgEl);
 
       // Remove initials when image is showing

package/components/avatar/avatar.d.ts

@@ -21,12 +21,10 @@ import { UIElement } from '../../core/element.js';
 export class UIAvatar extends UIElement {
   /** Phosphor icon name shown instead of initials when `src`/`text` are empty. */
   icon: string;
-  /** Deprecated alias for `text` (logs a one-shot console warning; will be removed in a future release). New code should use `text=` instead. */
-  name: string;
   /** Avatar shape */
   shape: 'circle' | 'square';
-  /** Avatar size. Canonical scale (xs/sm/md/lg/xl); long-form aliases (small/medium/large/xlarge) accepted for back-compat. */
-  size: 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'small' | 'medium' | 'large' | 'xlarge';
+  /** Avatar size — canonical scale. */
+  size: 'xs' | 'sm' | 'md' | 'lg' | 'xl';
   /** Image source URL. Falls back to initials on error. */
   src: string;
   /** Display string (full name or initials). Initials derive from spaces — first letter of each word, max 2. */

package/components/avatar/avatar.yaml

@@ -23,17 +23,6 @@ props:
     description: Display string (full name or initials). Initials derive from spaces — first letter of each word, max 2.
     type: string
     default: ""
-  name:
-    description: "Deprecated alias for `text` (logs a one-shot console warning; will be removed in a future release). New code should use `text=` instead."
-    type: string
-    # §179 (v0.5.5): principled deprecation metadata. The build pipeline
-    # propagates this into the sidecar + catalog; the LLM prompt builder
-    # surfaces "(deprecated, do not use)" based on this field rather than
-    # substring-matching the description.
-    deprecated: true
-    deprecated_since: "0.4.x"
-    deprecated_reason: "Use `text` instead. Will be removed in v0.6.0."
-    default: ""
   icon:
     description: Phosphor icon name shown instead of initials when `src`/`text` are empty.
     type: string
@@ -46,9 +35,7 @@ props:
       - circle
       - square
   size:
-    description: >-
-      Avatar size. Canonical scale (xs/sm/md/lg/xl); long-form aliases
-      (small/medium/large/xlarge) accepted for back-compat.
+    description: Avatar size — canonical scale.
     type: string
     default: md
     enum:
@@ -57,10 +44,6 @@ props:
       - md
       - lg
       - xl
-      - small
-      - medium
-      - large
-      - xlarge
   src:
     description: Image source URL. Falls back to initials on error.
     type: string