@adia-ai/gen-ui 0.8.37

package/corpus/catalog-a2ui_0_9_rules.txt

@@ -0,0 +1,1215 @@
+# AdiaUI Catalog — LLM Rules (v0.9)
+
+# Cross-component and contextual constraints that the JSON Schema validator
+# cannot express. Concatenated into the agent system prompt.
+# Generated from each component YAML's `a2ui.rules:` entries.
+
+## AccordionItem
+- Child of <accordion-ui> — places one collapsible section with header + body.
+- Toggle behavior: click anywhere on the row toggles, unless inside [slot='actions'] or [data-no-toggle].
+- For single-button disclosures (one expanding panel without a list) use <details>/<summary> or compose <button-ui> + <section-ui>.
+- An item inherits its host accordion-ui's [variant]; set variant="flat" or variant="contained" directly on ONE item to override just that item against the host.
+
+## Accordion
+- Hosts <accordion-item-ui> children. One or more sections may be open simultaneously (set single= to enforce only-one-open).
+- For tab-switched panels (always exactly one open) use <tabs-ui>; accordion supports zero-open and multi-open.
+- Item ordering is DOM-order; no auto-sort.
+- Set variant="contained" for a bounded per-item surface (background, border, radius, and an open-state divider) — the composition to reach for when nesting inside <card-ui>. Default variant="flat" (no chrome) suits settings pages and FAQ blocks sitting on the page canvas.
+
+## ActionItem
+- Child of <action-list-ui> — one inline-action row with icon + label + optional shortcut + optional sublabel.
+- Different from <menu-item-ui>: action-items live inline in content surfaces; menu-items live inside <menu-ui> popovers.
+- For navigation entries (route-changing) use <nav-item-ui> instead.
+
+## ActionList
+- Hosts <action-item-ui> children as a vertical command list inline in content surfaces.
+- For popover-style menus use <menu-ui> + <menu-item-ui> instead.
+- Typical use: command palettes, settings panels, agent suggestion lists.
+
+## AdiaMark
+- Use <AdiaMark> for the Adia brand/app-identity mark — a favicon-style app-switcher tile, a splash/loading screen, an about-panel header. Do not use it as a generic icon; it has no [name] prop and always renders the same wordmark.
+- Do not wrap <AdiaMark> in <Icon> or pass it a color/tone override — the background/foreground pairing is fixed by design (always inverse-on-inverse for contrast), not a themeable variant.
+- Prefer <AdiaMark size="sm"> in a nav/topbar brand slot (a Row alongside the product name); reserve larger sizes (lg, xl) for splash screens or empty-state headers. Set [inline] only when the mark sits directly inside a run of prose text, not inside a Row/flex layout (block-level children compose fine as flex items already).
+- Use <AdiaMark> for the square icon/tile use (app-switcher slot, favicon-style avatar) — always the fixed inverse-on-inverse pairing. Use <AdiaWordmark> instead for the standalone "Adia" text logotype meant to sit directly on a surface with no background chip.
+
+## AdiaWordmark
+- Use <AdiaWordmark> for the Adia text logotype standing alone directly on a surface — a login/marketing header, a footer, an about panel, a splash screen with no background chip. Use <AdiaMark> instead for the square icon/tile use (app-switcher slot, favicon-style avatar).
+- Do not wrap <AdiaWordmark> in <Icon> or pass it a color/tone override tied to an inverse pairing — it has no [name] prop, always renders the same logotype path data, and its fill is meant to track the current surface's foreground token.
+- Prefer <AdiaWordmark size="sm"> in a nav/topbar brand slot; reserve larger sizes (lg, xl) for splash or login screens. Set [inline] only when the wordmark sits directly inside a run of prose text, not inside a Row/flex layout (block-level children compose fine as flex items already).
+
+## AgentArtifact
+- Inline container for structured agent payloads inside <chat-thread-ui> message bodies or <inspector-ui> panes.
+- kind attribute (a2ui|json|ticket|code|...) sets content-type-aware rendering and icon/badge styling.
+- For free-text agent output use <text-ui> or <richtext-ui>; artifact-ui is for structured payloads only.
+- primary + secondary slots for header chrome; default slot for the artifact body.
+
+## AgentFeedbackBar
+- Thumbs-up / thumbs-down rating row + optional Save action, rendered beneath an LLM-generated message.
+- Different from <rating-ui> (star-based ordinal) — agent-feedback is binary good/bad.
+- Emits feedback events with value=up|down and optional save action; consumer wires the actual feedback API call.
+- Place at the end of an assistant message in <chat-thread-ui>, not on user messages.
+
+## AgentQuestions
+- Multi-choice clarifying-question card emitted by an agent when it needs disambiguation before proceeding.
+- multi attribute controls single-select (default) vs multi-select answer behavior.
+- Slot accepts <button-ui> answer chips; for radio-card style use <segmented-ui> + <segment-ui> children instead.
+- Different from <agent-suggestions-ui> (follow-up suggestions, optional) — agent-questions is gating (agent waits for answer).
+
+## AgentReasoning
+- Agent inner-monologue + pipeline viewer with steps, thoughts, plans, and iterations.
+- JS-property-driven ONLY — steps arrive via addStep()/addThought(); the component renders them internally as <timeline-item-ui> rows. Authored light-DOM children are NOT consumed (gh#938) — for a static/harvestable reasoning-steps surface, author a plain <timeline-ui> with <timeline-item-ui> children instead.
+- noAutocollapse attribute prevents the auto-collapse-on-complete behavior; useful for debug surfaces.
+- Different from <agent-trace-ui> (metrics + tool-call summary) — reasoning is narrative, trace is structured-data.
+
+## AgentSuggestions
+- Row of follow-up suggestion chips presented under an agent response. User taps to send the chip text as the next prompt.
+- Hosts <button-ui> children with chip-style variant; auto-applies variant if children don't set one.
+- Different from <agent-questions-ui> (required disambiguation) — suggestions are optional and the agent doesn't wait.
+- Place at the end of an assistant message in <chat-thread-ui>; not for first-message empty-state suggestions (use <empty-state-ui>).
+
+## AgentTrace
+- Collapsible metrics + training-feedback panel showing reasoning steps, tool calls, latency, and token counts.
+- Place inside <chat-thread-ui> message bodies for expert/debug views; hide by default in user-facing chat.
+- Different from <agent-reasoning-ui> (narrative inner monologue) — agent-trace is structured metrics.
+- Default collapsed=true; expand-on-demand keeps chat-thread visual density low.
+
+## Alert
+- Inline alert/banner for status messages within a content region. Severity via variant (info, success, warning, danger) — those four plus the family-less default are the whole enum.
+- For ephemeral toast notifications use <toast-ui> (or post to <feed-ui>); alert-ui is persistent inline.
+- For modal-style critical alerts use <modal-ui> with alert content.
+- Billing dunning / payment-failed notices use pattern="dunning" + amount + currency + dueAt props, NOT inlined into title/description strings.
+- pattern="dunning" SHOULD use variant="danger" (default) or variant="warning" (grace period); never variant="info" or "success".
+- When pattern="dunning", slot at least one button-ui in slot="actions" with data-dunning-action ("update" or "retry").
+
+## AnchorBar
+- Persistent, non-blocking anchored surface. Use for floating bulk-action toolbars, undo bars, and wizard/commit footers — never for transient notifications (use <toast-ui>) or blocking dialogs (use <modal-ui> / <drawer-ui>).
+- Default [viewport=false] anchors within the nearest scroll container via position:sticky — the correct choice when the bar sits over a bounded scroll region (e.g. a table's own scroll box). Set [viewport] only when the surface must anchor to the browser viewport regardless of ancestor scroll containers (e.g. an undo bar over an arbitrary page layout).
+- Does NOT join the modal mutual-exclusion convention — it is not a modal surface and coexists with page interaction and open popovers.
+
+## Aside
+- Use <aside-ui> as a slot stub inside an IN-PAGE primitive container parent (<card-ui>, <drawer-ui>, <modal-ui>, <page-ui>) for two-column layouts with a semantic side region. It ships no behavior; the parent reads [collapsible] and [width] via @scope. Typical contents: <list-ui> / <tree-ui> / <nav-ui variant="section">.
+- Do NOT use <aside-ui> for app-shell sidebars. <admin-shell> no longer reads <aside-ui slot="leading|trailing"> (retired in v0.4.0 per ADR-0024). Use the bespoke <admin-sidebar slot="leading|trailing" collapsible resizable> with reflected [collapsed] / [resizing] state. Same rule for <chat-sidebar> under <chat-shell> and <editor-sidebar> under <editor-shell>.
+- Do NOT confuse <aside-ui> with <pane-ui>: aside-ui declares the semantic side role (a11y + parent layout hint); <pane-ui> owns resize / collapse interaction. When you need interactive resize inside an aside, nest <pane-ui resizable> inside.
+- Width hints map to tokens: `width="rail"` ≈ icon-only nav, `width="panel"` ≈ nav with labels, `width="wide"` ≈ workspace pane. Unset defers to the parent default. Only pair `collapsible` with parents that wire a toggle (the prop is a hint, not a behavior).
+- For the settings-page description rail (label + help text on the left, controls on the right) use plain HTML <aside> inside a [data-section] flex layout — see apps/saas/billing and apps/saas/members. That pattern is NOT aside-ui; the primitive is for slotted container parents only.
+
+## AvatarGroup
+- Cluster of overlapping <avatar-ui> children with negative-margin stacking + +N overflow indicator.
+- max attribute controls visible-avatar count before +N overflow kicks in.
+- For a single user use <avatar-ui> standalone; avatar-group only for 2+ users.
+
+## Avatar
+- Use for representing a single person, account, or entity. Image, initials, or icon fallback in priority order.
+- For clusters of multiple users, wrap multiple <avatar-ui> in <avatar-group-ui> instead of placing them inline.
+- Do not embed inside <button-ui> for clickable avatars — make the <avatar-ui> itself the click target with role='button'.
+
+## Badge
+- Use for small status/count labels attached to another element (notification counts, status pills, version tags).
+- A bare Badge (no [tone]) renders a solid, saturated status stamp. Set [tone="muted"] for the quieter tinted look on dense metadata rows.
+- Place adjacent to or absolutely-positioned over the badged element, not inside it.
+- For dismissable taxonomy labels (filter chips, selected items in multi-select), use <tag-ui> instead.
+
+## Block
+- Generic semantic block — use for arbitrary content groupings without strong layout semantics.
+- For row/column layouts use <row-ui> / <col-ui>; for grid use <stack-ui>; block is for content-flow groupings.
+- Block-ui does not impose padding/gap by default — wrap in <section-ui> if you want chrome.
+
+## Blockquote
+- Use for pull-quotes, testimonials, or inline citations. Renders italic body text with a left rule indicator + optional em-dash attribution line.
+- Set [cite] for plain-string attribution; use [slot="cite"] for rich attribution (linked source, role pairing). Slot content overrides the [cite] prop when both are set.
+- Do NOT wrap blockquote-ui in a native <blockquote> element — that produces nested-blockquote semantics. The tag IS the blockquote.
+
+## Breadcrumb
+- Canonical placement: render <breadcrumb-ui> inside <admin-topbar> for hierarchical page-context display. It is the topbar's heading region — typically preceded by a sidebar-toggle <button-ui icon="sidebar" variant="ghost" size="sm"> and followed by topbar actions in [slot="action"]. The host stamps role="navigation" + aria-label="Breadcrumb" automatically.
+- Child shape: each crumb is either an <a href> (ancestor link) or a plain <span> (terminal / non-link current page). The LAST child is the current page and MUST be a plain <span> — the component auto-applies aria-current="page" and disables pointer events on it. Optional first child may be an <icon-ui> (or <a> wrapping one with aria-label) for an app / home glyph.
+- Separator + overflow: do NOT insert your own separator elements ([data-sep] spans are stamped automatically between children). For deep trails (4+ items) prefer the `collapse` attribute over manual truncation; tune visible edges with [collapse-keep-leading] / [collapse-keep-trailing]. Collapsed middle crumbs are presented as a `…` <menu-ui data-overflow> popover.
+- Decision rule: <breadcrumb-ui> is read-only PATH-CONTEXT display ("where am I"). For primary navigation (sidebar) use <nav-ui> + <nav-item-ui> inside <admin-sidebar>. For switching sub-views within a page use <tabs-ui>. Never use <breadcrumb-ui> as the primary navigation control or wrap navigation controls (selects, tabs, form controls) inside it.
+
+## Button
+- Canonical clickable affordance — text + optional icon. Variant attribute sets primary/secondary/ghost/destructive intent.
+- Do not repeat the icon's glyph in text=. Icon provides the symbol; text= carries only the words.
+- For navigation (route-change) use <nav-item-ui> or anchor; button-ui is for actions only.
+- For toggleable on/off state use <switch-ui>; for multi-select clusters use <toggle-group-ui> + <toggle-option-ui>.
+
+## CalendarGrid
+- Use <CalendarGrid> only as a substrate primitive composed inside a higher-level component (date-range picker, datetime picker, custom date affordance). For a full single-date input, use <CalendarPicker> — it adds a trigger button, popover surface, and form-association.
+- <CalendarGrid> is NOT form-associated. Its emitted `change` event is the sole signal to the parent — the parent owns the canonical value + form participation.
+
+## CalendarPicker
+- Form-associated date input. Trigger button + popover calendar grid; emits ISO date string via change events.
+- Use for single-date input. For date ranges compose two pickers or use a dedicated range component.
+- min/max attributes constrain selectable range; disabled-dates accepts a function or date list.
+
+## Canvas
+- A2UI rendering surface — consumes a DocStore / A2UI document and renders the component tree from it.
+- Typically wrapped by <a2ui-root> internally; for direct-mount use <canvas-ui> as the root.
+- Do not place static children inside — the runtime owns the rendered DOM.
+- theme attribute scopes the AdiaUI token theme to the canvas subtree.
+
+## Card
+- The card's <header> grid activates only for DIRECT-child slotted elements. If you need an icon column, place the icon element (avatar-ui, icon-ui) directly in the header with slot="icon" — not inside a wrapper.
+- Heading slot accepts inline badges/metadata: <span slot="heading"><text-ui strong>Title</text-ui><badge-ui text="New" variant="primary"></badge-ui></span> renders title + badge on one row.
+- Description slot also accepts bare <p> or <small> elements as siblings of the heading — they participate in the grid's row 2 without needing slot="description".
+- Multiple <section> siblings are allowed and stack vertically. [bleed] on a section removes its margin for edge-to-edge content (tables, charts); [padding] adds a canvas-scrim background for hero regions.
+- When neither [raw] nor [frameless] is present, a <table-ui> placed directly inside a <section bleed> automatically renders chromeless (background/box-shadow/border-radius reset; card.css, gh#796): the card already owns the frame, so the table doesn't need its own. table.yaml's [raw]/[frameless] docs describe the same composition; an explicit [raw] or [frameless] on the table still applies and is honored. A plain (non-bleed) <section> is unaffected — its own padding keeps a nested table's frame legible as an intentional nested surface.
+- [grow] on a section makes it fill the card's remaining height (flex:1 — same semantics as col-ui[grow]/row-ui[grow]). The card becomes a flex column so the section absorbs the leftover space after the header/footer. Requires the card to have a definite height (inline height, grid row track, or flex parent) — a content-sized card has nothing to fill. Combine with [bleed] for edge-to-edge fill: <section bleed grow>. A <chart-ui> directly inside a <section bleed> auto-grows without [grow] (zero-config convenience for the common chart case).
+- Footer with a [slot="description"] + [slot="action"] pair triggers justify-content: space-between — useful for a "Last saved …" note on the left and a Save/Cancel button group on the right.
+- Do NOT substitute <card-ui> for shell/page containers. <admin-page>, <admin-content>, and <page-ui> own routed page layout; <card-ui> is a localized bordered surface that lives INSIDE them. For overlays use <modal-ui> (centered) or <drawer-ui> (edge-anchored) — both share the same 4-stub <header>/<section>/<footer> vocabulary.
+- Use [raw] when a parent already owns the surface chrome (e.g. an auth screen centred on the viewport — see apps/user-flow/auth). Use [elevation] 0–3 for shadow depth; [variant="ghost"|"flat"] to remove shadow without removing structure. [draggable] emits a drag-end event; only enable on cards meant to move.
+
+## ChartLegend
+- Standalone legend primitive — a row of <badge-ui>+<swatch-ui> chips that are keyboard-focusable and click-toggleable.
+- Pairs with <chart-ui> via [for] id-ref (auto-bidirectional series toggling) or via items= for standalone use.
+- position attribute (top|bottom|left|right) places legend relative to its chart; static= disables interactivity.
+
+## Chart
+- Declarative SVG chart supporting 18 types via the type attribute (bar, line, pie, donut, radar, area, ...).
+- For density-grid visualizations (calendar heatmap, etc.) use <heatmap-ui> instead.
+- Pair with <chart-legend-ui [for]=...> for keyboard-toggleable series legends; otherwise use the built-in inline legend.
+- title + empty slots for chart chrome; canvas slot for chart-internal overlays.
+
+## ChatInput
+- ChatInput is a self-contained composer — it stamps its own textarea + model picker + send button. DO NOT add a separate Button sibling for "send" inside the same parent. The user gets two send buttons (one built-in, one redundant).
+- For chat interfaces emit ChatInput as the sole input component inside the chat shell. The submit event fires on Enter or send-button click; `detail` is `{ text, model }`.
+- To customize models, set the `models` prop with an array of {value, label} option objects. Do not stamp a separate Select next to ChatInput for model selection — the built-in model picker handles it.
+
+## ChatThread
+- Primitive chat-message scroll container — ad-hoc message rendering surface.
+- Different from the bespoke <chat-thread> (module-tier, lives inside <chat-shell-ui>, owns scroll + load-more affordances).
+- Hosts arbitrary children — typical content: agent + user message blocks, <agent-feedback-bar-ui>, <agent-suggestions-ui>.
+- streaming attribute hints the consumer to show a streaming indicator (composes well with <stream-ui> children).
+
+## Check
+- Self-labeling widget — use the [label] attribute directly; do NOT wrap in <field-ui>. The widget renders its own label inline via CSS attr() pattern. Wrapping breaks the consent-row layout (see field-ui anti_patterns).
+- When check-ui is used as a list-item icon/indicator beside a separate title element carrying the same name (a title column, a list-item-ui slot="text"), set [label-hidden] alongside [label] so the accessible name is preserved without painting the name twice.
+- Three states supported: unchecked (default), checked (via [checked]), and indeterminate (via [indeterminate]); form-associated.
+- For binary on/off toggles where visual switch metaphor matters, use <switch-ui> instead; check-ui is for multi-select sets and form-acceptance gates.
+
+## Code
+- Inline (default) for short tokens in prose; block variant (display='block') for multi-line snippets.
+- Do not use for editable code — use <richtext-ui> with code variant or a dedicated editor primitive.
+- Inside <agent-artifact-ui> blocks for agent-emitted code snippets; lang= sets syntax-highlighting hint.
+
+## Col
+- Vertical-stack flex container. Children flow top-to-bottom with token-driven gap.
+- Pair with <row-ui> for horizontal layouts; both share the same gap-token contract.
+- Set align/justify attributes for cross-axis / main-axis alignment; default is start/start.
+
+## ColorInput
+- Use <color-input-ui> for any form-row color field — it canonicalizes the popover + button + color-picker recipe and is the only form-bearing color primitive. Do not hand-roll the composition; reach for color-input-ui directly.
+- Set [format="oklch"] when the persisted value feeds CSS tokens or perceptual math; [format="hex"] for legacy / design-tool interop. Event detail (`change` / `input`) carries BOTH `hex` and `oklch` views regardless of [format], plus parsed `{l, c, h}` channel scalars.
+- For brand-palette constraints, set [maxChroma] / [minL] / [maxL] / [hueDriftMax] (with [baseHue]) on the host — they forward to the inner <color-picker-ui> and clamp generation. Useful for Tokens-Studio-style guarded color generation.
+- Use <color-picker-ui> DIRECTLY (no color-input-ui wrapper) only for full-surface editors where the picker IS the page (e.g. Tokens Studio main canvas). For inline form-row use, always reach for <color-input-ui>.
+- Per ADR-0027 (cross-primitive composition imports), consumer pages MUST explicitly import <button-ui>, <popover-ui>, and <color-picker-ui> before <color-input-ui>. The primitive composes them but does NOT auto-register them.
+
+## ColorPicker
+- OKLCH-native color picker with 2D color area + H/C/L sliders. Form-associated; emits OKLCH color strings.
+- For simple color swatches (read-only display) use <swatch-ui>; for hex/rgb text input use <color-input-ui>.
+- Output format defaults to oklch(); set format= to override (hex, rgb, hsl).
+
+## Combobox
+- Use <combobox-ui> for typeahead-filterable single-select with a constrained-choice value model. `value` MUST be one of `options[].value` unless `[free-text]` is set. For ≤ 4 options, use <segmented-ui> or <radio-ui> instead.
+- For free-form text entry with suggestions, use <autocomplete-input-ui> (SPEC-035) — combobox is constrained-choice. For button-first dropdowns where the trigger should be closed by default, use <select-ui searchable>.
+- Compose options via native <option> / <optgroup> children, OR set `.options` programmatically as an array of `{value, label, disabled?}` (grouped form: `{label, options:[…]}`). Setting `value` to a string not in `options` is invalid mid-state (free-text=false) and the validator should reject it.
+- `[creatable]` implies `[free-text]` and adds the "Create '{value}'" footer affordance + `create` event. Consumer wires the create event to a backend flow.
+- Multi-select goes through <select-ui multiple> (chips in the trigger, checkbox-style option rows), not combobox. Combobox is single-select; there is no <multi-select-ui> tag.
+
+## Command
+- <command-ui> is the searchable PALETTE primitive (input + option list). For Cmd+K palettes, wrap it in <admin-command> at the shell tier — admin-command owns the native <dialog>, focus management, and the Cmd+K / Ctrl+K shortcut listener. command-ui is content-only and does NOT own the dialog or shortcut. Do NOT hand-roll a <dialog> + Cmd+K key listener.
+- Author items as native <option value data-icon data-shortcut> elements inside <optgroup label="…"> for grouped sections, OR set `.options` programmatically as an array of `{value, label, icon?, shortcut?, disabled?}` (grouped form: `{label, options:[…]}`) — same fields, alternative to declarative children. The `select` event's detail.category mirrors the parent optgroup's label (or the group's `label` when authored via `options`). Detail = { value, label, category }.
+- Decision rule vs adjacent surfaces. Use <menu-ui> for small NON-searchable popover menus (≤10 actions, triggered by a button). Use <modal-ui> for generic centered dialogs. Reach for <command-ui> only when you need a searchable, keyboard-navigable list of commands or destinations.
+- command-ui MAY render inline (no dialog) for embedded search panels, but the canonical AdiaUI admin pattern is exactly one <command-ui placeholder="…"> as the sole child of <admin-command> inside <admin-shell>. See site/index.html and playgrounds/admin-shell/ for production references.
+
+## ContextMenu
+- Use <context-menu-ui> for right-click menus on a target (table row, file item, canvas object). For button-triggered menus use <menu-ui>; for popover content that is not a menu use <popover-ui> directly.
+- Items are <menu-item-ui> children inside the default slot — same shape as <menu-ui> items.
+- Bind target via wrap (default-slot first non-menu-item-ui child) OR [for] selector. The selector form is useful for whole-table or whole-canvas menus where wrapping isn't practical.
+
+## DateRangePicker
+- DateRangePicker.value MUST be `{from, to}` with both ISO 8601 dates, OR null. Either side null is invalid mid-state and the validator should reject it (use `input` event for partial state).
+- DateRangePicker.value.to MUST be `>=` value.from lexicographically. Reversed ranges trigger `invalid` and do NOT commit.
+- When `comparison: true`, both `value` AND `compareValue` MUST be set on commit. If only one is set, the form participation emits the set one and omits the other.
+- presets array entries each require both `label` (string) and `range` (`{from, to}`). Empty preset arrays are valid (rail renders empty).
+- Use DateRangePicker for date ranges. Do NOT compose two adjacent `<calendar-picker-ui>` instances + JS synchronization — that is the pattern this primitive replaces.
+
+## DatetimePicker
+- `DatetimePicker.value` MUST be ISO 8601 datetime (`YYYY-MM-DDTHH:mm` or `YYYY-MM-DDTHH:mm:ss`) OR empty string. Date-only or time-only strings fire `invalid`.
+- `precision: "second"` requires the value to include seconds when set; missing seconds are coerced to `:00` on commit.
+- `min` and `max` MUST be parseable ISO 8601 datetimes if non-empty. If `value` falls outside, `invalid` fires and the value does not commit.
+- `hour-cycle` overrides the locale-derived cycle in the time pane. Set explicitly when the surface needs a specific cycle (cron editors, log queries, system surfaces).
+- Use DatetimePicker for combined date+time. Do NOT compose `<calendar-picker-ui>` + a free-form `<input-ui>` manually as an alternative — that is the pattern this primitive replaces.
+- Per ADR-0025 NEVER wrap a native `<input type="datetime-local">` — the calendar pane + time pane composition + ElementInternals together provide form participation.
+
+## DemoToggle
+- Demo-page-only — toggles between live and code views in component documentation surfaces.
+- Do not use in apps/ — restrict to packages/web-components/components/*/<name>.html demo pages and docs surfaces.
+- Behavior: shows/hides the [data-code] block when toggled.
+
+## DescriptionList
+- Use for key:value pairs in dense detail views (user profile fields, metadata panels, audit logs).
+- Do not use for editable forms — use <fields-ui> instead.
+- Pairs render as label + value on the same row by default; use vertical variant for narrow panes.
+
+## DisplayField
+- Use for a display-ONLY labeled value — a masked card number, a 'card on file' read-out, an account id — anywhere a value reads as a field but must not be editable.
+- To host a third-party element (a Stripe Element iframe) under a label, slot it as the default child instead of setting value=. The label names it via role=group + aria-labelledby.
+- For an editable field use field-ui + input-ui; for a prominent KPI use stat-ui; for many read-only pairs at once use description-list-ui.
+
+## Divider
+- Use to separate visually distinct sections within a container; horizontal default, vertical via orientation='vertical'.
+- Inside menus / popovers use <menu-divider-ui> instead; it has menu-specific token spacing.
+- Do not stack multiple consecutive dividers — use a single divider or restructure the section.
+
+## Drawer
+- Direct children of <drawer-ui> MUST be <header>, <section> (1..n), <footer>, or an element with slot="header|body|footer". Wrap stray <col-ui> / <row-ui> / <div> / <text-ui> in a <section>. Enforced by scripts/audit/audit-drawer-structure.mjs. Bypassing the body slot loses the section inset and teaches the gen-UI corpus the wrong pattern.
+- Reflect open state via the [open] boolean attribute on the host (open=true / open=false). Do NOT toggle visibility with CSS, [hidden], or a [data-open] proxy — drawer-ui owns the native <dialog> lifecycle, focus trap, and ::backdrop. Listen for the `close` event (detail.reason ∈ escape | backdrop | close-button | programmatic) to react to dismiss.
+- Use drawer-ui (not modal-ui) for edge-anchored detail / edit panels and mobile bottom-sheet patterns. Pick side="right" for inspector flows opened FROM a row/list item, side="bottom" for sheets, side="left" for navigation drawers on narrow viewports. Centered confirmations belong in modal-ui.
+- Compose the drawer header with [slot="icon|heading|description| action"] direct-child elements to activate the card-ui-aligned 3-column grid (icon | heading+description | action+close). The close button is auto-stamped; do not author your own X button unless using [permanent] (which suppresses the close button).
+- Never set drawer.innerHTML wholesale — it wipes the stamped <dialog> part and the author skeleton. Mutate a stable inner element inside a persistent <section> instead. Same rule as <modal-ui>.
+
+## Embed
+- Responsive sandboxed <iframe> wrapper at constrained aspect ratio. Safe sandbox attributes are applied by default.
+- For raster/vector images use <image-ui>; for icons use <icon-ui>; embed-ui is for live external content only.
+- aspect attribute locks ratio (e.g. 16/9, 4/3) to prevent layout shift; width/height override when needed.
+- Do not embed first-party AdiaUI app routes — use direct component composition instead.
+
+## EmptyState
+- Use <empty-state-ui> for zero-data states: empty lists, no-results search, fresh accounts. Not for loading (use <skeleton-ui>). For inline notices within populated content use <alert-ui>. For full-section error states where the data cannot be shown at all (API failure, permission error), use <empty-state-ui variant="danger"> — the centered layout is more appropriate than an inline banner when the entire content area is replaced.
+- Canonical placement: slotted into cluster-specific wrappers — <chat-empty> inside <chat-thread>, <editor-canvas-empty> inside <editor-canvas>, OR inside <card-ui><section> for in-card empty states. Compose with an <icon-ui> for the leading glyph (pick a Phosphor name that mirrors the missing entity — folder, inbox, magnifying-glass).
+- Put AT MOST ONE CTA in slot="action". It should be the single next step (Create, Retry, Clear filters). Use [variant="primary"] for a create-flow CTA; leave [variant] unset for retry / secondary actions — the default (no attribute) already IS the secondary look, so don't add [variant="outline"] just to mark something as non-primary.
+- Use [minimal] for inline empty rows inside <table-ui> / <list-ui> where full-canvas chrome is too prominent. The `minimal` flag (§223 v0.5.9) drops chrome for a compact placeholder cell.
+- Per ADR-0027, empty-state-ui composes <icon-ui> but does NOT auto-register it. Consumer pages must explicitly import <icon-ui> before <empty-state-ui> renders correctly.
+
+## FeedItem
+- One notification entry inside <feed-ui>. Title + description + optional icon + auto-dismiss timer.
+- Typically created programmatically via UIFeed.post(...); do not place declaratively.
+- Different from <alert-ui> (inline persistent) and <toast-ui> (standalone ephemeral); feed-item is feed-scoped.
+- For "notification deep-link" pattern: post with action + onAction. Click navigates and auto-dismisses (router.push() / location.href / api.markRead()).
+
+## Feed
+- Top-layer notification feed channel — singleton per position (top-right, bottom-center, etc.) mounted lazily into document.body.
+- Hosts <feed-item-ui> children programmatically via static API (UIFeed.post(...)). Do not place feed-items declaratively.
+- For inline persistent alerts inside content regions use <alert-ui> instead; feed is ephemeral overlay.
+
+## Field
+- field-ui is for WIDE controls (input-ui, select-ui, textarea-ui, slider-ui, etc.) that need a separate label row. Small self-labeling widgets (check-ui, switch-ui, radio-ui, toggle-ui) carry their own [label] attribute and MUST NOT be wrapped in field-ui.
+- field-ui[inline] is for inline WIDE-control rows (e.g. search field with trailing kbd hint), NOT for compact-widget rows. For settings rows or consent rows, use the widget's own [label] attribute directly without a field-ui wrapper.
+
+## Fields
+- Container for form rows. Hosts <field-ui> children (or <row-ui>/<col-ui> with labeled inputs) with consistent label + control + help layout.
+- Different from <description-list-ui> (read-only key:value display) — fields-ui is for editable inputs.
+- For dynamic field arrays (repeat-able rows) compose fields-ui with manual add/remove controls.
+
+## Footer
+- Use <footer-ui> as the bottom chrome row inside a PRIMITIVE container parent (<card-ui>, <drawer-ui>, <modal-ui>, <page-ui>). Typically holds 1–3 <button-ui> children — the most common pattern is a Cancel / Confirm pair inside <modal-ui> or <drawer-ui>.
+- Use `justify="end"` (default) for Cancel+Confirm and trailing action clusters; `justify="between"` when one action lives left and one right (e.g. Back / Submit); `justify="center"` for single-button confirm flows; `justify="start"` for solo leading actions like Back.
+- Do NOT substitute <footer-ui> for bespoke shell-tier bottom chrome. Inside <admin-sidebar slot="footer"> use <admin-statusbar>; inside <editor-shell> use <editor-statusbar>. <footer-ui> is exclusively the in-container action bar at the primitive tier.
+- Do NOT wrap children in <row-ui> just to align them — the `justify` prop already lays children out horizontally. A nested row-ui double-applies layout and breaks the chrome's gap tokens.
+- Prefer flat <button-ui> children. If you need non-button content (text summary, pagination indicator), keep it as a single flat child so `justify` resolves cleanly.
+
+## Frame
+- Use <frame-ui> for a scroll-body-with-pinned-footer panel — the <section> scrolls; <header> / <footer> stay fixed.
+- Regions are positioned by tag + DOM order (native <header> / <section> / <footer>) OR by a role slot: slot="header"/"footer" pins ANY element as a rail, slot="body" makes it the scroll region (e.g. <section slot="header"> is a pinned rail). The native tag is the 90% sugar; reach for the slot when the element you want differs from the region role.
+- Most panels need only <section> + <footer>; add <header> only when the panel has its own title or toolbar.
+- For a bordered/elevated surface use <card-ui>; for an overlay use <drawer-ui> / <modal-ui>; for routed page layout use <admin-page> / <page-ui>. frame-ui is the bare layout only.
+- frame-ui fills its parent — give the parent a definite height (a flex/grid chain to a viewport height) or the section will not scroll.
+
+## Grid
+- For asymmetric column ratios, use [columns="N"] plus [span="M"] on the child that should be wider. Never set gridTemplateColumns via inline style in compositions — the component's responsive resolver sets it internally for @bp values; direct inline style bypasses that and reads as a local hack.
+- Canonical ratios: 1:1 → columns="2"; 2:1 → columns="3" + span="2"; 3:1 → columns="4" + span="3"; 3:2 → columns="5" + span="3"+"2"; 4:1 → columns="5" + span="4". Round unusual ratios (e.g. 7:5) to 3:2.
+- The default (no columns attribute) gives equal auto-columns flowing in a single row. Prefer the explicit numeric attribute for dashboard rows so the layout is predictable when items wrap.
+- For viewport-responsive layouts use `@bp` notation on [columns] and [gap]: columns="1 2@sm 4@lg" gives 1 column on xs, 2 from sm, 4 from lg/xl. Breakpoints (mobile-first, min-width): xs=0, sm=480, md=768, lg=1024, xl=1280. Unannotated value = base (smallest). Each @bp overrides upward until the next larger annotation takes over.
+
+## Header
+- Use <header-ui> as the top chrome row inside a PRIMITIVE container parent: <card-ui>, <drawer-ui>, <modal-ui>, <page-ui>. It is a CSS-only slot stub — no JS, no events. The parent's @scope rules drive layout and styling.
+- Compose with the default slot for the heading (typically <text-ui variant="title">) and slot="action" for trailing controls (button-ui, badge-ui). The slot vocabulary (icon / heading / description / action) is shared with <aside-ui> / <section-ui> / <footer-ui> per ADR-0009.
+- Do NOT substitute <header-ui> for bespoke shell-tier chrome. Inside <admin-content> / <admin-sidebar> use <admin-topbar>; inside <chat-shell> use <chat-header>; inside <editor-shell> use <editor-toolbar>. Those modules carry shell-specific slot vocabulary and CSS that <header-ui> does not. (admin-topbar.yaml codifies this explicitly.)
+- Do NOT wrap header-ui's children in <col-ui> or <row-ui>. The container parent's @scope already lays out default+icon+heading+description+action via slot vocabulary; extra layout primitives fight the chrome styling.
+- The `padding` attribute is a bare boolean — it enables default header padding, but the *scale* is set by the container parent's own `padding` prop. Do not pass numeric values.
+
+## Heatmap
+- Grid-cell heatmap visualization (calendar heatmap, density grid). Cells colored by value via OKLCH scale.
+- For continuous time-series use <chart-ui> with appropriate variant; heatmap is for grid-cell density.
+- Tooltip on hover shows cell value; click events emit cell coordinates.
+
+## Icon
+- [name] must be a registered Phosphor key (e.g. "house", "gear", "trash", "warning-circle"). Free-form names render empty. When unsure, default to a semantically obvious glyph (check, x, warning-circle, info).
+- Set [label] when the icon is the ONLY content of an interactive control (icon-only button); omit [label] when icon is decorative beside a text label. The host stamps role="img" + aria-label when [label] is set.
+- Use named [size] tokens (sm | md | lg) — free-form px / rem values ("32", "48") for anything beyond the row, e.g. empty-state hero icons; [size="md"] is the default for inline use. A denser or larger register comes from an ancestor [scale] tier, which the named tokens track automatically.
+- Use slot="icon" on parent primitives (<button-ui>, <badge-ui>, <alert-ui>, <list-item-ui>, <input-ui>, <nav-item-ui>, every chrome bar) — do NOT bare-render <icon-ui> beside text in a <row-ui> when the parent supports the [slot="icon"] convention.
+- Use [weight="fill"] for selected / active toggles, [weight="regular"] (default) for inactive. Do not mix weights in the same set; the visual inconsistency reads as a bug.
+- Set [tone] to carry semantic color independent of the parent's text color — e.g. a trend arrow icon that must read success/warning/danger regardless of surrounding row color. Leave [tone] unset when the icon should just inherit the ambient text color (the common case).
+
+## Image
+- Use for content images (illustrations, screenshots, user-uploaded photos). For icons use <icon-ui>; for embedded artifacts use <embed-ui>.
+- Set aspect-ratio attribute to lock dimensions and prevent layout shift during load.
+- For decorative-only images, set alt='' and aria-hidden='true' so screen readers skip them.
+
+## InlineEdit
+- Use inline-edit-ui for click-to-edit titles, draft names, table-cell text, breadcrumb labels — anywhere the user expects to edit text without opening a dialog.
+- inline-edit-ui IS form-participating (extends UIFormElement). Pair with a hidden <form> + name="..." to submit edits as a field.
+- Distinct from <input-ui> (always shows input chrome) and from <field-ui> (stacked label + input composition). inline-edit reads as text in the static state.
+- Listen to `change` event (detail.value, detail.oldValue) for commit; `cancel` for Escape. Default commit=blur saves on focusout + Enter.
+
+## InlineMessage
+- In-flow annotation under a form input (validation feedback, hint copy, inline confirmation). Severity via [variant] (info, success, warning, danger).
+- For overlay / banner-style notices use <alert-ui> instead; for transient toasts use <toast-ui>.
+- Place inside <field-ui>, <col-ui>, or <row-ui>; never as a page-level banner.
+- Do not nest a focusable child (button, link with action) — InlineMessage is non-interactive annotation.
+
+## Input
+- <input-ui> is the canonical single-line text input. The host IS the contenteditable surface — NEVER wrap a native <input>. The sole exception is type="password", which internally uses a real <input type="password"> for masking (per ADR-0025).
+- Wrap <input-ui> in <field-ui label="…" hint="…" error="…"> for the canonical stacked label / hint / error chrome. The inline [label] / [hint] / [error] props are also supported on the primitive for compact use.
+- Form participation is implicit via UIFormElement. Set [name] for FormData submission; [required] / [disabled] / [readonly] reflect; listen for `change` (blur or Enter commit) and `input` (per keystroke). `submit` event fires when Enter commits the value (used by <chat-composer>'s `composer-submit` forwarding).
+- For numeric input use [type="number"] with [min] [max] [step] [precision] [prefix] / [suffix] — this stamps a contenteditable surface + <button-ui> / <icon-ui> stepper column with ARIA spinbutton semantics. Read `el.valueAsNumber` for the parsed Number. Never substitute a native <input type="number">.
+- Inside <chat-composer>, the canonical inner input is <chat-input-ui> (chat variant subclass — adds the send button + model picker + paste-to-attach plumbing). The plain <input-ui> primitive ALSO fires a bubbling `submit` event on Enter (unconditional, no opt-in attribute); <chat-input-ui> simply builds on that semantic.
+
+## Inspector
+- Developer-tools pane for A2UI runtime state — composes <tabs-ui> + <code-ui> internally.
+- Binds to a <canvas-ui> / <a2ui-root> via value= or implicit selector; shows live doc JSON + rendered HTML + event log.
+- Use only in dev/debug surfaces; not for product UI.
+- Place in a right-pane inside <editor-shell-ui>'s editor-sidebar slot for editor-style inspector layouts.
+
+## IntegrationCard
+- Use <integration-card-ui> for one tile in an integrations grid. Set `provider` and `name` — both are required for analytics keys and the accessible name. Set `description` so users don't have to look the integration up externally.
+- `status` MUST be one of `available | connected | error | pending | coming-soon`. The button label and variant are DERIVED from `status` — never slot a <button-ui> directly in the card body. Use the `actions` slot for an overflow <menu-ui> with secondary actions like Reauthenticate or Disconnect.
+- When `status="error"`, set `error-message` — otherwise the user sees a Retry button with no context. The message renders below the description in danger-text color.
+- `logo` accepts a URL (containing `/`, renders as <img>) or a registered icon name (renders as <icon-ui>). Don't mix — one provider gets one logo source.
+- Group integration cards in <grid-ui columns="auto-fit"> or use <integrations-page-ui> (SPEC-063) for the canonical Settings-panel grid. Never nest <card-ui> around an <integration-card-ui> — it IS a card variant.
+
+## Kbd
+- Inline-only — content from innerHTML, typically one or two key labels.
+- In menu items, use the kbd= attribute on <menu-item-ui> instead of nesting <kbd-ui> directly.
+- Chord notation uses + between keys (Ctrl+Shift+P); platform-symbol variants ⌘⌥⇧ are fine.
+
+## Link
+- Use `<link-ui>` for navigation; use `<button-ui>` for actions. They are NOT interchangeable.
+- When wrapping action affordances that visually mimic links (e.g. 'Forgot password?' that triggers a reset flow), prefer `<button-ui variant="ghost">` over a fake `<link-ui>` — the affordance is semantically a button, just visually understated.
+- For inline-sentence affordances ('I agree to the [Terms] and [Privacy]'), nest `<link-ui>` directly inside `<text-ui>` so it inherits the paragraph's font / size / line-height.
+
+## ListWindow
+- ListWindow.items MUST be an array of plain objects OR scalars. Functions / DOM nodes / Promises are invalid.
+- ListWindow.render cannot be expressed in A2UI JSON — declarative authoring MUST use a <template> child (or default <list-item-ui> for objects with a text field).
+- When items.length > 200, the validator SHOULD recommend ListWindow over List to keep the DOM tractable.
+- ListWindow MUST have a defined height (via parent layout or style="height:..."). An unbounded-height windowed list defeats the windowing math.
+- ListWindow.item-size SHOULD be set when item heights are known and constant — the fast-path is significantly cheaper.
+- Do NOT nest ListWindow inside another scroll container; double-scroll containers break the IntersectionObserver math. Use one scroll boundary.
+- Do NOT use ListWindow for short lists (< 50 items). The windowing overhead exceeds the cost of rendering all rows. Use List for short lists.
+- Do NOT use for tabular data — that is Table with virtualized rows.
+
+## ListItem
+- Child of <list-ui> — one row of generic-list content.
+- For navigation lists use <nav-item-ui> inside <nav-ui>; for menu items use <menu-item-ui>; for tree rows use <tree-item-ui>.
+- Interactive list-items should have role='button' or be wrapped in <button-ui>; default is non-interactive.
+
+## List
+- Generic vertical list container — hosts <list-item-ui> or arbitrary children.
+- For interactive selection lists use <nav-ui> (single-select navigation) or <menu-ui> (action menu); list-ui is content display.
+- For data-grid / sortable / sticky-header needs use <table-ui> instead.
+
+## LoadingOverlay
+- <LoadingOverlay> MUST be placed inside a sized container with content (Card, Section, Table body, Chart). It absolutely positions against the nearest positioned ancestor. The parent's CSS must include `position: relative` (or any non-static positioning) — the component does not mutate parent layout styles.
+- Toggle <LoadingOverlay active> from consumer code while async work is in flight. The overlay applies aria-busy="true" to its parent while active; on dismiss, both inert and aria-busy are released.
+- The [delay] grace window (default 200ms) suppresses paint on fast-resolving loads. For server-rendered "definitely-slow" states (>1s known wait) consider [delay="0"] for immediate feedback.
+- Do NOT use as a page-level / viewport loader — use a dedicated route-loader pattern. <LoadingOverlay> is container-scoped.
+- Do NOT nest <LoadingOverlay> inside <Modal> or <Drawer> — those primitives own their own busy state. When they support it, pass [loading] to those directly.
+- Do NOT use <LoadingOverlay> to disable a form during submit — use <Button type="submit" loading> for the submit affordance.
+- The default slot accepts any busy indicator. When empty, a centered <Spinner size="lg"> is auto-stamped. Slot a <Skeleton> stack for placeholder-shaped loading; slot <Progress value=…> when the wait is determinate.
+
+## Mark
+- Use mark-ui for search-result match highlighting — wrap the matched substring in <mark-ui> within the surrounding text. Inline; preserves text flow.
+- variant=warning (default) is the conventional yellow-marker tone; info for brand-color highlights; success for "new since" / "added" emphasis; danger for "removed" / "deleted-line" in diff prose.
+- Distinct from <text-ui strong> (weight emphasis), <tag-ui> (block pill), <code-ui> (monospace). mark-ui is specifically the "visual rail behind matched text" use case.
+
+## MenuDivider
+- <menu-divider-ui> MUST be a direct child of <menu-ui>; a raw <hr> will render OUTSIDE the popover because <menu-ui> only hoists <menu-item-ui> and <menu-divider-ui> children via its direct-child selector.
+- Use to group items by semantic tier — primary actions → secondary → destructive (danger). Avoid leading / trailing dividers and consecutive dividers; they produce visual noise without grouping value.
+- Do not place a divider as the first or last child of <menu-ui> — the top / bottom popover padding already provides separation from the chrome.
+- Has no props, slots, or events. Treat as an inert separator with role="separator". If you need a labeled group, split into multiple <menu-ui> instances stacked, not custom content inside a divider.
+
+## MenuItem
+- <menu-item-ui> MUST be a direct child of <menu-ui>; do not place inside arbitrary containers or other components — <menu-ui> hoists items into its top-layer popover via a `:scope > menu-item-ui` selector that requires direct descendancy.
+- Always set a stable [value] — it is the only identifier surfaced on the parent's `action` event detail. [text] is the visible label; optional [icon] is a Phosphor icon name shown leading the label.
+- Use [variant="danger"] exclusively for destructive / irreversible actions (Delete, Remove). "Sign out" is NOT danger. Pair danger items with an explicit confirm flow (<modal-ui> destructive-confirm pattern) when the action cannot be undone.
+- Set [disabled] (not [hidden]) when an action is contextually unavailable — disabled items remain visible for affordance discoverability but skip roving focus + don't fire `action`.
+- Prefer [icon] + [text] props over slotted markup for consistency. Use slot="icon" / slot="text" only when you need custom markup (e.g. <avatar-ui slot="icon">, <kbd slot="trailing"> shortcut hint).
+
+## MenuLabel
+- <menu-label-ui> MUST be a direct child of <menu-ui>; like menu-item-ui and menu-divider-ui it is hoisted into the top-layer popover via <menu-ui>'s direct-descendant query — a label nested elsewhere renders outside the popover.
+- Use a label to NAME a group and <menu-divider-ui> to SEPARATE groups. The common pattern is one label at the top of each group with dividers between groups; avoid a label with no items beneath it.
+- Non-interactive: role="presentation", no [value], fires no events, and the menu's keyboard focus skips it. For a selectable row use <menu-item-ui>; for an unavailable action use <menu-item-ui disabled>.
+
+## Menu
+- <menu-ui> MUST have exactly one child with slot="trigger" (typically <button-ui>, but any focusable element works). Without it the menu cannot open. The trigger lives in light DOM; the items are hoisted to a top-layer popover on open.
+- Default slot accepts only <menu-item-ui> and <menu-divider-ui> children — no submenus, headers, or arbitrary content. Roving tabindex + Arrow / Home / End / Enter / Escape keyboard nav is built in.
+- Listen for the `action` event on <menu-ui> (or an ancestor — bubbles). Detail = { value, text }. Do NOT treat menu-ui as a value-holder; for single-select form input use <select-ui> instead. Menu fires actions, doesn't store state.
+- Use <menu-ui> for transient action surfaces (kebab / ⋯ row actions, workspace / user switchers, view-as toggles). For persistent side navigation use <nav-ui>; for inline (non-popover) command lists use <action-list-ui>; for searchable command palettes use <command-ui> inside <admin-command>.
+- Set [placement="top-start"] or [placement="top-end"] when the trigger sits near the bottom of the viewport (statusbar / footer menus); default [placement="bottom-start"] otherwise. Adjust [gap] (default 4px) only when chrome demands it.
+
+## Modal
+- Reflect modal visibility via the [open] boolean attribute on the host (open=true / open=false). Do NOT toggle [hidden], CSS display, or wrap in a sibling visibility container — modal-ui owns the native <dialog> lifecycle, focus trap, ::backdrop, and Escape-dismiss. Listen for the `close` event to react to dismiss.
+- Compose modal-ui with the same triplet as drawer-ui / card-ui: <header> (or [slot="header"]) + <section> (or default body) + <footer> (or [slot="footer"]). Set the title via [text] (which stamps the heading + aria-label) or a <span slot="heading">. Do not author your own close button unless using [permanent].
+- Use modal-ui (centered, interruptive) for short confirmations, destructive prompts, and transient previews — typically ≤2 form fields or a single decision. For edge-anchored multi-field detail editors and mobile sheets, use <drawer-ui> instead. The destructive-confirm-modal pattern lives at catalog/ui-patterns/app/destructive-confirm-modal/ as the canonical reference.
+- modal-ui is NOT the Cmd+K command palette. The palette is a bespoke shell-tier component (<admin-command> under <admin-shell>); do not model command palettes as modal-ui surfaces even though the visual is overlay-like. The palette owns its own keyboard / filter loop.
+- Use [size] presets (sm = 24rem | md = 32rem | lg = 48rem | xl = 95vw) to scale width. Do not override width with inline style or wrap modal-ui in a sizing container — the [size] attribute is the only supported width contract.
+
+## NavGroup
+- Composition: <nav-group-ui> MUST be a direct child of <nav-ui> (or standalone with explicit variant="section" outside a rail). Default slot accepts <nav-item-ui> children; do NOT wrap them in layout primitives — selection, keyboard, and the section-variant cascade all rely on direct descendancy.
+- Variant cascade: when parent <nav-ui variant="section">, this group inherits section styling (static kicker header, children always visible) via CSS — without touching its JS state. Set [variant="section"] explicitly only when there is no <nav-ui> parent, OR to override a primary-rail context.
+- Collapsibility: primary variant — [collapsible] (default true) toggles [open] via header click / Enter / Space; fires `group-toggle` event with detail {text, open}. When the parent <nav-ui> is collapsed to icon-only, the header opens a popover with this group's children instead. Section variant ignores [open] / [collapsible] (children always visible).
+- Decision rule: use <nav-group-ui> to group ≥2 related navigation links under one label inside <nav-ui>. For a single link, use <nav-item-ui> directly. For switching sub-views inside one page, use <tabs-ui> / <tab-ui>, never <nav-group-ui>.
+- Anti-patterns: do NOT nest <nav-group-ui> inside another <nav-group-ui> (flatten the hierarchy or split into two groups). Do NOT place non-<nav-item-ui> content in the default slot. Do NOT use it as a generic disclosure — for that use <accordion-ui> or <details>.
+
+## NavItem
+- Composition: <nav-item-ui> MUST be a direct child of <nav-ui> or <nav-group-ui>. Never wrap in <col-ui> / <row-ui> / <li> / <a> — the item is already a focusable, accessible link element; wrapping breaks selection, ARIA, and the section-variant CSS cascade.
+- Variant cascade: when an ancestor <nav-ui variant="section"> (or sibling-group with section variant) is present, this item inherits section styling (flat row, no reserved icon space when icon absent, left-edge selected accent) via CSS. Set [variant="section"] explicitly only when used standalone outside a section rail, or [variant="primary"] to override the cascade for a single highlighted item.
+- Selection: [selected] is set by the parent <nav-ui>'s select() method; do NOT set it on multiple items simultaneously. Provide [value] as a route or anchor; consumers listen for `nav-select` on <nav-ui> rather than per-item.
+- Decision rule: use <nav-item-ui> for a single navigable link (route or anchor). For an in-page view toggle, use <tab-ui>. For a popover menu action, use <menu-item-ui>. For an action button styled like a nav row, use <button-ui variant="ghost"> — not <nav-item-ui>.
+- Authoring options: default stamping renders icon+text+badge from attributes. Named slots `icon`, `text`, `trailing` are also supported for custom content (e.g. a `<kbd slot="trailing">⌘K</kbd>` shortcut hint on a command-trigger item — see the admin-shell playground). Do NOT nest <nav-item-ui> inside another <nav-item-ui>.
+
+## Nav
+- Composition: place <nav-ui> inside <admin-sidebar slot="leading"> wrapped in <section-ui> for app sidebars; inside an <aside data-subnav> with variant="section" for section / subnav rails; standalone on docs / auth pages. Children: <nav-group-ui>, <nav-item-ui>, optional <hr data-nav-divider>.
+- Variants: variant="primary" (default) — app sidebar; ResizeObserver collapses to icon-only ≤96px; collapsible groups open as a popover when collapsed. variant="section" — subnav rail; quieter chrome; optional [heading] kicker rendered via ::before.
+- Section-variant cascade (ADR-0015 § Nav consolidation): variant="section" on <nav-ui> cascades visually to direct <nav-group-ui> / <nav-item-ui> descendants via CSS `:not([variant])`. Children's JS state is NOT mutated; the cascade is purely visual. Explicit [variant] on a child always wins — use it to escape the cascade or style a standalone group/item.
+- Decision rule: if the user navigates AWAY (different page, route, or anchor) → <nav-ui>. If the user switches VIEWS within the same logical page → <tabs-ui>. Never use <nav-ui> as an in-page section switcher.
+- Anti-patterns: do NOT wrap <nav-ui> children in <col-ui> / <row-ui> — wrapping breaks selection bubbling + the variant cascade. Do NOT nest <nav-ui> inside <nav-ui>. The legacy 6-element family (<app-nav-ui> / <section-nav-ui> / <app-nav-item-ui> / <section-nav-item-ui> / <app-nav-group-ui> / <section-nav-group-ui>) was retired in ADR-0015 — only <nav-ui> / <nav-group-ui> / <nav-item-ui> remain.
+
+## Noodles
+- SVG connection lines between children with declared ports — bezier (default), step, or straight curves.
+- Place inside <canvas-ui> with port-declaring children (nodes); noodles draws connections between matching port refs.
+- editable attribute enables drag-to-connect interactions; default is render-only.
+- For data-flow visualizations only — for general-purpose lines/shapes use raw SVG.
+
+## NumberFormat
+- Use for read-only numeric display with locale-aware formatting. For numeric INPUT use <input-ui type=number>; for KPI big-number display use <stat-ui>.
+- [number-style=currency] REQUIRES [currency] to be set to a valid ISO 4217 code. Without it the element renders nothing rather than producing malformed output.
+- [number-style=percent] treats the [value] as a fraction (0.5 → 50%). To display 50 as '50%' pass value=0.5 OR keep [number-style=decimal] and append '%' manually.
+- Compact notation auto-defaults maximumFractionDigits to 1. Override only when extra precision is needed (rare for compact display — defeats the purpose).
+
+## OptionCard
+- Use <option-card-ui> for one-of-N choices where each option needs a heading + description, a leading icon, or both (onboarding personas, plan tiers, source pickers). Use <radio-ui> for dense forms with short labels and no descriptions. Use <segmented-ui> for compact horizontal single-select with short labels.
+- Group siblings by sharing the same [name] attribute — they auto-form a radiogroup. Form participation is implicit via UIFormElement: submits `name=value` with parent form. Wrap the group in <col-ui gap="2"> for default layout or <grid-ui> for [layout="tile"] hero pickers.
+- Set [checked] on the recommended / default option. Never leave the group with zero checked at first paint unless [required] is set and the form intentionally demands a deliberate choice.
+- Use [layout="tile"] only for hero pickers (3–4 options max) where the icon is a primary brand cue (plan tiers, role pickers). Use [layout="default"] (left-indicator) for everything else.
+- Put conditional follow-up inputs (a <textarea-ui> on "Other", a <select-ui> on "Custom") in the default slot — the spillover content auto-hides when the card is not checked. Do NOT duplicate this visibility logic in JS.
+
+## OtpInput
+- Use <otp-input-ui> for any fixed-length verification code (TOTP, email / SMS OTP, MFA enrollment) — NOT <input-ui type="number">. otp-input-ui provides per-digit focus management, paste-splitting of full codes, and the `complete` event that fires exactly once when all digits are filled.
+- Always set [autocomplete="one-time-code"] so iOS / Android keyboards surface inbound SMS codes via the platform autofill UI.
+- Listen for `complete` to auto-submit (fires exactly once per fill cycle), and `change` / `input` for live validation. Form participation is implicit via UIFormElement: [name] for FormData; [disabled] reflects.
+- Default [length=6]. Use [length=4] only for legacy 4-digit SMS codes and [length=8] for backup codes. Never compose two <otp-input-ui> side-by-side — use a single one with the right length.
+- Canonical placement: inside a <col-ui align="center"> beneath a description text. Do NOT wrap in <field-ui> — otp-input-ui has no label slot and visual centering is the canonical chrome.
+
+## Page
+- Top-level page container — wraps an entire route's content surface.
+- Inside <admin-shell-ui>, <chat-shell-ui>, or <editor-shell-ui>, use the shell's own body slot instead; page-ui is for standalone routes without shell chrome.
+- Hosts arbitrary children — no enforced child contract.
+
+## Pagination
+- Renders below tables, card grids, or list views for paginated data. Emits page-change events.
+- For cursor-based / infinite-scroll patterns use a custom load-more <button-ui> instead; pagination-ui is offset-based.
+- Page-number range auto-truncates with ellipsis for high counts; set siblings= to control visible window size.
+
+## Pane
+- pane-ui is a resizable / collapsible content panel. As a standalone primitive (no [side] attribute), it carries its own four-sided chrome and a right-edge resize grabber. As a horizontal-sibling child of a layout container (set [side="leading"] or [side="trailing"]), the chrome and grabber move to the inner edge so adjacent panes share a single seam.
+- Wrapped by <editor-sidebar slot="leading|trailing"> inside <editor-shell>, and by <admin-sidebar slot="leading|trailing"> inside <admin-shell>. The bespoke sidebar owns [collapsed] / [resizing] reflected state + localStorage persistence; the inner pane-ui owns the physical drag. Don't reimplement drag in the bespoke sidebar — delegate to <pane-ui resizable>.
+- Inner shape inside a pane-ui is the conventional <header> + <section> + optional <footer> slot pattern. Headers carry [slot="action"] button clusters; sections hold the navigator tree, inspector form rows, or other primary content.
+- For a standalone resizable two-pane layout (no shell), nest panes directly inside a flex row — both with [side]-typed chrome — and the resize handle will live on the seam between them. For a non-resizable summary pane (a fixed-width detail rail), drop [resizable] and pane-ui collapses to a static container.
+
+## PasswordStrength
+- Pair with <input-ui type=password> via a JS listener (input.addEventListener('input', e => meter.value = e.target.value)). The meter does NOT participate in form data — it is a display indicator.
+- The score is 0 (Weak) / 1 (Fair) / 2 (Good) / 3 (Strong). [min-score] sets the threshold for the `satisfied` boolean in score-change events. Use the boolean to gate a submit button.
+- Do NOT set value via setAttribute — value is JS-property only and never appears in rendered HTML (security: avoids leaking the password into the DOM).
+
+## PipelineStatus
+- Single updating pipeline status indicator — status pill with optional progress bar.
+- stage + status + message attributes drive the current display state.
+- For multi-step wizards use <stepper-ui>; for chronological history use <timeline-ui>; pipeline-status is a single current-state pill.
+- Renders inline — place inside toolbars, status bars, or agent message bodies.
+
+## Popover
+- <popover-ui> wraps a focusable trigger (slot="trigger", typically <button-ui>) + arbitrary interactive content (slot="content"). Never put bare text in slot="trigger" — it must be focusable so keyboard users can open the popover.
+- Decision rule vs adjacent surfaces. (a) For a list of action items use <menu-ui> instead — menu-ui is the specialized popover with role=menu + roving tabindex. (b) For read-only hover hints use <tooltip-ui>. (c) For centered focus-trapping dialogs use <modal-ui>. (d) For edge-anchored multi-field forms use <drawer-ui>. popover-ui is the GENERAL anchored surface for everything else (inline forms, color pickers, theme panels, export menus with non-action content).
+- Placement convention (ADR-0034): default `bottom` centers under the trigger — correct for wide pickers (calendar, color, date-range, filter forms). Use `bottom-start` for trigger-width menus (action lists, listboxes, breadcrumb overflow — popover width ≈ trigger width). Use `bottom-end` only when the trigger sits at the right edge of a container by construction (toolbar spillover). Use `top-*` when the trigger sits low in the viewport (statusbar). [gap] (default 4px) sets offset from anchor.
+- [trigger="hover"] is for non-essential disclosure only — never use it for popovers containing inputs, destructive actions, or anything the user must interact with via keyboard. Default [trigger="click"] for everything interactive.
+- Do NOT nest <modal-ui> or <drawer-ui> inside slot="content"; popovers are non-modal anchored surfaces, not dialog hosts. Stacking dialog surfaces inside a popover breaks focus management.
+
+## Preview
+- Use <preview-ui> to demonstrate ANY component or recipe — wrap the example markup once; it shows the live component and its copyable HTML source together. Prefer it over a bare <code-ui> snippet (which shows code but no render) or a bare rendered sample (which shows output but no copyable HTML).
+- Author the slotted markup as plain AdiaUI HTML with attributes only — no inline `style=`, no `<script>` wiring. If a sample needs inline styles to look right, the component is missing an attribute; fix the component, not the demo.
+- Side-by-side ([layout="split"]) is the default. Set [layout="stack"] for wide self-framing examples (a full card / shell / table reads cramped at half width). Use [code-first] when the code is the teaching point and the render is confirmation.
+
+## ProgressRow
+- Labeled progress row — composes a label + <progress-ui> + optional value display in one horizontal row.
+- For standalone progress bars without a row context use <progress-ui> directly.
+- Inside lists (multiple tasks with progress) stack multiple progress-rows in a <col-ui>.
+
+## Progress
+- Use for in-progress task feedback with known or indeterminate state. Value < 0 = indeterminate animation.
+- For labeled task lists (multiple progress bars with row labels), use <progress-row-ui> instead.
+- Spinner variant (variant='spinner') for circular loading indicators; bar variant default for linear.
+
+## QRCode
+- Set [value] for URLs / share links / plain text. The built-in encoder covers byte-mode UTF-8 up to QR version 10 (~150 chars at ECC-M, more at lower ECC levels).
+- For data that exceeds version 10, switch to a higher ECC level downgrade ([error-correction=L]) OR use a BYO encoder and pass the precomputed [matrix].
+- When QR sits over a non-white surface, set [background] to a solid color. White-on-image QR backgrounds are unreliable for scanners — quiet-zone contrast against the dark cells is the load-bearing visual.
+- The [margin] (quiet zone) defaults to 4 cells per QR spec. Smaller margins may scan on some devices but not others; do not go below 2.
+
+## RadioGroup
+- The canonical radio-group shape is <radio-group-ui label="…"> wrapping a set of bare <radio-ui label="…" name="…"> children — the wrapper supplies the group's accessible name (role=radiogroup + aria-labelledby); Column/Section cannot carry a role, so a bare Column of radios has no programmatic question↔group association.
+- Do not put the question text as a sibling Text node before a Column of radios — put it in radio-group-ui's own [label] prop instead.
+- radio-ui children keep their own [label] per-option; radio-group-ui's [label] is the shared question, not a per-option label.
+
+## Radio
+- Self-labeling widget — use the [label] attribute directly; do NOT wrap in <field-ui>. The widget renders its own label inline via CSS attr() pattern. For radio groups, the canonical pattern is <radio-group-ui label='…'> wrapping bare <radio-ui label='…'> elements sharing a [name=] — radio-group-ui supplies the group's accessible name (role=radiogroup + aria-labelledby); a bare Column of radios cannot (gh#729).
+- Use the [name] attribute to group radios — exactly one is selected per name group; form-associated.
+- For button-style single-select clusters (visually richer) use <segmented-ui> + <segment-ui> instead.
+
+## Range
+- Two-handle slider for selecting a range (min + max). Form-associated; emits two-value change events.
+- Different from <slider-ui> (single value) — use range when both endpoints matter.
+- Step attribute controls handle increments; min/max set the bound rails.
+
+## Rating
+- Star/icon-based ordinal rating input. Form-associated; emits numeric value 0..max via change events.
+- For thumbs-up/down agent feedback use <agent-feedback-bar-ui> instead — different semantics + visual.
+- max attribute sets the scale (default 5); allow-half attribute enables half-step granularity.
+
+## RelativeTime
+- Use for displaying a single timestamp as a relative phrase. Self-updates on a tick so the rendered text stays current; no parent re-render required.
+- Set [datetime] to an ISO 8601 string. Empty datetime renders nothing — do not stamp a relative-time-ui element until you have a timestamp value.
+- [update-interval=0] freezes the render (no tick). Use for historical timestamps that will never become 'just now' (audit-log rows, version-history entries from days+ ago).
+
+## RichText
+- Rich-text display + editor primitive. Renders paragraphs, lists, headings, and inline formatting; contenteditable when editable= is set.
+- Different from <text-ui> (single semantic block) — richtext handles multi-paragraph + inline marks.
+- For plain code use <code-ui> or richtext with code variant; for chat input use <chat-composer-ui>.
+
+## Row
+- Horizontal-stack flex container. Children flow left-to-right with token-driven gap.
+- Pair with <col-ui> for vertical layouts; both share the same gap-token contract.
+- Wrap attribute enables flex-wrap; default is nowrap.
+
+## Search
+- Search-input variant of <input-ui> with built-in search icon + clear affordance.
+- For command-palette interactions use <command-ui> (which composes search + menu).
+- Emits input events on each keystroke; debounce in the consumer for live-search.
+
+## Section
+- Use <section-ui> as the content body region inside a primitive container parent (<card-ui>, <drawer-ui>, <modal-ui>, <page-ui>) OR inside the body region of a bespoke shell-tier sidebar (<admin-sidebar> nav body — site/index.html and the admin-shell playground use this canonically). It is a CSS-only chrome stub for ADR-0009 slot vocabulary; the parent's @scope handles padding and borders.
+- `scroll` is a CONDITIONAL attribute. It makes section-ui the scroll container ONLY inside <card-ui> / <drawer-ui> / <modal-ui>. Inside <page-ui> and shell-tier hosts (<admin-shell>, <admin-page-body>) it is a no-op — those parents own their own scroll surface. Never nest <section-ui scroll> inside another scroll container (nested scroll is a UX anti-pattern).
+- Use `bleed` to remove section padding so children reach the card / drawer edges — typical for cover images, full-width charts, or media galleries (apps/saas/members.contents.html uses this pattern to wrap <table-ui raw>). Mix bleed and non-bleed sections in the same card to alternate edge-to-edge media with padded prose.
+- Do NOT substitute <section-ui> for bespoke shell-tier body regions. Inside <admin-page> use <admin-page-body>; inside <admin-content> use the bespoke children. <section-ui> is reserved for the primitive container chrome triad + the <admin-sidebar> nav body.
+- <section-ui> is the right place for layout primitives (<col-ui>, <row-ui>, <grid-ui>) that organize body content. Do NOT put those layout primitives inside <header-ui> or <footer-ui> — the parent's chrome scope already lays those rows out.
+
+## Segment
+- Child of <segmented-ui> — one selectable option button in a single-select group.
+- Different from <toggle-option-ui> (which is multi-select inside <toggle-group-ui>).
+- Selected state managed by parent <segmented-ui> via active attribute; do not set selected directly on segment.
+
+## Segmented
+- Single-select segmented control. Hosts <segment-ui> children; exactly one selected at a time.
+- For multi-select use <toggle-group-ui> + <toggle-option-ui> instead.
+- Use for view-mode switches (grid/list, light/dark) or short filter sets (3-5 options); for longer sets use <tabs-ui> or <select-ui>.
+
+## Select
+- Use <select-ui> for single-select with > 4 options or any list that benefits from a popover. Prefer <segmented-ui> / <radio-ui> when ≤ 4 visible options fit the row.
+- Compose options via native <option> / <optgroup> children — other tag names are silently ignored (per §225 v0.5.9) and warned once at runtime. Or set `.options` programmatically as an array of `{value, label, disabled?}` (grouped form: `{label, options:[…]}`).
+- Per-option visuals: give each <option> an `icon` (Phosphor name), `avatar` (image URL), or `mark` (Adia brand mark) — `<option value="light" icon="sun">`. Each row renders its glyph in the list AND the trigger reflects the SELECTED option's icon/avatar/mark (theme pickers, assignee/account switchers, workspace switchers). `mark` wins over `avatar`, which wins over `icon`; a host-level [mark]/[icon]/[avatar] is the fallback when the selected option carries none of the three. `mark` renders `<adia-mark-ui>` — a token-driven brand mark that inverts with the color scheme, so a workspace/app switcher doesn't need a static, scheme-locked logo URL.
+- For dynamic option lists rendered inside <editor-shell>, set the JSON via the [data-options] attribute — <editor-shell>'s wireSelects() finds select-ui[data-options], JSON.parses the attribute, and assigns `.options` on connect. Useful for static-HTML toolbars where JS hydration would be awkward.
+- <select-ui> owns its own label / hint / error chrome (via [label] / [hint] / [error] props). Only wrap in <field-ui> when you need to share the field-chrome stack with sibling inputs in the same form row group.
+- Enable [searchable] for > 10 options; add [free-text] only when unmatched values are valid (tag entry, email-with-suggestion). Use [multiple searchable] for multi-select rather than authoring a separate multi-select primitive.
+- For multi-select, set [multiple] — the trigger automatically renders <tag-ui> chips per selected option; the popover renders checkbox-style option rows where clicks toggle membership without closing. Form value is comma-separated under [name]. There is NO `<multi-select-ui>` tag — that name does not exist.
+- Multi-select bulk controls: [select-all] renders a "Select all" / "Clear" control above the option list; [clearable] adds a clear-all `x` affordance to the trigger. [max-chips] caps the visible chip count and renders "+N more". [min] / [max] gate form validity.
+
+## Skeleton
+- Use to placeholder content during loading. Shape via CSS sizing (width/height/border-radius); shimmer is automatic.
+- Compose multiple <skeleton-ui> blocks to mock the actual content shape (card-skeleton, row-skeleton, etc.).
+- For post-load empty states use <empty-state-ui> instead; skeleton is pre-load only.
+
+## SkipNav
+- Place as the FIRST focusable element on the page — inside <body> before any nav / shell chrome. Otherwise keyboard users still tab through the nav before hitting the skip link.
+- Target [#main] (or whatever id wraps the routed content). The target element should have tabindex="-1" so focus lands on it after the link is activated (otherwise focus may move to nothing perceptible).
+
+## Slider
+- Default mode is single-handle. Form-associated; emits numeric change events with detail.value.
+- For two-handle range selection (price filters, date ranges, audio range gates), set [dual] and use [lower-value]/[upper-value] instead of [value]. Form-data submits as "<lower>,<upper>" under [name]; change event detail carries {lower, upper}. Do NOT use <range-ui> — that primitive is a draggable numeric field, not a two-thumb range slider.
+- [step] controls increments for both single and dual modes. Constraint: in dual mode, [lower-value] ≤ [upper-value] is enforced on each setter; reversed values clamp to equal.
+
+## Spinner
+- Use <Spinner> for INDETERMINATE loading where the duration is unknown. For determinate progress (a known fraction complete), use <Progress> (linear) instead. For known-shape placeholder loading, use <Skeleton>.
+- When a Spinner is inside a Button, set tone="current" so it matches the button label color, and disable the button while the operation is in progress.
+- When overriding [label], use a present-progressive verb form ("Loading", "Saving", "Uploading"). Never use "Spin" or "Wait" — they describe the visual, not the operation.
+- Do not nest <Spinner> inside <Skeleton>; they are siblings (two different loading idioms), not parent/child.
+- Do not stack multiple sibling <Spinner>s in the same viewport region. Use one parent-level Spinner instead — multiple spinners add visual noise without extra information.
+
+## Stack
+- Overlay/layer stacking container — children occupy the same area, stacked on the z-axis.
+- Use for overlapping content (image + overlay, badge-over-avatar, drop-shadow stacks).
+- Do not use for vertical content flow — that's <col-ui>. Stack-ui is overlap-only.
+
+## Stat
+- Use for prominent metric/KPI displays inside dashboard cards. Value + label + optional delta indicator.
+- For inline percent/progress displays use <progress-ui>; stat is for standalone metrics, progress for completion bars.
+- Delta indicator uses positive/negative semantic tokens; pass change= attribute with sign.
+
+## StepProgress
+- Compact step indicator — N dots/segments showing current step out of total.
+- Different from <stepper-ui> (labeled, expanded) — step-progress is dense and label-free.
+- For multi-task progress bars (multiple labeled rows) use <progress-row-ui> stack.
+
+## StepperItem
+- Child of <stepper-ui> — one numbered step with label + complete/current/upcoming state.
+- State driven by parent's active-index; do not set state directly on stepper-item.
+- For chronological events (no completion semantics) use <timeline-item-ui> instead.
+- Set [disabled] to phase-gate a step out of click/keyboard reach without changing [status].
+
+## Stepper
+- Hosts <stepper-item-ui> children with a parent active-index driving complete/current/upcoming states.
+- Use for wizards, onboarding flows, multi-step forms.
+- For read-only event history use <timeline-ui>; stepper requires forward progress semantics.
+- Add [interactive] only when the host permits jumping to a step out of order; leave absent for a linear wizard the host advances programmatically.
+- Listen for [step-request] and call preventDefault() to veto a navigation conditionally (e.g. block a phase the app has not unlocked); set [disabled] on a stepper-item-ui to phase-gate it out of reach unconditionally.
+
+## Stream
+- Renders an AsyncIterable<string> as streaming text — canonical for LLM token streaming.
+- Place inside <chat-thread-ui> message bodies for LLM responses; standalone for log tailing.
+- pace attribute controls typewriter-effect speed; hide-cursor disables the blinking caret.
+- For static (post-stream) display use <text-ui> or <richtext-ui>; stream-ui assumes live token feed.
+
+## Swatch
+- Use to display a single color sample with optional label. For interactive color picking use <color-picker-ui>.
+- Inside design-token displays or palette grids; not for general decoration.
+- Color value accepts hex, rgb, hsl, or oklch; oklch preferred for AdiaUI token alignment.
+
+## Swiper
+- Horizontal slide carousel with touch + arrow nav. Hosts arbitrary children as slides.
+- For tab-switched peer views use <tabs-ui>; swiper is for content browsing, not panel switching.
+- Set autoplay attribute for timed-rotation; otherwise user-driven only.
+
+## Switch
+- Self-labeling widget — use the [label] attribute directly; do NOT wrap in <field-ui>. The widget renders its own label inline via CSS attr() pattern. For settings rows (label-left, switch-right), put the descriptive text in switch-ui's own [label] attribute; do not introduce a field-ui wrapper. For descriptive helper text below the switch, use <text-ui variant='caption'> as a sibling — not field-ui's hint slot.
+- Binary on/off only — no third state. For tri-state controls use <check-ui> with [indeterminate].
+- Use for settings toggles, feature flags, mode switches; for form gates / consent / multi-select use <check-ui> instead.
+
+## TableToolbar
+- Pair <table-toolbar-ui> with <table-ui> via [for="<table-id>"] (or rely on first-sibling fallback when both are inside the same parent). One toolbar per table. Do NOT also use <card-ui>'s <header> on the same card — that produces a doubled chrome row.
+- All four affordances (search, filter, sort, columns) default ON. Opt out individually via [no-search] / [no-filter] / [no-sort] / [no-columns]. The previous [searchable] / [filterable] attributes are deprecated — do NOT emit them.
+- Place the toolbar ABOVE the <card-ui> containing the table-ui, or use [variant="card"] when standing alone outside a card-ui parent (the variant wraps the toolbar in card-style chrome).
+- Use slot="action" (or [slot="actions"]) for trailing primary buttons (Invite, Export, +New). Use [text] / [count] props for the left cluster, or slotted [slot="title"] / [slot="count"] when content is markup (a <span> + <badge-ui>, etc.).
+- Listen for toolbar events (`search`, `filter-change`, `sort-change`, `columns-change`) only to mirror state to URL / persistence / analytics. The toolbar already wires its changes into the bound table — you don't need to manually update the table.
+
+## Table
+- Canonical composition: wrap <table-ui> in <card-ui><section bleed> for edge-to-edge tables. The [bleed] removes section padding so columns span the full card width (see apps/saas/members, billing, admin-dashboard).
+- Pair with <table-toolbar-ui for="<table-id>"> for any table that needs search / filter / sort / columns visibility. Do NOT re-implement those affordances in the card header — the toolbar auto-wires search/filter/sort/columns changes into the bound table.
+- Cells truncate single-line by default (v0.6.21 §403 truncate-default). Opt out per-table with [wrap] for whole-table multiline, or per-cell with [data-wrap] on a single column / cell.
+- [raw] is a visual-and-lifecycle chrome reset for consumer-owned body markup — render()'s early return (`if (this.raw) return;`) is unconditional: no header injection, no .data/.columns reconciliation, no empty/loading overlays, no aggregation or pagination footers, even if .columns and .data are set. Reach for it only when the consumer authors 100% of the body (spreadsheet / inline-edit style patterns wrapping a native <table>) — never to "keep the data lifecycle but skip demo seeding."
+- Listen for the `sort` event with detail.key + detail.dir (NOT .column / .direction). `cell-click` detail carries {key, row, value, dataIndex}. Per ADR-0027, table-ui composes check-ui, icon-ui, progress-ui, pagination-ui, skeleton-ui, badge-ui — consumer pages must explicitly import the ones they use.
+- For large datasets (100+ rows), use [paginate="N"] to limit rendered rows and add a pagination bar. [virtual] is NOT a recognized prop and is silently ignored — there is no DOM-level virtual scrolling in table-ui. [paginate] is the supported performance mechanism. Wire [paginate] with optional [search] and the `page` event for server-driven pagination.
+
+## Tab
+- <tab-ui> only renders inside <tabs-ui>. Never use it standalone. The parent reads each tab's [text] + [icon] + [value] to render the button strip; the tab's default slot is the panel content that the parent auto-hides when inactive.
+- [value] is required and must be unique among siblings — the parent <tabs-ui> matches its own [value] against each <tab-ui>[value] to decide which is active. [text] is the visible button label; optional [icon] is a Phosphor icon name shown leading the label.
+- Use the default slot for panel content. Inactive <tab-ui> children are auto-hidden by the parent's [hidden] toggling; do NOT set [hidden] yourself unless you want to remove the button from the strip entirely (i.e. a temporarily-disabled tab whose strip button shouldn't render at all).
+- Use [disabled] to keep a tab visible in the strip but non-selectable. Do not pair <tab-ui> with <button-ui> wrappers — the strip button is parent-rendered. Do not nest <tab-ui> inside another <tab-ui>.
+
+## Tabs
+- Decision rule: use <tabs-ui> when switching VIEWS within the same logical page (no route change, no URL change). For navigating AWAY (different page / route / anchor), use <nav-ui> instead. For a form-control segmented selector that returns a value, use <segmented-ui>.
+- Children of <tabs-ui> MUST be <tab-ui> elements. The button strip is rendered from each child's [text] + optional [icon]; the parent auto-toggles [hidden] on inactive <tab-ui> children. Do not place arbitrary markup directly inside <tabs-ui> — wrap it in <tab-ui>.
+- Canonical placements: inside <card-ui>'s <header> for in-card section switching; inside <editor-canvas-toolbar> for editor sub-views (see the editor sub-views recipe in patterns-recipes.md); or standalone as an in-page switcher. When standalone, wire sibling <div data-view="…"> panels via the `change` event (detail.value); for tabs whose content lives inside the <tab-ui> child, the auto-hide handles visibility.
+- Set [value] to the initially active tab. If omitted, the first non-disabled <tab-ui> becomes active on connect. Set [orientation="vertical"] for left-rail tab strips.
+- Variant caveat: only [variant="bordered"] is implemented (adds a subtle divider). [variant="underline"] is widely used in source but is equivalent to default (no-op). [variant="pills"] and [variant="segmented"] are declared in the enum but NOT styled — do NOT emit them; for a form-style selector use <segmented-ui>.
+
+## Tag
+- Use <tag-ui> for INTERACTIVE / DISMISSABLE labels — filter chips, autocomplete tokens, user-managed labels. Tag-ui fires a `remove` event when [removable] is set. For READ-ONLY status flags (counts, Beta / New / Deprecated markers, notification dots) use <badge-ui> instead — badge has no remove event and includes the [status] shorthand.
+- Set [removable] and listen for the `remove` event (detail: {text, value}) when the tag represents a user-applied filter or selection that can be cleared.
+- [variant] maps to semantic state of the underlying record: success = active / approved, warning = pending, danger = blocked / error, info = neutral-emphasis. Default (no variant) for unlabeled categories.
+- Use [size="sm"] for inline-with-text contexts (doc page headers, table cells, badges next to titles); [size="md"] (default) for filter-bar chips and standalone tag rows.
+- Group multiple tags inside a <row-ui gap="2"> — never stack them vertically; vertical lists of dismissable items are an <action-list-ui> use case, not <tag-ui>.
+- A family-less <tag-ui text="…"> (no [variant], no [tone]) renders the high-contrast solid pill by default (gh#794). In dense tables, tight metadata rows, or citation/footnote strips where many tags sit close together, set [tone="muted"] to keep the quieter tinted look instead — a wall of solid pills reads as visual noise there (gh#778).
+- A family [variant] (info/success/warning/danger/primary) with no [tone] renders the tinted-container look by default (gh#864). Set [tone="solid"] for a saturated status stamp instead.
+
+## TagsInput
+- Use <tags-input-ui> for OPEN-SET free-form token entry — labels, keywords, email recipients, comma-separated lists. For CLOSED option sets (pick N from a fixed list), use <select-ui multiple> (SPEC-040) — that primitive gates the value against `options[]`.
+- `TagsInput.value` MUST be a string array. Pass `["a","b"]`, not the comma-joined string `"a,b"`. The host parses string-form `value` attributes as JSON; non-array shapes throw `invalid`.
+- `delimiter: "enter"` disables in-line character commits; only the Enter key (or programmatic `addToken`) commits. Use this when the token grammar legitimately includes the default `,`.
+- `unique: true` (default) silently coalesces accidental duplicate adds. Do NOT emit `invalid` for those — the contract specifies silent dedup for ergonomic typing.
+- `validateFn` is a JS property, NOT serializable in A2UI JSON. Wire validators post-mount via DOM scripting; A2UI authors should not expect to declare a validator in the JSON payload.
+- Chips are rendered automatically from `value`. Do NOT slot individual <tag-ui> children manually — that decouples the rendered DOM from the form value and breaks Backspace removal.
+
+## Text
+- Use for typographic content with semantic role (heading, body, label, caption). Variant attribute sets the role.
+- For inline-flow rich content with multiple paragraphs, use <richtext-ui> instead.
+- Heading variants (h1, h2, ...) are not auto-tagged — set the role explicitly via variant.
+
+## Textarea
+- <textarea-ui> is the canonical multi-line text input. The host IS the contenteditable surface — NEVER use a native <textarea> (banned by ADR-0025).
+- Wrap <textarea-ui> in <field-ui label="…" hint="…" error="…"> for the canonical labeled stack. The inline [label] / [hint] / [error] props are also supported on the primitive for compact use.
+- Form participation is implicit via UIFormElement. Set [name] for FormData submission; [required] / [disabled] / [readonly] reflect; listen for `change` (on blur after value change) and `input` (per keystroke).
+- Use [rows] to set initial height (default 3) and [resize] (vertical | horizontal | both | none; default vertical) to control user resize. Never substitute a native <textarea> just to get rows / resize.
+- Enter (without Shift) dispatches a bubbling `submit` event; Shift+Enter inserts a newline. This is unconditional — there is no opt-in/opt-out attribute. For chat composer surfaces wrap inside <chat-composer> + <chat-input-ui> (which adds the send button + model picker + paste-to-attach plumbing on top of the same Enter→submit semantics).
+
+## ThemeProvider
+- Wrap a client-mounted surface root (SPA shell, embedded app, dynamic mount) in <theme-provider> so it self-provides the AdiaUI foundation — no <head> stylesheet link required.
+- For multi-page / top-level pages, prefer a render-blocking <link rel="stylesheet" href=".../web-components.min.css"> in <head> instead — cacheable across navigations, styled on the first frame. <theme-provider> and the link deliver byte-identical CSS, so they coexist.
+- Theme the wrapped subtree with theme="ocean" (a named preset) and/or scale="verse|prose" (compact / long-form register) — the provider adopts the matching opt-in layer on demand. The base foundation is OS light/dark automatically. Keep <theme-provider> at/near the mount root — display:contents means an ancestor "> " child selector will not reach its children.
+
+## TimePicker
+- `<time-picker-ui>` is the canonical standalone time-of-day picker. Per ADR-0025 NEVER wrap a native `<input type="time">` — segments are contenteditable spans + ElementInternals provides form participation.
+- `value` MUST be ISO 8601 time `HH:mm` or `HH:mm:ss` (24-hour), or empty string. Localized formats (e.g. "9:30 AM") are not accepted; display formatting is derived from `hour-cycle` regardless of how the value is stored.
+- `step` is in seconds. 60 = minute precision (default); 900 = 15-minute precision (meeting-time common); 1 = second precision (requires `precision="second"`).
+- `precision="second"` exposes the seconds segment AND emits `HH:mm:ss`. Default `precision="minute"` emits `HH:mm`.
+- `hour-cycle` overrides locale-derived behavior. Set explicitly (`h12` / `h23`) when the surface needs a specific cycle (cron editors, log queries, system surfaces).
+- For datetime selection use `<datetime-picker-ui>` (SPEC-038) — it composes this primitive as its time pane.
+
+## TimelineItem
+- Child of <timeline-ui> — one chronological event with timestamp + content + optional icon dot.
+- Different from <stepper-item-ui> (process steps with completion state) — timeline-item is event history.
+- Order is DOM-order — no auto-sort by timestamp.
+
+## Timeline
+- Use for chronological event lists (audit log, activity feed, version history).
+- Hosts <timeline-item-ui> children only.
+- For multi-step processes with progress state use <stepper-ui> instead; timeline is read-only history.
+
+## Toast
+- Single ephemeral notification item — auto-dismissing or manually-closable.
+- Typically posted into <feed-ui> via UIFeed.post(...); for inline persistent alerts use <alert-ui> instead.
+- Variant maps to severity (info, success, warn, error); same tokens as <alert-ui>.
+
+## TableOfContents
+- Use for in-page section navigation. Pair with a sticky container in an aside / right rail for the docs-site outline pattern.
+- Default scans the toc-ui's parent for h2/h3 headings. Set [target] to a CSS selector for a specific container; set [headings] to a comma-separated tag list (e.g. h1,h2,h3) for different depth coverage.
+- Headings missing an [id] receive an auto-generated slug from their text content. Existing ids are preserved.
+- Smooth-scroll on click is handled by the global `scroll-behavior: smooth` in resets.css (gated by prefers-reduced-motion). Do NOT add per-toc-ui smooth-scroll JS — the global wins.
+
+## ToggleGroup
+- Multi-select button cluster — hosts <toggle-option-ui> children, each independently toggleable.
+- Different from <segmented-ui> (single-select) — toggle-group emits a SET of active values.
+- Use for filter chips, multi-flag toggles, day-of-week pickers; for binary on/off use <switch-ui>.
+
+## ToggleOption
+- Child of <toggle-group-ui> — one independently-toggleable button in a multi-select cluster.
+- Different from <segment-ui> (which is single-select inside <segmented-ui>).
+- Active state controlled via the toggle-option's own active attribute (independent of siblings).
+
+## ToggleScheme
+- Place toggle-scheme-ui in the shell topbar's trailing action cluster — slot="action" inside <admin-topbar slot="header"> of <admin-content>. It is a persistent, app-wide preference control; never put it in a sidebar footer / <admin-statusbar>, which hosts user-account items only.
+- Stores user override in localStorage and writes color-scheme inline-style to the target; falls back to prefers-color-scheme if no override is set.
+- Singleton per page — placing more than one in DOM creates conflicting writes to the same target.
+
+## ToolbarGroup
+- Child of <toolbar-ui> — clusters related action buttons with token-driven internal gap.
+- Separate clusters with <divider-ui> siblings inside <toolbar-ui>.
+- Do not nest toolbar-groups; flat hierarchy only.
+
+## Toolbar
+- Horizontal action bar — hosts <button-ui>, <toolbar-group-ui>, and <divider-ui> children.
+- Cluster related buttons inside <toolbar-group-ui> with <divider-ui> separating clusters.
+- For navigation use <nav-ui>; for modal/popover action bars use the modal's footer slot. Toolbar is for inline action bars within content regions.
+
+## Tooltip
+- Use <tooltip-ui> to label icon-only <button-ui> elements (text="Save" on a save-icon button, etc.) and for short descriptive hover hints. Never use it for content the user must read carefully (the bubble is transient + non-focusable).
+- Never place INTERACTIVE children inside <tooltip-ui> — it is a read-only hint, not a surface. If the user must click or type, use <popover-ui> instead. Tooltips never receive keyboard focus.
+- [follows="pointer"] mode requires [for] pointing at a <chart-ui> or <heatmap-ui> [id]; the tooltip subscribes to that target's `chart-hover` / `chart-leave` events to render data-viz annotations that track the cursor. Without [for] the tooltip renders nothing in pointer mode.
+- Set [delay=0] only for high-frequency exploratory surfaces (sparkline ticks, chart hover). Keep the default 400ms delay elsewhere to avoid hover noise.
+- [indicator] (dot | line | dashed) is meaningful only in pointer mode for per-series swatches. Omit it or leave default "none" for text-mode tooltips.
+
+## TourStep
+- Single step inside <tour-ui>. Declares target (CSS selector) + title + body content.
+- target is a CSS selector (e.g. "#dashboard", ".filters button"), NOT a bare ID. Use the # prefix.
+- Renders nothing on its own — tour-ui orchestrates the popover stamping when the step becomes active.
+
+## Tour
+- Use tour-ui for spotlight-driven product tours / walkthroughs — sequence of steps each targeting a CSS-selector-resolved element.
+- Children are <tour-step target="..." title="..."> with body content as the default slot. tour-ui reads them in DOM order.
+- Set [auto-start] for first-run flows (paired with [storage-key] so it only shows once). Otherwise call .start() programmatically from a "Take the tour" button.
+- Distinct from <onboarding-checklist-ui> (persistent setup todo-list, user-paced) and <tooltip-ui> (single hover hint, no orchestration).
+- Listen to `tour-finish` for "user completed the tour" analytics; `tour-skip` for "user opted out". Both fire once per session.
+
+## TreeItem
+- <tree-item-ui> MUST be a direct or nested descendant of <tree-ui>. It is not a standalone primitive — outside a <tree-ui> parent, selection / expansion / keyboard nav don't wire.
+- Provide a stable [value] attribute on every <tree-item-ui> that consumers will select. The `tree-select` event's detail.value is the identifier downstream code reads to know which node was picked.
+- Use [open] to pre-expand branch nodes on initial render. Do NOT set [selected] declaratively on more than one item — the parent <tree-ui> manages selection. The host listens for click / Enter / Space / ArrowRight (expand) / ArrowLeft (collapse) per WAI-ARIA tree-view APG.
+- Use [icon] (Phosphor name) for affordance (folder / file / component icons); use [badge] for counts or short status labels (§184 v0.5.5).
+- Nest further <tree-item-ui> in the default slot only — no <list-item-ui>, <nav-item-ui>, or arbitrary content inside a tree row. The caret is auto-stamped when the row has nested tree-item-ui children.
+
+## Tree
+- Use <tree-ui> only when data is hierarchical with arbitrary nesting AND a single selected node is meaningful. For flat lists use <list-ui>; for flat sidebar navigation use <nav-ui>; for one-level collapsible groups use <accordion-ui>.
+- Canonical mount: inside <editor-sidebar slot="leading"> → <pane-ui side="leading" resizable> → <section> → <tree-ui id="…"> as the structure / navigator pane of the three-pane editor shell. Pair with a <header> in the same pane (e.g. "Structure", "Layers", "Files").
+- Direct children of <tree-ui> MUST be <tree-item-ui>. No other element types in the default slot. <tree-ui> manages single-selection across the whole subtree and implements WAI-ARIA tree-view keyboard navigation (Arrow keys, Enter / Space, Home / End).
+- Listen for `tree-select` on the <tree-ui>, NOT on individual rows — selection is managed by the parent and bubbles once. Detail = {item, text, value, ctrlKey, metaKey, shiftKey}.
+- Per ADR-0027, <tree-ui> composes <icon-ui> (for carets) but does NOT auto-import its children. Consumer pages must explicitly import both <tree-ui> and <tree-item-ui>.
+
+## Upload
+- File-upload input with drop zone + browse button. Form-associated; emits file-list change events.
+- Multiple attribute enables multi-file selection; accept= constrains file types.
+- For agent chat attachments use <chat-composer-ui>'s built-in upload affordance instead.
+
+## VisuallyHidden
+- Wrap text that screen readers need but sighted users do not — icon-only-button labels, contextual disambiguation ("Edit profile" inside a row whose visible button just says "Edit").
+- Distinct from [hidden] / display:none (hides from EVERYONE) and from aria-label (replaces visible text). Use <visually-hidden-ui> when both visible AND invisible text need to coexist on the same element.
+
+## AdminRoster
+- Use <admin-roster-ui> for the canonical persona-switch list in an
+agent-admin surface. Supply the `personas` array; the composite
+owns menuitemradio semantics and the active-row check glyph.
+
+- Listen for `persona-change` to swap the bound `SettingsStore`
+(CHAT-HARNESS §Interfaces 5) — a genuine store reference change
+resets the conversation + open surfaces; this composite never
+touches the store itself.
+
+
+## AdminSettings
+- Use <admin-settings-ui> for the canonical per-persona settings
+pane. Set both `persona` and `store` as JS properties — neither
+has an attribute form.
+
+- Never author per-kind branches around this composite (a
+prompt-section-specific control, a skill-specific control, …) —
+`KNOWN_KINDS` is display grouping only; a seventh kind must render
+through the SAME entry row with zero new code.
+
+
+## AgentAdmin
+- Compose `<agent-admin-ui>` with bespoke `<admin-roster-ui>` +
+`<admin-settings-ui>` + `<chat-shell>` children (chat-shell WITHOUT
+`proxy-url` — external mode; this composite drives it). Set
+`personas` as a JS property.
+
+- Never bind `<chat-shell proxy-url>` inside `<agent-admin-ui>` — the
+composite drives the chat pane itself via `wireAgentEvents`; a
+`proxy-url` would double-drive turns.
+
+
+## BillingOverview
+- BillingOverview.account is REQUIRED. The composite is meaningless without an account snapshot; emitting BillingOverview with null account and no data-stream-src renders the empty state.
+- account.status MUST be one of `active` | `trialing` | `past_due` | `canceled` | `paused`. Unknown values render neutral chrome.
+- account.dunning is REQUIRED when account.status is `past_due` (otherwise the dunning banner cannot render). Shape: `{amount, currency, dueAt, cardLast4?, reason?}`. The composite stamps `<alert-ui pattern="dunning">` per SPEC-006.
+- account.plans is REQUIRED when [variant] is `full` (otherwise the plan-picker section has nothing to render). Omit `plans` when [variant] is `compact` or `enterprise` to skip the plan-picker section.
+- account.paymentMethods is forwarded verbatim to <payment-method-list-ui>; account.invoices is forwarded verbatim to <invoice-history-ui>. Their shapes are owned by SPEC-010 and SPEC-008 respectively.
+- BillingOverview MUST NOT be nested inside Modal or Drawer. The dashboard is a route, not a modal — Modal traps focus + clips on long content; this surface is designed for full-page layout.
+- Wire one listener to `account-action` instead of subscribing to every child primitive's event. The composite normalises plan-action / payment-action / invoice-action / dunning-action into the single bubbling event.
+
+## InvoiceDetail
+- InvoiceDetail MUST set `invoice` OR `data-stream-src`. Neither produces the empty state but cannot be the submission state for a billing surface.
+- invoice.lines[] MUST contain at least one row with `description`, `qty`, `unitAmount`, `amount`. Empty lines arrays render the lines table empty-state row, not the host empty state.
+- invoice.total MUST equal subtotal + tax − (discount or 0). The composite renders the host-supplied total verbatim; consumers are authoritative on rounding rules per locale (SPEC-007 OD-001).
+- invoice.status MUST be one of draft / open / paid / past-due / void. Unknown statuses render the default badge variant + a one-shot console.warn.
+- InvoiceDetail MUST NOT be nested inside Modal or Drawer. Invoices are routes, not modals — Modal traps focus + clips on long content; the composite is designed for full-page layout. Use `<a href="/invoices/{number}">` instead.
+- Slot ALL header actions explicitly via `slot="header-actions"` — the composite NEVER stamps a default toolbar (SPEC-007 OD-002). Action sets vary across products; default is too opinionated.
+
+## InvoiceHistory
+- InvoiceHistory.invoices MUST be a non-empty array on commit. Empty arrays render the empty-state (no rows).
+- invoices[].status MUST be one of "draft" | "open" | "paid" | "past-due" | "void". Unknown values fall back to a neutral badge variant.
+- InvoiceHistory MUST NOT receive a `columns` prop — columns are owned by the composite. Consumers needing custom columns should compose <table-ui> directly with their own column array.
+- `hrefPattern` is a string template with `{number}` interpolation. Consumers needing dynamic resolution (query-strings, function- based routes) should preventDefault on `invoice-row-click` and route themselves.
+- Pair with `InvoiceDetail` (SPEC-007) at the route resolved by `hrefPattern` so the row-click destination exists.
+
+## PaymentMethodForm
+- PaymentMethodForm SHOULD be wrapped in a <Form> so its form-value (the resolved token) is delivered on submission. Standalone use requires the consumer wire `tokenize()` from a custom submit handler.
+- PaymentMethodForm MUST NOT receive a `value` prop carrying raw card digits. The form value is the tokenized output; raw card digits live only inside the form's sub-fields and are never mirrored to `value`.
+- PaymentMethodForm SHOULD only be used in test / demo / non-PCI surfaces. Production card-capture flows MUST tokenize via a real payment processor (Stripe Elements, Braintree, Adyen) and consume only the resulting token — this primitive is the form chrome + structured validation, not a tokenization provider.
+- Wrapping PaymentMethodForm inside <Field> duplicates the label and corrupts the grid layout. PaymentMethodForm IS a field group; the host carries `aria-label` directly.
+- `countries` SHOULD list every ISO 3166-1 alpha-2 code your product accepts. Empty arrays fall back to a default short list (US, CA, GB, DE, FR, AU) suitable for early-stage demos only — production deployments should set this explicitly.
+
+## PaymentMethodList
+- PaymentMethodList.methods MUST be an array. Empty array is valid and renders the empty-state.
+- methods[].id MUST be unique within the list. Duplicate ids cause row collision at diff time.
+- Exactly one record in `methods` MAY have `default: true`. If none does, the primitive marks the first row as default on connect.
+- methods[].brand SHOULD be from the enumerated set (visa | mastercard | amex | discover | jcb | unionpay | diners | paypal | apple-pay | google-pay | ach | sepa). Unknown brands fall back to a generic credit-card mark.
+- methods[].type MUST be `card`, `bank`, or `wallet`. Drives the brand-icon fallback when `brand` is unknown.
+- `value` wins on conflict with methods[].default — if both are set and disagree, value is the source of truth and the primitive emits `change` to reconcile.
+- Mutations are events, not props. Wire `change` / `add` / `remove` / `select` to your billing API; the primitive does NOT write to the underlying data source.
+
+## PlanPicker
+- PlanPicker.plans MUST be a non-empty array on commit. Empty arrays render the empty-state but cannot be the submission state.
+- At most ONE plans[] record may carry `recommended: true`. Two recommended plans are visually ambiguous and defeat the treatment's purpose.
+- `current` MUST match a plans[].id or be empty. Unknown ids fail silently — no anchor row renders, no current-state contextualization on siblings.
+- plans[].prices.monthly is REQUIRED on every record. annual is optional; if absent and cycle="annual" the card renders the monthly price with the annual cycle suffix and no `note`.
+- `cycle` MUST be `monthly` or `annual`. Other values are coerced to `monthly` and a one-shot console.warn fires.
+- Use `layout="list"` for in-app settings panels where the picker sits inside a <card-ui> and width is constrained. Use the default `layout="grid"` for marketing pricing pages.
+- Wire `select` (not `change`) to the actual commit handler — change fires on selection without commit (keyboard focus traversal, programmatic value-set); select fires when the user clicks the CTA inside a card.
+
+## ChatComposer
+- chat-composer is the bespoke replacement for legacy <chat-input-ui data-chat-input> inside <chat-shell>. Place an inner <chat-input-ui> as the primary input — it emits `submit` on Enter without Shift (unconditional; delegated from the inner textarea).
+- The host listens for 'composer-submit' on the composer (not on the inner input). The event detail mirrors the inner submit event so existing handlers Just Work.
+- Default slot holds a single <chat-input-ui> child; trailing/attach/leading slots host action buttons (send, attach, model picker).
+- For non-chat input surfaces (forms, prompts, search) use <chat-input-ui> directly without the composer wrapper.
+
+## ChatEmpty
+- chat-empty is the bespoke replacement for legacy <empty-state-ui data-chat-empty>. Place as the first child of <chat-thread>; visibility is automatic via the [empty] reflected attribute.
+- No reactive props — visibility is CSS-driven off the parent [empty] attribute, not a JS toggle.
+- For non-chat empty states (lists, tables, canvas) use <empty-state-ui> primitive instead; chat-empty is chat-cluster-namespaced.
+
+## ChatHeader
+- chat-header replaces the legacy <header> chrome bar inside <chat-shell>. Use named slots for canonical clusters; ad-hoc content goes in the default slot.
+- Slots: [slot="name"] for chat title, [slot="status"] for streaming/connection indicator (<chat-status>), [slot="action"] for action buttons.
+- For admin-shell-style chrome bars inside chat-shell, use <admin-topbar> instead — chat-header is for in-chat metadata only.
+
+## ChatShell
+- chat-shell takes bespoke chat-* children only. The canonical composition is <chat-thread> (with optional first-child <chat-empty>) followed by <chat-composer> wrapping a <chat-input-ui>. Add <chat-header> / <chat-sidebar> / <chat-status> as needed.
+- Don't nest col-ui / row-ui or generic layout primitives directly inside chat-shell — the shell's CSS reads child tag selectors to lay them out. Generic layout goes inside the bespoke children.
+- The shell listens for 'composer-submit' on <chat-composer> (not on the inner input). Streaming state is reflected on this host and propagates to <chat-thread>[streaming] + <chat-composer>[disabled] automatically — don't toggle child attributes manually.
+- Legacy data-attribute shapes were retired in v0.4.0 per ADR-0024. Do not author <section data-chat-messages>, <chat-input-ui data-chat-input>, <empty-state-ui data-chat-empty>, or <header data-chat-name> inside chat-shell.
+
+## ChatSidebar
+- chat-sidebar is the bespoke replacement for legacy <aside data-sidebar>. Use slot="leading" or slot="trailing" to position. Add resizable + collapsible attributes to opt in to interactive behaviors.
+- For chrome bars inside the sidebar, prefer <admin-topbar slot="header"> and <admin-statusbar slot="footer"> over raw <header-ui> / <footer-ui> when authoring shell-tier markup.
+- Use cluster-distinct localStorage key (adia-chat-sidebar-*) to avoid collisions with admin (adia-sidebar-*) and editor (adia-editor-sidebar-*) sidebars.
+- For chat-list / conversation-switcher content, host <nav-ui> + <nav-item-ui> children in the default slot.
+
+## ChatStatus
+- chat-status replaces legacy <span data-chat-status> for the streaming/connection indicator. Place inside <chat-header slot="status">.
+- CSS-only — content is innerHTML (typically a short status word like 'connected' or 'streaming' or an icon).
+- Use [data-state="streaming|connected|disconnected|..."] for token-driven coloring; the CSS reads the state attribute for tinting.
+
+## ChatThread
+- chat-thread is the bespoke replacement for legacy <section data-chat-messages> inside <chat-shell>. Use it for the message scroll surface; the host appends dynamic message divs as children.
+- Place <chat-empty> as an optional first child for the empty state; the [empty] reflected attribute drives its visibility via CSS (no JS toggling).
+- Different from primitive <chat-thread-ui>: chat-thread (no -ui suffix) is the module-tier shell-aware version with scroll-on-new-message + load-more + empty-state coordination.
+- Hosts message blocks (typically agent/user message rows) as default-slot children; <chat-empty> goes as first child for the empty state.
+
+## DashboardLayout
+- DashboardLayout MUST receive children via the four named slots
+(toolbar / kpis / charts / table) plus the optional aside.
+Children without a [slot] attribute will not render in any band.
+
+- DashboardLayout[kpi-columns] MUST be 2-6. Out-of-range values
+fall back to the default 4. Eight cards in a row is too narrow
+to be legible at typical container widths; container queries
+collapse the band to 2 columns ≤48em and 1 column ≤32em.
+
+- DashboardLayout[chart-split] MUST be one of the documented
+enum strings — "" (full-width) / 2 / 2:1 / 3:2 / 3:1.
+
+- A DashboardLayout SHOULD sit inside AdminPageBody for the
+canonical chrome stack. Top-level placement is allowed for
+surface-only demos but not the production shape.
+
+- A DashboardLayout MUST NOT contain another DashboardLayout as
+a descendant. Two parametric-density containers fight over the
+--a-density cascade. For nested dashboards use sibling
+DashboardLayouts switched by Tabs.
+
+
+## DateRangeSelector
+- DateRangeSelector MUST sit inside a toolbar context — typically a
+Row inside DashboardLayout.slot=toolbar, or directly inside
+AdminPageHeader.slot=action. Do NOT place it as a freestanding
+block primitive at page top-level.
+
+- ONLY ONE DateRangeSelector with broadcast="document" per page.
+Secondary instances on the same page MUST use broadcast="self"
+or broadcast="none". Two document-broadcasters race for the
+data-range-* attributes on <html> and produce flicker.
+
+- `presets` MUST be a comma-separated subset of the documented value
+enum (today, 7d, 30d, 90d, qtd, ytd, custom). Unknown keys are
+ignored at runtime; the chip-row renders only recognized keys.
+
+- When value="custom", from/to MUST be ISO-8601 dates supplied
+either declaratively (from + to attributes) or imperatively via
+setRange("custom", from, to). Without a custom from/to, the
+composite falls back to the prior resolved range.
+
+- For form participation, set [name]. Without [name], the composite
+emits range-change events only and does NOT participate in form
+submission. With [name], FormData carries the value "{from}:{to}".
+
+
+## EditorCanvasEmpty
+- editor-canvas-empty is the bespoke empty-state slot for <editor-canvas>. Place as the first child of <editor-canvas>; visibility is automatic via the [empty] reflected attribute.
+- CSS-only — no JS module needed in shell HTML imports.
+- For non-editor canvas empty states (raw <canvas-ui>) use <empty-state-ui> instead; editor-canvas-empty is editor-cluster-namespaced.
+
+## EditorCanvasToolbar
+- editor-canvas-toolbar is the bespoke chrome strip for the <editor-canvas> top edge. Use it to hold view-mode tabs (preview / schema / DOM) or breadcrumb-style navigation scoped to the canvas region.
+- Place as the first child of <editor-canvas>; the canvas's flex-column layout positions the toolbar above the content body automatically, and the toolbar is sticky to keep tabs visible during canvas scroll.
+- Distinct from <editor-toolbar> (app-scope, top of <editor-shell>) — this is canvas-scope, holding view-mode affordances rather than document-wide actions.
+
+## EditorCanvas
+- editor-canvas is the bespoke replacement for legacy <div data-canvas> inside <editor-shell>. Use it as the central content region for editor work surfaces.
+- Place <editor-canvas-empty> as an optional first child for the empty state; the [empty] reflected attribute drives its visibility via CSS (no JS toggling).
+- Place <editor-canvas-toolbar> as the first child to mount view-mode tabs (preview / schema / DOM, etc.), breadcrumbs, or canvas-scoped actions above the content body. Replaces the ad-hoc <div data-view-strip> pattern. Distinct from <editor-toolbar> (app-scope) — this is canvas-scope.
+
+## EditorShell
+- editor-shell takes bespoke editor-* children only. The canonical composition is <editor-toolbar> + <editor-sidebar slot="leading"> + <editor-canvas> + <editor-sidebar slot="trailing"> + <editor-statusbar>. Each child is optional except the canvas.
+- Don't nest col-ui / row-ui or generic layout primitives directly inside editor-shell — the shell's CSS reads child tag selectors to lay them out. Generic layout goes inside the bespoke children.
+- <editor-sidebar> WRAPS <pane-ui resizable> rather than implementing drag itself (delegation pattern). Inside each sidebar place a single <pane-ui resizable size="sm"> filled with <header> + <section> slots.
+- For editor-inside-admin nested-shell pages, place the editor-shell inside <admin-page-body> with `flex: 1; min-height: 0` on every ancestor in the flex chain. Without min-height: 0 the inner shell collapses to zero height.
+- Legacy data-attribute shapes were retired in v0.4.0 per ADR-0024. Do not author <div data-editor-body>, <pane-ui data-left|data-right>, <div data-canvas>, <span data-spacer>, or bare <header>/<footer> chrome inside editor-shell.
+
+## EditorSidebar
+- editor-sidebar wraps <pane-ui resizable> rather than implementing drag itself. Place a <pane-ui resizable> as the only structural child; fill the pane with header / section / footer slots.
+- The cluster-distinct localStorage prefix (adia-editor-sidebar-*) keeps editor sidebars from colliding with admin (adia-sidebar-*) and chat (adia-chat-sidebar-*) sidebars on the same domain.
+- Wraps a SINGLE <pane-ui resizable> as its only structural child; fill the pane with sub-views (nav, inspector, layers panel, etc.).
+- For multiple panes (e.g. left nav + right inspector), use two <editor-sidebar> instances at slot="leading" and slot="trailing" of <editor-shell>.
+
+## EditorStatusbar
+- editor-statusbar replaces legacy <footer> chrome bar inside <editor-shell>. Use named slots for canonical clusters; ad-hoc content goes in the default slot.
+- Slots: [slot="status"] for save/sync state, [slot="cursor"] for cursor position, [slot="zoom"] for zoom level, [slot="action"] for actions. All optional.
+- Different from <admin-statusbar> (which is for admin-shell); editor-statusbar has editor-specific slot vocabulary (cursor, zoom).
+
+## EditorToolbar
+- editor-toolbar replaces legacy <header> chrome bar inside <editor-shell>. Use named slots (title / status / action / action-leading) for canonical clusters; ad-hoc inline content goes in the default slot.
+- Buttons that should trigger named actions get [data-toolbar-action="<name>"]. The toolbar bubbles a single 'toolbar-action' event up to the host with the name in detail.
+- Different from <admin-topbar> (admin-shell chrome) — editor-toolbar has [full-screen] state + editor-specific [data-toolbar-action] event bubbling.
+- Place full-screen toggle buttons inside the toolbar with [data-toolbar-action="toggle-full-screen"]; host reflects [full-screen] up to <editor-shell>.
+
+## ConfirmDialog
+- ConfirmDialog is for NON-destructive yes/no questions ("Save changes?", "Switch theme?", "Apply preset?"). For irreversible destructive operations (delete, drop, deploy to prod) use AlertDialog instead — its danger chrome + role="alertdialog" + typed-name speed-bump are the WAI-APG pattern for that case.
+- Default focus lands on Cancel by default — this is intentional (WAI guidance: the least-destructive action is the default). Do NOT add autofocus to the confirm button or override the focus model.
+- The confirm button is primary-toned by default. Use [confirm-variant="ghost"] only when both options are roughly equivalent in weight (e.g. "Apply preset" vs "Keep current" where neither is strictly preferred).
+- Do NOT model the cancel option as a "Discard" action — if cancel means "lose data", the operation is destructive and belongs in AlertDialog. ConfirmDialog's cancel is a no-op return-to-prior- state semantically.
+- Reflect dialog visibility via the [open] boolean attribute on the ConfirmDialog host (open=true / open=false). Do NOT toggle [hidden], CSS display, or wrap in a sibling visibility container — the inner <modal-ui> owns the native <dialog> lifecycle.
+
+## FormPopover
+- Children are the form fragment, in author order: CheckBox, Radio, Input, Textarea, Divider, Field. Do NOT put Option children here — a single-value option list is Select's contract; FormPopover never rebuilds it.
+- Decision rule vs siblings: single-value choice → Select (with multiple:true for multi-select chips); pure action list → Menu; edge-anchored multi-field form → Drawer. FormPopover is only for a small MIXED fragment (checks + radios + an input) behind a summary trigger.
+- The trigger summary counts CheckBox children only — one checked shows its own label, more show "Label (N)", none shows the bare label (same contract as Select[summary-label]); Radio and Input children never count. Give every Radio child one shared name per group or the browser treats them as independent.
+
+## OnboardingChecklist
+- OnboardingChecklist MUST have a non-empty `items` array. Empty items renders an empty card.
+- Each item MUST have a unique `id` within the list — used as the storage key + event detail.
+- `storageKey` SHOULD be namespaced per product (e.g. `myapp:onboarding:v1`) to avoid cross-app collisions.
+- Items SHOULD number 3 to 8. Fewer than 3 is not worth a checklist; more than 8 should split into stages.
+- Use for the "card of optional setup tasks" case. For horizontal multi-screen wizards use <step-progress-ui>; for generic to-do lists compose <list-ui> + <check-ui> directly.
+- Do not nest two <onboarding-checklist-ui> with the same `storageKey` — they will clobber each other.
+
+## A2UIRoot
+- Mount point for an A2UI-rendered composition. Hosts the runtime-emitted DOM tree.
+- Different from <gen-root> (which is for the generative-UI lane with LLM-driven streaming).
+- Do not place static children inside; runtime owns the contents.
+
+## GenRoot
+- gen-root is an integration shell. Prefer admin-shell for admin UIs; use gen-root only for chat+canvas tooling.
+- Hosts <chat-thread-ui>, <canvas-ui>, and <inspector-ui> children via named slots — chat slot for the conversation lane, canvas slot for the artifact lane, inspector slot for the dev-tools lane.
+- Mode attribute (chat-only|split|canvas-only) controls layout; transitions are CSS-animated.
+
+## IntegrationsPage
+- Use <integrations-page-ui> for the canonical Settings >
+Integrations grid. Supply the `integrations` array — the
+composite owns the search + grouping + grid breakpoints +
+empty state.
+
+- `integrations` MUST be a non-empty array OR the page renders
+the empty-state. Each item MUST satisfy the SPEC-062 card
+prop contract (provider + name required).
+
+- Do NOT slot <integration-card-ui> children directly — the page
+generates cards from the `integrations` prop. Slotted children
+are ignored.
+
+- Do NOT nest <integrations-page-ui> inside another
+<integrations-page-ui>.
+
+- For one-off integration tile groups (e.g., a single recommended
+provider on a marketing page) use <integration-card-ui> directly
+inside <grid-ui>; reach for the page composite only when search
++ grouping + empty-state semantics are needed.
+
+
+## NotificationPreferences
+- NotificationPreferences.channels MUST be non-empty. A matrix with zero columns renders nothing meaningful — author at least one channel record.
+- NotificationPreferences.preferences[].channels keys MUST match the channels[].key set. Mismatched keys silently render the cell as `false` (off) — they do NOT raise an error, but the user can never toggle them into existence either.
+- The composite is fully CONTROLLED — toggling a cell does NOT mutate `preferences`. The host MUST listen for `change` (and `bulk-toggle` for the column master), apply the change to its own state, then re-pass the new `preferences` array. Failing to do this leaves the toggle visually flipping back to its prior state on the next render.
+- For binary on/off cell toggles, use <check-ui> semantics — NOT <switch-ui>. The column-header master IS a <switch-ui> (because it's a "setting" — flip the whole column), but each cell is a multi-select-style checkbox.
+- Use `group-by="group"` only when `preferences[]` records carry a stable `group` field. Mixing grouped + ungrouped rows in the same matrix produces inconsistent section heights.
+
+## AdminCommand
+- admin-command wraps a native <dialog>; the inner <command-ui> is the actual palette. Keyboard shortcut defaults to both Cmd+K (mac) and Ctrl+K (other) — the AdiaUI convention.
+- Place admin-command as a direct child of admin-shell, NOT inside a sidebar or main column. The host coordinates triggers ([data-command-trigger]) by reaching across siblings.
+- For inline content-region command surfaces use <command-ui> directly; admin-command is the modal wrapper that opens the palette as an overlay.
+- Triggers anywhere in the shell via [data-command-trigger] attribute on any element; the host wires the open/close cycle.
+
+## AdminContent
+- admin-content is the bespoke replacement for raw <main> inside admin-shell. CSS-only; the shell's css/main.css selectors target both shapes via :is(main, admin-content).
+- Place as a direct child of <admin-shell>, not inside a sidebar or topbar; admin-content owns the center column.
+- Hosts <admin-page> children OR raw page content via the default slot; for chrome bars use <admin-topbar slot="header">.
+
+## AdminEntityItem
+- admin-entity-item is the canonical icon + label + badge identity row for shell surfaces. Slot it whole into [slot="heading"] of an <admin-topbar> / <admin-statusbar> so the icon + label + badge collapse together inside a collapsible <admin-sidebar>. Do NOT re-implement it with a bare <span> or an ad-hoc flex <div> — those have no shared collapse boundary.
+- For an INTERACTIVE workspace switcher use <select-ui variant="ghost"> instead — admin-entity-item is read-only identity display.
+- Slot whole into [slot="heading"] of <admin-topbar>/<admin-statusbar>; do not nest inside other admin-entity-items.
+- Flat hierarchy: icon + label + badge in three slots, no extra wrapping at the admin-entity-item level. For full-width metadata strips compose multiple inside <row-ui> instead.
+- For an <icon-ui> glyph, wrap it: <span slot="icon"><icon-ui name="…"></icon-ui></span>. For <img>/<avatar-ui>, slot directly (no wrapper).
+
+## AdminPageBody
+- admin-page-body is the centered body band of <admin-page>. Wraps an inner <section-ui> for centered reading-column rhythm; can host full-bleed content directly to opt out.
+- Wraps an inner <section-ui> by default for centered reading-column rhythm; for full-bleed content (tables, canvas grids) use [data-full-bleed] on the section.
+- Always inside <admin-page slot="body">; do not place admin-page-body outside admin-page.
+
+## AdminPageFooter
+- admin-page-footer is the sticky bottom band of <admin-page>, the bottom-anchored counterpart of <admin-page-header>. Wraps an inner <footer-ui> for centered reading-column rhythm.
+- Wraps an inner <footer-ui> for centered reading-column rhythm; admin-page-footer owns sticky positioning + border-top, footer-ui owns the content layout.
+- Always inside <admin-page slot="footer">; for shell-tier status chrome spanning the whole shell use <admin-statusbar> instead.
+- Optional — most pages need only <admin-page-header> + <admin-page-body>. Add a footer only for persistent page-level actions (save bar, pagination, legal); never stamp an empty one.
+
+## AdminPageHeader
+- admin-page-header is the sticky top band of <admin-page>. Wraps an inner <header-ui> for centered reading-column rhythm.
+- Wraps an inner <header-ui> for centered reading-column rhythm; admin-page-header owns sticky positioning + border, header-ui owns the content layout.
+- Always inside <admin-page slot="header">; for shell-tier chrome use <admin-topbar> instead.
+- Always wrap an inner <header-ui> — not a raw <header>. Raw <header> has no shadow DOM; slot="action" and other named slots on its children are silently dropped.
+
+## AdminPage
+- admin-page is the bespoke replacement for <article data-content-root>. Provides the page-content named container query so descendants can use @container page-content (max-width: 720px) etc.
+- Hosts a single page surface via [slot="body"] (typically <admin-page-body>) with optional [slot="header"] (<admin-page-header>) and [slot="footer"].
+- Sits inside <admin-content>'s default slot; do not place outside admin-shell.
+
+## AdminScroll
+- admin-scroll is the bespoke replacement for the legacy <section> child of <main> inside admin-shell. Single child convention — typically wraps an <admin-page> for sticky-band layout.
+- Wraps a single <admin-page> child typically; do not place multiple admin-pages side-by-side as siblings here.
+- For horizontal scrolling regions (data grids, canvas surfaces) use overflow on the inner content instead — admin-scroll is vertical-only.
+
+## AppShell
+- admin-shell takes bespoke admin-* children only. The canonical composition is <admin-topbar> + <admin-sidebar slot="leading"> + <admin-content> + <admin-sidebar slot="trailing"> + <admin-command> + optional <admin-statusbar>. The shell's CSS grid reads child tag selectors to place them.
+- Don't nest col-ui / row-ui or generic layout primitives directly inside admin-shell — app-shell.css handles grid layout based on bespoke child tags. Generic layout goes inside <admin-content> or inside <admin-page-body>.
+- Click forwarding patterns — [data-sidebar-toggle="<name>"] on a button forwards to <admin-sidebar[slot="<name>"]>.toggle(); [data-command-trigger] on a button forwards to <admin-command>.show(). The shell doesn't need to know about the buttons; the bespoke children own the behavior.
+- Legacy data-attribute shapes were retired in v0.4.0 per ADR-0024. Do not author <aside data-sidebar>, <dialog data-command>, [data-resize], <aside-ui slot=>, <span data-spacer>, or <div data-actions> inside admin-shell.
+
+## AdminSidebar
+- admin-sidebar is the bespoke replacement for legacy <aside data-sidebar>. Use slot="leading" or slot="trailing" to position. Add resizable + collapsible attributes to opt in to interactive behaviors.
+- For chrome bars inside the sidebar, prefer <admin-topbar slot="header"> and <admin-statusbar slot="footer"> over raw <header-ui> / <footer-ui> when authoring shell-tier markup.
+- [resizable] attribute enables drag-resize via internal <pane-ui resizable>; persists collapsed/width to localStorage under adia-sidebar-* keys.
+- For non-resizable static rails (fixed-width nav), omit [resizable]; the same primitive serves both modes.
+
+## AdminStatusbar
+- admin-statusbar replaces <footer-ui> at shell-tier. Same slot vocabulary as <admin-topbar>; visual treatment differs (the shell css applies a top-border instead of bottom).
+- For a user-identity row (avatar + name + role badge), slot a single <admin-entity-item slot="heading"> rather than separate slot="icon" + slot="heading" children — the wrapper collapses the name + badge together inside a collapsible <admin-sidebar>, keeping the avatar.
+- All slots optional; common pattern is [slot="heading"] + [slot="action"] only. Empty admin-statusbar renders zero-height (no visual chrome).
+- Sits at slot="footer" of <admin-shell>, <admin-content>, or <admin-sidebar>; do not place inside <admin-page slot="footer"> (use raw <footer-ui> there).
+
+## AdminTopbar
+- admin-topbar replaces <header-ui> at shell-tier — use it for chrome bars inside admin-shell, admin-content, admin-sidebar. Use <header-ui> for primitive containers (Card / Drawer / Modal).
+- For an icon + label (+ optional badge) identity row — workspace or product identity — slot a single <admin-entity-item slot="heading"> rather than separate slot="icon" + slot="heading" children. The wrapper keeps the icon and label as one unit so they truncate and collapse together inside a collapsible <admin-sidebar>.
+- All slots optional; common pattern is [slot="heading"] + [slot="action"] only. Empty admin-topbar renders zero-height (no visual chrome).
+- Sits at slot="header" of <admin-shell>, <admin-content>, or <admin-sidebar>; do not place inside <admin-page slot="header"> (use <admin-page-header> there).
+
+## AppShell
+- embed-shell takes exactly one [app] child + any number of [panel="<name>"] children. It owns layout, not content — the consumer supplies the surfaces.
+- Open a panel with an [opens="<name>"] trigger anywhere inside, or an `embed:open` event; dismiss with [close]. Do not toggle visibility manually — the shell reflects [panel] + sets [active] on the open panel.
+- Use clean attributes (ADR-0024) — [app], [panel], [opens], [close] — not the legacy data-* shapes.
+
+## SimpleContent
+- simple-content is the article surface inside simple-shell. Use for primary page body. Sibling to <simple-hero> (optional).
+- CSS-only — do not import its JS module (there isn't one); does not need an `import` in shell HTML.
+- For multi-page apps with chrome (nav, topbar, command palette) use <admin-shell-ui> with <admin-content> instead.
+
+## SimpleHero
+- simple-hero is the optional top strip inside simple-shell. Use for marketing splashes, error-page reassurance text, or single- flow page intros. Always followed by <simple-content> for body.
+- Three named slots: heading (large title), lede (supporting subtitle), actions (button cluster). All optional but order is fixed.
+- CSS-only — sibling to <simple-content> inside <simple-shell>. Do not nest hero inside content or vice versa.
+
+## SimpleShell
+- simple-shell is the bespoke shell for thin / minimal page surfaces. Use when the page has no nav rail, no chrome bars, no command palette. For full app surfaces use admin-shell; for chat surfaces use chat-shell; for design tools use editor-shell.
+- Compose with <simple-hero> (optional top hero strip) and <simple-content> (main article body). Both are CSS-only structural children — no JS, no state.
+- [centered] reflected attribute centers content vertically; [full-bleed] drops the max-width constraint on <simple-content> children. Both optional, default unset.
+- For multi-page apps with chrome (nav, topbar, command palette) use <admin-shell> instead; simple-shell has zero chrome.
+
+## ThemePanel
+- theme-panel is the canonical appearance-preferences popover. Compose inside a <popover-ui slot="content"> in the topbar of a shell (admin, chat, editor, simple) when the page exposes user theming. Avoid hardcoding it as a shell child — placement is the consumer's call.
+- Use [persist] for the docs surface or a real product app; omit [persist] for playgrounds and embedded demos so state stays ephemeral. The default is ephemeral.
+- Add boolean attributes [parametric], [presets], [register], [scheme-toggle] to enable sections; the minimum panel is the theme button grid (empty until [themes] is supplied — no default list).
+