@adia-ai/web-components 0.6.21 → 0.6.22

package/CHANGELOG.md

@@ -1,5 +1,63 @@
 # Changelog — @adia-ai/web-components
 
+## [0.6.22] — 2026-05-22
+
+### Added — `@bp` responsive attribute system (`core/responsive.js`)
+
+- New `core/responsive.js` exports `BREAKPOINTS`, `BP_NAMES`, a shared `breakpoint` signal (matchMedia-driven; SSR-safe), and `parseResponsive(value, activeBp)`. Mobile-first: unannotated value = base; `@bp` applies at that breakpoint and wider. Reading `breakpoint.value` inside any UIElement `render()` auto-subscribes — no manual listener wiring needed.
+- **`grid-ui`**: `columns`, `gap` accept `@bp` (e.g. `columns="2 4@md"`). `render()` also sets `gridAutoFlow:row` + `gridAutoColumns:auto` so items wrap correctly — the default `grid-auto-flow:column` would otherwise spread them horizontally.
+- **`col-ui`**: `gap`, `align`, `justify` accept `@bp`. `align` sets `text-align` inline to mirror the CSS attribute side-effect.
+- **`row-ui`**: `gap`, `align`, `justify` accept `@bp`.
+- **`text-ui`**: `size` accepts `@bp` (`size="sm md@lg"`).
+- **`block-ui`**: `padding`, `margin` accept `@bp` (`padding="sm md@lg"`).
+- Subscription is lazy: each component only subscribes to the breakpoint signal when at least one prop contains `@`.
+
+### Added — `empty-state-ui` `variant="danger|warning"`
+
+- New `variant` prop (default|danger|warning). Colors icon and text via danger/warning semantic tokens — **no background tint or border** (by design: an empty-state occupies the full content surface; a tinted box would frame absent content). Use `variant="danger"` for full-section error states where content cannot be shown; the centered layout is more appropriate than an inline alert banner when data is absent. File: `components/empty-state/empty-state.css`.
+
+### Fixed — `card-ui` sparkline cards fill available height
+
+- `card.css`: `:has(> section[bleed] > chart-ui)` switches matching cards to `flex-direction: column`; bleed section gets `flex: 1; min-height: 0`. Scoped tightly — no effect on other card layouts.
+- `chart.css`: sparkline type gains `height: 100%`. Computes to `auto` when parent has no explicit height (backward-compatible); fills flex-grown height when available.
+
+### Fixed — `alert-ui` missing `[slot="action"]` CSS rule
+
+- `slot="action"` was documented in `alert.yaml` but had no CSS. Added `flex-shrink: 0; align-self: start` so action content behaves as a proper trailing flex item.
+
+### Fixed — `segmented-ui` overflow: labels now truncate with ellipsis
+
+- `segmented.css`: added `min-width: 0` to `:scope`. `inline-grid` previously never shrank below its max-content width in flex contexts, leaving the `::after { text-overflow: ellipsis }` rule in `segment.css` (already correct) unreachable.
+- `card.css`: changed card header action column from `max-content` → `auto` (`minmax(min-content, max-content)`). `max-content` prevented the action column from shrinking. Added `min-width: 0` to `[slot="action"]`. Chain: card narrows → action column shrinks → action flex shrinks → segmented-ui shrinks → segments share available width → `::after` ellipsis fires.
+
+### Fixed — `stat-ui [slot="label"]` now truncates with ellipsis
+
+- **`[slot="label"]` (the eyebrow line above the value) was missing the overflow-ellipsis triad** that `[slot="value"]` already carried. Long label strings clipped hard at the grid cell boundary with no `…`. Added `overflow: hidden; text-overflow: ellipsis; white-space: nowrap` to bring the two sibling slots into parity. File: `components/stat/stat.css`.
+
+### Fixed — `table-ui` column headers now truncate with ellipsis
+
+- **Column headers had `white-space: nowrap` but no overflow clipping**, so long header text overflowed into adjacent cells. `overflow: hidden` cannot be applied to the `[role="columnheader"]` directly — it would clip the `position: absolute` filter dropdown rendered inside it. Fix: converted `[role="columnheader"]` to `display: flex; align-items: center` and added `flex: 1; min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap` on the label `<span>` child (already created by `class.js`). Sort icons and filter buttons remain fully visible at their natural size; only the label text truncates. File: `components/table/table.css`.
+
+### Fixed — `table-ui` body cells now show ellipsis (not just hard clipping)
+
+- **Body cells declared `text-overflow: ellipsis` but showed hard clipping with no `…` character.** Root cause: `text-overflow: ellipsis` on a `display: flex` container has no effect on anonymous flex items (text nodes set via `cell.textContent`). All 6 built-in text-scalar cell types (`text`, `number`, `currency`, `percent`, `date`, `datetime`) and the two `class.js` fallback paths now wrap text in a `<span>` child element. CSS rules targeting `[role="gridcell"] > span` and `> a` (link type) carry `flex: 1; min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap`. Rules for `> row-ui { min-width: 0; overflow: hidden }` and `> row-ui > span` cover the avatar and progress composite types. The `[wrap]` opt-in is extended to reset child-element overflow properties so per-table or per-column wrap still works. Files: `components/table/cell-types.js`, `components/table/class.js`, `components/table/table.css`.
+
+### Changed — UI context inset/gap scale reduced
+
+- **`--a-inset-sm/md/lg` and `--a-gap-sm/md/lg` shifted down the space scale** to better suit dense UI surfaces. New values at `--a-density: 1`: inset sm 16→8px, md 24→16px, lg 32→24px; gap sm 12→8px, md 16→12px, lg 24→16px. The `[prose]` context is unchanged — it stays coarser by design. File: `styles/tokens.css`.
+
+### Changed — `stat-ui` gap tokens cascade with container size context
+
+- **`--stat-column-gap` and `--stat-row-gap` are now `var(--a-gap)` and `var(--a-gap-sm)`** instead of hardcoded space tokens. When a parent container sets `size="sm"` or `size="lg"`, stat-ui gaps adapt automatically. File: `components/stat/stat.css`.
+
+### Documentation — 21 component examples pages corrected
+
+- **YAML-vs-HTML audit of all 93 components** found 58 with missing or stale API documentation. 21 fixed: missing props added, stale enum values corrected (`block`→`stretch` for button, `error`→`danger` for tag/alert, size ranges extended), full API sections added where absent (link, field, nav, nav-group, nav-item). See journal §411–§418 for the complete list.
+
+### Documentation — `packages/web-components/patterns/` + `packages/web-components/traits/` examples sweep
+
+- **§407 ripple sweep on `patterns/` + `traits/` examples.html files.** As a side-effect of the §407 spacing-scale rebase + table-truncation work, demo pages for `conversion-funnel`, `editor-shell`, `form-drawer`, `record-detail-drawer`, `retention-cohort`, `wizard-drawer` (patterns) and `active-state`, `arrow-grid-nav`, `draggable-list-item`, `drop-target`, `focus-restore`, `focus-trap`, `focusable`, `hotkey`, `hoverable` (traits) were re-stamped to use the new inset/gap tokens consistently.
+
 ## [0.6.21] — 2026-05-21
 
 ### Changed — `table-ui` body cells truncate by default (opt-in wrap via `[wrap]` / `[data-wrap]`)

