@adia-ai/web-components 0.6.20 → 0.6.22

package/components/col/col.yaml

@@ -6,16 +6,27 @@ tag: col-ui
 component: Col
 category: layout
 version: 1
-description: Flex column layout primitive.
+description: |
+  Flex column layout primitive — vertical stack of children with
+  [gap] / [align] / [justify] / [grow]. The most common layout
+  primitive in the repo. Use <col-ui> for vertical stacks, <row-ui>
+  for horizontal rows, <stack-ui> for overlay (children stack on top
+  of each other in a grid), <grid-ui> for 2D grids. Composes inside
+  <section-ui> for in-card layout; do NOT use as a child of
+  <header-ui> / <footer-ui> (the chrome scope already lays out
+  slots).
 props:
   align:
-    description: Align items
+    description: >-
+      Cross-axis alignment (start/center/end/stretch). Accepts `@bp` notation:
+      align="stretch center@sm" applies stretch below sm, center from sm up.
     type: string
     default: stretch
   gap:
     description: >-
-      Gap between children. Accepts either the named scale (xs/sm/md/lg/xl)
-      or a numeric rung on the spacing scale ("1"…"16", mapped to --a-space-N).
+      Gap between children. Named scale (xs/sm/md/lg/xl) or numeric spacing
+      rung ("1"…"16", mapped to --a-space-N). Accepts `@bp` notation:
+      gap="2 4@md" = 2 below md, 4 from md upward.
     type: string
     default: md
   grow:
@@ -24,7 +35,9 @@ props:
     default: false
     reflect: true
   justify:
-    description: Justify content
+    description: >-
+      Main-axis justify (start/center/end/space-between/space-around).
+      Accepts `@bp` notation: justify="start space-between@md".
     type: string
     default: start
 events: {}
@@ -37,7 +50,13 @@ states:
 traits: []
 tokens: {}
 a2ui:
-  rules: []
+  rules:
+    - rule: 'Vertical-stack flex container. Children flow top-to-bottom with token-driven gap.'
+      reason: 'Canonical vertical layout.'
+    - rule: 'Pair with <row-ui> for horizontal layouts; both share the same gap-token contract.'
+      reason: 'Layout symmetry.'
+    - rule: 'Set align/justify attributes for cross-axis / main-axis alignment; default is start/start.'
+      reason: 'Standard flex knobs.'
 anti_patterns: []
 examples:
   - name: chat-interface
@@ -340,7 +359,8 @@ examples:
 keywords:
   - column
   - col
-synonyms: {}
+synonyms:
+  column: [col, vstack, vertical-stack, vbox]
 related:
   - avatar
   - input

package/components/color-input/color-input.yaml

@@ -142,7 +142,33 @@ tokens:
   --color-input-swatch-size:
     description: Diameter (em) of the inline swatch circle inside the trigger button. Default 1em.
 a2ui:
-  rules: []
+  rules:
+    - >-
+      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.
 anti_patterns: []
 examples:
   - name: color-input-basic

package/components/color-picker/color-picker.a2ui.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://adiaui.dev/a2ui/v0_9/components/ColorPicker.json",
   "title": "ColorPicker",
-  "description": "OKLCH-native color picker with 2D area and H/C/L sliders. Form-associated.",
+  "description": "OKLCH-native color picker with 2D area and H/C/L sliders. Form-associated input emitting OKLCH color strings; canonical color authoring surface in the AdiaUI token system. Use for color input in design tools or theming UIs; for simple color swatches use <swatch-ui> or <color-input-ui> instead.",
   "type": "object",
   "allOf": [
     {
@@ -128,7 +128,13 @@
         "name": "disabled"
       }
     ],
-    "synonyms": {},
+    "synonyms": {
+      "color-picker": [
+        "color-canvas",
+        "color-surface",
+        "swatch-picker"
+      ]
+    },
     "tag": "color-picker-ui",
     "tokens": {},
     "traits": [],

package/components/color-picker/color-picker.yaml

@@ -6,7 +6,12 @@ tag: color-picker-ui
 component: ColorPicker
 category: input
 version: 1
-description: OKLCH-native color picker with 2D area and H/C/L sliders. Form-associated.
+description: >-
+  OKLCH-native color picker with 2D area and H/C/L sliders.
+  Form-associated input emitting OKLCH color strings; canonical color
+  authoring surface in the AdiaUI token system. Use for color input in
+  design tools or theming UIs; for simple color swatches use <swatch-ui>
+  or <color-input-ui> instead.
 # Per ADR-0027 — primitives that programmatically create other primitives
 # do NOT auto-import them. Consumer (or demo shell) must explicitly import.
 composes:
