@ds-mo/ui 9.0.0 → 9.1.0

package/README.md

@@ -48,6 +48,34 @@ There is **no** published `@ds-mo/ui/loader` or global `@ds-mo/ui/css` bundle
 
 **SPA hosts (Angular / React):** `ds-panel-nav` and `ds-bar-nav` need a [first-paint integration contract](docs/framework-integration.md) on hard reload — seed bar-nav state and stamp `data-nav-style` before custom elements upgrade.
 
+## Agent recipes through MCP
+
+The package includes a local stdio MCP server that exposes component metadata and
+executable Custom Elements, React, and Angular composition recipes. It runs on the
+developer's machine; no hosted MCP service or API key is required.
+
+When `@ds-mo/ui` is installed in the consuming project, point Codex at the package binary:
+
+```toml
+# .codex/config.toml
+[mcp_servers.compomo]
+command = "./node_modules/.bin/compomo-mcp"
+```
+
+Or let npm obtain the latest public package when the MCP client starts:
+
+```toml
+[mcp_servers.compomo]
+command = "npx"
+args = ["-y", "--package", "@ds-mo/ui@latest", "compomo-mcp"]
+```
+
+The server provides `list_components`, `get_component`, `get_setup_guide`,
+`get_component_source`, `list_patterns`, and `get_pattern`. Add a repository
+instruction telling agents to retrieve the applicable pattern before composing
+multiple design-system components; connecting the MCP makes recipes available,
+while the instruction makes their use consistent.
+
 ## Components
 
 All tags are `ds-*` custom elements. Grouped by role (see Storybook for props and stories):

package/dist/.build-stamp

@@ -1 +1 @@
-1784322516816
+1784331945246

package/dist/agent-patterns.json

