# Component behavior index One `##` section per `component.md`-eligible component (screenReader + behavioral both authored, same eligibility test `component.md` itself uses). **Grep this file by tag, never load it whole** (`grep -A 20 '^## ``' component-behavior-index.md`); at ~130 sections this file is a reading aid, not a document meant to be read end to end (LLD-0022 §C1). ## `` **Composes:** _(none)_ **Allowed children (a2ui):** _(unconstrained)_ **Fulfills:** _None._ **Disambiguation:** _None._ ### Screen-reader spec The runtime owns the rendered children. The host does not add a live region or announce unresolved component types; it dispatches `a2ui-error` as a JavaScript event. Consumers that need an accessible error announcement must present it through their own UI. Focus and keyboard behavior belong to the rendered components. ### Behavioral spec Callers using `process(message)` or `processAll(messages)` own the document boundary. Before starting a new document through either method, call `reset()`. Reset clears the rendered surfaces and the set of already-reported unresolved component types; it is a document reset, not just an error-counter reset. Within that boundary, each unresolved component type emits `a2ui-error` once, with an Error in `detail.error` naming the type. Rendering continues for types that resolve. Neither `process()` nor `processAll()` starts a new deduplication window. Without `reset()`, encountering the same unresolved type in a later document suppresses its error event even though it belongs to a new document. A new stream connection or `replaceDoc()` call starts a fresh unresolved-type reporting window automatically. Setting `doc` delegates to `replaceDoc()`. ## `` **Composes:** `` **Allowed children (a2ui):** `` **Fulfills:** _None._ **Disambiguation:** | Neighbor | Cue | |---|---| | `tree-ui` | For arbitrary nesting depth, tree-ui is the right fit, since accordion's zero-or-multi-open model only handles one flat level of sections. | | `tabs-ui` | For a view switcher where exactly one panel is always visible, tabs-ui is the right fit; accordion supports zero-open and multi-open, tabs never does. | ### Screen-reader spec Each auto-stamped `[slot="header"]` gets `role="button"`, `tabindex="0"`, and an `aria-expanded` attribute kept in sync on every render() pass as [open] toggles, so a screen reader announces the current disclosure state after every interaction, not just on first paint. Headers sit in normal Tab order, one stop per item, in DOM order; Enter and Space both route through the same `header.click()` path a pointer click uses, so keyboard and pointer users trigger identical behavior. A consumer-authored `[slot="header"]` is left entirely alone: no `role`/`tabindex`/`aria-expanded` is stamped onto it (only the caret is restored, FN-1), so its accessibility contract is the consumer's own from that point forward. There is no `aria-controls` linking a header to its `[slot="body"]` panel and no `role="region"` on the body: the header/panel relationship is DOM adjacency only, with no explicit ARIA cross-reference. ### Behavioral spec Single-open is the default: opening one item force-closes every other currently-open item in the same accordion-ui host (`#onItemToggle` walks all `accordion-item-ui` children and closes any other than the one that just opened). This coordination only fires when [multiple] is unset: with [multiple] set, items toggle fully independently and the host never intervenes. A click landing inside a `[slot="action"]`/`[slot="actions"]` region, or on an element carrying `data-no-toggle`, is explicitly exempt from the toggle handler, so a consumer can place action buttons inside a custom header without triggering expand/collapse. There is no loading, error, or empty state: content is always synchronously present in the light DOM, and an item with no children simply renders an empty body when opened. [variant="contained"] is a pure CSS re-point (surface, border, radius, an open-state divider) with no JS-level state behind it: an individual item can opt back to `variant="flat"` even when its host accordion is contained. ## `` **Composes:** `` **Allowed children (a2ui):** `` **Fulfills:** _None._ **Disambiguation:** | Neighbor | Cue | |---|---| | `menu-ui` | Use menu-ui instead when the actions should be hidden behind a trigger and rendered in a popover; action-list-ui is always visible inline. | | `list-ui` | Use list-ui instead when the items are passive display data with no click/keyboard activation semantics at all. | ### Screen-reader spec The host stamps `role="list"` and each `action-item-ui` stamps `role="listitem"` when the consumer hasn't already set an explicit role (adopt-or-stamp, gh#753): this is a passive list role, not `listbox`/`menu`, even though items are click- and keyboard-activatable; a screen reader announces item count/position via the list semantics, not a selection or menu model. Every enabled item carries `tabindex="0"` individually (not a roving-tabindex single stop): Tab moves through every item in DOM order, one stop each, while ArrowUp/ArrowDown/Home/End move focus WITHOUT changing tab order, wrapping at both ends (`(idx + length) % length`). A [disabled] item gets `aria-disabled="true"` and `tabindex="-1"`, removing it from both Tab order and arrow-key cycling (`#items()` filters `:not([disabled])` before computing navigation targets). Enter and Space on a focused item click() it, routing through the same `action` event path a pointer click uses. ### Behavioral spec There is no selection state: action-list-ui is a fire-and-forget command list, not a single/multi-select control; clicking or keyboard-activating an item dispatches one `action` CustomEvent ({ value, text, item }) and the list itself retains no memory of which item was last triggered. [icon]/[text]/[description] each stamp their own light-DOM child (`icon-ui`/`span[slot=text]`/`span[slot=subtitle]`) only when the consumer hasn't already authored that slot: every stamp is dataset-marked (`data-action-item-stamped`) so render() only ever updates or removes elements the component itself created, never a consumer-authored slot child. Setting [description] to empty after it was non-empty removes the stamped subtitle element entirely rather than leaving an empty node. There is no loading, error, or empty state of its own: items are always synchronously present in the light DOM, and an action-list-ui with zero action-item-ui children simply renders an empty list with no items to navigate. ## `` **Composes:** _(none)_ **Allowed children (a2ui):** _(unconstrained)_ **Fulfills:** _None._ **Disambiguation:** | Neighbor | Cue | |---|---| | `icon-ui` | adia-mark-ui is not a generic icon, it has no [name] prop, always renders the same five-path wordmark SVG, and is never themeable to another color (see anti_patterns). | ### Screen-reader spec `connected()` stamps `role="img"` and, unless the consumer already set an explicit `aria-label`, `aria-label="Adia"`, so the mark always announces as a single named image, never as its five constituent SVG paths. The SVG root itself carries `aria-hidden="true"`, keeping the raw path geometry out of the accessibility tree entirely; the host-element role/label pair is the sole accessible surface. ### Behavioral spec Fully static: `static template` returns identical markup on every render regardless of [size] or [inline], since neither prop is interpolated into the template (both are surfaced purely via CSS through the reflected attribute). There is no press/focus/keyboard handling, no loading/error/empty state, and no async lifecycle: `stamp()`'s first-mount `replaceChildren` only ever regenerates the same template-owned SVG content, which is SSR-safe by construction (gh#284's "template content never depends on light-DOM children" shape, same as check-ui/switch-ui but with zero interpolated values). Background and wordmark fills are always the inverse-surface/ inverse-foreground token pair: there is no variant/tone/color prop to diverge from that pairing. ## `` **Composes:** _(none)_ **Allowed children (a2ui):** _(unconstrained)_ **Fulfills:** _None._ **Disambiguation:** | Neighbor | Cue | |---|---| | `adia-mark-ui` | Use adia-mark-ui instead for the square icon/tile use (app-switcher slot, favicon-style avatar) with the fixed inverse-on-inverse background pairing; the two are not interchangeable, wordmark has no background of its own. | ### Screen-reader spec `connected()` stamps `role="img"` and, unless the consumer already set an explicit `aria-label`, `aria-label="Adia"`: identical contract to `adia-mark-ui`. The SVG root carries `aria-hidden="true"`, so the five logotype paths never enter the accessibility tree; the host role/label pair is the sole accessible surface, and it announces the same name regardless of [size]/[inline]. ### Behavioral spec Fully static: `static template` returns identical markup on every render; neither [size] nor [inline] is interpolated into the SVG markup, both surface purely via CSS through the reflected attribute. No press/focus/keyboard handling, no loading/error/empty state, no async lifecycle: `stamp()`'s first-mount `replaceChildren` only ever regenerates the same template-owned content (gh#284's SSR-safe "template content never depends on light-DOM children" shape). Unlike `adia-mark-ui`'s fixed inverse-on-inverse pairing, the wordmark fill defaults to the current scheme's on-surface foreground token (`--a-fg-strong`, gh#390): it tracks scheme changes but has no variant/tone prop to diverge from that single foreground token. ## `` **Composes:** ``, `` **Allowed children (a2ui):** _(unconstrained)_ **Fulfills:** _None._ **Disambiguation:** | Neighbor | Cue | |---|---| | `code-ui` | Skip agent-artifact-ui's header chrome for a bare code block that needs no title, kind badge, or collapse affordance; the header is pure overhead there. | | `alert-ui` | [tone] only recolors the container border and the kind badge; it is not alert-ui's severity+role pairing and should not stand in for a real alert when content needs to interrupt a screen reader. | | `card-ui` | card-ui is the generic container with no header/collapse contract at all; reach for it instead when there's no title, kind, or action row to show. | ### Screen-reader spec The header built in `#build()` is `role="button"` `tabindex="0"` with `aria-expanded` set to the inverse of [collapsed], kept in sync on every render (`render()` re-sets `aria-expanded` from the live `collapsed` value). The header carries no explicit `aria-label`: its accessible name is whatever a screen reader composes from its content: the [title] text span (hidden via the DOM `hidden` property when title is empty) and the kind badge-ui, which self-labels via its own `aria-label` mirrored from its `text` attribute (the uppercased [kind] value): while the leading icon and the caret icon are both `aria-hidden="true"` (icon-ui's own default when no `label` attribute is set, and neither `#iconEl` nor `#caretEl` ever receives one here). Toggling relies entirely on that native `aria-expanded` state change on a `role="button"` element: there is no separate live region announcing expand/collapse. Slotted action buttons living in the header's actions cluster keep their own independent accessible names; `#onHeaderClick`/`#onHeaderKey` explicitly skip toggling when the event target is inside `[slot="primary"], [slot="secondary"]`, so they don't inherit the header's button semantics. The body is a plain unlabeled `
`; setting it `hidden` when [collapsed] removes it from the accessibility tree entirely, not just visually. ### Behavioral spec `#build()` runs once from `connected()` and partitions the light-DOM children by logical slot (primary, secondary, or body), walking recursively into any child whose `role="presentation"` or `style.display === "contents"` (the template engine's transparent wrapper span around interpolated children) so wrapped action buttons still reach the header instead of being stranded in the body (the wrapper-trap class, FB-92/96/98). Captured secondary buttons are appended to the actions cluster BEFORE primary buttons, so visual/DOM order is secondary-then-primary regardless of authoring order. Clicking the header (outside `[slot="primary"], [slot="secondary"]`) flips [collapsed], dispatches a bubbling `artifact-toggle` event with `{ collapsed }` reflecting the NEW state, then calls `render()` directly in addition to the framework's own property-driven re-render. Space/Enter on the header (`#onHeaderKey`, same target exclusion) calls `preventDefault()` and re-enters the same click handler: no separate keyboard code path. [tone] drives two independent mechanisms off the same attribute: JS maps it through `TONE_TO_BADGE_VARIANT` (neutral→default, accent→accent, warning→warning, danger→danger) onto the kind badge's `variant`, while CSS `:scope[tone="…"]` selectors separately override `--agent-artifact-border` for accent/warning/danger (neutral has no override and falls back to `--a-border-subtle`). [icon], [title], and [kind] each independently hide their own header cell when unset: there's no combined empty-header collapse. `disconnected()` removes both header listeners and nulls all six cached element references (`#headerEl`/`#iconEl`/`#titleEl`/`#kindEl`/`#caretEl`/`#bodyEl`): symmetric cleanup on every disconnect. Composing icon-ui and badge-ui (`composes:`, ADR-0027, the consumer imports them explicitly) covers the header chrome only; the default slot is never dictated, so code-ui, canvas-ui, a plain `
`, anything renders there. ## `` **Composes:** `` **Allowed children (a2ui):** _(unconstrained)_ **Fulfills:** _None._ **Disambiguation:** | Neighbor | Cue | |---|---| | `rating-ui` | rating-ui is a star-based ordinal scale; use that for a 1-5 quality rating, not binary agent feedback. | ### Screen-reader spec `#build()` creates all three buttons via the shared `makeButton()` helper as ``; the thumbs-up/ thumbs-down buttons are icon-only with no `text`, so `makeButton()` sets a `title` ("Rate this response positively" / "Rate this response negatively"), which button-ui's own accessibility fallback mirrors into `aria-label` automatically (icon-only buttons with no explicit `aria-label`/`aria-labelledby`, per its §184/FEEDBACK-08 §8 safety net): agent-feedback-bar-ui never sets `aria-*` attributes directly, it relies entirely on that button-ui contract. The save button gets a real visible `text` from [saveLabel] whenever it's shown, so it needs no title/aria-label fallback. [disabled] sets no `aria-disabled`/ `disabled` attribute on the row or its buttons: it's a CSS-only `pointer-events: none` + dimmed-opacity treatment (`:scope[disabled]` in the stylesheet) layered on top of the JS-side guards in `#onUp`/ `#onDown`/`#onSave`, which independently no-op while `this.disabled` is true. The status span (`[data-feedback-status]`) is a plain unlabeled `` with no `aria-live` region: text written via `setStatus()` is not automatically announced to a screen reader unless the host wires its own live region around this component. ### Behavioral spec Thumbs-up (`#onUp`) and thumbs-down (`#onDown`) share a single `#rated` flag: once either fires and sets it, both are gated off by `!this.#rated`. `#emitRate(rating)` dispatches the bubbling `feedback-rate` event with `detail: { rating }` FIRST (rating is always the hardcoded `5` for thumbs-up or `2` for thumbs-down, never derived from anything else): any host listener that calls `.setStatus()` synchronously during that dispatch runs before the component's own courtesy default is evaluated. Only if `#statusEl.textContent` is still empty afterward does the component supply its own ack via `setStatus(text, { lock: 'rate' })` ("Thanks!" when `rating >= 4`, i.e. the thumbs-up path; "Noted" otherwise, i.e. thumbs-down): that default call is what sets `#rated` and disables both buttons in the common case where the host doesn't lock rating itself. Save has no equivalent self-locking default: `#emitSave()` dispatches `feedback-save` with an empty `detail: {}` and does nothing else: `#saved` only flips (disabling the save button) when the host explicitly calls `setStatus(text, { lock: 'save' | 'all' })`; left uncalled, Save stays repeatable indefinitely. `render()`: the framework's reactive re-render, distinct from the one-time `#build()`: re-syncs [saveLabel]/[saveIcon] onto the live save button's `text`/`icon`/ `hidden` attributes on every property change, so toggling [saveLabel] empty↔non-empty after connect shows/hides the save button reactively, not just at initial mount. `reset()` clears both `#rated`/`#saved` flags, blanks the status text, and re-enables all three buttons: it dispatches no event of its own. `disconnected()` removes the three `press` listeners (button-ui's own bubbling activation event, not `click`) and nulls all four cached refs. ## `` **Composes:** ``, `` **Allowed children (a2ui):** _(unconstrained)_ **Fulfills:** _None._ **Disambiguation:** | Neighbor | Cue | |---|---| | `agent-suggestions-ui` | Use agent-suggestions-ui instead for optional follow-ups the user can ignore; agent-questions always gates the turn on an answer. | ### Screen-reader spec agent-questions-ui itself sets no ARIA directly; it composes `` per option and relies entirely on that primitive's own accessibility machinery. Each card gets `role="radio"`, `tabindex="0"`, and `aria-checked` mirroring `.checked` on every render (option-card's `render()`). In [multi] mode, `#render()` overrides the connect-time role to `role="checkbox"` on every card right after stamping it: `aria-checked` still tracks `.checked` regardless of role, so a checkbox group announces checked/unchecked correctly even though option-card's own internals were built radio-first. Disabled cards (post-answer, in both modes) get `aria-disabled="true"` from option-card-ui's own render. The submit button is a real `` (hidden entirely in single-select via `this.#submitEl.hidden = !this.multi`), so it only enters the accessibility tree at all in multi mode, and stays `disabled` (native semantics) until at least one option is selected, and again once answered (`this.#submitEl.disabled = this.#answered || this.#selected.size === 0` in `#render()`). ### Behavioral spec Two independent selection paths depending on [multi], not a shared toggle method. Single-select: `#onCardChange` listens for option-card-ui's own `change` event (which only ever fires on becoming selected, never on deselect), clears `#selected`, sets `#answered = true`, and immediately dispatches `questions-answer` with `detail: { selected: [id], option }`: there is no separate submit step and no way to change the pick afterward (all cards become `disabled` once answered). Multi-select: the container intercepts `click` and `keydown` at the CAPTURE phase (`#onOptionsClickCapture` / `#onOptionsKeydownCapture`, both installed with `useCapture: true`) to stop option-card-ui's bubble-phase click handler before it runs: necessary because option-card-ui's `#select()` can only select, never toggle off, so multi mode needs its own toggle logic (`#toggleMulti`) driving `#selected` as a Set. Arrow keys are swallowed in multi mode (`e.stopPropagation()`) rather than forwarded to option-card-ui's forced-select arrow navigation, since a checkbox group has no "arrow moves the pick" semantics. Multi answers only fire on explicit submit-button press (`#onSubmit`), with `detail.selected` as the full array of picked ids in Set-iteration order and `detail.option` as the first picked option object. Setting `.options` (the JS setter, not an attribute) clears `#selected` and resets `#answered = false` unconditionally: replacing options always resets the answered state, even mid-answer. `disconnected()` removes all three internal listeners and nulls the element refs symmetrically with what `connected()`/`#build()` wires up. Options are passed via the JS `options` setter (an array of `{ id, label, description, icon }`), not as light-DOM children or slotted markup: there is no declarative-children path. ## `` **Composes:** ``, `` **Allowed children (a2ui):** _(unconstrained)_ **Fulfills:** _None._ **Disambiguation:** | Neighbor | Cue | |---|---| | `agent-trace-ui` | agent-trace-ui is structured tool-call/metrics data, not narrative prose; reach for it instead of agent-reasoning when the surface is quantitative diagnostics rather than a progress narrative. | | `agent-questions-ui` | agent-questions-ui is a gating disambiguation prompt the turn waits on, not a progress narrative; reach for it instead when the agent needs an answer before continuing. | ### Screen-reader spec The summary row (`#summaryEl`, built once in `#buildShell()`) gets `role="button"`, `tabindex="0"`, and `aria-expanded` mirroring `!this.collapsed`, refreshed on every `#render()` call: clicking it or pressing Space/Enter (`#onSummaryKey`) toggles `[collapsed]` and dispatches `reasoning-toggle`. The status icon (`#renderStatusIcon()`: spinner/check-circle/warning-circle/circle) is stamped as a bare `` with no `label` attribute, so icon-ui's own connect-time default (`role="presentation"`, `aria-hidden="true"` when `this.label` is falsy) makes it fully decorative: the announced state comes from the adjacent `` text and `` (`done/total`), not the glyph. Individual step rows are `` instances this component composes but doesn't itself add ARIA to; their accessibility is that primitive's own contract. `reasoning-step-toggle` is a delegated listener on `#bodyEl` for the bubbling `timeline-toggle` event: it sets no ARIA itself, only re-dispatches with `{ stepId }` resolved from `dataset.stepId`. ### Behavioral spec Two parallel input paths, not modes on a single prop: the imperative pipeline (`addStep`/`updateStep`/`completeStep`/`failStep`/`addThought`/ `setPlan`/`startIteration`/`endIteration`) mutates the internal `#entries` array incrementally and re-renders after each call, while the `entries` setter is a full declarative replace that also resets `#iterationStack = []`: any imperative iteration in progress is discarded the moment `entries` is assigned. `#appendToCurrentScope()` nests a new entry inside the innermost open iteration's own `steps` array ONLY when `entry.kind === 'step'`; a `thought` or `plan` entry added while an iteration is open still lands in the top-level `#entries` list as a sibling, not nested inside the iteration block. `finish(summaryLabel, { status })` walks every still-`active` step/iteration and force-resolves it to `completed` or `error` (matching the finish status) before firing `reasoning-finish` with `detail: { summary, status }`; `fail(text)` is sugar for `finish(text, { status: 'error' })`. Auto-collapse only fires when `!noAutocollapse && !isError`: a 1200ms `setTimeout` sets `[collapsed] = true` and re-renders; an error-status finish never auto-collapses regardless of `[noAutocollapse]`. The live elapsed-time ticker (`#timerInterval`, 1s cadence) updates the summary's `data-reasoning-time` text and mirrors elapsed seconds into any `active`-and-not-`completed` ``'s `duration` attribute, unless that item carries `dataset._frozenDuration`, and stops permanently the moment `finish()` runs (`clearInterval` inside `finish()`, not `disconnected()`). Lifecycle is symmetric and idempotent: `connected()` guards re-entry with a `#bound` flag and wires the interval, the shell, and a `ResizeObserver` (for spine relayout on row-height reflow); `disconnected()` tears down the interval, `#finishTimer`, the queued `requestAnimationFrame` spine layout, the `ResizeObserver`, and both summary/body listeners, then resets `#bound = false` so a later reconnect rebinds cleanly. An unrecognized `[status]` value falls back silently to `'active'` in `#render()`; an unrecognized `finish()` status falls back to `'completed'` the same way (both via `REASONING_STATUSES.has()`). ## `` **Composes:** `` **Allowed children (a2ui):** _(unconstrained)_ **Fulfills:** _None._ **Disambiguation:** | Neighbor | Cue | |---|---| | `agent-questions-ui` | Use agent-questions-ui instead for a disambiguating question the agent must gate the conversation on: it always renders a submit affordance and blocks progress until answered; agent-suggestions never does. | ### Screen-reader spec agent-suggestions-ui sets no ARIA of its own; every chip is a real `` element, so accessibility comes entirely from button-ui's own connect-time logic. Each chip gets button-ui's default `role="button"` and `tabindex="0"` (button-ui only defaults these when the author hasn't already set a role/tabindex, and agent-suggestions never does). The chip's accessible name is the truncated label: `#render()` sets `text=` on the chip to `truncate(label, 42)`, and button-ui mirrors a non-empty `[text]` into `aria-label` on every render, so a screen reader announces the (possibly ellipsis-truncated) label, never the full untruncated prompt. `[disabled]` on the host is forwarded to every chip's own `disabled` attribute (native semantics); the host itself only gets `opacity: 0.6; pointer-events: none` via CSS, no `aria-disabled`. ### Behavioral spec `suggestions` is a JS-only setter (`el.suggestions = [...]`): no attribute equivalent, no slotted-children path, and setting it clears and fully rebuilds the chip row via `#render()`. Each entry may be a bare string (used as both label and prompt) or an object `{ label, prompt, icon }`; label/prompt resolution falls back in both directions: `label = s.label || s.prompt`, `prompt = s.prompt || s.label`, so an entry with only one of the two still produces a usable chip. `[variant]` (`outline` default, `ghost`) and `[size]` (`sm` default, `md`) are read fresh on every `#render()` and applied uniformly to all chips; there's no per-suggestion override. Each chip listens for button-ui's `press` event (not `click`) and, when the host isn't `[disabled]`, dispatches a bubbling `suggestion-select` with `detail: { label, prompt, index }`: `index` is the array position at render time, not a stable id. When `[disabled]` is set, the press handler still runs but its own early return (`if (this.disabled) return`) suppresses the event, so pressing a disabled chip is a no-op at the JS layer too, not merely blocked by the CSS `pointer-events: none`. `disconnected()` clears the host with `this.innerHTML = ''`, dropping all chip children and their listeners: there is no separate per-chip listener teardown, since DOM removal is what releases them. ## `` **Composes:** _(none)_ **Allowed children (a2ui):** _(unconstrained)_ **Fulfills:** _None._ **Disambiguation:** | Neighbor | Cue | |---|---| | `agent-reasoning-ui` | agent-reasoning-ui is the agent's narrative inner monologue: step-by-step thoughts/plans/iterations; agent-trace is metrics, not prose. | ### Screen-reader spec agent-trace-ui sets no ARIA of its own on the disclosure structure: the summary/body is built from native `
`/`` elements (`#buildShell()`), which carry implicit disclosure semantics in the accessibility tree (expanded/collapsed state exposed automatically from the native `open` attribute; no `aria-expanded` is authored). Purely decorative alignment placeholders get explicit `aria-hidden="true"`: `data-trace-header-spacer` (the empty Detail-column header when no metric has an `aux`) and `data-trace-row-caret-spacer` (per-row filler when that row has no `details` but sibling rows do, keeping grid columns aligned). Every `` the component stamps: the summary caret, each row's caret, the pill dot, and each feedback line's icon: omits icon-ui's `label` attribute, so icon-ui's own connect-time logic (`if (!this.label) this.setAttribute('aria-hidden', 'true')`) makes all of them decorative; the announced content is always the adjacent text (pill label/value, row label/value/aux, feedback text), never the icon glyphs. ### Behavioral spec `pills`, `metrics`, and `feedback` are independent JS-only setters (no attribute equivalent, no slotted-children path); each clones its input array (`Array.isArray(v) ? v.slice() : []`) and calls `#render()`, but `#render()` is a guarded no-op until `#rootEl` exists (`if (!this.#rootEl) return;`): setting any of the three before the element connects has no visible effect until `connected()` runs `#buildShell()`, which rebuilds the shell and calls `#render()` again, picking up whatever was set pre-connect. The summary header uses whichever of `pills` or [label] is truthy: non-empty pills win outright (joined with a literal `·` separator span), and [label] (default `'Trace'`) only ever appears when `pills` is empty. The "Detail" header word and the row-caret column are two independent, data-driven decisions: `hasAux` (any metric with a non-empty `aux`) controls whether the header word renders at all, while `hasAnyDetails` (any metric with a non-empty `details`) controls whether an extra caret column exists across every row: a metric with `details` but no `aux` still gets a populated caret column even though its own Detail cell is blank. A metric row becomes its own native `
`/`` (independently expandable) only when that row's own `details` is non-empty; other rows render as a plain `
`. `details` itself branches on type: an array renders as escaped `
`/`
` pairs via `#renderDetails()`; a string is trusted raw HTML and rendered unescaped: the only unescaped-injection path in the component (every other label/value/aux/text goes through `escapeText`/`escapeAttr`). Expanding/collapsing the root `
` is native browser behavior: the component only listens for the resulting `toggle` event (`#onToggle`) to sync `this.collapsed` (reflecting the `collapsed` attribute on the host, but not re-triggering `#buildShell()`/`#render()` since `static template = () => null` makes the property system's own render pathway a no-op) and dispatch `trace-toggle` with `detail: { collapsed }`. `connected()` unconditionally wipes and rebuilds the host (`this.innerHTML = ''`) before attaching the `toggle` listener; `disconnected()` removes that listener and nulls `#rootEl`, but, unlike ``, does not itself clear `this.innerHTML`. ## `` **Composes:** _(none)_ **Allowed children (a2ui):** _(unconstrained)_ **Fulfills:** _None._ **Disambiguation:** | Neighbor | Cue | |---|---| | `toast-ui` | alert-ui is not for a transient, self-dismissing notification, use toast-ui for that. | | `empty-state-ui` | alert-ui is not for a zero-data placeholder, use empty-state-ui for that. | ### Screen-reader spec `#updateRole()` sets `role="alert"` for [variant="danger"] or [variant="warning"] (interrupts a screen reader immediately, matching their higher severity) and `role="status"` for every other variant (announced without interrupting). The accessible name is composed and mirrored into `aria-label` on every render: title+description mode joins `[title]. [description]`, dunning mode joins `title. amount. meta` (all three deviant of Intl-formatted), and plain [text] mode has no separate aria-label: the content slot's own text is what's announced. Author-provided rich content (a slotted `` with real children already inside, detected by the ABSENCE of `data-alert-auto`) is left alone except for still mirroring [title]/[description] to aria-label if set: the author owns the accessible name in that mode. The close button is a real ``, so it announces "Close, button" regardless of the alert's own variant/role. ### Behavioral spec [pattern="dunning"] branches into a completely separate render path (`#renderDunning()`) that skips the standard title/description/text precedence chain: while dunning is set, [title]/[text]/rich-content modes below don't apply, only the reason-keyed default title, Intl-formatted [amount]/[currency], [dueAt], [cardLast4], and [reason] feed the stamped content. Standard (non-dunning) content resolution is three-mode precedence, checked in order: (1) author-provided rich content already inside the content slot (no `data-alert-auto` flag) is left untouched; (2) [title] and/or [description] set → bolded headline + body paragraph, `data-alert-auto="title-desc"`; (3) [text] alone → single-line message, `data-alert-auto="text"`. There is no loading state: alert-ui renders synchronously. [closable] stamps a close button that removes the element from the DOM entirely on press/click (`#close()` fires a `close` event then calls `this.remove()`): there is no "hidden but still present" dismissed state to restore from. `#normalizeAliases()` silently remaps two hallucination-class inputs once per session (warn-once): `variant="error"` → `variant="danger"`, and `[closeable]` → `[closable]`. ## `` **Composes:** _(none)_ **Allowed children (a2ui):** _(unconstrained)_ **Fulfills:** _None._ **Disambiguation:** | Neighbor | Cue | |---|---| | `modal-ui` | Use modal-ui instead for a surface that must trap focus or block the rest of the page; anchor-bar-ui coexists with page interaction and never joins modal-ui's mutual-exclusion convention. | | `drawer-ui` | Use drawer-ui instead for a surface that must trap focus or block the rest of the page; anchor-bar-ui coexists with page interaction and never joins drawer-ui's mutual-exclusion convention. | ### Screen-reader spec anchor-bar-ui sets no ARIA role or label of its own: `class.js` contains no `role=`/`aria-*` assignment on the host at all; the element relies entirely on slotted content (typically a `` or a `` count) to carry its own accessible semantics, per the examples' own convention of adding `aria-live="polite"` to a running selection count. The only attribute the component ever sets on itself is `popover="manual"`, applied once when [viewport] is bound (`#bindPopover()`) and removed on unbind: this is a Popover API state marker, not an ARIA construct, and manual popovers never light-dismiss or close on Escape (visibility is entirely [open]-driven). Closed state is signaled to assistive tech via CSS `visibility: hidden` (not `display`/`[hidden]`), which pulls the bar out of the accessibility tree and tab order while closed without triggering a `display:none` reset of slotted ResizeObserver-driven children. The component never calls `.focus()` on itself or any descendant at any lifecycle point: no focus is stolen on open; slotted interactive content keeps its normal tab order. ### Behavioral spec `updated(changed)` branches on two independent property changes: a `viewport` transition calls `#bindPopover()` (true) or `#unbindPopover()` (false), and an `open` transition calls `#sync()` then dispatches a plain bubbling `open` or `close` `Event` (no `detail` payload) matching the new [open] value. `connected()` calls `#bindPopover()` only if [viewport] is already true at connect time: no popover wiring happens for the default (sticky) mode, and no `toggle` listener is ever attached while [viewport] is false. `#bindPopover()` sets `popover="manual"` only if the attribute isn't already present, guards against double-binding the `toggle` listener via a private `#popoverBound` flag, then calls `#sync()`. `#sync()` is the single source of truth reconciling [open] with actual popover state: it no-ops when [viewport] is false, and otherwise calls `showPopover()`/`hidePopover()` only when `:popover-open` disagrees with [open]: both calls are wrapped in try/catch since the Popover API may be unavailable. `render()` re-calls `#sync()` on every reactive pass while [viewport] is true, so the popover stays in sync even after the class methods change [open] out of band. `#onToggle` listens for the native `toggle` event (fired by browser-driven or programmatic `showPopover()`/`hidePopover()` calls) and reflects `e.newState === 'open'` back into the [open] property, but only when it actually differs: preventing an update→sync→toggle feedback loop. `disconnected()` is symmetric cleanup: if still popover-open, it calls `hidePopover()` (try/catch-guarded); if a `toggle` listener is bound, it clears `#popoverBound` and removes the listener: mirroring `#unbindPopover()`'s own teardown without touching the `popover` attribute itself (the element is leaving the DOM regardless). Anchor-bar deliberately does not join the modal/drawer mutual-exclusion convention; it coexists with page interaction and open popovers rather than blocking either. ## `` **Composes:** _(none)_ **Allowed children (a2ui):** _(unconstrained)_ **Fulfills:** _None._ **Disambiguation:** | Neighbor | Cue | |---|---| | `admin-sidebar` | Not for app-shell sidebars: admin-shell no longer reads `` (ADR-0024); use the bespoke `` instead. | | `chat-sidebar` | Not for app-shell sidebars: use the bespoke `` under `` instead of ``. | | `editor-sidebar` | Not for app-shell sidebars: use the bespoke `` under `` instead of ``. | ### Screen-reader spec No class file exists for this component: it is a CSS-only slot stub with no `connected()`/`render()` lifecycle of its own, so it stamps no role or ARIA attributes at all. Accessible semantics come entirely from the container parent that reads [collapsible]/[width] via `@scope`; consumers wanting a landmark role should add one explicitly (or let the parent primitive's own a11y wiring supply it) rather than relying on aside-ui for any implicit announcement. ### Behavioral spec There is no interaction model and no lifecycle: aside-ui ships zero JS (`.class.js` does not exist for this component); it is pure CSS positioned by tag + ancestor + DOM order. [collapsible] and [width] are plain reflected attributes read by the container parent's own styling and JS; the aside element itself never toggles, animates, or responds to either attribute changing. There is no loading, error, or empty state. No Card/Drawer/Modal/Page/AppShell CSS or JS currently reads `` (a grep across those components' `.css`/`.class.js` returns zero matches): treat any such parent-styling wiring as unimplemented, not as a placement contract. ## `` **Composes:** `` **Allowed children (a2ui):** _(unconstrained)_ **Fulfills:** _None._ **Disambiguation:** | Neighbor | Cue | |---|---| | `avatar-group-ui` | For a stacked/overflowed set of avatars, reach for the sibling avatar-group-ui rather than composing rows of avatar-ui by hand: it owns the +N overflow counter and size propagation this primitive doesn't. | ### Screen-reader spec connected() stamps `role="img"`, and render() derives the accessible name via `syncAutoAriaLabel()` from [text] first, then [icon], never clobbering a consumer-set `aria-label` (gh#1647's value-tracking guard: the component only owns the aria-label value it itself last wrote, so a hand-authored aria-label survives every re-render). The rendered `` element's own `alt` mirrors [text] (empty string when [text] is unset, never left undefined); this is somewhat redundant with the host's own `role="img"` + aria-label, which is what a screen reader actually announces. There is no focus/keyboard handling of any kind: avatar-ui is a decorative or identity-labeling image element, never independently focusable, and carries no interactive semantics beyond the static `role="img"`. ### Behavioral spec The real fallback precedence, read from render(), is narrower than the yaml `description`'s "image → initials → icon" phrasing might suggest: with [src] set, a successful load always wins; only an `onerror` (failed image load) falls through, and it falls through directly to [text]-derived initials, NEVER to [icon], even when [icon] is also set. With [src] unset, [icon] takes priority OVER [text]: an avatar with both [text] and [icon] set and no [src] renders the icon, not initials; initials render only when [icon] is also empty. All three surfaces (image/icon/initials) are mutually exclusive DOM children: render() actively removes the other two before creating the active one, so more than one visual representation is never mounted at once. An avatar with none of [src]/[text]/[icon] set renders nothing at all (render() returns before creating any child): there is no default placeholder glyph. There is no loading or error state exposed to the consumer: the image-load failure is handled entirely internally via the swap to initials. ## `` **Composes:** `` **Allowed children (a2ui):** _(unconstrained)_ **Fulfills:** _None._ **Disambiguation:** | Neighbor | Cue | |---|---| | `tag-ui` | badge-ui is not for anything interactive or removable, use tag-ui for filter chips or user-managed labels, which fires its own `remove` event and stays proportional/sentence-case rather than badge's uppercase/mono/wide-tracked register. | ### Screen-reader spec `connected()` stamps `role="status"` unless the consumer already set an explicit role before connection (e.g. `` overriding to `role="button"` for a toggleable legend chip: badge-ui never clobbers that choice). `render()` mirrors [text] into `aria-label` whenever [text] is non-empty, so the accessible name always matches the visible pill text (including the CSS-rendered `attr(text)` content) even though the text itself paints via CSS rather than a text node. An icon has no accessible-name contribution of its own: it's a decorative `icon-ui` child, so [text] (or the [status] shorthand's mapped text) is the sole source of the announced label; a badge with an icon and no [text]/ [status] announces nothing. `role="status"` means a badge mounted or updated inside a live region gets announced as a passive state change, not an interruption: there is no separate live-region wiring beyond that role. ### Behavioral spec There is no interaction model: no press/focus/keyboard handling, no `disabled` state. [status] and [variant]/[text] are mutually exclusive in effect: while [status] is set, `render()`'s shorthand mapping overwrites [variant]/[text] on every render pass, so setting both is unsupported (last shorthand write wins, not a merge). [icon] is added or removed by direct DOM diffing against the existing `icon-ui` child (`querySelector(':scope > icon-ui')`) rather than a full re-stamp, so changing only [weight] on an already-present icon updates the existing element in place instead of remove+recreate. There is no loading, error, or empty state: badge-ui renders synchronously from its properties with no async lifecycle of its own. ## `` **Composes:** _(none)_ **Allowed children (a2ui):** _(unconstrained)_ **Fulfills:** _None._ **Disambiguation:** | Neighbor | Cue | |---|---| | `col-ui` | For spacing children relative to each other, col-ui (or row-ui / grid-ui) is the right fit: block applies [padding] / [margin] to itself and owns no flex or grid, so it cannot lay its children out at all. | ### Screen-reader spec No role, label, or ARIA attribute is stamped by this component at any point: `static template` returns `null` and `render()` only ever touches inline `--block-padding`/`--block-margin` custom properties. block-ui is accessibility-neutral by design: it contributes nothing to the accessibility tree beyond whatever semantics its children or a wrapping landmark supply. ### Behavioral spec Pure CSS-token resolver, no interaction model. `render()` runs on every [padding]/[margin] change and only does unit conversion: a responsive value (containing `@`) is resolved against the current breakpoint via `parseResponsive`/`breakpoint.value` and written to the `--block-padding`/`--block-margin` custom properties; a non-responsive value clears those properties so block.css's static rules take over instead: the two paths are mutually exclusive per dimension, never both active at once. Named rungs (`xs`..`xl`) map to the parametric `--a-{padding,margin}-{rung}` scale; bare integers map to `--a-space-N`; `none` resolves to literal `0`. There is no loading, error, focus, or empty state: [app]/[panel]/[active] are inert pass-through markup this component never reads or reacts to itself. ## `` **Composes:** _(none)_ **Allowed children (a2ui):** _(unconstrained)_ **Fulfills:** _None._ **Disambiguation:** | Neighbor | Cue | |---|---| | `alert-ui` | blockquote-ui is not a general callout or alert container: reach for alert-ui when the content is a status/notice rather than a quotation. | | `card-ui` | blockquote-ui is not a general callout container: reach for card-ui when the content needs its own bounded surface rather than inline prose chrome. | ### Screen-reader spec `connected()` sets `role="blockquote"` on the host exactly once, and only if no `role` attribute is already present (`if (!this.hasAttribute( 'role')) this.setAttribute('role', 'blockquote')`): this is the component's only ARIA-relevant call in `class.js`; it exists because assistive tech doesn't infer semantics from a custom-element tag name the way it would from a native `
`. There is no aria-label, live-region, or other ARIA construct: the quote body (default slot) and the citation line (`[slot="cite"]`) are read as ordinary text content in DOM order, so a screen reader announces the quote body followed by the citation line (visually prefixed with an em-dash via CSS `::before`, which is not exposed to the accessibility tree since it's decorative). ### Behavioral spec `render()` implements the two-attribution-path precedence described in [cite]'s own prop entry, resolved fresh on every reactive pass. It first looks for author-provided slotted content: a `[slot="cite"]` element that does NOT carry `data-cite-stamped`, and if present, removes any previously auto-stamped span (`stamped?.remove()`) and returns immediately: slot content always wins over the [cite] prop when both are set, matching the yaml's own contract, and no further cite handling runs that pass. Absent author-provided slot content, [cite] drives an auto-stamped ``: if a stamped span already exists from a prior render, its `textContent` is updated in place (avoiding a remove/recreate churn); otherwise a new span is created and appended as the last child. If [cite] is empty/falsy and a stamped span still exists (e.g. the caller cleared [cite] after setting it), the stamped span is removed entirely: there is no empty citation line left behind. The `data-cite-stamped` marker is what lets `render()` distinguish "component-owned, safe to overwrite/remove" content from "author-owned, must not touch" content on every subsequent pass. ## `` **Composes:** ``, ``, `` **Allowed children (a2ui):** _(unconstrained)_ **Fulfills:** _None._ **Disambiguation:** | Neighbor | Cue | |---|---| | `nav-ui` | For offering a set of destinations, nav-ui is the right fit. breadcrumb-ui does not offer choices, it reports the path TO the current page as an ordered trail with auto-inserted separators, collapsing the middle into an overflow menu when it does not fit. | ### Screen-reader spec connected() stamps `role="navigation"` and `aria-label="Breadcrumb"` on the host once, unconditionally (no adopt-or-stamp guard on the label: a consumer-set aria-label is overwritten on every connect). Every render() pass marks exactly the LAST visible-in-DOM item `aria-current="page"` and strips it from every other item, so the current-page marker always tracks DOM order even as items are added/removed/collapsed. Separator characters are inserted as `aria-hidden="true"` ``s between consecutive visible siblings, so a screen reader never announces the separator glyph itself: only the item text and (for the overflow trigger) its own aria-label. The overflow `…` trigger is a `button-ui[aria-label="Show collapsed crumbs"]` that opens a `menu-ui` popover; that popover inherits menu-ui's own keyboard nav and top-layer rendering rather than breadcrumb-ui wiring any keyboard handling of its own. ### Behavioral spec [collapse] only takes effect once the item count is at least `max(collapseKeepLeading + collapseKeepTrailing + 1, 4)`: a short trail never collapses even with [collapse] set. The collapsed middle items are hidden (`data-collapsed`) and re-surfaced only inside the `…` overflow `menu-ui` popover as `menu-item-ui` entries; activating one navigates via `window.location.href` for a real href, and is a no-op for a placeholder `#` link. A collapsed link's href is preserved by copying it onto the menu-item's `value`, but a non-link crumb (a bare ``) loses any click affordance entirely once collapsed: only its text survives into the menu. `collapse-keep-trailing` is floored at 1 internally regardless of the attribute value (gh#2813): the LAST item always receives `aria-current="page"`, so a consumer setting `collapse-keep-trailing="0"` no longer pulls the current-page crumb into the collapsed/hidden set: it stays visible in the trail rather than becoming reachable only by opening the overflow menu. Set `collapse-keep-leading="0"` instead if the intent was to push the overflow trigger to the very start of the trail. render() is fully idempotent: it strips all previously-stamped separators and the overflow menu before recomputing, so no chrome accumulates across repeated attribute changes. There is no loading, error, or empty state: items are always synchronously present in the light DOM. Light-DOM children are plain `` links or a final non-link `` for the current page, never breadcrumb's own prop-driven markup. ## `` **Composes:** `` **Allowed children (a2ui):** _(unconstrained)_ **Fulfills:** _None._ **Disambiguation:** | Neighbor | Cue | |---|---| | `link-ui` | button-ui is not for navigation (route changes): use link-ui, which carries `` semantics and announces "link" to a screen reader instead of "button". | | `switch-ui` | button-ui is not for toggleable on/off state: use switch-ui for a single toggle; button-ui has no pressed/checked persistence, only a momentary `press` event. | | `segmented-ui` | button-ui is not for toggleable on/off state: use `segmented-ui multiple` + segment-ui for a multi-select cluster; button-ui has no pressed/checked persistence, only a momentary `press` event. | | `segment-ui` | button-ui is not for toggleable on/off state: use segment-ui inside `segmented-ui multiple` for a multi-select cluster; button-ui has no pressed/checked persistence, only a momentary `press` event. | ### Screen-reader spec The accessible name comes from [ariaLabel] when set, or falls back to the rendered [text]/child text content (reflected in render() via setAttribute, deliberately outside `static properties` so it doesn't clobber native ariaLabel reflection). An icon-only button (no [text] and no non-whitespace child text) MUST set [ariaLabel] explicitly: render() reflects the icon-only state as `[data-icon-only]`, but that attribute is a CSS hook only, not an accessible-name source, so a screen reader announces nothing for an unlabeled icon-only button. Focus order follows DOM order like any native `