package/components/accordion/accordion-item.a2ui.json

@@ -46,9 +46,19 @@
       }
     },
     "examples": [],
-    "keywords": [],
+    "keywords": [
+      "accordion-item",
+      "collapsible",
+      "disclosure",
+      "expand",
+      "collapse-row",
+      "section-toggle"
+    ],
     "name": "UIAccordionItem",
-    "related": [],
+    "related": [
+      "Accordion",
+      "Card"
+    ],
     "slots": {
       "action": {
         "description": "§206 (v0.5.7): action buttons inside a custom header (e.g. Copy /\nDownload / settings). Children placed at `[slot=\"action\"]` (or\n`[slot=\"actions\"]`, or marked `[data-no-toggle]`) are excluded from\nthe toggle-on-click cascade — clicking them fires their own handler\nwithout also toggling the section."
@@ -58,7 +68,14 @@
       }
     },
     "states": [],
-    "synonyms": {},
+    "synonyms": {
+      "accordion-item": [
+        "collapsible-row",
+        "disclosure-row",
+        "expansion-panel",
+        "expander"
+      ]
+    },
     "tag": "accordion-item-ui",
     "tokens": {},
     "traits": [],

package/components/accordion/accordion-item.yaml

@@ -45,3 +45,27 @@ events:
       open:
         type: boolean
         description: New open state.
