@adia-ai/a2ui-corpus 0.6.33 → 0.6.35

package/catalog-a2ui_0_9_rules.txt

@@ -64,6 +64,9 @@
 - Inline alert/banner for status messages within a content region. Severity via variant (info, success, warn, error).
 - 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").
 
 ## 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">.
@@ -104,6 +107,10 @@
 - 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.
@@ -173,12 +180,34 @@
 - 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 <multi-select-ui> (SPEC-040), not combobox. Combobox is single-select.
+
 ## 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. The `select` event's detail.category mirrors the parent optgroup's label. 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.
 
+## 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.
@@ -270,12 +299,18 @@
 - 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.
 
+## 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 submit-on-enter> (chat variant subclass — owns the submit-on-enter contract explicitly). The plain <input-ui> primitive already fires `submit` on Enter, but only chat-input-ui reflects the [submit-on-enter] attribute.
+- 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.
@@ -283,6 +318,13 @@
 - 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.
@@ -293,6 +335,16 @@
 - 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>.
@@ -303,6 +355,15 @@
 - 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.
+
 ## 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.
@@ -463,6 +524,8 @@
 - 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.
@@ -474,6 +537,13 @@
 - For two-handle range selection use <range-ui> instead.
 - Step attribute controls increments; show-value enables an inline value label.
 
+## 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).
@@ -554,6 +624,14 @@
 - 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>.
 
+## 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.
@@ -564,7 +642,15 @@
 - 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 inserts a newline — <textarea-ui> does NOT emit a `submit` event. For Enter-to-send multi-line composers, use <chat-input-ui submit-on-enter> inside <chat-composer>, not textarea-ui.
+- 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).
+
+## 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.
@@ -632,8 +718,57 @@
 - Multiple attribute enables multi-file selection; accept= constrains file types.
 - For agent chat attachments use <chat-composer-ui>'s built-in upload affordance instead.
 
+## 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 submit-on-enter> as the primary input.
+- 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.
@@ -649,7 +784,7 @@
 - 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 submit-on-enter>. Add <chat-header> / <chat-sidebar> / <chat-status> as needed.
+- 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.
@@ -671,6 +806,53 @@
 - 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 produces a
+KPI card narrower than --dashboard-layout-kpi-min.
+
+- 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.
@@ -710,6 +892,21 @@
 - 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.
+
+## 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).
@@ -720,6 +917,36 @@
 - 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.