@@ -0,0 +1,233 @@
+{
+  "schemaVersion": "1.0.0",
+  "package": "@ds-mo/ui",
+  "packageVersion": "9.1.0",
+  "kind": "patterns",
+  "entries": [
+    {
+      "id": "pattern:application-shell",
+      "status": "experimental",
+      "summary": "Required base-page composition for standard authenticated applications, with one AppShell coordinating primary destinations, secondary route sections, tools chrome, responsive modes, and stable main content geometry.",
+      "useWhen": [
+        "Building any standard authenticated product or workspace page with CompoMo.",
+        "Application navigation and tools must remain consistent around changing route content.",
+        "Creating a reusable base-page template for CompoMo applications."
+      ],
+      "avoidWhen": [
+        "Building authentication, onboarding, public, marketing, print, error, or intentionally focused full-screen experiences.",
+        "The page is already rendered inside an AppShell.",
+        "A nested or second application shell is being considered."
+      ],
+      "components": [
+        {
+          "component": "component:ds-app-shell",
+          "role": "Provides the single workspace root and coordinates shell composition, shared chrome, responsive modes, and stable content geometry.",
+          "required": true
+        },
+        {
+          "component": "component:ds-panel-nav",
+          "role": "Provides the application's one primary navigation with top-level destinations and standard Dashboard/Settings and account footer controls.",
+          "required": true
+        },
+        {
+          "component": "component:ds-bar-nav",
+          "role": "Provides secondary route-section navigation or the active primary destination label while preserving shell height.",
+          "required": true
+        },
+        {
+          "component": "component:ds-panel-tools",
+          "role": "Provides required tools chrome with Search and Help as the minimum standard tools and optional additional product tools.",
+          "required": true
+        }
+      ],
+      "stateOwnership": [
+        "The application router owns the current route, Dashboard or Settings context, authorization filtering, destination and section collections, localized labels, and navigation execution.",
+        "AppShell owns desktop, tablet, and mobile composition, shell geometry, navStyle propagation, gradient alignment, chrome transitions, metrics, and shell shortcuts.",
+        "PanelNav owns primary-destination presentation and the user-controlled desktop collapse preference.",
+        "BarNav derives the active secondary route from currentUrl and basePath and receives the active PanelNav destination label as heading.",
+        "PanelTools owns tool-rail and drawer interaction while the application owns available tool content and active-tool state.",
+        "PanelNav groups and BarNav dividers visually organize peers and never introduce nested navigation hierarchy."
+      ],
+      "accessibility": [
+        "Render one main landmark in the default content region.",
+        "Use PanelNav exclusively for primary destinations and BarNav exclusively for secondary route sections.",
+        "Keep localized visible labels and accessible names available when navigation is collapsed or moved into overflow.",
+        "Provide Search and Help as the minimum accessible PanelTools actions.",
+        "Preserve keyboard focus and route state across responsive and Dashboard/Settings context changes."
+      ],
+      "responsiveBehavior": [
+        "Use fixed system breakpoints: desktop at 1200px and wider, tablet from 768px through 1199px, and mobile below 768px.",
+        "Desktop permits PanelNav expansion and collapse and restores the persisted user preference.",
+        "Tablet keeps PanelNav permanently collapsed and does not overwrite the desktop preference.",
+        "Mobile keeps AppShell as the root while replacing desktop navigation with a future dedicated mobile navigation design.",
+        "Keep BarNav height, PanelTools chrome, and main-content origin stable across route changes.",
+        "Treat the complete responsive composition as an intended contract that is not yet fully implemented by the current AppShell runtime."
+      ],
+      "implementations": {
+        "customElements": {
+          "status": "verified",
+          "references": [
+            "src/wc/components/AppShell/AppShell.stories.ts",
+            "docs/framework-integration.md"
+          ]
+        },
+        "react": {
+          "status": "planned",
+          "references": [
+            "scripts/verify-package-imports.mjs",
+            "docs/framework-integration.md"
+          ]
+        },
+        "angular": {
+          "status": "verified",
+          "references": [
+            "scripts/verify-package-imports.mjs",
+            "docs/framework-integration.md"
+          ]
+        }
+      },
+      "references": [
+        "src/wc/components/AppShell/AppShell.mdx",
+        "docs/framework-integration.md"
+      ]
+    },
+    {
+      "id": "pattern:menu-trigger",
+      "status": "stable",
+      "summary": "Connect a ButtonUnfilled trigger to an anchored Menu for a compact command or view-selection popup without application-authored positioning.",
+      "useWhen": [
+        "A button should reveal a short contextual collection of commands.",
+        "A compact button should show the current view or mode and let the user choose another one from a menu."
+      ],
+      "avoidWhen": [
+        "The choice is a submitted form value with a field label or validation; use Select.",
+        "The available local views can remain visible; use TabGroup.",
+        "The choices are primary or secondary application destinations; use the matching navigation component.",
+        "The popup contains substantial content, confirmation, or a form; use Modal."
+      ],
+      "components": [
+        {
+          "component": "component:ds-button-unfilled",
+          "role": "Provides the visible trigger, popup relationship attributes, and focus target.",
+          "required": true
+        },
+        {
+          "component": "component:ds-menu",
+          "role": "Owns anchored placement, menu semantics, keyboard navigation, viewport clamping, selection, and close behavior.",
+          "required": true
+        }
+      ],
+      "stateOwnership": [
+        "The application owns the selected command or view value and derives the trigger label and each item's isSelected state from it.",
+        "The application synchronizes one open boolean to ButtonUnfilled.expanded and Menu.open.",
+        "Menu owns popup placement and keyboard navigation; the application never calculates popup coordinates or applies positional CSS.",
+        "On dsSelect, update the selected value, close the Menu, and restore focus to the trigger.",
+        "On dsClose, synchronize the application open state to false."
+      ],
+      "accessibility": [
+        "Set ButtonUnfilled.haspopup to menu, controls to the Menu id, and expanded from the same open state passed to Menu.",
+        "Give Menu a concise menuLabel describing the available commands or views.",
+        "Set Menu.initialFocusVisible only when the trigger MouseEvent detail is zero, indicating keyboard activation.",
+        "Keep visible selected styling synchronized with the application's selected value; Menu exposes the selected command through aria-current.",
+        "Return focus to the trigger after selection; Menu already restores it for Escape and outside dismissal."
+      ],
+      "responsiveBehavior": [
+        "Keep Menu's default choice-cell anchor alignment unless deliberate custom frame geometry is required.",
+        "Let Menu clamp to the viewport and avoid application-authored fixed or absolute positioning.",
+        "Use a concise trigger label that can fit the owning layout without hiding the selected meaning."
+      ],
+      "implementations": {
+        "customElements": {
+          "status": "verified",
+          "recipes": [
+            {
+              "id": "selected-view-menu",
+              "title": "Selected view menu",
+              "summary": "A ButtonUnfilled displays the active view and opens a Menu whose selected row updates that view.",
+              "files": [
+                {
+                  "path": "view-menu.html",
+                  "language": "html",
+                  "content": "<ds-button-unfilled\n  id=\"view-menu-trigger\"\n  label=\"View · Overview\"\n  haspopup=\"menu\"\n  controls=\"view-menu\"\n></ds-button-unfilled>\n<ds-menu\n  id=\"view-menu\"\n  anchor-id=\"view-menu-trigger\"\n  menu-label=\"Choose view\"\n></ds-menu>"
+                },
+                {
+                  "path": "view-menu.ts",
+                  "language": "typescript",
+                  "content": "import '@ds-mo/ui/components/ds-button-unfilled.js'\nimport '@ds-mo/ui/components/ds-menu.js'\nimport type { MenuItemData } from '@ds-mo/ui'\n\nconst choices: MenuItemData[] = [\n  { label: 'Overview', value: 'overview' },\n  { label: 'Map', value: 'map' },\n  { label: 'Timeline', value: 'timeline' },\n]\n\nconst trigger = document.querySelector<HTMLDsButtonUnfilledElement>('#view-menu-trigger')!\nconst menu = document.querySelector<HTMLDsMenuElement>('#view-menu')!\nlet selectedValue = 'overview'\n\nfunction render() {\n  const selected = choices.find(item => item.value === selectedValue) ?? choices[0]\n  trigger.label = `View · ${selected.label}`\n  menu.items = choices.map(item => ({ ...item, isSelected: item.value === selectedValue }))\n}\n\nfunction setOpen(open: boolean) {\n  trigger.expanded = open\n  menu.open = open\n}\n\ntrigger.addEventListener('dsClick', event => {\n  const mouseEvent = (event as CustomEvent<MouseEvent>).detail\n  menu.initialFocusVisible = mouseEvent.detail === 0\n  setOpen(!menu.open)\n})\nmenu.addEventListener('dsClose', () => setOpen(false))\nmenu.addEventListener('dsSelect', event => {\n  selectedValue = (event as CustomEvent<MenuItemData>).detail.value ?? selectedValue\n  render()\n  setOpen(false)\n  requestAnimationFrame(() => trigger.setFocus())\n})\n\nrender()"
+                }
+              ],
+              "notes": [
+                "Assign Menu.items as a JavaScript property; complex arrays cannot be expressed as an HTML attribute.",
+                "Do not add positioning styles to either element."
+              ]
+            }
+          ],
+          "references": [
+            "src/wc/components/Tag/Tag.stories.ts",
+            "src/wc/components/Menu/Menu.stories.ts"
+          ]
+        },
+        "react": {
+          "status": "verified",
+          "recipes": [
+            {
+              "id": "selected-view-menu",
+              "title": "Selected view menu",
+              "summary": "A controlled React composition using generated ButtonUnfilled and Menu wrappers.",
+              "files": [
+                {
+                  "path": "ViewMenu.tsx",
+                  "language": "tsx",
+                  "content": "import { useState } from 'react'\nimport type { HTMLDsButtonUnfilledElement, MenuItemData } from '@ds-mo/ui'\nimport { DsButtonUnfilled, DsMenu } from '@ds-mo/ui/react'\n\nconst choices: MenuItemData[] = [\n  { label: 'Overview', value: 'overview' },\n  { label: 'Map', value: 'map' },\n  { label: 'Timeline', value: 'timeline' },\n]\n\nexport function ViewMenu() {\n  const [selectedValue, setSelectedValue] = useState('overview')\n  const [open, setOpen] = useState(false)\n  const [initialFocusVisible, setInitialFocusVisible] = useState(false)\n  const selected = choices.find(item => item.value === selectedValue) ?? choices[0]\n  const items = choices.map(item => ({ ...item, isSelected: item.value === selectedValue }))\n\n  function focusTrigger() {\n    requestAnimationFrame(() => {\n      const trigger = document.querySelector<HTMLDsButtonUnfilledElement>('#view-menu-trigger')\n      trigger?.setFocus()\n    })\n  }\n\n  return (\n    <>\n      <DsButtonUnfilled\n        id=\"view-menu-trigger\"\n        label={`View · ${selected.label}`}\n        haspopup=\"menu\"\n        controls=\"view-menu\"\n        expanded={open}\n        onDsClick={event => {\n          setInitialFocusVisible(event.detail.detail === 0)\n          setOpen(current => !current)\n        }}\n      />\n      <DsMenu\n        id=\"view-menu\"\n        anchorId=\"view-menu-trigger\"\n        menuLabel=\"Choose view\"\n        items={items}\n        open={open}\n        initialFocusVisible={initialFocusVisible}\n        onDsClose={() => setOpen(false)}\n        onDsSelect={event => {\n          setSelectedValue(event.detail.value ?? selectedValue)\n          setOpen(false)\n          focusTrigger()\n        }}\n      />\n    </>\n  )\n}"
+                }
+              ],
+              "notes": [
+                "Use one React state value for both the trigger expanded prop and Menu open prop.",
+                "Keep the stable trigger and menu ids unique when rendering more than one composition."
+              ]
+            }
+          ],
+          "references": [
+            "src/react/ds-button-unfilled.ts",
+            "src/react/ds-menu.ts"
+          ]
+        },
+        "angular": {
+          "status": "verified",
+          "recipes": [
+            {
+              "id": "selected-view-menu",
+              "title": "Selected view menu",
+              "summary": "A controlled Angular composition using generated standalone ButtonUnfilled and Menu adapters.",
+              "files": [
+                {
+                  "path": "view-menu.component.html",
+                  "language": "html",
+                  "content": "<ds-button-unfilled\n  id=\"view-menu-trigger\"\n  [label]=\"'View · ' + selectedLabel\"\n  haspopup=\"menu\"\n  controls=\"view-menu\"\n  [expanded]=\"open\"\n  (dsClick)=\"toggleMenu($event)\"\n></ds-button-unfilled>\n<ds-menu\n  id=\"view-menu\"\n  anchorId=\"view-menu-trigger\"\n  menuLabel=\"Choose view\"\n  [items]=\"menuItems\"\n  [open]=\"open\"\n  [initialFocusVisible]=\"initialFocusVisible\"\n  (dsClose)=\"open = false\"\n  (dsSelect)=\"selectView($event)\"\n></ds-menu>"
+                },
+                {
+                  "path": "view-menu.component.ts",
+                  "language": "typescript",
+                  "content": "import { Component } from '@angular/core'\nimport type { HTMLDsButtonUnfilledElement, MenuItemData } from '@ds-mo/ui'\nimport { DsButtonUnfilled } from '@ds-mo/ui/angular/ds-button-unfilled'\nimport { DsMenu } from '@ds-mo/ui/angular/ds-menu'\n\nconst choices: MenuItemData[] = [\n  { label: 'Overview', value: 'overview' },\n  { label: 'Map', value: 'map' },\n  { label: 'Timeline', value: 'timeline' },\n]\n\n@Component({\n  selector: 'app-view-menu',\n  standalone: true,\n  imports: [DsButtonUnfilled, DsMenu],\n  templateUrl: './view-menu.component.html',\n})\nexport class ViewMenuComponent {\n  selectedValue = 'overview'\n  open = false\n  initialFocusVisible = false\n\n  get selectedLabel() {\n    return choices.find(item => item.value === this.selectedValue)?.label ?? choices[0].label\n  }\n\n  get menuItems() {\n    return choices.map(item => ({ ...item, isSelected: item.value === this.selectedValue }))\n  }\n\n  toggleMenu(event: CustomEvent<MouseEvent>) {\n    this.initialFocusVisible = event.detail.detail === 0\n    this.open = !this.open\n  }\n\n  selectView(event: CustomEvent<MenuItemData>) {\n    this.selectedValue = event.detail.value ?? this.selectedValue\n    this.open = false\n    requestAnimationFrame(() => {\n      const trigger = document.querySelector<HTMLDsButtonUnfilledElement>('#view-menu-trigger')\n      trigger?.setFocus()\n    })\n  }\n}"
+                }
+              ],
+              "notes": [
+                "Bind items as a property and import both generated standalone adapters.",
+                "Keep the stable trigger and menu ids unique when rendering more than one composition."
+              ]
+            }
+          ],
+          "references": [
+            "src/angular/ds-button-unfilled.ts",
+            "src/angular/ds-menu.ts"
+          ]
+        }
+      },
+      "references": [
+        "src/wc/components/Tag/Tag.stories.ts",
+        "src/wc/components/Menu/Menu.agent.json",
+        "docs/framework-integration.md"
+      ]
+    }
+  ]
+}