+
+keywords:
+  - accordion-item
+  - collapsible
+  - disclosure
+  - expand
+  - collapse-row
+  - section-toggle
+
+synonyms:
+  accordion-item: [collapsible-row, disclosure-row, expansion-panel, expander]
+
+related:
+  - Accordion
+  - Card
+
+a2ui:
+  rules:
+    - rule: 'Child of <accordion-ui> — places one collapsible section with header + body.'
+      reason: 'Cluster contract.'
+    - rule: 'Toggle behavior: click anywhere on the row toggles, unless inside [slot=''actions''] or [data-no-toggle].'
+      reason: 'Built-in cascade; do not wire onclick yourself.'
+    - rule: 'For single-button disclosures (one expanding panel without a list) use <details>/<summary> or compose <button-ui> + <section-ui>.'
+      reason: 'Accordion-item assumes sibling-context.'

package/components/accordion/accordion.a2ui.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://adiaui.dev/a2ui/v0_9/components/Accordion.json",
   "title": "Accordion",
-  "description": "Accordion container managing single/multiple open states.",
+  "description": "Accordion container managing single or multiple open states across\na collection of <accordion-item-ui> children. Each item carries its\nown [open] reflected state; the accordion host coordinates exclusive\nopening when [multiple] is unset (default single-open mode). Use\ninside settings pages, FAQ blocks, or any progressive-disclosure\npattern where one-level collapsible groups suffice — for arbitrary\nhierarchy use <tree-ui>; for in-page view switching use <tabs-ui>.\n",
   "type": "object",
   "allOf": [
     {

package/components/accordion/accordion.d.ts

@@ -1,5 +1,12 @@
 /**
- * `<accordion-ui>` — Accordion container managing single/multiple open states.
+ * `<accordion-ui>` — Accordion container managing single or multiple open states across
+a collection of <accordion-item-ui> children. Each item carries its
+own [open] reflected state; the accordion host coordinates exclusive
+opening when [multiple] is unset (default single-open mode). Use
+inside settings pages, FAQ blocks, or any progressive-disclosure
+pattern where one-level collapsible groups suffice — for arbitrary
+hierarchy use <tree-ui>; for in-page view switching use <tabs-ui>.
+
  *
  * @see https://ui-kit.exe.xyz/site/components/accordion
  *

package/components/accordion/accordion.yaml

@@ -6,7 +6,14 @@ tag: accordion-ui
 component: Accordion
 category: container
 version: 1
-description: Accordion container managing single/multiple open states.
+description: |
+  Accordion container managing single or multiple open states across
+  a collection of <accordion-item-ui> children. Each item carries its
+  own [open] reflected state; the accordion host coordinates exclusive
+  opening when [multiple] is unset (default single-open mode). Use
+  inside settings pages, FAQ blocks, or any progressive-disclosure
+  pattern where one-level collapsible groups suffice — for arbitrary
+  hierarchy use <tree-ui>; for in-page view switching use <tabs-ui>.
 # Per ADR-0027 — primitives that programmatically create other primitives
 # do NOT auto-import them. Consumer (or demo shell) must explicitly import.
 composes:
@@ -34,7 +41,13 @@ tokens: {}
 requiredIcons:
   - caret-down
 a2ui:
-  rules: []
+  rules:
+    - rule: 'Hosts <accordion-item-ui> children. One or more sections may be open simultaneously (set single= to enforce only-one-open).'
+      reason: 'Multi-vs-single open mode.'
+    - rule: 'For tab-switched panels (always exactly one open) use <tabs-ui>; accordion supports zero-open and multi-open.'
+      reason: 'Decision rule vs tabs.'
+    - rule: 'Item ordering is DOM-order; no auto-sort.'
+      reason: 'Author-controlled order.'
 anti_patterns: []
 examples:
   - name: accordion-settings

package/components/action-list/action-item.a2ui.json

@@ -49,12 +49,28 @@
     "composes": [],
     "events": {},
     "examples": [],
-    "keywords": [],
+    "keywords": [
+      "action-item",
+      "command-row",
+      "inline-action",
+      "list-action",
+      "action-list-row"
+    ],
     "name": "UIActionItem",
-    "related": [],
+    "related": [
+      "ActionList",
+      "MenuItem",
+      "Button"
+    ],
     "slots": {},
     "states": [],
-    "synonyms": {},
+    "synonyms": {
+      "action-item": [
+        "command-item",
+        "inline-command",
+        "action-row"
+      ]
+    },
     "tag": "action-item-ui",
     "tokens": {},
     "traits": [],

package/components/action-list/action-item.yaml

@@ -35,3 +35,27 @@ props:
     description: Disables click + keyboard activation; aria-disabled is set.
     type: boolean
     default: false
+
+keywords:
+  - action-item
+  - command-row
+  - inline-action
+  - list-action
+  - action-list-row
+
+synonyms:
+  action-item: [command-item, inline-command, action-row]
+
+related:
+  - ActionList
+  - MenuItem
+  - Button
+
+a2ui:
+  rules:
+    - rule: 'Child of <action-list-ui> — one inline-action row with icon + label + optional shortcut + optional sublabel.'
+      reason: 'Action-list cluster contract.'
+    - rule: 'Different from <menu-item-ui>: action-items live inline in content surfaces; menu-items live inside <menu-ui> popovers.'
+      reason: 'Context boundary.'
+    - rule: 'For navigation entries (route-changing) use <nav-item-ui> instead.'
+      reason: 'Different intent — actions vs navigation.'

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

@@ -60,7 +60,11 @@
       "list"
     ],
     "name": "UIActionList",
-    "related": [],
+    "related": [
+      "ActionItem",
+      "Menu",
+      "Button"
+    ],
     "slots": {
       "default (action-item-ui children)": {
         "description": "Child content region for the `default (action-item-ui children)` slot."
@@ -72,7 +76,13 @@
         "name": "idle"
       }
     ],
-    "synonyms": {},
+    "synonyms": {
+      "action-list": [
+        "command-list",
+        "action-rows",
+        "command-rows"
+      ]
+    },
     "tag": "action-list-ui",
     "tokens": {},
     "traits": [],

package/components/action-list/action-list.yaml

@@ -35,7 +35,13 @@ states:
 traits: []
 tokens: {}
 a2ui:
-  rules: []
+  rules:
+    - rule: 'Hosts <action-item-ui> children as a vertical command list inline in content surfaces.'
+      reason: 'Cluster contract.'
+    - rule: 'For popover-style menus use <menu-ui> + <menu-item-ui> instead.'
+      reason: 'Inline vs popover.'
+    - rule: 'Typical use: command palettes, settings panels, agent suggestion lists.'
+      reason: 'Surface examples.'
 anti_patterns: []
 examples:
   - name: basic-action-list
@@ -66,5 +72,9 @@ keywords:
   - action-list
   - action
   - list
-synonyms: {}
-related: []
+synonyms:
+  action-list: [command-list, action-rows, command-rows]
+related:
+  - ActionItem
+  - Menu
+  - Button

package/components/agent-artifact/agent-artifact.a2ui.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://adiaui.dev/a2ui/v0_9/components/AgentArtifact.json",
   "title": "AgentArtifact",
-  "description": "Inline container for structured agent artifacts (A2UI, JSON, tickets).",
+  "description": "Inline container for structured agent artifacts (A2UI, JSON, tickets, code). Renders inside <chat-thread-ui> message bodies or <inspector-ui> panes as a labeled, optionally collapsible block with content-type-aware rendering. Use for agent-emitted structured payloads; for free-text agent output use <text-ui> or <richtext-ui> instead.",
   "type": "object",
   "allOf": [
     {
@@ -100,7 +100,14 @@
         "name": "idle"
       }
     ],
-    "synonyms": {},
+    "synonyms": {
+      "artifact": [
+        "agent-artifact",
+        "tool-output",
+        "agent-output",
+        "tool-result"
+      ]
+    },
     "tag": "agent-artifact-ui",
     "tokens": {},
     "traits": [],

package/components/agent-artifact/agent-artifact.d.ts

@@ -1,5 +1,5 @@
 /**
- * `<agent-artifact-ui>` — Inline container for structured agent artifacts (A2UI, JSON, tickets).
+ * `<agent-artifact-ui>` — Inline container for structured agent artifacts (A2UI, JSON, tickets, code). Renders inside <chat-thread-ui> message bodies or <inspector-ui> panes as a labeled, optionally collapsible block with content-type-aware rendering. Use for agent-emitted structured payloads; for free-text agent output use <text-ui> or <richtext-ui> instead.
  *
  * @see https://ui-kit.exe.xyz/site/components/agent-artifact
  *

package/components/agent-artifact/agent-artifact.yaml

@@ -6,7 +6,12 @@ tag: agent-artifact-ui
 component: AgentArtifact
 category: agent
 version: 1
-description: Inline container for structured agent artifacts (A2UI, JSON, tickets).
+description: >-
+  Inline container for structured agent artifacts (A2UI, JSON, tickets,
+  code). Renders inside <chat-thread-ui> message bodies or <inspector-ui>
+  panes as a labeled, optionally collapsible block with content-type-aware
+  rendering. Use for agent-emitted structured payloads; for free-text
+  agent output use <text-ui> or <richtext-ui> instead.
 # Per ADR-0027 — primitives that programmatically create other primitives
 # do NOT auto-import them. Consumer (or demo shell) must explicitly import.
 composes:
@@ -56,7 +61,15 @@ requiredIcons:
   - caret-right
   - caret-down
 a2ui:
-  rules: []
+  rules:
+    - rule: 'Inline container for structured agent payloads inside <chat-thread-ui> message bodies or <inspector-ui> panes.'
+      reason: 'Canonical artifact-rendering surface.'
+    - rule: 'kind attribute (a2ui|json|ticket|code|...) sets content-type-aware rendering and icon/badge styling.'
+      reason: 'Polymorphic content.'
+    - rule: 'For free-text agent output use <text-ui> or <richtext-ui>; artifact-ui is for structured payloads only.'
+      reason: 'Free-text vs structured boundary.'
+    - rule: 'primary + secondary slots for header chrome; default slot for the artifact body.'
+      reason: 'Slot contract — chrome + payload separation.'
 anti_patterns: []
 examples:
   - name: basic
@@ -77,7 +90,8 @@ keywords:
   - inline
   - preview
   - attachment
-synonyms: {}
+synonyms:
+  artifact: [agent-artifact, tool-output, agent-output, tool-result]
 related:
   - card-ui
   - code-ui

package/components/agent-feedback-bar/agent-feedback-bar.a2ui.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://adiaui.dev/a2ui/v0_9/components/AgentFeedbackBar.json",
   "title": "AgentFeedbackBar",
-  "description": "Thumbs + save row under an agent response.",
+  "description": "Agent-response feedback bar — thumbs up / thumbs down rating row\nplus an optional Save action, rendered beneath an LLM-generated\nmessage. Composes <button-ui> children for the affordances; emits\n`feedback` event with detail.{value, action} on rating. Sits as the\ntrailing chrome of a chat message bubble or alongside an\n<agent-trace-ui> step — used in chat-shell, gen-ui canvas, and\ninspector flows.\n",
   "type": "object",
   "allOf": [
     {
@@ -91,7 +91,14 @@
         "name": "disabled"
       }
     ],
-    "synonyms": {},
+    "synonyms": {
+      "feedback-bar": [
+        "agent-feedback",
+        "response-feedback",
+        "thumbs-bar",
+        "rating-bar"
+      ]
+    },
     "tag": "agent-feedback-bar-ui",
     "tokens": {},
     "traits": [],

package/components/agent-feedback-bar/agent-feedback-bar.d.ts

@@ -1,5 +1,12 @@
 /**
- * `<agent-feedback-bar-ui>` — Thumbs + save row under an agent response.
+ * `<agent-feedback-bar-ui>` — Agent-response feedback bar — thumbs up / thumbs down rating row
+plus an optional Save action, rendered beneath an LLM-generated
+message. Composes <button-ui> children for the affordances; emits
+`feedback` event with detail.{value, action} on rating. Sits as the
+trailing chrome of a chat message bubble or alongside an
+<agent-trace-ui> step — used in chat-shell, gen-ui canvas, and
+inspector flows.
+
  *
  * @see https://ui-kit.exe.xyz/site/components/agent-feedback-bar
  *

package/components/agent-feedback-bar/agent-feedback-bar.yaml

@@ -6,7 +6,14 @@ tag: agent-feedback-bar-ui
 component: AgentFeedbackBar
 category: agent
 version: 1
-description: Thumbs + save row under an agent response.
+description: |
+  Agent-response feedback bar — thumbs up / thumbs down rating row
+  plus an optional Save action, rendered beneath an LLM-generated
+  message. Composes <button-ui> children for the affordances; emits
+  `feedback` event with detail.{value, action} on rating. Sits as the
+  trailing chrome of a chat message bubble or alongside an
+  <agent-trace-ui> step — used in chat-shell, gen-ui canvas, and
+  inspector flows.
 # Per ADR-0027 — primitives that programmatically create other primitives
 # do NOT auto-import them. Consumer (or demo shell) must explicitly import.
 composes:
@@ -48,7 +55,15 @@ states:
 traits: []
 tokens: {}
 a2ui:
-  rules: []
+  rules:
+    - rule: 'Thumbs-up / thumbs-down rating row + optional Save action, rendered beneath an LLM-generated message.'
+      reason: 'Canonical LLM feedback affordance.'
+    - rule: 'Different from <rating-ui> (star-based ordinal) — agent-feedback is binary good/bad.'
+      reason: 'Rating model boundary.'
+    - rule: 'Emits feedback events with value=up|down and optional save action; consumer wires the actual feedback API call.'
+      reason: 'Event-driven contract.'
+    - rule: 'Place at the end of an assistant message in <chat-thread-ui>, not on user messages.'
+      reason: 'Surface scope — LLM feedback only.'
 anti_patterns: []
 examples:
   - name: basic
@@ -67,7 +82,8 @@ keywords:
   - rating
   - save
   - bookmark
-synonyms: {}
+synonyms:
+  feedback-bar: [agent-feedback, response-feedback, thumbs-bar, rating-bar]
 related:
   - agent-suggestions-ui
   - agent-trace-ui

package/components/agent-questions/agent-questions.a2ui.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://adiaui.dev/a2ui/v0_9/components/AgentQuestions.json",
   "title": "AgentQuestions",
-  "description": "Multi-choice clarifying-question cards.",
+  "description": "Multi-choice clarifying-question card emitted by an agent when it\nneeds disambiguation before proceeding. Renders the question prompt\n+ a slotted list of <button-ui> answer chips (or radio-style cards\nwhen [multi] is set for multi-select). The submit button fires\n`answer` with detail.{value(s)} once the user confirms. Use for\nagentic clarification turns — not generic form input (use\n<field-ui> + form primitives for that).\n",
   "type": "object",
   "allOf": [
     {
@@ -93,7 +93,13 @@
         "name": "idle"
       }
     ],
-    "synonyms": {},
+    "synonyms": {
+      "questions": [
+        "clarifying-questions",
+        "agent-prompt",
+        "disambiguation"
+      ]
+    },
     "tag": "agent-questions-ui",
     "tokens": {},
     "traits": [],

package/components/agent-questions/agent-questions.d.ts

@@ -1,5 +1,12 @@
 /**
- * `<agent-questions-ui>` — Multi-choice clarifying-question cards.
+ * `<agent-questions-ui>` — Multi-choice clarifying-question card emitted by an agent when it
+needs disambiguation before proceeding. Renders the question prompt
++ a slotted list of <button-ui> answer chips (or radio-style cards
+when [multi] is set for multi-select). The submit button fires
+`answer` with detail.{value(s)} once the user confirms. Use for
+agentic clarification turns — not generic form input (use
+<field-ui> + form primitives for that).
+
  *
  * @see https://ui-kit.exe.xyz/site/components/agent-questions
  *

package/components/agent-questions/agent-questions.yaml

@@ -6,7 +6,14 @@ tag: agent-questions-ui
 component: AgentQuestions
 category: agent
 version: 1
-description: Multi-choice clarifying-question cards.
+description: |
+  Multi-choice clarifying-question card emitted by an agent when it
+  needs disambiguation before proceeding. Renders the question prompt
+  + a slotted list of <button-ui> answer chips (or radio-style cards
+  when [multi] is set for multi-select). The submit button fires
+  `answer` with detail.{value(s)} once the user confirms. Use for
+  agentic clarification turns — not generic form input (use
+  <field-ui> + form primitives for that).
 # Per ADR-0027 — primitives that programmatically create other primitives
 # do NOT auto-import them. Consumer (or demo shell) must explicitly import.
 composes:
@@ -50,7 +57,15 @@ tokens: {}
 requiredIcons:
   - check
 a2ui:
-  rules: []
+  rules:
+    - rule: 'Multi-choice clarifying-question card emitted by an agent when it needs disambiguation before proceeding.'
+      reason: 'Disambiguation pattern.'
+    - rule: 'multi attribute controls single-select (default) vs multi-select answer behavior.'
+      reason: 'Selection mode.'
+    - rule: 'Slot accepts <button-ui> answer chips; for radio-card style use <segmented-ui> + <segment-ui> children instead.'
+      reason: 'Slot vs sibling primitive choice.'
+    - rule: 'Different from <agent-suggestions-ui> (follow-up suggestions, optional) — agent-questions is gating (agent waits for answer).'
+      reason: 'Required vs optional response.'
 anti_patterns: []
 examples:
   - name: basic
@@ -70,7 +85,8 @@ keywords:
   - multiple choice
   - elicit
   - clarify
-synonyms: {}
+synonyms:
+  questions: [clarifying-questions, agent-prompt, disambiguation]
 related:
   - agent-suggestions-ui
   - agent-reasoning-ui

package/components/agent-reasoning/agent-reasoning.yaml

@@ -68,7 +68,15 @@ requiredIcons:
   - warning
   - warning-circle
 a2ui:
-  rules: []
+  rules:
+    - rule: 'Agent inner-monologue + pipeline viewer with steps, thoughts, plans, and iterations.'
+      reason: 'Reasoning visualization surface.'
+    - rule: 'Composes <timeline-ui> internally — pass reasoning steps as children rendered as <timeline-item-ui>.'
+      reason: 'Composition contract.'
+    - rule: 'noAutocollapse attribute prevents the auto-collapse-on-complete behavior; useful for debug surfaces.'
+      reason: 'Behavior knob.'
+    - rule: 'Different from <agent-trace-ui> (metrics + tool-call summary) — reasoning is narrative, trace is structured-data.'
+      reason: 'Narrative vs structured boundary.'
 anti_patterns: []
 examples:
   - name: basic

package/components/agent-suggestions/agent-suggestions.a2ui.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://adiaui.dev/a2ui/v0_9/components/AgentSuggestions.json",
   "title": "AgentSuggestions",
-  "description": "Row of follow-up suggestion chips.",
+  "description": "Row of follow-up suggestion chips presented under an agent response.\nEach suggestion is a <button-ui> child the user can tap to send the\ntext back as the next prompt. Composes <button-ui> with chip-style\nvisual treatment; the variant + size props cascade to children. Use\nto lower input friction at the bottom of a chat response; not for\npermanent navigation (that's <nav-ui>).\n",
   "type": "object",
   "allOf": [
     {
@@ -95,7 +95,14 @@
         "name": "disabled"
       }
     ],
-    "synonyms": {},
+    "synonyms": {
+      "suggestions": [
+        "follow-ups",
+        "follow-up-chips",
+        "prompts",
+        "completions"
+      ]
+    },
     "tag": "agent-suggestions-ui",
     "tokens": {},
     "traits": [],

package/components/agent-suggestions/agent-suggestions.d.ts

@@ -1,5 +1,11 @@
 /**
- * `<agent-suggestions-ui>` — Row of follow-up suggestion chips.
+ * `<agent-suggestions-ui>` — Row of follow-up suggestion chips presented under an agent response.
+Each suggestion is a <button-ui> child the user can tap to send the
+text back as the next prompt. Composes <button-ui> with chip-style
+visual treatment; the variant + size props cascade to children. Use
+to lower input friction at the bottom of a chat response; not for
+permanent navigation (that's <nav-ui>).
+
  *
  * @see https://ui-kit.exe.xyz/site/components/agent-suggestions
  *

package/components/agent-suggestions/agent-suggestions.yaml

@@ -6,7 +6,13 @@ tag: agent-suggestions-ui
 component: AgentSuggestions
 category: agent
 version: 1
-description: Row of follow-up suggestion chips.
+description: |
+  Row of follow-up suggestion chips presented under an agent response.
+  Each suggestion is a <button-ui> child the user can tap to send the
+  text back as the next prompt. Composes <button-ui> with chip-style
+  visual treatment; the variant + size props cascade to children. Use
+  to lower input friction at the bottom of a chat response; not for
+  permanent navigation (that's <nav-ui>).
 # Per ADR-0027 — primitives that programmatically create other primitives
 # do NOT auto-import them. Consumer (or demo shell) must explicitly import.
 composes:
@@ -50,7 +56,15 @@ states:
 traits: []
 tokens: {}
 a2ui:
-  rules: []
+  rules:
+    - rule: 'Row of follow-up suggestion chips presented under an agent response. User taps to send the chip text as the next prompt.'
+      reason: 'Follow-up pattern.'
+    - rule: 'Hosts <button-ui> children with chip-style variant; auto-applies variant if children don''t set one.'
+      reason: 'Composition behavior.'
+    - rule: 'Different from <agent-questions-ui> (required disambiguation) — suggestions are optional and the agent doesn''t wait.'
+      reason: 'Optional vs gating.'
+    - rule: 'Place at the end of an assistant message in <chat-thread-ui>; not for first-message empty-state suggestions (use <empty-state-ui>).'
+      reason: 'Surface scope.'
 anti_patterns: []
 examples:
   - name: basic
@@ -67,7 +81,8 @@ keywords:
   - chips
   - follow-up
   - quick replies
-synonyms: {}
+synonyms:
+  suggestions: [follow-ups, follow-up-chips, prompts, completions]
 related:
   - agent-questions-ui
   - agent-feedback-bar-ui