@adia-ai/a2ui-corpus 0.6.21 → 0.6.23

package/catalog-a2ui_0_9.json

@@ -122,7 +122,13 @@
             "name": "active"
           }
         ],
-        "synonyms": {},
+        "synonyms": {
+          "a2ui-root": [
+            "a2ui-canvas-host",
+            "a2ui-mount",
+            "doc-root"
+          ]
+        },
         "tag": "a2ui-root",
         "tokens": {},
         "traits": [],
@@ -131,7 +137,7 @@
     },
     "Accordion": {
       "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": [
         {
@@ -311,9 +317,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."
@@ -323,7 +339,14 @@
           }
         },
         "states": [],
-        "synonyms": {},
+        "synonyms": {
+          "accordion-item": [
+            "collapsible-row",
+            "disclosure-row",
+            "expansion-panel",
+            "expander"
+          ]
+        },
         "tag": "accordion-item-ui",
         "tokens": {},
         "traits": [],
@@ -379,12 +402,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": [],
@@ -451,7 +490,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."
@@ -463,7 +506,13 @@
             "name": "idle"
           }
         ],
-        "synonyms": {},
+        "synonyms": {
+          "action-list": [
+            "command-list",
+            "action-rows",
+            "command-rows"
+          ]
+        },
         "tag": "action-list-ui",
         "tokens": {},
         "traits": [],
