@ds-mo/ui 12.6.2 → 12.8.0

package/dist/agent.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": "1.0.0",
   "package": "@ds-mo/ui",
-  "packageVersion": "12.6.2",
+  "packageVersion": "12.8.0",
   "kind": "components",
   "entries": [
     {
@@ -1273,7 +1273,8 @@
           "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.",
-          "A semantic color would be decorative or merely match the surrounding product area."
+          "A semantic color would be decorative or merely match the surrounding product area.",
+          "The control is an overflow or more-options menu whose only content is an Ellipses glyph; that role is never filled."
         ],
         "alternatives": [
           {
@@ -1285,20 +1286,32 @@
             "when": "The user is choosing a destination in application navigation.",
             "component": "component:ds-panel-nav",
             "reason": "Navigation components own destination selection, active state, and navigation semantics."
+          },
+          {
+            "when": "The control is the overflow or more-options menu for a row, card, or toolbar.",
+            "component": "component:ds-button-unfilled",
+            "reason": "An icon-only Ellipses trigger is chrome, and its glyph conveys the menu without a chevron; a filled button never carries that role."
           }
         ],
         "commonlyComposedWith": [
           "component:ds-modal",
-          "component:ds-field"
+          "component:ds-field",
+          "component:ds-menu"
+        ],
+        "patterns": [
+          "pattern:menu-trigger"
         ],
         "accessibility": [
           "Provide an explicit accessible name for icon-only buttons.",
+          "Set hasMenu when the action opens a Menu; it implies aria-haspopup of menu and renders the trailing chevron. Pass controls with the Menu id and expanded from the same open state given to Menu.",
+          "Use haspopup directly for a non-menu popup such as a dialog; that case gets no chevron.",
           "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 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": [
+          "Every size applies one complete control-density recipe across frame height, inline padding, icon zone, text-container inset, gap, and radius.",
           "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.",
@@ -1306,7 +1319,11 @@
           "Parent surface context changes only the optional inset border color. Contrast continues to own the button fill, foreground, hover, pressed, and focus treatments; never use surface context to change action hierarchy.",
           "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 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."
+          "Icon and icon-label loading replace the icon in place. Label-only loading centers the loader while preserving the button's measured width.",
+          "Physical press scaling is on by default. Disable it only when an owning composite must keep child or background geometry fixed; hover and pressed interaction washes remain available.",
+          "ButtonFilled has no active or selected state; a filled action is a command, not a toggle or a persistent selection.",
+          "An open popup is a transient pressed state instead. While expanded is true the pressed wash is held for the popup's complete rendered lifecycle and survives hover, so the trigger reads as held open without introducing a selected treatment.",
+          "hasMenu supports only the label and icon-label variants. The chevron is what communicates that a menu will open, so an icon-only filled menu button would leave the affordance unstated."
         ],
         "responsiveBehavior": [
           "Use fill width only when the parent layout calls for a full-width action, commonly on narrow form layouts."
@@ -1343,10 +1360,26 @@
             "type": "ButtonFilledContrast",
             "required": false
           },
+          "controls": {
+            "type": "string | undefined",
+            "required": false
+          },
+          "expanded": {
+            "type": "boolean | undefined",
+            "required": false
+          },
           "hasBorder": {
             "type": "boolean",
             "required": false
           },
+          "hasMenu": {
+            "type": "boolean",
+            "required": false
+          },
+          "haspopup": {
+            "type": "ButtonFilledPopup | undefined",
+            "required": false
+          },
           "icon": {
             "type": "string",
             "required": false
@@ -1367,6 +1400,14 @@
             "type": "string",
             "required": false
           },
+          "pressScale": {
+            "type": "boolean",
+            "required": false
+          },
+          "pressed": {
+            "type": "boolean | undefined",
+            "required": false
+          },
           "rounded": {
             "type": "boolean",
             "required": false
@@ -1426,7 +1467,8 @@
         "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."
+          "A command represents a persistent toggle or mode whose active state remains meaningful after activation.",
+          "A row, card, or toolbar needs an overflow or more-options menu; this is the only component that carries that role."
         ],
         "avoidWhen": [
           "The command is the single primary action in a local decision area; use ButtonFilled instead.",
@@ -1461,6 +1503,9 @@
         ],
         "accessibility": [
           "Provide an explicit accessible name for every icon-only action.",
+          "Set hasMenu when the button triggers a Menu; it implies aria-haspopup of menu. Pass controls with the Menu id and expanded from the same open state given to Menu.",
+          "Give an icon-only menu button an accessible name that states the role, such as More options, because no visible label or chevron carries it.",
+          "Use haspopup directly for a non-menu popup such as a listbox or dialog; those cases get no chevron.",
           "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 focused and named, exposes busy and disabled state, and blocks activation; announce broader operation progress from the owning workflow when needed.",
@@ -1468,13 +1513,18 @@
           "For form submission, use native submit behavior and handle the form submit event rather than submitting from the button click event."
         ],
         "states": [
+          "Every size applies one complete control-density recipe across frame height, inline padding, icon zone, text-container inset, gap, and radius.",
           "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 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."
+          "Physical press scaling is on by default. Disable it only when an owning composite must keep child or background geometry fixed; hover and pressed interaction washes remain available.",
+          "Icon and icon-label loading replace the icon in place. Label-only loading centers the loader while preserving the button's measured width.",
+          "hasMenu covers two distinct menu-button shapes and the variant selects between them. With label or icon-label the action has a menu, and a trailing chevron carries the affordance. With icon the button is a menu, meaning the overflow or more-options control, and no chevron is added.",
+          "Because the icon-only shape has no chevron, its glyph must convey the menu on its own; use Ellipses. Never pair hasMenu with an icon-only glyph that does not read as a menu.",
+          "An open popup is a transient pressed state rather than a selected one. While expanded is true the pressed wash is held for the popup's complete rendered lifecycle and survives hover, including when chrome opts out of selected fills with activeFill set to false."
         ],
         "responsiveBehavior": [
           "The consuming layout decides when an icon-label action becomes icon-only and must provide an explicit accessible name after changing variants.",
@@ -1533,6 +1583,10 @@
             "type": "boolean",
             "required": false
           },
+          "hasMenu": {
+            "type": "boolean",
+            "required": false
+          },
           "haspopup": {
             "type": "ButtonUnfilledPopup | undefined",
             "required": false
@@ -1557,6 +1611,10 @@
             "type": "string",
             "required": false
           },
+          "pressScale": {
+            "type": "boolean",
+            "required": false
+          },
           "pressed": {
             "type": "boolean | undefined",
             "required": false
@@ -1660,13 +1718,14 @@
           "The card disables decorative legend-row hover; genuine legend links retain native link semantics and affordances."
         ],
         "states": [
+          "Bar, Line, and Donut cards share the same fill-chart and content-sized-legend body contract so dashboard card geometry remains aligned across chart types.",
           "The chart region fills the remaining card body while an optional legend remains content-sized.",
           "The card disables local hover highlighting on a slotted ChartLegend because bar legends are static keys.",
           "Chart and legend regions render only when their corresponding slots contain content, avoiding empty region spacing.",
           "The owning product controls data, filtering, loading, empty, and error state; the card emits the filter action only."
         ],
         "responsiveBehavior": [
-          "The selected sm, md, or lg shell size controls the card dimensions while the bar chart shrinks within its chart region.",
+          "The selected sm, md, or lg shell size controls the card dimensions while the bar chart reflows to the chart region without visually scaling its primitives.",
           "The horizontal legend wraps complete entries when the available width is constrained.",
           "The parent dashboard owns card wrapping and breakpoint changes."
         ],
@@ -1771,6 +1830,7 @@
           "The application owns meaningful loading, empty, and error status copy when either content region is temporarily replaced or absent."
         ],
         "states": [
+          "Bar, Line, and Donut cards share the same fill-chart and content-sized-legend body contract so dashboard card geometry remains aligned across chart types.",
           "The chart region fills remaining card height while the legend remains content-sized.",
           "Chart and legend regions render only when their corresponding slots contain content, allowing the owner to substitute loading, empty, or error presentations without dangling region padding.",
           "Hover synchronization changes highlight only; it never represents selection, filtering, or navigation.",
@@ -1778,6 +1838,7 @@
         ],
         "responsiveBehavior": [
           "Select the token-based card width appropriate to the parent grid; the matching minimum height preserves the chart region.",
+          "The donut measures the chart region and changes radius within its shared size band while token thickness and typography remain fixed.",
           "The parent dashboard owns wrapping and column changes while the internal chart-over-legend arrangement remains stable."
         ],
         "frameworkCaveats": {
@@ -1882,13 +1943,14 @@
           "The card disables decorative legend-row hover; genuine legend links retain native link semantics and affordances."
         ],
         "states": [
+          "Bar, Line, and Donut cards share the same fill-chart and content-sized-legend body contract so dashboard card geometry remains aligned across chart types.",
           "The chart region fills the remaining card body while the legend remains content-sized.",
           "The card disables local hover highlighting on a slotted ChartLegend because the line chart is static.",
           "Chart and legend regions render only when their corresponding slots contain content, avoiding empty region spacing.",
           "The owning product controls data, filtering, loading, empty, and error state; the card emits the filter action only."
         ],
         "responsiveBehavior": [
-          "The selected sm, md, or lg shell size controls the card dimensions while the line chart shrinks within its chart region.",
+          "The selected sm, md, or lg shell size controls the card dimensions while the line chart reflows to the chart region without visually scaling its primitives.",
           "The horizontal legend wraps complete entries when the available width is constrained.",
           "The parent dashboard owns card wrapping and breakpoint changes."
         ],
@@ -1947,6 +2009,153 @@
         "card-shell-data-viz"
       ]
     },
