@ds-mo/ui 8.1.0 → 8.2.0

package/dist/agent.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": "1.0.0",
   "package": "@ds-mo/ui",
-  "packageVersion": "8.1.0",
+  "packageVersion": "8.2.0",
   "kind": "components",
   "entries": [
     {
@@ -521,7 +521,7 @@
           "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.",
-          "Loading keeps the action's accessible name and exposes busy state; announce broader operation progress from the owning workflow when users need confirmation.",
+          "Loading keeps the action focused and named, exposes busy and disabled state, and blocks activation; 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": [
@@ -529,7 +529,7 @@
           "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.",
           "Rounded changes only the control radius to the half-radius treatment; it does not change hierarchy, size, variant, intent, or interaction semantics.",
-          "Loading prevents duplicate activation without applying inactive opacity.",
+          "Loading prevents duplicate activation without applying inactive opacity or removing the current keyboard focus.",
           "Icon and icon-label loading replace the icon in place. Label-only loading centers the loader while preserving the button's measured width."
         ],
         "responsiveBehavior": [
@@ -676,7 +676,7 @@
           "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.",
+          "Loading keeps the action focused and named, exposes busy and disabled state, and blocks activation; 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."
         ],
@@ -685,7 +685,7 @@
           "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.",
+          "Loading prevents duplicate activation without applying inactive opacity or removing the current keyboard focus.",
           "Rounded changes only the control radius to the half-radius treatment; it does not change hierarchy, size, variant, or interaction semantics.",
           "Icon and icon-label loading replace the icon in place. Label-only loading centers the loader while preserving the button's measured width."
         ],
@@ -747,7 +747,7 @@
             "required": false
           },
           "haspopup": {
-            "type": "string | undefined",
+            "type": "ButtonUnfilledPopup | undefined",
             "required": false
           },
           "icon": {
@@ -1198,8 +1198,8 @@
         "alternatives": [
           {
             "when": "Exactly one option must be chosen from a mutually exclusive set.",
-            "component": "component:ds-radio-group",
-            "reason": "RadioGroup communicates one-of-many selection."
+            "component": "component:ds-radio",
+            "reason": "Radio communicates one-of-many selection."
           },
           {
             "when": "A binary setting takes effect immediately.",
@@ -1224,7 +1224,7 @@
           "Use presentation mode only inside a composite option that owns selection semantics, focus, and interaction."
         ],
         "states": [
-          "Every box keeps a 1px inset secondary border and 2px radius, including when selected. Checked renders the box-sized Check icon and indeterminate renders the box-sized Subtract icon on a brand fill.",
+          "Unchecked boxes use a tertiary-foreground inset stroke: 1.25px at md, 1px at sm, and 0.75px at xs. Selected and mixed boxes remove the border, use a brand fill, and draw a component-owned check or subtract mark at the same density-specific stroke width.",
           "Activating an indeterminate checkbox clears the mixed state, toggles checked, and emits dsChange with the resulting boolean.",
           "The initial checked and indeterminate values are restored by native form reset; checked values submit under name and unchecked values submit nothing.",
           "Sizes are md with a 16px box in a 20px placement, sm with a 12px box in a 16px placement, and xs with an 8px box in a 12px placement.",
@@ -1319,11 +1319,9 @@
       },
       "dependencies": [
         "@ds-mo/ui",
-        "@ds-mo/tokens",
-        "@ds-mo/icons"
+        "@ds-mo/tokens"
       ],
       "componentDependencies": [
-        "icon",
         "text"
       ]
     },
@@ -1686,11 +1684,89 @@
       "tag": "ds-field",
       "name": "field",
       "title": "Field",
-      "summary": "Simple label wrapper that links to child input via htmlFor.",
-      "intentStatus": "migration-pending",
-      "intent": null,
+      "summary": "Accessible form-field composition that gives one Input or Select a persistent label, optional guidance, shared error presentation, stable IDs, and observable interaction state.",
+      "intentStatus": "complete",
+      "intent": {
+        "audience": "general",
+        "status": "stable",
+        "summary": "Accessible form-field composition that gives one Input or Select a persistent label, optional guidance, shared error presentation, stable IDs, and observable interaction state.",
+        "useWhen": [
+          "An Input, Select, or SelectMulti needs a persistent visible label in a form.",
+          "Help text or an error message must be programmatically associated with one control.",
+          "A form layout needs one consistent label-control-message rhythm."
+        ],
+        "avoidWhen": [
+          "The component already owns its visible label and complete selection semantics, such as Checkbox, Radio, or Switch.",
+          "Several controls belong to one question; use a semantic fieldset and legend instead.",
+          "Text describes a region or group rather than one form control."
+        ],
+        "alternatives": [
+          {
+            "when": "Several related controls answer one question.",
+            "component": "component:ds-text",
+            "reason": "Use native fieldset and legend semantics, then compose Text only for supporting content."
+          }
+        ],
+        "commonlyComposedWith": [
+          "component:ds-input",
+          "component:ds-select",
+          "component:ds-select-multi",
+          "component:ds-text"
+        ],
+        "accessibility": [
+          "Slot exactly one form control. Field assigns its stable control ID and connects the visible label automatically.",
+          "Description and rendered error IDs are merged with any authored aria-describedby references rather than replacing them.",
+          "The error prop forwards aria-invalid and supported design-system control error styling; put visible error text on Field, not again on the child control.",
+          "Clicking the label focuses the slotted design-system control without opening a Select popup.",
+          "Do not use placeholder text as the only label. Keep label text concise and put format or consequence guidance in description."
+        ],
+        "states": [
+          "Field exposes data-focused, data-filled, data-dirty, data-touched, data-invalid, data-disabled, and data-required hooks while the slotted control remains the source of value and interaction behavior.",
+          "Description remains visible during error so guidance and validation do not replace each other.",
+          "Field owns validation presentation but not validation timing; the form decides when to set error and errorMessage.",
+          "The label uses primary body-small emphasis, description uses secondary body-small text, and error uses negative body-small text."
+        ],
+        "responsiveBehavior": [
+          "Field fills the width supplied by its parent and makes the slotted control fill that field width.",
+          "The form layout owns column count, wrapping, and responsive placement; Field keeps the vertical label-control-message composition intact."
+        ],
+        "frameworkCaveats": {
+          "customElements": [
+            "Set fieldId only when another element must reference a predictable control ID; otherwise use the generated association.",
+            "Assign child component values and option arrays through their normal JavaScript properties."
+          ],
+          "react": [
+            "Compose one DsInput, DsSelect, or DsSelectMulti child and control validation timing in the form owner."
+          ],
+          "angular": [
+            "Compose the generated Field adapter around the control adapter and its matching Angular value accessor."
+          ]
+        },
+        "references": [
+          {
+            "label": "Storybook examples",
+            "path": "src/wc/components/Field/Field.stories.ts"
+          },
+          {
+            "label": "Cross-browser form and accessibility coverage",
+            "path": "tests/e2e/forms.spec.ts"
+          }
+        ]
+      },
       "api": {
         "props": {
+          "description": {
+            "type": "string | undefined",
+            "required": false
+          },
+          "error": {
+            "type": "boolean",
+            "required": false
+          },
+          "errorMessage": {
+            "type": "string | undefined",
+            "required": false
+          },
           "fieldId": {
             "type": "string | undefined",
             "required": false
@@ -1765,11 +1841,13 @@
           "Icons are decorative by default and remain hidden from assistive technology when visible text or an owning control already communicates the meaning.",
           "The owning button, link, or composite control provides the accessible name; do not repeat that name on its nested Icon.",
           "Provide an explicit label only when the non-interactive icon itself communicates otherwise unavailable meaning.",
+          "Tertiary and quaternary foregrounds are restricted to icons inside genuinely inactive or disabled UI, or to purely decorative icons; quaternary is the fainter tier, and informative icons and meaningful status graphics retain sufficient rendered contrast even when aria-hidden.",
           "Informative flags require an explicit localized country or region label; never derive accessible text from the export name.",
           "Icon never receives focus or owns interaction."
         ],
         "states": [
           "Omitted color inherits currentColor from the owning context. Explicit semantic aliases and CSS-variable references are available when the icon has an independent color role.",
+          "Prefer the owning control's isInactive or native disabled state over manually selecting tertiary or quaternary so visual treatment and inactive semantics remain synchronized.",
           "Built-in glyph lookup accepts exact canonical IcoMo export names only. Names beginning with Flag select the flag catalog automatically.",
           "A cache miss lazy-loads into a fixed-size box without layout shift. Unknown names, failed loads, and rejected markup leave that box empty.",
           "Critical first-paint glyphs may be pre-registered before rendering; all resolved glyphs share a global cache.",
@@ -1840,9 +1918,89 @@
       "tag": "ds-input",
       "name": "input",
       "title": "Input",
-      "summary": "Text input supporting text, email, tel, url, search, and password types. Search type includes auto clear button.",
-      "intentStatus": "migration-pending",
-      "intent": null,
+      "summary": "Form-associated single-line text field for primary and secondary application backgrounds, with native text input behavior, three control densities, optional leading and trailing content, search clearing, and validation.",
+      "intentStatus": "complete",
+      "intent": {
+        "audience": "general",
+        "status": "stable",
+        "summary": "Form-associated single-line text field for primary and secondary application backgrounds, with native text input behavior, three control densities, optional leading and trailing content, search clearing, and validation.",
+        "useWhen": [
+          "A user must enter or edit one line of text, an email address, telephone number, URL, search query, or password.",
+          "The value must participate in native, Angular, or React form state.",
+          "A compact filter or toolbar needs a single-line search field that follows the shared control-density recipe."
+        ],
+        "avoidWhen": [
+          "The user chooses from a finite set of known values.",
+          "The user must enter multiple paragraphs or formatted content.",
+          "The value is adjusted primarily by dragging within a numeric range."
+        ],
+        "alternatives": [
+          {
+            "when": "The value comes from a finite set of known choices.",
+            "component": "component:ds-select",
+            "reason": "Select exposes the available values and owns listbox selection behavior."
+          },
+          {
+            "when": "The value is an immediate on/off setting.",
+            "component": "component:ds-switch",
+            "reason": "Switch communicates a binary setting instead of free text entry."
+          },
+          {
+            "when": "The value is chosen from a bounded numeric range.",
+            "component": "component:ds-slider",
+            "reason": "Slider supports direct range adjustment and communicates the current position."
+          }
+        ],
+        "commonlyComposedWith": [
+          "component:ds-field",
+          "component:ds-icon",
+          "component:ds-text"
+        ],
+        "accessibility": [
+          "Provide a persistent visible label through the owning field or an external native label; placeholder text is guidance and must not be the field's only label.",
+          "Choose the native input type that matches the value so browsers and assistive technology can provide appropriate semantics and keyboards.",
+          "Error text is associated with the native input and announced as an alert when the invalid state is rendered.",
+          "Read-only fields remain focusable and submittable while preventing edits; inactive or disabled fields leave the tab order and are omitted from form submission.",
+          "Suffix content must not carry information that is otherwise absent from the field's visible label, value, or description."
+        ],
+        "states": [
+          "The normal field boundary uses the shared secondary inset border. Focus promotes it to the thicker bold-brand inset stroke, while error uses the thicker bold-negative inset stroke without changing geometry.",
+          "Placeholder text is secondary at rest and quaternary while the editable field is focused because it becomes decorative once typing begins.",
+          "Entered values use the parent surface's primary foreground; prefix icons, suffix content, and resting placeholder text use its secondary foreground.",
+          "Search fields show a standard borderless CrossCircle icon action only while they contain a value. Clearing emits the empty value and restores focus to the native field.",
+          "The suffix slot is for compact units or decorations. The optional leading icon is decorative and does not replace the field label.",
+          "Use autoComplete, inputMode, and enterKeyHint to provide browser and virtual-keyboard hints without changing the value's semantic type.",
+          "The host exposes focused, filled, dirty, touched, invalid, disabled, read-only, and required data attributes for Field integration and diagnostics.",
+          "Use Input only on primary or secondary application backgrounds. It intentionally does not expose alternate surface contexts."
+        ],
+        "responsiveBehavior": [
+          "Form fields normally fill their parent; use hug width only in a compact toolbar or filter layout with an explicit width constraint.",
+          "Choose density from the containing layout: md for ordinary forms, sm or xs only where the surrounding controls use the same compact recipe.",
+          "The owner supplies layout constraints and decides when a compact field moves to its own row."
+        ],
+        "frameworkCaveats": {
+          "customElements": [
+            "Listen for dsChange for user edits and dsClear for the search clear action.",
+            "Use the form attribute on the host when associating an input rendered outside its owning form."
+          ],
+          "react": [
+            "Use DsInput, bind value for controlled application state, and handle onDsChange and onDsClear."
+          ],
+          "angular": [
+            "Import DsInput with TextValueAccessor when integrating with Angular Forms."
+          ]
+        },
+        "references": [
+          {
+            "label": "Storybook examples",
+            "path": "src/wc/components/Input/Input.stories.ts"
+          },
+          {
+            "label": "Cross-browser form and accessibility coverage",
+            "path": "tests/e2e/forms.spec.ts"
+          }
+        ]
+      },
       "api": {
         "props": {
           "ariaDescribedby": {
@@ -1857,6 +2015,10 @@
             "type": "string | undefined",
             "required": false
           },
+          "autoComplete": {
+            "type": "string | undefined",
+            "required": false
+          },
           "autoFocus": {
             "type": "boolean",
             "required": false
@@ -1869,6 +2031,10 @@
             "type": "boolean",
             "required": false
           },
+          "enterKeyHint": {
+            "type": "string",
+            "required": false
+          },
           "error": {
             "type": "boolean",
             "required": false
@@ -1877,10 +2043,26 @@
             "type": "string | undefined",
             "required": false
           },
+          "form": {
+            "type": "string | undefined",
+            "required": false
+          },
+          "hasBorder": {
+            "type": "boolean",
+            "required": false
+          },
+          "icon": {
+            "type": "string | undefined",
+            "required": false
+          },
           "inputId": {
             "type": "string | undefined",
             "required": false
           },
+          "inputMode": {
+            "type": "string",
+            "required": false
+          },
           "isInactive": {
             "type": "boolean",
             "required": false
@@ -1893,6 +2075,10 @@
             "type": "string | undefined",
             "required": false
           },
+          "readOnly": {
+            "type": "boolean",
+            "required": false
+          },
           "required": {
             "type": "boolean",
             "required": false
@@ -1901,6 +2087,10 @@
             "type": "string",
             "required": false
           },
+          "size": {
+            "type": "InputSize",
+            "required": false
+          },
           "type": {
             "type": "InputType",
             "required": false
@@ -1908,6 +2098,10 @@
           "value": {
             "type": "string",
             "required": false
+          },
+          "width": {
+            "type": "InputWidth",
+            "required": false
           }
         },
         "events": [
@@ -1929,9 +2123,12 @@
       },
       "dependencies": [
         "@ds-mo/ui",
-        "@ds-mo/tokens"
+        "@ds-mo/tokens",
+        "@ds-mo/icons"
       ],
       "componentDependencies": [
+        "button-unfilled",
+        "icon",
         "text"
       ]
     },
@@ -1978,12 +2175,14 @@
         "accessibility": [
           "When Loader is nested in a busy button, field, or region, keep it unnamed and expose busy state from the owner.",
           "Standalone Loader requires contextual status text that explains what is loading; do not rely on a generic visual spinner alone.",
+          "Loader is an informative progress graphic and must retain sufficient rendered contrast; tertiary and quaternary are not supported standalone or informative Loader treatments.",
           "Avoid duplicate announcements from both Loader and its owning busy region.",
           "Reduced motion stops rotation while keeping the glyph and status semantics visible."
         ],
         "states": [
           "Loader communicates indeterminate progress only and does not emit completion or failure events.",
           "Omitted color inherits currentColor. Explicit semantic aliases and CSS-variable references match Icon when an independent progress color is required.",
+          "Nested Loader inherits a readable color from its owning busy control or region rather than selecting tertiary or quaternary directly.",
           "The owner decides whether to delay Loader visibility for short operations and removes it when the operation settles.",
           "The owner reserves space and supplies centering or overlay layout so Loader never causes unexpected layout movement."
         ],
@@ -2085,7 +2284,8 @@
           "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 presentation indicator.",
+          "Switch rows use menuitemcheckbox semantics on the row; the nested ds-switch is an aria-hidden md presentation indicator.",
+          "A gradient-picker section changes the popup to a non-modal dialog so its radio group and ordinary preference buttons keep valid nested semantics; Tab moves between its controls, then leaves and closes at the popup boundary.",
           "Use notification dots only as supplemental status and not as the sole indication of important information."
         ],
         "states": [
@@ -2093,7 +2293,7 @@
           "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 menu for the global AppShell wash preference; apply dsGradientSelect immediately without closing the menu."
+          "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."
         ],
         "responsiveBehavior": [
           "Choose placement relative to the trigger and allow the component to clamp the popup to the viewport.",
@@ -2370,6 +2570,7 @@
           "Provide localized dashboard, settings, account, navigation, collapse, and expand labels.",
           "Preserve accessible destination names when the panel is collapsed to icon-only presentation.",
           "Use notification dots as supplemental status and never as the only indication of important information.",
+          "When the destination body overflows, it becomes a localized keyboard-focusable scroll region in addition to the roving destination controls.",
           "Keep the standard dashboard/settings switch and user/account entry available in the footer."
         ],
         "states": [
@@ -2470,6 +2671,10 @@
             "type": "NavChromeStyle",
             "required": false
           },
+          "navigationItemsLabel": {
+            "type": "string",
+            "required": false
+          },
           "routerMode": {
             "type": "PanelNavRouterMode",
             "required": false
@@ -2834,13 +3039,86 @@
       ]
     },
     {
-      "id": "component:ds-radio-group",
-      "tag": "ds-radio-group",
-      "name": "radio-group",
-      "title": "RadioGroup",
-      "summary": "Radio selection group with vertical/horizontal layout, per-option inactive state, and keyboard navigation.",
-      "intentStatus": "migration-pending",
-      "intent": null,
+      "id": "component:ds-radio",
+      "tag": "ds-radio",
+      "name": "radio",
+      "title": "Radio",
+      "summary": "Form-associated one-of-many radio selection set with vertical or horizontal layout, three densities, per-option inactive state, and roving keyboard focus.",
+      "intentStatus": "complete",
+      "intent": {
+        "audience": "general",
+        "status": "stable",
+        "summary": "Form-associated one-of-many radio selection set with vertical or horizontal layout, three densities, per-option inactive state, and roving keyboard focus.",
+        "useWhen": [
+          "A user must select exactly one visible option from a small set.",
+          "All available choices should remain visible for comparison.",
+          "A form needs one selected string value with native validation, reset, or external form association."
+        ],
+        "avoidWhen": [
+          "A user may select zero or multiple independent choices.",
+          "A binary setting applies immediately rather than selecting from a set.",
+          "The option list is too long or space-constrained to remain visible."
+        ],
+        "alternatives": [
+          {
+            "when": "A user may select zero or multiple independent choices.",
+            "component": "component:ds-checkbox",
+            "reason": "Checkbox communicates independent selection rather than one-of-many choice."
+          },
+          {
+            "when": "A binary setting applies immediately.",
+            "component": "component:ds-switch",
+            "reason": "Switch communicates an immediately applied on/off setting."
+          },
+          {
+            "when": "The option list is long or the available space is constrained.",
+            "component": "component:ds-select",
+            "reason": "Select keeps a larger one-of-many choice set compact."
+          }
+        ],
+        "commonlyComposedWith": [
+          "component:ds-field",
+          "component:ds-text"
+        ],
+        "accessibility": [
+          "The host exposes radiogroup semantics and requires an accessible group name from aria-label or aria-labelledby.",
+          "Each visible option exposes radio semantics, its checked state, its label text, and any inactive state.",
+          "Arrow keys move and select through active options; Home and End select the first and last active options; Space and Enter select the focused option.",
+          "Roving tabindex keeps one active option in the tab order, preferring the selected option."
+        ],
+        "states": [
+          "Unchecked circles use a tertiary-foreground inset stroke: 1.25px at md, 1px at sm, and 0.75px at xs.",
+          "Selected circles remove the border, use a brand fill, and draw a centered on-bold foreground dot sized 8px at md, 6px at sm, and 4px at xs.",
+          "Sizes are md with a 16px circle in a 20px placement, sm with a 12px circle in a 16px placement, and xs with an 8px circle in a 12px placement.",
+          "The initial value is restored by native form reset; the selected value submits under name and a required set is invalid until one active option is selected."
+        ],
+        "responsiveBehavior": [
+          "Choose size from the density of the containing form or settings row.",
+          "Prefer vertical layout when labels may wrap or horizontal space is constrained; horizontal layout is appropriate for short labels in a small set."
+        ],
+        "frameworkCaveats": {
+          "customElements": [
+            "Assign options as a JavaScript property, set value as a property for application state updates, and listen for dsChange.",
+            "Use the form attribute on the host when associating a radio set rendered outside its owning form."
+          ],
+          "react": [
+            "Use DsRadio, pass options as an array, and handle onDsChange; value is mutable and updates after user selection."
+          ],
+          "angular": [
+            "Use DsRadio with options and value bindings plus dsChange, or import the generated radio value accessor with the component adapter."
+          ]
+        },
+        "references": [
+          {
+            "label": "Storybook examples",
+            "path": "src/wc/components/Radio/Radio.stories.ts"
+          },
+          {
+            "label": "Cross-browser form and accessibility coverage",
+            "path": "tests/e2e/forms.spec.ts"
+          }
+        ]
+      },
       "api": {
         "props": {
           "ariaLabel": {
@@ -2859,6 +3137,10 @@
             "type": "boolean",
             "required": false
           },
+          "form": {
+            "type": "string | undefined",
+            "required": false
+          },
           "isInactive": {
             "type": "boolean",
             "required": false
@@ -2879,6 +3161,10 @@
             "type": "string",
             "required": false
           },
+          "size": {
+            "type": "RadioSize",
+            "required": false
+          },
           "value": {
             "type": "string",
             "required": false
@@ -2893,9 +3179,9 @@
         "slots": []
       },
       "exports": {
-        "customElement": "ds-radio-group",
-        "react": "DsRadioGroup",
-        "angular": "DsRadioGroup"
+        "customElement": "ds-radio",
+        "react": "DsRadio",
+        "angular": "DsRadio"
       },
       "dependencies": [
         "@ds-mo/ui",
@@ -2940,8 +3226,8 @@
           },
           {
             "when": "A small set of choices should remain visible.",
-            "component": "component:ds-radio-group",
-            "reason": "Prefer RadioGroup for roughly two to five mutually exclusive choices when the available space allows all choices to remain visible."
+            "component": "component:ds-radio",
+            "reason": "Prefer Radio for roughly two to five mutually exclusive choices when the available space allows all choices to remain visible."
           }
         ],
         "commonlyComposedWith": [
@@ -2971,8 +3257,8 @@
           "When any option supplies subtext, every row uses the same subtext structure and missing values render an em dash. Subtext should disambiguate or add decision-helpful information.",
           "Option labels and the selected trigger label stay on one line and truncate when constrained. Option subtext may wrap to at most two lines.",
           "The optional prefix icon and chevron always use the parent surface's secondary foreground color, including when a selected value promotes the label to primary.",
-          "The shared popup search control stays md at every trigger size, using body-medium text, a 20px icon, and the same internal spacing as a borderless Select trigger. Its container uses menu-item padding on every side and owns a 1px bottom divider that becomes a 1.5px bold-brand stroke while search has focus. Search placeholder text is secondary at rest and quaternary while focused.",
-          "When search contains text, the shared control shows a rounded sm icon-only ButtonUnfilled with the Cross icon and no border. It clears the local term, stays hidden for an empty term, and returns focus to search.",
+          "The shared popup search control stays md at every trigger size, using body-medium text, a 20px icon, and the same internal spacing as a borderless Select trigger. Its container uses menu-item padding on every side and owns a 1px bottom divider that becomes a 1.5px bold-brand stroke while search has focus. Search placeholder text is secondary at rest and quaternary while focused because it becomes decorative once the editable field is active.",
+          "When search contains text, the shared control shows a rounded sm icon-only ButtonUnfilled with the CrossCircle icon and no border. It clears the local term, stays hidden for an empty term, and returns focus to search.",
           "The shared clear footer mirrors the search region's sizing: menu-item padding surrounds an md-height borderless row, and the Clear label uses the same row and label insets as option text. The outer footer owns a 1px top divider.",
           "An empty filtered list composes the message-only body variant of EmptyState. Keep the default neutral no-results message unless localized product guidance makes the outcome clearer.",
           "Enable searchable for more than roughly 20 options, user-managed listings, large domains such as addresses, or sets users cannot efficiently scan. Local matching includes option labels, subtext, and section headings; the owner resolves remote data before assigning options.",
@@ -3222,7 +3508,7 @@
           "When any option supplies subtext, every row uses the same subtext structure and missing values render an em dash. Subtext should disambiguate or add decision-helpful information.",
           "Option labels stay on one line and truncate when constrained. Option subtext may wrap to at most two lines.",
           "The optional prefix icon and chevron always use the parent surface's secondary foreground color, including when selection promotes the label and count to primary.",
-          "The shared popup search control stays md at every trigger size, using body-medium text, a 20px icon, and the same internal spacing as a borderless Select trigger. Its container uses menu-item padding on every side and owns a 1px bottom divider that becomes a 1.5px bold-brand stroke while search has focus. Search placeholder text is secondary at rest and quaternary while focused.",
+          "The shared popup search control stays md at every trigger size, using body-medium text, a 20px icon, and the same internal spacing as a borderless Select trigger. Its container uses menu-item padding on every side and owns a 1px bottom divider that becomes a 1.5px bold-brand stroke while search has focus. Search placeholder text is secondary at rest and quaternary while focused because it becomes decorative once the editable field is active.",
           "When search contains text, the shared control shows a rounded sm icon-only ButtonUnfilled with the Cross icon and no border. It clears the local term, stays hidden for an empty term, and returns focus to search.",
           "The shared summary-and-clear footer mirrors the search region's sizing: menu-item padding surrounds an md-height borderless row, and both texts use the same row and label insets as option text. The outer footer owns a 1px top divider.",
           "An empty filtered list composes the message-only body variant of EmptyState. Keep the default neutral no-results message unless localized product guidance makes the outcome clearer.",
@@ -3764,11 +4050,118 @@
       "tag": "ds-slider",
       "name": "slider",
       "title": "Slider",
-      "summary": "Range input with visual fill track, label, and current value display.",
-      "intentStatus": "migration-pending",
-      "intent": null,
+      "summary": "Form-associated single or two-thumb range input with native slider semantics, pointer dragging, keyboard operation, formatting, density, and orientation controls.",
+      "intentStatus": "complete",
+      "intent": {
+        "audience": "general",
+        "status": "stable",
+        "summary": "Form-associated single or two-thumb range input with native slider semantics, pointer dragging, keyboard operation, formatting, density, and orientation controls.",
+        "useWhen": [
+          "A person should choose or tune an approximate numeric value within known bounds.",
+          "A bounded minimum and maximum range needs two independently focusable thumbs.",
+          "A value benefits from direct manipulation, immediate preview, and native form submission."
+        ],
+        "avoidWhen": [
+          "The exact numeric value is more important than direct spatial adjustment.",
+          "The choices are categorical rather than ordered numeric values.",
+          "The value is progress, measurement, or read-only status rather than user input."
+        ],
+        "alternatives": [
+          {
+            "when": "People must enter or verify a precise numeric value.",
+            "component": "component:ds-input",
+            "reason": "A typed field supports exact entry and review more efficiently than spatial adjustment."
+          },
+          {
+            "when": "The available values are a short finite set with meaningful labels.",
+            "component": "component:ds-radio",
+            "reason": "Visible named choices communicate categorical meaning more clearly."
+          },
+          {
+            "when": "The setting is binary and applies immediately.",
+            "component": "component:ds-switch",
+            "reason": "Switch communicates an immediate on/off state without implying intermediate values."
+          }
+        ],
+        "commonlyComposedWith": [
+          "component:ds-text",
+          "component:ds-input"
+        ],
+        "accessibility": [
+          "Each thumb contains a native range input and must have an accessible name; a visible label names a single thumb, while startLabel and endLabel distinguish a two-thumb range.",
+          "Arrow keys adjust one step, Home and End reach the allowed bounds, and browser-supported Page Up and Page Down make larger changes.",
+          "Every range thumb remains in a constant tab order and exposes dynamic minimum and maximum values when the other thumb constrains it.",
+          "Use valueText for one authored description or valueTexts for per-thumb range descriptions when numeric values are not understandable on their own, such as named levels, dates, durations, or units.",
+          "Read-only sliders remain focusable and submittable; inactive or disabled sliders leave the tab order and form submission."
+        ],
+        "states": [
+          "value is mutable: user pointer, keyboard, or assistive-technology input updates it and emits dsChange continuously.",
+          "dsCommit emits once a pointer interaction completes or the native range input commits a keyboard or assistive-technology change.",
+          "Assign a two-number array through the JavaScript value property to create a range; values are ordered, clamped, stepped, and prevented from crossing.",
+          "minStepsBetweenValues reserves a minimum stepped distance between range thumbs.",
+          "The initial normalized value is the native form-reset baseline and range values submit as repeated entries under the same name.",
+          "Focused, filled, dirty, touched, dragging, valid, disabled, read-only, and orientation data hooks expose interaction state without changing the value contract."
+        ],
+        "responsiveBehavior": [
+          "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.",
+          "Track thickness scales with density: 8px at md, 6px at sm, and 4px at xs. The unfilled track is transparent with a tertiary-foreground inset outline, the filled range is brand, and the thumb uses a 1.5px brand inset ring.",
+          "Horizontal value direction is left-to-right; the design system does not author RTL-specific component behavior."
+        ],
+        "frameworkCaveats": {
+          "customElements": [
+            "Assign range arrays and formatOptions through JavaScript properties, not string attributes.",
+            "Listen for dsChange during adjustment and dsCommit for expensive work that should run after the interaction settles."
+          ],
+          "react": [
+            "Use DsSlider with a number or two-number value array and handle onDsChange and onDsCommit custom events."
+          ],
+          "angular": [
+            "Use DsSlider with property binding for range arrays; the generated number value accessor is appropriate only for a single numeric value."
+          ]
+        },
+        "references": [
+          {
+            "label": "Storybook design review",
+            "path": "src/wc/components/Slider/Slider.stories.ts"
+          },
+          {
+            "label": "Cross-browser form and interaction coverage",
+            "path": "tests/e2e/forms.spec.ts"
+          }
+        ]
+      },
       "api": {
         "props": {
+          "ariaDescribedby": {
+            "type": "string | undefined",
+            "required": false
+          },
+          "ariaLabel": {
+            "type": "string | null",
+            "required": false
+          },
+          "ariaLabelledby": {
+            "type": "string | undefined",
+            "required": false
+          },
+          "disabled": {
+            "type": "boolean",
+            "required": false
+          },
+          "endLabel": {
+            "type": "string",
+            "required": false
+          },
+          "form": {
+            "type": "string | undefined",
+            "required": false
+          },
+          "formatOptions": {
+            "type": "Intl.NumberFormatOptions | undefined",
+            "required": false
+          },
           "inputId": {
             "type": "string | undefined",
             "required": false
@@ -3778,8 +4171,12 @@
             "required": false
           },
           "label": {
-            "type": "string",
-            "required": true
+            "type": "string | undefined",
+            "required": false
+          },
+          "locale": {
+            "type": "string | undefined",
+            "required": false
           },
           "max": {
             "type": "number",
@@ -3789,23 +4186,75 @@
             "type": "number",
             "required": false
           },
+          "minStepsBetweenValues": {
+            "type": "number",
+            "required": false
+          },
+          "name": {
+            "type": "string | undefined",
+            "required": false
+          },
+          "orientation": {
+            "type": "SliderOrientation",
+            "required": false
+          },
+          "rangeSeparator": {
+            "type": "string",
+            "required": false
+          },
+          "readOnly": {
+            "type": "boolean",
+            "required": false
+          },
+          "showValue": {
+            "type": "boolean",
+            "required": false
+          },
+          "size": {
+            "type": "SliderSize",
+            "required": false
+          },
+          "startLabel": {
+            "type": "string",
+            "required": false
+          },
           "step": {
             "type": "number",
             "required": false
           },
+          "thumbAlignment": {
+            "type": "SliderThumbAlignment",
+            "required": false
+          },
           "value": {
-            "type": "number",
+            "type": "SliderValue",
+            "required": false
+          },
+          "valuePrefix": {
+            "type": "string",
+            "required": false
+          },
+          "valueSuffix": {
+            "type": "string",
             "required": false
           },
           "valueText": {
             "type": "string | undefined",
             "required": false
+          },
+          "valueTexts": {
+            "type": "string[]",
+            "required": false
           }
         },
         "events": [
           {
             "name": "dsChange",
-            "detail": "number"
+            "detail": "SliderValue"
+          },
+          {
+            "name": "dsCommit",
+            "detail": "SliderValue"
           }
         ],
         "slots": []
@@ -3852,8 +4301,8 @@
           },
           {
             "when": "The user must choose one option from a mutually exclusive group.",
-            "component": "component:ds-radio-group",
-            "reason": "RadioGroup communicates one-of-many selection."
+            "component": "component:ds-radio",
+            "reason": "Radio communicates one-of-many selection."
           },
           {
             "when": "The control triggers a one-time command or submission.",
@@ -3870,17 +4319,20 @@
           "Every standalone switch requires an accessible name from a native label, aria-label, or aria-labelledby.",
           "Checked state is exposed through switch semantics and thumb position, so state does not rely on color alone.",
           "Read-only switches remain focusable and submitted but cannot change; inactive or disabled switches leave the tab order and are omitted from form submission.",
+          "Required and invalid state are exposed explicitly on the switch role; focused, filled, dirty, touched, valid, and invalid data hooks support form diagnostics without imposing visual validation timing.",
           "Use presentation mode only when a composite owner such as a menuitemcheckbox provides the interaction and accessible state."
         ],
         "states": [
           "Activation updates checked immediately and emits dsChange with the new boolean value.",
           "The initial checked value is the form-reset baseline; unchecked switches submit nothing unless uncheckedValue is provided.",
-          "Sizes are md 36×24 with a 16px thumb and 4px body inset, sm 24×16 with a 12px thumb and 2px inset, and xs 12×8 with a 6px thumb and 1px inset.",
+          "Sizes are md 32×20 with a 12px thumb and 4px body inset, sm 24×16 with a 10px thumb and 3px inset, and xs 20×12 with an 8px thumb and 2px inset.",
+          "Unchecked track and thumb are transparent and each uses a tertiary-foreground inset stroke: 1.25px at md, 1px at sm, and 0.75px at xs. Checked uses a brand track and primary-background thumb with both strokes removed.",
           "Presentation mode removes switch semantics, focus, interaction, and form submission while retaining the checked visual."
         ],
         "responsiveBehavior": [
           "Choose size from the density of the containing row; do not enlarge the switch to the full control height.",
-          "Keep the switch from shrinking when adjacent labels wrap."
+          "Keep the switch from shrinking when adjacent labels wrap.",
+          "Thumb movement is left-to-right; the design system does not author RTL-specific component behavior."
         ],
         "frameworkCaveats": {
           "customElements": [
@@ -4408,6 +4860,7 @@
           "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.",
+          "Tertiary and quaternary foregrounds are restricted to text inside genuinely inactive or disabled UI, or to purely decorative content whose removal would not change meaning; quaternary is the fainter tier, and aria-hidden alone does not exempt meaningful visible text from contrast requirements.",
           "Underline link text by default. Brand-blue links may omit the resting underline when color already supplies the affordance.",
           "Use dotted underline for hidden or supplemental interaction such as a tooltip; the owning trigger must provide focus, keyboard interaction, and accessible tooltip semantics."
         ],
@@ -4415,6 +4868,7 @@
           "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.",
+          "Prefer the owning control's isInactive or native disabled state over manually selecting tertiary or quaternary so visual treatment and inactive semantics remain synchronized.",
           "Line truncation and wrapping require an owner-supplied width constraint and content-aware composition decision.",
           "Solid underline is the default link affordance; brand-blue links may omit it at rest. 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.",