@@ -100,7 +105,13 @@ requiredIcons:
   - check
   - warning
 a2ui:
-  rules: []
+  rules:
+    - rule: 'OKLCH-native color picker with 2D color area + H/C/L sliders. Form-associated; emits OKLCH color strings.'
+      reason: 'Canonical color-authoring surface.'
+    - rule: 'For simple color swatches (read-only display) use <swatch-ui>; for hex/rgb text input use <color-input-ui>.'
+      reason: 'Surface boundary.'
+    - rule: 'Output format defaults to oklch(); set format= to override (hex, rgb, hsl).'
+      reason: 'Format knob.'
 anti_patterns: []
 examples:
   - name: color-picker-demo
@@ -156,7 +167,8 @@ keywords:
   - color-picker
   - color
   - picker
-synonyms: {}
+synonyms:
+  color-picker: [color-canvas, color-surface, swatch-picker]
 related:
   - grid
   - button

package/components/command/command.a2ui.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://adiaui.dev/a2ui/v0_9/components/Command.json",
   "title": "Command",
-  "description": "Searchable command palette with keyboard navigation.",
+  "description": "Searchable command palette primitive — combobox-style search input\nplus a scrollable list of <option value> items grouped by\n<optgroup label>. Content-only; does NOT own the dialog or the\nCmd+K shortcut. For canonical Cmd+K palettes wrap in <admin-command>\nat the shell tier, which provides the native <dialog> + focus\nmanagement + cross-platform Cmd+K listener. Distinct from <menu-ui>\n(small popover action menu, not searchable) and <modal-ui> (generic\ncentered dialog).\n",
   "type": "object",
   "allOf": [
     {
@@ -88,7 +88,12 @@
       "keybinding"
     ],
     "name": "UICommand",
-    "related": [],
+    "related": [
+      "AdminCommand",
+      "Menu",
+      "Modal",
+      "Search"
+    ],
     "slots": {
       "empty": {
         "description": "Empty state shown when no items match"

package/components/command/command.d.ts

@@ -1,5 +1,13 @@
 /**
- * `<command-ui>` — Searchable command palette with keyboard navigation.
+ * `<command-ui>` — Searchable command palette primitive — combobox-style search input
+plus a scrollable list of <option value> items grouped by
+<optgroup label>. Content-only; does NOT own the dialog or the
+Cmd+K shortcut. For canonical Cmd+K palettes wrap in <admin-command>
+at the shell tier, which provides the native <dialog> + focus
+management + cross-platform Cmd+K listener. Distinct from <menu-ui>
+(small popover action menu, not searchable) and <modal-ui> (generic
+centered dialog).
+
  *
  * @see https://ui-kit.exe.xyz/site/components/command
  *

package/components/command/command.yaml

@@ -4,7 +4,15 @@ tag: command-ui
 component: Command
 category: container
 version: 1
-description: Searchable command palette with keyboard navigation.
+description: |
+  Searchable command palette primitive — combobox-style search input
+  plus a scrollable list of <option value> items grouped by
+  <optgroup label>. Content-only; does NOT own the dialog or the
+  Cmd+K shortcut. For canonical Cmd+K palettes wrap in <admin-command>
+  at the shell tier, which provides the native <dialog> + focus
+  management + cross-platform Cmd+K listener. Distinct from <menu-ui>
+  (small popover action menu, not searchable) and <modal-ui> (generic
+  centered dialog).
 props:
   open:
     description: Whether the command palette is visible
@@ -52,7 +60,31 @@ tokens: {}
 requiredIcons:
   - magnifying-glass
 a2ui:
-  rules: []
+  rules:
+    - >-
+      <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.
 anti_patterns: []
 examples:
 - name: basic-command
@@ -181,4 +213,8 @@ synonyms:
   - palette
   tags:
   - CommandPalette
-related: []
+related:
+  - AdminCommand
+  - Menu
+  - Modal
+  - Search

package/components/demo-toggle/demo-toggle.yaml

@@ -81,7 +81,13 @@ tokens:
   --demo-toggle-stage-padding:
     description: Inner padding around each slot
 a2ui:
-  rules: []
+  rules:
+    - rule: 'Demo-page-only — toggles between live and code views in component documentation surfaces.'
+      reason: 'Doc-tooling primitive; not for product surfaces.'
+    - rule: 'Do not use in apps/ — restrict to packages/web-components/components/*/<name>.html demo pages and docs surfaces.'
+      reason: 'Surface scope.'
+    - rule: 'Behavior: shows/hides the [data-code] block when toggled.'
+      reason: 'Built-in cascade.'
 anti_patterns: []
 examples:
   - name: with-without-trait

package/components/description-list/description-list.a2ui.json

@@ -62,7 +62,11 @@
       "dl"
     ],
     "name": "UIDescriptionList",
-    "related": [],
+    "related": [
+      "List",
+      "Field",
+      "Section"
+    ],
     "slots": {
       "[object Object]": {
         "description": "Child content region for the `[object Object]` slot."

package/components/description-list/description-list.yaml

@@ -46,7 +46,13 @@ states:
 traits: []
 tokens: {}
 a2ui:
-  rules: []
+  rules:
+    - rule: 'Use for key:value pairs in dense detail views (user profile fields, metadata panels, audit logs).'
+      reason: 'Semantic <dl> with token-driven spacing; better than ad-hoc <row-ui> layouts.'
+    - rule: 'Do not use for editable forms — use <fields-ui> instead.'
+      reason: 'Description list is read-only display; fields handle input + validation.'
+    - rule: 'Pairs render as label + value on the same row by default; use vertical variant for narrow panes.'
+      reason: 'Responsive layout knob.'
 anti_patterns: []
 examples: []
 keywords:
@@ -65,4 +71,7 @@ synonyms:
     - spec list
     - metadata list
     - property list
-related: []
+related:
+  - List
+  - Field
+  - Section

package/components/divider/divider.a2ui.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://adiaui.dev/a2ui/v0_9/components/Divider.json",
   "title": "Divider",
-  "description": "Horizontal or vertical divider with optional label.",
+  "description": "Horizontal or vertical divider with optional label — a semantic\nrule between content groups. Set [vertical] for column dividers\n(typically inside <row-ui>); set [label] for a labeled-rule pattern\nwhere the divider carries a short caption (e.g. \"OR\" between auth\nmethods, \"Today\" between message groups). Distinct from\n<hr data-nav-divider> (which is a CSS hook used by <nav-ui> for nav\nsection separation, not a primitive).\n",
   "type": "object",
   "allOf": [
     {

package/components/divider/divider.d.ts

@@ -1,5 +1,12 @@
 /**
- * `<divider-ui>` — Horizontal or vertical divider with optional label.
+ * `<divider-ui>` — Horizontal or vertical divider with optional label — a semantic
+rule between content groups. Set [vertical] for column dividers
+(typically inside <row-ui>); set [label] for a labeled-rule pattern
+where the divider carries a short caption (e.g. "OR" between auth
+methods, "Today" between message groups). Distinct from
+<hr data-nav-divider> (which is a CSS hook used by <nav-ui> for nav
+section separation, not a primitive).
+
  *
  * @see https://ui-kit.exe.xyz/site/components/divider
  *

package/components/divider/divider.yaml

@@ -6,7 +6,14 @@ tag: divider-ui
 component: Divider
 category: display
 version: 1
-description: Horizontal or vertical divider with optional label.
+description: |
+  Horizontal or vertical divider with optional label — a semantic
+  rule between content groups. Set [vertical] for column dividers
+  (typically inside <row-ui>); set [label] for a labeled-rule pattern
+  where the divider carries a short caption (e.g. "OR" between auth
+  methods, "Today" between message groups). Distinct from
+  <hr data-nav-divider> (which is a CSS hook used by <nav-ui> for nav
+  section separation, not a primitive).
 props:
   label:
     description: Center label text
@@ -24,7 +31,13 @@ states:
 traits: []
 tokens: {}
 a2ui:
-  rules: []
+  rules:
+    - rule: 'Use to separate visually distinct sections within a container; horizontal default, vertical via orientation=''vertical''.'
+      reason: 'Single-purpose primitive — semantic rule + token-driven margin.'
+    - rule: 'Inside menus / popovers use <menu-divider-ui> instead; it has menu-specific token spacing.'
+      reason: 'Menu-divider is menu-namespaced; divider-ui is generic.'
+    - rule: 'Do not stack multiple consecutive dividers — use a single divider or restructure the section.'
+      reason: 'Visual rhythm.'
 anti_patterns: []
 examples:
   - name: settings-page

package/components/drawer/drawer.yaml

@@ -131,7 +131,38 @@ states:
 traits: []
 tokens: {}
 a2ui:
-  rules: []
+  rules:
+    - >-
+      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>.
 anti_patterns:
   - description: >-
       Replacing a drawer's children wholesale — `drawer.innerHTML = '…'` —

package/components/embed/embed.a2ui.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://adiaui.dev/a2ui/v0_9/components/Embed.json",
   "title": "Embed",
-  "description": "Responsive sandboxed iframe wrapper.",
+  "description": "Responsive sandboxed <iframe> wrapper — renders external content at\na constrained [aspect] ratio with optional [width] / [height] override.\nThe iframe is created in light DOM with safe sandbox attributes;\nauthors do NOT slot an <iframe> directly. Use for YouTube / Vimeo /\nFigma embeds in articles, marketing pages, or chat responses; not\nfor arbitrary cross-origin app integrations (use the platform's own\nSDK / portal instead).\n",
   "type": "object",
   "allOf": [
     {

package/components/embed/embed.d.ts

@@ -1,5 +1,12 @@
 /**
- * `<embed-ui>` — Responsive sandboxed iframe wrapper.
+ * `<embed-ui>` — Responsive sandboxed <iframe> wrapper — renders external content at
+a constrained [aspect] ratio with optional [width] / [height] override.
+The iframe is created in light DOM with safe sandbox attributes;
+authors do NOT slot an <iframe> directly. Use for YouTube / Vimeo /
+Figma embeds in articles, marketing pages, or chat responses; not
+for arbitrary cross-origin app integrations (use the platform's own
+SDK / portal instead).
+
  *
  * @see https://ui-kit.exe.xyz/site/components/embed
  *

package/components/embed/embed.yaml

@@ -6,7 +6,14 @@ tag: embed-ui
 component: Embed
 category: agent
 version: 1
-description: Responsive sandboxed iframe wrapper.
+description: |
+  Responsive sandboxed <iframe> wrapper — renders external content at
+  a constrained [aspect] ratio with optional [width] / [height] override.
+  The iframe is created in light DOM with safe sandbox attributes;
+  authors do NOT slot an <iframe> directly. Use for YouTube / Vimeo /
+  Figma embeds in articles, marketing pages, or chat responses; not
+  for arbitrary cross-origin app integrations (use the platform's own
+  SDK / portal instead).
 props:
   aspect:
     description: CSS aspect-ratio (e.g. 16/9)
@@ -34,7 +41,15 @@ states:
 traits: []
 tokens: {}
 a2ui:
-  rules: []
+  rules:
+    - rule: 'Responsive sandboxed <iframe> wrapper at constrained aspect ratio. Safe sandbox attributes are applied by default.'
+      reason: 'Iframe primitive.'
+    - rule: 'For raster/vector images use <image-ui>; for icons use <icon-ui>; embed-ui is for live external content only.'
+      reason: 'Sibling decision rule.'
+    - rule: 'aspect attribute locks ratio (e.g. 16/9, 4/3) to prevent layout shift; width/height override when needed.'
+      reason: 'Dimension knobs.'
+    - rule: 'Do not embed first-party AdiaUI app routes — use direct component composition instead.'
+      reason: 'Cross-origin discipline.'
 anti_patterns: []
 examples:
   - name: embed-content

package/components/empty-state/empty-state.a2ui.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://adiaui.dev/a2ui/v0_9/components/EmptyState.json",
   "title": "EmptyState",
-  "description": "Placeholder for empty views with icon, heading, description, and action slot.",
+  "description": "Placeholder for empty views with icon, heading, description, and action slot. Renders centered inside lists, tables, panes, or cards when no data is present. Use as a zero-state inside containers; for app-loading shells use <skeleton-ui> instead.",
   "type": "object",
   "allOf": [
     {
@@ -35,6 +35,16 @@
       "description": "§223 (v0.5.9). Single-line muted layout — drops centered-column chrome\n(no vertical padding, no row-stack, no icon-size bump). Useful for\ninline empty-table-row / inline empty-list / placeholder cells where\nthe full-canvas placeholder is too prominent.",
       "type": "boolean",
       "default": false
+    },
+    "variant": {
+      "description": "Semantic color variant. Use `danger` or `warning` for full-section error states where the data cannot be shown (API failure, permission error) — the centered layout mirrors the empty state but uses danger/ warning tones. Leave unset (default) for the canonical zero-data case.",
+      "type": "string",
+      "enum": [
+        "default",
+        "danger",
+        "warning"
+      ],
+      "default": "default"
     }
   },
   "required": [
@@ -85,7 +95,14 @@
         "name": "idle"
       }
     ],
-    "synonyms": {},
+    "synonyms": {
+      "empty-state": [
+        "zero-state",
+        "no-data",
+        "placeholder",
+        "empty"
+      ]
+    },
     "tag": "empty-state-ui",
     "tokens": {
       "--empty-state-action-mt": {

package/components/empty-state/empty-state.css

@@ -56,6 +56,20 @@
     margin-top: var(--empty-state-action-mt);
   }
 
+  /* ── Semantic color variants ──
+     Color the icon + text only; no background/border tint. */
+  :scope[variant="danger"] {
+    --empty-state-icon-fg:    var(--a-danger-strong);
+    --empty-state-heading-fg: var(--a-danger-text);
+    --empty-state-desc-fg:    var(--a-danger-text);
+  }
+
+  :scope[variant="warning"] {
+    --empty-state-icon-fg:    var(--a-warning-strong);
+    --empty-state-heading-fg: var(--a-warning-text);
+    --empty-state-desc-fg:    var(--a-warning-text);
+  }
+
   /* ── §223 (v0.5.9): [minimal] — single-line muted layout ──
      Drops centered-column chrome (no canvas-style padding, no flex-column
      stack). Renders as `[icon] heading [description]` inline in muted-fg.

package/components/empty-state/empty-state.d.ts

@@ -1,5 +1,5 @@
 /**
- * `<empty-state-ui>` — Placeholder for empty views with icon, heading, description, and action slot.
+ * `<empty-state-ui>` — Placeholder for empty views with icon, heading, description, and action slot. Renders centered inside lists, tables, panes, or cards when no data is present. Use as a zero-state inside containers; for app-loading shells use <skeleton-ui> instead.
  *
  * @see https://ui-kit.exe.xyz/site/components/empty-state
  *
@@ -24,4 +24,6 @@ export class UIEmptyState extends UIElement {
 inline empty-table-row / inline empty-list / placeholder cells where
 the full-canvas placeholder is too prominent. */
   minimal: boolean;
+  /** Semantic color variant. Use `danger` or `warning` for full-section error states where the data cannot be shown (API failure, permission error) — the centered layout mirrors the empty state but uses danger/ warning tones. Leave unset (default) for the canonical zero-data case. */
+  variant: 'default' | 'danger' | 'warning';
 }

package/components/empty-state/empty-state.yaml

@@ -6,7 +6,11 @@ tag: empty-state-ui
 component: EmptyState
 category: display
 version: 1
-description: Placeholder for empty views with icon, heading, description, and action slot.
+description: >-
+  Placeholder for empty views with icon, heading, description, and action
+  slot. Renders centered inside lists, tables, panes, or cards when no
+  data is present. Use as a zero-state inside containers; for app-loading
+  shells use <skeleton-ui> instead.
 # Per ADR-0027 — primitives that programmatically create other primitives
 # do NOT auto-import them. Consumer (or demo shell) must explicitly import.
 composes:
@@ -33,6 +37,19 @@ props:
     type: boolean
     default: false
     reflect: true
+  variant:
+    description: >-
+      Semantic color variant. Use `danger` or `warning` for full-section
+      error states where the data cannot be shown (API failure, permission
+      error) — the centered layout mirrors the empty state but uses danger/
+      warning tones. Leave unset (default) for the canonical zero-data case.
+    type: string
+    default: default
+    enum:
+      - default
+      - danger
+      - warning
+    reflect: true
 events: {}
 slots:
   action:
@@ -65,7 +82,36 @@ tokens:
   --empty-state-py:
     description: Vertical padding
 a2ui:
-  rules: []
+  rules:
+    - >-
+      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). Prefer
+      [variant="primary"] for create-flows; [variant="outline"] for
+      retry / secondary actions.
+    - >-
+      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.
 anti_patterns: []
 examples:
   - name: empty-state
@@ -313,7 +359,8 @@ keywords:
   - empty-state
   - empty
   - state
-synonyms: {}
+synonyms:
+  empty-state: [zero-state, no-data, placeholder, empty]
 related:
   - button
   - drawer