+    {
+      "id": "component:ds-card-overview",
+      "tag": "ds-card-overview",
+      "name": "card-overview",
+      "title": "CardOverview",
+      "summary": "Page-level summary bar pairing one headline score with a reporting period, an application-owned period control, and a responsive grid of comparable measures.",
+      "intentStatus": "complete",
+      "intent": {
+        "audience": "general",
+        "status": "experimental",
+        "summary": "Page-level summary bar pairing one headline score with a reporting period, an application-owned period control, and a responsive grid of comparable measures.",
+        "useWhen": [
+          "A page opens with one headline figure that the surrounding measures explain.",
+          "Every measure is compared against the same period, so one caption describes the comparison for all of them.",
+          "The measures are read together at a glance rather than explored individually."
+        ],
+        "avoidWhen": [
+          "There is no headline figure and the measures are unrelated; use the matching card surface for each one.",
+          "A measure needs a chart, sparkline, or other visualization; the grid presents values and change only.",
+          "The measures each require their own comparison period or their own filter control.",
+          "The content is a settings section or a general read-only card."
+        ],
+        "alternatives": [
+          {
+            "when": "A measure needs a chart or other data visualization.",
+            "component": "component:ds-card-shell-data-viz",
+            "reason": "CardShellDataViz owns the data-visualization shell contract; the overview grid presents values and change only."
+          },
+          {
+            "when": "The surface is a settings section with an edit workflow.",
+            "component": "component:ds-card-setting",
+            "reason": "CardSetting owns the controlled view and edit chrome."
+          }
+        ],
+        "commonlyComposedWith": [
+          "component:ds-select",
+          "component:ds-button-unfilled",
+          "component:ds-text",
+          "component:ds-tooltip"
+        ],
+        "accessibility": [
+          "The bar is a labelled region; set overviewLabel to name what is being summarised, such as Safety summary.",
+          "Trend arrows are decorative and hidden from assistive technology, so the formatted change value must read correctly on its own.",
+          "Colour never carries the trend meaning alone; the arrow direction and the value are both present.",
+          "Measures become selectable only when they are not inactive. Selectable measures form one roving tab stop, so the grid is a single stop and arrow keys move between measures.",
+          "Set labelTooltip when a measure's label needs qualifying rather than shortening the label into something ambiguous.",
+          "While loading, the region exposes a busy state and renders skeletons whose type metrics match the resolved content."
+        ],
+        "states": [
+          "Score and measures are supplied as data; the component owns their type treatment so summary bars stay consistent across pages.",
+          "Trend is supplied already resolved as a direction, a formatted value, and a tone. Whether a rise reads well is a product decision, so the component never infers tone from the numbers. Derive it with resolveMetricTrend.",
+          "Omit a trend when there is nothing to report; resolveMetricTrend returns null in that case so no zero change is rendered.",
+          "Omit score to render the bar without a headline figure. Set scoreErrorMessage to report that the figure could not be resolved while the measures remain readable.",
+          "Loading replaces the score and the measures with skeletons and does not alter the slotted period control.",
+          "The period control is slotted rather than owned, because the choice of stepper, select, or date range varies by product surface."
+        ],
+        "responsiveBehavior": [
+          "The measure grid reflows to fewer columns and finally stacks, driven by the minimum measure width alone. There is no measurement and no horizontal scrolling.",
+          "Set metricMinWidth to change the width a measure may shrink to before the grid drops a column.",
+          "The score block hugs its content and never shrinks, so the headline figure holds its size while the grid absorbs the remaining width.",
+          "The score moves above the body once the bar can no longer fit both side by side."
+        ],
+        "frameworkCaveats": {
+          "customElements": [
+            "Assign score and metrics as JavaScript properties; both are objects and cannot be expressed as HTML attributes.",
+            "Place the period control in the filter slot; the component reserves space for it but never renders one."
+          ],
+          "react": [
+            "Pass score and metrics as props and read the selected measure from the onDsMetricSelect event detail.",
+            "Derive each trend with resolveMetricTrend so tone stays an explicit product decision."
+          ],
+          "angular": [
+            "Bind [score] and [metrics] as properties and read the selected measure from $event.detail on (dsMetricSelect).",
+            "Derive each trend with resolveMetricTrend so tone stays an explicit product decision."
+          ]
+        },
+        "references": [
+          {
+            "label": "Storybook structural examples",
+            "path": "src/wc/components/CardOverview/CardOverview.stories.ts"
+          },
+          {
+            "label": "Trend resolution unit coverage",
+            "path": "tests/metric-change.test.ts"
+          }
+        ]
+      },
+      "api": {
+        "props": {
+          "comparisonLabel": {
+            "type": "string",
+            "required": false
+          },
+          "isLoading": {
+            "type": "boolean",
+            "required": false
+          },
+          "metricMinWidth": {
+            "type": "string",
+            "required": false
+          },
+          "metrics": {
+            "type": "OverviewMetric[]",
+            "required": false
+          },
+          "overviewLabel": {
+            "type": "string",
+            "required": false
+          },
+          "periodLabel": {
+            "type": "string",
+            "required": false
+          },
+          "score": {
+            "type": "OverviewScore | undefined",
+            "required": false
+          },
+          "scoreErrorMessage": {
+            "type": "string | undefined",
+            "required": false
+          }
+        },
+        "events": [
+          {
+            "name": "dsMetricSelect",
+            "detail": "OverviewMetric"
+          }
+        ],
+        "slots": []
+      },
+      "exports": {
+        "customElement": "ds-card-overview",
+        "react": "DsCardOverview",
+        "angular": "DsCardOverview"
+      },
+      "dependencies": [
+        "@ds-mo/ui",
+        "@ds-mo/tokens",
+        "@ds-mo/icons"
+      ],
+      "componentDependencies": [
+        "icon",
+        "skeleton",
+        "text",
+        "tooltip"
+      ]
+    },
     {
       "id": "component:ds-card-setting",
       "tag": "ds-card-setting",
@@ -2255,7 +2464,8 @@
           "Authored datum colors override the shared categorical palette."
         ],
         "responsiveBehavior": [
-          "The owner supplies dimensions and updates them with its layout; the chart does not measure its container.",
+          "Width and height provide the standalone intrinsic viewport; container constraints are measured and reflow the plot across the available pixels.",
+          "Responsive layout changes bar positions and plot extents without scaling SVG text, strokes, corner radii, or margins.",
           "Limit or pre-format long category labels so they remain legible at the chosen width.",
           "Time labels remain ordered, pre-formatted buckets with equal spacing rather than raw continuous timestamps."
         ],
