@ds-mo/ui 6.0.1 → 8.0.0

package/dist/agent.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": "1.0.0",
   "package": "@ds-mo/ui",
-  "packageVersion": "6.0.1",
+  "packageVersion": "8.0.0",
   "kind": "components",
   "entries": [
     {
@@ -130,9 +130,83 @@
       "tag": "ds-badge",
       "name": "badge",
       "title": "Badge",
-      "summary": "Compact counter or notification dot for status and unread indicators.",
-      "intentStatus": "migration-pending",
-      "intent": null,
+      "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.",
+          "The immediate backing surface can be identified so the badge ring visually separates the mark from its owner."
+        ],
+        "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."
+          },
+          {
+            "when": "The count is primary content rather than supplemental notification chrome.",
+            "component": "component:ds-text",
+            "reason": "Text preserves the quantity as normal readable content."
+          }
+        ],
+        "commonlyComposedWith": [
+          "component:ds-button-unfilled",
+          "component:ds-bar-nav",
+          "component:ds-panel-nav",
+          "component:ds-menu"
+        ],
+        "accessibility": [
+          "The owning control or content provides the primary accessible name; Badge contributes only supplemental unread or notification meaning.",
+          "When a dot is announced, provide contextual text that explains its meaning. Otherwise mark it aria-hidden from the owning composition.",
+          "When a counter is announced, provide contextual text such as “5 unread notifications”; a bare number is insufficient.",
+          "Avoid duplicating information already included in the owning control's accessible name.",
+          "Badge never receives focus and never owns an interaction."
+        ],
+        "states": [
+          "Counter represents an unread or notification count, while dot communicates presence without quantity.",
+          "Non-positive counter values hide the badge.",
+          "Counts above the configured compact limit display the limit with a plus suffix while accessible text retains meaningful context.",
+          "Badge keeps one brand treatment; semantic severity belongs to another component or adjacent content.",
+          "The ring matches the immediate backing surface for both variants. Use a direct ring override only for a component-local fill that no surface preset represents.",
+          "Shell gradient rings align automatically inside active AppShell gradient chrome and may be explicitly enabled or disabled when composition requires it."
+        ],
+        "responsiveBehavior": [
+          "The owning control or layout positions Badge and decides whether notification indicators remain visible, condense, or move at responsive breakpoints.",
+          "Badge does not anchor itself or automatically switch between counter and dot variants."
+        ],
+        "frameworkCaveats": {
+          "customElements": [
+            "Position Badge from the owning element's layout and synchronize its contextual accessibility text with the owner."
+          ],
+          "react": [
+            "Keep count, visibility, and contextual accessibility text derived from the same unread-notification state as the owning control."
+          ],
+          "angular": [
+            "Keep count, visibility, and contextual accessibility text derived from the same unread-notification state as the owning control."
+          ]
+        },
+        "references": [
+          {
+            "label": "Storybook examples",
+            "path": "src/wc/components/Badge/Badge.stories.ts"
+          }
+        ]
+      },
       "api": {
         "props": {
           "background": {
@@ -290,7 +364,7 @@
         ],
         "accessibility": [
           "Use concise localized labels for every route section.",
-          "Keep section navigation keyboard accessible through the generated TabGroupNav behavior and overflow menu.",
+          "Keep section navigation keyboard accessible through BarNav's built-in horizontal roving focus and overflow menu.",
           "Preserve the selected route state when sections move between the visible row and overflow menu.",
           "Use notification dots only as supplemental status and not as the sole indication of important information.",
           "Pass the active PanelNav destination label through heading whenever section tabs are absent or hidden."
@@ -393,9 +467,9 @@
         "@ds-mo/tokens"
       ],
       "componentDependencies": [
+        "badge",
         "button-unfilled",
         "menu",
-        "tab-group-nav",
         "text"
       ]
     },
@@ -404,20 +478,23 @@
       "tag": "ds-button-filled",
       "name": "button-filled",
       "title": "ButtonFilled",
-      "summary": "Emphasized command button for primary, confirming, or semantically important actions.",
+      "summary": "Highest-emphasis command button for the single primary action in a local decision area, with semantic consequence and async progress treatments.",
       "intentStatus": "complete",
       "intent": {
         "audience": "general",
         "status": "stable",
-        "summary": "Emphasized command button for primary, confirming, or semantically important actions.",
+        "summary": "Highest-emphasis command button for the single primary action in a local decision area, with semantic consequence and async progress treatments.",
         "useWhen": [
-          "The user initiates a primary or emphasized command.",
-          "An action needs a semantic intent such as positive, negative, warning, or AI."
+          "The user initiates the single primary command in a local decision area.",
+          "An action's consequence requires a matching semantic treatment.",
+          "A standalone compact primary action needs an icon-only presentation with an explicit accessible name."
         ],
         "avoidWhen": [
+          "Another filled action already exists in the same local decision area.",
           "The action is unfilled icon-only shell or navigation chrome.",
           "The element represents navigation rather than a command.",
-          "The content is a persistent selected state rather than an action."
+          "The content is a persistent selected state rather than an action.",
+          "A semantic color would be decorative or merely match the surrounding product area."
         ],
         "alternatives": [
           {
@@ -438,15 +515,31 @@
         "accessibility": [
           "Provide an explicit accessible name for icon-only buttons.",
           "Use inactive state only when the action must remain visible but unavailable.",
-          "Do not encode the action meaning through color alone."
+          "Do not encode the action meaning through color alone.",
+          "Loading keeps the action's accessible name and exposes busy state; announce broader operation progress from the owning workflow when users need confirmation.",
+          "Use native submit behavior for form submission and handle the form submit event rather than submitting from the button click event."
         ],
         "states": [
-          "Choose one primary filled action per local decision area when possible.",
-          "Use semantic intent for meaning and contrast for emphasis; do not use contrast as a substitute for state."
+          "Use only one filled action per local decision area; render all secondary actions with ButtonUnfilled.",
+          "Choose brand or neutral for general commands. Reserve positive, negative, warning, and caution for matching action consequences, and AI, guide, or walkthrough for actions that enter those feature experiences.",
+          "Contrast serves both surface adaptation and hierarchy, but never permits a second filled action in the same decision area.",
+          "Loading prevents duplicate activation without applying inactive opacity.",
+          "Icon and icon-label loading replace the icon in place. Label-only loading centers the loader while preserving the button's measured width."
         ],
         "responsiveBehavior": [
           "Use fill width only when the parent layout calls for a full-width action, commonly on narrow form layouts."
         ],
+        "frameworkCaveats": {
+          "customElements": [
+            "For form submission, use the native submit type and listen to the form submit event; use dsClick for non-submit commands."
+          ],
+          "react": [
+            "Keep async state in the owner and pass it to the loading state until the command settles."
+          ],
+          "angular": [
+            "Keep async state in the owner and pass it to the loading state until the command settles."
+          ]
+        },
         "references": [
           {
             "label": "Storybook examples",
@@ -476,6 +569,10 @@
             "type": "boolean",
             "required": false
           },
+          "isLoading": {
+            "type": "boolean",
+            "required": false
+          },
           "label": {
             "type": "string",
             "required": false
@@ -517,6 +614,7 @@
       ],
       "componentDependencies": [
         "icon",
+        "loader",
         "text"
       ]
     },
@@ -525,9 +623,84 @@
       "tag": "ds-button-unfilled",
       "name": "button-unfilled",
       "title": "ButtonUnfilled",
-      "summary": "Unfilled button with variant (label / icon / icon-label), control-density sizes, width hug/fill, active/border/dot, and surface-aware interaction states.",
-      "intentStatus": "migration-pending",
-      "intent": null,
+      "summary": "Secondary command and compact chrome button with optional persistent toggle state, surface-aware interaction treatment, and async progress.",
+      "intentStatus": "complete",
+      "intent": {
+        "audience": "general",
+        "status": "stable",
+        "summary": "Secondary command and compact chrome button with optional persistent toggle state, surface-aware interaction treatment, and async progress.",
+        "useWhen": [
+          "A secondary command accompanies the single filled primary action in a local decision area.",
+          "A toolbar, tool rail, overflow area, or shell region needs a compact icon action.",
+          "A command represents a persistent toggle or mode whose active state remains meaningful after activation."
+        ],
+        "avoidWhen": [
+          "The command is the single primary action in a local decision area; use ButtonFilled instead.",
+          "The control selects an application destination or local content panel; use the matching navigation component.",
+          "Active styling would only indicate the most recently invoked command or add decorative emphasis.",
+          "Surface context would be used to make the action louder or quieter rather than describe its actual parent surface."
+        ],
+        "alternatives": [
+          {
+            "when": "The command is the single primary action in the decision area.",
+            "component": "component:ds-button-filled",
+            "reason": "ButtonFilled owns highest-emphasis commands."
+          },
+          {
+            "when": "The choices are persistent application destinations.",
+            "component": "component:ds-panel-nav",
+            "reason": "PanelNav owns primary route selection and navigation semantics."
+          },
+          {
+            "when": "The choices are transient commands or contextual options.",
+            "component": "component:ds-menu",
+            "reason": "Menu owns temporary popup collections and their keyboard model."
+          }
+        ],
+        "commonlyComposedWith": [
+          "component:ds-button-filled",
+          "component:ds-menu",
+          "component:ds-panel-tools"
+        ],
+        "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.",
+          "Treat notification dots as supplemental unread or status information; never use a dot as the sole state, meaning, or accessible name.",
+          "Loading keeps the action's accessible name and exposes busy state; announce broader operation progress from the owning workflow when needed.",
+          "Use inactive state only when an unavailable action must remain visible.",
+          "For form submission, use native submit behavior and handle the form submit event rather than submitting from the button click event."
+        ],
+        "states": [
+          "General content UI keeps the selected interaction fill and border for persistent active state.",
+          "Shell, navigation, and tool-rail chrome uses foreground-only active state with no selected fill or border.",
+          "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.",
+          "Surface context must match the actual parent surface; translucent, inverted, media, and always-dark treatments are reserved for those surfaces.",
+          "Loading prevents duplicate activation without applying inactive opacity.",
+          "Icon and icon-label loading replace the icon in place. Label-only loading centers the loader while preserving the button's measured width."
+        ],
+        "responsiveBehavior": [
+          "The consuming layout decides when an icon-label action becomes icon-only and must provide an explicit accessible name after changing variants.",
+          "Use fill width only when the parent layout requires a full-width secondary action."
+        ],
+        "frameworkCaveats": {
+          "customElements": [
+            "For form submission, use the native submit type and listen to the form submit event; use dsClick for non-submit commands.",
+            "Roving-focus composites own the button's tab-stop placement and selection semantics."
+          ],
+          "react": [
+            "Keep active, pressed, and async state synchronized from the owning toolbar or workflow."
+          ],
+          "angular": [
+            "Keep active, pressed, and async state synchronized from the owning toolbar or workflow."
+          ]
+        },
+        "references": [
+          {
+            "label": "Storybook examples",
+            "path": "src/wc/components/ButtonUnfilled/ButtonUnfilled.stories.ts"
+          }
+        ]
+      },
       "api": {
         "props": {
           "activeFill": {
@@ -542,10 +715,6 @@
             "type": "ButtonUnfilledBackground | undefined",
             "required": false
           },
-          "backgroundContrast": {
-            "type": "ButtonUnfilledOnBackgroundContrast",
-            "required": false
-          },
           "controls": {
             "type": "string | undefined",
             "required": false
@@ -582,6 +751,10 @@
             "type": "boolean",
             "required": false
           },
+          "isLoading": {
+            "type": "boolean",
+            "required": false
+          },
           "label": {
             "type": "string",
             "required": false
@@ -632,6 +805,7 @@
       "componentDependencies": [
         "badge",
         "icon",
+        "loader",
         "text"
       ]
     },
@@ -1058,15 +1232,81 @@
       "tag": "ds-chip",
       "name": "chip",
       "title": "Chip",
-      "summary": "Removable metadata chip — same control-density recipe as Tag, colored by semantic state (default / active / error / caution). Not a toggle/select control.",
-      "intentStatus": "migration-pending",
-      "intent": null,
+      "summary": "Always-removable metadata value for primary surfaces, with semantic value status and parent-owned removal.",
+      "intentStatus": "complete",
+      "intent": {
+        "audience": "general",
+        "status": "stable",
+        "summary": "Always-removable metadata value for primary surfaces, with semantic value status and parent-owned removal.",
+        "useWhen": [
+          "A user-applied value such as a filter, recipient, or tokenized input entry must remain visible and individually removable.",
+          "A compact metadata value needs a semantic neutral, active, error, or caution status before removal.",
+          "A collection owner can remove the represented value and restore focus after the dismiss action."
+        ],
+        "avoidWhen": [
+          "The label is static or not individually removable; use Tag instead.",
+          "The control selects, toggles, or navigates; use the matching button or navigation component.",
+          "The information is a persistent status, count, or unread indicator; use Badge or an appropriate status composition instead.",
+          "The chip would be placed on any surface other than a primary surface."
+        ],
+        "alternatives": [
+          {
+            "when": "The metadata label is static and has no dismiss action.",
+            "component": "component:ds-tag",
+            "reason": "Tag owns non-interactive taxonomy and metadata labels."
+          },
+          {
+            "when": "The compact mark communicates a count, status, or unread indicator.",
+            "component": "component:ds-badge",
+            "reason": "Badge owns supplemental counters and status marks without a dismiss action."
+          },
+          {
+            "when": "The value is a selectable or persistent toggle.",
+            "component": "component:ds-button-unfilled",
+            "reason": "ButtonUnfilled owns command and toggle semantics."
+          }
+        ],
+        "commonlyComposedWith": [
+          "component:ds-input",
+          "component:ds-select"
+        ],
+        "accessibility": [
+          "Keep the visible label meaningful without relying on semantic color alone.",
+          "Give the dismiss action a name that identifies the represented value.",
+          "After removal, the parent moves focus to the next chip, then the previous chip, or the owning collection or input trigger when no chips remain.",
+          "Inactive chips remain visible while their dismiss action is disabled and removed from keyboard interaction."
+        ],
+        "states": [
+          "Semantic state describes the represented value; active does not mean selected or pressed.",
+          "The dismiss action is the chip's only interaction, and the parent owns data mutation after dsRemove.",
+          "Long labels remain on one line and truncate only when the consuming layout supplies a maximum width; otherwise the chip sizes to its content.",
+          "Rounded shape is a visual choice and does not change semantics or interaction.",
+          "Chip is designed only for primary surfaces and has no surface-context API."
+        ],
+        "responsiveBehavior": [
+          "The parent chooses chip size and owns wrapping, overflow, and collection condensation.",
+          "Chip does not automatically resize, hide, or collapse its label at responsive breakpoints."
+        ],
+        "frameworkCaveats": {
+          "customElements": [
+            "dsRemove has no payload; associate each rendered chip with its owning value and remove that value from the event handler."
+          ],
+          "react": [
+            "Use the rendered chip's bound item context in the dsRemove handler, then restore focus after the collection rerenders."
+          ],
+          "angular": [
+            "Use the rendered chip's bound item context in the dsRemove handler, then restore focus after the collection rerenders."
+          ]
+        },
+        "references": [
+          {
+            "label": "Storybook examples",
+            "path": "src/wc/components/Chip/Chip.stories.ts"
+          }
+        ]
+      },
       "api": {
         "props": {
-          "background": {
-            "type": "ChipBackground | undefined",
-            "required": false
-          },
           "isInactive": {
             "type": "boolean",
             "required": false
@@ -1079,10 +1319,6 @@
             "type": "string | number | undefined",
             "required": false
           },
-          "removable": {
-            "type": "boolean",
-            "required": false
-          },
           "removeLabel": {
             "type": "string",
             "required": false
@@ -1128,11 +1364,80 @@
       "tag": "ds-divider",
       "name": "divider",
       "title": "Divider",
-      "summary": "Decorative horizontal or vertical visual separator for non-edge-to-edge separation. Supports surface-aware divider tokens, inset, and custom line length.",
-      "intentStatus": "migration-pending",
-      "intent": null,
+      "summary": "Horizontal or vertical separator between sibling content groups, decorative by default with optional structural semantics.",
+      "intentStatus": "complete",
+      "intent": {
+        "audience": "general",
+        "status": "stable",
+        "summary": "Horizontal or vertical separator between sibling content groups, decorative by default with optional structural semantics.",
+        "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."
+        ],
+        "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."
+          }
+        ],
+        "commonlyComposedWith": [
+          "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
@@ -1148,10 +1453,6 @@
           "semantic": {
             "type": "boolean",
             "required": false
-          },
-          "surface": {
-            "type": "DividerSurface",
-            "required": false
           }
         },
         "events": [],
@@ -1247,17 +1548,90 @@
       "tag": "ds-icon",
       "name": "icon",
       "title": "Icon",
-      "summary": "Icon component from @ds-mo/ui.",
-      "intentStatus": "migration-pending",
-      "intent": null,
+      "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.",
+          "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.",
+          "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 | undefined",
-            "required": false
-          },
-          "flag": {
-            "type": "boolean",
+            "type": "IconColor",
             "required": false
           },
           "label": {
@@ -1393,16 +1767,82 @@
       "tag": "ds-loader",
       "name": "loader",
       "title": "Loader",
-      "summary": "Anti-clockwise SVG spinner matching ds-icon size/color tokens.",
-      "intentStatus": "migration-pending",
-      "intent": null,
-      "api": {
-        "props": {
-          "color": {
-            "type": "LoaderColor | undefined",
-            "required": false
-          },
-          "label": {
+      "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.",
+          "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.",
+          "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
           },
@@ -1923,6 +2363,131 @@
         "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-tools",
       "tag": "ds-panel-tools",
@@ -2465,11 +3030,88 @@
       "tag": "ds-skeleton",
       "name": "skeleton",
       "title": "Skeleton",
-      "summary": "Atomic loading placeholder with token-aligned text, icon, and control canvases. Supports optional shimmer, circular icons, and rounded controls.",
-      "intentStatus": "migration-pending",
-      "intent": null,
+      "summary": "Aria-hidden atomic placeholder for preserving expected text, icon, or control geometry while structured content is pending.",
+      "intentStatus": "complete",
+      "intent": {
+        "audience": "general",
+        "status": "stable",
+        "summary": "Aria-hidden atomic placeholder for preserving expected text, icon, or control geometry while structured content is pending.",
+        "useWhen": [
+          "A pending content region has a predictable structure whose geometry should remain stable while data loads.",
+          "Text, icon, and control placeholder atoms can be composed to approximate the final hierarchy and arrangement.",
+          "The owning region can expose busy state and contextual loading status independently."
+        ],
+        "avoidWhen": [
+          "An action or operation is progressing without predictable content structure; use Loader.",
+          "The final layout is unknown or likely to differ substantially from the placeholder composition.",
+          "A complete card, list, or table preset is expected from one Skeleton; compose atomic shapes in the owner.",
+          "The shimmer would be used as decoration after content is available."
+        ],
+        "alternatives": [
+          {
+            "when": "An indeterminate action or operation is in progress.",
+            "component": "component:ds-loader",
+            "reason": "Loader owns operation-level indeterminate progress."
+          },
+          {
+            "when": "Real text content is already available.",
+            "component": "component:ds-text",
+            "reason": "Text should replace its placeholder as soon as content is ready."
+          },
+          {
+            "when": "A real system glyph is available.",
+            "component": "component:ds-icon",
+            "reason": "Icon renders actual glyph content rather than loading geometry."
+          }
+        ],
+        "commonlyComposedWith": [
+          "component:ds-card",
+          "component:ds-table",
+          "component:ds-text",
+          "component:ds-icon"
+        ],
+        "accessibility": [
+          "Skeleton remains hidden from assistive technology because its shapes do not represent content.",
+          "The owning content region exposes busy state and a contextual loading status when an announcement is needed.",
+          "Do not announce every placeholder atom or duplicate status text across a composed skeleton layout.",
+          "The owner preserves focus and meaningful reading order when replacing placeholders with real content."
+        ],
+        "states": [
+          "Text, icon, and control variants are atomic metric canvases aligned to their corresponding design-system recipes.",
+          "Compose approximate line count, hierarchy, widths, and control placement without simulating actual values.",
+          "Shimmer is on by default and may be disabled for a static placeholder. Reduced motion always produces the static final shape.",
+          "Rounded is an optional visual treatment for icon and control atoms rather than a semantic state.",
+          "Omitted background is for primary and secondary surfaces. Explicit faint documents a faint parent while using the same standard base and shimmer tokens; other contexts use matching surface tokens.",
+          "The owner decides whether to delay initial visibility and when to replace the complete composition."
+        ],
+        "responsiveBehavior": [
+          "The owning layout changes placeholder count, width, visibility, and arrangement to match its real responsive content.",
+          "Skeleton does not infer breakpoints or rearrange sibling atoms."
+        ],
+        "frameworkCaveats": {
+          "customElements": [
+            "Compose one element per placeholder atom and set aria-busy or loading status on the containing content region."
+          ],
+          "react": [
+            "Render Skeleton and real content from one loading branch so placeholder geometry and region busy state settle together."
+          ],
+          "angular": [
+            "Render Skeleton and real content from one loading branch so placeholder geometry and region busy state settle together."
+          ]
+        },
+        "references": [
+          {
+            "label": "Storybook examples",
+            "path": "src/wc/components/Skeleton/Skeleton.stories.ts"
+          }
+        ]
+      },
       "api": {
         "props": {
+          "background": {
+            "type": "SkeletonBackground | undefined",
+            "required": false
+          },
           "controlSize": {
             "type": "ControlSize",
             "required": false
@@ -2486,10 +3128,6 @@
             "type": "boolean",
             "required": false
           },
-          "surface": {
-            "type": "SkeletonSurface",
-            "required": false
-          },
           "textVariant": {
             "type": "TextVariant",
             "required": false
@@ -2738,66 +3376,91 @@
       "tag": "ds-tab-group",
       "name": "tab-group",
       "title": "TabGroup",
-      "summary": "Horizontal or vertical tab list with roving keyboard focus and optional dividers between tab groups.",
-      "intentStatus": "migration-pending",
-      "intent": null,
-      "api": {
-        "props": {
-          "ariaLabel": {
-            "type": "string | null",
-            "required": false
-          },
-          "ariaLabelledby": {
-            "type": "string | undefined",
-            "required": false
-          },
-          "background": {
-            "type": "TabBackground | undefined",
-            "required": false
+      "summary": "Horizontal single-selection tabs for switching adjacent local views or view modes, with uniform label, icon, or icon-label presentation and surface-aware selection.",
+      "intentStatus": "complete",
+      "intent": {
+        "audience": "general",
+        "status": "stable",
+        "summary": "Horizontal single-selection tabs for switching adjacent local views or view modes, with uniform label, icon, or icon-label presentation and surface-aware selection.",
+        "useWhen": [
+          "Adjacent local content views or panels fit in a horizontal tab row.",
+          "A compact horizontal selector switches between equivalent local view modes such as list and grid.",
+          "A tab set needs concise labels, icons, or icon-label content with optional supplemental notification dots."
+        ],
+        "avoidWhen": [
+          "The choices navigate application routes; use PanelNav or BarNav instead.",
+          "The choices belong in a vertical panel or card side rail; use PanelSubNav instead.",
+          "The choices are temporary commands or contextual options; use Menu instead.",
+          "The row requires mixed content variants, subtext, nested levels, or multi-row wrapping.",
+          "No enabled tab can remain selected while enabled choices exist."
+        ],
+        "alternatives": [
+          {
+            "when": "Local views need persistent vertical side-rail navigation.",
+            "component": "component:ds-panel-sub-nav",
+            "reason": "PanelSubNav owns the vertical local-view keyboard and selection model."
           },
-          "orientation": {
-            "type": "'horizontal' | 'vertical'",
-            "required": false
+          {
+            "when": "The choices are primary application destinations.",
+            "component": "component:ds-panel-nav",
+            "reason": "PanelNav owns application route selection in shell navigation."
           },
-          "tabs": {
-            "type": "TabItem[]",
-            "required": false
+          {
+            "when": "The choices are secondary application route sections.",
+            "component": "component:ds-bar-nav",
+            "reason": "BarNav owns route sections, overflow, and shell coordination."
           },
-          "value": {
-            "type": "string",
-            "required": false
+          {
+            "when": "The choices are transient actions or options.",
+            "component": "component:ds-menu",
+            "reason": "Menu owns temporary popup collections rather than persistent local views."
           }
+        ],
+        "commonlyComposedWith": [
+          "component:ds-text",
+          "component:ds-icon"
+        ],
+        "accessibility": [
+          "Provide an accessible tab-list name with aria-label or aria-labelledby.",
+          "Keep exactly one valid enabled tab selected whenever enabled tabs exist, and keep its controlled view synchronized.",
+          "When tabs control tabpanels, give each tab the id of its panel and label each panel from its tab.",
+          "ArrowLeft and ArrowRight move and activate selection; Home and End select the first and last available tabs.",
+          "Icon-only tabs retain their required text label as the accessible name even though the label is not visible.",
+          "Notification dots are supplemental status only and must never replace a label, state, or accessible name.",
+          "Inactive tabs remain visible but cannot be focused or selected."
+        ],
+        "states": [
+          "The parent owns the canonical selected value and adjacent view visibility, and should update both from dsChange.",
+          "A missing, empty, inactive, or unknown selected value is invalid when enabled tabs exist; the component does not choose a fallback selection.",
+          "Selection is singular and follows keyboard focus.",
+          "Use one consistent content variant across every selectable tab in a group.",
+          "Omitted background is for primary and secondary surfaces; pass the faint context explicitly on faint surfaces.",
+          "Only the omitted default context emphasizes visible selected label text and keeps the filled track; explicit faint follows the other surface contexts with a transparent track, stable text weight, surface border, and neutral active fill.",
+          "Dividers visually separate related subsets inside one tab list but do not create nested navigation or independent selection groups."
+        ],
+        "responsiveBehavior": [
+          "The component remains a single horizontal row and does not become vertical or wrap.",
+          "The consuming layout owns narrow-width placement and overflow, or replaces the row with a more suitable navigation pattern."
+        ],
+        "frameworkCaveats": {
+          "customElements": [
+            "Assign tabs as a JavaScript property because structured arrays are not represented by HTML attributes.",
+            "Use one item variant consistently, keep value synchronized to an enabled item, and update controlled content from dsChange."
+          ],
+          "react": [
+            "Pass tabs as an array through the generated wrapper, keep value controlled, and use onDsChange to synchronize the visible view."
+          ],
+          "angular": [
+            "Bind tabs and a valid value as properties, and handle dsChange to synchronize the visible view."
+          ]
         },
-        "events": [
+        "references": [
           {
-            "name": "dsChange",
-            "detail": "string"
+            "label": "Storybook examples",
+            "path": "src/wc/components/TabGroup/TabGroup.stories.ts"
           }
-        ],
-        "slots": []
-      },
-      "exports": {
-        "customElement": "ds-tab-group",
-        "react": "DsTabGroup",
-        "angular": "DsTabGroup"
+        ]
       },
-      "dependencies": [
-        "@ds-mo/ui",
-        "@ds-mo/tokens"
-      ],
-      "componentDependencies": [
-        "badge",
-        "text"
-      ]
-    },
-    {
-      "id": "component:ds-tab-group-nav",
-      "tag": "ds-tab-group-nav",
-      "name": "tab-group-nav",
-      "title": "TabGroupNav",
-      "summary": "Navigation-style tab list for primary and secondary navigation surfaces.",
-      "intentStatus": "migration-pending",
-      "intent": null,
       "api": {
         "props": {
           "ariaLabel": {
@@ -2809,23 +3472,11 @@
             "required": false
           },
           "background": {
-            "type": "TabGroupNavBackground | undefined",
-            "required": false
-          },
-          "orientation": {
-            "type": "'horizontal' | 'vertical'",
-            "required": false
-          },
-          "rovingEnabled": {
-            "type": "boolean",
-            "required": false
-          },
-          "selectionFollowsFocus": {
-            "type": "boolean",
+            "type": "TabBackground | undefined",
             "required": false
           },
           "tabs": {
-            "type": "TabItem[]",
+            "type": "TabGroupItem[]",
             "required": false
           },
           "value": {
@@ -2837,25 +3488,23 @@
           {
             "name": "dsChange",
             "detail": "string"
-          },
-          {
-            "name": "dsRovingExit",
-            "detail": "'start' | 'end'"
           }
         ],
         "slots": []
       },
       "exports": {
-        "customElement": "ds-tab-group-nav",
-        "react": "DsTabGroupNav",
-        "angular": "DsTabGroupNav"
+        "customElement": "ds-tab-group",
+        "react": "DsTabGroup",
+        "angular": "DsTabGroup"
       },
       "dependencies": [
         "@ds-mo/ui",
-        "@ds-mo/tokens"
+        "@ds-mo/tokens",
+        "@ds-mo/icons"
       ],
       "componentDependencies": [
         "badge",
+        "icon",
         "text"
       ]
     },
@@ -2957,19 +3606,117 @@
       "tag": "ds-tag",
       "name": "tag",
       "title": "Tag",
-      "summary": "Static metadata label with intent coloring and optional icon support. Uses control-density recipes for md/sm/xs.",
-      "intentStatus": "migration-pending",
-      "intent": null,
+      "summary": "Compact metadata or semantic-status label on primary surfaces, optionally rendered as a controlled menu trigger with leading and fixed suffix icons.",
+      "intentStatus": "complete",
+      "intent": {
+        "audience": "general",
+        "status": "stable",
+        "summary": "Compact metadata or semantic-status label on primary surfaces, optionally rendered as a controlled menu trigger with leading and fixed suffix icons.",
+        "useWhen": [
+          "A value needs a compact static metadata or category label.",
+          "A status needs persistent semantic color and visible text without interaction.",
+          "Product affiliation or AI-generated content needs an explicit labelled marker.",
+          "A compact metadata value opens a related menu and needs a native button with controlled popup state."
+        ],
+        "avoidWhen": [
+          "The value must be individually removable; use Chip.",
+          "The element triggers an action other than opening a related menu; use the appropriate button or link.",
+          "The element represents persistent selection or a toggle; use a control whose active state owns that meaning.",
+          "A count or notification dot supplements another control; use Badge.",
+          "The tag would be placed on a non-primary parent surface."
+        ],
+        "alternatives": [
+          {
+            "when": "A metadata value is individually removable.",
+            "component": "component:ds-chip",
+            "reason": "Chip owns dismiss interaction and parent-managed removal."
+          },
+          {
+            "when": "A compact mark communicates unread count or notification presence.",
+            "component": "component:ds-badge",
+            "reason": "Badge owns supplemental notification indicators."
+          },
+          {
+            "when": "The compact element triggers a non-menu action or toggle.",
+            "component": "component:ds-button-unfilled",
+            "reason": "ButtonUnfilled owns general actions, focus, and active state."
+          }
+        ],
+        "commonlyComposedWith": [
+          "component:ds-card",
+          "component:ds-table",
+          "component:ds-text",
+          "component:ds-icon"
+        ],
+        "accessibility": [
+          "The visible label provides Tag's accessible name; a separate aria-label is normally unnecessary.",
+          "Leading icons reinforce the visible label and remain decorative. The fixed ChevronUpDown suffix is always decorative.",
+          "Static Tag stays outside the tab order. Interactive Tag renders a native button with menu popup semantics.",
+          "The owner controls expanded state, associates the menu with aria-controls when available, and moves focus according to the Menu contract.",
+          "Do not communicate semantic intent by color alone; the label must remain understandable without color."
+        ],
+        "states": [
+          "Intent describes the represented value's semantic meaning, never selection or interaction state.",
+          "Neutral is ordinary metadata; brand marks Motive or product affiliation; AI marks AI-generated or AI-assisted content; positive, caution, warning, and negative communicate increasingly specific status meaning.",
+          "Warning signals higher urgency or risk than caution, which asks for attention before a possible issue.",
+          "Contrast changes visual prominence without changing semantic intent or parent surface context.",
+          "Rounded is an optional visual style with no semantic difference.",
+          "Labels stay on one line and truncate only when the owner supplies a maximum width.",
+          "Omitted interactive renders static metadata with no focus, event, or suffix. Interactive adds the fixed ChevronUpDown suffix and emits dsClick without toggling expanded internally.",
+          "isInactive disables only the interactive button and applies the shared inactive treatment."
+        ],
+        "responsiveBehavior": [
+          "The owner selects md, sm, or xs density to match its local layout and owns collection wrapping, overflow, and condensation.",
+          "Tag does not change size or behavior automatically at breakpoints."
+        ],
+        "frameworkCaveats": {
+          "customElements": [
+            "Listen for dsClick to open the associated menu, then update expanded as controlled state. Use the Tag host ID as the menu anchor when required."
+          ],
+          "react": [
+            "Use a stable key and parent-owned layout for Tag collections. For interactive Tag, synchronize expanded and the associated menu from the same state."
+          ],
+          "angular": [
+            "Use parent-owned layout for Tag collections. For interactive Tag, synchronize expanded and the associated menu from the same state."
+          ]
+        },
+        "references": [
+          {
+            "label": "Storybook examples",
+            "path": "src/wc/components/Tag/Tag.stories.ts"
+          }
+        ]
+      },
       "api": {
         "props": {
+          "ariaControls": {
+            "type": "string | undefined",
+            "required": false
+          },
           "contrast": {
             "type": "TagContrast",
             "required": false
           },
+          "expanded": {
+            "type": "boolean",
+            "required": false
+          },
+          "icon": {
+            "type": "string",
+            "required": false
+          },
           "intent": {
             "type": "TagIntent",
             "required": false
           },
+          "interactive": {
+            "type": "boolean",
+            "required": false
+          },
+          "isInactive": {
+            "type": "boolean",
+            "required": false
+          },
           "label": {
             "type": "string",
             "required": true
@@ -2987,7 +3734,12 @@
             "required": false
           }
         },
-        "events": [],
+        "events": [
+          {
+            "name": "dsClick",
+            "detail": "MouseEvent"
+          }
+        ],
         "slots": []
       },
       "exports": {
@@ -2997,9 +3749,11 @@
       },
       "dependencies": [
         "@ds-mo/ui",
-        "@ds-mo/tokens"
+        "@ds-mo/tokens",
+        "@ds-mo/icons"
       ],
       "componentDependencies": [
+        "icon",
         "text"
       ]
     },
@@ -3008,9 +3762,86 @@
       "tag": "ds-text",
       "name": "text",
       "title": "Text",
-      "summary": "Typography primitive supporting all design-system text variants, colors, truncation, wrapping, and optional loading shimmer.",
-      "intentStatus": "migration-pending",
-      "intent": null,
+      "summary": "Semantic plain UI text with atomic tokenized typography recipes, measurable line boxes, and composition-owned wrapping and truncation.",
+      "intentStatus": "complete",
+      "intent": {
+        "audience": "general",
+        "status": "stable",
+        "summary": "Semantic plain UI text with atomic tokenized typography recipes, measurable line boxes, and composition-owned wrapping and truncation.",
+        "useWhen": [
+          "Plain UI text needs a complete design-system typography recipe.",
+          "Headings, paragraphs, labels, or inline phrasing need native HTML semantics independent from their visual scale.",
+          "A component needs a stable measurable text box aligned to shared typography metrics.",
+          "Changing numeric values need tabular glyph widths."
+        ],
+        "avoidWhen": [
+          "Content is markdown, rich prose, or an arbitrary nested document structure.",
+          "The element is interactive; use the correct native or design-system control and compose Text only for its label.",
+          "Individual font metrics must be overridden instead of selecting an existing complete variant.",
+          "Typography alone would be used to repair an incorrect heading hierarchy."
+        ],
+        "alternatives": [
+          {
+            "when": "Predictable text geometry is pending while content loads.",
+            "component": "component:ds-skeleton",
+            "reason": "Skeleton owns aria-hidden loading geometry aligned to Text line metrics."
+          },
+          {
+            "when": "Compact static metadata or semantic status needs a contained treatment.",
+            "component": "component:ds-tag",
+            "reason": "Tag owns compact labelled metadata and intent surfaces."
+          }
+        ],
+        "commonlyComposedWith": [
+          "component:ds-icon",
+          "component:ds-card",
+          "component:ds-field",
+          "component:ds-button-filled"
+        ],
+        "accessibility": [
+          "Choose the native element from document meaning and hierarchy; choose the visual variant independently.",
+          "Composition authors preserve logical h1–h6 order regardless of visual size.",
+          "Visible content and the selected native element provide accessible meaning; avoid redundant roles and labels.",
+          "Use label semantics and its for association only for a real form control.",
+          "When truncating essential content, the owner provides an accessible way to obtain the omitted text.",
+          "Use solid underline only when Text is composed inside a real link.",
+          "Use dotted underline to signal hidden or supplemental interaction such as a tooltip; the owning trigger must provide focus, keyboard interaction, and accessible tooltip semantics."
+        ],
+        "states": [
+          "A variant is atomic: font size, line height, weight, and letter spacing stay together and are not overridden by consumers.",
+          "Emphasis selects the supported stronger recipe for local hierarchy; it does not independently mean selected or active.",
+          "Omitted color inherits currentColor. Explicit semantic aliases or CSS-variable references are used only when Text has an independent color role.",
+          "Line truncation and wrapping require an owner-supplied width constraint and content-aware composition decision.",
+          "Solid underline communicates a real link; dotted underline communicates hidden or supplemental interaction such as a tooltip. Decoration does not make Text interactive by itself.",
+          "Tabular numbers are for changing numeric values or aligned numeric columns where stable glyph width matters.",
+          "Shimmer is reserved for visible generating/loading status text whose owner provides status semantics; reduced motion keeps static readable text."
+        ],
+        "responsiveBehavior": [
+          "The composition owns width, wrapping, truncation, alignment, and any responsive variant change.",
+          "Text preserves complete token recipes and does not scale fluidly or infer breakpoints."
+        ],
+        "frameworkCaveats": {
+          "customElements": [
+            "Set as explicitly for inline text, headings, and labels; omitted as renders a paragraph."
+          ],
+          "react": [
+            "Keep semantic as choices aligned with the rendered document hierarchy rather than component styling."
+          ],
+          "angular": [
+            "Use the for prop only when Text renders a label associated with a real control ID."
+          ]
+        },
+        "references": [
+          {
+            "label": "Storybook examples",
+            "path": "src/wc/components/Text/Text.stories.ts"
+          },
+          {
+            "label": "Typography contract",
+            "path": "AGENTS.md"
+          }
+        ]
+      },
       "api": {
         "props": {
           "align": {
@@ -3022,7 +3853,7 @@
             "required": false
           },
           "color": {
-            "type": "TextColor | undefined",
+            "type": "TextColor",
             "required": false
           },
           "decoration": {