@@ -472,7 +521,7 @@
     },
     "AdminCommand": {
       "title": "AdminCommand",
-      "description": "Module-tier command palette wrapper — wraps a native <dialog> and the\ninner <command-ui>. Owns the keyboard shortcut listener, focus\nmanagement, and dismiss handlers. Reflects [open].\n\nSits inside <admin-shell> as a direct child. The host wires\n[data-command-trigger] elements to <admin-command>.show() via lookup.\n\nThis is the bespoke web-component replacement for the legacy\n<dialog data-command> shape. <admin-shell> still recognizes the\nlegacy shape via :is() selector. New code should prefer <admin-command>.\n",
+      "description": "Module-tier command palette wrapper — wraps a native <dialog> and the\ninner <command-ui>. Owns the keyboard shortcut listener, focus\nmanagement, and dismiss handlers. Reflects [open].\n\nSits inside <admin-shell> as a direct child. The host wires\n[data-command-trigger] elements to <admin-command>.show() via lookup.\n\nThis is the bespoke web-component replacement for the legacy\n<dialog data-command> shape per ADR-0023. The legacy shape was\nretired in v0.4.0 per ADR-0024 and is no longer recognized.\n",
       "type": "object",
       "allOf": [
         {
@@ -573,7 +622,7 @@
     },
     "AdminContent": {
       "title": "AdminContent",
-      "description": "Module-tier shell main-column container. CSS-only — no behavior, no\nJS. Sits inside <admin-shell> as the center column between leading\nand trailing sidebars. Authors compose chrome bars + scroll surface\nvia slot vocabulary.\n\nThis is the bespoke replacement for the legacy raw <main> element\ninside admin-shell. Both shapes still render correctly per ADR-0023\nPhase 1 backwards-compat; new code should prefer <admin-content>.\n",
+      "description": "Module-tier shell main-column container. CSS-only — no behavior, no\nJS. Sits inside <admin-shell> as the center column between leading\nand trailing sidebars. Authors compose chrome bars + scroll surface\nvia slot vocabulary.\n\nThis is the bespoke replacement for the legacy raw <main> element\ninside admin-shell per ADR-0023. The legacy shape was retired in\nv0.4.0 per ADR-0024 and is no longer recognized.\n",
       "type": "object",
       "allOf": [
         {
@@ -978,7 +1027,7 @@
     },
     "AdminSidebar": {
       "title": "AdminSidebar",
-      "description": "Module-tier shell sidebar — owns resize, snap-to-collapsed, persistence,\nand the [collapsed] reflected attribute. Sits inside <admin-shell> as\nslot=\"leading\" or slot=\"trailing\". Authors compose chrome bars + content\ninside via slot vocabulary.\n\nThis is the bespoke web-component replacement for the legacy\n<aside data-sidebar> shape. <admin-shell> still recognizes the legacy\nshape via :is() selector for backwards compat. New code should prefer\n<admin-sidebar>.\n",
+      "description": "Module-tier shell sidebar — owns resize, snap-to-collapsed, persistence,\nand the [collapsed] reflected attribute. Sits inside <admin-shell> as\nslot=\"leading\" or slot=\"trailing\". Authors compose chrome bars + content\ninside via slot vocabulary.\n\nThis is the bespoke web-component replacement for the legacy\n<aside data-sidebar> shape per ADR-0023. The legacy shape was\nretired in v0.4.0 per ADR-0024 and is no longer recognized.\n",
       "type": "object",
       "allOf": [
         {
@@ -1115,7 +1164,7 @@
     },
     "AdminStatusbar": {
       "title": "AdminStatusbar",
-      "description": "Module-tier shell bottom chrome bar. CSS-only — no behavior, no JS.\nSame shape as <admin-topbar> (icon + heading + description + action\nclusters via slot vocabulary), conventionally used for read-only\nstatus — connection state, sync indicator, footer metadata.\n\nReplaces legacy <footer-ui> usage at shell-tier. Both still work per\nADR-0023 backwards-compat.\n",
+      "description": "Module-tier shell bottom chrome bar. CSS-only — no behavior, no JS.\nSame shape as <admin-topbar> (icon + heading + description + action\nclusters via slot vocabulary), conventionally used for read-only\nstatus — connection state, sync indicator, footer metadata.\n\nReplaces legacy <footer-ui> usage at shell-tier per ADR-0023. The\nlegacy shape was retired in v0.4.0 per ADR-0024 and is no longer\nrecognized; new code uses <admin-statusbar> for shell-tier chrome\n(use <footer-ui> for primitive containers like Card / Drawer /\nModal).\n",
       "type": "object",
       "allOf": [
         {
@@ -1196,7 +1245,7 @@
     },
     "AdminTopbar": {
       "title": "AdminTopbar",
-      "description": "Module-tier shell top chrome bar. CSS-only — no behavior, no JS.\nSits at the top of <admin-content>, <admin-sidebar>, or any chrome\nregion. Provides the canonical icon + heading + description +\naction-clusters layout via slot vocabulary.\n\nReplaces the legacy <header-ui> usage at shell-tier. Both still work\nper ADR-0023 backwards-compat; new code should prefer <admin-topbar>\nfor shell-tier chrome bars (use <header-ui> for primitive containers\nlike Card / Drawer / Modal).\n",
+      "description": "Module-tier shell top chrome bar. CSS-only — no behavior, no JS.\nSits at the top of <admin-content>, <admin-sidebar>, or any chrome\nregion. Provides the canonical icon + heading + description +\naction-clusters layout via slot vocabulary.\n\nReplaces the legacy <header-ui> usage at shell-tier per ADR-0023.\nThe legacy shape was retired in v0.4.0 per ADR-0024 and is no\nlonger recognized; new code uses <admin-topbar> for shell-tier\nchrome bars (use <header-ui> for primitive containers like Card /\nDrawer / Modal).\n",
       "type": "object",
       "allOf": [
         {
@@ -1279,7 +1328,7 @@
     },
     "AgentArtifact": {
       "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": [
         {
@@ -1377,7 +1426,14 @@
             "name": "idle"
           }
         ],
-        "synonyms": {},
+        "synonyms": {
+          "artifact": [
+            "agent-artifact",
+            "tool-output",
+            "agent-output",
+            "tool-result"
+          ]
+        },
         "tag": "agent-artifact-ui",
         "tokens": {},
         "traits": [],
@@ -1386,7 +1442,7 @@
     },
     "AgentFeedbackBar": {
       "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": [
         {
@@ -1475,7 +1531,14 @@
             "name": "disabled"
           }
         ],
-        "synonyms": {},
+        "synonyms": {
+          "feedback-bar": [
+            "agent-feedback",
+            "response-feedback",
+            "thumbs-bar",
+            "rating-bar"
+          ]
+        },
         "tag": "agent-feedback-bar-ui",
         "tokens": {},
         "traits": [],
@@ -1484,7 +1547,7 @@
     },
     "AgentQuestions": {
       "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": [
         {
@@ -1575,7 +1638,13 @@
             "name": "idle"
           }
         ],
-        "synonyms": {},
+        "synonyms": {
+          "questions": [
+            "clarifying-questions",
+            "agent-prompt",
+            "disambiguation"
+          ]
+        },
         "tag": "agent-questions-ui",
         "tokens": {},
         "traits": [],
@@ -1714,7 +1783,7 @@
     },
     "AgentSuggestions": {
       "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": [
         {
@@ -1807,7 +1876,14 @@
             "name": "disabled"
           }
         ],
-        "synonyms": {},
+        "synonyms": {
+          "suggestions": [
+            "follow-ups",
+            "follow-up-chips",
+            "prompts",
+            "completions"
+          ]
+        },
         "tag": "agent-suggestions-ui",
         "tokens": {},
         "traits": [],
@@ -1816,7 +1892,7 @@
     },
     "AgentTrace": {
       "title": "AgentTrace",
-      "description": "Collapsible metrics + training-feedback panel for an agent turn.",
+      "description": "Collapsible metrics + training-feedback panel for an agent turn. Shows reasoning steps, tool calls, latency, and token counts with a thumbs-up/down feedback affordance. Use inside <chat-thread-ui> message bodies for expert/debug views; hide by default in user-facing chat.",
       "type": "object",
       "allOf": [
         {
@@ -1890,7 +1966,14 @@
             "name": "idle"
           }
         ],
-        "synonyms": {},
+        "synonyms": {
+          "trace": [
+            "agent-trace",
+            "reasoning-trace",
+            "tool-trace",
+            "agent-log"
+          ]
+        },
         "tag": "agent-trace-ui",
         "tokens": {},
         "traits": [],
@@ -1899,7 +1982,7 @@
     },
     "Alert": {
       "title": "Alert",
-      "description": "Inline alert banner with optional icon and close button.",
+      "description": "Inline alert banner — a persistent, in-flow notice with icon +\ntitle + description + optional dismiss + slotted action. Variants\nmap to semantic severity (info / success / warning / danger).\nDistinct from <toast-ui> (transient global notification with\nauto-dismiss) and from <empty-state-ui> (zero-data placeholder).\nUse alert-ui for inline contextual notices the user should see\nbefore continuing — form-level errors, banner-style status,\ninline upgrade prompts.\n",
       "type": "object",
       "allOf": [
         {
@@ -2129,7 +2212,7 @@
     },
     "AppShell": {
       "title": "AppShell",
-      "description": "Behavior-only application shell. Wires sidebar toggles, resize handles,\na Cmd+K command palette, and a ResizeObserver that drives responsive\nsidebar collapse. Author supplies the DOM (aside[data-sidebar], main,\ndialog[data-command]); admin-shell binds the interactions.\n",
+      "description": "Behavior-only application shell. Canonical authoring shape uses\ncluster-namespaced bespoke children — <admin-topbar> at the top,\n<admin-sidebar slot=\"leading|trailing\"> rails, <admin-content> for\nthe main content region, <admin-command> for the Cmd+K palette, and\noptional <admin-statusbar> at the bottom. The shell wires sidebar\ntoggle forwarding, command-palette triggers, and the ResizeObserver\nthat drives responsive sidebar collapse; each bespoke child owns\nits own resize / collapse / open state-as-attribute semantics per\nADR-0023.\n\nLegacy data-attribute shapes (<aside data-sidebar>, <dialog\ndata-command>, [data-resize], <aside-ui slot=>, <span data-spacer>,\n<div data-actions>) were RETIRED in v0.4.0 per ADR-0024 and are no\nlonger recognized. Consumers must use the bespoke vocabulary.\n",
       "type": "object",
       "allOf": [
         {
@@ -2201,19 +2284,19 @@
             "description": "Secondary metadata inside any chrome bar. Muted + --a-ui-sm size."
           },
           "default": {
-            "description": "Author-supplied page DOM. Expected structure — aside[data-sidebar] for navigation, main for content, optional dialog[data-command] for Cmd+K."
+            "description": "Bespoke children compose here in document order — <admin-topbar>, <admin-sidebar slot=\"leading\">, <admin-content> (containing <admin-page> / <admin-page-header> / <admin-page-body>), <admin-sidebar slot=\"trailing\">, <admin-command>, optional <admin-statusbar>. The shell's grid layout reads child tag selectors to place them."
           },
           "action": {
-            "description": "Trailing control cluster inside any chrome bar. The first [slot=\"action\"] child pushes itself (and siblings) to the end; subsequent siblings flow with gap. Coexists with legacy <span data-spacer> / <div data-actions> hooks for one release — new code should prefer slots."
+            "description": "Trailing control cluster inside any chrome bar. The first [slot=\"action\"] child pushes itself (and siblings) to the end; subsequent siblings flow with gap."
           },
           "action-leading": {
-            "description": "Leading (inline-start) control cluster inside any chrome bar. Pairs with [slot=\"action\"] for dual-cluster chrome (e.g. back button + breadcrumb on the left, primary actions on the right). Replaces the legacy <span data-spacer> hack."
+            "description": "Leading (inline-start) control cluster inside any chrome bar. Pairs with [slot=\"action\"] for dual-cluster chrome (e.g. back button + breadcrumb on the left, primary actions on the right)."
           },
           "heading": {
             "description": "Primary label inside any chrome bar. Medium-weight + strong fg."
           },
           "icon": {
-            "description": "Leading glyph inside any chrome bar — > main > header / footer and [data-sidebar] > header / footer. Muted color, flex-align."
+            "description": "Leading glyph inside any chrome bar (<admin-topbar>, <admin-statusbar>, <admin-sidebar> header/footer). Muted color, flex-align."
           }
         },
         "states": [
@@ -2316,7 +2399,13 @@
             "name": "idle"
           }
         ],
-        "synonyms": {},
+        "synonyms": {
+          "aside": [
+            "side-region",
+            "side-panel-slot",
+            "secondary-rail"
+          ]
+        },
         "tag": "aside-ui",
         "tokens": {},
         "traits": [],
@@ -2325,7 +2414,7 @@
     },
     "Avatar": {
       "title": "Avatar",
-      "description": "Avatar with image → initials → empty fallback chain.",
+      "description": "User-portrait primitive with an image → initials → icon fallback\nchain. Resolves the leading [src] image; on load failure falls back\nto [text]-derived initials; on missing text falls back to a slotted\nor default <icon-ui>. Use for user identity in chat surfaces,\nmember tables, statusbar account chips, comment threads. Pair via\n<avatar-group-ui> for stacked / overflowed sets.\n",
       "type": "object",
       "allOf": [
         {
@@ -2568,12 +2657,29 @@
         "composes": [],
         "events": {},
         "examples": [],
-        "keywords": [],
+        "keywords": [
+          "avatar-group",
+          "avatar-stack",
+          "user-group",
+          "facepile",
+          "people-stack",
+          "overflow-avatars"
+        ],
         "name": "UIAvatarGroup",
-        "related": [],
+        "related": [
+          "Avatar",
+          "Tag"
+        ],
         "slots": {},
         "states": [],
-        "synonyms": {},
+        "synonyms": {
+          "avatar-group": [
+            "facepile",
+            "user-stack",
+            "people-pile",
+            "avatar-pile"
+          ]
+        },
         "tag": "avatar-group-ui",
         "tokens": {},
         "traits": [],
@@ -2582,7 +2688,7 @@
     },
     "Badge": {
       "title": "Badge",
-      "description": "Inline pill-shaped badge/tag. Text rendered via CSS attr().",
+      "description": "Inline pill-shaped badge — READ-ONLY status flag, count, or\nnotification dot. Text rendered via CSS `attr(text)`. Distinct from\n<tag-ui>, which is INTERACTIVE / removable and fires a `remove`\nevent. Use badge-ui for status flags (Beta / New / Deprecated),\nnotification counts, and unread indicators; use tag-ui for filter\nchips or user-managed labels.\n",
       "type": "object",
       "allOf": [
         {
@@ -2754,7 +2860,7 @@
     },
     "Block": {
       "title": "Block",
-      "description": "Generic padded/margined content wrapper.",
+      "description": "Generic padded / margined content wrapper. Applies a configurable\npadding + margin scale via [padding] / [margin] attribute props,\nmapping to the canonical spacing tokens. Use as a lightweight\nspacing wrapper when <section-ui> would imply chrome the parent\ncontainer doesn't own. Not a layout primitive (no flex / grid) —\nfor layout use <col-ui> / <row-ui> / <stack-ui> / <grid-ui>.\n",
       "type": "object",
       "allOf": [
         {
@@ -2769,7 +2875,7 @@
           "const": "Block"
         },
         "margin": {
-          "description": "Margin size",
+          "description": "Margin size (none/xs/sm/md/lg/xl). Accepts `@bp` notation: margin=\"none sm@md\" = no margin below md, sm from md up.",
           "type": "string",
           "enum": [
             "none",
@@ -2782,7 +2888,7 @@
           "default": "none"
         },
         "padding": {
-          "description": "Padding amount, maps to spacing tokens",
+          "description": "Padding amount (none/xs/sm/md/lg/xl → spacing tokens). Accepts `@bp` notation: padding=\"sm md@lg\" = sm below lg, md from lg up.",
           "type": "string",
           "enum": [
             "none",
@@ -2823,7 +2929,12 @@
           "developer"
         ],
         "name": "UIBlock",
-        "related": [],
+        "related": [
+          "Section",
+          "Col",
+          "Row",
+          "Stack"
+        ],
         "slots": {},
         "states": [
           {
@@ -2951,7 +3062,11 @@
           "back"
         ],
         "name": "UIBreadcrumb",
-        "related": [],
+        "related": [
+          "AdminTopbar",
+          "Nav",
+          "Tabs"
+        ],
         "slots": {},
         "states": [
           {
@@ -3104,7 +3219,16 @@
           }
         },
         "examples": [],
-        "keywords": [],
+        "keywords": [
+          "button",
+          "action",
+          "cta",
+          "submit",
+          "click",
+          "primary-action",
+          "ghost-button",
+          "icon-button"
+        ],
         "name": "UIButton",
         "related": [
           "Link"
@@ -3143,7 +3267,18 @@
             "selector": ":active"
           }
         ],
-        "synonyms": {},
+        "synonyms": {
+          "button": [
+            "btn",
+            "action-button",
+            "click-target",
+            "control"
+          ],
+          "submit": [
+            "form-submit",
+            "primary-action"
+          ]
+        },
         "tag": "button-ui",
         "tokens": {
           "--button-background": {
@@ -3183,7 +3318,7 @@
     },
     "CalendarPicker": {
       "title": "CalendarPicker",
-      "description": "Date picker with trigger button and popover calendar grid. Form-associated.",
+      "description": "Date picker with trigger button and popover calendar grid. Form-associated input emitting ISO date string via change events; supports min/max and disabled-date masks. Use for single-date input in forms; for date ranges compose two pickers or use a dedicated range component.",
       "type": "object",
       "allOf": [
         {
@@ -3326,7 +3461,7 @@
     },
     "Canvas": {
       "title": "Canvas",
-      "description": "A2UI rendering surface.",
+      "description": "A2UI rendering surface — the canonical mount point that consumes a\nDocStore / A2UI document and renders the component tree from it.\nThe runtime's <a2ui-root> typically wraps a canvas-ui internally\nfor the preview pane in <editor-canvas>. Use for embedding live\nA2UI output inside a custom editor, playground, or preview surface;\nnot for generic in-page canvases (use HTML <canvas> for drawing).\n",
       "type": "object",
       "allOf": [
         {
@@ -3370,7 +3505,11 @@
           "canvas"
         ],
         "name": "UICanvas",
-        "related": [],
+        "related": [
+          "A2uiRoot",
+          "GenRoot",
+          "EditorCanvas"
+        ],
         "slots": {
           "default": {
             "description": "Default slot — primary child content."
@@ -4149,7 +4288,7 @@
     },
     "ChatComposer": {
       "title": "ChatComposer",
-      "description": "Module-tier chat composer wrapper — replaces legacy <chat-input-ui\ndata-chat-input> direct child of <chat-shell> per ADR-0023.\nForwards submit events as 'composer-submit', propagates [disabled]\nto the inner input, provides slot vocabulary for future composer\nsurfaces (file attach, autocomplete, model picker).\n\nSits inside <chat-shell> as the input region (typically inside or\nalongside the footer). Authors place an inner <chat-input-ui>\n(or input-ui / textarea-ui) as the primary input.\n\nBackwards compat — <chat-shell> still recognizes the legacy\n<chat-input-ui data-chat-input> shape via :is() selector. New\ncode should prefer <chat-composer>.\n",
+      "description": "Module-tier chat composer wrapper — replaces legacy <chat-input-ui\ndata-chat-input> direct child of <chat-shell> per ADR-0023.\nForwards submit events as 'composer-submit', propagates [disabled]\nto the inner input, provides slot vocabulary for future composer\nsurfaces (file attach, autocomplete, model picker).\n\nSits inside <chat-shell> as the input region (typically inside or\nalongside the footer). Authors place an inner <chat-input-ui>\n(or input-ui / textarea-ui) as the primary input.\n",
       "type": "object",
       "allOf": [
         {
@@ -4242,7 +4381,7 @@
     },
     "ChatEmpty": {
       "title": "ChatEmpty",
-      "description": "Module-tier chat empty state. CSS-only — no behavior, no JS. Sits\nas the first child of <chat-thread> as the empty state placeholder.\nVisibility is driven by <chat-thread>'s [empty] reflected attribute\nvia CSS (no JS toggling needed) — when messages arrive, the parent\nthread loses [empty] and CSS hides this stub.\n\nReplaces the legacy <empty-state-ui data-chat-empty> child of the\nmessages container per ADR-0023. Both shapes still work via\nbackwards compat; new code should prefer <chat-empty>.\n",
+      "description": "Module-tier chat empty state. CSS-only — no behavior, no JS. Sits\nas the first child of <chat-thread> as the empty state placeholder.\nVisibility is driven by <chat-thread>'s [empty] reflected attribute\nvia CSS (no JS toggling needed) — when messages arrive, the parent\nthread loses [empty] and CSS hides this stub.\n\nReplaces the legacy <empty-state-ui data-chat-empty> child of the\nmessages container per ADR-0023. The legacy shape was retired in\nv0.4.0 per ADR-0024 and is no longer recognized.\n",
       "type": "object",
       "allOf": [
         {
@@ -4309,7 +4448,7 @@
     },
     "ChatHeader": {
       "title": "ChatHeader",
-      "description": "Module-tier chat header chrome bar. CSS-only — no behavior, no JS.\nSits at the top of <chat-shell> or inside a <chat-sidebar>. Holds\nthe chat name, status indicator, and action clusters via slot\nvocabulary.\n\nReplaces the legacy <header> with [data-chat-name] / [data-chat-status]\ndata-attribute children. Both shapes still work per ADR-0023 backwards\ncompat; new code should prefer <chat-header> with <chat-status> as\na slotted child.\n",
+      "description": "Module-tier chat header chrome bar. CSS-only — no behavior, no JS.\nSits at the top of <chat-shell> or inside a <chat-sidebar>. Holds\nthe chat name, status indicator, and action clusters via slot\nvocabulary.\n\nReplaces the legacy <header> with [data-chat-name] / [data-chat-status]\ndata-attribute children per ADR-0023. The legacy shape was retired\nin v0.4.0 per ADR-0024 and is no longer recognized; new code uses\n<chat-header> with <chat-status> as a slotted child.\n",
       "type": "object",
       "allOf": [
         {
@@ -4541,7 +4680,7 @@
     },
     "ChatShell": {
       "title": "ChatShell",
-      "description": "Behavior-only chat orchestrator (LLM-streaming module). Author supplies the\nDOM structure via [data-chat-messages], [data-chat-input], [data-chat-empty],\n[data-chat-status] elements; chat-shell wires message streaming, markdown\nrendering, code-block upgrades, and an LLM integration path via proxy-url\n(or via external submit).\n",
+      "description": "Behavior-only chat orchestrator (LLM-streaming module). Canonical\nauthoring shape uses cluster-namespaced bespoke children —\n<chat-thread> as the message scroll surface (containing <chat-empty>\nas the empty-state slot), <chat-composer> wrapping the input\nprimitive, and optional <chat-header> / <chat-sidebar> / <chat-status>\nchrome. The shell wires LLM streaming, markdown rendering, code-block\nupgrades, and the proxy-url integration path; each bespoke child owns\nits own [streaming] / [empty] / [disabled] state-as-attribute\nsemantics per ADR-0023.\n\nLegacy data-attribute shapes (<section data-chat-messages>,\n<chat-input-ui data-chat-input>, <empty-state-ui data-chat-empty>,\n<header data-chat-name>) were RETIRED in v0.4.0 per ADR-0024 and\nare no longer recognized. Consumers must use the bespoke vocabulary.\n",
       "type": "object",
       "allOf": [
         {
@@ -4571,7 +4710,7 @@
           "default": ""
         },
         "streaming": {
-          "description": "Active streaming indicator; toggled while a response is being received.",
+          "description": "Active streaming indicator; toggled while a response is being received. Propagated to <chat-thread>[streaming] and <chat-composer>[disabled].",
           "type": "boolean",
           "default": false
         },
@@ -4633,7 +4772,7 @@
             }
           },
           "submit": {
-            "description": "Fired on user message submit (before LLM call begins).",
+            "description": "Fired on user message submit (before LLM call begins). Forwarded from <chat-composer>'s composer-submit event.",
             "detail": {
               "model": "string",
               "text": "string"
@@ -4653,16 +4792,23 @@
           "llm",
           "streaming",
           "conversation",
-          "agent"
+          "agent",
+          "assistant"
         ],
         "name": "ChatShell",
         "related": [
+          "ChatThread",
+          "ChatComposer",
+          "ChatEmpty",
+          "ChatHeader",
+          "ChatSidebar",
+          "ChatStatus",
           "ChatInput",
           "Code"
         ],
         "slots": {
           "default": {
-            "description": "Author provides the structural DOM. Expected markers — [data-chat-messages] (message list), [data-chat-input] (input surface), [data-chat-empty] (empty state), [data-chat-status] (streaming indicator)."
+            "description": "Bespoke children compose here in document order — typically <chat-thread> (with optional <chat-empty> inside) for the message surface, then <chat-composer> wrapping a <chat-input-ui submit-on-enter> for the input. Optional <chat-header>, <chat-sidebar slot=\"leading|trailing\">, <chat-status>."
           }
         },
         "states": [
@@ -4671,7 +4817,7 @@
             "name": "idle"
           },
           {
-            "description": "An LLM request is in-flight; [data-chat-status] visible.",
+            "description": "An LLM request is in-flight; child <chat-thread>[streaming] + <chat-composer>[disabled] propagate from this attribute.",
             "attribute": "streaming",
             "name": "streaming"
           }
@@ -4680,7 +4826,9 @@
           "chat": [
             "conversation",
             "messages",
-            "thread"
+            "thread",
+            "assistant",
+            "agent"
           ]
         },
         "tag": "chat-shell",
@@ -4888,7 +5036,7 @@
     },
     "ChatThread": {
       "title": "ChatThread",
-      "description": "Module-tier chat message thread container — replaces legacy\n<section data-chat-messages> per ADR-0023. Owns scroll-to-bottom\non new message (with user-scroll-up suspension), [streaming] and\n[empty] reflected attributes, and a stable target for the host's\nmessage rendering pipeline.\n\nSits inside <chat-shell> as the central scroll surface. Authors\ncompose <chat-empty> as an optional first child for the empty\nstate; message children are appended dynamically by the host.\n\nBackwards compat — <chat-shell> still recognizes the legacy\n<section data-chat-messages> shape via :is() selector. New code\nshould prefer <chat-thread>.\n",
+      "description": "Module-tier chat message thread container — replaces legacy\n<section data-chat-messages> per ADR-0023. Owns scroll-to-bottom\non new message (with user-scroll-up suspension), [streaming] and\n[empty] reflected attributes, and a stable target for the host's\nmessage rendering pipeline.\n\nSits inside <chat-shell> as the central scroll surface. Authors compose <chat-empty> as an optional first child for the empty state; message children are appended dynamically by the host.\n",
       "type": "object",
       "allOf": [
         {
@@ -4984,7 +5132,7 @@
     },
     "Check": {
       "title": "Check",
-      "description": "Checkbox. The host IS the control.",
+      "description": "Checkbox primitive — the host IS the control (per ADR-0025, no\nnative <input> wrapped underneath). Form-bearing via UIFormElement:\n[name], [value], [checked] (reflect), [indeterminate], [required],\n[disabled]. Wrap in <field-ui label=\"…\" hint=\"…\"> for the canonical\nlabeled stack, or set inline [label] / [hint] props. Distinct from\n<switch-ui> (binary on/off toggle) — use check-ui for opt-in lists\nand form acknowledgements, switch-ui for setting-style toggles.\n",
       "type": "object",
       "allOf": [
         {
@@ -5070,7 +5218,11 @@
           "check"
         ],
         "name": "UICheck",
-        "related": [],
+        "related": [
+          "Switch",
+          "Radio",
+          "Field"
+        ],
         "slots": {
           "box": {
             "description": "Visual checkbox indicator"
@@ -5093,7 +5245,13 @@
             "name": "disabled"
           }
         ],
-        "synonyms": {},
+        "synonyms": {
+          "checkbox": [
+            "check",
+            "tickbox",
+            "boolean-input"
+          ]
+        },
         "tag": "check-ui",
         "tokens": {
           "--check-box-background": {
@@ -5124,7 +5282,7 @@
     },
     "Code": {
       "title": "Code",
-      "description": "Inline or block code display with optional language label and copy button.",
+      "description": "Inline or block code display with optional language label and copy button. Renders preformatted text with monospace font and code-block tokens; syntax highlighting is opt-in via the language attribute. Use for code snippets in documentation, chat, or artifact panes; for editable code use <richtext-ui> with a code variant.",
       "type": "object",
       "allOf": [
         {
@@ -5363,7 +5521,7 @@
     },
     "Col": {
       "title": "Col",
-      "description": "Flex column layout primitive.",
+      "description": "Flex column layout primitive — vertical stack of children with\n[gap] / [align] / [justify] / [grow]. The most common layout\nprimitive in the repo. Use <col-ui> for vertical stacks, <row-ui>\nfor horizontal rows, <stack-ui> for overlay (children stack on top\nof each other in a grid), <grid-ui> for 2D grids. Composes inside\n<section-ui> for in-card layout; do NOT use as a child of\n<header-ui> / <footer-ui> (the chrome scope already lays out\nslots).\n",
       "type": "object",
       "allOf": [
         {
@@ -5375,7 +5533,7 @@
       ],
       "properties": {
         "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"
         },
@@ -5383,7 +5541,7 @@
           "const": "Col"
         },
         "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).",
+          "description": "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"
         },
@@ -5393,7 +5551,7 @@
           "default": false
         },
         "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"
         }
@@ -5442,7 +5600,14 @@
             "name": "idle"
           }
         ],
-        "synonyms": {},
+        "synonyms": {
+          "column": [
+            "col",
+            "vstack",
+            "vertical-stack",
+            "vbox"
+          ]
+        },
         "tag": "col-ui",
         "tokens": {},
         "traits": [],
@@ -5667,7 +5832,7 @@
     },
     "ColorPicker": {
       "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": [
         {
@@ -5793,7 +5958,13 @@
             "name": "disabled"
           }
         ],
-        "synonyms": {},
+        "synonyms": {
+          "color-picker": [
+            "color-canvas",
+            "color-surface",
+            "swatch-picker"
+          ]
+        },
         "tag": "color-picker-ui",
         "tokens": {},
         "traits": [],
@@ -5802,7 +5973,7 @@
     },
     "Command": {
       "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": [
         {
@@ -5888,7 +6059,12 @@
           "keybinding"
         ],
         "name": "UICommand",
-        "related": [],
+        "related": [
+          "AdminCommand",
+          "Menu",
+          "Modal",
+          "Search"
+        ],
         "slots": {
           "empty": {
             "description": "Empty state shown when no items match"
@@ -6250,7 +6426,11 @@
           "dl"
         ],
         "name": "UIDescriptionList",
-        "related": [],
+        "related": [
+          "List",
+          "Field",
+          "Section"
+        ],
         "slots": {
           "[object Object]": {
             "description": "Child content region for the `[object Object]` slot."
@@ -6279,7 +6459,7 @@
     },
     "Divider": {
       "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": [
         {
@@ -6608,7 +6788,7 @@
     },
     "EditorCanvas": {
       "title": "EditorCanvas",
-      "description": "Module-tier editor canvas surface — replaces legacy <div data-canvas>\ninside <editor-shell> per ADR-0023. Owns scroll/zoom container\nsemantics, [empty] and [focused] reflected attributes, and a stable\ntarget for the host's content rendering pipeline.\n\nSits as the central content region inside <editor-shell>, between\nthe optional <editor-sidebar slot=\"leading\"> and <editor-sidebar\nslot=\"trailing\">. Authors compose <editor-canvas-empty> as an\noptional first child for the empty state; canvas content children\n(artboards, document body, etc.) are appended either statically or\ndynamically by the host.\n\nBackwards compat — <editor-shell> still recognizes the legacy\n<div data-canvas> shape via :is() selector. New code should prefer\n<editor-canvas>.\n",
+      "description": "Module-tier editor canvas surface — replaces legacy <div data-canvas>\ninside <editor-shell> per ADR-0023. Owns scroll/zoom container\nsemantics, [empty] and [focused] reflected attributes, and a stable\ntarget for the host's content rendering pipeline.\n\nSits as the central content region inside <editor-shell>, between\nthe optional <editor-sidebar slot=\"leading\"> and <editor-sidebar\nslot=\"trailing\">. Authors compose <editor-canvas-empty> as an\noptional first child for the empty state; canvas content children\n(artboards, document body, etc.) are appended either statically or\ndynamically by the host.\n",
       "type": "object",
       "allOf": [
         {
@@ -6842,7 +7022,7 @@
     },
     "EditorShell": {
       "title": "EditorShell",
-      "description": "Behavior-only editor shell module for design-tool layouts. Author\nprovides the structural DOM — header (topbar), [data-editor-body] with\npane-ui children ([data-left], [data-right]), [data-canvas] for the\ncentral surface, and a footer (statusbar). editor-shell wires\nselect-ui[data-options] for JSON-parsed option lists.\n",
+      "description": "Behavior-only editor shell for design-tool / code-editor / canvas\nlayouts. Canonical authoring shape uses cluster-namespaced bespoke\nchildren — <editor-toolbar> at the top, <editor-sidebar\nslot=\"leading|trailing\"> rails wrapping <pane-ui resizable>,\n<editor-canvas> as the central work surface (optionally containing\n<editor-canvas-toolbar> + <editor-canvas-empty>), and\n<editor-statusbar> at the bottom. The shell coordinates the family,\npropagates [focus-mode] to children's [full-screen] / [focused],\nand lets each child own its own state-as-attribute semantics per\nADR-0023.\n\nLegacy data-attribute shapes (<header>, <div data-editor-body>,\n<pane-ui data-left|data-right>, <div data-canvas>, <footer>,\n<span data-spacer>) were RETIRED in v0.4.0 per ADR-0024 and are no\nlonger recognized. Consumers must use the bespoke vocabulary.\n",
       "type": "object",
       "allOf": [
         {
@@ -6855,6 +7035,11 @@
       "properties": {
         "component": {
           "const": "EditorShell"
+        },
+        "focusMode": {
+          "description": "Reflected — when set, the shell enters distraction-free mode and\npropagates a matching [full-screen] / [focused] state to its\nbespoke children (editor-toolbar gains [full-screen], editor-canvas\ngains [focused]). Typically toggled by a [data-toolbar-action]\nbutton inside <editor-toolbar>.\n",
+          "type": "boolean",
+          "default": false
         }
       },
       "required": [
@@ -6871,41 +7056,47 @@
           "editor-shell",
           "editor",
           "design-tool",
-          "canvas-shell"
+          "code-editor",
+          "canvas-shell",
+          "workspace-shell",
+          "editing-surface"
         ],
         "name": "EditorShell",
         "related": [
+          "EditorToolbar",
+          "EditorCanvas",
+          "EditorCanvasToolbar",
+          "EditorCanvasEmpty",
+          "EditorSidebar",
+          "EditorStatusbar",
           "Pane",
-          "Select",
-          "Toolbar"
+          "AdminShell",
+          "ChatShell"
         ],
         "slots": {
-          "description": {
-            "description": "Secondary metadata inside <header> or <footer> — document name, artboard size, zoom level, etc. Muted color, --a-ui-sm size."
-          },
           "default": {
-            "description": "Author provides header, [data-editor-body] wrapping pane-ui[data-left], [data-canvas], pane-ui[data-right], and an optional footer."
-          },
-          "action": {
-            "description": "Trailing control cluster inside <header> or <footer>. The first [slot=\"action\"] child pushes itself (and siblings) to the end of the bar; subsequent [slot=\"action\"] siblings flow with gap."
-          },
-          "action-leading": {
-            "description": "Leading (inline-start) control cluster inside <header> or <footer>. Pairs with [slot=\"action\"] to produce a dual-cluster bar with space-between alignment (e.g. Back ↔ Cancel/Next, Discard ↔ Publish). Replaces the legacy <span data-spacer> hack."
-          },
-          "heading": {
-            "description": "Primary label inside <header> or <footer>. Rendered with --editor-title-weight + the strong foreground token."
-          },
-          "icon": {
-            "description": "Leading glyph inside <header> or <footer> — status dot, app icon, zoom badge, etc. Muted color, size-aware."
+            "description": "Bespoke children compose here in document order — <editor-toolbar>, <editor-sidebar slot=\"leading\">, <editor-canvas>, <editor-sidebar slot=\"trailing\">, <editor-statusbar>. The shell's grid layout reads child tag selectors to place them; no slot= attribute is needed on the children themselves except for the leading / trailing sidebar discriminator."
           }
         },
         "states": [
           {
-            "description": "Default.",
+            "description": "Default editing mode.",
             "name": "idle"
+          },
+          {
+            "description": "Distraction-free mode active; chrome children dim or hide per their own [full-screen] / [focused] rules.",
+            "attribute": "focus-mode",
+            "name": "focus-mode"
           }
         ],
-        "synonyms": {},
+        "synonyms": {
+          "editor-shell": [
+            "design-tool-shell",
+            "code-editor-shell",
+            "workspace-shell",
+            "canvas-shell"
+          ]
+        },
         "tag": "editor-shell",
         "tokens": {},
         "traits": [],
@@ -7091,7 +7282,7 @@
     },
     "EditorToolbar": {
       "title": "EditorToolbar",
-      "description": "Module-tier editor toolbar — replaces legacy <header> chrome bar\ninside <editor-shell> per ADR-0023. Owns the [full-screen] reflected\nattribute (set when host enters focus mode), click-bubble for\n[data-toolbar-action] buttons, and slot vocabulary routing.\n\nSits at the top of <editor-shell>. Authors compose actions + status\nvia slot vocabulary. The host (<editor-shell>) reads either\n<editor-toolbar> or <header> via :is() selector for backwards compat.\n",
+      "description": "Module-tier editor toolbar — replaces legacy <header> chrome bar\ninside <editor-shell> per ADR-0023. Owns the [full-screen] reflected\nattribute (set when host enters focus mode), click-bubble for\n[data-toolbar-action] buttons, and slot vocabulary routing.\n\nSits at the top of <editor-shell>. Authors compose actions + status\nvia slot vocabulary. Replaces the legacy <header> chrome bar per\nADR-0023; the legacy shape was retired in v0.4.0 per ADR-0024 and\nis no longer recognized.\n",
       "type": "object",
       "allOf": [
         {
@@ -7186,7 +7377,7 @@
     },
     "Embed": {
       "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": [
         {
@@ -7335,7 +7526,7 @@
     },
     "EmptyState": {
       "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": [
         {
@@ -7368,6 +7559,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": [
@@ -7418,7 +7619,14 @@
             "name": "idle"
           }
         ],
-        "synonyms": {},
+        "synonyms": {
+          "empty-state": [
+            "zero-state",
+            "no-data",
+            "placeholder",
+            "empty"
+          ]
+        },
         "tag": "empty-state-ui",
         "tokens": {
           "--empty-state-action-mt": {
@@ -7512,12 +7720,32 @@
           }
         },
         "examples": [],
-        "keywords": [],
+        "keywords": [
+          "feed",
+          "notification-feed",
+          "activity-stream",
+          "toast-stack",
+          "alert-stack",
+          "snackbar-stack",
+          "notification-channel"
+        ],
         "name": "UIFeedContainer",
-        "related": [],
+        "related": [
+          "FeedItem",
+          "Toast",
+          "Alert"
+        ],
         "slots": {},
         "states": {},
-        "synonyms": {},
+        "synonyms": {
+          "feed": [
+            "notification-feed",
+            "toast-feed",
+            "alert-feed",
+            "activity-feed",
+            "snackbar-stack"
+          ]
+        },
         "tag": "feed-ui",
         "tokens": {},
         "traits": [],
@@ -7592,16 +7820,34 @@
           }
         },
         "examples": [],
-        "keywords": [],
+        "keywords": [
+          "feed-item",
+          "notification",
+          "toast-row",
+          "alert-row",
+          "feed-entry",
+          "notification-card"
+        ],
         "name": "UIFeedItem",
-        "related": [],
+        "related": [
+          "Feed",
+          "Toast",
+          "Alert"
+        ],
         "slots": {
           "body": {
             "description": "Default content slot (also accepts the `text` / `heading` props)"
           }
         },
         "states": {},
-        "synonyms": {},
+        "synonyms": {
+          "feed-item": [
+            "notification-row",
+            "toast-entry",
+            "feed-row",
+            "alert-item"
+          ]
+        },
         "tag": "feed-item-ui",
         "tokens": {},
         "traits": [],
@@ -7949,7 +8195,13 @@
             "name": "idle"
           }
         ],
-        "synonyms": {},
+        "synonyms": {
+          "footer": [
+            "footer-bar",
+            "footer-row",
+            "bottom-bar"
+          ]
+        },
         "tag": "footer-ui",
         "tokens": {},
         "traits": [],
@@ -8024,7 +8276,13 @@
             "name": "idle"
           }
         ],
-        "synonyms": {},
+        "synonyms": {
+          "gen-root": [
+            "gen-ui-root",
+            "gen-ui-mount",
+            "generative-root"
+          ]
+        },
         "tag": "gen-root",
         "tokens": {},
         "traits": [],
@@ -8033,7 +8291,7 @@
     },
     "Grid": {
       "title": "Grid",
-      "description": "CSS grid layout primitive. Supports [columns=\"1..6\"] for equal columns, [columns=\"auto-fill\"|\"auto-fit\"] for responsive density, and a per-child [span=\"2..6\"|\"full\"] attribute for asymmetric layouts. Compose a 2:1 split as columns=\"3\" + the wide child span=\"2\"; compose a 3:2 split as columns=\"5\" + span=\"3\" + span=\"2\". Never set grid-template-columns via inline style — use the span attribute on children instead.",
+      "description": "CSS grid layout primitive. Supports [columns=\"1..6\"] for equal columns, [columns=\"auto-fill\"|\"auto-fit\"] for responsive density, and a per-child [span=\"2..6\"|\"full\"] attribute for asymmetric layouts. Both [columns] and [gap] accept responsive `@bp` notation for viewport-driven layout: columns=\"1 2@sm 4@lg\" gives 1 column on xs, 2 from sm, 4 from lg/xl. Compose a 2:1 split as columns=\"3\" + span=\"2\"; 3:2 as columns=\"5\" + span=\"3\" + span=\"2\".",
       "type": "object",
       "allOf": [
         {
@@ -8050,7 +8308,7 @@
           "default": ""
         },
         "columns": {
-          "description": "Number of columns or grid-template-columns",
+          "description": "Number of equal columns (1–6), \"auto-fill\", or \"auto-fit\". Accepts responsive `@bp` notation: \"1 2@sm 4@lg\" = 1 on xs, 2 from sm, 4 from lg/xl. Unannotated value is the mobile-first base.",
           "type": "string",
           "default": "3"
         },
@@ -8058,7 +8316,7 @@
           "const": "Grid"
         },
         "gap": {
-          "description": "Grid gap",
+          "description": "Grid gap. Accepts numeric space-scale values (0–12) or named sizes (xs/sm/md/lg/xl). Responsive notation supported: \"2 4@md\" = 2 below md, 4 from md upward.",
           "type": "string",
           "default": "md"
         },
@@ -8264,7 +8522,14 @@
             "name": "idle"
           }
         ],
-        "synonyms": {},
+        "synonyms": {
+          "header": [
+            "header-bar",
+            "header-row",
+            "top-bar",
+            "chrome-top"
+          ]
+        },
         "tag": "header-ui",
         "tokens": {},
         "traits": [],
@@ -8431,7 +8696,7 @@
     },
     "Icon": {
       "title": "Icon",
-      "description": "SVG icon from the icon registry. Renders inline SVG from getIcon().",
+      "description": "SVG icon from the icon registry. Renders inline SVG from getIcon() lookups with size + color token support; the canonical icon primitive throughout AdiaUI. Use for all icon needs; do not embed raw SVG or image-based icons in composed components.",
       "type": "object",
       "allOf": [
         {
@@ -8513,7 +8778,14 @@
             "name": "idle"
           }
         ],
-        "synonyms": {},
+        "synonyms": {
+          "icon": [
+            "glyph",
+            "phosphor-icon",
+            "ui-icon",
+            "symbol"
+          ]
+        },
         "tag": "icon-ui",
         "tokens": {},
         "traits": [],
@@ -9122,7 +9394,7 @@
     },
     "Inspector": {
       "title": "Inspector",
-      "description": "Developer tools pane for inspecting A2UI state.",
+      "description": "Developer-tools pane for inspecting A2UI runtime state — composes\n<tabs-ui> + <code-ui> to show the live document JSON, rendered\nHTML, and event log for the bound <canvas-ui> / <a2ui-root>. The\nright-pane inspector of the a2ui-editor app. Use inside an\n<editor-sidebar slot=\"trailing\"> for debugging A2UI playgrounds;\nnot for end-user inspector panes (build those bespoke with\n<field-ui> + form rows per the editor-inspector-pane recipe in\npatterns-recipes.md).\n",
       "type": "object",
       "allOf": [
         {
@@ -9166,7 +9438,12 @@
           "inspector"
         ],
         "name": "UIInspector",
-        "related": [],
+        "related": [
+          "A2uiRoot",
+          "EditorSidebar",
+          "Code",
+          "Tabs"
+        ],
         "slots": {
           "default": {
             "description": "Default slot — primary child content."
@@ -9194,7 +9471,7 @@
     },
     "Kbd": {
       "title": "Kbd",
-      "description": "Keyboard key cap. Purely decorative, content from innerHTML.",
+      "description": "Keyboard key cap. Purely decorative, content from innerHTML — typically a single key or short chord like \"⌘K\" or \"Ctrl+Shift+P\". Use inline in menu items, tooltips, command hints, and shortcut documentation.",
       "type": "object",
       "allOf": [
         {
@@ -9471,7 +9748,7 @@
     },
     "List": {
       "title": "List",
-      "description": "Styled list with optional icons and dividers.",
+      "description": "Styled flat list with optional row dividers and icons — each row\nis a <list-item-ui> child. Selectable mode via [selectable] +\n[selectedKey] / `select` event. Composes <icon-ui> for row leading\nglyphs. Distinct from <nav-ui> (sidebar navigation, route-aware),\n<tree-ui> (hierarchical with arbitrary nesting), and <table-ui>\n(tabular data with columns). Use list-ui for non-navigable,\nnon-tabular vertical rows — comment lists, file lists, message\nstreams outside chat-shell.\n",
       "type": "object",
       "allOf": [
         {
@@ -9548,7 +9825,12 @@
           "star"
         ],
         "name": "UIList",
-        "related": [],
+        "related": [
+          "ListItem",
+          "Tree",
+          "Nav",
+          "Table"
+        ],
         "slots": {},
         "states": [
           {
@@ -9631,12 +9913,30 @@
         "composes": [],
         "events": {},
         "examples": [],
-        "keywords": [],
+        "keywords": [
+          "list-item",
+          "list-row",
+          "list-entry",
+          "item-row",
+          "row"
+        ],
         "name": "UIListItem",
-        "related": [],
+        "related": [
+          "List",
+          "NavItem",
+          "MenuItem",
+          "TreeItem"
+        ],
         "slots": {},
         "states": [],
-        "synonyms": {},
+        "synonyms": {
+          "list-item": [
+            "row",
+            "entry",
+            "list-row",
+            "item"
+          ]
+        },
         "tag": "list-item-ui",
         "tokens": {},
         "traits": [],
@@ -9724,7 +10024,13 @@
           "right-click"
         ],
         "name": "UIMenu",
-        "related": [],
+        "related": [
+          "MenuItem",
+          "MenuDivider",
+          "Popover",
+          "Command",
+          "Button"
+        ],
         "slots": {
           "default": {
             "description": "Menu items with role=\"menuitem\" and optional <hr> dividers"
@@ -9817,12 +10123,26 @@
         "composes": [],
         "events": {},
         "examples": [],
-        "keywords": [],
+        "keywords": [
+          "menu-divider",
+          "separator",
+          "menu-rule"
+        ],
         "name": "UIMenuDivider",
-        "related": [],
+        "related": [
+          "Menu",
+          "MenuItem",
+          "Divider"
+        ],
         "slots": {},
         "states": [],
-        "synonyms": {},
+        "synonyms": {
+          "menu-divider": [
+            "menu-separator",
+            "menu-rule",
+            "popover-divider"
+          ]
+        },
         "tag": "menu-divider-ui",
         "tokens": {},
         "traits": [],
@@ -9885,9 +10205,19 @@
         "composes": [],
         "events": {},
         "examples": [],
-        "keywords": [],
+        "keywords": [
+          "menu-item",
+          "menu-row",
+          "popover-action",
+          "dropdown-item"
+        ],
         "name": "UIMenuItem",
-        "related": [],
+        "related": [
+          "Menu",
+          "MenuDivider",
+          "Button",
+          "NavItem"
+        ],
         "slots": {
           "icon": {
             "description": "Custom leading element override; falls through to `[icon]` prop if not slotted."
@@ -9897,7 +10227,13 @@
           }
         },
         "states": [],
-        "synonyms": {},
+        "synonyms": {
+          "menu-item": [
+            "dropdown-item",
+            "menu-row",
+            "popover-action"
+          ]
+        },
         "tag": "menu-item-ui",
         "tokens": {},
         "traits": [],
@@ -9906,7 +10242,7 @@
     },
     "Modal": {
       "title": "Modal",
-      "description": "Centered dialog overlay using native <dialog>. Focus trapping, Escape key, backdrop.",
+      "description": "Centered dialog overlay using native <dialog> — same portal /\nbackdrop / focus-trap / Escape-dismiss primitives as <drawer-ui>,\nbut anchored to the viewport center with size presets. Canonical\ninner shape mirrors drawer / card: <header> + one or more <section>\n+ optional <footer>. The header stamps a built-in title bar from\n[text] plus an auto-close button (unless [permanent]). Use modal-ui\nfor centered confirmations, destructive prompts, transient previews,\nand short focused interactions; use <drawer-ui> instead for\nedge-anchored multi-field editors and mobile sheet patterns.\n",
       "type": "object",
       "allOf": [
         {
@@ -9971,7 +10307,12 @@
           "modal"
         ],
         "name": "UIModal",
-        "related": [],
+        "related": [
+          "Drawer",
+          "Card",
+          "Popover",
+          "AdminCommand"
+        ],
         "slots": {
           "default": {
             "description": "Content placed inside the modal surface. Accepts any elements (card-ui, command-ui, custom markup)."
@@ -10112,7 +10453,13 @@
           "links"
         ],
         "name": "UINav",
-        "related": [],
+        "related": [
+          "NavGroup",
+          "NavItem",
+          "Tabs",
+          "Breadcrumb",
+          "AdminSidebar"
+        ],
         "slots": {
           "default": {
             "description": "Primary slot — accepts <nav-group-ui> + <nav-item-ui> children, plus <hr data-nav-divider> for hand-placed dividers."
@@ -10128,7 +10475,15 @@
             "name": "collapsed"
           }
         ],
-        "synonyms": {},
+        "synonyms": {
+          "nav": [
+            "sidebar",
+            "side-nav",
+            "navigation-rail",
+            "primary-nav",
+            "section-nav"
+          ]
+        },
         "tag": "nav-ui",
         "tokens": {},
         "traits": [],
@@ -10222,7 +10577,11 @@
           "menu"
         ],
         "name": "UINavGroup",
-        "related": [],
+        "related": [
+          "Nav",
+          "NavItem",
+          "Accordion"
+        ],
         "slots": {
           "default": {
             "description": "Children — typically <nav-item-ui> rows."
@@ -10241,7 +10600,13 @@
             "name": "open"
           }
         ],
-        "synonyms": {},
+        "synonyms": {
+          "nav-group": [
+            "nav-section",
+            "sidebar-group",
+            "menu-group"
+          ]
+        },
         "tag": "nav-group-ui",
         "tokens": {},
         "traits": [],
@@ -10343,7 +10708,12 @@
           "sidebar"
         ],
         "name": "UINavItem",
-        "related": [],
+        "related": [
+          "Nav",
+          "NavGroup",
+          "Button",
+          "Tab"
+        ],
         "slots": {
           "default": {
             "description": "Optional override of the default icon + text + badge stamping."
@@ -10363,7 +10733,13 @@
             "name": "disabled"
           }
         ],
-        "synonyms": {},
+        "synonyms": {
+          "nav-item": [
+            "nav-link",
+            "sidebar-item",
+            "menu-link"
+          ]
+        },
         "tag": "nav-item-ui",
         "tokens": {},
         "traits": [],
@@ -10526,7 +10902,10 @@
           "noodles"
         ],
         "name": "UINoodles",
-        "related": [],
+        "related": [
+          "Canvas",
+          "EditorCanvas"
+        ],
         "slots": {},
         "states": [
           {
@@ -10539,7 +10918,14 @@
             "name": "disabled"
           }
         ],
-        "synonyms": {},
+        "synonyms": {
+          "noodles": [
+            "connection-curve",
+            "wire",
+            "edge-line",
+            "bezier-wire"
+          ]
+        },
         "tag": "noodles-ui",
         "tokens": {
           "--noodles-duration": {
@@ -11038,7 +11424,13 @@
             "name": "header-stuck"
           }
         ],
-        "synonyms": {},
+        "synonyms": {
+          "page": [
+            "page-container",
+            "route-surface",
+            "content-surface"
+          ]
+        },
         "tag": "page-ui",
         "tokens": {},
         "traits": [],
@@ -11047,7 +11439,7 @@
     },
     "Pagination": {
       "title": "Pagination",
-      "description": "Page navigation with prev/next buttons, page numbers, and ellipsis.",
+      "description": "Page navigation with prev/next buttons, page numbers, and ellipsis. Emits page-change events when buttons are clicked; visible page-number range is automatically truncated for high page counts. Use below tables, card grids, or list views; for cursor-based pagination use a custom load-more <button-ui> instead.",
       "type": "object",
       "allOf": [
         {
@@ -11164,7 +11556,7 @@
     },
     "Pane": {
       "title": "Pane",
-      "description": "Collapsible, resizable panel.",
+      "description": "Collapsible, resizable content panel — drag-resize handle on the\ninner edge when [side=\"leading\"] / [side=\"trailing\"], [resizable]\nopt-in. Used standalone for resizable two-pane layouts, or wrapped\nby <editor-sidebar> / <admin-sidebar> which DELEGATE drag to the\ninner pane-ui rather than reimplementing it. See pane.yaml's\na2ui.rules for the full composition contract.\n",
       "type": "object",
       "allOf": [
         {
@@ -11274,7 +11666,7 @@
     },
     "PipelineStatus": {
       "title": "PipelineStatus",
-      "description": "<pipeline-status-ui> — Single updating pipeline status indicator.",
+      "description": "Single updating pipeline status indicator showing current step and progress. Renders inline as a status pill with optional progress bar; updates via the status property. Use for long-running agent or build pipelines; for multi-step wizards use <stepper-ui> instead.",
       "type": "object",
       "allOf": [
         {
@@ -11342,7 +11734,11 @@
           "status"
         ],
         "name": "UIPipelineStatus",
-        "related": [],
+        "related": [
+          "AgentTrace",
+          "Stepper",
+          "StepProgress"
+        ],
         "slots": {
           "default": {
             "description": "Default slot — primary child content."
@@ -11535,7 +11931,7 @@
     },
     "Progress": {
       "title": "Progress",
-      "description": "Progress indicator. Bar (default) or spinner. Value < 0 = indeterminate.",
+      "description": "Progress indicator with bar (default) or spinner variant. Value < 0 marks indeterminate state showing animated activity instead of a fill. Use inside <progress-row-ui> for labeled task lists or standalone for global loading indicators; for percent-complete inline displays use <stat-ui> instead.",
       "type": "object",
       "allOf": [
         {
@@ -11794,7 +12190,11 @@
           "row"
         ],
         "name": "UIProgressRow",
-        "related": [],
+        "related": [
+          "Progress",
+          "StepProgress",
+          "List"
+        ],
         "slots": {
           "label": {
             "description": "Label region — control label."
@@ -11809,7 +12209,13 @@
             "name": "idle"
           }
         ],
-        "synonyms": {},
+        "synonyms": {
+          "progress-row": [
+            "task-row",
+            "progress-line",
+            "labeled-progress"
+          ]
+        },
         "tag": "progress-row-ui",
         "tokens": {},
         "traits": [],
@@ -11818,7 +12224,7 @@
     },
     "Radio": {
       "title": "Radio",
-      "description": "Radio button with pure CSS dot. Groups by name attribute. Form-associated.",
+      "description": "Radio button with pure CSS dot. Groups by name attribute (one selected value per group); form-associated and emits standard change events. Use for single-select option groups in forms; for richer styling or button-style options use <segment-ui> inside <segmented-ui> instead.",
       "type": "object",
       "allOf": [
         {
@@ -12296,7 +12702,10 @@
           "like"
         ],
         "name": "UIRating",
-        "related": [],
+        "related": [
+          "Field",
+          "AgentFeedbackBar"
+        ],
         "slots": {},
         "states": [
           {
@@ -12320,7 +12729,7 @@
     },
     "RichText": {
       "title": "RichText",
-      "description": "Renders markdown to styled HTML.",
+      "description": "Markdown-to-HTML rendering primitive — converts the [markdown] prop\n(or fetched [src] content) into styled HTML using the canonical\nprose tokens. Used for rendering LLM responses inside chat surfaces,\narticle bodies, and documentation pages. Distinct from <code-ui>\n(syntax-highlighted code), <textarea-ui> (interactive editor), and\n<text-ui> (single-line typography). Not a Markdown editor — for\nediting use a CodeMirror-backed <code-ui language=\"markdown\"\neditable>.\n",
       "type": "object",
       "allOf": [
         {
@@ -12380,7 +12789,11 @@
           "richtext"
         ],
         "name": "UIRichText",
-        "related": [],
+        "related": [
+          "Code",
+          "Text",
+          "Textarea"
+        ],
         "slots": {
           "default": {
             "description": "Default slot — primary child content."
@@ -12407,7 +12820,7 @@
     },
     "Row": {
       "title": "Row",
-      "description": "Flex row layout primitive.",
+      "description": "Flex row layout primitive — horizontal stack of children with\n[gap] / [align] / [justify] / [grow] / [wrap]. The horizontal\ncounterpart to <col-ui>. Use <row-ui> for horizontal toolbars,\ninline-control clusters, button groups, table cells. For action\nclusters inside chrome containers (<header-ui> / <footer-ui>) use\nthe parent's [slot=\"action\"] convention instead — the chrome scope\nalready lays out actions correctly without wrapping in row-ui.\n",
       "type": "object",
       "allOf": [
         {
@@ -12419,7 +12832,7 @@
       ],
       "properties": {
         "align": {
-          "description": "Align items",
+          "description": "Cross-axis alignment (start/center/end/stretch/baseline). Accepts `@bp` notation: align=\"start center@sm\".",
           "type": "string",
           "default": "center"
         },
@@ -12432,7 +12845,7 @@
           "default": false
         },
         "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\").",
+          "description": "Gap between children. Named scale (xs/sm/md/lg/xl) or numeric spacing rung (\"1\"…\"16\"). Accepts `@bp` notation: gap=\"2 4@md\".",
           "type": "string",
           "default": "md"
         },
@@ -12442,14 +12855,19 @@
           "default": false
         },
         "justify": {
-          "description": "Justify content",
+          "description": "Main-axis justify (start/center/end/between/space-between/space-around). Accepts `@bp` notation: justify=\"start between@md\".",
           "type": "string",
           "default": "start"
         },
         "wrap": {
-          "description": "Enable flex wrap",
+          "description": "Enable flex-wrap unconditionally. For viewport-responsive wrapping use [wrap-at] instead.",
           "type": "boolean",
           "default": false
+        },
+        "wrapAt": {
+          "description": "Enable flex-wrap from the named breakpoint upward (xs/sm/md/lg/xl). `wrap-at=\"sm\"` = no-wrap on xs, wrap from sm up. Complements the boolean [wrap] (always-wrap) without conflicting with it.",
+          "type": "string",
+          "default": ""
         }
       },
       "required": [
@@ -12495,7 +12913,13 @@
             "name": "idle"
           }
         ],
-        "synonyms": {},
+        "synonyms": {
+          "row": [
+            "hstack",
+            "horizontal-stack",
+            "hbox"
+          ]
+        },
         "tag": "row-ui",
         "tokens": {},
         "traits": [],
@@ -12596,7 +13020,11 @@
           "combobox"
         ],
         "name": "UISearch",
-        "related": [],
+        "related": [
+          "Input",
+          "Command",
+          "Select"
+        ],
         "slots": {
           "clear": {
             "description": "Clear button (shown when value is non-empty)"
@@ -12761,7 +13189,13 @@
             "name": "idle"
           }
         ],
-        "synonyms": {},
+        "synonyms": {
+          "section": [
+            "section-region",
+            "body-region",
+            "content-section"
+          ]
+        },
         "tag": "section-ui",
         "tokens": {},
         "traits": [],
@@ -12770,7 +13204,7 @@
     },
     "Segment": {
       "title": "Segment",
-      "description": "Individual segment option, child of segmented-ui.",
+      "description": "Individual segment child of <segmented-ui> — carries the [value],\n[text], optional [icon], and [selected] state for one option in\na horizontal segmented selector. Distinct from <tab-ui> (a view\nswitcher's child) and <option> (native option for <select-ui>).\nUse segment-ui only as a direct child of <segmented-ui>; never\nstandalone.\n",
       "type": "object",
       "allOf": [
         {
@@ -12867,7 +13301,13 @@
             "name": "disabled"
           }
         ],
-        "synonyms": {},
+        "synonyms": {
+          "segment": [
+            "segment-button",
+            "segmented-option",
+            "option-button"
+          ]
+        },
         "tag": "segment-ui",
         "tokens": {},
         "traits": [],
@@ -12927,7 +13367,12 @@
           "button-group"
         ],
         "name": "UISegmented",
-        "related": [],
+        "related": [
+          "Segment",
+          "ToggleGroup",
+          "Tabs",
+          "Radio"
+        ],
         "slots": {
           "default": {
             "description": "Child segment-ui elements that form the toggle group. Children MUST be segment-ui — bare segment tags render text but are silently ignored for the sliding indicator and role/aria-checked state."
@@ -12992,7 +13437,7 @@
     },
     "Select": {
       "title": "Select",
-      "description": "Alias for ChoicePicker. Dropdown select with options.",
+      "description": "Single-select dropdown primitive — the canonical AdiaUI select\ncontrol. Form-bearing via UIFormElement: [name], [value],\n[required], [disabled], fires `change`. Options via native\n<option> / <optgroup> children, programmatic `.options` array, or\nJSON [data-options] (hydrated by <editor-shell>'s wireSelects).\nUse for single-select with > 4 options; for ≤ 4 options use\n<segmented-ui> or <radio-ui>. Multi-select via [multiple searchable].\n",
       "type": "object",
       "allOf": [
         {
@@ -13448,7 +13893,7 @@
     },
     "Skeleton": {
       "title": "Skeleton",
-      "description": "Placeholder shimmer for loading states. Purely presentational.",
+      "description": "Placeholder shimmer for loading states. Purely presentational — animated pulse background with configurable shape via CSS sizing. Use as a structural placeholder while data loads; for zero-state messaging after loading completes use <empty-state-ui> instead.",
       "type": "object",
       "allOf": [
         {
@@ -13514,7 +13959,12 @@
           "shimmer"
         ],
         "name": "UISkeleton",
-        "related": [],
+        "related": [
+          "EmptyState",
+          "Card",
+          "Table",
+          "List"
+        ],
         "slots": {},
         "states": [
           {
@@ -13728,7 +14178,7 @@
     },
     "Stack": {
       "title": "Stack",
-      "description": "Grid overlay layout — children stack on top of each other.",
+      "description": "Grid-overlay layout primitive — children stack on TOP of each\nother in a single grid cell (z-axis layering). Distinct from\n<col-ui> (vertical) / <row-ui> (horizontal) / <grid-ui> (2D\ngrid with cells). Use stack-ui for badge overlays on avatars,\nabsolute-positioned UI on top of charts, loading spinners over\ncontent, or any case where children must occupy the same physical\nspace. [align] controls how children align within the shared\ncell.\n",
       "type": "object",
       "allOf": [
         {
@@ -13768,7 +14218,11 @@
           "stack"
         ],
         "name": "UIStack",
-        "related": [],
+        "related": [
+          "Col",
+          "Row",
+          "Grid"
+        ],
         "slots": {
           "default": {
             "description": "Default slot — primary child content."
@@ -13780,7 +14234,14 @@
             "name": "idle"
           }
         ],
-        "synonyms": {},
+        "synonyms": {
+          "stack": [
+            "overlay-stack",
+            "z-stack",
+            "grid-overlay",
+            "layer"
+          ]
+        },
         "tag": "stack-ui",
         "tokens": {},
         "traits": [],
@@ -13789,7 +14250,7 @@
     },
     "Stat": {
       "title": "Stat",
-      "description": "Metric/KPI display — value + label + optional change indicator and trend.",
+      "description": "Metric/KPI display — value + label + optional change indicator and trend icon. Renders as a stacked block with prominent value and small caption; supports positive/negative delta coloring. Use inside dashboard cards or summary headers; for inline percentages or progress use <progress-ui>.",
       "type": "object",
       "allOf": [
         {
@@ -13874,7 +14335,11 @@
           "scoreboard"
         ],
         "name": "UIStat",
-        "related": [],
+        "related": [
+          "Card",
+          "Badge",
+          "Progress"
+        ],
         "slots": {
           "change": {
             "description": "Child content region for the `change` slot."
@@ -14045,7 +14510,7 @@
     },
     "Stepper": {
       "title": "Stepper",
-      "description": "Wizard / process stepper — parent step index drives numbered children.",
+      "description": "Wizard / process stepper — parent step index drives numbered children's complete/current/upcoming states automatically. Renders horizontally as a labeled step bar with connectors. Use for multi-step forms, onboarding, or pipelines; for read-only event history use <timeline-ui> instead.",
       "type": "object",
       "allOf": [
         {
@@ -14174,9 +14639,19 @@
         "composes": [],
         "events": {},
         "examples": [],
-        "keywords": [],
+        "keywords": [
+          "stepper-item",
+          "step",
+          "wizard-step",
+          "progress-step",
+          "step-row"
+        ],
         "name": "UIStepperItem",
-        "related": [],
+        "related": [
+          "Stepper",
+          "Timeline",
+          "StepProgress"
+        ],
         "slots": {
           "description": {
             "description": "Custom description content; falls through to `[description]` prop if not slotted."
@@ -14186,7 +14661,14 @@
           }
         },
         "states": [],
-        "synonyms": {},
+        "synonyms": {
+          "stepper-item": [
+            "step",
+            "wizard-step",
+            "progress-step",
+            "checkpoint"
+          ]
+        },
         "tag": "stepper-item-ui",
         "tokens": {},
         "traits": [],
@@ -14371,7 +14853,11 @@
           "stream"
         ],
         "name": "UIStream",
-        "related": [],
+        "related": [
+          "ChatThreadUI",
+          "Text",
+          "Code"
+        ],
         "slots": {
           "default": {
             "description": "Default slot — primary child content."
@@ -14383,7 +14869,13 @@
             "name": "idle"
           }
         ],
-        "synonyms": {},
+        "synonyms": {
+          "stream": [
+            "streaming-text",
+            "live-text",
+            "incremental-text"
+          ]
+        },
         "tag": "stream-ui",
         "tokens": {
           "--stream-color": {
@@ -14782,7 +15274,7 @@
     },
     "Switch": {
       "title": "Switch",
-      "description": "Toggle switch. The host IS the control.",
+      "description": "Toggle switch primitive — binary on/off control where the host IS\nthe control (per ADR-0025, no native <input type=\"checkbox\"> wrapped\nunderneath). Form-bearing via UIFormElement: [name], [value],\n[checked] (reflect), [required], [disabled]. Distinct from <check-ui>\n— use switch-ui for setting-style toggles (notifications on/off,\ndark mode, feature flags), check-ui for opt-in lists, terms\nacceptance, multi-select rows.\n",
       "type": "object",
       "allOf": [
         {
@@ -14875,7 +15367,11 @@
           "switch"
         ],
         "name": "UISwitch",
-        "related": [],
+        "related": [
+          "Check",
+          "Radio",
+          "Field"
+        ],
         "slots": {
           "hint": {
             "description": "Help text below the label"
@@ -14976,12 +15472,26 @@
         "composes": [],
         "events": {},
         "examples": [],
-        "keywords": [],
+        "keywords": [
+          "tab",
+          "tab-panel",
+          "view-switcher-child",
+          "tabs-child"
+        ],
         "name": "UITab",
-        "related": [],
+        "related": [
+          "Tabs",
+          "Nav",
+          "Segmented"
+        ],
         "slots": {},
         "states": [],
-        "synonyms": {},
+        "synonyms": {
+          "tab": [
+            "view-tab",
+            "switcher-tab"
+          ]
+        },
         "tag": "tab-ui",
         "tokens": {},
         "traits": [],
@@ -15765,7 +16275,7 @@
     },
     "Tabs": {
       "title": "Tabs",
-      "description": "Tabbed panel switcher. Renders button strip from child tab-ui elements.",
+      "description": "Tabbed panel switcher. Renders a button strip from child <tab-ui> elements and toggles their associated panel via the active attribute. Use for switching between equivalent peer views in one region; for navigation between routes use <nav-ui> instead.",
       "type": "object",
       "allOf": [
         {
@@ -15946,7 +16456,7 @@
     },
     "Tag": {
       "title": "Tag",
-      "description": "Inline tag/chip with optional dismiss button.",
+      "description": "Inline INTERACTIVE chip / pill with optional dismiss affordance.\nText rendered via CSS `attr(text)`. Use for filter chips\n(removable=true + `remove` event), autocomplete tokens, and\nuser-managed labels. Distinct from <badge-ui>, which is READ-ONLY\nand includes the [status] shorthand for Beta / New / Deprecated\nmarkers — badge-ui has no remove event. For navigation grouping\nuse <nav-group-ui>; for inline command actions use\n<action-list-ui>.\n",
       "type": "object",
       "allOf": [
         {
@@ -16041,7 +16551,11 @@
           "pill"
         ],
         "name": "UITag",
-        "related": [],
+        "related": [
+          "Badge",
+          "NavGroup",
+          "ActionList"
+        ],
         "slots": {},
         "states": [
           {
@@ -16136,7 +16650,7 @@
           "default": 0
         },
         "size": {
-          "description": "Override the variant's font-size on the body ladder. Maps to --a-body-sm / --a-body-md / --a-body-lg. Permissive: unknown values are no-ops (variant size wins). Added v0.6.18 (FB-10).",
+          "description": "Override the variant's font-size on the body ladder (sm/md/lg → --a-body-sm/md/lg). Accepts `@bp` notation: size=\"sm md@lg\" = sm below lg, md from lg up. Added v0.6.18 (FB-10).",
           "type": "string",
           "enum": [
             "sm",
@@ -16254,7 +16768,14 @@
             "name": "idle"
           }
         ],
-        "synonyms": {},
+        "synonyms": {
+          "text": [
+            "typography",
+            "prose",
+            "label-text",
+            "paragraph"
+          ]
+        },
         "tag": "text-ui",
         "tokens": {},
         "traits": [],
@@ -16263,7 +16784,7 @@
     },
     "Textarea": {
       "title": "Textarea",
-      "description": "Multiline text input. The host IS the interactive surface.",
+      "description": "Multi-line text input primitive — the host IS the contenteditable\nsurface (per ADR-0025, no native <textarea> wrapped underneath).\nForm-bearing via UIFormElement: [name], [value], [required],\n[disabled], [readonly], fires `change` on blur and `input` per\nkeystroke. Enter inserts a newline — does NOT fire `submit` (for\nEnter-to-send composers use <chat-input-ui submit-on-enter> inside\n<chat-composer>). Wrap in <field-ui label=\"…\"> for the canonical\nlabeled stack.\n",
       "type": "object",
       "allOf": [
         {
@@ -16371,7 +16892,12 @@
           "textarea"
         ],
         "name": "UITextarea",
-        "related": [],
+        "related": [
+          "Input",
+          "Field",
+          "ChatInput",
+          "Code"
+        ],
         "slots": {},
         "states": [
           {
@@ -16379,7 +16905,14 @@
             "name": "idle"
           }
         ],
-        "synonyms": {},
+        "synonyms": {
+          "textarea": [
+            "multiline-input",
+            "text-area",
+            "comment-input",
+            "long-text-input"
+          ]
+        },
         "tag": "textarea-ui",
         "tokens": {},
         "traits": [],
@@ -16647,7 +17180,14 @@
             "name": "idle"
           }
         ],
-        "synonyms": {},
+        "synonyms": {
+          "timeline": [
+            "activity-log",
+            "event-log",
+            "history",
+            "audit-trail"
+          ]
+        },
         "tag": "timeline-ui",
         "tokens": {},
         "traits": [],
@@ -16716,12 +17256,29 @@
         "composes": [],
         "events": {},
         "examples": [],
-        "keywords": [],
+        "keywords": [
+          "timeline-item",
+          "timeline-row",
+          "activity-entry",
+          "event-entry",
+          "history-row"
+        ],
         "name": "UITimelineItem",
-        "related": [],
+        "related": [
+          "Timeline",
+          "FeedItem",
+          "Stepper"
+        ],
         "slots": {},
         "states": [],
-        "synonyms": {},
+        "synonyms": {
+          "timeline-item": [
+            "timeline-row",
+            "activity-row",
+            "event-row",
+            "history-entry"
+          ]
+        },
         "tag": "timeline-item-ui",
         "tokens": {},
         "traits": [],
@@ -16730,7 +17287,7 @@
     },
     "Toast": {
       "title": "Toast",
-      "description": "Notification popup with auto-dismiss. Animated enter/exit.",
+      "description": "Transient global notification popup with auto-dismiss + animated\nenter/exit. Variants map to severity (info / success / warning /\ndanger). Distinct from <alert-ui> (inline persistent banner) and\n<empty-state-ui> (zero-data placeholder). Use toast-ui for\nshort-lived feedback after user actions (\"Saved\", \"Copied to\nclipboard\"); the toast positions itself relative to viewport\n[position] regardless of where in the DOM it's rendered.\n",
       "type": "object",
       "allOf": [
         {
@@ -16814,7 +17371,11 @@
           "alert"
         ],
         "name": "UIToast",
-        "related": [],
+        "related": [
+          "Feed",
+          "Alert",
+          "FeedItem"
+        ],
         "slots": {},
         "states": [
           {
@@ -16908,7 +17469,7 @@
     },
     "ToggleGroup": {
       "title": "ToggleGroup",
-      "description": "Multi-select button group (unlike segmented which is single-select).",
+      "description": "Multi-select button group (unlike <segmented-ui> which is single-select). Hosts <toggle-option-ui> children, each independently toggleable; emits change events with the active value set. Use for filter chips or feature flag clusters; for single-select option groups use <segmented-ui> instead.",
       "type": "object",
       "allOf": [
         {
@@ -16966,7 +17527,11 @@
           "group"
         ],
         "name": "UIToggleGroup",
-        "related": [],
+        "related": [
+          "ToggleOption",
+          "Segmented",
+          "Radio"
+        ],
         "slots": {
           "default": {
             "description": "Default slot — primary child content."
@@ -16978,7 +17543,13 @@
             "name": "idle"
           }
         ],
-        "synonyms": {},
+        "synonyms": {
+          "toggle-group": [
+            "segmented-control",
+            "option-group",
+            "toggle-set"
+          ]
+        },
         "tag": "toggle-group-ui",
         "tokens": {
           "--toggle-group-border": {
@@ -17084,12 +17655,27 @@
         "composes": [],
         "events": {},
         "examples": [],
-        "keywords": [],
+        "keywords": [
+          "toggle-option",
+          "toggle-segment",
+          "option-toggle",
+          "segmented-option"
+        ],
         "name": "UIToggleOption",
-        "related": [],
+        "related": [
+          "ToggleGroup",
+          "Segment",
+          "Radio"
+        ],
         "slots": {},
         "states": [],
-        "synonyms": {},
+        "synonyms": {
+          "toggle-option": [
+            "toggle-segment",
+            "option-button",
+            "segmented-option"
+          ]
+        },
         "tag": "toggle-option-ui",
         "tokens": {},
         "traits": [],
@@ -17440,12 +18026,27 @@
         "composes": [],
         "events": {},
         "examples": [],
-        "keywords": [],
+        "keywords": [
+          "toolbar-group",
+          "button-group",
+          "action-cluster",
+          "toolbar-cluster"
+        ],
         "name": "UIToolbarGroup",
-        "related": [],
+        "related": [
+          "Toolbar",
+          "Button",
+          "Divider"
+        ],
         "slots": {},
         "states": [],
-        "synonyms": {},
+        "synonyms": {
+          "toolbar-group": [
+            "button-group",
+            "action-cluster",
+            "toolbar-section"
+          ]
+        },
         "tag": "toolbar-group-ui",
         "tokens": {},
         "traits": [],
@@ -17684,7 +18285,12 @@
           "folder"
         ],
         "name": "UITree",
-        "related": [],
+        "related": [
+          "TreeItem",
+          "Nav",
+          "List",
+          "Accordion"
+        ],
         "slots": {
           "default (tree-item-ui children)": {
             "description": "Child content region for the `default (tree-item-ui children)` slot."
@@ -17826,12 +18432,28 @@
         "composes": [],
         "events": {},
         "examples": [],
-        "keywords": [],
+        "keywords": [
+          "tree-item",
+          "tree-row",
+          "tree-node",
+          "hierarchy-item"
+        ],
         "name": "UITreeItem",
-        "related": [],
+        "related": [
+          "Tree",
+          "List",
+          "Nav",
+          "Accordion"
+        ],
         "slots": {},
         "states": [],
-        "synonyms": {},
+        "synonyms": {
+          "tree-item": [
+            "tree-node",
+            "tree-row",
+            "hierarchy-row"
+          ]
+        },
         "tag": "tree-item-ui",
         "tokens": {},
         "traits": [],