@@ -2264,10 +2474,10 @@
             "Assign data as a JavaScript property; arrays are not supported as HTML attributes."
           ],
           "react": [
-            "Pass a stable data array and dimensions derived from the containing layout."
+            "Pass a stable data array; width and height provide standalone intrinsic dimensions while constrained containers reflow automatically."
           ],
           "angular": [
-            "Bind data as a property and update dimensions from the containing layout."
+            "Bind data as a property; width and height provide standalone intrinsic dimensions while constrained containers reflow automatically."
           ]
         },
         "references": [
@@ -2364,8 +2574,9 @@
           "Negative values are unsupported and render as zero; the owning product supplies loading, empty, and error states."
         ],
         "responsiveBehavior": [
-          "The SVG preserves its authored aspect ratio while shrinking to fit a narrower parent.",
-          "The parent supplies dimensions and chooses how many time buckets remain legible at each width.",
+          "Width and height provide the standalone intrinsic viewport; constrained card regions are measured and reflow both axes to their rendered pixel dimensions.",
+          "Responsive layout changes stack positions and plot extents without scaling SVG text, strokes, separators, corner radii, or margins.",
+          "The parent chooses how many time buckets remain legible at each width.",
           "Pre-format category labels and reduce bucket count before rendering when horizontal space becomes constrained."
         ],
         "frameworkCaveats": {
@@ -2477,6 +2688,7 @@
         "responsiveBehavior": [
           "Prefer container-fill sizing inside data-viz cards and explicit sizing only in layouts that own a stable diameter.",
           "Fill sizing remains centered and constrained to the shared donut size band.",
+          "Changing the measured diameter changes the ring radius without scaling its token-based thickness, typography, focus stroke, or corner treatment.",
           "The owner adapts category count and legend placement for available space."
         ],
         "frameworkCaveats": {
@@ -2759,7 +2971,8 @@
           "Authored series colors override the shared categorical palette."
         ],
         "responsiveBehavior": [
-          "The owner supplies intrinsic dimensions; the SVG preserves its aspect ratio while shrinking to fit a narrower parent.",
+          "Width and height provide the standalone intrinsic viewport; constrained card regions are measured and reflow both axes to their rendered pixel dimensions.",
+          "Responsive layout changes point positions and plot extents without scaling SVG text, line strokes, point markers, or margins.",
           "Category positions are always equally spaced, even when labels represent time.",
           "Reduce or pre-format dense labels before passing them; the chart renders authored labels without a continuous time scale."
         ],
@@ -2768,10 +2981,10 @@
             "Assign series and categories as JavaScript properties and keep every series aligned to the category count."
           ],
           "react": [
-            "Pass stable series and category arrays with dimensions derived from the containing layout."
+            "Pass stable series and category arrays; width and height provide standalone intrinsic dimensions while constrained containers reflow automatically."
           ],
           "angular": [
-            "Bind series and categories as properties with dimensions derived from the containing layout."
+            "Bind series and categories as properties; width and height provide standalone intrinsic dimensions while constrained containers reflow automatically."
           ]
         },
         "references": [
@@ -2823,12 +3036,12 @@
       "tag": "ds-checkbox",
       "name": "checkbox",
       "title": "Checkbox",
-      "summary": "Form-associated checkbox for independent choices, acknowledgment, or consent, with checked, unchecked, mixed, and three density states.",
+      "summary": "Form-associated checkbox for independent choices, acknowledgment, or consent, with checked, unchecked, mixed, and four density states.",
       "intentStatus": "complete",
       "intent": {
         "audience": "general",
         "status": "stable",
-        "summary": "Form-associated checkbox for independent choices, acknowledgment, or consent, with checked, unchecked, mixed, and three density states.",
+        "summary": "Form-associated checkbox for independent choices, acknowledgment, or consent, with checked, unchecked, mixed, and four density states.",
         "useWhen": [
           "A user may independently select zero or more choices.",
           "A form requires acknowledgment, consent, or an opt-in value before submission.",
@@ -2868,15 +3081,15 @@
           "Use presentation mode only inside a composite option that owns selection semantics, focus, and interaction."
         ],
         "states": [
-          "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.",
+          "Unchecked boxes use a tertiary-foreground inset stroke: 1.5px at lg, 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.",
+          "Sizes are lg with a 20px box in a 24px placement, 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.",
           "Presentation mode removes checkbox semantics, focus, interaction, label rendering, and form submission while preserving the visual state."
         ],
         "responsiveBehavior": [
           "Choose size from the density of the containing row; labels may wrap while the placement box stays fixed.",
-          "Use the md indicator centered by the shared 20px option icon zone in multi-select rows."
+          "Use the same density as the shared option icon zone in multi-select rows."
         ],
         "frameworkCaveats": {
           "customElements": [
@@ -3204,7 +3417,7 @@
           "actionLayout footer stretches a long action between 8px side and bottom insets.",
           "Both action layouts share the always-active scroll-overlay fade controller, reserve measured end clearance, and begin fading 8px before the visible action.",
           "ConversationList paints its measured fade on a separate surface-aware layer so contextual row actions retain a real backdrop for blur; hovered, focused, and menu-open rows rise above that decorative fade.",
-          "The persistent action wrapper splits its md outer shadow from a top inset-highlight overlay so opaque filled actions keep the complete TokoMo elevation; slotted controls must disable optional resting borders."
+          "The persistent action wrapper splits its md outer shadow from a top inset-highlight overlay so opaque filled actions keep the complete TokoMo elevation; slotted buttons disable optional resting borders and the press-scale modifier moves the button and elevated surface as one unit."
         ],
         "responsiveBehavior": [
           "The list fills its owner, scrolls independently, and keeps its persistent action above scrolling rows."
@@ -3275,7 +3488,7 @@
           "Hover and press use the shared interaction hover and pressed overlays. Only the selected conversation uses the persistent active fill.",
           "The title uses body-medium, not title-small, and the body-small preview truncates after one line. Unread titles use emphasis with primary foreground; read titles use regular weight with secondary foreground.",
           "The actions slot overlays the row at an 8px right inset without changing title or preview measure, and paints above the row interaction wash while that wash remains active.",
-          "Contextual actions use the shared md control-elevation wrapper so their transparent backdrop blur is unchanged while the split inset highlight remains above the borderless slotted action."
+          "Contextual actions use the shared md control-elevation wrapper so their transparent backdrop blur is unchanged while the split inset highlight remains above the borderless slotted action and the press-scale modifier moves the complete elevated surface."
         ],
         "responsiveBehavior": [
           "Long titles and previews truncate without displacing trailing status."
@@ -3577,7 +3790,7 @@
           "Supported compositions are icon plus title plus body, title plus body, and body only; body copy is present in every supported composition.",
           "The decorative icon renders at xl in the primary foreground with an 8px gap before the text group and only when a title is also provided.",
           "The visual title uses title-small primary text; body uses body-medium secondary text with a 4px title-to-body gap.",
-          "All content is centered. The owner supplies container size and surrounding padding; do not compose actions into or immediately alongside the current EmptyState pattern.",
+          "All content is centered. The owner supplies container size and surrounding padding; repeated panel and master-detail owners should share one empty-region geometry instead of wrapping each EmptyState differently. Do not compose actions into or immediately alongside the current EmptyState pattern.",
           "First-use, no-content, no-results, and no-access states reuse this primitive with cause-specific localized messages rather than visual variants."
         ],
         "responsiveBehavior": [
@@ -3599,6 +3812,10 @@
           {
             "label": "Storybook examples",
             "path": "src/wc/components/EmptyState/EmptyState.stories.ts"
+          },
+          {
+            "label": "Shared layout recipe foundation",
+            "path": "docs/layout-recipe-foundation.md"
           }
         ]
       },
@@ -3677,6 +3894,7 @@
           "Do not use placeholder text as the only label. Keep label text concise and put format or consequence guidance in description."
         ],
         "states": [
+          "Label, control, description, and error content follow the shared 4px vertical field flow without changing the slotted control's width or semantics.",
           "Field exposes data-focused, data-filled, data-dirty, data-touched, data-invalid, data-disabled, and data-required hooks while the slotted control remains the source of value and interaction behavior.",
           "A rendered error replaces the description; preserve essential guidance in the error message so users retain what they need to correct the field.",
           "Field owns validation presentation but not validation timing; the form decides when to set error and errorMessage.",
@@ -3874,12 +4092,12 @@
       "tag": "ds-input",
       "name": "input",
       "title": "Input",
-      "summary": "Form-associated single-line text field for primary and secondary application backgrounds, with native text input behavior, three control densities, optional leading and trailing content, search clearing, and validation.",
+      "summary": "Form-associated single-line text field for primary and secondary application backgrounds, with native text input behavior, four 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.",
+        "summary": "Form-associated single-line text field for primary and secondary application backgrounds, with native text input behavior, four 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.",
@@ -3920,6 +4138,7 @@
           "Suffix content must not carry information that is otherwise absent from the field's visible label, value, or description."
         ],
         "states": [
+          "Every size applies one complete control-density recipe across frame height, inline padding, icon zones, text-container inset, gap, and radius; supporting error content follows the shared 4px field flow.",
           "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.",
@@ -3931,7 +4150,7 @@
         ],
         "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.",
+          "Choose density from the containing layout: md for ordinary forms, lg for a touch-primary layout, and sm or xs only where surrounding controls use the same compact recipe.",
           "The owner supplies layout constraints and decides when a compact field moves to its own row."
         ],
         "frameworkCaveats": {
@@ -4318,7 +4537,7 @@
           "Anchor the menu to the control that opens it and return focus to that control when the menu closes.",
           "Open with visible initial focus only when the trigger was activated from the keyboard.",
           "Keep disabled items discoverable only when their unavailable state is meaningful.",
-          "Switch rows use menuitemcheckbox semantics on the row; the nested ds-switch is an aria-hidden md presentation indicator.",
+          "Switch rows use menuitemcheckbox semantics on the row; the nested ds-switch is an aria-hidden presentation indicator at the same density as the menu.",
           "Single-selection menus use menuitemradio semantics and aria-checked on each row, but render no nested radio control; selected interaction fill and primary foreground provide the visual state.",
           "A swatch-picker section changes the popup to a non-modal dialog so its radio group and ordinary preference buttons keep valid nested semantics; Tab moves between its controls, then leaves and closes at the popup boundary.",
           "Use notification dots only as supplemental status and not as the sole indication of important information."
@@ -4329,7 +4548,8 @@
           "After dsSelect from a switch row, replace the items or sections array with updated switchValue data so the controlled indicator reflects the new state.",
           "For selectionMode single, keep exactly one item isSelected and replace the items or sections array after dsSelect; Menu never mutates consumer-owned selection data.",
           "Arrays, objects, and element anchors must be assigned as JavaScript properties.",
-          "Use a swatch-picker section for a small curated visual preference and apply dsSwatchSelect immediately without closing the popup; the legacy gradient-picker section and dsGradientSelect remain compatibility-only."
+          "Use a swatch-picker section for a small curated visual preference and apply dsSwatchSelect immediately without closing the popup; the legacy gradient-picker section and dsGradientSelect remain compatibility-only.",
+          "Ordinary rows, section headings, and supporting text consume the Menu size. At xs, both the primary label and supporting text use caption metrics."
         ],
         "responsiveBehavior": [
           "Keep the default choice-cell anchor alignment so the first or last interactive row edge aligns with its trigger, matching Select; use popup-frame only for deliberate custom frame geometry.",
@@ -4419,6 +4639,10 @@
           "sideOffset": {
             "type": "number | string",
             "required": false
+          },
+          "size": {
+            "type": "MenuSize",
+            "required": false
           }
         },
         "events": [
@@ -4768,7 +4992,7 @@
           "Selection and transcript interaction release automatic following.",
           "Opening saved history, message jumps, and prepended history preserve deliberate position.",
           "The scroll-to-latest action is absent at the live edge, appears only after the reader moves away, and disappears again after returning to the newest message.",
-          "Scroll to latest uses the shared md control-elevation wrapper with a pointer-transparent top highlight, preserving its transparent backdrop blur and borderless unfilled action.",
+          "Scroll to latest uses the shared md control-elevation wrapper with a pointer-transparent top highlight, preserving its transparent backdrop blur and borderless unfilled action while the press-scale modifier moves the complete elevated surface.",
           "Place a composer container with 8px padding on every side in the overlay slot so messages scroll behind it; the shared scroll-overlay controller tracks every composer growth step, reserves matching transcript clearance, begins the fade 8px before the visible composer, and keeps scroll-to-latest above it."
         ],
         "responsiveBehavior": [
@@ -4860,7 +5084,7 @@
           "Direct touch paints the pressed overlay immediately, keeps a quick tap visible for one short frame, and clears it after release or cancellation without relying on Safari's latch-prone active state."
         ],
         "responsiveBehavior": [
-          "Render only below the mobile breakpoint and preserve safe-area clearance.",
+          "Render only below the mobile breakpoint; its secondary surface extends through the bottom safe-area inset when the application enables viewport-fit=cover.",
           "The secondary-background bar keeps an 8px outer inset; its two icon-only groups anchor to opposite edges while retaining fixed 40px targets and a divider between Menu and current area.",
           "Bar chrome and its divider are not text-selectable and suppress the iOS touch callout."
         ],