package/dist/agent.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": "1.0.0",
   "package": "@ds-mo/ui",
-  "packageVersion": "9.0.0",
+  "packageVersion": "9.1.0",
   "kind": "components",
   "entries": [
     {
@@ -29,7 +29,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"
@@ -672,6 +672,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.",
@@ -2382,14 +2385,17 @@
           "component:ds-button-unfilled",
           "component:ds-panel-nav",
           "component:ds-switch",
-          "component:ds-shell-gradient-picker"
+          "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.",
-          "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.",
+          "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": [
@@ -2397,9 +2403,10 @@
           "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."
+          "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."
         ],
@@ -2439,6 +2446,10 @@
             "type": "HTMLElement | undefined",
             "required": false
           },
+          "anchorAlignment": {
+            "type": "ChoicePopupAnchorAlignment",
+            "required": false
+          },
           "anchorId": {
             "type": "string | undefined",
             "required": false
@@ -2492,6 +2503,10 @@
           {
             "name": "dsSelect",
             "detail": "MenuItemData"
+          },
+          {
+            "name": "dsSwatchSelect",
+            "detail": "string"
           }
         ],
         "slots": []
@@ -2507,7 +2522,7 @@
       ],
       "componentDependencies": [
         "badge",
-        "shell-gradient-picker",
+        "swatch-picker",
         "switch",
         "text"
       ]
