@adia-ai/a2ui 0.8.40 → 0.8.42

package/catalog/catalog-a2ui_0_9_rules.txt

@@ -17,14 +17,18 @@
 - 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.
+- Child of <action-list-ui> — one inline-action row with icon + label + optional description + optional trailing shortcut/badge.
 - 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.
+- Use [variant="danger"] exclusively for destructive/irreversible actions (Delete, Remove). Pair danger items with an explicit confirm flow when the action cannot be undone.
+- Prefer [icon]/[text]/[description] props over slotted markup; use slot="icon"/"text"/"subtitle"/"trailing" only for custom markup (e.g. a slotted <kbd> shortcut hint).
+- NOTE (ADR-0063, gh#1571): [subtitle] is now a deprecated alias for [description] — kept as a dual-read compat shim (new-name precedence, one-time console.warn), removed at the 0.9.0 cut.
 
 ## 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.
+- For a persisted, non-firing single selection (highlight the current row, no keyboard-activated command) use <list-ui selectable> instead — action-list-ui always fires and never holds a selected state.
 
 ## 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.
@@ -129,7 +133,7 @@
 - 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>.
+- For toggleable on/off state use <switch-ui>; for multi-select clusters use <segmented-ui multiple> + <segment-ui> (gh#1369 — <toggle-group-ui>/<toggle-option-ui> are deprecated).
 
 ## 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.
@@ -137,8 +141,11 @@
 
 ## 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.
+- Use for single-date input. For date ranges use <date-range-picker-ui> instead of composing two calendar-picker instances.
 - min/max attributes constrain selectable range; disabled-dates accepts a function or date list.
+- Set `precision: "minute"` or `precision: "second"` for combined date+time selection — composes a time pane alongside the calendar grid. `value` MUST then be ISO 8601 datetime ("YYYY-MM-DDTHH:mm" or with seconds) OR empty string; a date-only or time-only string fires `invalid`.
+- `hour-cycle`/`step`/`locale` are only meaningful when `precision` is minute/second.
+- Do NOT wrap in `<field-ui label>` AND also expect a bare `label` attribute on `<calendar-picker-ui>` to render — the picker has no first-class label; use `<field-ui label="…">` (siblings all follow this convention).
 
 ## Canvas
 - A2UI rendering surface — consumes a DocStore / A2UI document and renders the component tree from it.
@@ -173,7 +180,7 @@
 - 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
+## UIChatThread
 - 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>.
@@ -195,17 +202,22 @@
 - 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.
 
+## ColorArea
+- 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>.
+- Renamed from <color-picker-ui> (ADR-0063, gh#1563); the old tag is a deprecated alias that still works — new generation should reach for ColorArea directly.
+- Output format defaults to oklch(); set format= to override (hex, rgb, hsl).
+
 ## 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.
+- Use <color-input-ui> for any form-row color field — it canonicalizes the popover + button + color-area 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.
+- For brand-palette constraints, set [maxChroma] / [minL] / [maxL] / [hueDriftMax] (with [baseHue]) on the host — they forward to the inner <color-area-ui> and clamp generation. Useful for Tokens-Studio-style guarded color generation.
+- Use <color-area-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-area-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.
+- DEPRECATED — prefer `{"component": "ColorArea"}` over `{"component": "ColorPicker"}`. Both render and behave identically; ColorPicker is a thin compatibility alias.
 - 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.
@@ -233,11 +245,9 @@
 - Use DateRangePicker for date ranges. Do NOT compose two adjacent `<calendar-picker-ui>` instances + JS synchronization — that is the pattern this primitive replaces.
 
 ## DatetimePicker
+- DEPRECATED — prefer `{"component": "CalendarPicker", "precision": "minute"}` (or `"second"`) over `{"component": "DatetimePicker"}`. Both render and behave identically; DatetimePicker is a thin compatibility alias.
 - `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
@@ -288,14 +298,15 @@
 
 ## 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.
+- Typically created programmatically via UIFeed.post(...); do not place declaratively — for a generated declarative notification author `Toast` instead, which forwards into this same channel (SPEC-FEED-CHANNEL-001 Phase 4).
+- Different from <alert-ui> (inline persistent). <toast-ui> is not a separate standalone system — it is the declarative-authoring facade for this same feed channel; both render as a feed-item paint site.
 - 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.
+- Not the generation target for a new transient notification — author `Toast` instead. <toast-ui> is a thin declarative facade that already posts into this channel and self-removes on connect (SPEC-FEED-CHANNEL-001 Phase 4); `<feed-ui>`/`<feed-item-ui>` are the imperative/programmatic infrastructure underneath it, reached via `UIFeed.post()` or a declared `<toast-ui>`, never by placing `<feed-ui>`/`<feed-item-ui>` directly in generated markup.
 
 ## 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.
@@ -331,7 +342,7 @@
 - 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.
+- The `padded` 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.
@@ -369,6 +380,7 @@
 - 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.
+- input-ui's `type` enum covers only the modes it actually implements — text/email/password/number/tel/url (gh#1363 B10). Never set [type] to an HTML5 value input-ui doesn't render — route date/time/color/search intents to the owning primitive instead: CalendarPicker, DatetimePicker, TimePicker, ColorInput (or ColorPicker directly), Search. See anti_patterns.
 
 ## Inspector
 - Developer-tools pane for A2UI runtime state — composes <tabs-ui> + <code-ui> internally.
@@ -407,11 +419,13 @@
 - 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.
+- [selected] reflects the row current-selection state under <list-ui selectable> — it is parent-managed (ADR-0056); drive selection via the parent's [selectedKey], never [selected] directly.
 
 ## 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.
+- list-ui supports single selection natively via [selectable] + [selectedKey] (ADR-0056, #1363 B7) — the parent stamps the matching <list-item-ui>'s [selected] + aria-selected and fires selection-change. For route-aware navigation use <nav-ui> instead; for a popover action menu use <menu-ui> instead — both have different interaction contracts than a plain selectable list.
 - For data-grid / sortable / sticky-header needs use <table-ui> instead.
+- list-ui carries no fire-and-forget "action" mode. [selectable] keeps a persisted single selection (`selectedKey` / `aria-selected`, roving tabindex); for rows that activate immediately with no persisted selection state use <action-list-ui> + <action-item-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.
@@ -439,6 +453,7 @@
 - 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).
+- <action-item-ui> (child of <action-list-ui>) shares this row contract (icon/text/subtitle/value/variant/disabled props, icon/text/subtitle/ trailing slot overrides) for inline, non-popover command rows — use it instead when the surface isn't a <menu-ui> popover (#1363 C5). NOTE (ADR-0063, gh#1563): <menu-item-ui>'s own `subtitle` PROP is now a deprecated alias for `description` — <action-item-ui> still uses `subtitle` as its own primary spelling and was NOT renamed in this pass (flagged as a discovered follow-up candidate, not fixed here).
 
 ## 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.
@@ -450,7 +465,7 @@
 - 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.
+- 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 [offset] (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.
@@ -537,7 +552,7 @@
 ## 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.
+- 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). [offset] (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.
 
@@ -547,14 +562,13 @@
 - 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>.
+- DEPRECATED — do not generate ProgressRow. Set `label` (and optional `meta`) directly on <progress-ui> instead; label present activates the identical row layout.
+- For standalone progress bars without a row context use <progress-ui> directly (no `label`).
 
 ## 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.
+- For labeled task lists (multiple progress bars with row labels, e.g. storage/capacity breakdowns), set `label` (and optional `meta`) directly on <progress-ui> — no separate component needed.
+- For circular loading indicators, use <spinner-ui> instead — <progress-ui> is bar-only.
 
 ## 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).
@@ -610,14 +624,14 @@
 - <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.
+- Child of <segmented-ui> — one selectable option button; the parent's [multiple] axis decides single- or multi-select, segment-ui itself is unchanged either way.
+- <toggle-option-ui> (deprecated, gh#1369) is the same concept — use segment-ui inside <segmented-ui multiple> instead.
+- Selected state managed by the parent <segmented-ui> — it syncs the selected attribute onto every child whose value is in its own value (single value, or the [multiple] comma-separated set); 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>.
+- Single-select by default. Hosts <segment-ui> children; exactly one selected at a time.
+- For multi-select (filter chips, multi-flag toggles, day-of-week pickers), set [multiple] instead of using a separate component — value becomes a comma-separated set of selected segment values. <toggle-group-ui>/<toggle-option-ui> are deprecated; use <segmented-ui multiple> + <segment-ui> instead (gh#1369, #1363 C1).
+- 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 multiple>.
 
 ## 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.
@@ -663,7 +677,7 @@
 ## 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.
+- For multi-task progress bars (multiple labeled rows) use a stack of <progress-ui> with `label` set (absorbed the row layout from the now-deprecated progress-row-ui).
 
 ## StepperItem
 - Child of <stepper-ui> — one numbered step with label + complete/current/upcoming state.
@@ -685,7 +699,7 @@
 - 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>.
+- Use to display a single color sample with optional label. For interactive color picking use <color-area-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.
 
@@ -719,6 +733,7 @@
 - [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>.
+- [selected] reflects whether this tab's panel is active — it is parent-managed (ADR-0056's selection-item convention, mirroring <segment-ui>); author markup drives the parent's [value], never [selected] directly.
 
 ## 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>.
@@ -782,7 +797,8 @@
 ## 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>.
+- Variant maps to severity (info, success, warning, danger); same tokens as <alert-ui>.
+- Taught default for generated transient notifications — author `Toast` declaratively. It safely dissolves into `<feed-ui>` on connect (SPEC-FEED-CHANNEL-001 Phase 4; see toast.class.js), forwarding only `text`, `duration`, and `position` — not full parity with `UIFeed.post()`, which also accepts `heading`, `icon`, `dismissible`, and `action`, and defaults `variant` to `default` where Toast defaults to `info`. For those extra fields, call `UIFeed.post()` directly (imperative) instead of authoring `Toast`. Do not author `FeedItem` directly either way — <feed-ui>/<feed-item-ui>'s own a2ui rules say not to place it declaratively; that pair is the imperative channel Toast forwards into, not itself a generation target.
 
 ## TableOfContents
 - Use for in-page section navigation. Pair with a sticky container in an aside / right rail for the docs-site outline pattern.
@@ -791,14 +807,14 @@
 - 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
+- DEPRECATED (gh#1369, #1363 C1) — generate <segmented-ui multiple> + <segment-ui> children instead when [single] is false/absent (the default, multi-select). When [single] is true, generate plain <segmented-ui> (no [multiple]) instead — single-select toggle-group maps to segmented's own single-select mode, not the multiple axis; note segmented-ui single-select never clears on re-click (toggle-group[single] does). Same comma-separated value encoding either way; toggle-group is kept working for existing consumers but should not appear in new generated output.
 - 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>.
 - Sets the child <toggle-option-ui>'s declared [selected] prop to reflect the group value (ADR-0056) — do not author [selected] directly in generated markup; author the group's value instead.
 
 ## ToggleOption
+- DEPRECATED (gh#1369, #1363 C1) — generate <segment-ui> instead, as a child of <segmented-ui multiple> (or plain <segmented-ui>, no [multiple], if the parent toggle-group had [single] — see toggle-group.yaml). toggle-option is kept working for existing consumers but should not appear in new generated output.
 - 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>).
 - Selected state exposed via its own declared [selected] reflected prop, set by the parent <toggle-group-ui> (ADR-0056) — mirrors <segment-ui>'s convention. Do not set [selected] directly; drive the group's value instead.
 
 ## ToggleScheme
@@ -852,6 +868,7 @@
 ## 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.
+- compact renders an icon-only trigger (no drop-zone chrome) — use in toolbars/dense rows; label becomes the trigger's aria-label. Programmatic triggering goes through the public .open() method, never the internal [data-dropzone] part.
 - For agent chat attachments use <chat-composer-ui>'s built-in upload affordance instead.
 
 ## VisuallyHidden
@@ -1171,11 +1188,11 @@ inside <grid-ui>; reach for the page composite only when search
 - 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
+## AdminShell
 - 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.
+- Legacy data-attribute shapes were retired in v0.4.0 per ADR-0024. Do not author <aside data-sidebar>, <dialog data-command>, [data-sidebar-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.

package/catalog/common_types.json

@@ -155,6 +155,7 @@
         "textAlign": { "$ref": "#/$defs/DynamicString",  "description": "Text alignment — start, center, end, justify." },
         "ariaLabel": { "$ref": "#/$defs/DynamicString",  "description": "Accessibility label (maps to aria-label at runtime)." },
         "ariaHidden":{ "$ref": "#/$defs/DynamicBoolean", "description": "Accessibility hidden state (maps to aria-hidden at runtime)." },
+        "ariaLive":  { "$ref": "#/$defs/DynamicString",  "description": "ARIA live-region politeness (maps to aria-live at runtime). Values: off | polite | assertive (A2UI v1.0 vocabulary, SPEC REQ-013). Use polite for status/progress text that updates in place, assertive only for urgent errors." },
         "span":      { "$ref": "#/$defs/DynamicString",  "description": "Grid-child column span, read by grid-ui's CSS attribute selector ([span=\"N\"] { grid-column: span N }). Layout-bearing like slot — accepted on every component, not a per-component prop (TKT-0002/TKT-0010)." }
       },
       "patternProperties": {