@@ -5189,7 +5413,9 @@
           "Area, Help, and Account events express intent while the application owns navigation and product behavior."
         ],
         "responsiveBehavior": [
-          "The pane fills the mobile content stage while the bottom bar remains available."
+          "The pane fills the mobile content stage while the bottom bar remains available.",
+          "The sheet header and scrollable navigation body each use the shared 8px chrome inset; large destination controls retain their independent 40px density.",
+          "Dashboard and Settings preserve their supplied visual groups with an 8px gap between destinations inside a section and a 32px gap between sections."
         ],
         "references": [
           {
@@ -6120,6 +6346,7 @@
           "Tools with search compose ds-panel-tool-search immediately below the shared header. Its 48px row always contains the md search control and must not be reduced to sm or xs.",
           "If an active optional tool becomes unavailable, PanelTools closes the drawer, clears activeTool, and emits its deselection.",
           "Use isInactive only for a temporarily unavailable visible tool; omit tools the user is not authorized to access.",
+          "Rail actions disable physical press scaling so notification-dot halos remain aligned to the shell gradient; hover and pressed washes continue to paint above the dot and halo.",
           "The application owns slotted tool products and data while PanelTools owns rail ordering, drawer selection, open state, motion, and shell events.",
           "Opening and closing clip an already-rendered fixed-width surface. Header and tool content remain fully opaque and retained during width motion; transition completion is accepted only at the measured terminal clip width, after which the closed surface becomes inert and paint-skipped.",
           "Entering and exiting fullscreen snaps without borrowing the drawer open or close animation.",
@@ -6259,12 +6486,12 @@
       "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.",
+      "summary": "Form-associated one-of-many radio selection set with vertical or horizontal layout, four 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.",
+        "summary": "Form-associated one-of-many radio selection set with vertical or horizontal layout, four 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.",
@@ -6303,9 +6530,9 @@
           "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.",
+          "Unchecked circles use a tertiary-foreground inset stroke: 1.5px at lg, 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 10px at lg, 8px at md, 6px at sm, and 4px at xs.",
+          "Sizes are lg with a 20px circle in a 24px placement, 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": [
@@ -6541,6 +6768,8 @@
           "Use errorMessage with error so the trigger is described by the rendered alert."
         ],
         "states": [
+          "Select and SelectMulti share popup positioning, dismissal, focus, typeahead, and listbox traversal while retaining their distinct scalar and array selection contracts.",
+          "Every size applies one complete control-density recipe across trigger height, inline padding, icon zones, text-container inset, gap, and radius; error content follows the shared 4px field flow.",
           "Value is controlled through the mutable value property; dsChange reports user selection and clearing.",
           "Required Selects begin without an automatic selection and require the user to make an explicit choice; do not preselect the first option merely to satisfy validity.",
           "When allowClear is enabled, the clear affordance appears only after a value exists. Clearing is valid for optional and required fields; a required field becomes invalid until the user selects again.",
@@ -6552,9 +6781,9 @@
           "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 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.",
+          "The shared popup search control follows the Select density, using the same text, icon, and internal spacing as a borderless 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 icon-only ButtonUnfilled with the CrossCircle icon and no border, sized to remain inset within the current row density. It clears the local term, stays hidden for an empty term, and returns focus to search.",
+          "The shared clear footer mirrors the owning density: menu-item padding surrounds a borderless density 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.",
           "Validation timing belongs to the form owner and may be immediate or deferred until blur or submit; the Select exposes validity and error presentation without imposing that policy.",
@@ -6790,23 +7019,25 @@
           "The popup is a listbox with aria-multiselectable and every option exposes its independent aria-selected state.",
           "Disabled options expose aria-disabled and are skipped by keyboard navigation and typeahead.",
           "Keyboard navigation keeps the aria-activedescendant option scrolled into the visible listbox viewport.",
-          "Each row uses a medium-size presentation-only ds-checkbox indicator; multi-select option rows never add a prefix icon alongside it, and the option remains the sole selection semantic and interaction target.",
+          "Each row uses a presentation-only ds-checkbox indicator at the same density as the row; multi-select option rows never add a prefix icon alongside it, and the option remains the sole selection semantic and interaction target.",
           "The trigger keeps its field label visible and appends the current selected count; an explicit aria-label or aria-labelledby remains the authoritative accessible name when supplied.",
           "Use errorMessage with error so the trigger is described by the rendered alert."
         ],
         "states": [
+          "Select and SelectMulti share popup positioning, dismissal, focus, typeahead, and listbox traversal while retaining their distinct scalar and array selection contracts.",
+          "Every size applies one complete control-density recipe across trigger height, inline padding, icon zones, text-container inset, gap, and radius; error content follows the shared 4px field flow.",
           "Values is a controlled JavaScript array; dsChange emits a new array after each user toggle.",
           "Required SelectMulti controls begin without an automatic selection and require the user to make an explicit choice.",
           "Selecting an option keeps the popup open so additional values can be toggled.",
-          "The trigger label stays left-aligned at every width; every option row uses the same leading medium Checkbox indicator. The default control size is md in both forms and filter bars.",
+          "The trigger label stays left-aligned at every width; every option row uses the same leading Checkbox indicator at its density. The default control size is md in both forms and filter bars.",
           "The selected count always follows the persistent label as plain text separated by a centered dot, including for one selection, and counts every selected value even when search or grouping hides it. Never replace the count with selected option names.",
           "Create sections only for categories that are meaningful to customers, not merely to break a long list into arbitrary chunks.",
           "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 because it becomes decorative once the editable field is active.",
+          "The shared popup search control follows the SelectMulti density, using the same text, icon, and internal spacing as a borderless 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.",
+          "The shared summary-and-clear footer mirrors the owning density: menu-item padding surrounds a borderless density 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.",
           "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.",
           "When allowClear is enabled, clear-all appears only after at least one value exists. Clearing is valid for optional and required fields; a required field becomes invalid until the user selects again.",
@@ -7068,6 +7299,7 @@
           "On desktop, PanelNav defaults expanded, permits user collapse or expansion, and respects the locally persisted desktop preference.",
           "On tablet, ShellApp keeps PanelNav permanently collapsed and prevents user expansion without overwriting the desktop preference.",
           "On mobile, ShellApp hides and inerts PanelNav and BarNav, uses a solid primary stage, and composes routed ShellPage MobileHeader presentations, MobileSheetNav, ShellTools, and the persistent five-item MobileBarNav.",
+          "When the application enables viewport-fit=cover, ShellApp reserves the shared top safe-area inset once for the complete mobile stage; nested routed, sheet, and tool headers must not add a second top inset.",
           "Mobile global surfaces conceal and inert the routed workspace without unmounting it, preserving nested routes and scroll state.",
           "Keep PanelNav width, BarNav height, PanelTools chrome, and main-content origin stable except during intentional responsive or collapse transitions.",
           "The bottom bar remains visible at all route and tool depths in the foundation release."
@@ -7421,7 +7653,8 @@
           "A ShellPage-managed BarTitle remains concealed until headerCapacity is available and its rendered variant matches the resolved presentation, preventing a default-variant flash during route activation.",
           "responsiveMode=mobile hides and inerts the desktop header, exposes mobile-header, and disables desktop scroll-compaction geometry.",
           "Update headerCapacity synchronously with shell layout state so opening tools or crossing application breakpoints cannot briefly render the wrong presentation.",
-          "On roomy pages, the expanded header scrolls upward until its title and action row reaches the compact row position, then snaps variants without moving that shared visual anchor.",
+          "The default content inset is 32px in desktop mode and 16px in tablet and mobile modes, while preserving the larger bottom scroll space.",
+          "On roomy pages, the expanded header scrolls upward until its title and action row reaches the compact row position, while its bottom divider progressively extends from the expanded inset to edge-to-edge; it then snaps variants without moving that shared visual anchor.",
           "Scroll compaction preserves the expanded page flow offset so content never jumps beneath the sticky header.",
           "ShellPage relies on ShellApp's content scroller and never introduces nested scrolling.",
           "BarWorkflow remains compact and is not assigned BarTitle's capacity or scroll variants."
@@ -7833,6 +8066,7 @@
           "Read-only sliders remain focusable and submittable; inactive or disabled sliders leave the tab order and form submission."
         ],
         "states": [
+          "The label, slider control, value display, and supporting content follow the shared 4px vertical field flow.",
           "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.",
@@ -8131,12 +8365,12 @@
       "tag": "ds-switch",
       "name": "switch",
       "title": "Switch",
-      "summary": "Compact on/off setting control for changes that take effect immediately, with three sizes and form-associated behavior.",
+      "summary": "Compact on/off setting control for changes that take effect immediately, with four sizes and form-associated behavior.",
       "intentStatus": "complete",
       "intent": {
         "audience": "general",
         "status": "stable",
-        "summary": "Compact on/off setting control for changes that take effect immediately, with three sizes and form-associated behavior.",
+        "summary": "Compact on/off setting control for changes that take effect immediately, with four sizes and form-associated behavior.",
         "useWhen": [
           "A binary setting takes effect immediately when the user turns it on or off.",
           "A settings, form, or menu row needs a compact on/off control.",
@@ -8179,7 +8413,7 @@
         "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 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.",
+          "Sizes are lg 40×24 with a 16px thumb and 4px body inset, md 32×20 with a 12px thumb and 4px inset, sm 24×16 with a 10px thumb and 3px inset, and xs 20×12 with an 8px thumb and 2px inset.",
           "Unchecked uses a transparent track with a density-specific tertiary-foreground inset stroke and a solid tertiary-foreground thumb without a border. Checked uses a brand track and primary-background thumb with no strokes.",
           "Presentation mode removes switch semantics, focus, interaction, and form submission while retaining the checked visual."
         ],
@@ -8980,7 +9214,7 @@
           },
           {
             "label": "Positioning unit coverage",
-            "path": "tests/tooltip-position.test.ts"
+            "path": "tests/anchored-position.test.ts"
           }
         ]
       },
@@ -9087,6 +9321,8 @@
           "The owning chart mounts the callout when a local interaction starts and unmounts it when that interaction ends.",
           "Coordinate updates track within one mounted interaction session without restarting the show delay.",
           "Placement flips horizontally or vertically when the rendered callout approaches a viewport edge.",
+          "Placement is chosen as a quadrant rather than computed as coordinates: the component measures its own rendered rect and flips its side and align props, which CSS consumes. It therefore does not use the shared anchored-position utilities, which resolve an anchor element into x and y.",
+          "This separation is deliberate. The callout follows the pointer instead of an element, so it has no anchor rect to resolve; adopting the shared geometry would mean rewriting its CSS to consume coordinates for no behavioral gain.",
           "Reduced motion preserves the final visible state without an opacity transition."
         ],
         "responsiveBehavior": [