@@ -3757,12 +3772,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 +3833,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 +3875,7 @@
         "@ds-mo/tokens"
       ],
       "componentDependencies": [
-        "shell-gradient-swatch"
+        "swatch-picker"
       ]
     },
     {
@@ -3866,12 +3883,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 +3902,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 +4165,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 +4335,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 +4786,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.",

package/dist/angular/ds-menu.d.ts

@@ -10,9 +10,10 @@ export declare class DsMenu {
     dsClose: EventEmitter<DsMenuCustomEvent<void>>;
     dsSelect: EventEmitter<DsMenuCustomEvent<IDsMenuMenuItemData>>;
     dsGradientSelect: EventEmitter<DsMenuCustomEvent<IDsMenuShellGradientPreset>>;
+    dsSwatchSelect: EventEmitter<DsMenuCustomEvent<string>>;
     constructor(c: ChangeDetectorRef, r: ElementRef, z: NgZone);
     static ɵfac: i0.ɵɵFactoryDeclaration<DsMenu, never>;
-    static ɵcmp: i0.ɵɵComponentDeclaration<DsMenu, "ds-menu", never, { "align": { "alias": "align"; "required": false; }; "alignOffset": { "alias": "alignOffset"; "required": false; }; "anchor": { "alias": "anchor"; "required": false; }; "anchorId": { "alias": "anchorId"; "required": false; }; "initialFocusVisible": { "alias": "initialFocusVisible"; "required": false; }; "items": { "alias": "items"; "required": false; }; "menuLabel": { "alias": "menuLabel"; "required": false; }; "menuWidth": { "alias": "menuWidth"; "required": false; }; "minWidth": { "alias": "minWidth"; "required": false; }; "open": { "alias": "open"; "required": false; }; "sections": { "alias": "sections"; "required": false; }; "side": { "alias": "side"; "required": false; }; "sideOffset": { "alias": "sideOffset"; "required": false; }; }, { "dsClose": "dsClose"; "dsSelect": "dsSelect"; "dsGradientSelect": "dsGradientSelect"; }, never, ["*"], true, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<DsMenu, "ds-menu", never, { "align": { "alias": "align"; "required": false; }; "alignOffset": { "alias": "alignOffset"; "required": false; }; "anchor": { "alias": "anchor"; "required": false; }; "anchorAlignment": { "alias": "anchorAlignment"; "required": false; }; "anchorId": { "alias": "anchorId"; "required": false; }; "initialFocusVisible": { "alias": "initialFocusVisible"; "required": false; }; "items": { "alias": "items"; "required": false; }; "menuLabel": { "alias": "menuLabel"; "required": false; }; "menuWidth": { "alias": "menuWidth"; "required": false; }; "minWidth": { "alias": "minWidth"; "required": false; }; "open": { "alias": "open"; "required": false; }; "sections": { "alias": "sections"; "required": false; }; "side": { "alias": "side"; "required": false; }; "sideOffset": { "alias": "sideOffset"; "required": false; }; }, { "dsClose": "dsClose"; "dsSelect": "dsSelect"; "dsGradientSelect": "dsGradientSelect"; "dsSwatchSelect": "dsSwatchSelect"; }, never, ["*"], true, never>;
 }
 export declare interface DsMenu extends Components.DsMenu {
     dsClose: EventEmitter<DsMenuCustomEvent<void>>;
@@ -21,4 +22,8 @@ export declare interface DsMenu extends Components.DsMenu {
      * Emitted when a `gradient-picker` section swatch is chosen.
      */
     dsGradientSelect: EventEmitter<DsMenuCustomEvent<IDsMenuShellGradientPreset>>;
+    /**
+     * Emitted when a generic `swatch-picker` section option is chosen.
+     */
+    dsSwatchSelect: EventEmitter<DsMenuCustomEvent<string>>;
 }

package/dist/angular/ds-menu.js

@@ -16,16 +16,17 @@ let DsMenu = class DsMenu {
         this.dsClose = new EventEmitter();
         this.dsSelect = new EventEmitter();
         this.dsGradientSelect = new EventEmitter();
+        this.dsSwatchSelect = new EventEmitter();
         c.detach();
         this.el = r.nativeElement;
     }
     static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.0.6", ngImport: i0, type: DsMenu, deps: [{ token: i0.ChangeDetectorRef }, { token: i0.ElementRef }, { token: i0.NgZone }], target: i0.ɵɵFactoryTarget.Component }); }
-    static { this.ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "14.0.0", version: "22.0.6", type: DsMenu, isStandalone: true, selector: "ds-menu", inputs: { align: "align", alignOffset: "alignOffset", anchor: "anchor", anchorId: "anchorId", initialFocusVisible: "initialFocusVisible", items: "items", menuLabel: "menuLabel", menuWidth: "menuWidth", minWidth: "minWidth", open: "open", sections: "sections", side: "side", sideOffset: "sideOffset" }, outputs: { dsClose: "dsClose", dsSelect: "dsSelect", dsGradientSelect: "dsGradientSelect" }, ngImport: i0, template: '<ng-content></ng-content>', isInline: true, changeDetection: i0.ChangeDetectionStrategy.OnPush }); }
+    static { this.ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "14.0.0", version: "22.0.6", type: DsMenu, isStandalone: true, selector: "ds-menu", inputs: { align: "align", alignOffset: "alignOffset", anchor: "anchor", anchorAlignment: "anchorAlignment", anchorId: "anchorId", initialFocusVisible: "initialFocusVisible", items: "items", menuLabel: "menuLabel", menuWidth: "menuWidth", minWidth: "minWidth", open: "open", sections: "sections", side: "side", sideOffset: "sideOffset" }, outputs: { dsClose: "dsClose", dsSelect: "dsSelect", dsGradientSelect: "dsGradientSelect", dsSwatchSelect: "dsSwatchSelect" }, ngImport: i0, template: '<ng-content></ng-content>', isInline: true, changeDetection: i0.ChangeDetectionStrategy.OnPush }); }
 };
 DsMenu = __decorate([
     ProxyCmp({
         defineCustomElementFn: defineDsMenu,
-        inputs: ['align', 'alignOffset', 'anchor', 'anchorId', 'initialFocusVisible', 'items', 'menuLabel', 'menuWidth', 'minWidth', 'open', 'sections', 'side', 'sideOffset']
+        inputs: ['align', 'alignOffset', 'anchor', 'anchorAlignment', 'anchorId', 'initialFocusVisible', 'items', 'menuLabel', 'menuWidth', 'minWidth', 'open', 'sections', 'side', 'sideOffset']
     })
 ], DsMenu);
 export { DsMenu };
