@ds-mo/ui 9.0.0 → 9.2.0

package/dist/agent.json

@@ -1,9 +1,340 @@
 {
   "schemaVersion": "1.0.0",
   "package": "@ds-mo/ui",
-  "packageVersion": "9.0.0",
+  "packageVersion": "9.2.0",
   "kind": "components",
   "entries": [
+    {
+      "id": "component:ds-agent-activity",
+      "tag": "ds-agent-activity",
+      "name": "agent-activity",
+      "title": "AgentActivity",
+      "summary": "Collapsible, user-safe summary of agent work steps without private reasoning.",
+      "intentStatus": "complete",
+      "intent": {
+        "audience": "specialized",
+        "status": "experimental",
+        "summary": "Collapsible, user-safe summary of agent work steps without private reasoning.",
+        "useWhen": [
+          "An agent response benefits from concise progress or completion summaries."
+        ],
+        "avoidWhen": [
+          "The content would reveal private chain-of-thought, hidden prompts, secrets, or raw internal traces."
+        ],
+        "commonlyComposedWith": [
+          "component:ds-agent-response",
+          "component:ds-loader"
+        ],
+        "patterns": [
+          "pattern:agent-chat"
+        ],
+        "accessibility": [
+          "Each step has textual state and description; animation and color are supplementary.",
+          "The disclosure uses native keyboard and expanded-state semantics."
+        ],
+        "states": [
+          "While collapsed, the summary follows the current user-safe activity and shimmers only while active; while expanded, the heading becomes Activity and the ordered list exposes every step.",
+          "Pending, active, complete, and error describe user-safe workflow progress."
+        ],
+        "responsiveBehavior": [
+          "Steps wrap within the response width."
+        ],
+        "references": [
+          {
+            "label": "Storybook examples",
+            "path": "src/wc/components/MessageScroller/MessageScroller.stories.ts"
+          }
+        ]
+      },
+      "api": {
+        "props": {
+          "heading": {
+            "type": "string",
+            "required": false
+          },
+          "items": {
+            "type": "AgentActivityItem[]",
+            "required": false
+          },
+          "open": {
+            "type": "boolean",
+            "required": false
+          }
+        },
+        "events": [],
+        "slots": []
+      },
+      "exports": {
+        "customElement": "ds-agent-activity",
+        "react": "DsAgentActivity",
+        "angular": "DsAgentActivity"
+      },
+      "dependencies": [
+        "@ds-mo/ui",
+        "@ds-mo/tokens",
+        "@ds-mo/icons"
+      ],
+      "componentDependencies": [
+        "icon",
+        "loader",
+        "text"
+      ]
+    },
+    {
+      "id": "component:ds-agent-response",
+      "tag": "ds-agent-response",
+      "name": "agent-response",
+      "title": "AgentResponse",
+      "summary": "Ordered renderer for normalized immutable agent response parts inside a generic incoming message.",
+      "intentStatus": "complete",
+      "intent": {
+        "audience": "specialized",
+        "status": "experimental",
+        "summary": "Ordered renderer for normalized immutable agent response parts inside a generic incoming message.",
+        "useWhen": [
+          "An agent response combines Markdown, user-safe activity, display-only tools, attachments, and sources in authored order."
+        ],
+        "avoidWhen": [
+          "The component would be expected to own a model, transport, persistence, title generation, approval policy, or private reasoning."
+        ],
+        "commonlyComposedWith": [
+          "component:ds-message",
+          "component:ds-markdown",
+          "component:ds-agent-activity",
+          "component:ds-agent-tool-call",
+          "component:ds-agent-source-list"
+        ],
+        "patterns": [
+          "pattern:agent-chat"
+        ],
+        "accessibility": [
+          "Part order matches authored reading order and remains inside generic message semantics.",
+          "Streaming state supplements rather than replaces meaningful textual status."
+        ],
+        "states": [
+          "The owner replaces immutable part arrays as scripted or live output changes."
+        ],
+        "responsiveBehavior": [
+          "Rich content uses the wider ghost message treatment while respecting transcript constraints."
+        ],
+        "references": [
+          {
+            "label": "Storybook examples",
+            "path": "src/wc/components/MessageScroller/MessageScroller.stories.ts"
+          }
+        ]
+      },
+      "api": {
+        "props": {
+          "author": {
+            "type": "string",
+            "required": false
+          },
+          "messageId": {
+            "type": "string",
+            "required": false
+          },
+          "parts": {
+            "type": "AgentResponsePart[]",
+            "required": false
+          },
+          "showAuthor": {
+            "type": "boolean",
+            "required": false
+          },
+          "streaming": {
+            "type": "boolean",
+            "required": false
+          },
+          "timestamp": {
+            "type": "string",
+            "required": false
+          }
+        },
+        "events": [],
+        "slots": []
+      },
+      "exports": {
+        "customElement": "ds-agent-response",
+        "react": "DsAgentResponse",
+        "angular": "DsAgentResponse"
+      },
+      "dependencies": [
+        "@ds-mo/ui",
+        "@ds-mo/tokens"
+      ],
+      "componentDependencies": [
+        "agent-activity",
+        "agent-source-list",
+        "agent-tool-call",
+        "attachment-list",
+        "markdown",
+        "message",
+        "message-bubble"
+      ]
+    },
+    {
+      "id": "component:ds-agent-source-list",
+      "tag": "ds-agent-source-list",
+      "name": "agent-source-list",
+      "title": "AgentSourceList",
+      "summary": "Collapsible list of agent response sources with title, description, and validated external links.",
+      "intentStatus": "complete",
+      "intent": {
+        "audience": "specialized",
+        "status": "experimental",
+        "summary": "Collapsible list of agent response sources with title, description, and validated external links.",
+        "useWhen": [
+          "An agent response cites external material readers may inspect."
+        ],
+        "avoidWhen": [
+          "The links are ordinary body links or are not sources for the response."
+        ],
+        "commonlyComposedWith": [
+          "component:ds-agent-response",
+          "component:ds-markdown"
+        ],
+        "patterns": [
+          "pattern:agent-chat"
+        ],
+        "accessibility": [
+          "Each source uses descriptive linked text and visible supporting context.",
+          "Unsafe link schemes remain non-interactive text."
+        ],
+        "responsiveBehavior": [
+          "Source titles and descriptions wrap within the response width."
+        ],
+        "references": [
+          {
+            "label": "Storybook examples",
+            "path": "src/wc/components/MessageScroller/MessageScroller.stories.ts"
+          }
+        ]
+      },
+      "api": {
+        "props": {
+          "heading": {
+            "type": "string",
+            "required": false
+          },
+          "items": {
+            "type": "AgentSource[]",
+            "required": false
+          },
+          "open": {
+            "type": "boolean",
+            "required": false
+          }
+        },
+        "events": [],
+        "slots": []
+      },
+      "exports": {
+        "customElement": "ds-agent-source-list",
+        "react": "DsAgentSourceList",
+        "angular": "DsAgentSourceList"
+      },
+      "dependencies": [
+        "@ds-mo/ui",
+        "@ds-mo/tokens",
+        "@ds-mo/icons"
+      ],
+      "componentDependencies": [
+        "icon",
+        "text"
+      ]
+    },
+    {
+      "id": "component:ds-agent-tool-call",
+      "tag": "ds-agent-tool-call",
+      "name": "agent-tool-call",
+      "title": "AgentToolCall",
+      "summary": "Display-only disclosure for an agent tool call, its safe input or output, and execution status.",
+      "intentStatus": "complete",
+      "intent": {
+        "audience": "specialized",
+        "status": "experimental",
+        "summary": "Display-only disclosure for an agent tool call, its safe input or output, and execution status.",
+        "useWhen": [
+          "A prototype or agent product needs to expose user-safe tool execution detail."
+        ],
+        "avoidWhen": [
+          "A participant must approve, deny, edit, or retry the tool call; those are product controls outside this component."
+        ],
+        "commonlyComposedWith": [
+          "component:ds-agent-response",
+          "component:ds-code-block"
+        ],
+        "patterns": [
+          "pattern:agent-chat"
+        ],
+        "accessibility": [
+          "Queued, running, success, error, and denied states are available as text.",
+          "The disclosure uses native keyboard and expanded-state semantics."
+        ],
+        "states": [
+          "This component presents state but never executes a tool or owns approval policy."
+        ],
+        "responsiveBehavior": [
+          "Structured detail wraps and scrolls without widening the transcript."
+        ],
+        "references": [
+          {
+            "label": "Storybook examples",
+            "path": "src/wc/components/MessageScroller/MessageScroller.stories.ts"
+          }
+        ]
+      },
+      "api": {
+        "props": {
+          "error": {
+            "type": "string",
+            "required": false
+          },
+          "input": {
+            "type": "unknown",
+            "required": false
+          },
+          "label": {
+            "type": "string",
+            "required": false
+          },
+          "name": {
+            "type": "string",
+            "required": false
+          },
+          "open": {
+            "type": "boolean",
+            "required": false
+          },
+          "output": {
+            "type": "unknown",
+            "required": false
+          },
+          "state": {
+            "type": "AgentToolState",
+            "required": false
+          }
+        },
+        "events": [],
+        "slots": []
+      },
+      "exports": {
+        "customElement": "ds-agent-tool-call",
+        "react": "DsAgentToolCall",
+        "angular": "DsAgentToolCall"
+      },
+      "dependencies": [
+        "@ds-mo/ui",
+        "@ds-mo/tokens",
+        "@ds-mo/icons"
+      ],
+      "componentDependencies": [
+        "icon",
+        "loader",
+        "text"
+      ]
+    },
     {
       "id": "component:ds-app-shell",
       "tag": "ds-app-shell",
@@ -29,7 +360,7 @@
           "component:ds-panel-nav",
           "component:ds-bar-nav",
           "component:ds-panel-tools",
-          "component:ds-shell-gradient-picker"
+          "component:ds-swatch-picker"
         ],
         "patterns": [
           "pattern:application-shell"
@@ -126,36 +457,166 @@
       "componentDependencies": []
     },
     {
-      "id": "component:ds-badge",
-      "tag": "ds-badge",
-      "name": "badge",
-      "title": "Badge",
-      "summary": "Non-interactive brand counter or dot that supplements an owning control or label with unread notification information.",
+      "id": "component:ds-attachment-list",
+      "tag": "ds-attachment-list",
+      "name": "attachment-list",
+      "title": "AttachmentList",
+      "summary": "Channel-neutral list of message attachments with name, media type, size, and optional safe link.",
       "intentStatus": "complete",
       "intent": {
         "audience": "general",
-        "status": "stable",
-        "summary": "Non-interactive brand counter or dot that supplements an owning control or label with unread notification information.",
+        "status": "experimental",
+        "summary": "Channel-neutral list of message attachments with name, media type, size, and optional safe link.",
         "useWhen": [
-          "An existing control, navigation item, or label needs a compact unread notification count.",
-          "An owning element needs a small visual dot indicating that supplemental notification information exists.",
-          "When the badge overlaps an icon or content, the immediate backing surface can be identified so its separation ring matches."
+          "A conversation message needs to display already-known attachment metadata."
         ],
         "avoidWhen": [
-          "The status must stand alone without an owning label or control.",
-          "The mark needs semantic positive, caution, negative, or neutral color; Badge intentionally uses one brand treatment.",
-          "The compact content is metadata or taxonomy; use Tag or Chip according to whether it is removable.",
-          "The badge itself would receive pointer or keyboard interaction; put interaction on the owning control."
+          "Users need to choose, upload, remove, or edit files; those controls belong to the product workflow."
         ],
-        "alternatives": [
-          {
-            "when": "A compact static label communicates taxonomy or a semantic status.",
-            "component": "component:ds-tag",
-            "reason": "Tag owns static metadata labels and semantic intent coloring."
-          },
-          {
-            "when": "A metadata value must be individually removable.",
-            "component": "component:ds-chip",
+        "commonlyComposedWith": [
+          "component:ds-message",
+          "component:ds-message-bubble"
+        ],
+        "patterns": [
+          "pattern:conversation"
+        ],
+        "accessibility": [
+          "Attachment name remains visible and is the link text when a safe URL is available.",
+          "Media type and size are supporting metadata, never the only identifier."
+        ],
+        "responsiveBehavior": [
+          "Long names wrap or truncate without overflowing the message surface."
+        ],
+        "references": [
+          {
+            "label": "Storybook examples",
+            "path": "src/wc/components/MessageScroller/MessageScroller.stories.ts"
+          }
+        ]
+      },
+      "api": {
+        "props": {
+          "items": {
+            "type": "ConversationAttachment[]",
+            "required": false
+          },
+          "label": {
+            "type": "string",
+            "required": false
+          }
+        },
+        "events": [],
+        "slots": []
+      },
+      "exports": {
+        "customElement": "ds-attachment-list",
+        "react": "DsAttachmentList",
+        "angular": "DsAttachmentList"
+      },
+      "dependencies": [
+        "@ds-mo/ui",
+        "@ds-mo/tokens",
+        "@ds-mo/icons"
+      ],
+      "componentDependencies": [
+        "icon",
+        "text"
+      ]
+    },
+    {
+      "id": "component:ds-avatar",
+      "tag": "ds-avatar",
+      "name": "avatar",
+      "title": "Avatar",
+      "summary": "Compact icon avatar for visually identifying a person, group, channel, or conversation type.",
+      "intentStatus": "complete",
+      "intent": {
+        "audience": "general",
+        "status": "experimental",
+        "summary": "Compact icon avatar for visually identifying a person, group, channel, or conversation type.",
+        "useWhen": [
+          "A list or message composition needs a consistent 32px circular identity marker represented by an icon."
+        ],
+        "avoidWhen": [
+          "The identity has a supplied photograph, initials, presence state, or editable profile behavior; those variants are not part of this primitive."
+        ],
+        "commonlyComposedWith": [
+          "component:ds-conversation-list-item",
+          "component:ds-message"
+        ],
+        "accessibility": [
+          "Provide label only when the icon communicates meaning that surrounding text does not already convey.",
+          "Omit label when the owning row or message already provides an equivalent accessible name."
+        ],
+        "responsiveBehavior": [
+          "The avatar keeps its fixed 32px circle and 20px icon at every viewport size."
+        ],
+        "references": [
+          {
+            "label": "Storybook examples",
+            "path": "src/wc/components/Avatar/Avatar.stories.ts"
+          }
+        ]
+      },
+      "api": {
+        "props": {
+          "icon": {
+            "type": "string",
+            "required": false
+          },
+          "label": {
+            "type": "string | undefined",
+            "required": false
+          }
+        },
+        "events": [],
+        "slots": []
+      },
+      "exports": {
+        "customElement": "ds-avatar",
+        "react": "DsAvatar",
+        "angular": "DsAvatar"
+      },
+      "dependencies": [
+        "@ds-mo/ui",
+        "@ds-mo/tokens",
+        "@ds-mo/icons"
+      ],
+      "componentDependencies": [
+        "icon"
+      ]
+    },
+    {
+      "id": "component:ds-badge",
+      "tag": "ds-badge",
+      "name": "badge",
+      "title": "Badge",
+      "summary": "Non-interactive brand counter or dot that supplements an owning control or label with unread notification information.",
+      "intentStatus": "complete",
+      "intent": {
+        "audience": "general",
+        "status": "stable",
+        "summary": "Non-interactive brand counter or dot that supplements an owning control or label with unread notification information.",
+        "useWhen": [
+          "An existing control, navigation item, or label needs a compact unread notification count.",
+          "An owning element needs a small visual dot indicating that supplemental notification information exists.",
+          "When the badge overlaps an icon or content, the immediate backing surface can be identified so its separation ring matches."
+        ],
+        "avoidWhen": [
+          "The status must stand alone without an owning label or control.",
+          "The mark needs semantic positive, caution, negative, or neutral color; Badge intentionally uses one brand treatment.",
+          "The compact content is metadata or taxonomy; use Tag or Chip according to whether it is removable.",
+          "The badge itself would receive pointer or keyboard interaction; put interaction on the owning control."
+        ],
+        "alternatives": [
+          {
+            "when": "A compact static label communicates taxonomy or a semantic status.",
+            "component": "component:ds-tag",
+            "reason": "Tag owns static metadata labels and semantic intent coloring."
+          },
+          {
+            "when": "A metadata value must be individually removable.",
+            "component": "component:ds-chip",
             "reason": "Chip owns dismissible metadata values."
           },
           {
@@ -672,6 +1133,9 @@
           "component:ds-menu",
           "component:ds-panel-tools"
         ],
+        "patterns": [
+          "pattern:menu-trigger"
+        ],
         "accessibility": [
           "Provide an explicit accessible name for every icon-only action.",
           "Use active state only for a persistent toggle or mode, and synchronize pressed semantics unless an owning composite exposes the selection state.",
@@ -1562,98 +2026,52 @@
       ]
     },
     {
-      "id": "component:ds-divider",
-      "tag": "ds-divider",
-      "name": "divider",
-      "title": "Divider",
-      "summary": "Horizontal or vertical separator between sibling content groups, decorative by default with optional structural semantics.",
+      "id": "component:ds-code-block",
+      "tag": "ds-code-block",
+      "name": "code-block",
+      "title": "CodeBlock",
+      "summary": "Scrollable monospace code surface with optional language or filename context and copy action.",
       "intentStatus": "complete",
       "intent": {
         "audience": "general",
-        "status": "stable",
-        "summary": "Horizontal or vertical separator between sibling content groups, decorative by default with optional structural semantics.",
+        "status": "experimental",
+        "summary": "Scrollable monospace code surface with optional language or filename context and copy action.",
         "useWhen": [
-          "Related sibling content groups on one surface need stronger visual separation than spacing alone provides.",
-          "A list or panel needs an inset separator that does not define the outer edge of its container.",
-          "Meaningful document or group structure requires an explicit horizontal or vertical separator."
+          "A message or document displays fenced code that readers may copy."
         ],
         "avoidWhen": [
-          "Spacing alone communicates the grouping clearly.",
-          "The line defines a container edge, control outline, or selected state; use the owning component's border treatment.",
-          "The divider would compensate for weak headings or unclear information hierarchy.",
-          "A decorative flourish does not clarify grouping."
-        ],
-        "alternatives": [
-          {
-            "when": "Content needs an enclosing surface and outer boundary.",
-            "component": "component:ds-card",
-            "reason": "Card owns container chrome, structure, and edge treatment."
-          },
-          {
-            "when": "A static compact label is being used to name a group.",
-            "component": "component:ds-text",
-            "reason": "Text communicates hierarchy directly instead of relying on a line."
-          }
+          "A live editor, terminal, diff viewer, or syntax-highlighting environment is required."
         ],
         "commonlyComposedWith": [
-          "component:ds-card",
-          "component:ds-menu",
-          "component:ds-panel-sub-nav"
+          "component:ds-markdown",
+          "component:ds-button-unfilled"
         ],
         "accessibility": [
-          "Keep purely visual dividers hidden from assistive technology.",
-          "Expose separator semantics only when the line represents meaningful document or group structure.",
-          "Semantic orientation must match the divider's visual orientation.",
-          "Do not use a semantic divider as a substitute for headings, landmarks, or explicit group labels."
-        ],
-        "states": [
-          "Horizontal and vertical variants separate sibling groups along the parent's layout axis.",
-          "The omitted background context is for primary and secondary surfaces. Explicit faint documents a faint surface while using the same standard divider token.",
-          "Other background contexts select their matching divider token, including navigation where Divider is composed inside app chrome.",
-          "Inset is symmetric along the line axis. Explicit length is reserved for layout-specific separators; otherwise the line fills the available axis."
+          "The copy action has explicit status wording and the code remains selectable text.",
+          "Language and filename labels supplement rather than replace the code content."
         ],
         "responsiveBehavior": [
-          "The parent layout decides whether to change orientation, visibility, inset, or length at responsive breakpoints.",
-          "Divider does not infer layout direction or hide itself responsively."
+          "Long lines scroll horizontally and do not widen the owning transcript."
         ],
-        "frameworkCaveats": {
-          "customElements": [
-            "Set semantic mode only from known document structure; presentation alone should remain hidden from assistive technology."
-          ],
-          "react": [
-            "Derive orientation and visibility from the parent layout rather than viewport logic inside Divider."
-          ],
-          "angular": [
-            "Derive orientation and visibility from the parent layout rather than viewport logic inside Divider."
-          ]
-        },
         "references": [
           {
             "label": "Storybook examples",
-            "path": "src/wc/components/Divider/Divider.stories.ts"
+            "path": "src/wc/components/MessageScroller/MessageScroller.stories.ts"
           }
         ]
       },
       "api": {
         "props": {
-          "background": {
-            "type": "DividerBackground | undefined",
-            "required": false
-          },
-          "inset": {
-            "type": "DividerInset",
-            "required": false
-          },
-          "length": {
-            "type": "DividerLength",
+          "code": {
+            "type": "string",
             "required": false
           },
-          "orientation": {
-            "type": "DividerOrientation",
+          "filename": {
+            "type": "string",
             "required": false
           },
-          "semantic": {
-            "type": "boolean",
+          "language": {
+            "type": "string",
             "required": false
           }
         },
@@ -1661,344 +2079,226 @@
         "slots": []
       },
       "exports": {
-        "customElement": "ds-divider",
-        "react": "DsDivider",
-        "angular": "DsDivider"
+        "customElement": "ds-code-block",
+        "react": "DsCodeBlock",
+        "angular": "DsCodeBlock"
       },
       "dependencies": [
         "@ds-mo/ui",
         "@ds-mo/tokens"
       ],
-      "componentDependencies": []
+      "componentDependencies": [
+        "button-unfilled",
+        "text"
+      ]
     },
     {
-      "id": "component:ds-empty-state",
-      "tag": "ds-empty-state",
-      "name": "empty-state",
-      "title": "EmptyState",
-      "summary": "Centered empty-content message composed as icon plus title plus body, title plus body, or compact body-only content.",
+      "id": "component:ds-conversation-list",
+      "tag": "ds-conversation-list",
+      "name": "conversation-list",
+      "title": "ConversationList",
+      "summary": "Scrollable conversation-list region with dedicated empty and floating-action placement.",
       "intentStatus": "complete",
       "intent": {
         "audience": "general",
-        "status": "stable",
-        "summary": "Centered empty-content message composed as icon plus title plus body, title plus body, or compact body-only content.",
+        "status": "experimental",
+        "summary": "Scrollable conversation-list region with dedicated empty and floating-action placement.",
         "useWhen": [
-          "A bounded content area is in a first-use, no-content, filtered no-results, or no-access state and needs a calm explanatory message tailored to that cause.",
-          "A prominent empty region benefits from a decorative icon, visual title, and supporting body copy.",
-          "A compact owner such as a Select popup needs only centered body copy."
+          "A messaging-like surface needs a reusable history list with empty and action regions."
         ],
         "avoidWhen": [
-          "Content is still loading; use Skeleton for predictable structure or Loader for an indeterminate operation.",
-          "The state is an error, warning, or confirmation that needs semantic intent and announcement from the owning workflow.",
-          "The state needs a recovery action, link, or other interactive content; the current EmptyState pattern is intentionally message-only.",
-          "A decorative illustration, arbitrary rich content, or custom layout is required."
-        ],
-        "alternatives": [
-          {
-            "when": "A content region is waiting for structured data.",
-            "component": "component:ds-skeleton",
-            "reason": "Skeleton preserves expected geometry while content is pending."
-          },
-          {
-            "when": "An operation is progressing without predictable content structure.",
-            "component": "component:ds-loader",
-            "reason": "Loader owns indeterminate progress rather than an empty outcome."
-          },
-          {
-            "when": "Only ordinary prose is needed without empty-state layout.",
-            "component": "component:ds-text",
-            "reason": "Text owns typography without adding centered empty-state composition."
-          }
+          "The content is not a collection of conversations or threads."
         ],
         "commonlyComposedWith": [
-          "component:ds-select",
-          "component:ds-text",
-          "component:ds-icon"
+          "component:ds-conversation-list-section",
+          "component:ds-conversation-list-item",
+          "component:ds-empty-state"
         ],
-        "accessibility": [
-          "The optional icon is decorative; the title and body provide all meaning in text.",
-          "EmptyState does not create a live region or alert automatically. The owner decides whether a dynamic transition requires announcement.",
-          "The visual title does not impose a document heading level because the correct hierarchy belongs to the consuming page or region.",
-          "Keep localized body copy concise and sufficient when using the body-only variant."
+        "patterns": [
+          "pattern:conversation"
         ],
-        "states": [
-          "Supported compositions are icon plus title plus body, title plus body, and body only; body copy is present in every supported composition.",
-          "The decorative icon renders at xl in the primary foreground with an 8px gap before the text group and only when a title is also provided.",
-          "The visual title uses title-small primary text; body uses body-medium secondary text with a 4px title-to-body gap.",
-          "All content is centered. The owner supplies container size and surrounding padding; do not compose actions into or immediately alongside the current EmptyState pattern.",
-          "First-use, no-content, no-results, and no-access states reuse this primitive with cause-specific localized messages rather than visual variants."
+        "accessibility": [
+          "Provide an accessible list label through the surrounding heading or region.",
+          "Keep the empty message descriptive and the floating action explicitly named."
         ],
         "responsiveBehavior": [
-          "The owner controls available width and height; text wraps naturally while remaining centered.",
-          "EmptyState does not infer breakpoints or change composition automatically."
+          "The list fills its owner, scrolls independently, and keeps its action at the lower end corner."
         ],
-        "frameworkCaveats": {
-          "customElements": [
-            "Pass canonical IcoMo icon names and localized heading/body strings through properties or attributes."
-          ],
-          "react": [
-            "Choose one supported composition by passing body with optional heading and icon props."
-          ],
-          "angular": [
-            "Choose one supported composition by binding body with optional heading and icon inputs."
-          ]
-        },
         "references": [
           {
             "label": "Storybook examples",
-            "path": "src/wc/components/EmptyState/EmptyState.stories.ts"
+            "path": "src/wc/components/ConversationList/ConversationList.stories.ts"
           }
         ]
       },
       "api": {
-        "props": {
-          "body": {
-            "type": "string",
-            "required": false
-          },
-          "heading": {
-            "type": "string | undefined",
-            "required": false
-          },
-          "icon": {
-            "type": "string | undefined",
-            "required": false
-          }
-        },
+        "props": {},
         "events": [],
         "slots": []
       },
       "exports": {
-        "customElement": "ds-empty-state",
-        "react": "DsEmptyState",
-        "angular": "DsEmptyState"
+        "customElement": "ds-conversation-list",
+        "react": "DsConversationList",
+        "angular": "DsConversationList"
       },
       "dependencies": [
         "@ds-mo/ui",
-        "@ds-mo/tokens",
-        "@ds-mo/icons"
+        "@ds-mo/tokens"
       ],
-      "componentDependencies": [
-        "icon",
-        "text"
-      ]
+      "componentDependencies": []
     },
     {
-      "id": "component:ds-field",
-      "tag": "ds-field",
-      "name": "field",
-      "title": "Field",
-      "summary": "Accessible form-field composition that gives one Input or Select a persistent label, optional guidance, shared error presentation, stable IDs, and observable interaction state.",
+      "id": "component:ds-conversation-list-item",
+      "tag": "ds-conversation-list-item",
+      "name": "conversation-list-item",
+      "title": "ConversationListItem",
+      "summary": "Selectable conversation row with one-line preview, recency, unread presence, generic busy or error status, and channel-owned accessory slots.",
       "intentStatus": "complete",
       "intent": {
         "audience": "general",
-        "status": "stable",
-        "summary": "Accessible form-field composition that gives one Input or Select a persistent label, optional guidance, shared error presentation, stable IDs, and observable interaction state.",
+        "status": "experimental",
+        "summary": "Selectable conversation row with one-line preview, recency, unread presence, generic busy or error status, and channel-owned accessory slots.",
         "useWhen": [
-          "An Input, Select, or SelectMulti needs a persistent visible label in a form.",
-          "Help text or an error message must be programmatically associated with one control.",
-          "A form layout needs one consistent label-control-message rhythm."
+          "A conversation history needs a compact row that opens one thread."
         ],
         "avoidWhen": [
-          "The component already owns its visible label and complete selection semantics, such as Checkbox, Radio, or Switch.",
-          "Several controls belong to one question; use a semantic fieldset and legend instead.",
-          "Text describes a region or group rather than one form control."
-        ],
-        "alternatives": [
-          {
-            "when": "Several related controls answer one question.",
-            "component": "component:ds-text",
-            "reason": "Use native fieldset and legend semantics, then compose Text only for supporting content."
-          }
+          "The row represents a command rather than a persisted conversation."
         ],
         "commonlyComposedWith": [
-          "component:ds-input",
-          "component:ds-select",
-          "component:ds-select-multi",
-          "component:ds-text"
+          "component:ds-conversation-list-section",
+          "component:ds-avatar",
+          "component:ds-badge",
+          "component:ds-loader"
+        ],
+        "patterns": [
+          "pattern:conversation"
         ],
         "accessibility": [
-          "Slot exactly one form control. Field assigns its stable control ID and connects the visible label automatically.",
-          "The visible description or error ID is merged with any authored aria-describedby references; a rendered error replaces the description.",
-          "The error prop forwards aria-invalid and supported design-system control error styling; put visible error text on Field, not again on the child control.",
-          "Clicking the label focuses the slotted design-system control without opening a Select popup.",
-          "Do not use placeholder text as the only label. Keep label text concise and put format or consequence guidance in description."
+          "The conversation surface is one button with its title as the primary accessible name; actions are sibling controls so buttons are never nested.",
+          "An action in the actions slot remains keyboard-focusable and appears on row focus as well as pointer hover; touch layouts keep it visible.",
+          "Status copy must make busy or error meaning available without relying on motion or color."
         ],
         "states": [
-          "Field exposes data-focused, data-filled, data-dirty, data-touched, data-invalid, data-disabled, and data-required hooks while the slotted control remains the source of value and interaction behavior.",
-          "A rendered error replaces the description; preserve essential guidance in the error message so users retain what they need to correct the field.",
-          "Field owns validation presentation but not validation timing; the form decides when to set error and errorMessage.",
-          "The label uses primary body-small emphasis, description uses secondary body-small text, and error uses negative body-small text."
+          "Rows reuse the md choice-item label/subtext recipe used by Menu, including 6px row padding, 2px text inset, and the shared content gap. The enclosing conversation-list scroll region supplies the larger 8px outer container padding.",
+          "Busy and error are generic channel-neutral states; the owning product supplies suitable status wording.",
+          "Any positive unreadCount renders one dot on the title row rather than a visible counter; the accessible row name may still announce the exact unread quantity.",
+          "Hover and press use the shared interaction hover and pressed overlays. Only the selected conversation uses the persistent active fill.",
+          "The title uses body-medium emphasis, not title-small, and the body-small preview truncates after one line. Unread titles use primary foreground; read titles use secondary foreground.",
+          "The actions slot overlays the row at an 8px right inset without changing title or preview measure, and paints above the row interaction wash while that wash remains active."
         ],
         "responsiveBehavior": [
-          "Field fills the width supplied by its parent and makes the slotted control fill that field width.",
-          "The form layout owns column count, wrapping, and responsive placement; Field keeps the vertical label-control-message composition intact."
+          "Long titles and previews truncate without displacing trailing status."
         ],
-        "frameworkCaveats": {
-          "customElements": [
-            "Set fieldId only when another element must reference a predictable control ID; otherwise use the generated association.",
-            "Assign child component values and option arrays through their normal JavaScript properties."
-          ],
-          "react": [
-            "Compose one DsInput, DsSelect, or DsSelectMulti child and control validation timing in the form owner."
-          ],
-          "angular": [
-            "Compose the generated Field adapter around the control adapter and its matching Angular value accessor."
-          ]
-        },
         "references": [
           {
             "label": "Storybook examples",
-            "path": "src/wc/components/Field/Field.stories.ts"
-          },
-          {
-            "label": "Cross-browser form and accessibility coverage",
-            "path": "tests/e2e/forms.spec.ts"
+            "path": "src/wc/components/ConversationList/ConversationList.stories.ts"
           }
         ]
       },
       "api": {
         "props": {
-          "description": {
-            "type": "string | undefined",
+          "conversationId": {
+            "type": "string",
             "required": false
           },
-          "error": {
+          "conversationTitle": {
+            "type": "string",
+            "required": false
+          },
+          "preview": {
+            "type": "string",
+            "required": false
+          },
+          "selected": {
             "type": "boolean",
             "required": false
           },
-          "errorMessage": {
-            "type": "string | undefined",
+          "state": {
+            "type": "ConversationItemState",
             "required": false
           },
-          "fieldId": {
-            "type": "string | undefined",
+          "statusLabel": {
+            "type": "string",
             "required": false
           },
-          "label": {
+          "unreadCount": {
+            "type": "number",
+            "required": false
+          },
+          "updatedAt": {
             "type": "string",
-            "required": true
+            "required": false
           }
         },
-        "events": [],
+        "events": [
+          {
+            "name": "dsSelect",
+            "detail": "{ id: string }"
+          }
+        ],
         "slots": []
       },
       "exports": {
-        "customElement": "ds-field",
-        "react": "DsField",
-        "angular": "DsField"
+        "customElement": "ds-conversation-list-item",
+        "react": "DsConversationListItem",
+        "angular": "DsConversationListItem"
       },
       "dependencies": [
         "@ds-mo/ui",
         "@ds-mo/tokens"
       ],
       "componentDependencies": [
+        "badge",
+        "loader",
         "text"
       ]
     },
     {
-      "id": "component:ds-icon",
-      "tag": "ds-icon",
-      "name": "icon",
-      "title": "Icon",
-      "summary": "Secure, lazily loaded renderer for canonical IcoMo system and flag glyphs, decorative by default with optional graphic semantics.",
+      "id": "component:ds-conversation-list-section",
+      "tag": "ds-conversation-list-section",
+      "name": "conversation-list-section",
+      "title": "ConversationListSection",
+      "summary": "Semantically labelled section for grouping conversation rows by meaningful chronology or category.",
       "intentStatus": "complete",
       "intent": {
         "audience": "general",
-        "status": "stable",
-        "summary": "Secure, lazily loaded renderer for canonical IcoMo system and flag glyphs, decorative by default with optional graphic semantics.",
+        "status": "experimental",
+        "summary": "Semantically labelled section for grouping conversation rows by meaningful chronology or category.",
         "useWhen": [
-          "An approved IcoMo system glyph supplements visible text or control chrome.",
-          "A canonical flag glyph communicates a country or region with adjacent text or an explicit localized label.",
-          "A standalone non-interactive symbol conveys meaning that is unavailable from nearby text."
+          "A conversation list needs visible groups such as Today, Yesterday, or Older."
         ],
         "avoidWhen": [
-          "The glyph itself must be clickable or keyboard interactive; use an appropriate button or link and compose Icon inside it.",
-          "The visual is an illustration, logo, chart, or arbitrary SVG artwork rather than a canonical IcoMo glyph.",
-          "An alias, guessed name, or case-insensitive lookup would be required; runtime lookup uses exact canonical export names.",
-          "A fallback glyph would be required when loading fails; Icon intentionally preserves an empty fixed-size box."
-        ],
-        "alternatives": [
-          {
-            "when": "The icon initiates an action or persistent toggle.",
-            "component": "component:ds-button-unfilled",
-            "reason": "ButtonUnfilled owns interaction, focus, naming, and toggle semantics."
-          },
-          {
-            "when": "The visual communicates indeterminate loading progress.",
-            "component": "component:ds-loader",
-            "reason": "Loader owns progress status and motion behavior."
-          },
-          {
-            "when": "The compact visual is an unread count or notification dot.",
-            "component": "component:ds-badge",
-            "reason": "Badge owns supplemental notification semantics."
-          }
+          "A flat list is clearer or the proposed grouping has no meaning to readers."
         ],
         "commonlyComposedWith": [
-          "component:ds-button-filled",
-          "component:ds-button-unfilled",
-          "component:ds-menu",
-          "component:ds-panel-nav"
+          "component:ds-conversation-list",
+          "component:ds-conversation-list-item"
         ],
-        "accessibility": [
-          "Icons are decorative by default and remain hidden from assistive technology when visible text or an owning control already communicates the meaning.",
-          "The owning button, link, or composite control provides the accessible name; do not repeat that name on its nested Icon.",
-          "Provide an explicit label only when the non-interactive icon itself communicates otherwise unavailable meaning.",
-          "Tertiary and quaternary foregrounds are restricted to icons inside genuinely inactive or disabled UI, or to purely decorative icons; quaternary is the fainter tier, and informative icons and meaningful status graphics retain sufficient rendered contrast even when aria-hidden.",
-          "Informative flags require an explicit localized country or region label; never derive accessible text from the export name.",
-          "Icon never receives focus or owns interaction."
+        "patterns": [
+          "pattern:conversation"
         ],
-        "states": [
-          "Omitted color inherits currentColor from the owning context. Explicit semantic aliases and CSS-variable references are available when the icon has an independent color role.",
-          "Prefer the owning control's isInactive or native disabled state over manually selecting tertiary or quaternary so visual treatment and inactive semantics remain synchronized.",
-          "Built-in glyph lookup accepts exact canonical IcoMo export names only. Names beginning with Flag select the flag catalog automatically.",
-          "A cache miss lazy-loads into a fixed-size box without layout shift. Unknown names, failed loads, and rejected markup leave that box empty.",
-          "Critical first-paint glyphs may be pre-registered before rendering; all resolved glyphs share a global cache.",
-          "Every SVG is validated at the render boundary and injected as parsed DOM nodes so app-registered markup cannot bypass executable-content or external-reference checks."
+        "accessibility": [
+          "The visible heading labels the section and must describe the relationship shared by its rows."
         ],
         "responsiveBehavior": [
-          "The owning component or layout chooses icon size and any responsive changes.",
-          "Icon does not scale from viewport width or change glyphs automatically."
+          "Rows remain full width while the heading stays visible in document order."
         ],
-        "frameworkCaveats": {
-          "customElements": [
-            "Import each canonical glyph as an SVG string and call registerIcons before first render when synchronous critical-icon paint is required."
-          ],
-          "react": [
-            "Keep nested control icons decorative and place the accessible name on the owning React control."
-          ],
-          "angular": [
-            "Keep nested control icons decorative and place the accessible name on the owning Angular control."
-          ]
-        },
         "references": [
           {
             "label": "Storybook examples",
-            "path": "src/wc/components/Icon/Icon.stories.ts"
-          },
-          {
-            "label": "Preload API guidance",
-            "path": "src/wc/components/Icon/icon-cache.ts"
+            "path": "src/wc/components/ConversationList/ConversationList.stories.ts"
           }
         ]
       },
       "api": {
         "props": {
-          "color": {
-            "type": "IconColor",
-            "required": false
-          },
-          "label": {
-            "type": "string | undefined",
-            "required": false
-          },
-          "name": {
+          "heading": {
             "type": "string",
             "required": false
           },
-          "size": {
-            "type": "IconSize",
+          "sectionId": {
+            "type": "string",
             "required": false
           }
         },
@@ -2006,324 +2306,1198 @@
         "slots": []
       },
       "exports": {
-        "customElement": "ds-icon",
-        "react": "DsIcon",
-        "angular": "DsIcon"
+        "customElement": "ds-conversation-list-section",
+        "react": "DsConversationListSection",
+        "angular": "DsConversationListSection"
       },
       "dependencies": [
         "@ds-mo/ui",
-        "@ds-mo/tokens",
-        "@ds-mo/icons"
+        "@ds-mo/tokens"
       ],
-      "componentDependencies": []
+      "componentDependencies": [
+        "text"
+      ]
     },
     {
-      "id": "component:ds-input",
-      "tag": "ds-input",
-      "name": "input",
-      "title": "Input",
-      "summary": "Form-associated single-line text field for primary and secondary application backgrounds, with native text input behavior, three control densities, optional leading and trailing content, search clearing, and validation.",
+      "id": "component:ds-divider",
+      "tag": "ds-divider",
+      "name": "divider",
+      "title": "Divider",
+      "summary": "Horizontal or vertical separator between sibling content groups, decorative by default with optional structural semantics.",
       "intentStatus": "complete",
       "intent": {
         "audience": "general",
         "status": "stable",
-        "summary": "Form-associated single-line text field for primary and secondary application backgrounds, with native text input behavior, three control densities, optional leading and trailing content, search clearing, and validation.",
+        "summary": "Horizontal or vertical separator between sibling content groups, decorative by default with optional structural semantics.",
         "useWhen": [
-          "A user must enter or edit one line of text, an email address, telephone number, URL, search query, or password.",
-          "The value must participate in native, Angular, or React form state.",
-          "A compact filter or toolbar needs a single-line search field that follows the shared control-density recipe."
+          "Related sibling content groups on one surface need stronger visual separation than spacing alone provides.",
+          "A list or panel needs an inset separator that does not define the outer edge of its container.",
+          "Meaningful document or group structure requires an explicit horizontal or vertical separator."
         ],
         "avoidWhen": [
-          "The user chooses from a finite set of known values.",
-          "The user must enter multiple paragraphs or formatted content.",
-          "The value is adjusted primarily by dragging within a numeric range."
+          "Spacing alone communicates the grouping clearly.",
+          "The line defines a container edge, control outline, or selected state; use the owning component's border treatment.",
+          "The divider would compensate for weak headings or unclear information hierarchy.",
+          "A decorative flourish does not clarify grouping."
         ],
         "alternatives": [
           {
-            "when": "The value comes from a finite set of known choices.",
-            "component": "component:ds-select",
-            "reason": "Select exposes the available values and owns listbox selection behavior."
-          },
-          {
-            "when": "The value is an immediate on/off setting.",
-            "component": "component:ds-switch",
-            "reason": "Switch communicates a binary setting instead of free text entry."
+            "when": "Content needs an enclosing surface and outer boundary.",
+            "component": "component:ds-card",
+            "reason": "Card owns container chrome, structure, and edge treatment."
           },
           {
-            "when": "The value is chosen from a bounded numeric range.",
-            "component": "component:ds-slider",
-            "reason": "Slider supports direct range adjustment and communicates the current position."
+            "when": "A static compact label is being used to name a group.",
+            "component": "component:ds-text",
+            "reason": "Text communicates hierarchy directly instead of relying on a line."
           }
         ],
         "commonlyComposedWith": [
-          "component:ds-field",
-          "component:ds-icon",
-          "component:ds-text"
+          "component:ds-card",
+          "component:ds-menu",
+          "component:ds-panel-sub-nav"
+        ],
+        "accessibility": [
+          "Keep purely visual dividers hidden from assistive technology.",
+          "Expose separator semantics only when the line represents meaningful document or group structure.",
+          "Semantic orientation must match the divider's visual orientation.",
+          "Do not use a semantic divider as a substitute for headings, landmarks, or explicit group labels."
+        ],
+        "states": [
+          "Horizontal and vertical variants separate sibling groups along the parent's layout axis.",
+          "The omitted background context is for primary and secondary surfaces. Explicit faint documents a faint surface while using the same standard divider token.",
+          "Other background contexts select their matching divider token, including navigation where Divider is composed inside app chrome.",
+          "Inset is symmetric along the line axis. Explicit length is reserved for layout-specific separators; otherwise the line fills the available axis."
+        ],
+        "responsiveBehavior": [
+          "The parent layout decides whether to change orientation, visibility, inset, or length at responsive breakpoints.",
+          "Divider does not infer layout direction or hide itself responsively."
+        ],
+        "frameworkCaveats": {
+          "customElements": [
+            "Set semantic mode only from known document structure; presentation alone should remain hidden from assistive technology."
+          ],
+          "react": [
+            "Derive orientation and visibility from the parent layout rather than viewport logic inside Divider."
+          ],
+          "angular": [
+            "Derive orientation and visibility from the parent layout rather than viewport logic inside Divider."
+          ]
+        },
+        "references": [
+          {
+            "label": "Storybook examples",
+            "path": "src/wc/components/Divider/Divider.stories.ts"
+          }
+        ]
+      },
+      "api": {
+        "props": {
+          "background": {
+            "type": "DividerBackground | undefined",
+            "required": false
+          },
+          "inset": {
+            "type": "DividerInset",
+            "required": false
+          },
+          "length": {
+            "type": "DividerLength",
+            "required": false
+          },
+          "orientation": {
+            "type": "DividerOrientation",
+            "required": false
+          },
+          "semantic": {
+            "type": "boolean",
+            "required": false
+          }
+        },
+        "events": [],
+        "slots": []
+      },
+      "exports": {
+        "customElement": "ds-divider",
+        "react": "DsDivider",
+        "angular": "DsDivider"
+      },
+      "dependencies": [
+        "@ds-mo/ui",
+        "@ds-mo/tokens"
+      ],
+      "componentDependencies": []
+    },
+    {
+      "id": "component:ds-empty-state",
+      "tag": "ds-empty-state",
+      "name": "empty-state",
+      "title": "EmptyState",
+      "summary": "Centered empty-content message composed as icon plus title plus body, title plus body, or compact body-only content.",
+      "intentStatus": "complete",
+      "intent": {
+        "audience": "general",
+        "status": "stable",
+        "summary": "Centered empty-content message composed as icon plus title plus body, title plus body, or compact body-only content.",
+        "useWhen": [
+          "A bounded content area is in a first-use, no-content, filtered no-results, or no-access state and needs a calm explanatory message tailored to that cause.",
+          "A prominent empty region benefits from a decorative icon, visual title, and supporting body copy.",
+          "A compact owner such as a Select popup needs only centered body copy."
+        ],
+        "avoidWhen": [
+          "Content is still loading; use Skeleton for predictable structure or Loader for an indeterminate operation.",
+          "The state is an error, warning, or confirmation that needs semantic intent and announcement from the owning workflow.",
+          "The state needs a recovery action, link, or other interactive content; the current EmptyState pattern is intentionally message-only.",
+          "A decorative illustration, arbitrary rich content, or custom layout is required."
+        ],
+        "alternatives": [
+          {
+            "when": "A content region is waiting for structured data.",
+            "component": "component:ds-skeleton",
+            "reason": "Skeleton preserves expected geometry while content is pending."
+          },
+          {
+            "when": "An operation is progressing without predictable content structure.",
+            "component": "component:ds-loader",
+            "reason": "Loader owns indeterminate progress rather than an empty outcome."
+          },
+          {
+            "when": "Only ordinary prose is needed without empty-state layout.",
+            "component": "component:ds-text",
+            "reason": "Text owns typography without adding centered empty-state composition."
+          }
+        ],
+        "commonlyComposedWith": [
+          "component:ds-select",
+          "component:ds-text",
+          "component:ds-icon"
+        ],
+        "accessibility": [
+          "The optional icon is decorative; the title and body provide all meaning in text.",
+          "EmptyState does not create a live region or alert automatically. The owner decides whether a dynamic transition requires announcement.",
+          "The visual title does not impose a document heading level because the correct hierarchy belongs to the consuming page or region.",
+          "Keep localized body copy concise and sufficient when using the body-only variant."
+        ],
+        "states": [
+          "Supported compositions are icon plus title plus body, title plus body, and body only; body copy is present in every supported composition.",
+          "The decorative icon renders at xl in the primary foreground with an 8px gap before the text group and only when a title is also provided.",
+          "The visual title uses title-small primary text; body uses body-medium secondary text with a 4px title-to-body gap.",
+          "All content is centered. The owner supplies container size and surrounding padding; do not compose actions into or immediately alongside the current EmptyState pattern.",
+          "First-use, no-content, no-results, and no-access states reuse this primitive with cause-specific localized messages rather than visual variants."
+        ],
+        "responsiveBehavior": [
+          "The owner controls available width and height; text wraps naturally while remaining centered.",
+          "EmptyState does not infer breakpoints or change composition automatically."
+        ],
+        "frameworkCaveats": {
+          "customElements": [
+            "Pass canonical IcoMo icon names and localized heading/body strings through properties or attributes."
+          ],
+          "react": [
+            "Choose one supported composition by passing body with optional heading and icon props."
+          ],
+          "angular": [
+            "Choose one supported composition by binding body with optional heading and icon inputs."
+          ]
+        },
+        "references": [
+          {
+            "label": "Storybook examples",
+            "path": "src/wc/components/EmptyState/EmptyState.stories.ts"
+          }
+        ]
+      },
+      "api": {
+        "props": {
+          "body": {
+            "type": "string",
+            "required": false
+          },
+          "heading": {
+            "type": "string | undefined",
+            "required": false
+          },
+          "icon": {
+            "type": "string | undefined",
+            "required": false
+          }
+        },
+        "events": [],
+        "slots": []
+      },
+      "exports": {
+        "customElement": "ds-empty-state",
+        "react": "DsEmptyState",
+        "angular": "DsEmptyState"
+      },
+      "dependencies": [
+        "@ds-mo/ui",
+        "@ds-mo/tokens",
+        "@ds-mo/icons"
+      ],
+      "componentDependencies": [
+        "icon",
+        "text"
+      ]
+    },
+    {
+      "id": "component:ds-field",
+      "tag": "ds-field",
+      "name": "field",
+      "title": "Field",
+      "summary": "Accessible form-field composition that gives one Input or Select a persistent label, optional guidance, shared error presentation, stable IDs, and observable interaction state.",
+      "intentStatus": "complete",
+      "intent": {
+        "audience": "general",
+        "status": "stable",
+        "summary": "Accessible form-field composition that gives one Input or Select a persistent label, optional guidance, shared error presentation, stable IDs, and observable interaction state.",
+        "useWhen": [
+          "An Input, Select, or SelectMulti needs a persistent visible label in a form.",
+          "Help text or an error message must be programmatically associated with one control.",
+          "A form layout needs one consistent label-control-message rhythm."
+        ],
+        "avoidWhen": [
+          "The component already owns its visible label and complete selection semantics, such as Checkbox, Radio, or Switch.",
+          "Several controls belong to one question; use a semantic fieldset and legend instead.",
+          "Text describes a region or group rather than one form control."
+        ],
+        "alternatives": [
+          {
+            "when": "Several related controls answer one question.",
+            "component": "component:ds-text",
+            "reason": "Use native fieldset and legend semantics, then compose Text only for supporting content."
+          }
+        ],
+        "commonlyComposedWith": [
+          "component:ds-input",
+          "component:ds-select",
+          "component:ds-select-multi",
+          "component:ds-text"
+        ],
+        "accessibility": [
+          "Slot exactly one form control. Field assigns its stable control ID and connects the visible label automatically.",
+          "The visible description or error ID is merged with any authored aria-describedby references; a rendered error replaces the description.",
+          "The error prop forwards aria-invalid and supported design-system control error styling; put visible error text on Field, not again on the child control.",
+          "Clicking the label focuses the slotted design-system control without opening a Select popup.",
+          "Do not use placeholder text as the only label. Keep label text concise and put format or consequence guidance in description."
+        ],
+        "states": [
+          "Field exposes data-focused, data-filled, data-dirty, data-touched, data-invalid, data-disabled, and data-required hooks while the slotted control remains the source of value and interaction behavior.",
+          "A rendered error replaces the description; preserve essential guidance in the error message so users retain what they need to correct the field.",
+          "Field owns validation presentation but not validation timing; the form decides when to set error and errorMessage.",
+          "The label uses primary body-small emphasis, description uses secondary body-small text, and error uses negative body-small text."
+        ],
+        "responsiveBehavior": [
+          "Field fills the width supplied by its parent and makes the slotted control fill that field width.",
+          "The form layout owns column count, wrapping, and responsive placement; Field keeps the vertical label-control-message composition intact."
+        ],
+        "frameworkCaveats": {
+          "customElements": [
+            "Set fieldId only when another element must reference a predictable control ID; otherwise use the generated association.",
+            "Assign child component values and option arrays through their normal JavaScript properties."
+          ],
+          "react": [
+            "Compose one DsInput, DsSelect, or DsSelectMulti child and control validation timing in the form owner."
+          ],
+          "angular": [
+            "Compose the generated Field adapter around the control adapter and its matching Angular value accessor."
+          ]
+        },
+        "references": [
+          {
+            "label": "Storybook examples",
+            "path": "src/wc/components/Field/Field.stories.ts"
+          },
+          {
+            "label": "Cross-browser form and accessibility coverage",
+            "path": "tests/e2e/forms.spec.ts"
+          }
+        ]
+      },
+      "api": {
+        "props": {
+          "description": {
+            "type": "string | undefined",
+            "required": false
+          },
+          "error": {
+            "type": "boolean",
+            "required": false
+          },
+          "errorMessage": {
+            "type": "string | undefined",
+            "required": false
+          },
+          "fieldId": {
+            "type": "string | undefined",
+            "required": false
+          },
+          "label": {
+            "type": "string",
+            "required": true
+          }
+        },
+        "events": [],
+        "slots": []
+      },
+      "exports": {
+        "customElement": "ds-field",
+        "react": "DsField",
+        "angular": "DsField"
+      },
+      "dependencies": [
+        "@ds-mo/ui",
+        "@ds-mo/tokens"
+      ],
+      "componentDependencies": [
+        "text"
+      ]
+    },
+    {
+      "id": "component:ds-icon",
+      "tag": "ds-icon",
+      "name": "icon",
+      "title": "Icon",
+      "summary": "Secure, lazily loaded renderer for canonical IcoMo system and flag glyphs, decorative by default with optional graphic semantics.",
+      "intentStatus": "complete",
+      "intent": {
+        "audience": "general",
+        "status": "stable",
+        "summary": "Secure, lazily loaded renderer for canonical IcoMo system and flag glyphs, decorative by default with optional graphic semantics.",
+        "useWhen": [
+          "An approved IcoMo system glyph supplements visible text or control chrome.",
+          "A canonical flag glyph communicates a country or region with adjacent text or an explicit localized label.",
+          "A standalone non-interactive symbol conveys meaning that is unavailable from nearby text."
+        ],
+        "avoidWhen": [
+          "The glyph itself must be clickable or keyboard interactive; use an appropriate button or link and compose Icon inside it.",
+          "The visual is an illustration, logo, chart, or arbitrary SVG artwork rather than a canonical IcoMo glyph.",
+          "An alias, guessed name, or case-insensitive lookup would be required; runtime lookup uses exact canonical export names.",
+          "A fallback glyph would be required when loading fails; Icon intentionally preserves an empty fixed-size box."
+        ],
+        "alternatives": [
+          {
+            "when": "The icon initiates an action or persistent toggle.",
+            "component": "component:ds-button-unfilled",
+            "reason": "ButtonUnfilled owns interaction, focus, naming, and toggle semantics."
+          },
+          {
+            "when": "The visual communicates indeterminate loading progress.",
+            "component": "component:ds-loader",
+            "reason": "Loader owns progress status and motion behavior."
+          },
+          {
+            "when": "The compact visual is an unread count or notification dot.",
+            "component": "component:ds-badge",
+            "reason": "Badge owns supplemental notification semantics."
+          }
+        ],
+        "commonlyComposedWith": [
+          "component:ds-button-filled",
+          "component:ds-button-unfilled",
+          "component:ds-menu",
+          "component:ds-panel-nav"
+        ],
+        "accessibility": [
+          "Icons are decorative by default and remain hidden from assistive technology when visible text or an owning control already communicates the meaning.",
+          "The owning button, link, or composite control provides the accessible name; do not repeat that name on its nested Icon.",
+          "Provide an explicit label only when the non-interactive icon itself communicates otherwise unavailable meaning.",
+          "Tertiary and quaternary foregrounds are restricted to icons inside genuinely inactive or disabled UI, or to purely decorative icons; quaternary is the fainter tier, and informative icons and meaningful status graphics retain sufficient rendered contrast even when aria-hidden.",
+          "Informative flags require an explicit localized country or region label; never derive accessible text from the export name.",
+          "Icon never receives focus or owns interaction."
+        ],
+        "states": [
+          "Omitted color inherits currentColor from the owning context. Explicit semantic aliases and CSS-variable references are available when the icon has an independent color role.",
+          "Prefer the owning control's isInactive or native disabled state over manually selecting tertiary or quaternary so visual treatment and inactive semantics remain synchronized.",
+          "Built-in glyph lookup accepts exact canonical IcoMo export names only. Names beginning with Flag select the flag catalog automatically.",
+          "A cache miss lazy-loads into a fixed-size box without layout shift. Unknown names, failed loads, and rejected markup leave that box empty.",
+          "Critical first-paint glyphs may be pre-registered before rendering; all resolved glyphs share a global cache.",
+          "Every SVG is validated at the render boundary and injected as parsed DOM nodes so app-registered markup cannot bypass executable-content or external-reference checks."
+        ],
+        "responsiveBehavior": [
+          "The owning component or layout chooses icon size and any responsive changes.",
+          "Icon does not scale from viewport width or change glyphs automatically."
+        ],
+        "frameworkCaveats": {
+          "customElements": [
+            "Import each canonical glyph as an SVG string and call registerIcons before first render when synchronous critical-icon paint is required."
+          ],
+          "react": [
+            "Keep nested control icons decorative and place the accessible name on the owning React control."
+          ],
+          "angular": [
+            "Keep nested control icons decorative and place the accessible name on the owning Angular control."
+          ]
+        },
+        "references": [
+          {
+            "label": "Storybook examples",
+            "path": "src/wc/components/Icon/Icon.stories.ts"
+          },
+          {
+            "label": "Preload API guidance",
+            "path": "src/wc/components/Icon/icon-cache.ts"
+          }
+        ]
+      },
+      "api": {
+        "props": {
+          "color": {
+            "type": "IconColor",
+            "required": false
+          },
+          "label": {
+            "type": "string | undefined",
+            "required": false
+          },
+          "name": {
+            "type": "string",
+            "required": false
+          },
+          "size": {
+            "type": "IconSize",
+            "required": false
+          }
+        },
+        "events": [],
+        "slots": []
+      },
+      "exports": {
+        "customElement": "ds-icon",
+        "react": "DsIcon",
+        "angular": "DsIcon"
+      },
+      "dependencies": [
+        "@ds-mo/ui",
+        "@ds-mo/tokens",
+        "@ds-mo/icons"
+      ],
+      "componentDependencies": []
+    },
+    {
+      "id": "component:ds-input",
+      "tag": "ds-input",
+      "name": "input",
+      "title": "Input",
+      "summary": "Form-associated single-line text field for primary and secondary application backgrounds, with native text input behavior, three control densities, optional leading and trailing content, search clearing, and validation.",
+      "intentStatus": "complete",
+      "intent": {
+        "audience": "general",
+        "status": "stable",
+        "summary": "Form-associated single-line text field for primary and secondary application backgrounds, with native text input behavior, three control densities, optional leading and trailing content, search clearing, and validation.",
+        "useWhen": [
+          "A user must enter or edit one line of text, an email address, telephone number, URL, search query, or password.",
+          "The value must participate in native, Angular, or React form state.",
+          "A compact filter or toolbar needs a single-line search field that follows the shared control-density recipe."
+        ],
+        "avoidWhen": [
+          "The user chooses from a finite set of known values.",
+          "The user must enter multiple paragraphs or formatted content.",
+          "The value is adjusted primarily by dragging within a numeric range."
+        ],
+        "alternatives": [
+          {
+            "when": "The value comes from a finite set of known choices.",
+            "component": "component:ds-select",
+            "reason": "Select exposes the available values and owns listbox selection behavior."
+          },
+          {
+            "when": "The value is an immediate on/off setting.",
+            "component": "component:ds-switch",
+            "reason": "Switch communicates a binary setting instead of free text entry."
+          },
+          {
+            "when": "The value is chosen from a bounded numeric range.",
+            "component": "component:ds-slider",
+            "reason": "Slider supports direct range adjustment and communicates the current position."
+          }
+        ],
+        "commonlyComposedWith": [
+          "component:ds-field",
+          "component:ds-icon",
+          "component:ds-text"
+        ],
+        "accessibility": [
+          "Provide a persistent visible label through the owning field or an external native label; placeholder text is guidance and must not be the field's only label.",
+          "Choose the native input type that matches the value so browsers and assistive technology can provide appropriate semantics and keyboards.",
+          "Error text is associated with the native input and announced as an alert when the invalid state is rendered.",
+          "Read-only fields remain focusable and submittable while preventing edits; inactive or disabled fields leave the tab order and are omitted from form submission.",
+          "Suffix content must not carry information that is otherwise absent from the field's visible label, value, or description."
+        ],
+        "states": [
+          "The normal field boundary uses the shared secondary inset border. Focus promotes it to the thicker bold-brand inset stroke, while error uses the thicker bold-negative inset stroke without changing geometry.",
+          "Placeholder text is secondary at rest and quaternary while the editable field is focused because it becomes decorative once typing begins.",
+          "Entered values use the parent surface's primary foreground; prefix icons, suffix content, and resting placeholder text use its secondary foreground.",
+          "Search fields show a standard borderless CrossCircle icon action only while they contain a value. Clearing emits the empty value and restores focus to the native field.",
+          "The suffix slot is for compact units or decorations. The optional leading icon is decorative and does not replace the field label.",
+          "Use autoComplete, inputMode, and enterKeyHint to provide browser and virtual-keyboard hints without changing the value's semantic type.",
+          "The host exposes focused, filled, dirty, touched, invalid, disabled, read-only, and required data attributes for Field integration and diagnostics.",
+          "Use Input only on primary or secondary application backgrounds. It intentionally does not expose alternate surface contexts."
+        ],
+        "responsiveBehavior": [
+          "Form fields normally fill their parent; use hug width only in a compact toolbar or filter layout with an explicit width constraint.",
+          "Choose density from the containing layout: md for ordinary forms, sm or xs only where the surrounding controls use the same compact recipe.",
+          "The owner supplies layout constraints and decides when a compact field moves to its own row."
+        ],
+        "frameworkCaveats": {
+          "customElements": [
+            "Listen for dsChange for user edits and dsClear for the search clear action.",
+            "Use the form attribute on the host when associating an input rendered outside its owning form."
+          ],
+          "react": [
+            "Use DsInput, bind value for controlled application state, and handle onDsChange and onDsClear."
+          ],
+          "angular": [
+            "Import DsInput with TextValueAccessor when integrating with Angular Forms."
+          ]
+        },
+        "references": [
+          {
+            "label": "Storybook examples",
+            "path": "src/wc/components/Input/Input.stories.ts"
+          },
+          {
+            "label": "Cross-browser form and accessibility coverage",
+            "path": "tests/e2e/forms.spec.ts"
+          }
+        ]
+      },
+      "api": {
+        "props": {
+          "ariaDescribedby": {
+            "type": "string | undefined",
+            "required": false
+          },
+          "ariaLabel": {
+            "type": "string | null",
+            "required": false
+          },
+          "ariaLabelledby": {
+            "type": "string | undefined",
+            "required": false
+          },
+          "autoComplete": {
+            "type": "string | undefined",
+            "required": false
+          },
+          "autoFocus": {
+            "type": "boolean",
+            "required": false
+          },
+          "clearLabel": {
+            "type": "string",
+            "required": false
+          },
+          "disabled": {
+            "type": "boolean",
+            "required": false
+          },
+          "enterKeyHint": {
+            "type": "string",
+            "required": false
+          },
+          "error": {
+            "type": "boolean",
+            "required": false
+          },
+          "errorMessage": {
+            "type": "string | undefined",
+            "required": false
+          },
+          "form": {
+            "type": "string | undefined",
+            "required": false
+          },
+          "hasBorder": {
+            "type": "boolean",
+            "required": false
+          },
+          "icon": {
+            "type": "string | undefined",
+            "required": false
+          },
+          "inputId": {
+            "type": "string | undefined",
+            "required": false
+          },
+          "inputMode": {
+            "type": "string",
+            "required": false
+          },
+          "isInactive": {
+            "type": "boolean",
+            "required": false
+          },
+          "name": {
+            "type": "string | undefined",
+            "required": false
+          },
+          "placeholder": {
+            "type": "string | undefined",
+            "required": false
+          },
+          "readOnly": {
+            "type": "boolean",
+            "required": false
+          },
+          "required": {
+            "type": "boolean",
+            "required": false
+          },
+          "requiredMessage": {
+            "type": "string",
+            "required": false
+          },
+          "size": {
+            "type": "InputSize",
+            "required": false
+          },
+          "type": {
+            "type": "InputType",
+            "required": false
+          },
+          "value": {
+            "type": "string",
+            "required": false
+          },
+          "width": {
+            "type": "InputWidth",
+            "required": false
+          }
+        },
+        "events": [
+          {
+            "name": "dsChange",
+            "detail": "string"
+          },
+          {
+            "name": "dsClear",
+            "detail": "void"
+          }
+        ],
+        "slots": []
+      },
+      "exports": {
+        "customElement": "ds-input",
+        "react": "DsInput",
+        "angular": "DsInput"
+      },
+      "dependencies": [
+        "@ds-mo/ui",
+        "@ds-mo/tokens",
+        "@ds-mo/icons"
+      ],
+      "componentDependencies": [
+        "button-unfilled",
+        "icon",
+        "text"
+      ]
+    },
+    {
+      "id": "component:ds-loader",
+      "tag": "ds-loader",
+      "name": "loader",
+      "title": "Loader",
+      "summary": "Indeterminate progress glyph for ongoing operations, inheriting owner color and optionally exposing standalone polite status text.",
+      "intentStatus": "complete",
+      "intent": {
+        "audience": "general",
+        "status": "stable",
+        "summary": "Indeterminate progress glyph for ongoing operations, inheriting owner color and optionally exposing standalone polite status text.",
+        "useWhen": [
+          "An action or operation is in progress and its remaining duration cannot be quantified.",
+          "A button, field, or bounded workflow needs a compact visual busy indicator owned by that control or region.",
+          "A standalone operation needs a visible spinner with contextual polite status text."
+        ],
+        "avoidWhen": [
+          "Pending content has a predictable structure; use Skeleton to preserve that layout.",
+          "Progress is measurable; use an appropriate determinate progress pattern.",
+          "The UI needs a blocking overlay or automatic centering; the owning layout must provide that structure.",
+          "Success, failure, retry, or completion must be communicated; the owning workflow handles outcomes."
+        ],
+        "alternatives": [
+          {
+            "when": "A content region is waiting for structured data.",
+            "component": "component:ds-skeleton",
+            "reason": "Skeleton preserves the expected content geometry while data loads."
+          },
+          {
+            "when": "A static visual symbol is needed without progress semantics.",
+            "component": "component:ds-icon",
+            "reason": "Icon owns non-progress system and flag glyphs."
+          }
+        ],
+        "commonlyComposedWith": [
+          "component:ds-button-filled",
+          "component:ds-button-unfilled",
+          "component:ds-input",
+          "component:ds-select"
+        ],
+        "accessibility": [
+          "When Loader is nested in a busy button, field, or region, keep it unnamed and expose busy state from the owner.",
+          "Standalone Loader requires contextual status text that explains what is loading; do not rely on a generic visual spinner alone.",
+          "Loader is an informative progress graphic and must retain sufficient rendered contrast; tertiary and quaternary are not supported standalone or informative Loader treatments.",
+          "Avoid duplicate announcements from both Loader and its owning busy region.",
+          "Reduced motion stops rotation while keeping the glyph and status semantics visible."
+        ],
+        "states": [
+          "Loader communicates indeterminate progress only and does not emit completion or failure events.",
+          "Omitted color inherits currentColor. Explicit semantic aliases and CSS-variable references match Icon when an independent progress color is required.",
+          "Nested Loader inherits a readable color from its owning busy control or region rather than selecting tertiary or quaternary directly.",
+          "The owner decides whether to delay Loader visibility for short operations and removes it when the operation settles.",
+          "The owner reserves space and supplies centering or overlay layout so Loader never causes unexpected layout movement."
+        ],
+        "responsiveBehavior": [
+          "The owning component or layout chooses Loader size, placement, and any responsive changes.",
+          "Loader does not infer container size or viewport breakpoints."
+        ],
+        "frameworkCaveats": {
+          "customElements": [
+            "Use the label only for standalone status; nested usage should synchronize aria-busy on the owning element."
+          ],
+          "react": [
+            "Derive Loader visibility and the owner's busy state from the same operation state."
+          ],
+          "angular": [
+            "Derive Loader visibility and the owner's busy state from the same operation state."
+          ]
+        },
+        "references": [
+          {
+            "label": "Storybook examples",
+            "path": "src/wc/components/Loader/Loader.stories.ts"
+          }
+        ]
+      },
+      "api": {
+        "props": {
+          "color": {
+            "type": "LoaderColor",
+            "required": false
+          },
+          "label": {
+            "type": "string | undefined",
+            "required": false
+          },
+          "size": {
+            "type": "LoaderSize",
+            "required": false
+          }
+        },
+        "events": [],
+        "slots": []
+      },
+      "exports": {
+        "customElement": "ds-loader",
+        "react": "DsLoader",
+        "angular": "DsLoader"
+      },
+      "dependencies": [
+        "@ds-mo/ui",
+        "@ds-mo/tokens"
+      ],
+      "componentDependencies": []
+    },
+    {
+      "id": "component:ds-markdown",
+      "tag": "ds-markdown",
+      "name": "markdown",
+      "title": "Markdown",
+      "summary": "Safe CommonMark and GFM renderer built from parsed nodes without raw HTML injection.",
+      "intentStatus": "complete",
+      "intent": {
+        "audience": "specialized",
+        "status": "experimental",
+        "summary": "Safe CommonMark and GFM renderer built from parsed nodes without raw HTML injection.",
+        "useWhen": [
+          "Trusted or untrusted message text needs headings, lists, links, tables, tasks, quotes, and code."
+        ],
+        "avoidWhen": [
+          "The application needs arbitrary HTML, custom plugins, or a full document CMS renderer."
+        ],
+        "commonlyComposedWith": [
+          "component:ds-code-block",
+          "component:ds-message-bubble"
+        ],
+        "patterns": [
+          "pattern:conversation",
+          "pattern:agent-chat"
         ],
         "accessibility": [
-          "Provide a persistent visible label through the owning field or an external native label; placeholder text is guidance and must not be the field's only label.",
-          "Choose the native input type that matches the value so browsers and assistive technology can provide appropriate semantics and keyboards.",
-          "Error text is associated with the native input and announced as an alert when the invalid state is rendered.",
-          "Read-only fields remain focusable and submittable while preventing edits; inactive or disabled fields leave the tab order and are omitted from form submission.",
-          "Suffix content must not carry information that is otherwise absent from the field's visible label, value, or description."
+          "Semantic parsed elements preserve heading, list, table, quote, and code relationships.",
+          "Raw HTML is ignored and unsafe link schemes are not made interactive.",
+          "Link text must remain descriptive in authored content."
         ],
         "states": [
-          "The normal field boundary uses the shared secondary inset border. Focus promotes it to the thicker bold-brand inset stroke, while error uses the thicker bold-negative inset stroke without changing geometry.",
-          "Placeholder text is secondary at rest and quaternary while the editable field is focused because it becomes decorative once typing begins.",
-          "Entered values use the parent surface's primary foreground; prefix icons, suffix content, and resting placeholder text use its secondary foreground.",
-          "Search fields show a standard borderless CrossCircle icon action only while they contain a value. Clearing emits the empty value and restores focus to the native field.",
-          "The suffix slot is for compact units or decorations. The optional leading icon is decorative and does not replace the field label.",
-          "Use autoComplete, inputMode, and enterKeyHint to provide browser and virtual-keyboard hints without changing the value's semantic type.",
-          "The host exposes focused, filled, dirty, touched, invalid, disabled, read-only, and required data attributes for Field integration and diagnostics.",
-          "Use Input only on primary or secondary application backgrounds. It intentionally does not expose alternate surface contexts."
+          "Streaming updates are coalesced to one parse and render per animation frame."
         ],
         "responsiveBehavior": [
-          "Form fields normally fill their parent; use hug width only in a compact toolbar or filter layout with an explicit width constraint.",
-          "Choose density from the containing layout: md for ordinary forms, sm or xs only where the surrounding controls use the same compact recipe.",
-          "The owner supplies layout constraints and decides when a compact field moves to its own row."
+          "Tables and code scroll horizontally instead of forcing the transcript wider."
+        ],
+        "references": [
+          {
+            "label": "Storybook examples",
+            "path": "src/wc/components/MessageScroller/MessageScroller.stories.ts"
+          }
+        ]
+      },
+      "api": {
+        "props": {
+          "content": {
+            "type": "string",
+            "required": false
+          },
+          "streaming": {
+            "type": "boolean",
+            "required": false
+          }
+        },
+        "events": [],
+        "slots": []
+      },
+      "exports": {
+        "customElement": "ds-markdown",
+        "react": "DsMarkdown",
+        "angular": "DsMarkdown"
+      },
+      "dependencies": [
+        "@ds-mo/ui",
+        "@ds-mo/tokens"
+      ],
+      "componentDependencies": [
+        "code-block"
+      ]
+    },
+    {
+      "id": "component:ds-menu",
+      "tag": "ds-menu",
+      "name": "menu",
+      "title": "Menu",
+      "summary": "Anchored action menu with flat commands, grouped sections, single-selection radio choices, supplemental notification dots, switches, and destructive actions.",
+      "intentStatus": "complete",
+      "intent": {
+        "audience": "general",
+        "status": "stable",
+        "summary": "Anchored action menu with flat commands, grouped sections, single-selection radio choices, supplemental notification dots, switches, and destructive actions.",
+        "useWhen": [
+          "A trigger reveals a short contextual list of commands or state-changing actions.",
+          "Actions need grouping, mutually exclusive selected state, supplemental notification dots, switch rows, or destructive treatment."
+        ],
+        "avoidWhen": [
+          "The user is selecting a value for a form field.",
+          "The content requires rich dialog interaction or a multi-step workflow.",
+          "The actions should remain persistently visible."
+        ],
+        "alternatives": [
+          {
+            "when": "The choice is a form value with a label, validation, and submitted value.",
+            "component": "component:ds-select",
+            "reason": "Select provides form-control semantics and value ownership."
+          },
+          {
+            "when": "Several form values may be selected.",
+            "component": "component:ds-select-multi",
+            "reason": "SelectMulti provides multi-select listbox semantics, array value ownership, and count presentation."
+          },
+          {
+            "when": "The interaction needs substantial content, confirmation, or a form.",
+            "component": "component:ds-modal",
+            "reason": "Modal owns focus containment and dialog-level interaction."
+          }
+        ],
+        "commonlyComposedWith": [
+          "component:ds-button-unfilled",
+          "component:ds-panel-nav",
+          "component:ds-switch",
+          "component:ds-swatch-picker"
+        ],
+        "patterns": [
+          "pattern:menu-trigger"
+        ],
+        "accessibility": [
+          "Anchor the menu to the control that opens it and return focus to that control when the menu closes.",
+          "Open with visible initial focus only when the trigger was activated from the keyboard.",
+          "Keep disabled items discoverable only when their unavailable state is meaningful.",
+          "Switch rows use menuitemcheckbox semantics on the row; the nested ds-switch is an aria-hidden md presentation indicator.",
+          "Single-selection menus use menuitemradio semantics and aria-checked on each row; the leading radio mark is presentation-only.",
+          "A swatch-picker section changes the popup to a non-modal dialog so its radio group and ordinary preference buttons keep valid nested semantics; Tab moves between its controls, then leaves and closes at the popup boundary.",
+          "Use notification dots only as supplemental status and not as the sole indication of important information."
+        ],
+        "states": [
+          "The host owns open state and responds to selection and close events.",
+          "Use either flat items or sections, not both.",
+          "After dsSelect from a switch row, update switchValue in the items property so the controlled indicator reflects the new state.",
+          "For selectionMode single, keep exactly one item isSelected and update the items property after dsSelect.",
+          "Arrays, objects, and element anchors must be assigned as JavaScript properties.",
+          "Use a swatch-picker section for a small curated visual preference and apply dsSwatchSelect immediately without closing the popup; the legacy gradient-picker section and dsGradientSelect remain compatibility-only."
+        ],
+        "responsiveBehavior": [
+          "Keep the default choice-cell anchor alignment so the first or last interactive row edge aligns with its trigger, matching Select; use popup-frame only for deliberate custom frame geometry.",
+          "Choose placement relative to the trigger and allow the component to clamp the popup to the viewport.",
+          "Avoid fixed widths that exceed narrow viewports."
         ],
         "frameworkCaveats": {
           "customElements": [
-            "Listen for dsChange for user edits and dsClear for the search clear action.",
-            "Use the form attribute on the host when associating an input rendered outside its owning form."
+            "Assign items, sections, and HTMLElement anchors as properties after the element is defined."
           ],
           "react": [
-            "Use DsInput, bind value for controlled application state, and handle onDsChange and onDsClear."
+            "Pass arrays and objects as wrapper props and handle generated onDsSelect and onDsClose event props."
           ],
           "angular": [
-            "Import DsInput with TextValueAccessor when integrating with Angular Forms."
+            "Use property bindings for arrays, objects, and anchors and event bindings for dsSelect and dsClose."
           ]
         },
         "references": [
           {
             "label": "Storybook examples",
-            "path": "src/wc/components/Input/Input.stories.ts"
+            "path": "src/wc/components/Menu/Menu.stories.ts"
           },
           {
-            "label": "Cross-browser form and accessibility coverage",
-            "path": "tests/e2e/forms.spec.ts"
+            "label": "Framework integration",
+            "path": "docs/framework-integration.md"
           }
         ]
       },
       "api": {
         "props": {
-          "ariaDescribedby": {
-            "type": "string | undefined",
+          "align": {
+            "type": "MenuAlign",
             "required": false
           },
-          "ariaLabel": {
-            "type": "string | null",
+          "alignOffset": {
+            "type": "number | string",
             "required": false
           },
-          "ariaLabelledby": {
-            "type": "string | undefined",
+          "anchor": {
+            "type": "HTMLElement | undefined",
             "required": false
           },
-          "autoComplete": {
+          "anchorAlignment": {
+            "type": "ChoicePopupAnchorAlignment",
+            "required": false
+          },
+          "anchorId": {
             "type": "string | undefined",
             "required": false
           },
-          "autoFocus": {
+          "initialFocusVisible": {
             "type": "boolean",
             "required": false
           },
-          "clearLabel": {
+          "items": {
+            "type": "MenuItemData[]",
+            "required": false
+          },
+          "menuLabel": {
             "type": "string",
             "required": false
           },
-          "disabled": {
-            "type": "boolean",
+          "menuWidth": {
+            "type": "string | undefined",
             "required": false
           },
-          "enterKeyHint": {
-            "type": "string",
+          "minWidth": {
+            "type": "string | undefined",
             "required": false
           },
-          "error": {
+          "open": {
             "type": "boolean",
             "required": false
           },
-          "errorMessage": {
-            "type": "string | undefined",
+          "sections": {
+            "type": "MenuSection[]",
             "required": false
           },
-          "form": {
-            "type": "string | undefined",
+          "selectionMode": {
+            "type": "MenuSelectionMode",
             "required": false
           },
-          "hasBorder": {
-            "type": "boolean",
+          "side": {
+            "type": "MenuSide",
             "required": false
           },
-          "icon": {
-            "type": "string | undefined",
+          "sideOffset": {
+            "type": "number | string",
             "required": false
+          }
+        },
+        "events": [
+          {
+            "name": "dsClose",
+            "detail": "void"
           },
-          "inputId": {
-            "type": "string | undefined",
-            "required": false
+          {
+            "name": "dsGradientSelect",
+            "detail": "ShellGradientPreset"
           },
-          "inputMode": {
+          {
+            "name": "dsSelect",
+            "detail": "MenuItemData"
+          },
+          {
+            "name": "dsSwatchSelect",
+            "detail": "string"
+          }
+        ],
+        "slots": []
+      },
+      "exports": {
+        "customElement": "ds-menu",
+        "react": "DsMenu",
+        "angular": "DsMenu"
+      },
+      "dependencies": [
+        "@ds-mo/ui",
+        "@ds-mo/tokens"
+      ],
+      "componentDependencies": [
+        "badge",
+        "swatch-picker",
+        "switch",
+        "text"
+      ]
+    },
+    {
+      "id": "component:ds-message",
+      "tag": "ds-message",
+      "name": "message",
+      "title": "Message",
+      "summary": "Channel-neutral message row owning direction, grouping, author, time, delivery metadata, and accessory regions.",
+      "intentStatus": "complete",
+      "intent": {
+        "audience": "general",
+        "status": "experimental",
+        "summary": "Channel-neutral message row owning direction, grouping, author, time, delivery metadata, and accessory regions.",
+        "useWhen": [
+          "A transcript contains messages that need consistent incoming, outgoing, or system layout."
+        ],
+        "avoidWhen": [
+          "Content is not an authored message in a conversation."
+        ],
+        "commonlyComposedWith": [
+          "component:ds-message-bubble",
+          "component:ds-message-scroller"
+        ],
+        "patterns": [
+          "pattern:conversation"
+        ],
+        "accessibility": [
+          "Author and time metadata remain textual when they are necessary to interpret the transcript.",
+          "Delivery failure must be expressed in text rather than color alone."
+        ],
+        "states": [
+          "Pass an ISO timestamp. Message keeps the full value in dateTime and formats the visible value as a localized time; applications must not render a raw ISO string as visible transcript metadata.",
+          "Grouping joins adjacent bubble corners, shows the incoming author only at the start, and shows delivery/time metadata only at the end. Outgoing author remains in the accessible message label without repeating a visible You label.",
+          "Set showAuthor false only when the product makes participant and assistant roles visually self-evident; continue passing author so the accessible message label remains specific."
+        ],
+        "responsiveBehavior": [
+          "Outgoing and incoming rows adapt to available width while preserving their directional alignment."
+        ],
+        "references": [
+          {
+            "label": "Storybook examples",
+            "path": "src/wc/components/MessageScroller/MessageScroller.stories.ts"
+          }
+        ]
+      },
+      "api": {
+        "props": {
+          "author": {
             "type": "string",
             "required": false
           },
-          "isInactive": {
-            "type": "boolean",
+          "deliveryState": {
+            "type": "MessageDeliveryState | undefined",
             "required": false
           },
-          "name": {
-            "type": "string | undefined",
+          "direction": {
+            "type": "MessageDirection",
             "required": false
           },
-          "placeholder": {
-            "type": "string | undefined",
+          "groupPosition": {
+            "type": "MessageGroupPosition",
             "required": false
           },
-          "readOnly": {
-            "type": "boolean",
+          "messageId": {
+            "type": "string",
             "required": false
           },
-          "required": {
+          "scrollAnchor": {
             "type": "boolean",
             "required": false
           },
-          "requiredMessage": {
-            "type": "string",
-            "required": false
-          },
-          "size": {
-            "type": "InputSize",
+          "showAuthor": {
+            "type": "boolean",
             "required": false
           },
-          "type": {
-            "type": "InputType",
+          "streaming": {
+            "type": "boolean",
             "required": false
           },
-          "value": {
+          "timestamp": {
             "type": "string",
             "required": false
-          },
-          "width": {
-            "type": "InputWidth",
-            "required": false
           }
         },
-        "events": [
-          {
-            "name": "dsChange",
-            "detail": "string"
-          },
-          {
-            "name": "dsClear",
-            "detail": "void"
-          }
-        ],
+        "events": [],
         "slots": []
       },
       "exports": {
-        "customElement": "ds-input",
-        "react": "DsInput",
-        "angular": "DsInput"
+        "customElement": "ds-message",
+        "react": "DsMessage",
+        "angular": "DsMessage"
       },
       "dependencies": [
         "@ds-mo/ui",
-        "@ds-mo/tokens",
-        "@ds-mo/icons"
+        "@ds-mo/tokens"
       ],
       "componentDependencies": [
-        "button-unfilled",
-        "icon",
         "text"
       ]
     },
     {
-      "id": "component:ds-loader",
-      "tag": "ds-loader",
-      "name": "loader",
-      "title": "Loader",
-      "summary": "Indeterminate progress glyph for ongoing operations, inheriting owner color and optionally exposing standalone polite status text.",
+      "id": "component:ds-message-bubble",
+      "tag": "ds-message-bubble",
+      "name": "message-bubble",
+      "title": "MessageBubble",
+      "summary": "Visible message content surface with a body-medium default, separated from message-row direction and metadata.",
       "intentStatus": "complete",
       "intent": {
         "audience": "general",
-        "status": "stable",
-        "summary": "Indeterminate progress glyph for ongoing operations, inheriting owner color and optionally exposing standalone polite status text.",
+        "status": "experimental",
+        "summary": "Visible message content surface with a body-medium default, separated from message-row direction and metadata.",
         "useWhen": [
-          "An action or operation is in progress and its remaining duration cannot be quantified.",
-          "A button, field, or bounded workflow needs a compact visual busy indicator owned by that control or region.",
-          "A standalone operation needs a visible spinner with contextual polite status text."
+          "Message content needs a primary, secondary, ghost, or error surface within a Message row.",
+          "Plain incoming or outgoing message copy should use the shared body-medium regular typography recipe without application styling."
         ],
         "avoidWhen": [
-          "Pending content has a predictable structure; use Skeleton to preserve that layout.",
-          "Progress is measurable; use an appropriate determinate progress pattern.",
-          "The UI needs a blocking overlay or automatic centering; the owning layout must provide that structure.",
-          "Success, failure, retry, or completion must be communicated; the owning workflow handles outcomes."
-        ],
-        "alternatives": [
-          {
-            "when": "A content region is waiting for structured data.",
-            "component": "component:ds-skeleton",
-            "reason": "Skeleton preserves the expected content geometry while data loads."
-          },
-          {
-            "when": "A static visual symbol is needed without progress semantics.",
-            "component": "component:ds-icon",
-            "reason": "Icon owns non-progress system and flag glyphs."
-          }
+          "The surface is a general card, callout, or form container.",
+          "The application wants to promote ordinary conversation copy to body-large; message typography stays body-medium unless a distinct authored rich-content element owns its own complete type recipe."
         ],
         "commonlyComposedWith": [
-          "component:ds-button-filled",
-          "component:ds-button-unfilled",
-          "component:ds-input",
-          "component:ds-select"
+          "component:ds-message",
+          "component:ds-markdown"
         ],
-        "accessibility": [
-          "When Loader is nested in a busy button, field, or region, keep it unnamed and expose busy state from the owner.",
-          "Standalone Loader requires contextual status text that explains what is loading; do not rely on a generic visual spinner alone.",
-          "Loader is an informative progress graphic and must retain sufficient rendered contrast; tertiary and quaternary are not supported standalone or informative Loader treatments.",
-          "Avoid duplicate announcements from both Loader and its owning busy region.",
-          "Reduced motion stops rotation while keeping the glyph and status semantics visible."
+        "patterns": [
+          "pattern:conversation"
         ],
-        "states": [
-          "Loader communicates indeterminate progress only and does not emit completion or failure events.",
-          "Omitted color inherits currentColor. Explicit semantic aliases and CSS-variable references match Icon when an independent progress color is required.",
-          "Nested Loader inherits a readable color from its owning busy control or region rather than selecting tertiary or quaternary directly.",
-          "The owner decides whether to delay Loader visibility for short operations and removes it when the operation settles.",
-          "The owner reserves space and supplies centering or overlay layout so Loader never causes unexpected layout movement."
+        "accessibility": [
+          "Surface styling does not add semantics; meaningful error or status copy belongs in message content or metadata."
         ],
         "responsiveBehavior": [
-          "The owning component or layout chooses Loader size, placement, and any responsive changes.",
-          "Loader does not infer container size or viewport breakpoints."
+          "The bubble wraps content and allows wide ghost responses to use more transcript width."
         ],
-        "frameworkCaveats": {
-          "customElements": [
-            "Use the label only for standalone status; nested usage should synchronize aria-busy on the owning element."
-          ],
-          "react": [
-            "Derive Loader visibility and the owner's busy state from the same operation state."
-          ],
-          "angular": [
-            "Derive Loader visibility and the owner's busy state from the same operation state."
-          ]
-        },
         "references": [
           {
             "label": "Storybook examples",
-            "path": "src/wc/components/Loader/Loader.stories.ts"
+            "path": "src/wc/components/MessageScroller/MessageScroller.stories.ts"
           }
         ]
       },
       "api": {
         "props": {
-          "color": {
-            "type": "LoaderColor",
-            "required": false
-          },
-          "label": {
-            "type": "string | undefined",
-            "required": false
-          },
-          "size": {
-            "type": "LoaderSize",
+          "variant": {
+            "type": "MessageBubbleVariant",
             "required": false
           }
         },
@@ -2331,9 +3505,9 @@
         "slots": []
       },
       "exports": {
-        "customElement": "ds-loader",
-        "react": "DsLoader",
-        "angular": "DsLoader"
+        "customElement": "ds-message-bubble",
+        "react": "DsMessageBubble",
+        "angular": "DsMessageBubble"
       },
       "dependencies": [
         "@ds-mo/ui",
@@ -2342,174 +3516,193 @@
       "componentDependencies": []
     },
     {
-      "id": "component:ds-menu",
-      "tag": "ds-menu",
-      "name": "menu",
-      "title": "Menu",
-      "summary": "Anchored action menu with flat commands, grouped sections, selected command state, supplemental notification dots, switches, and destructive actions.",
+      "id": "component:ds-message-composer",
+      "tag": "ds-message-composer",
+      "name": "message-composer",
+      "title": "MessageComposer",
+      "summary": "Two-line auto-growing conversation textarea with submit, stop, error, and extensible leading-tool or trailing-action regions.",
       "intentStatus": "complete",
       "intent": {
         "audience": "general",
-        "status": "stable",
-        "summary": "Anchored action menu with flat commands, grouped sections, selected command state, supplemental notification dots, switches, and destructive actions.",
+        "status": "experimental",
+        "summary": "Two-line auto-growing conversation textarea with submit, stop, error, and extensible leading-tool or trailing-action regions.",
         "useWhen": [
-          "A trigger reveals a short contextual list of commands or state-changing actions.",
-          "Actions need grouping, selected state, supplemental notification dots, switch rows, or destructive treatment."
+          "A conversation accepts multi-line text and needs Enter-to-submit with a streaming stop action."
         ],
         "avoidWhen": [
-          "The user is selecting a value for a form field.",
-          "The content requires rich dialog interaction or a multi-step workflow.",
-          "The actions should remain persistently visible."
-        ],
-        "alternatives": [
-          {
-            "when": "The choice is a form value with a label, validation, and submitted value.",
-            "component": "component:ds-select",
-            "reason": "Select provides form-control semantics and value ownership."
-          },
-          {
-            "when": "Several form values may be selected.",
-            "component": "component:ds-select-multi",
-            "reason": "SelectMulti provides multi-select listbox semantics, array value ownership, and count presentation."
-          },
-          {
-            "when": "The interaction needs substantial content, confirmation, or a form.",
-            "component": "component:ds-modal",
-            "reason": "Modal owns focus containment and dialog-level interaction."
-          }
+          "The text is a conventional form field submitted with unrelated fields."
         ],
         "commonlyComposedWith": [
-          "component:ds-button-unfilled",
-          "component:ds-panel-nav",
-          "component:ds-switch",
-          "component:ds-shell-gradient-picker"
+          "component:ds-message-scroller",
+          "component:ds-button-filled",
+          "component:ds-button-unfilled"
+        ],
+        "patterns": [
+          "pattern:conversation"
         ],
         "accessibility": [
-          "Anchor the menu to the control that opens it and return focus to that control when the menu closes.",
-          "Open with visible initial focus only when the trigger was activated from the keyboard.",
-          "Keep disabled items discoverable only when their unavailable state is meaningful.",
-          "Switch rows use menuitemcheckbox semantics on the row; the nested ds-switch is an aria-hidden md presentation indicator.",
-          "A gradient-picker section changes the popup to a non-modal dialog so its radio group and ordinary preference buttons keep valid nested semantics; Tab moves between its controls, then leaves and closes at the popup boundary.",
-          "Use notification dots only as supplemental status and not as the sole indication of important information."
+          "Always provide a localized textarea label and submit or stop action names.",
+          "Shift plus Enter inserts a newline while Enter submits non-empty content.",
+          "Streaming and error states remain perceivable without relying on icon shape alone."
         ],
         "states": [
-          "The host owns open state and responds to selection and close events.",
-          "Use either flat items or sections, not both.",
-          "After dsSelect from a switch row, update switchValue in the items property so the controlled indicator reflects the new state.",
-          "Arrays, objects, and element anchors must be assigned as JavaScript properties.",
-          "Use one gradient-picker section in the user or account Appearance or Theme popup for the global AppShell wash preference; apply dsGradientSelect immediately without closing the popup."
+          "The owner controls draft value and transport state; the composer emits intent without performing transport.",
+          "Use the tools slot for leading actions such as add and the actions slot for trailing actions such as dictation; the built-in submit or stop action remains last.",
+          "The submit action defaults to brand for both agent and person-to-person conversations; change submitIntent only when the action consequence has a different semantic intent."
         ],
         "responsiveBehavior": [
-          "Choose placement relative to the trigger and allow the component to clamp the popup to the viewport.",
-          "Avoid fixed widths that exceed narrow viewports."
+          "The textarea begins at two body-medium lines, grows one line at a time through six lines, and then scrolls internally."
         ],
-        "frameworkCaveats": {
-          "customElements": [
-            "Assign items, sections, and HTMLElement anchors as properties after the element is defined."
-          ],
-          "react": [
-            "Pass arrays and objects as wrapper props and handle generated onDsSelect and onDsClose event props."
-          ],
-          "angular": [
-            "Use property bindings for arrays, objects, and anchors and event bindings for dsSelect and dsClose."
-          ]
-        },
         "references": [
           {
             "label": "Storybook examples",
-            "path": "src/wc/components/Menu/Menu.stories.ts"
+            "path": "src/wc/components/MessageComposer/MessageComposer.stories.ts"
           },
           {
-            "label": "Framework integration",
-            "path": "docs/framework-integration.md"
+            "label": "Scroller overlay composition",
+            "path": "src/wc/components/MessageScroller/MessageScroller.stories.ts"
           }
         ]
       },
       "api": {
         "props": {
-          "align": {
-            "type": "MenuAlign",
-            "required": false
-          },
-          "alignOffset": {
-            "type": "number | string",
+          "isInactive": {
+            "type": "boolean",
             "required": false
           },
-          "anchor": {
-            "type": "HTMLElement | undefined",
+          "label": {
+            "type": "string",
             "required": false
           },
-          "anchorId": {
-            "type": "string | undefined",
+          "placeholder": {
+            "type": "string",
             "required": false
           },
-          "initialFocusVisible": {
-            "type": "boolean",
+          "status": {
+            "type": "MessageComposerStatus",
             "required": false
           },
-          "items": {
-            "type": "MenuItemData[]",
+          "submitIntent": {
+            "type": "ButtonFilledIntent",
             "required": false
           },
-          "menuLabel": {
+          "value": {
             "type": "string",
             "required": false
+          }
+        },
+        "events": [
+          {
+            "name": "dsInput",
+            "detail": "string"
           },
-          "menuWidth": {
-            "type": "string | undefined",
-            "required": false
-          },
-          "minWidth": {
-            "type": "string | undefined",
-            "required": false
+          {
+            "name": "dsStop",
+            "detail": "void"
           },
-          "open": {
+          {
+            "name": "dsSubmit",
+            "detail": "{ text: string }"
+          }
+        ],
+        "slots": []
+      },
+      "exports": {
+        "customElement": "ds-message-composer",
+        "react": "DsMessageComposer",
+        "angular": "DsMessageComposer"
+      },
+      "dependencies": [
+        "@ds-mo/ui",
+        "@ds-mo/tokens"
+      ],
+      "componentDependencies": [
+        "button-filled"
+      ]
+    },
+    {
+      "id": "component:ds-message-scroller",
+      "tag": "ds-message-scroller",
+      "name": "message-scroller",
+      "title": "MessageScroller",
+      "summary": "Focusable transcript scroller that follows the live edge only while the reader remains there.",
+      "intentStatus": "complete",
+      "intent": {
+        "audience": "general",
+        "status": "experimental",
+        "summary": "Focusable transcript scroller that follows the live edge only while the reader remains there.",
+        "useWhen": [
+          "Messages can append or stream and transcript position must remain respectful of reader intent."
+        ],
+        "avoidWhen": [
+          "Content is static prose without message navigation or live updates."
+        ],
+        "commonlyComposedWith": [
+          "component:ds-message",
+          "component:ds-message-composer"
+        ],
+        "patterns": [
+          "pattern:conversation"
+        ],
+        "accessibility": [
+          "Give each transcript a concise localized label.",
+          "New content is exposed through log semantics without stealing focus.",
+          "The scroll-to-latest control remains keyboard accessible when follow behavior is released."
+        ],
+        "states": [
+          "Selection and transcript interaction release automatic following.",
+          "Opening saved history, message jumps, and prepended history preserve deliberate position.",
+          "The scroll-to-latest action is absent at the live edge, appears only after the reader moves away, and disappears again after returning to the newest message.",
+          "Place a composer container in the overlay slot so messages scroll behind it; the scroller measures its live height, reserves matching transcript clearance, and keeps scroll-to-latest above it."
+        ],
+        "responsiveBehavior": [
+          "Transcript width is readable while the scroll region fills available height."
+        ],
+        "references": [
+          {
+            "label": "Storybook examples",
+            "path": "src/wc/components/MessageScroller/MessageScroller.stories.ts"
+          }
+        ]
+      },
+      "api": {
+        "props": {
+          "autoFollow": {
             "type": "boolean",
             "required": false
           },
-          "sections": {
-            "type": "MenuSection[]",
+          "busy": {
+            "type": "boolean",
             "required": false
           },
-          "side": {
-            "type": "MenuSide",
+          "defaultPosition": {
+            "type": "MessageScrollerPosition",
             "required": false
           },
-          "sideOffset": {
-            "type": "number | string",
+          "messagesLabel": {
+            "type": "string",
             "required": false
           }
         },
         "events": [
           {
-            "name": "dsClose",
+            "name": "dsReachStart",
             "detail": "void"
-          },
-          {
-            "name": "dsGradientSelect",
-            "detail": "ShellGradientPreset"
-          },
-          {
-            "name": "dsSelect",
-            "detail": "MenuItemData"
           }
         ],
         "slots": []
       },
       "exports": {
-        "customElement": "ds-menu",
-        "react": "DsMenu",
-        "angular": "DsMenu"
+        "customElement": "ds-message-scroller",
+        "react": "DsMessageScroller",
+        "angular": "DsMessageScroller"
       },
       "dependencies": [
         "@ds-mo/ui",
         "@ds-mo/tokens"
       ],
       "componentDependencies": [
-        "badge",
-        "shell-gradient-picker",
-        "switch",
-        "text"
+        "button-unfilled"
       ]
     },
     {
@@ -2723,170 +3916,416 @@
             "type": "PanelNavRouterMode",
             "required": false
           },
-          "settingsLabel": {
+          "settingsLabel": {
+            "type": "string",
+            "required": false
+          },
+          "settingsNavigationLabel": {
+            "type": "string",
+            "required": false
+          },
+          "storageKey": {
+            "type": "string",
+            "required": false
+          },
+          "userInitial": {
+            "type": "string",
+            "required": false
+          },
+          "userName": {
+            "type": "string",
+            "required": false
+          }
+        },
+        "events": [
+          {
+            "name": "dsChromeTransitionEnd",
+            "detail": "ChromeTransitionDetail"
+          },
+          {
+            "name": "dsChromeTransitionStart",
+            "detail": "ChromeTransitionDetail"
+          },
+          {
+            "name": "dsNavFooterAction",
+            "detail": "void"
+          },
+          {
+            "name": "dsNavSelect",
+            "detail": "string"
+          },
+          {
+            "name": "dsNavToggle",
+            "detail": "boolean"
+          },
+          {
+            "name": "dsNavUserAction",
+            "detail": "PanelNavUserActionDetail"
+          }
+        ],
+        "slots": []
+      },
+      "exports": {
+        "customElement": "ds-panel-nav",
+        "react": "DsPanelNav",
+        "angular": "DsPanelNav"
+      },
+      "dependencies": [
+        "@ds-mo/ui",
+        "@ds-mo/tokens",
+        "@ds-mo/icons"
+      ],
+      "componentDependencies": [
+        "badge",
+        "button-unfilled",
+        "icon",
+        "text",
+        "tooltip"
+      ]
+    },
+    {
+      "id": "component:ds-panel-sub-nav",
+      "tag": "ds-panel-sub-nav",
+      "name": "panel-sub-nav",
+      "title": "PanelSubNav",
+      "summary": "Persistent vertical tab navigation for a panel or card side rail, switching adjacent local content with menu-like selected fill and stable text weight.",
+      "intentStatus": "complete",
+      "intent": {
+        "audience": "general",
+        "status": "stable",
+        "summary": "Persistent vertical tab navigation for a panel or card side rail, switching adjacent local content with menu-like selected fill and stable text weight.",
+        "useWhen": [
+          "A panel or card side rail needs a persistent vertical list that switches adjacent local content.",
+          "Each concise text label controls an immediately available tabpanel without changing application routes."
+        ],
+        "avoidWhen": [
+          "The navigation is not contained in a panel or card side rail.",
+          "Local views should be arranged horizontally; use TabGroup instead.",
+          "The choices navigate routes in application shell chrome; use PanelNav or BarNav instead.",
+          "The choices are temporary commands or contextual options; use Menu instead.",
+          "Rows need icons, subtext, notification dots, nested levels, or section headers."
+        ],
+        "alternatives": [
+          {
+            "when": "Local panel choices fit a horizontal tab row.",
+            "component": "component:ds-tab-group",
+            "reason": "TabGroup is the horizontal local-view counterpart."
+          },
+          {
+            "when": "The choices are primary application destinations.",
+            "component": "component:ds-panel-nav",
+            "reason": "PanelNav owns primary application navigation."
+          },
+          {
+            "when": "The choices are secondary application routes.",
+            "component": "component:ds-bar-nav",
+            "reason": "BarNav owns route sections inside AppShell."
+          },
+          {
+            "when": "The choices are transient actions or options.",
+            "component": "component:ds-menu",
+            "reason": "Menu owns temporary popup collections."
+          }
+        ],
+        "commonlyComposedWith": [
+          "component:ds-card",
+          "component:ds-text"
+        ],
+        "accessibility": [
+          "Provide an accessible name with aria-label or aria-labelledby.",
+          "Give every item a unique id and the id of its controlled tabpanel.",
+          "Keep each controlled tabpanel labelled by its matching item id.",
+          "Always provide a valid selected item when enabled items exist so exactly one tab and panel are active.",
+          "ArrowUp and ArrowDown move and activate selection; Home and End select the first and last available items.",
+          "Do not use selected text weight as the selection cue; active fill and primary foreground communicate selection."
+        ],
+        "states": [
+          "The parent owns the canonical selected value and panel visibility, and should update both from dsChange.",
+          "A missing, empty, or unknown selected value is invalid when enabled items exist; the component does not choose a fallback selection.",
+          "Inactive items remain visible but cannot be focused or selected.",
+          "Selection is singular and follows keyboard focus.",
+          "The omitted default surface treatment is for primary and secondary parent surfaces and uses the brand-active selected fill; pass faint explicitly on faint surfaces to use the neutral active fill.",
+          "Rows contain one text label only and do not express nested navigation or grouped hierarchy."
+        ],
+        "responsiveBehavior": [
+          "The component remains vertical at every width.",
+          "The consuming panel owns responsive adaptation and decides whether to reposition or replace the side rail."
+        ],
+        "frameworkCaveats": {
+          "customElements": [
+            "Assign items as a JavaScript property because structured arrays are not represented by HTML attributes.",
+            "Keep value synchronized to a valid enabled item and update the controlled panel from dsChange."
+          ],
+          "react": [
+            "Pass items as an array through the generated wrapper, keep value controlled, and use onDsChange to synchronize the visible panel."
+          ],
+          "angular": [
+            "Bind items and a valid value as properties, and handle dsChange to synchronize the visible panel."
+          ]
+        }
+      },
+      "api": {
+        "props": {
+          "ariaLabel": {
+            "type": "string | null",
+            "required": false
+          },
+          "ariaLabelledby": {
+            "type": "string | undefined",
+            "required": false
+          },
+          "background": {
+            "type": "PanelSubNavBackground | undefined",
+            "required": false
+          },
+          "items": {
+            "type": "PanelSubNavItem[]",
+            "required": false
+          },
+          "value": {
+            "type": "string",
+            "required": false
+          }
+        },
+        "events": [
+          {
+            "name": "dsChange",
+            "detail": "string"
+          }
+        ],
+        "slots": []
+      },
+      "exports": {
+        "customElement": "ds-panel-sub-nav",
+        "react": "DsPanelSubNav",
+        "angular": "DsPanelSubNav"
+      },
+      "dependencies": [
+        "@ds-mo/ui",
+        "@ds-mo/tokens"
+      ],
+      "componentDependencies": [
+        "text"
+      ]
+    },
+    {
+      "id": "component:ds-panel-tool-header",
+      "tag": "ds-panel-tool-header",
+      "name": "panel-tool-header",
+      "title": "PanelToolHeader",
+      "summary": "Canonical left-aligned PanelTools header with an optional leading navigation or dismiss action and application-owned trailing icon actions.",
+      "intentStatus": "complete",
+      "intent": {
+        "audience": "general",
+        "status": "experimental",
+        "summary": "Canonical left-aligned PanelTools header with an optional leading navigation or dismiss action and application-owned trailing icon actions.",
+        "useWhen": [
+          "PanelTools needs its one shared root or detail header.",
+          "A tool header needs a title with optional Back or Close navigation, menu, fullscreen, or other compact icon actions."
+        ],
+        "avoidWhen": [
+          "Rendering inside a PanelTools tool body; PanelTools already composes this canonical header above the body.",
+          "The header belongs to page content."
+        ],
+        "commonlyComposedWith": [
+          "component:ds-button-unfilled"
+        ],
+        "accessibility": [
+          "Leading navigation or dismiss actions and trailing icon actions require concise localized names.",
+          "The visible heading names the active panel or subview."
+        ],
+        "states": [
+          "The title remains left aligned whether the header has no actions, Back, one trailing action, or several trailing actions.",
+          "Leading and trailing control zones never shrink; only the title consumes and truncates within the remaining width, with a fixed 4px gap between zones.",
+          "Header chrome text is not selectable; actions remain keyboard focusable and interactive.",
+          "Adjacent trailing actions keep the shared 4px control gap in drawer and fullscreen presentations.",
+          "When fullscreen and overflow actions appear together, author fullscreen before overflow so Ellipses remains the rightmost action.",
+          "PanelTools supplies application-owned actions and relays their ids through its shared dsHeaderAction event."
+        ],
+        "responsiveBehavior": [
+          "The title truncates between optional leading navigation and trailing action zones."
+        ],
+        "references": [
+          {
+            "label": "Standalone examples",
+            "path": "src/wc/components/PanelToolHeader/PanelToolHeader.stories.ts"
+          }
+        ]
+      },
+      "api": {
+        "props": {
+          "actions": {
+            "type": "PanelToolsHeaderAction[]",
+            "required": false
+          },
+          "backAriaLabel": {
+            "type": "string",
+            "required": false
+          },
+          "backIcon": {
+            "type": "string",
+            "required": false
+          },
+          "heading": {
+            "type": "string",
+            "required": false
+          },
+          "menuAriaLabel": {
             "type": "string",
             "required": false
           },
-          "settingsNavigationLabel": {
-            "type": "string",
+          "menuControls": {
+            "type": "string | undefined",
             "required": false
           },
-          "storageKey": {
-            "type": "string",
+          "menuExpanded": {
+            "type": "boolean",
             "required": false
           },
-          "userInitial": {
+          "menuTriggerId": {
             "type": "string",
             "required": false
           },
-          "userName": {
-            "type": "string",
+          "showBack": {
+            "type": "boolean",
+            "required": false
+          },
+          "showMenu": {
+            "type": "boolean",
             "required": false
           }
         },
         "events": [
           {
-            "name": "dsChromeTransitionEnd",
-            "detail": "ChromeTransitionDetail"
-          },
-          {
-            "name": "dsChromeTransitionStart",
-            "detail": "ChromeTransitionDetail"
-          },
-          {
-            "name": "dsNavFooterAction",
-            "detail": "void"
-          },
-          {
-            "name": "dsNavSelect",
-            "detail": "string"
+            "name": "dsAction",
+            "detail": "{ id: string; originalEvent: MouseEvent }"
           },
           {
-            "name": "dsNavToggle",
-            "detail": "boolean"
+            "name": "dsBack",
+            "detail": "MouseEvent"
           },
           {
-            "name": "dsNavUserAction",
-            "detail": "PanelNavUserActionDetail"
+            "name": "dsMenuToggle",
+            "detail": "MouseEvent"
           }
         ],
         "slots": []
       },
       "exports": {
-        "customElement": "ds-panel-nav",
-        "react": "DsPanelNav",
-        "angular": "DsPanelNav"
+        "customElement": "ds-panel-tool-header",
+        "react": "DsPanelToolHeader",
+        "angular": "DsPanelToolHeader"
       },
       "dependencies": [
         "@ds-mo/ui",
-        "@ds-mo/tokens",
-        "@ds-mo/icons"
+        "@ds-mo/tokens"
       ],
       "componentDependencies": [
-        "badge",
         "button-unfilled",
-        "icon",
-        "text",
-        "tooltip"
+        "text"
       ]
     },
     {
-      "id": "component:ds-panel-sub-nav",
-      "tag": "ds-panel-sub-nav",
-      "name": "panel-sub-nav",
-      "title": "PanelSubNav",
-      "summary": "Persistent vertical tab navigation for a panel or card side rail, switching adjacent local content with menu-like selected fill and stable text weight.",
+      "id": "component:ds-panel-tool-search",
+      "tag": "ds-panel-tool-search",
+      "name": "panel-tool-search",
+      "title": "PanelToolSearch",
+      "summary": "Transparent search row for the top of a PanelTools product view, with a fixed 48px allocation around the standard md search control and an optional filter-menu trigger.",
       "intentStatus": "complete",
       "intent": {
         "audience": "general",
-        "status": "stable",
-        "summary": "Persistent vertical tab navigation for a panel or card side rail, switching adjacent local content with menu-like selected fill and stable text weight.",
+        "status": "experimental",
+        "summary": "Transparent search row for the top of a PanelTools product view, with a fixed 48px allocation around the standard md search control and an optional filter-menu trigger.",
         "useWhen": [
-          "A panel or card side rail needs a persistent vertical list that switches adjacent local content.",
-          "Each concise text label controls an immediately available tabpanel without changing application routes."
+          "A PanelTools base view filters or searches the tool's own content.",
+          "Several tool products need the same search-row geometry directly below the shared PanelTools header.",
+          "The product needs a compact filter menu next to search while keeping its filter choices and matching policy application-owned."
         ],
         "avoidWhen": [
-          "The navigation is not contained in a panel or card side rail.",
-          "Local views should be arranged horizontally; use TabGroup instead.",
-          "The choices navigate routes in application shell chrome; use PanelNav or BarNav instead.",
-          "The choices are temporary commands or contextual options; use Menu instead.",
-          "Rows need icons, subtext, notification dots, nested levels, or section headers."
-        ],
-        "alternatives": [
-          {
-            "when": "Local panel choices fit a horizontal tab row.",
-            "component": "component:ds-tab-group",
-            "reason": "TabGroup is the horizontal local-view counterpart."
-          },
-          {
-            "when": "The choices are primary application destinations.",
-            "component": "component:ds-panel-nav",
-            "reason": "PanelNav owns primary application navigation."
-          },
-          {
-            "when": "The choices are secondary application routes.",
-            "component": "component:ds-bar-nav",
-            "reason": "BarNav owns route sections inside AppShell."
-          },
-          {
-            "when": "The choices are transient actions or options.",
-            "component": "component:ds-menu",
-            "reason": "Menu owns temporary popup collections."
-          }
+          "The search belongs inside a Select or SelectMulti popup; use that component's searchable behavior.",
+          "A form needs a labelled standalone field; compose ds-input inside ds-field instead."
         ],
         "commonlyComposedWith": [
-          "component:ds-card",
-          "component:ds-text"
+          "component:ds-panel-tools",
+          "component:ds-conversation-list",
+          "component:ds-input"
         ],
         "accessibility": [
-          "Provide an accessible name with aria-label or aria-labelledby.",
-          "Give every item a unique id and the id of its controlled tabpanel.",
-          "Keep each controlled tabpanel labelled by its matching item id.",
-          "Always provide a valid selected item when enabled items exist so exactly one tab and panel are active.",
-          "ArrowUp and ArrowDown move and activate selection; Home and End select the first and last available items.",
-          "Do not use selected text weight as the selection cue; active fill and primary foreground communicate selection."
+          "Provide an aria-label that names the searched domain, such as Search agent chats or Search messages.",
+          "The standard search clear action restores focus and emits both the empty query and dsClear.",
+          "When showFilter is enabled, provide stable filterTriggerId and filterControls values, synchronize filterExpanded with the controlled menu, and restore focus after selection."
         ],
         "states": [
-          "The parent owns the canonical selected value and panel visibility, and should update both from dsChange.",
-          "A missing, empty, or unknown selected value is invalid when enabled items exist; the component does not choose a fallback selection.",
-          "Inactive items remain visible but cannot be focused or selected.",
-          "Selection is singular and follows keyboard focus.",
-          "The omitted default surface treatment is for primary and secondary parent surfaces and uses the brand-active selected fill; pass faint explicitly on faint surfaces to use the neutral active fill.",
-          "Rows contain one text label only and do not express nested navigation or grouped hierarchy."
+          "The row is always 48px high with 8px outer padding and a complete md search recipe: 32px control, text-body-medium at 14px/20px, and a 20px md search icon.",
+          "The search icon stays foreground-secondary at rest, hover, focus, active, and while the query is filled.",
+          "The row and control surface remain transparent so the AppShell chrome wash is visible behind them.",
+          "The row divider remains the same tertiary 1px boundary while the input is focused because it belongs to the 48px container rather than the input control.",
+          "With filtering enabled, the md search control, decorative vertical divider, and borderless md Filter action are separated by 8px; filterActive promotes only the trigger foreground without adding a selected fill."
         ],
         "responsiveBehavior": [
-          "The component remains vertical at every width.",
-          "The consuming panel owns responsive adaptation and decides whether to reposition or replace the side rail."
+          "The row fills the available drawer or fullscreen width, allows its search region to shrink inside a 300px drawer without pushing the filter trigger under the tool rail, and does not reduce its control below md density."
         ],
         "frameworkCaveats": {
           "customElements": [
-            "Assign items as a JavaScript property because structured arrays are not represented by HTML attributes.",
-            "Keep value synchronized to a valid enabled item and update the controlled panel from dsChange."
+            "Listen for dsChange to receive the current string query and dsClear when the clear action is used.",
+            "Listen for dsFilterToggle and pair the trigger with an externally controlled ds-menu; product-specific filter labels and filtering remain outside this component."
           ],
           "react": [
-            "Pass items as an array through the generated wrapper, keep value controlled, and use onDsChange to synchronize the visible panel."
+            "Use DsPanelToolSearch, bind value for controlled state, and handle onDsChange.",
+            "Bind the optional filter trigger state and connect onDsFilterToggle to a controlled DsMenu."
           ],
           "angular": [
-            "Bind items and a valid value as properties, and handle dsChange to synchronize the visible panel."
+            "Import DsPanelToolSearch and bind value as a property; this search composition is not a form value accessor.",
+            "Bind showFilter, filterExpanded, and filterActive, then connect dsFilterToggle to a product-owned ds-menu."
           ]
-        }
+        },
+        "references": [
+          {
+            "label": "Storybook examples",
+            "path": "src/wc/components/PanelToolSearch/PanelToolSearch.stories.ts"
+          }
+        ]
       },
       "api": {
         "props": {
           "ariaLabel": {
-            "type": "string | null",
+            "type": "string",
             "required": false
           },
-          "ariaLabelledby": {
+          "controls": {
             "type": "string | undefined",
             "required": false
           },
-          "background": {
-            "type": "PanelSubNavBackground | undefined",
+          "filterActive": {
+            "type": "boolean",
             "required": false
           },
-          "items": {
-            "type": "PanelSubNavItem[]",
+          "filterAriaLabel": {
+            "type": "string",
+            "required": false
+          },
+          "filterControls": {
+            "type": "string | undefined",
+            "required": false
+          },
+          "filterExpanded": {
+            "type": "boolean",
+            "required": false
+          },
+          "filterTriggerId": {
+            "type": "string",
+            "required": false
+          },
+          "isInactive": {
+            "type": "boolean",
+            "required": false
+          },
+          "placeholder": {
+            "type": "string",
+            "required": false
+          },
+          "showFilter": {
+            "type": "boolean",
             "required": false
           },
           "value": {
@@ -2898,20 +4337,32 @@
           {
             "name": "dsChange",
             "detail": "string"
+          },
+          {
+            "name": "dsClear",
+            "detail": "void"
+          },
+          {
+            "name": "dsFilterToggle",
+            "detail": "MouseEvent"
           }
         ],
         "slots": []
       },
       "exports": {
-        "customElement": "ds-panel-sub-nav",
-        "react": "DsPanelSubNav",
-        "angular": "DsPanelSubNav"
+        "customElement": "ds-panel-tool-search",
+        "react": "DsPanelToolSearch",
+        "angular": "DsPanelToolSearch"
       },
       "dependencies": [
         "@ds-mo/ui",
-        "@ds-mo/tokens"
+        "@ds-mo/tokens",
+        "@ds-mo/icons"
       ],
       "componentDependencies": [
+        "button-unfilled",
+        "divider",
+        "icon",
         "text"
       ]
     },
@@ -2979,21 +4430,32 @@
           "The drawer starts closed, remains open across ordinary route changes, and retains every mounted tool's independent conversation, query, scroll, and work state.",
           "When storageKey is set, persist only the last active tool in this browser and still restore the drawer closed after reload.",
           "The application owns unread state; opening Messages, Agents, Stacks, or Activity does not automatically clear its notification dot.",
+          "PanelTools owns the one visible header above every drawer tool view and above fullscreen views using the default shared header mode. Slotted tool content must not render a second header unless the conversation product explicitly opts into split fullscreen headers.",
+          "PanelTools composes ds-panel-tool-header as its canonical left-aligned header implementation so standalone header stories and shell rendering cannot diverge.",
+          "Each tool supplies its current header title, base-versus-detail Back state, and right-side actions through the headers property. Base views omit Back; deeper views expose Back and update the same header in place.",
+          "Header Back and action events express intent only; the owning tool changes product navigation, menus, and data state. PanelTools keeps the final header action exactly 8px from the drawer edge.",
+          "Menus opened from a right-side header action use PANEL_TOOLS_HEADER_MENU_PLACEMENT: bottom/end choice-cell alignment and a 12px side offset, placing the popup 4px below the 48px header while aligning the final menu item edge with the trigger.",
+          "Tool view roots stay transparent so AppShell's chrome wash remains visible; only explicitly designed child surfaces introduce a fill.",
+          "Tools with search compose ds-panel-tool-search immediately below the shared header. Its 48px row always contains the md search control and must not be reduced to sm or xs.",
           "If an active optional tool becomes unavailable, PanelTools closes the drawer, clears activeTool, and emits its deselection.",
           "Use isInactive only for a temporarily unavailable visible tool; omit tools the user is not authorized to access.",
-          "The application owns slotted tool products and data while PanelTools owns rail ordering, drawer selection, open state, motion, and shell events."
+          "The application owns slotted tool products and data while PanelTools owns rail ordering, drawer selection, open state, motion, and shell events.",
+          "Opening and closing clip an already-rendered fixed-width surface. Header and tool content remain fully opaque and retained during width motion; transition completion is accepted only at the measured terminal clip width, after which the closed surface becomes inert and paint-skipped.",
+          "Entering and exiting fullscreen snaps without borrowing the drawer open or close animation.",
+          "When fullscreenHeaderMode is split, PanelTools suppresses only its fullscreen shared header. The application renders exactly two canonical ds-panel-tool-header instances: a tool-title/list-actions header over the 300px history pane and a chat-title/Exit-fullscreen/chat-actions header over the detail pane. The detail header omits Back because the list remains visible."
         ],
         "responsiveBehavior": [
-          "On desktop at 1200px and wider, the open drawer reduces main-content width and uses --dimension-panel-width-sm (400px).",
-          "On tablet from 768px through 1199px, the open drawer also reduces main-content width and uses --dimension-panel-width-xs (300px).",
-          "AppShell owns the responsive drawer-width variable and fixed breakpoint policy; consumers must not hardcode alternate drawer widths.",
+          "The open drawer reduces main-content width and uses --dimension-panel-width-xs (300px) on every supported desktop and tablet viewport.",
+          "AppShell owns the fixed drawer-width variable; consumers must not hardcode alternate drawer widths.",
           "Below 768px, do not reuse desktop PanelTools: future AppShell mobile composition uses a bottom bar for Search, Agents, Notifications, and Stacks, while Help moves into mobile primary navigation.",
           "Keep named-slot content mounted while tools switch or the drawer closes so users can return to in-progress global work.",
+          "Conversation products may use fullscreenHeaderMode split for a 300px history rail beside a flexible detail pane, each with its own canonical header; the application owns that internal split layout.",
           "Use fixed drawer widths for now; do not add user resizing or width persistence."
         ],
         "frameworkCaveats": {
           "customElements": [
             "Assign items as a JavaScript property for structured data; items-json is the string fallback.",
+            "Assign headers as a JavaScript property and replace its object identity whenever an active tool changes title, depth, or actions.",
             "Keep PanelTools mounted at AppShell scope across route changes and provide each product through its matching named slot."
           ],
           "react": [
@@ -3002,6 +4464,7 @@
           ],
           "angular": [
             "Import DsPanelTools from @ds-mo/ui/angular/ds-panel-tools and bind items as a property.",
+            "Bind headers as a replaced object and route dsHeaderBack and dsHeaderAction to the active tool owner.",
             "Keep the component in the persistent shell layout rather than recreating it in routed page components."
           ]
         },
@@ -3026,6 +4489,18 @@
             "type": "PanelToolsToolId | ''",
             "required": false
           },
+          "fullscreenHeaderMode": {
+            "type": "'shared' | 'split'",
+            "required": false
+          },
+          "headers": {
+            "type": "PanelToolsHeaders",
+            "required": false
+          },
+          "headersJson": {
+            "type": "string",
+            "required": false
+          },
           "items": {
             "type": "PanelToolsItem[]",
             "required": false
@@ -3038,6 +4513,10 @@
             "type": "boolean",
             "required": false
           },
+          "presentation": {
+            "type": "'drawer' | 'fullscreen'",
+            "required": false
+          },
           "storageKey": {
             "type": "string",
             "required": false
@@ -3060,6 +4539,18 @@
             "name": "dsChromeTransitionStart",
             "detail": "ChromeTransitionDetail"
           },
+          {
+            "name": "dsHeaderAction",
+            "detail": "{\n    tool: PanelToolsToolId;\n    id: string;\n  }"
+          },
+          {
+            "name": "dsHeaderBack",
+            "detail": "{\n    tool: PanelToolsToolId;\n  }"
+          },
+          {
+            "name": "dsPresentationChange",
+            "detail": "{\n    presentation: 'drawer' | 'fullscreen';\n  }"
+          },
           {
             "name": "dsToolChange",
             "detail": "{\n    id: PanelToolsToolId;\n    selected: boolean;\n  }"
@@ -3078,7 +4569,7 @@
       ],
       "componentDependencies": [
         "button-unfilled",
-        "text",
+        "panel-tool-header",
         "tooltip"
       ]
     },
@@ -3757,12 +5248,14 @@
       "tag": "ds-shell-gradient-picker",
       "name": "shell-gradient-picker",
       "title": "ShellGradientPicker",
-      "summary": "The canonical compact control for selecting the single global AppShell chrome wash preference from fixed token-based presets.",
+      "summary": "Deprecated compatibility wrapper that maps the fixed AppShell wash presets into SwatchPicker.",
       "intentStatus": "complete",
       "intent": {
         "audience": "specialized",
-        "status": "stable",
-        "summary": "The canonical compact control for selecting the single global AppShell chrome wash preference from fixed token-based presets.",
+        "status": "deprecated",
+        "replacedBy": "component:ds-swatch-picker",
+        "replacementReason": "SwatchPicker now owns the same accessible interaction with a generic option model that supports both flat colors and gradients.",
+        "summary": "Deprecated compatibility wrapper that maps the fixed AppShell wash presets into SwatchPicker.",
         "useWhen": [
           "Adding the Appearance or Theme section to the application's user or account menu.",
           "Users must choose the global AppShell chrome treatment from none, cool, neutral, warm, or fresh."
@@ -3816,8 +5309,8 @@
         },
         "references": [
           {
-            "label": "Executable stories",
-            "path": "src/wc/components/ShellGradientPicker/ShellGradientPicker.stories.ts"
+            "label": "Replacement stories",
+            "path": "src/wc/components/SwatchPicker/SwatchPicker.stories.ts"
           },
           {
             "label": "AppShell gradient contract",
@@ -3858,7 +5351,7 @@
         "@ds-mo/tokens"
       ],
       "componentDependencies": [
-        "shell-gradient-swatch"
+        "swatch-picker"
       ]
     },
     {
@@ -3866,12 +5359,14 @@
       "tag": "ds-shell-gradient-swatch",
       "name": "shell-gradient-swatch",
       "title": "ShellGradientSwatch",
-      "summary": "Internal radio swatch used by ShellGradientPicker to preview one fixed AppShell chrome preset.",
+      "summary": "Deprecated internal compatibility component for one legacy AppShell gradient swatch.",
       "intentStatus": "complete",
       "intent": {
         "audience": "internal",
-        "status": "stable",
-        "summary": "Internal radio swatch used by ShellGradientPicker to preview one fixed AppShell chrome preset.",
+        "status": "deprecated",
+        "replacedBy": "component:ds-swatch-picker",
+        "replacementReason": "SwatchPicker renders its option buttons internally so an individually published radio swatch is no longer needed.",
+        "summary": "Deprecated internal compatibility component for one legacy AppShell gradient swatch.",
         "useWhen": [
           "Maintaining or extending ShellGradientPicker inside CompoMo."
         ],
@@ -3883,12 +5378,12 @@
         "alternatives": [
           {
             "when": "An application needs the supported global shell appearance control.",
-            "component": "component:ds-shell-gradient-picker",
-            "reason": "The picker provides the complete preset set, radio semantics, keyboard behavior, and selection event."
+            "component": "component:ds-swatch-picker",
+            "reason": "SwatchPicker provides the complete radio-group semantics, keyboard behavior, generic previews, and selection event."
           }
         ],
         "commonlyComposedWith": [
-          "component:ds-shell-gradient-picker"
+          "component:ds-swatch-picker"
         ],
         "accessibility": [
           "Keep radio semantics, aria-checked state, and a preset-specific accessible name on the internal button.",
@@ -4146,6 +5641,7 @@
           "Focused, filled, dirty, touched, dragging, valid, disabled, read-only, and orientation data hooks expose interaction state without changing the value contract."
         ],
         "responsiveBehavior": [
+          "The visible label uses the same primary emphasized text-body-small recipe as Field at every density; the value uses the same primary metric without emphasis.",
           "Horizontal Slider fills the width supplied by its parent; the parent chooses an appropriate readable track length.",
           "Vertical Slider owns a token-based default length that may be overridden with --ds-slider-vertical-length in layout-specific compositions.",
           "Use md in ordinary forms and sm or xs only when the surrounding control density uses the same recipe.",
@@ -4315,6 +5811,121 @@
         "text"
       ]
     },
+    {
+      "id": "component:ds-swatch-picker",
+      "tag": "ds-swatch-picker",
+      "name": "swatch-picker",
+      "title": "SwatchPicker",
+      "summary": "Compact one-of-many picker for curated flat-color, gradient, or visually absent presets with optional section separators and roving radio-group interaction.",
+      "intentStatus": "complete",
+      "intent": {
+        "audience": "general",
+        "status": "stable",
+        "summary": "Compact one-of-many picker for curated flat-color, gradient, or visually absent presets with optional section separators and roving radio-group interaction.",
+        "useWhen": [
+          "Users choose exactly one visual preset from a small curated set.",
+          "Options are best compared through compact flat-color or gradient previews.",
+          "A settings surface or richer menu needs an immediately applied visual preference."
+        ],
+        "avoidWhen": [
+          "Users need an unrestricted spectrum, numeric channels, opacity editing, or custom CSS gradient construction.",
+          "Text labels are the primary distinction between choices; use Radio instead.",
+          "The choice is a submitted form value with validation or a long compact list; use Radio or Select.",
+          "Color or gradient is the only indication of status, meaning, or required action."
+        ],
+        "alternatives": [
+          {
+            "when": "The user needs an arbitrary color rather than a curated preset.",
+            "component": "component:ds-input",
+            "reason": "SwatchPicker intentionally does not provide spectrum, channel, or free-form value editing."
+          },
+          {
+            "when": "Visible text labels are more important than visual previews.",
+            "component": "component:ds-radio",
+            "reason": "Radio presents explicit one-of-many option labels and native form behavior."
+          },
+          {
+            "when": "The option set is long or must remain compact.",
+            "component": "component:ds-select",
+            "reason": "Select scales a larger named choice set into an anchored listbox."
+          }
+        ],
+        "commonlyComposedWith": [
+          "component:ds-menu",
+          "component:ds-app-shell"
+        ],
+        "accessibility": [
+          "Provide a localized groupLabel describing the complete choice.",
+          "Give every option a meaningful label because its visual preview is never its accessible name.",
+          "The options form one radio group with one Tab stop; Arrow keys wrap across active options while Home and End select the boundaries.",
+          "Inactive options remain named and disabled, and keyboard movement skips them."
+        ],
+        "states": [
+          "value is the selected option value and updates when the user chooses an active option.",
+          "options provides one flat list; sections takes precedence and adds visual separators while preserving one radio group.",
+          "A preview may use a token-based backgroundColor, a CSS gradient backgroundImage, and an optional opacity from zero through one.",
+          "The parent owns persistence and application of the selected value; SwatchPicker owns only choice interaction and dsChange."
+        ],
+        "responsiveBehavior": [
+          "Options wrap within the width supplied by the parent while retaining compact fixed swatch geometry.",
+          "Keep the set small enough for direct visual comparison; switch to a named list when wrapping harms comprehension."
+        ],
+        "frameworkCaveats": {
+          "customElements": [
+            "Assign options or sections as JavaScript properties, bind value, and listen for dsChange."
+          ],
+          "react": [
+            "Use DsSwatchPicker, pass option arrays as props, and handle onDsChange."
+          ],
+          "angular": [
+            "Use property bindings for options or sections and handle dsChange to update application state."
+          ]
+        },
+        "references": [
+          {
+            "label": "Executable stories",
+            "path": "src/wc/components/SwatchPicker/SwatchPicker.stories.ts"
+          }
+        ]
+      },
+      "api": {
+        "props": {
+          "groupLabel": {
+            "type": "string",
+            "required": false
+          },
+          "options": {
+            "type": "SwatchPickerOption[]",
+            "required": false
+          },
+          "sections": {
+            "type": "SwatchPickerSection[]",
+            "required": false
+          },
+          "value": {
+            "type": "string",
+            "required": false
+          }
+        },
+        "events": [
+          {
+            "name": "dsChange",
+            "detail": "string"
+          }
+        ],
+        "slots": []
+      },
+      "exports": {
+        "customElement": "ds-swatch-picker",
+        "react": "DsSwatchPicker",
+        "angular": "DsSwatchPicker"
+      },
+      "dependencies": [
+        "@ds-mo/ui",
+        "@ds-mo/tokens"
+      ],
+      "componentDependencies": []
+    },
     {
       "id": "component:ds-switch",
       "tag": "ds-switch",
@@ -4651,7 +6262,8 @@
         "commonlyComposedWith": [
           "component:ds-card",
           "component:ds-text",
-          "component:ds-icon"
+          "component:ds-icon",
+          "component:ds-menu"
         ],
         "accessibility": [
           "The visible label provides Tag's accessible name; a separate aria-label is normally unnecessary.",