@@ -36,8 +37,8 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.6", ngImpor
                     changeDetection: ChangeDetectionStrategy.OnPush,
                     template: '<ng-content></ng-content>',
                     // eslint-disable-next-line @angular-eslint/no-inputs-metadata-property
-                    inputs: ['align', 'alignOffset', 'anchor', 'anchorId', 'initialFocusVisible', 'items', 'menuLabel', 'menuWidth', 'minWidth', 'open', 'sections', 'side', 'sideOffset'],
-                    outputs: ['dsClose', 'dsSelect', 'dsGradientSelect'],
+                    inputs: ['align', 'alignOffset', 'anchor', 'anchorAlignment', 'anchorId', 'initialFocusVisible', 'items', 'menuLabel', 'menuWidth', 'minWidth', 'open', 'sections', 'side', 'sideOffset'],
+                    outputs: ['dsClose', 'dsSelect', 'dsGradientSelect', 'dsSwatchSelect'],
                 }]
         }], ctorParameters: () => [{ type: i0.ChangeDetectorRef }, { type: i0.ElementRef }, { type: i0.NgZone }], propDecorators: { dsClose: [{
                 type: Output
@@ -45,4 +46,6 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.6", ngImpor
                 type: Output
             }], dsGradientSelect: [{
                 type: Output
+            }], dsSwatchSelect: [{
+                type: Output
             }] } });