@hirobius/design-system 0.18.0 → 0.19.1

package/public/hds-manifest.json

@@ -2,11 +2,11 @@
   "name": "Hirobius Design System",
   "description": "Three-tier design token system for Adrian Milsap's portfolio site. Tokens flow primitive → semantic → component. All visual decisions trace back to hirobius.tokens.json.",
   "version": "1",
-  "generated": "2026-09-28T00:14:31.544Z",
+  "generated": "2026-09-30T12:27:39.299Z",
   "source": "hirobius.tokens.json",
   "format": "W3C DTCG 2025.10",
-  "docs": "https://adrianmilsap.com/hds",
-  "llmsTxt": "https://adrianmilsap.com/llms.txt",
+  "docs": "https://hirobius-design-system.vercel.app/",
+  "llmsTxt": "https://hirobius-design-system.vercel.app/llms.txt",
   "systemSpecs": {
     "engine": "React + TypeScript",
     "icons": "Lucide React",
@@ -75,9 +75,11 @@
     "Container",
     "ContextMenu",
     "Cover",
+    "DataTableSection",
     "DateInput",
     "DateRangeInput",
     "DateTimeInput",
+    "DestructiveSection",
     "Dialog",
     "DialogClose",
     "DialogContent",
@@ -95,6 +97,7 @@
     "Field",
     "FileInput",
     "Form",
+    "FormActions",
     "FormField",
     "FormFieldShell",
     "FoundationSwatch",
@@ -114,11 +117,14 @@
     "Lightbox",
     "Menu",
     "MetadataList",
+    "MetricTile",
+    "MetricTiles",
     "MultiSelector",
     "NavGroup",
     "NavItem",
     "OverflowList",
     "Page",
+    "PageHeader",
     "Pagination",
     "Pin",
     "Popover",
@@ -240,7 +246,68 @@
       "monoSm"
     ]
   },
-  "patternInventory": [],
+  "patternInventory": [
+    "DataTableSection",
+    "DestructiveSection",
+    "FormActions",
+    "MetricTiles",
+    "PageHeader"
+  ],
+  "iconSet": {
+    "subpath": "@hirobius/design-system/icons",
+    "names": [
+      "Archive",
+      "ArrowDown",
+      "ArrowLeft",
+      "ArrowRight",
+      "ArrowUp",
+      "Bell",
+      "Bookmark",
+      "Calendar",
+      "Check",
+      "ChevronDown",
+      "ChevronLeft",
+      "ChevronRight",
+      "ChevronUp",
+      "CircleAlert",
+      "CircleCheck",
+      "CircleHelp",
+      "Clock",
+      "Copy",
+      "Download",
+      "Ellipsis",
+      "EllipsisVertical",
+      "ExternalLink",
+      "Eye",
+      "EyeOff",
+      "FileText",
+      "Funnel",
+      "Heart",
+      "House",
+      "Image",
+      "Info",
+      "Link",
+      "Lock",
+      "LogIn",
+      "LogOut",
+      "Mail",
+      "Menu",
+      "Minus",
+      "Pencil",
+      "Plus",
+      "RefreshCw",
+      "Save",
+      "Search",
+      "Settings",
+      "Share",
+      "Star",
+      "Trash2",
+      "TriangleAlert",
+      "Upload",
+      "User",
+      "X"
+    ]
+  },
   "phases": [
     {
       "id": "foundation",
@@ -581,7 +648,7 @@
     ],
     "namespaceViolations": []
   },
-  "agentEntrypoint": "CLAUDE.md",
+  "agentEntrypoint": "llms.txt",
   "breakingChangePolicy": "Version increments on any prop rename, token path rename, or removed component. Additions are non-breaking.",
   "componentSpecs": {
     "CaseStudyLayout": {
@@ -691,7 +758,12 @@
         "sizing": "panel"
       },
       "consumers": [
+        "src/app/components/badge.tsx",
+        "src/app/components/dialog.tsx",
+        "src/app/components/empty-state.tsx",
+        "src/app/components/toast.tsx",
         "src/app/data/hdsEditorial.tsx",
+        "src/stories/alert-dialog.stories.tsx",
         "src/stories/alert.stories.tsx",
         "src/stories/static-primitives.stories.tsx"
       ],
@@ -812,7 +884,21 @@
         "primitives-alert--success",
         "primitives-alert--warning",
         "primitives-alert--with-title"
-      ]
+      ],
+      "usage": {
+        "when": "Show a persistent inline message with a severity, next to the content it concerns.",
+        "whenNot": "A brief confirmation that should disappear on its own, or a status label.",
+        "useInstead": [
+          {
+            "component": "ToastProvider",
+            "reason": "a brief confirmation that fades away"
+          },
+          {
+            "component": "Badge",
+            "reason": "a short status label"
+          }
+        ]
+      }
     },
     "CinematicLink": {
       "category": "Branding",
@@ -946,7 +1032,7 @@
       "governedCategory": true,
       "hidden": false,
       "filePath": "src/app/components/container.tsx",
-      "description": "Container — semantic width-constrained layout. semantic max-width scale, so agents stop hand-rolling `marginInline: auto` plus an ad hoc max-width pixel value for page shells. use the semantic width scale ('content' | 'max'), never a raw px value. Do NOT use the deprecated `padding` prop — it is a no-op; apply padding via Surface or a Stack instead. Do NOT import Container directly inside a page under src/app/pages — use Page, which wraps Container and owns vertical rhythm. Use Center instead when you also need a horizontal gutter, which Container does not support. Centers content horizontally and applies semantic max-width constraints. - maxWidth options: 'content' (760px prose) | 'max' (1200px full layout) - No arbitrary pixel values allowed Usage: <Container maxWidth=\"max\"> <div>...</div> </Container>",
+      "description": "Container — semantic width-constrained layout. Centers content horizontally and applies semantic max-width constraints. - maxWidth options: 'content' (760px prose) | 'max' (1200px full layout) - No arbitrary pixel values allowed Usage: <Container maxWidth=\"max\"> <div>...</div> </Container>",
       "figmaUrl": null,
       "figmaId": null,
       "preview": {
@@ -959,6 +1045,7 @@
         "src/app/components/center.tsx",
         "src/app/components/page.tsx",
         "src/app/components/switcher.tsx",
+        "src/app/context/__tests__/portal-scope.test.tsx",
         "src/app/layouts/CaseStudyLayout.tsx",
         "src/app/layouts/DocLayout.tsx",
         "src/stories/box.stories.tsx",
@@ -1010,7 +1097,26 @@
       "storyIds": [
         "primitives-container--content-width",
         "primitives-container--max-width"
-      ]
+      ],
+      "usage": {
+        "when": "Constrain a page region to the content or maximum width and centre it.",
+        "whenNot": "Spacing between siblings, columns, or a surface with padding.",
+        "useInstead": [
+          {
+            "component": "Stack",
+            "reason": "spacing between siblings"
+          },
+          {
+            "component": "Grid",
+            "reason": "columns"
+          },
+          {
+            "component": "Box",
+            "reason": "one-off layout that no named primitive covers"
+          }
+        ]
+      },
+      "aiRules": "Reach for this named layout intent before Box/sx. maxWidth MUST use the semantic width scale ('content' | 'max'), never a raw px value. Do NOT use the deprecated `padding` prop — it is a no-op; apply padding via Surface or a Stack instead. Do NOT import Container directly inside a page under src/app/pages — use Page, which wraps Container and owns vertical rhythm. Use Center instead when you also need a horizontal gutter, which Container does not support."
     },
     "Disclosure": {
       "category": "Layout",
@@ -1027,6 +1133,7 @@
       },
       "consumers": [
         "src/app/components/nav-group.tsx",
+        "src/app/components/tabs.tsx",
         "src/app/layouts/HdsDocsShell.tsx",
         "src/stories/disclosure.stories.tsx",
         "src/stories/nav-group.stories.tsx"
@@ -1134,7 +1241,17 @@
         "primitives-disclosure--multiple-items",
         "primitives-disclosure--open-by-default",
         "primitives-disclosure--panel"
-      ]
+      ],
+      "usage": {
+        "when": "Hide optional explanatory content behind a heading that people can expand.",
+        "whenNot": "Content people must see, or switching between panels.",
+        "useInstead": [
+          {
+            "component": "Tabs",
+            "reason": "switching between panels of content"
+          }
+        ]
+      }
     },
     "Divider": {
       "category": "Layout",
@@ -1239,7 +1356,21 @@
         "primitives-divider--legacy-strong-prop",
         "primitives-divider--vertical",
         "primitives-divider--with-spacing"
-      ]
+      ],
+      "usage": {
+        "when": "Separate two regions of content with a thin semantic rule.",
+        "whenNot": "Spacing alone would do, or the separation needs a container.",
+        "useInstead": [
+          {
+            "component": "Stack",
+            "reason": "gap-based spacing between siblings"
+          },
+          {
+            "component": "Surface",
+            "reason": "a bounded region with its own background"
+          }
+        ]
+      }
     },
     "DocLinkCard": {
       "category": "Navigation",
@@ -1411,6 +1542,7 @@
         "sizing": "full"
       },
       "consumers": [
+        "src/stories/foundation-swatch.stories.test.ts",
         "src/stories/foundation-swatch.stories.tsx"
       ],
       "tokenMapping": {},
@@ -1543,8 +1675,11 @@
       "consumers": [
         "src/app/components/box.tsx",
         "src/app/components/cluster.tsx",
+        "src/app/components/container.tsx",
         "src/app/components/foundation-swatch.tsx",
         "src/app/components/image-lightbox.tsx",
+        "src/app/components/metric-tiles.test.tsx",
+        "src/app/components/metric-tiles.tsx",
         "src/app/components/segmented-control.test.tsx",
         "src/app/components/sidebar.tsx",
         "src/app/components/stack.tsx",
@@ -1557,7 +1692,8 @@
         "src/stories/grid.stories.tsx",
         "src/stories/patterns-layout.stories.tsx",
         "src/stories/segmented-control.stories.tsx",
-        "src/stories/surface.stories.tsx"
+        "src/stories/surface.stories.tsx",
+        "src/stories/tile-grid.stories.tsx"
       ],
       "tokenMapping": {},
       "props": {
@@ -1658,7 +1794,22 @@
         "primitives-grid--auto-fit",
         "primitives-grid--three-column",
         "primitives-grid--two-column"
-      ]
+      ],
+      "usage": {
+        "when": "Lay out content in responsive columns with token-governed gaps, or align nested content with subgrid.",
+        "whenNot": "A single row or column, or styling a surface.",
+        "useInstead": [
+          {
+            "component": "Stack",
+            "reason": "a single row or column"
+          },
+          {
+            "component": "Box",
+            "reason": "one-off layout that no named primitive covers"
+          }
+        ]
+      },
+      "aiRules": "Use Grid for spatial layout, not for surface styling or content padding. Do NOT apply background, border, or internal padding directly to Grid to mimic a card. Do NOT use arbitrary CSS grid templates when fixed, auto-fit, or subgrid modes already express the layout. Do NOT use Grid for simple one-dimensional stacks where Stack is sufficient."
     },
     "Icon": {
       "category": "Display",
@@ -1677,6 +1828,7 @@
         "src/app/components/activity-feed.test.tsx",
         "src/app/components/activity-feed.tsx",
         "src/app/components/alert.tsx",
+        "src/app/components/avatar.tsx",
         "src/app/components/breadcrumb.tsx",
         "src/app/components/checkbox.tsx",
         "src/app/components/code-block.tsx",
@@ -1823,7 +1975,21 @@
         "primitives-icon--semantic-color",
         "primitives-icon--semantic-colors",
         "primitives-icon--size-gallery"
-      ]
+      ],
+      "usage": {
+        "when": "Draw a Lucide glyph at a size and colour from the design tokens.",
+        "whenNot": "A control someone can activate, or a picture that carries content.",
+        "useInstead": [
+          {
+            "component": "Button",
+            "reason": "a clickable control, with iconOnly for an icon-only one"
+          },
+          {
+            "component": "Avatar",
+            "reason": "a picture of a person or entity"
+          }
+        ]
+      }
     },
     "IconButton": {
       "category": "Actions",
@@ -1839,6 +2005,8 @@
         "sizing": "panel"
       },
       "consumers": [
+        "src/app/components/button.test.tsx",
+        "src/app/components/data-table-section.tsx",
         "src/app/components/hds-tooltip.tsx",
         "src/app/components/inline-code.tsx",
         "src/app/components/pagination.tsx",
@@ -1846,7 +2014,10 @@
         "src/app/data/hdsEditorial.tsx",
         "src/docs-tooling/page-footer.tsx",
         "src/docs-tooling/shell-controls.tsx",
-        "src/stories/icon-button.stories.tsx"
+        "src/stories/data-table-section.stories.tsx",
+        "src/stories/icon-button.stories.tsx",
+        "src/stories/lib/usage-description.test.ts",
+        "src/stories/patterns-client-detail.stories.tsx"
       ],
       "tokenMapping": {
         "Fill": "semantic.accent.rest",
@@ -1962,7 +2133,17 @@
         "primitives-icon-button--primary",
         "primitives-icon-button--size-gallery",
         "primitives-icon-button--tertiary"
-      ]
+      ],
+      "usage": {
+        "when": "Trigger an action from a compact icon-only control, always with an accessible label.",
+        "whenNot": "A control that needs a visible text label.",
+        "useInstead": [
+          {
+            "component": "Button",
+            "reason": "a control with a text label, or Button iconOnly (hds#254 folds IconButton into it)"
+          }
+        ]
+      }
     },
     "InlineCode": {
       "category": "Display",
@@ -2044,10 +2225,13 @@
         "sizing": "panel"
       },
       "consumers": [
+        "src/app/components/button.tsx",
         "src/app/components/hover-card.tsx",
         "src/app/components/image-lightbox.tsx",
+        "src/app/components/text.tsx",
         "src/docs-tooling/lab/legacy-token-detail.tsx",
-        "src/stories/inline-link.stories.tsx"
+        "src/stories/inline-link.stories.tsx",
+        "src/stories/lib/usage-description.test.ts"
       ],
       "tokenMapping": {
         "Link text": "semantic.color.content.accent",
@@ -2095,7 +2279,21 @@
         "primitives-inline-link--external-no-icon",
         "primitives-inline-link--in-body-copy",
         "primitives-inline-link--internal-route"
-      ]
+      ],
+      "usage": {
+        "when": "Link to a route or external URL from inside body copy.",
+        "whenNot": "An action that changes something, or a control that needs button styling.",
+        "useInstead": [
+          {
+            "component": "Button",
+            "reason": "an action or a link that needs button styling"
+          },
+          {
+            "component": "Text",
+            "reason": "unlinked body copy"
+          }
+        ]
+      }
     },
     "Input": {
       "category": "Inputs",
@@ -2111,17 +2309,25 @@
         "sizing": "panel"
       },
       "consumers": [
+        "src/app/components/field.tsx",
         "src/app/components/form.tsx",
         "src/app/components/segmented-control.tsx",
+        "src/app/components/slider.tsx",
         "src/app/components/stepper-field.tsx",
         "src/app/components/textarea.tsx",
         "src/app/components/time-input.tsx",
         "src/app/data/hdsEditorial.tsx",
         "src/app/design-system/generated-token-descriptions.ts",
         "src/stories/combobox.stories.tsx",
+        "src/stories/date-input.stories.tsx",
+        "src/stories/date-range-input.stories.tsx",
+        "src/stories/date-time-input.stories.tsx",
+        "src/stories/file-input.stories.tsx",
+        "src/stories/input-group.stories.tsx",
         "src/stories/input.stories.tsx",
         "src/stories/patterns-layout.stories.tsx",
-        "src/stories/textarea.stories.tsx"
+        "src/stories/textarea.stories.tsx",
+        "src/stories/time-input.stories.tsx"
       ],
       "tokenMapping": {
         "Surface fill": "role.background",
@@ -2349,7 +2555,25 @@
         "primitives-input--size-variants",
         "primitives-input--with-error",
         "primitives-input--with-helper"
-      ]
+      ],
+      "usage": {
+        "when": "Collect a single line of text, a number, an email or a password, with label, helper and error slots.",
+        "whenNot": "Multi-line text, or choosing from a fixed list of options.",
+        "useInstead": [
+          {
+            "component": "Textarea",
+            "reason": "multi-line text"
+          },
+          {
+            "component": "Select",
+            "reason": "a short fixed list"
+          },
+          {
+            "component": "Combobox",
+            "reason": "a long fixed list that needs search"
+          }
+        ]
+      }
     },
     "NavGroup": {
       "category": "Navigation",
@@ -2569,7 +2793,10 @@
         "sizing": "panel"
       },
       "consumers": [
+        "src/app/components/button-group.tsx",
+        "src/app/components/radio.tsx",
         "src/app/components/segmented-control.test.tsx",
+        "src/app/components/tabs.tsx",
         "src/app/data/hdsEditorial.tsx",
         "src/app/hooks/useInteractionState.ts",
         "src/docs-tooling/TokenDisplayToggle.tsx",
@@ -2660,7 +2887,25 @@
         "primitives-segmented-control--full-width",
         "primitives-segmented-control--primary",
         "primitives-segmented-control--secondary"
-      ]
+      ],
+      "usage": {
+        "when": "Switch between two to five mutually exclusive views or modes in a compact row.",
+        "whenNot": "A form choice that submits with the form, or more than five options.",
+        "useInstead": [
+          {
+            "component": "Radio",
+            "reason": "a form choice that submits with the form"
+          },
+          {
+            "component": "Tabs",
+            "reason": "switching between panels of content"
+          },
+          {
+            "component": "Select",
+            "reason": "more than five options"
+          }
+        ]
+      }
     },
     "Sketch": {
       "category": "Layout",
@@ -2676,6 +2921,7 @@
         "sizing": "panel"
       },
       "consumers": [
+        "src/stories/sketch.stories.test.tsx",
         "src/stories/sketch.stories.tsx"
       ],
       "tokenMapping": {},
@@ -2756,10 +3002,13 @@
       "consumers": [
         "src/app/components/activity-feed.tsx",
         "src/app/components/box.tsx",
+        "src/app/components/button-group.tsx",
         "src/app/components/cluster.tsx",
         "src/app/components/container.tsx",
         "src/app/components/cover.tsx",
+        "src/app/components/data-table-section.tsx",
         "src/app/components/disclosure.tsx",
+        "src/app/components/divider.tsx",
         "src/app/components/error-boundary.tsx",
         "src/app/components/error-pattern.tsx",
         "src/app/components/foundation-swatch.tsx",
@@ -2767,8 +3016,11 @@
         "src/app/components/heading-stack.tsx",
         "src/app/components/image-lightbox.tsx",
         "src/app/components/nav-group.tsx",
+        "src/app/components/page-header.tsx",
         "src/app/components/page.tsx",
         "src/app/components/sketch.tsx",
+        "src/app/components/surface.tsx",
+        "src/app/components/table.tsx",
         "src/app/components/tooltip.tsx",
         "src/app/data/hdsEditorial.tsx",
         "src/app/layouts/CaseStudyLayout.tsx",
@@ -2781,7 +3033,9 @@
         "src/stories/box.stories.tsx",
         "src/stories/code-block.stories.tsx",
         "src/stories/grid.stories.tsx",
+        "src/stories/heading-stack.stories.tsx",
         "src/stories/page.stories.tsx",
+        "src/stories/patterns-client-detail.stories.tsx",
         "src/stories/patterns-layout.stories.tsx",
         "src/stories/stack.stories.tsx"
       ],
@@ -2936,7 +3190,22 @@
         "primitives-stack--space-between",
         "primitives-stack--spacious-gap",
         "primitives-stack--tight-gap"
-      ]
+      ],
+      "usage": {
+        "when": "Space a row or column of content with token gaps and simple flex alignment.",
+        "whenNot": "Multi-column layout, or giving content a background or padding.",
+        "useInstead": [
+          {
+            "component": "Grid",
+            "reason": "multi-column layout"
+          },
+          {
+            "component": "Surface",
+            "reason": "content that needs a background or padding"
+          }
+        ]
+      },
+      "aiRules": "Use Stack for flow spacing and simple flex alignment only. Do NOT use Stack to create card chrome, internal surface padding, or page-width constraints. Do NOT apply arbitrary margins to Stack to fake spacing between children when the gap prop should own that rhythm. Do NOT use Stack for true two-dimensional layouts that require Grid."
     },
     "StepperField": {
       "category": "Inputs",
@@ -2952,6 +3221,7 @@
         "sizing": "panel"
       },
       "consumers": [
+        "src/app/components/stepper-field.test.tsx",
         "src/stories/stepper-field.stories.tsx"
       ],
       "tokenMapping": {},
@@ -3052,10 +3322,13 @@
         "sizing": "full"
       },
       "consumers": [
+        "src/app/components/data-table-section.tsx",
         "src/app/components/table.test.tsx",
         "src/app/data/hdsEditorial.tsx",
+        "src/app/data/manifest-types.ts",
         "src/docs-tooling/api-reference.tsx",
         "src/docs-tooling/propTableUtils.tsx",
+        "src/stories/data-table-section.stories.tsx",
         "src/stories/nav-group.stories.tsx",
         "src/stories/nav-item.stories.tsx",
         "src/stories/segmented-control.stories.tsx",
@@ -3131,10 +3404,25 @@
         "primitives-table--density-comfortable",
         "primitives-table--density-compact",
         "primitives-table--flush",
+        "primitives-table--follows-density-dial",
         "primitives-table--sortable",
         "primitives-table--with-badge-slots",
         "primitives-table--with-caption"
-      ]
+      ],
+      "usage": {
+        "when": "Show rows of structured data in aligned columns, with optional sorting.",
+        "whenNot": "A single record, a short list of links, or content that reflows as cards.",
+        "useInstead": [
+          {
+            "component": "Field",
+            "reason": "one record as label and value pairs"
+          },
+          {
+            "component": "Stack",
+            "reason": "a short list of items"
+          }
+        ]
+      }
     },
     "Tag": {
       "category": "Inputs",
@@ -3303,7 +3591,17 @@
         "primitives-tag--filter-row",
         "primitives-tag--interactive",
         "primitives-tag--state-matrix"
-      ]
+      ],
+      "usage": {
+        "when": "Show an interactive filter or category chip that people can toggle.",
+        "whenNot": "A read-only status or count label.",
+        "useInstead": [
+          {
+            "component": "Badge",
+            "reason": "a read-only status or count"
+          }
+        ]
+      }
     },
     "Token": {
       "category": "Display",
@@ -3480,7 +3778,7 @@
       "governedCategory": true,
       "hidden": false,
       "filePath": "src/app/components/surface.tsx",
-      "description": "Surface — governed inset surface primitive. Enforces the \"Surface Inset\" rule: backgrounds MUST have internal padding. - Default padding: px24 (cards) | px16 (items) - Default border: none (elevation model — use shadow for lift) - Fixed radius: var(--component-card-radius) - shadow prop: applies a two-layer elevation shadow for card lift Usage: <Surface>Card content</Surface> <Surface padding=\"item\">Compact item</Surface> <Surface shadow>Lifted card with elevation shadow.</Surface>",
+      "description": "Surface — governed inset surface primitive. Enforces the \"Surface Inset\" rule: backgrounds MUST have internal padding. - Default padding: px24 (cards) | px16 (items) - Default border: none (elevation model — use shadow for lift) - Radius: `rounded-lg` (role radius + 4px), the one container radius shared with Card - shadow prop: applies a two-layer elevation shadow for card lift Usage: <Surface>Card content</Surface> <Surface padding=\"item\">Compact item</Surface> <Surface shadow>Lifted card with elevation shadow.</Surface>",
       "figmaUrl": "https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=89-27",
       "figmaId": null,
       "preview": {
@@ -3488,23 +3786,28 @@
         "sizing": "panel"
       },
       "consumers": [
+        "src/app/components/card.tsx",
         "src/app/components/container.tsx",
         "src/app/components/dialog.tsx",
         "src/app/components/disclosure.tsx",
+        "src/app/components/divider.tsx",
         "src/app/components/empty-state.tsx",
         "src/app/components/error-boundary.tsx",
         "src/app/components/error-pattern.tsx",
         "src/app/components/foundation-swatch.tsx",
         "src/app/components/image-lightbox.tsx",
+        "src/app/components/metric-tiles.tsx",
         "src/app/components/popover.tsx",
         "src/app/components/sketch.tsx",
         "src/app/components/slider.tsx",
+        "src/app/components/stack.tsx",
         "src/app/components/stepper-field.tsx",
         "src/app/components/surface-padding.ts",
         "src/app/components/table.tsx",
         "src/app/components/tokenTableUtils.ts",
         "src/app/components/tokenUtils.ts",
         "src/app/components/tooltip.tsx",
+        "src/app/context/hds-theme.tsx",
         "src/app/data/hdsEditorial.tsx",
         "src/app/layouts/CaseStudyLayout.tsx",
         "src/docs-tooling/api-reference.tsx",
@@ -3573,7 +3876,22 @@
         "primitives-surface--forced-dark",
         "primitives-surface--item-padding",
         "primitives-surface--with-shadow"
-      ]
+      ],
+      "usage": {
+        "when": "Wrap content in a padded, background-bearing inset surface with no header or footer anatomy.",
+        "whenNot": "Page layout, section spacing, width constraints, or content that needs slots.",
+        "useInstead": [
+          {
+            "component": "Card",
+            "reason": "content that needs header, body or footer slots"
+          },
+          {
+            "component": "Stack",
+            "reason": "spacing between siblings"
+          }
+        ]
+      },
+      "aiRules": "Use Surface only when content needs a background-bearing inset wrapper. Do NOT use Surface for macro page layouts, section spacing, or pure width constraints. Do NOT nest extra padded wrappers inside Surface to simulate another card. Do NOT recreate surface behavior with raw div padding, backgroundColor, or border styles elsewhere."
     },
     "Card": {
       "category": "Display",
@@ -3585,18 +3903,31 @@
       "figmaUrl": "https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=39-11",
       "figmaId": null,
       "consumers": [
+        "src/app/components/card-progress.test.tsx",
+        "src/app/components/card.test.tsx",
+        "src/app/components/destructive-section.tsx",
         "src/app/components/doc-link-card.tsx",
         "src/app/components/empty-state.tsx",
+        "src/app/components/field.tsx",
         "src/app/components/grid.tsx",
         "src/app/components/metadata-list.tsx",
+        "src/app/components/metric-tiles.tsx",
         "src/app/components/radio.test.tsx",
         "src/app/components/stacked-card-rail.tsx",
+        "src/app/components/stat.tsx",
+        "src/app/components/status-tile.tsx",
         "src/app/components/surface-padding.ts",
         "src/app/components/surface.tsx",
         "src/app/data/hdsEditorial.tsx",
         "src/app/design-system/generated-token-descriptions.ts",
         "src/stories/card.stories.tsx",
+        "src/stories/doc-link-card.stories.tsx",
         "src/stories/grid.stories.tsx",
+        "src/stories/history-card.stories.tsx",
+        "src/stories/hover-card.stories.tsx",
+        "src/stories/metric-tiles.stories.tsx",
+        "src/stories/selectable-card.stories.tsx",
+        "src/stories/stacked-card-rail.stories.tsx",
         "src/stories/static-primitives.stories.tsx"
       ],
       "tokenMapping": {
@@ -3821,7 +4152,21 @@
         "primitives-card--padding-variants",
         "primitives-card--progress-slot",
         "primitives-card--variant-accent"
-      ]
+      ],
+      "usage": {
+        "when": "Group related content on a raised surface with header, body, footer and metric slots.",
+        "whenNot": "A bare padded background with no slot anatomy, or a single headline figure.",
+        "useInstead": [
+          {
+            "component": "Surface",
+            "reason": "a padded background without slot anatomy"
+          },
+          {
+            "component": "Card.Metric",
+            "reason": "a single headline figure"
+          }
+        ]
+      }
     },
     "ComponentInstanceMatrix": {
       "category": "Utilities",
@@ -4195,17 +4540,22 @@
         "src/app/components/alert-dialog.tsx",
         "src/app/components/animated-label.tsx",
         "src/app/components/card.tsx",
+        "src/app/components/data-table-section.tsx",
         "src/app/components/date-input.tsx",
         "src/app/components/date-time-input.tsx",
+        "src/app/components/destructive-section.tsx",
         "src/app/components/dialog.tsx",
         "src/app/components/error-pattern.tsx",
         "src/app/components/foundation-swatch.tsx",
         "src/app/components/hds-tooltip.tsx",
+        "src/app/components/inline-link.tsx",
+        "src/app/components/kbd.tsx",
         "src/app/components/nav-item.tsx",
         "src/app/components/table.tsx",
         "src/app/components/text-lockup.tsx",
         "src/app/components/tokenTableUtils.ts",
         "src/app/components/toolbar.test.tsx",
+        "src/app/components/visually-hidden.tsx",
         "src/app/design-system/generated-token-descriptions.ts",
         "src/brand/overlay.ts",
         "src/docs-tooling/preview-frame.tsx",
@@ -4220,6 +4570,7 @@
         "src/stories/skeleton.stories.tsx",
         "src/stories/sketch.stories.tsx",
         "src/stories/surface.stories.tsx",
+        "src/stories/text-lockup.stories.tsx",
         "src/stories/text.stories.tsx",
         "src/stories/toolbar.stories.tsx"
       ],
@@ -4246,7 +4597,21 @@
         "primitives-text--heading-3",
         "primitives-text--technical",
         "primitives-text--ui"
-      ]
+      ],
+      "usage": {
+        "when": "Set any text on the type ramp, with the element chosen by `as`.",
+        "whenNot": "Navigation links, or a keyboard hint.",
+        "useInstead": [
+          {
+            "component": "InlineLink",
+            "reason": "a link inside body copy"
+          },
+          {
+            "component": "Kbd",
+            "reason": "a keyboard key hint"
+          }
+        ]
+      }
     },
     "Dialog": {
       "category": "Overlays",
@@ -4268,14 +4633,20 @@
         "src/app/components/alert-dialog.tsx",
         "src/app/components/command-palette.tsx",
         "src/app/components/dialog.test.tsx",
+        "src/app/components/hover-card.tsx",
         "src/app/components/image-lightbox.test.tsx",
         "src/app/components/image-lightbox.tsx",
         "src/app/components/menu.tsx",
         "src/app/components/popover.tsx",
+        "src/app/components/toast.tsx",
+        "src/app/context/__tests__/portal-hydration.test.tsx",
+        "src/app/context/__tests__/portal-scope.test.tsx",
+        "src/stories/alert-dialog.stories.tsx",
         "src/stories/alert.stories.tsx",
         "src/stories/combobox.stories.tsx",
         "src/stories/dialog.stories.tsx",
-        "src/stories/table.stories.tsx"
+        "src/stories/table.stories.tsx",
+        "src/styles/__tests__/scrim-and-color-scheme.test.ts"
       ],
       "tokenMapping": {},
       "variantAxes": [
@@ -4402,6 +4773,11 @@
           "tokenBinding": {
             "fill": "role.muted-foreground"
           }
+        },
+        {
+          "name": "trigger",
+          "description": "The element that opens the dialog (Dialog.Trigger).",
+          "source": "jsdoc"
         }
       ],
       "allowedChildren": [
@@ -4447,10 +4823,47 @@
         "src/stories/dialog.stories.tsx"
       ],
       "storyIds": [
+        "primitives-dialog--dark-scope",
         "primitives-dialog--default",
         "primitives-dialog--destructive",
         "primitives-dialog--information",
         "primitives-dialog--no-close-affordance"
+      ],
+      "usage": {
+        "when": "Interrupt the page with a modal that needs a decision or focused input before people continue.",
+        "whenNot": "A preview on hover, a message that needs no reply, or content that can stay inline.",
+        "useInstead": [
+          {
+            "component": "HoverCard",
+            "reason": "a preview on hover or focus"
+          },
+          {
+            "component": "Alert",
+            "reason": "a message that needs no reply"
+          },
+          {
+            "component": "ToastProvider",
+            "reason": "a brief confirmation"
+          }
+        ]
+      },
+      "keyboard": [
+        {
+          "keys": "Enter/Space",
+          "effect": "Opens the dialog from the trigger and moves focus inside it."
+        },
+        {
+          "keys": "Escape",
+          "effect": "Closes the dialog and returns focus to the trigger."
+        },
+        {
+          "keys": "Tab",
+          "effect": "Cycles focus inside the open dialog."
+        },
+        {
+          "keys": "Shift+Tab",
+          "effect": "Cycles focus backwards inside the open dialog."
+        }
       ]
     },
     "StackedCardRail": {
@@ -4470,6 +4883,7 @@
         "sizing": "panel"
       },
       "consumers": [
+        "src/app/components/stacked-card-rail.test.tsx",
         "src/index.ts",
         "src/stories/stacked-card-rail.stories.tsx"
       ],
@@ -4519,13 +4933,21 @@
         "src/app/components/animated-label.tsx",
         "src/app/components/button-group.test.tsx",
         "src/app/components/button-group.tsx",
+        "src/app/components/button.test.tsx",
+        "src/app/components/card.test.tsx",
         "src/app/components/card.tsx",
+        "src/app/components/command-palette.tsx",
+        "src/app/components/data-table-section.tsx",
+        "src/app/components/destructive-section.tsx",
         "src/app/components/dialog.tsx",
         "src/app/components/error-boundary.tsx",
         "src/app/components/error-pattern.tsx",
+        "src/app/components/form-actions.tsx",
         "src/app/components/form.tsx",
         "src/app/components/icon-button.tsx",
+        "src/app/components/icon.tsx",
         "src/app/components/image-lightbox.tsx",
+        "src/app/components/inline-link.tsx",
         "src/app/components/menu.tsx",
         "src/app/components/multi-selector.tsx",
         "src/app/components/pagination.tsx",
@@ -4547,19 +4969,25 @@
         "src/stories/button.stories.tsx",
         "src/stories/code-block.stories.tsx",
         "src/stories/combobox.stories.tsx",
+        "src/stories/data-table-section.stories.tsx",
         "src/stories/dialog.stories.tsx",
+        "src/stories/form-actions.stories.tsx",
         "src/stories/form.stories.tsx",
         "src/stories/hds-tooltip.stories.tsx",
         "src/stories/icon-button.stories.tsx",
         "src/stories/image-lightbox.stories.tsx",
         "src/stories/inline-code.stories.tsx",
+        "src/stories/lib/usage-description.test.ts",
         "src/stories/menu.stories.tsx",
         "src/stories/nav-group.stories.tsx",
+        "src/stories/page-header.stories.tsx",
+        "src/stories/patterns-client-detail.stories.tsx",
         "src/stories/patterns-layout.stories.tsx",
         "src/stories/popover.stories.tsx",
         "src/stories/table.stories.tsx",
         "src/stories/text-lockup.stories.tsx",
         "src/stories/toast.stories.tsx",
+        "src/stories/toggle-button.stories.tsx",
         "src/stories/toolbar.stories.tsx",
         "src/stories/top-nav.stories.tsx"
       ],
@@ -4743,7 +5171,17 @@
         "primitives-button--secondary",
         "primitives-button--small",
         "primitives-button--tertiary"
-      ]
+      ],
+      "usage": {
+        "when": "Trigger an action (submit, save, open a dialog) with a text label and optional icons; for an icon-only control pass iconOnly with iconLeft.",
+        "whenNot": "Navigating to another page, where a link is the correct element.",
+        "useInstead": [
+          {
+            "component": "InlineLink",
+            "reason": "navigation to another page"
+          }
+        ]
+      }
     },
     "Callout": {
       "category": "Feedback",
@@ -4829,7 +5267,7 @@
       "hidden": false,
       "docExempt": false,
       "filePath": "src/app/components/empty-state.tsx",
-      "description": "EmptyState — consistent no-data placeholder for lists, grids, and sections. communicate \"no data yet\" with consistent muted typography instead of agents inventing one-off `<p>No items.</p>` lines. use for full-page errors (use ErrorPage) or for loading states (use a skeleton). Do NOT wrap in Surface or Card — the empty state is a typographic message, not a chrome-bearing container.",
+      "description": "EmptyState — consistent no-data placeholder for lists, grids, and sections.",
       "figmaUrl": "https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=88-352",
       "figmaId": null,
       "figmaLink": "https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=88-352",
@@ -4839,7 +5277,9 @@
         "sizing": "panel"
       },
       "consumers": [
+        "src/app/components/data-table-section.tsx",
         "src/docs-tooling/lab/legacy-token-detail.tsx",
+        "src/stories/data-table-section.stories.tsx",
         "src/stories/empty-state.stories.tsx",
         "src/stories/patterns-layout.stories.tsx"
       ],
@@ -4873,7 +5313,22 @@
         "primitives-empty-state--in-grid",
         "primitives-empty-state--title-only",
         "primitives-empty-state--with-description"
-      ]
+      ],
+      "usage": {
+        "when": "Say that a list, grid or section has no data yet, with a title and an optional description.",
+        "whenNot": "Content that is still loading, or a full-page error.",
+        "useInstead": [
+          {
+            "component": "Skeleton",
+            "reason": "content that is still loading"
+          },
+          {
+            "component": "Alert",
+            "reason": "a message about something that went wrong"
+          }
+        ]
+      },
+      "aiRules": "Use only for inline empty states inside an existing section. Do NOT use for full-page errors (use ErrorPage) or for loading states (use a skeleton). Do NOT wrap in Surface or Card — the empty state is a typographic message, not a chrome-bearing container."
     },
     "Field": {
       "category": "Display",
@@ -4895,11 +5350,13 @@
         "src/app/components/combobox.tsx",
         "src/app/components/form.tsx",
         "src/app/components/input.tsx",
+        "src/app/components/table.tsx",
         "src/app/components/textarea.tsx",
         "src/form/hds-form.tsx",
         "src/stories/field.stories.tsx",
         "src/stories/patterns-layout.stories.tsx",
-        "src/stories/sketch.stories.tsx"
+        "src/stories/sketch.stories.tsx",
+        "src/stories/stepper-field.stories.tsx"
       ],
       "tokenMapping": {},
       "variantAxes": [],
@@ -4969,7 +5426,21 @@
         "primitives-field--success",
         "primitives-field--warning",
         "primitives-field--with-children"
-      ]
+      ],
+      "usage": {
+        "when": "Show a labelled read-only value, such as a name and its value in a detail view.",
+        "whenNot": "Editable input, or a single headline figure.",
+        "useInstead": [
+          {
+            "component": "Input",
+            "reason": "an editable single-line value"
+          },
+          {
+            "component": "Card.Metric",
+            "reason": "a headline figure inside a Card"
+          }
+        ]
+      }
     },
     "Page": {
       "category": "Layout",
@@ -4992,6 +5463,7 @@
         "src/app/components/not-found-pattern.tsx",
         "src/app/components/pagination.test.tsx",
         "src/app/components/pagination.tsx",
+        "src/app/components/surface.tsx",
         "src/app/components/toast.tsx",
         "src/app/design-system/generated-token-descriptions.ts",
         "src/brand/overlay.ts",
@@ -5072,6 +5544,8 @@
         "sizing": "panel"
       },
       "consumers": [
+        "src/app/components/metric-tiles.tsx",
+        "src/stories/metric-tiles.stories.tsx",
         "src/stories/stat.stories.tsx"
       ],
       "tokenMapping": {},
@@ -5134,7 +5608,21 @@
         "primitives-stat--success",
         "primitives-stat--warning",
         "primitives-stat--with-sub"
-      ]
+      ],
+      "usage": {
+        "when": "Show one standalone headline figure with its label and an optional sub-line.",
+        "whenNot": "A figure inside a Card, or a status with a trailing badge.",
+        "useInstead": [
+          {
+            "component": "Card.Metric",
+            "reason": "a figure inside a Card (hds#254 folds Stat into the Card slot)"
+          },
+          {
+            "component": "StatusTile",
+            "reason": "a titled status with notes and a trailing badge"
+          }
+        ]
+      }
     },
     "StatusListItem": {
       "category": "Display",
@@ -5154,6 +5642,7 @@
       },
       "consumers": [
         "src/app/components/status-tile.tsx",
+        "src/stories/status-list-item.stories.test.tsx",
         "src/stories/status-list-item.stories.tsx"
       ],
       "tokenMapping": {},
@@ -5234,7 +5723,11 @@
         "sizing": "panel"
       },
       "consumers": [
+        "src/app/components/metric-tiles.tsx",
+        "src/app/components/stat.tsx",
+        "src/stories/metric-tiles.stories.tsx",
         "src/stories/status-list-item.stories.tsx",
+        "src/stories/status-tile.stories.test.tsx",
         "src/stories/status-tile.stories.tsx"
       ],
       "tokenMapping": {},
@@ -5279,7 +5772,21 @@
         "primitives-status-tile--tile-grid",
         "primitives-status-tile--warning",
         "primitives-status-tile--with-trailing-badge"
-      ]
+      ],
+      "usage": {
+        "when": "Show a titled status block with optional notes and a trailing badge or affordance.",
+        "whenNot": "A single headline figure, or a row inside a list.",
+        "useInstead": [
+          {
+            "component": "Card.Metric",
+            "reason": "a headline figure (hds#254 folds StatusTile into the Card slot)"
+          },
+          {
+            "component": "StatusListItem",
+            "reason": "a status row inside a list"
+          }
+        ]
+      }
     },
     "TileGrid": {
       "category": "Layout",
@@ -5298,6 +5805,7 @@
         "sizing": "panel"
       },
       "consumers": [
+        "src/stories/status-tile.stories.test.tsx",
         "src/stories/status-tile.stories.tsx",
         "src/stories/tile-grid.stories.tsx"
       ],
@@ -5375,7 +5883,10 @@
       },
       "consumers": [
         "src/app/components/alert.tsx",
+        "src/app/components/avatar.tsx",
         "src/app/components/card.tsx",
+        "src/app/components/page-header.tsx",
+        "src/app/components/tag.tsx",
         "src/app/data/hdsEditorial.tsx",
         "src/app/design-system/generated-token-descriptions.ts",
         "src/docs-tooling/lab/legacy-token-detail.tsx",
@@ -5384,9 +5895,16 @@
         "src/stories/code-block.stories.tsx",
         "src/stories/combobox.stories.tsx",
         "src/stories/component-instance-matrix.stories.tsx",
+        "src/stories/data-table-section.stories.tsx",
         "src/stories/nav-group.stories.tsx",
+        "src/stories/page-header.stories.tsx",
+        "src/stories/patterns-client-detail.stories.tsx",
         "src/stories/patterns-layout.stories.tsx",
         "src/stories/static-primitives.stories.tsx",
+        "src/stories/status-list-item.stories.test.tsx",
+        "src/stories/status-list-item.stories.tsx",
+        "src/stories/status-tile.stories.test.tsx",
+        "src/stories/status-tile.stories.tsx",
         "src/stories/table.stories.tsx"
       ],
       "tokenMapping": {},
@@ -5400,7 +5918,21 @@
         "primitives-badge--neutral",
         "primitives-badge--success",
         "primitives-badge--warning"
-      ]
+      ],
+      "usage": {
+        "when": "Label a status, state or count with a compact neutral or semantic chip.",
+        "whenNot": "A chip people can toggle, or a message that needs a sentence.",
+        "useInstead": [
+          {
+            "component": "Tag",
+            "reason": "an interactive filter or category chip"
+          },
+          {
+            "component": "Alert",
+            "reason": "a message that needs a sentence"
+          }
+        ]
+      }
     },
     "TextLockup": {
       "variantAxes": [
@@ -5469,7 +6001,8 @@
         "primitives-text-lockup--numbered",
         "primitives-text-lockup--section",
         "primitives-text-lockup--with-eyebrow"
-      ]
+      ],
+      "aiRules": "Use TextLockup when content is a semantic title lockup with optional eyebrow and supporting text. Do NOT use TextLockup for arbitrary prose groups, data tables, or freeform mixed layouts. Do NOT restyle the internal type pairing with custom heading stacks when an existing size already fits. Do NOT use TextLockup to replace standalone body text or labels that do not form a title-description unit."
     },
     "AssetImg": {
       "category": "Display",
@@ -5488,6 +6021,7 @@
         "sizing": "panel"
       },
       "consumers": [
+        "src/app/components/asset-img.test.tsx",
         "src/app/components/hds-tooltip.tsx",
         "src/app/components/image-lightbox.tsx",
         "src/app/components/tooltip.tsx",
@@ -5663,7 +6197,11 @@
         "sizing": "panel"
       },
       "consumers": [
+        "src/app/components/breadcrumb.tsx",
+        "src/app/components/disclosure.tsx",
+        "src/app/components/segmented-control.tsx",
         "src/stories/combobox.stories.tsx",
+        "src/stories/patterns-client-detail.stories.tsx",
         "src/stories/tabs.stories.tsx"
       ],
       "tokenMapping": {},
@@ -5689,7 +6227,21 @@
         "primitives-tabs--default",
         "primitives-tabs--many-tabs",
         "primitives-tabs--with-disabled-tab"
-      ]
+      ],
+      "usage": {
+        "when": "Switch between panels of related content in the same place, one visible at a time.",
+        "whenNot": "A compact mode switch with no panels, or content that must all be visible.",
+        "useInstead": [
+          {
+            "component": "SegmentedControl",
+            "reason": "a compact switch with no panels"
+          },
+          {
+            "component": "Disclosure",
+            "reason": "optional content that expands in place"
+          }
+        ]
+      }
     },
     "TabsContent": {
       "category": "Navigation",
@@ -5708,6 +6260,7 @@
         "sizing": "panel"
       },
       "consumers": [
+        "src/stories/patterns-client-detail.stories.tsx",
         "src/stories/tabs.stories.tsx"
       ],
       "tokenMapping": {},
@@ -5752,6 +6305,7 @@
         "sizing": "panel"
       },
       "consumers": [
+        "src/stories/patterns-client-detail.stories.tsx",
         "src/stories/tabs.stories.tsx"
       ],
       "tokenMapping": {},
@@ -5796,6 +6350,7 @@
         "sizing": "panel"
       },
       "consumers": [
+        "src/stories/patterns-client-detail.stories.tsx",
         "src/stories/tabs.stories.tsx"
       ],
       "tokenMapping": {},
@@ -5839,6 +6394,8 @@
       "consumers": [
         "src/app/components/checkbox.tsx",
         "src/app/components/radio.test.tsx",
+        "src/app/components/segmented-control.tsx",
+        "src/app/components/toggle.tsx",
         "src/app/hooks/useInteractionState.test.ts",
         "src/app/hooks/useInteractionState.ts",
         "src/index.ts",
@@ -5889,7 +6446,25 @@
         "primitives-radio--disabled-selected",
         "primitives-radio--group",
         "primitives-radio--selected"
-      ]
+      ],
+      "usage": {
+        "when": "Choose exactly one option from a small set that should stay visible together.",
+        "whenNot": "Independent yes/no options, or a long list of options.",
+        "useInstead": [
+          {
+            "component": "Checkbox",
+            "reason": "independent options that can be ticked together"
+          },
+          {
+            "component": "Select",
+            "reason": "a long list that can collapse into a dropdown"
+          },
+          {
+            "component": "SegmentedControl",
+            "reason": "a compact switch between two to five views or modes"
+          }
+        ]
+      }
     },
     "Select": {
       "category": "Inputs",
@@ -5911,9 +6486,15 @@
         "src/app/components/date-range-input.test.tsx",
         "src/app/components/date-range-input.tsx",
         "src/app/components/form.tsx",
+        "src/app/components/input.tsx",
+        "src/app/components/menu.tsx",
         "src/app/components/multi-selector.test.tsx",
         "src/app/components/multi-selector.tsx",
+        "src/app/components/radio.tsx",
+        "src/app/components/segmented-control.tsx",
         "src/app/components/select.test.tsx",
+        "src/app/context/__tests__/portal-hydration.test.tsx",
+        "src/app/context/__tests__/portal-scope.test.tsx",
         "src/app/data/hdsEditorial.tsx",
         "src/docs-tooling/lab/legacy-token-detail.tsx",
         "src/index.ts",
@@ -5964,6 +6545,50 @@
       "storyIds": [
         "primitives-select--default",
         "primitives-select--no-label"
+      ],
+      "usage": {
+        "when": "Choose one value from a short list of options in a form field.",
+        "whenNot": "Firing actions, or choosing from a list long enough to need search.",
+        "useInstead": [
+          {
+            "component": "Menu",
+            "reason": "firing actions from a trigger"
+          },
+          {
+            "component": "Combobox",
+            "reason": "a long list that needs search"
+          }
+        ]
+      },
+      "keyboard": [
+        {
+          "keys": "Enter/Space/ArrowDown",
+          "effect": "Opens the listbox from the trigger with the selected option highlighted."
+        },
+        {
+          "keys": "ArrowDown/ArrowUp",
+          "effect": "Moves the highlight."
+        },
+        {
+          "keys": "Home/End",
+          "effect": "Jumps to the first or last option."
+        },
+        {
+          "keys": "Character",
+          "effect": "Highlights the option that matches the typed letters."
+        },
+        {
+          "keys": "Enter",
+          "effect": "Commits the highlighted option and returns focus to the trigger."
+        },
+        {
+          "keys": "Escape",
+          "effect": "Closes the listbox and returns focus to the trigger."
+        },
+        {
+          "keys": "Tab",
+          "effect": "Does not leave the open listbox."
+        }
       ]
     },
     "Slider": {
@@ -6029,7 +6654,17 @@
         "primitives-slider--default",
         "primitives-slider--stepped",
         "primitives-slider--typography-controls"
-      ]
+      ],
+      "usage": {
+        "when": "Pick a number within a known range by dragging, when the exact value matters less than the position.",
+        "whenNot": "A precise number the person must type or read exactly.",
+        "useInstead": [
+          {
+            "component": "Input",
+            "reason": "a precise typed value (type=\"number\")"
+          }
+        ]
+      }
     },
     "Toggle": {
       "category": "Inputs",
@@ -6054,6 +6689,7 @@
         "src/app/hooks/useInteractionState.ts",
         "src/docs-tooling/shell-controls.tsx",
         "src/index.ts",
+        "src/stories/toggle-button.stories.tsx",
         "src/stories/toggle.stories.tsx"
       ],
       "tokenMapping": {
@@ -6101,7 +6737,21 @@
         "primitives-toggle--disabled-on",
         "primitives-toggle--on",
         "primitives-toggle--settings-group"
-      ]
+      ],
+      "usage": {
+        "when": "Switch one setting on or off, with the effect applying immediately.",
+        "whenNot": "A choice that only takes effect after submitting a form, or picking from several options.",
+        "useInstead": [
+          {
+            "component": "Checkbox",
+            "reason": "a form option confirmed on submit"
+          },
+          {
+            "component": "Radio",
+            "reason": "one choice from a set"
+          }
+        ]
+      }
     },
     "Avatar": {
       "category": "Display",
@@ -6123,6 +6773,7 @@
         "src/app/components/avatar-group.test.tsx",
         "src/app/components/avatar-group.tsx",
         "src/app/components/avatar.test.tsx",
+        "src/app/components/icon.tsx",
         "src/app/design-system/generated-token-descriptions.ts",
         "src/stories/avatar-group.stories.tsx",
         "src/stories/avatar.stories.tsx"
@@ -6170,7 +6821,21 @@
         "primitives-avatar--large",
         "primitives-avatar--small",
         "primitives-avatar--with-image"
-      ]
+      ],
+      "usage": {
+        "when": "Show a person or entity as an image with an initials fallback.",
+        "whenNot": "A generic pictogram, or a status marker.",
+        "useInstead": [
+          {
+            "component": "Icon",
+            "reason": "a generic pictogram"
+          },
+          {
+            "component": "Badge",
+            "reason": "a status marker"
+          }
+        ]
+      }
     },
     "Progress": {
       "category": "Feedback",
@@ -6189,8 +6854,12 @@
         "sizing": "panel"
       },
       "consumers": [
+        "src/app/components/card-progress.test.tsx",
+        "src/app/components/card.test.tsx",
         "src/app/components/card.tsx",
         "src/app/components/progress.test.tsx",
+        "src/app/components/skeleton.tsx",
+        "src/app/components/spinner.tsx",
         "src/stories/card.stories.tsx",
         "src/stories/circular-progress.stories.tsx",
         "src/stories/progress.stories.tsx",
@@ -6232,7 +6901,21 @@
         "primitives-progress--complete",
         "primitives-progress--default",
         "primitives-progress--indeterminate"
-      ]
+      ],
+      "usage": {
+        "when": "Show how far a task has got, as a bar that is determinate or indeterminate.",
+        "whenNot": "A wait of unknown length with no bar, or content that is still loading.",
+        "useInstead": [
+          {
+            "component": "Spinner",
+            "reason": "a wait of unknown length"
+          },
+          {
+            "component": "Skeleton",
+            "reason": "placeholder shapes for loading content"
+          }
+        ]
+      }
     },
     "Skeleton": {
       "category": "Feedback",
@@ -6251,7 +6934,10 @@
         "sizing": "panel"
       },
       "consumers": [
+        "src/app/components/empty-state.tsx",
+        "src/app/components/progress.tsx",
         "src/app/components/skeleton.test.tsx",
+        "src/app/components/spinner.tsx",
         "src/stories/patterns-layout.stories.tsx",
         "src/stories/patterns-scroll.stories.tsx",
         "src/stories/skeleton.stories.tsx"
@@ -6293,7 +6979,21 @@
         "primitives-skeleton--circular",
         "primitives-skeleton--default",
         "primitives-skeleton--text"
-      ]
+      ],
+      "usage": {
+        "when": "Reserve the shape of content that is still loading, so the layout does not jump.",
+        "whenNot": "A task with measurable progress, or a wait with no layout to reserve.",
+        "useInstead": [
+          {
+            "component": "Progress",
+            "reason": "a task with measurable progress"
+          },
+          {
+            "component": "Spinner",
+            "reason": "a short wait with no layout to reserve"
+          }
+        ]
+      }
     },
     "Spinner": {
       "category": "Feedback",
@@ -6312,6 +7012,8 @@
         "sizing": "panel"
       },
       "consumers": [
+        "src/app/components/progress.tsx",
+        "src/app/components/skeleton.tsx",
         "src/app/components/spinner.test.tsx",
         "src/stories/spinner.stories.tsx"
       ],
@@ -6349,7 +7051,21 @@
         "primitives-spinner--default",
         "primitives-spinner--large",
         "primitives-spinner--small"
-      ]
+      ],
+      "usage": {
+        "when": "Show that something is loading when the wait is short or has no measurable end.",
+        "whenNot": "A task with measurable progress, or a region whose layout is known.",
+        "useInstead": [
+          {
+            "component": "Progress",
+            "reason": "a task with measurable progress"
+          },
+          {
+            "component": "Skeleton",
+            "reason": "a region whose layout is known"
+          }
+        ]
+      }
     },
     "Breadcrumb": {
       "category": "Navigation",
@@ -6369,8 +7085,12 @@
       },
       "consumers": [
         "src/app/components/breadcrumb.test.tsx",
+        "src/app/components/page-header.tsx",
+        "src/app/components/pagination.tsx",
         "src/app/components/table.tsx",
-        "src/stories/breadcrumb.stories.tsx"
+        "src/stories/breadcrumb.stories.tsx",
+        "src/stories/page-header.stories.tsx",
+        "src/stories/patterns-client-detail.stories.tsx"
       ],
       "tokenMapping": {},
       "variantAxes": [],
@@ -6399,7 +7119,21 @@
         "primitives-breadcrumb--default",
         "primitives-breadcrumb--shallow-trail",
         "primitives-breadcrumb--single-crumb"
-      ]
+      ],
+      "usage": {
+        "when": "Show where the current page sits in a hierarchy and link back up it.",
+        "whenNot": "Switching between sibling views, or stepping through pages of results.",
+        "useInstead": [
+          {
+            "component": "Tabs",
+            "reason": "switching between sibling views"
+          },
+          {
+            "component": "Pagination",
+            "reason": "stepping through pages of results"
+          }
+        ]
+      }
     },
     "Pagination": {
       "category": "Navigation",
@@ -6418,6 +7152,7 @@
         "sizing": "panel"
       },
       "consumers": [
+        "src/app/components/breadcrumb.tsx",
         "src/app/components/pagination.test.tsx",
         "src/stories/pagination.stories.tsx"
       ],
@@ -6458,7 +7193,17 @@
         "primitives-pagination--last-page",
         "primitives-pagination--middle-page",
         "primitives-pagination--wide-siblings"
-      ]
+      ],
+      "usage": {
+        "when": "Move between pages of a long result set, with truncated page numbers.",
+        "whenNot": "A hierarchy trail, or a short list that fits on one page.",
+        "useInstead": [
+          {
+            "component": "Breadcrumb",
+            "reason": "a hierarchy trail"
+          }
+        ]
+      }
     },
     "ToastProvider": {
       "category": "Feedback",
@@ -6477,6 +7222,8 @@
         "sizing": "panel"
       },
       "consumers": [
+        "src/app/components/alert.tsx",
+        "src/app/components/dialog.tsx",
         "src/app/components/toast.test.tsx",
         "src/stories/toast.stories.tsx"
       ],
@@ -6508,7 +7255,21 @@
         "primitives-toast--info",
         "primitives-toast--success",
         "primitives-toast--warning"
-      ]
+      ],
+      "usage": {
+        "when": "Confirm an action with a brief message that appears and dismisses itself, through useToast.",
+        "whenNot": "A message people must act on or that must stay next to its content.",
+        "useInstead": [
+          {
+            "component": "Alert",
+            "reason": "a message that stays next to its content"
+          },
+          {
+            "component": "Dialog",
+            "reason": "a message that needs a decision"
+          }
+        ]
+      }
     },
     "Combobox": {
       "category": "Inputs",
@@ -6530,7 +7291,9 @@
         "src/app/components/combobox.test.tsx",
         "src/app/components/date-range-input.tsx",
         "src/app/components/form.tsx",
+        "src/app/components/input.tsx",
         "src/app/components/multi-selector.tsx",
+        "src/app/components/select.tsx",
         "src/stories/combobox.stories.tsx",
         "src/stories/popover.stories.tsx"
       ],
@@ -6587,6 +7350,46 @@
         "primitives-combobox--few-options",
         "primitives-combobox--pre-selected",
         "primitives-combobox--with-disabled-option"
+      ],
+      "usage": {
+        "when": "Pick one value from a long list of options, with a search field that filters as you type.",
+        "whenNot": "A short list that needs no search, or an action list.",
+        "useInstead": [
+          {
+            "component": "Select",
+            "reason": "a short list without search"
+          },
+          {
+            "component": "Menu",
+            "reason": "firing actions from a trigger"
+          }
+        ]
+      },
+      "keyboard": [
+        {
+          "keys": "Enter/Space",
+          "effect": "Opens the list from the trigger and moves focus to the search field."
+        },
+        {
+          "keys": "ArrowDown/ArrowUp",
+          "effect": "Moves the active option and wraps at the ends."
+        },
+        {
+          "keys": "Character",
+          "effect": "Filters the options to those matching the typed text."
+        },
+        {
+          "keys": "Enter",
+          "effect": "Commits the active option and closes the list."
+        },
+        {
+          "keys": "Escape",
+          "effect": "Closes the list."
+        },
+        {
+          "keys": "Tab",
+          "effect": "Stays inside the open list."
+        }
       ]
     },
     "Form": {
@@ -6606,12 +7409,14 @@
         "sizing": "panel"
       },
       "consumers": [
+        "src/app/components/form-actions.tsx",
         "src/app/components/form.test.tsx",
         "src/app/data/hdsEditorial.tsx",
         "src/form/hds-form.tsx",
         "src/form/index.ts",
         "src/form/use-hds-form.ts",
         "src/index.ts",
+        "src/stories/form-actions.stories.tsx",
         "src/stories/form.stories.tsx",
         "src/stories/patterns-layout.stories.tsx"
       ],
@@ -6788,6 +7593,9 @@
       },
       "consumers": [
         "src/app/context/__tests__/context.test.tsx",
+        "src/app/context/__tests__/portal-hydration.test.tsx",
+        "src/app/context/__tests__/portal-scope.test.tsx",
+        "src/app/context/hds-portal.tsx",
         "src/index.ts"
       ],
       "tokenMapping": {},
@@ -6842,7 +7650,17 @@
       "requiredProps": [],
       "a11yRules": [],
       "storyFiles": [],
-      "storyIds": []
+      "storyIds": [],
+      "usage": {
+        "when": "Wrap an app or region once to set theme, density and other root attributes for everything inside it.",
+        "whenNot": "Styling a single component, or per-component overrides.",
+        "useInstead": [
+          {
+            "component": "Surface",
+            "reason": "a single region with its own background"
+          }
+        ]
+      }
     },
     "AvatarGroup": {
       "category": "Display",
@@ -6993,7 +7811,21 @@
       "storyIds": [
         "primitives-button-group--default",
         "primitives-button-group--vertical"
-      ]
+      ],
+      "usage": {
+        "when": "Attach related Buttons into one segmented row or column that reads as a single control.",
+        "whenNot": "Buttons that are unrelated, or choosing one of several views.",
+        "useInstead": [
+          {
+            "component": "SegmentedControl",
+            "reason": "choosing one of several views"
+          },
+          {
+            "component": "Stack",
+            "reason": "loosely spaced buttons"
+          }
+        ]
+      }
     },
     "InputGroup": {
       "category": "Inputs",
@@ -7073,6 +7905,7 @@
       },
       "consumers": [
         "src/app/components/kbd.test.tsx",
+        "src/app/components/text.tsx",
         "src/stories/kbd.stories.tsx"
       ],
       "tokenMapping": {},
@@ -7102,7 +7935,17 @@
         "primitives-kbd--combination",
         "primitives-kbd--default",
         "primitives-kbd--sizes"
-      ]
+      ],
+      "usage": {
+        "when": "Show a keyboard key or shortcut hint inline, as a native kbd element.",
+        "whenNot": "Code samples, or a control that runs the shortcut.",
+        "useInstead": [
+          {
+            "component": "Text",
+            "reason": "inline code and other typography"
+          }
+        ]
+      }
     },
     "StatusDot": {
       "category": "Feedback",
@@ -7269,7 +8112,17 @@
       ],
       "storyIds": [
         "primitives-visually-hidden--default"
-      ]
+      ],
+      "usage": {
+        "when": "Give assistive technology a label or description that sighted people do not need to see.",
+        "whenNot": "Text everyone should read, or hiding an element from assistive technology too.",
+        "useInstead": [
+          {
+            "component": "Text",
+            "reason": "text that everyone should read"
+          }
+        ]
+      }
     },
     "CircularProgress": {
       "category": "Feedback",
@@ -7441,6 +8294,8 @@
       },
       "consumers": [
         "src/app/components/image-lightbox.test.tsx",
+        "src/app/context/__tests__/portal-hydration.test.tsx",
+        "src/app/context/__tests__/portal-scope.test.tsx",
         "src/app/data/hdsEditorial.tsx",
         "src/index.ts",
         "src/stories/asset-img.stories.tsx",
@@ -7938,6 +8793,7 @@
       "consumers": [
         "src/app/components/stepper.test.tsx",
         "src/index.ts",
+        "src/stories/stepper-field.stories.tsx",
         "src/stories/stepper.stories.tsx"
       ],
       "tokenMapping": {},
@@ -7990,6 +8846,7 @@
         "sizing": "panel"
       },
       "consumers": [
+        "src/app/components/data-table-section.tsx",
         "src/app/components/toolbar.test.tsx",
         "src/index.ts",
         "src/stories/toolbar.stories.tsx"
@@ -8085,7 +8942,12 @@
       },
       "consumers": [
         "src/app/components/alert-dialog.test.tsx",
-        "src/stories/alert-dialog.stories.tsx"
+        "src/app/components/destructive-section.tsx",
+        "src/app/context/__tests__/portal-hydration.test.tsx",
+        "src/app/context/__tests__/portal-scope.test.tsx",
+        "src/stories/alert-dialog.stories.tsx",
+        "src/stories/destructive-section.stories.tsx",
+        "src/styles/__tests__/scrim-and-color-scheme.test.ts"
       ],
       "tokenMapping": {},
       "variantAxes": [],
@@ -8101,6 +8963,7 @@
         "src/stories/alert-dialog.stories.tsx"
       ],
       "storyIds": [
+        "primitives-alert-dialog--dark-scope",
         "primitives-alert-dialog--default"
       ]
     },
@@ -8216,6 +9079,8 @@
       },
       "consumers": [
         "src/app/components/context-menu.test.tsx",
+        "src/app/context/__tests__/portal-hydration.test.tsx",
+        "src/app/context/__tests__/portal-scope.test.tsx",
         "src/stories/context-menu.stories.tsx"
       ],
       "tokenMapping": {},
@@ -8233,6 +9098,54 @@
       ],
       "storyIds": [
         "primitives-context-menu--default"
+      ],
+      "slots": [
+        {
+          "name": "trigger",
+          "description": "The area that opens the menu on right-click (ContextMenu.Trigger).",
+          "source": "jsdoc"
+        },
+        {
+          "name": "content",
+          "description": "The popup holding the items (ContextMenu.Content).",
+          "source": "jsdoc"
+        }
+      ],
+      "usage": {
+        "when": "Offer actions for an item on right-click, or the equivalent keyboard gesture.",
+        "whenNot": "The only way to reach an action, or actions from a visible trigger.",
+        "useInstead": [
+          {
+            "component": "Menu",
+            "reason": "actions from a visible trigger"
+          }
+        ]
+      },
+      "keyboard": [
+        {
+          "keys": "ArrowDown/ArrowUp",
+          "effect": "Moves the highlight and stops at the first and last item."
+        },
+        {
+          "keys": "End",
+          "effect": "Jumps to the last item."
+        },
+        {
+          "keys": "Character",
+          "effect": "Highlights the next item that starts with the typed letter."
+        },
+        {
+          "keys": "Enter",
+          "effect": "Selects the highlighted item and closes the menu."
+        },
+        {
+          "keys": "Escape",
+          "effect": "Closes the menu without leaving focus inside the removed content."
+        },
+        {
+          "keys": "Tab",
+          "effect": "Does not leave the open menu."
+        }
       ]
     },
     "DateInput": {
@@ -8454,7 +9367,10 @@
         "sizing": "panel"
       },
       "consumers": [
+        "src/app/components/dialog.tsx",
         "src/app/components/hover-card.test.tsx",
+        "src/app/context/__tests__/portal-hydration.test.tsx",
+        "src/app/context/__tests__/portal-scope.test.tsx",
         "src/stories/hover-card.stories.tsx"
       ],
       "tokenMapping": {},
@@ -8472,6 +9388,46 @@
       ],
       "storyIds": [
         "primitives-hover-card--default"
+      ],
+      "slots": [
+        {
+          "name": "trigger",
+          "description": "The link or element that opens the card (HoverCard.Trigger).",
+          "source": "jsdoc"
+        },
+        {
+          "name": "content",
+          "description": "The preview (HoverCard.Content).",
+          "source": "jsdoc"
+        }
+      ],
+      "usage": {
+        "when": "Preview extra detail about a link or mention when it is hovered or focused, without navigating.",
+        "whenNot": "Content people must reach, or a label for an interactive control.",
+        "useInstead": [
+          {
+            "component": "Dialog",
+            "reason": "content people must act on"
+          },
+          {
+            "component": "Tooltip",
+            "reason": "a short label for a control"
+          }
+        ]
+      },
+      "keyboard": [
+        {
+          "keys": "Focus",
+          "effect": "Opens the card when the trigger receives keyboard focus."
+        },
+        {
+          "keys": "Escape",
+          "effect": "Closes the card and keeps focus on the trigger."
+        },
+        {
+          "keys": "Tab",
+          "effect": "Moves on to the next element and closes the card."
+        }
       ]
     },
     "MultiSelector": {
@@ -8653,7 +9609,7 @@
       "hidden": false,
       "docExempt": false,
       "filePath": "src/app/components/box.tsx",
-      "description": "Box — polymorphic layout primitive with a token-first `sx` engine. named primitive covers, without inviting ad hoc inline styles or raw hex/px values back into the system — the `sx` engine only accepts HDS token keys and a small, deliberate CSS subset. Box `sx` ONLY for genuinely one-off layout. sx colors/spacing MUST use token keys, not raw hex/px. Prefer named layout primitives over ad-hoc flex. `sx` is a deliberate SUBSET of MUI's sx — not all of CSS-in-JS is a feature: - Spacing shorthands (m/p/gap family) resolve numbers off the 4px HDS scale (`--primitive-space-<n>`) and named steps ('tight'|'normal'|'inset'|'spacious') off `--semantic-space-layout-*`. - `color`/`bgcolor`/`borderColor`/`fill`/`stroke` resolve dotted token keys ('content.primary', 'surface.raised', 'border.subtle', 'accent', 'accent.hover', 'feedback.success', …) to the matching semantic CSS var. - Responsive `{ xs, sm, md, lg, xl }` objects compile to `min-width` media queries off the HDS breakpoint scale. - `&`-prefixed keys ('&:hover', '& > *', '&[data-state=open]') nest a selector, composable with responsive values. - Everything else passes through as a plain camelCase→kebab-case CSS declaration (numbers get `px` unless in the unitless allowlist). See `box-sx.ts` for the pure resolver + hashing/injection engine.",
+      "description": "Box — polymorphic layout primitive with a token-first `sx` engine. `sx` is a deliberate SUBSET of MUI's sx — not all of CSS-in-JS is a feature: - Spacing shorthands (m/p/gap family) resolve numbers off the 4px HDS scale (`--primitive-space-<n>`) and named steps ('tight'|'normal'|'inset'|'spacious') off `--semantic-space-layout-*`. - `color`/`bgcolor`/`borderColor`/`fill`/`stroke` resolve dotted token keys ('content.primary', 'surface.raised', 'border.subtle', 'accent', 'accent.hover', 'feedback.success', …) to the matching semantic CSS var. - Responsive `{ xs, sm, md, lg, xl }` objects compile to `min-width` media queries off the HDS breakpoint scale. - `&`-prefixed keys ('&:hover', '& > *', '&[data-state=open]') nest a selector, composable with responsive values. - Everything else passes through as a plain camelCase→kebab-case CSS declaration (numbers get `px` unless in the unitless allowlist). See `box-sx.ts` for the pure resolver + hashing/injection engine.",
       "figmaUrl": null,
       "figmaId": null,
       "figmaLink": null,
@@ -8671,6 +9627,7 @@
         "src/app/components/container.tsx",
         "src/app/components/cover.tsx",
         "src/app/components/frame.tsx",
+        "src/app/components/grid.tsx",
         "src/app/components/sidebar.tsx",
         "src/app/components/switcher.tsx",
         "src/app/components/toggle.tsx",
@@ -8710,7 +9667,26 @@
         "primitives-box--responsive-values",
         "primitives-box--spacing-shorthands",
         "primitives-box--token-colors"
-      ]
+      ],
+      "usage": {
+        "when": "Build one-off layout that no named layout primitive covers, using token keys through `sx`.",
+        "whenNot": "Ordinary vertical or horizontal spacing, columns, or page-width constraint.",
+        "useInstead": [
+          {
+            "component": "Stack",
+            "reason": "a row or column of content with even gaps"
+          },
+          {
+            "component": "Grid",
+            "reason": "multi-column layout"
+          },
+          {
+            "component": "Container",
+            "reason": "a width-constrained page region"
+          }
+        ]
+      },
+      "aiRules": "Reach for Stack/Grid/Container/the every-layout primitives first. Use Box `sx` ONLY for genuinely one-off layout. sx colors/spacing MUST use token keys, not raw hex/px. Prefer named layout primitives over ad-hoc flex."
     },
     "Bleed": {
       "category": "Layout",
@@ -8719,7 +9695,7 @@
       "hidden": false,
       "docExempt": false,
       "filePath": "src/app/components/bleed.tsx",
-      "description": "Bleed — controlled negative-margin full-bleed within a padded container. padding\" (a full-width image inside a padded card, a divider that should touch both edges) with a single tokenized negative-margin wrapper, so agents stop hand-rolling `margin: -24px` guesses that drift from the parent's actual padding token. use a semantic space step, never raw px, and MUST match the ancestor padding it is meant to cancel out. Do NOT use Bleed to fake extra spacing — its only job is canceling a specific known padding value on a specific axis. Every Layout reference: https://every-layout.dev/layouts/the-stack/ (bleed is the inverse of a padded Center/Container — HDS names it separately since \"every-layout\" itself does not ship a dedicated Bleed recipe).",
+      "description": "Bleed — controlled negative-margin full-bleed within a padded container. Every Layout reference: https://every-layout.dev/layouts/the-stack/ (bleed is the inverse of a padded Center/Container — HDS names it separately since \"every-layout\" itself does not ship a dedicated Bleed recipe).",
       "figmaUrl": null,
       "figmaId": null,
       "figmaLink": null,
@@ -8783,7 +9759,8 @@
       "storyIds": [
         "primitives-bleed--bleed-both",
         "primitives-bleed--bleed-x"
-      ]
+      ],
+      "aiRules": "Reach for this named layout intent before Box/sx. amount MUST use a semantic space step, never raw px, and MUST match the ancestor padding it is meant to cancel out. Do NOT use Bleed to fake extra spacing — its only job is canceling a specific known padding value on a specific axis."
     },
     "Center": {
       "category": "Layout",
@@ -8792,7 +9769,7 @@
       "hidden": false,
       "docExempt": false,
       "filePath": "src/app/components/center.tsx",
-      "description": "Center — max-width column, auto-centered horizontally. max-width box with auto horizontal margins and, optionally, matching horizontal gutters — so agents stop hand-rolling `marginInline: auto` plus an ad hoc max-width value. use the semantic width scale ('content' | 'max'), never a raw px value. gutter, when set, MUST use a semantic space step, never raw px. Do NOT use Center for full-bleed page shells — use Container. Do NOT use Center when you need the deprecated Container padding prop — gutter replaces it. Every Layout reference: https://every-layout.dev/layouts/center/",
+      "description": "Center — max-width column, auto-centered horizontally. Every Layout reference: https://every-layout.dev/layouts/center/",
       "figmaUrl": null,
       "figmaId": null,
       "figmaLink": null,
@@ -8860,7 +9837,8 @@
         "primitives-center--content-width",
         "primitives-center--max-width",
         "primitives-center--with-gutter"
-      ]
+      ],
+      "aiRules": "Reach for this named layout intent before Box/sx. maxWidth MUST use the semantic width scale ('content' | 'max'), never a raw px value. gutter, when set, MUST use a semantic space step, never raw px. Do NOT use Center for full-bleed page shells — use Container. Do NOT use Center when you need the deprecated Container padding prop — gutter replaces it."
     },
     "Cluster": {
       "category": "Layout",
@@ -8869,7 +9847,7 @@
       "hidden": false,
       "docExempt": false,
       "filePath": "src/app/components/cluster.tsx",
-      "description": "Cluster — wrapping horizontal group with even gaps. (tag rows, button groups, chip lists, filter pills) with a single flex-wrap wrapper and a tokenized gap in both axes, so agents stop hand-rolling `flexWrap` + `gap` + alignment combinations inline. horizontal groups that should wrap as a unit. Spacing MUST use semantic steps, never raw px. Do NOT use Cluster for a strict single-line row — use Stack with `direction=\"row\"` when wrapping is never desired. Do NOT use Cluster for two-dimensional grid layouts — use Grid. Every Layout reference: https://every-layout.dev/layouts/cluster/",
+      "description": "Cluster — wrapping horizontal group with even gaps. Every Layout reference: https://every-layout.dev/layouts/cluster/",
       "figmaUrl": null,
       "figmaId": null,
       "figmaLink": null,
@@ -8880,6 +9858,11 @@
       },
       "consumers": [
         "src/app/components/cluster.test.tsx",
+        "src/app/components/data-table-section.tsx",
+        "src/app/components/destructive-section.tsx",
+        "src/app/components/form-actions.test.tsx",
+        "src/app/components/form-actions.tsx",
+        "src/app/components/page-header.tsx",
         "src/app/components/switcher.tsx",
         "src/stories/cluster.stories.tsx",
         "src/stories/patterns-layout.stories.tsx"
@@ -8947,7 +9930,8 @@
         "primitives-cluster--default",
         "primitives-cluster--space-between",
         "primitives-cluster--spacious-gap"
-      ]
+      ],
+      "aiRules": "Reach for this named layout intent before Box/sx. Use Cluster for horizontal groups that should wrap as a unit. Spacing MUST use semantic steps, never raw px. Do NOT use Cluster for a strict single-line row — use Stack with `direction=\"row\"` when wrapping is never desired. Do NOT use Cluster for two-dimensional grid layouts — use Grid."
     },
     "Cover": {
       "category": "Layout",
@@ -8956,7 +9940,7 @@
       "hidden": false,
       "docExempt": false,
       "filePath": "src/app/components/cover.tsx",
-      "description": "Cover — vertical shell with an auto-centered main region. centered hero/main region that absorbs the remaining space, and an optional footer\" problem via the flex auto-margin centering technique, so agents stop hand-rolling `position: absolute` centering or a fixed 50vh split. semantic space step, never raw px. minHeight is a CSS length dimension (not spacing) — defaults to '100svh' (small viewport height, safe against mobile browser chrome). Pass minHeight=\"100vh\" explicitly if you need the classic viewport unit for a target that predates svh support. Do NOT use Cover for ordinary page content flow — use Stack. Every Layout reference: https://every-layout.dev/layouts/cover/",
+      "description": "Cover — vertical shell with an auto-centered main region. Every Layout reference: https://every-layout.dev/layouts/cover/",
       "figmaUrl": null,
       "figmaId": null,
       "figmaLink": null,
@@ -9031,7 +10015,8 @@
         "primitives-cover--header-main-footer",
         "primitives-cover--header-only",
         "primitives-cover--main-only"
-      ]
+      ],
+      "aiRules": "Reach for this named layout intent before Box/sx. gap MUST use a semantic space step, never raw px. minHeight is a CSS length dimension (not spacing) — defaults to '100svh' (small viewport height, safe against mobile browser chrome). Pass minHeight=\"100vh\" explicitly if you need the classic viewport unit for a target that predates svh support. Do NOT use Cover for ordinary page content flow — use Stack."
     },
     "Frame": {
       "category": "Layout",
@@ -9040,7 +10025,7 @@
       "hidden": false,
       "docExempt": false,
       "filePath": "src/app/components/frame.tsx",
-      "description": "Frame — aspect-ratio-locked, token-clipped media box. cause layout shift while it loads, cropped to a token-governed corner radius\" — a thin, token-skinned wrapper over `AspectRatio` (`@radix-ui/react-aspect-ratio`), which already owns the ratio-lock mechanics. Frame adds the overflow-hidden clip and semantic radius that a bare media frame needs and `AspectRatio` deliberately leaves undecorated. media (image, video, embed, map tile). radius MUST use a semantic borderRadius token, never a raw px value. Do NOT reach for bare `AspectRatio` in product code just to add a border-radius by hand — use Frame. Do NOT use Frame for non-media layout — it exists purely as a media clipping frame. Every Layout reference: https://every-layout.dev/layouts/frame/",
+      "description": "Frame — aspect-ratio-locked, token-clipped media box. Every Layout reference: https://every-layout.dev/layouts/frame/",
       "figmaUrl": null,
       "figmaId": null,
       "figmaLink": null,
@@ -9101,7 +10086,8 @@
         "primitives-frame--no-radius",
         "primitives-frame--square",
         "primitives-frame--widescreen"
-      ]
+      ],
+      "aiRules": "Reach for this named layout intent before Box/sx when framing media (image, video, embed, map tile). radius MUST use a semantic borderRadius token, never a raw px value. Do NOT reach for bare `AspectRatio` in product code just to add a border-radius by hand — use Frame. Do NOT use Frame for non-media layout — it exists purely as a media clipping frame."
     },
     "Sidebar": {
       "category": "Layout",
@@ -9110,7 +10096,7 @@
       "hidden": false,
       "docExempt": false,
       "filePath": "src/app/components/sidebar.tsx",
-      "description": "Sidebar — fixed-width rail beside fluid content, no media query. problem with the flex-basis/flex-grow disparity technique — the rail holds `sideWidth` and the content flex-basis 0 with an overwhelming flex-grow, so the pair wraps to stacked automatically once the container can no longer fit both without squeezing content below `contentMin`. No CSS media query, no JS resize observer. EXACTLY two children — the rail and the content — passed in that order. `side` controls which one visually renders as the rail; DOM order is unchanged. gap MUST use a semantic space step, never raw px. sideWidth and contentMin are CSS length dimensions (not spacing) — a length string like '16rem' or '50%' is expected, matching the check-hardcoded-spacing gate's own dimension-prop exemption. Do NOT use Sidebar for more than two regions — use Grid. Every Layout reference: https://every-layout.dev/layouts/sidebar/",
+      "description": "Sidebar — fixed-width rail beside fluid content, no media query. Every Layout reference: https://every-layout.dev/layouts/sidebar/",
       "figmaUrl": null,
       "figmaId": null,
       "figmaLink": null,
@@ -9189,7 +10175,8 @@
         "primitives-sidebar--narrow-container-stacks",
         "primitives-sidebar--rail-end",
         "primitives-sidebar--rail-start"
-      ]
+      ],
+      "aiRules": "Reach for this named layout intent before Box/sx. Sidebar expects EXACTLY two children — the rail and the content — passed in that order. `side` controls which one visually renders as the rail; DOM order is unchanged. gap MUST use a semantic space step, never raw px. sideWidth and contentMin are CSS length dimensions (not spacing) — a length string like '16rem' or '50%' is expected, matching the check-hardcoded-spacing gate's own dimension-prop exemption. Do NOT use Sidebar for more than two regions — use Grid."
     },
     "Switcher": {
       "category": "Layout",
@@ -9198,7 +10185,7 @@
       "hidden": false,
       "docExempt": false,
       "filePath": "src/app/components/switcher.tsx",
-      "description": "Switcher — flips a row to a column below a width threshold, no media query. vertical stack once the container gets narrow\" without a breakpoint or a resize observer, using the flex-basis calc() technique: each item's flex-basis resolves to a huge negative or huge positive number depending on whether the container is above or below `threshold`, forcing every item onto its own line once it flips. semantic space step, never raw px. threshold is a CSS length dimension (not spacing), e.g. '30rem'. `limit` unconditionally forces the stacked (column) layout once there are more than `limit` children, regardless of container width — use it to stop a row from thinning out into an unreadable N-up strip. Do NOT use Switcher for content that should always wrap in place — use Cluster. Every Layout reference: https://every-layout.dev/layouts/the-switcher/",
+      "description": "Switcher — flips a row to a column below a width threshold, no media query. Every Layout reference: https://every-layout.dev/layouts/the-switcher/",
       "figmaUrl": null,
       "figmaId": null,
       "figmaLink": null,
@@ -9262,7 +10249,8 @@
         "primitives-switcher--default",
         "primitives-switcher--limit-forces-stacked",
         "primitives-switcher--narrow-container-stacks"
-      ]
+      ],
+      "aiRules": "Reach for this named layout intent before Box/sx. gap MUST use a semantic space step, never raw px. threshold is a CSS length dimension (not spacing), e.g. '30rem'. `limit` unconditionally forces the stacked (column) layout once there are more than `limit` children, regardless of container width — use it to stop a row from thinning out into an unreadable N-up strip. Do NOT use Switcher for content that should always wrap in place — use Cluster."
     },
     "Pin": {
       "category": "Layout",
@@ -9271,7 +10259,7 @@
       "hidden": false,
       "docExempt": false,
       "filePath": "src/app/components/pin.tsx",
-      "description": "Pin — sticky-pin an element within its scroll region. section scrolls — the dependency-free basis for pinned scroll scenes (the \"tall section + sticky child\" pattern that GSAP's `pin: true` solves imperatively). Reach for this before hand-rolling sticky positioning. Give the pinned element a TALLER scrolling parent so it has room to travel. For the scroll-scrubbed animation inside a pinned scene, use CSS `animation-timeline` (see Reveal) or `useScrollProgress` from `@hirobius/design-system/scroll`. See ADR-021.",
+      "description": "Pin — sticky-pin an element within its scroll region.",
       "figmaUrl": null,
       "figmaId": null,
       "figmaLink": null,
@@ -9281,6 +10269,7 @@
         "sizing": "panel"
       },
       "consumers": [
+        "src/app/components/form-actions.tsx",
         "src/app/components/pin.test.tsx",
         "src/stories/patterns-scroll.stories.tsx",
         "src/stories/pin.stories.tsx",
@@ -9321,7 +10310,8 @@
       ],
       "storyIds": [
         "primitives-pin--sidebar"
-      ]
+      ],
+      "aiRules": "`top` is a CSS length offset (a dimension, not a spacing step). Give the pinned element a TALLER scrolling parent so it has room to travel. For the scroll-scrubbed animation inside a pinned scene, use CSS `animation-timeline` (see Reveal) or `useScrollProgress` from `@hirobius/design-system/scroll`. See ADR-021."
     },
     "Reveal": {
       "category": "Motion",
@@ -9330,7 +10320,7 @@
       "hidden": false,
       "docExempt": false,
       "filePath": "src/app/components/reveal.tsx",
-      "description": "Reveal — reveal-on-scroll primitive via CSS scroll-driven animation. purely by scroll position (`animation-timeline: view()`) — no JS, no deps, no IntersectionObserver. Reach for this before hand-rolling reveal logic. `animation-timeline` is supported AND the user has not requested reduced motion (both fall back to visible, never stuck hidden). Pick `animation` from the fixed set — do not hand-roll keyframes. For momentum/inertia scrolling wrap the app in `SmoothScroll`; for a scroll-progress value in JS use `useScrollProgress` — both from `@hirobius/design-system/scroll`. See ADR-021.",
+      "description": "Reveal — reveal-on-scroll primitive via CSS scroll-driven animation.",
       "figmaUrl": null,
       "figmaId": null,
       "figmaLink": null,
@@ -9392,7 +10382,8 @@
         "patterns-scroll--simple-parallax",
         "primitives-reveal--animations",
         "primitives-reveal--scale-reveal-scene"
-      ]
+      ],
+      "aiRules": "Content is fully visible by DEFAULT; the effect applies only where `animation-timeline` is supported AND the user has not requested reduced motion (both fall back to visible, never stuck hidden). Pick `animation` from the fixed set — do not hand-roll keyframes. For momentum/inertia scrolling wrap the app in `SmoothScroll`; for a scroll-progress value in JS use `useScrollProgress` — both from `@hirobius/design-system/scroll`. See ADR-021."
     },
     "Textarea": {
       "category": "Inputs",
@@ -9411,6 +10402,8 @@
         "sizing": "panel"
       },
       "consumers": [
+        "src/app/components/input.tsx",
+        "src/stories/patterns-client-detail.stories.tsx",
         "src/stories/textarea.stories.tsx"
       ],
       "tokenMapping": {},
@@ -9465,7 +10458,17 @@
         "primitives-textarea--disabled",
         "primitives-textarea--error",
         "primitives-textarea--with-helper"
-      ]
+      ],
+      "usage": {
+        "when": "Collect multi-line free text such as a message, note or description.",
+        "whenNot": "A single line of text, or choosing from a list.",
+        "useInstead": [
+          {
+            "component": "Input",
+            "reason": "a single line of text"
+          }
+        ]
+      }
     },
     "CardBody": {
       "category": "Display",
@@ -9483,7 +10486,9 @@
         "exportName": "CardBody",
         "sizing": "panel"
       },
-      "consumers": [],
+      "consumers": [
+        "src/app/components/card.test.tsx"
+      ],
       "tokenMapping": {},
       "variantAxes": [],
       "componentProperties": [],
@@ -9526,7 +10531,9 @@
         "exportName": "CardDescription",
         "sizing": "panel"
       },
-      "consumers": [],
+      "consumers": [
+        "src/app/components/card.test.tsx"
+      ],
       "tokenMapping": {},
       "variantAxes": [],
       "componentProperties": [],
@@ -9569,7 +10576,9 @@
         "exportName": "CardFooter",
         "sizing": "panel"
       },
-      "consumers": [],
+      "consumers": [
+        "src/app/components/card.test.tsx"
+      ],
       "tokenMapping": {},
       "variantAxes": [],
       "componentProperties": [],
@@ -9612,7 +10621,9 @@
         "exportName": "CardHeader",
         "sizing": "panel"
       },
-      "consumers": [],
+      "consumers": [
+        "src/app/components/card.test.tsx"
+      ],
       "tokenMapping": {},
       "variantAxes": [],
       "componentProperties": [],
@@ -9651,7 +10662,7 @@
       "hidden": false,
       "docExempt": false,
       "filePath": "src/app/components/card.tsx",
-      "description": "Card — surface container with slot anatomy (12d-card-anatomy). Slot anatomy (DESIGN.md §\"Card Anatomy\"). Status, progress, and metadata are layout-bearing — they live in slots, never inline next to prose. <Card variant=\"accent\"> <Card.Header metadata={<Badge tone=\"warning\">in-progress</Badge>}> <Card.Title>Discovery phase</Card.Title> <Card.Description>Stakeholder interviews and audit prep.</Card.Description> </Card.Header> <Card.Progress value={42} max={100} label=\"5 / 12 tasks\" /> <Card.Metric label=\"Retainer\" value=\"$3,500\" sub=\"Active\" /> <Card.Body>…</Card.Body> <Card.Footer>…</Card.Footer> </Card> Slot reservations: - Header: title (h3) + optional description (caption) + optional metadata zone (right-aligned, holds <Badge> / <Tag> for status, never raw spans). - Progress: full-width 4px bar in a reserved 16px vertical rail. Owns its spacing — never crowds adjacent prose. - Metric: single label-uppercase + big value (h2) + optional sub-line. Reserved vertical block. Use multiple side-by-side via flex/grid container. - Body: prose, lists, structured content. NO inline status, progress, or thin colored bars. Group sections via separate <Card.Body> blocks. - Footer: actions, secondary metadata, timestamps. `variant`: 'default' (borderless) | 'accent' (2px accent border) — the structural axis, for highlighted entries like \"recommended package\". `tone`: neutral | danger | success | warning | info — the fixed feedback axis (#60 variant contract), for status-driven cards where the border IS the signal. `variant`/`tone` together replace hand-rolled `pkgHighlight`-style overrides. Legacy props (padding / gap / noPadding / as / style) are retained. Existing callers that pass raw children continue to work; new callers should prefer compound parts + `padding=\"none\"`. Depth comes from semantic.color.border.default (role.border) at rest; elevation tokens are not bound by default — pass `className=\"shadow-...\"` for a hover/floating treatment on interactive cards.",
+      "description": "Card.Metric — one uppercase label, a large value and an optional sub-line inside a Card.",
       "figmaUrl": null,
       "figmaId": null,
       "figmaLink": null,
@@ -9660,7 +10671,9 @@
         "exportName": "CardMetric",
         "sizing": "panel"
       },
-      "consumers": [],
+      "consumers": [
+        "src/app/components/card.test.tsx"
+      ],
       "tokenMapping": {},
       "variantAxes": [],
       "componentProperties": [],
@@ -9707,7 +10720,11 @@
         "primitives-card--padding-variants",
         "primitives-card--progress-slot",
         "primitives-card--variant-accent"
-      ]
+      ],
+      "usage": {
+        "when": "Show one headline figure (a KPI, a count, a total) with its label inside a Card.",
+        "whenNot": "A metric outside a Card, or several figures that share one label."
+      }
     },
     "CardProgress": {
       "category": "Display",
@@ -9725,7 +10742,9 @@
         "exportName": "CardProgress",
         "sizing": "panel"
       },
-      "consumers": [],
+      "consumers": [
+        "src/app/components/card.test.tsx"
+      ],
       "tokenMapping": {},
       "variantAxes": [],
       "componentProperties": [],
@@ -9791,7 +10810,9 @@
         "exportName": "CardTitle",
         "sizing": "panel"
       },
-      "consumers": [],
+      "consumers": [
+        "src/app/components/card.test.tsx"
+      ],
       "tokenMapping": {},
       "variantAxes": [],
       "componentProperties": [],
@@ -9825,7 +10846,7 @@
       "hidden": false,
       "docExempt": true,
       "filePath": "src/app/components/dialog.tsx",
-      "description": "Dialog — modal dialog (shadcn baseline, compound parts). shadcn-baseline implementation (8s-7): Radix Dialog primitive (@radix-ui/react-dialog) themed with role tokens. Provides focus trap, scroll lock, ESC-to-close, backdrop scrim, and portal mounting out of the box. <Dialog> <Dialog.Trigger asChild> <Button>Open</Button> </Dialog.Trigger> <Dialog.Content> <Dialog.Header> <Dialog.Title>Confirm</Dialog.Title> <Dialog.Description>Are you sure?</Dialog.Description> </Dialog.Header> <Dialog.Footer> <Dialog.Close asChild> <Button variant=\"secondary\">Cancel</Button> </Dialog.Close> </Dialog.Footer> </Dialog.Content> </Dialog> Surface uses role.popover (semantic.color.surface.overlay) + shadow-overlay (semantic.shadow.overlay from 8e-1). The scrim is a foreground/80 wash so it picks up the theme without a hardcoded black. The close affordance is rendered as an absolutely-positioned X inside Content; pass `hideClose` to opt out for fully-custom layouts.",
+      "description": "Dialog — modal dialog (shadcn baseline, compound parts). shadcn-baseline implementation (8s-7): Radix Dialog primitive (@radix-ui/react-dialog) themed with role tokens. Provides focus trap, scroll lock, ESC-to-close, backdrop scrim, and portal mounting out of the box. <Dialog> <Dialog.Trigger asChild> <Button>Open</Button> </Dialog.Trigger> <Dialog.Content> <Dialog.Header> <Dialog.Title>Confirm</Dialog.Title> <Dialog.Description>Are you sure?</Dialog.Description> </Dialog.Header> <Dialog.Footer> <Dialog.Close asChild> <Button variant=\"secondary\">Cancel</Button> </Dialog.Close> </Dialog.Footer> </Dialog.Content> </Dialog> Surface uses role.popover (semantic.color.surface.overlay) + shadow-overlay (semantic.shadow.overlay from 8e-1). The scrim is role.scrim (semantic.color.surface.scrim) at 60% alpha: dark in both themes, black in dark mode. The overlay portals into the nearest `data-hds` scope so it inherits the active theme; pass `container` to override. The close affordance is rendered as an absolutely-positioned X inside Content; pass `hideClose` to opt out for fully-custom layouts.",
       "figmaUrl": null,
       "figmaId": null,
       "figmaLink": null,
@@ -9834,7 +10855,9 @@
         "exportName": "DialogClose",
         "sizing": "panel"
       },
-      "consumers": [],
+      "consumers": [
+        "src/app/components/dialog.test.tsx"
+      ],
       "tokenMapping": {},
       "variantAxes": [],
       "componentProperties": [],
@@ -9854,6 +10877,7 @@
         "src/stories/dialog.stories.tsx"
       ],
       "storyIds": [
+        "primitives-dialog--dark-scope",
         "primitives-dialog--default",
         "primitives-dialog--destructive",
         "primitives-dialog--information",
@@ -9867,7 +10891,7 @@
       "hidden": false,
       "docExempt": true,
       "filePath": "src/app/components/dialog.tsx",
-      "description": "Dialog — modal dialog (shadcn baseline, compound parts). shadcn-baseline implementation (8s-7): Radix Dialog primitive (@radix-ui/react-dialog) themed with role tokens. Provides focus trap, scroll lock, ESC-to-close, backdrop scrim, and portal mounting out of the box. <Dialog> <Dialog.Trigger asChild> <Button>Open</Button> </Dialog.Trigger> <Dialog.Content> <Dialog.Header> <Dialog.Title>Confirm</Dialog.Title> <Dialog.Description>Are you sure?</Dialog.Description> </Dialog.Header> <Dialog.Footer> <Dialog.Close asChild> <Button variant=\"secondary\">Cancel</Button> </Dialog.Close> </Dialog.Footer> </Dialog.Content> </Dialog> Surface uses role.popover (semantic.color.surface.overlay) + shadow-overlay (semantic.shadow.overlay from 8e-1). The scrim is a foreground/80 wash so it picks up the theme without a hardcoded black. The close affordance is rendered as an absolutely-positioned X inside Content; pass `hideClose` to opt out for fully-custom layouts.",
+      "description": "Dialog — modal dialog (shadcn baseline, compound parts). shadcn-baseline implementation (8s-7): Radix Dialog primitive (@radix-ui/react-dialog) themed with role tokens. Provides focus trap, scroll lock, ESC-to-close, backdrop scrim, and portal mounting out of the box. <Dialog> <Dialog.Trigger asChild> <Button>Open</Button> </Dialog.Trigger> <Dialog.Content> <Dialog.Header> <Dialog.Title>Confirm</Dialog.Title> <Dialog.Description>Are you sure?</Dialog.Description> </Dialog.Header> <Dialog.Footer> <Dialog.Close asChild> <Button variant=\"secondary\">Cancel</Button> </Dialog.Close> </Dialog.Footer> </Dialog.Content> </Dialog> Surface uses role.popover (semantic.color.surface.overlay) + shadow-overlay (semantic.shadow.overlay from 8e-1). The scrim is role.scrim (semantic.color.surface.scrim) at 60% alpha: dark in both themes, black in dark mode. The overlay portals into the nearest `data-hds` scope so it inherits the active theme; pass `container` to override. The close affordance is rendered as an absolutely-positioned X inside Content; pass `hideClose` to opt out for fully-custom layouts.",
       "figmaUrl": null,
       "figmaId": null,
       "figmaLink": null,
@@ -9876,7 +10900,9 @@
         "exportName": "DialogContent",
         "sizing": "panel"
       },
-      "consumers": [],
+      "consumers": [
+        "src/app/components/dialog.test.tsx"
+      ],
       "tokenMapping": {},
       "variantAxes": [],
       "componentProperties": [],
@@ -9900,6 +10926,7 @@
         "src/stories/dialog.stories.tsx"
       ],
       "storyIds": [
+        "primitives-dialog--dark-scope",
         "primitives-dialog--default",
         "primitives-dialog--destructive",
         "primitives-dialog--information",
@@ -9913,7 +10940,7 @@
       "hidden": false,
       "docExempt": true,
       "filePath": "src/app/components/dialog.tsx",
-      "description": "Dialog — modal dialog (shadcn baseline, compound parts). shadcn-baseline implementation (8s-7): Radix Dialog primitive (@radix-ui/react-dialog) themed with role tokens. Provides focus trap, scroll lock, ESC-to-close, backdrop scrim, and portal mounting out of the box. <Dialog> <Dialog.Trigger asChild> <Button>Open</Button> </Dialog.Trigger> <Dialog.Content> <Dialog.Header> <Dialog.Title>Confirm</Dialog.Title> <Dialog.Description>Are you sure?</Dialog.Description> </Dialog.Header> <Dialog.Footer> <Dialog.Close asChild> <Button variant=\"secondary\">Cancel</Button> </Dialog.Close> </Dialog.Footer> </Dialog.Content> </Dialog> Surface uses role.popover (semantic.color.surface.overlay) + shadow-overlay (semantic.shadow.overlay from 8e-1). The scrim is a foreground/80 wash so it picks up the theme without a hardcoded black. The close affordance is rendered as an absolutely-positioned X inside Content; pass `hideClose` to opt out for fully-custom layouts.",
+      "description": "Dialog — modal dialog (shadcn baseline, compound parts). shadcn-baseline implementation (8s-7): Radix Dialog primitive (@radix-ui/react-dialog) themed with role tokens. Provides focus trap, scroll lock, ESC-to-close, backdrop scrim, and portal mounting out of the box. <Dialog> <Dialog.Trigger asChild> <Button>Open</Button> </Dialog.Trigger> <Dialog.Content> <Dialog.Header> <Dialog.Title>Confirm</Dialog.Title> <Dialog.Description>Are you sure?</Dialog.Description> </Dialog.Header> <Dialog.Footer> <Dialog.Close asChild> <Button variant=\"secondary\">Cancel</Button> </Dialog.Close> </Dialog.Footer> </Dialog.Content> </Dialog> Surface uses role.popover (semantic.color.surface.overlay) + shadow-overlay (semantic.shadow.overlay from 8e-1). The scrim is role.scrim (semantic.color.surface.scrim) at 60% alpha: dark in both themes, black in dark mode. The overlay portals into the nearest `data-hds` scope so it inherits the active theme; pass `container` to override. The close affordance is rendered as an absolutely-positioned X inside Content; pass `hideClose` to opt out for fully-custom layouts.",
       "figmaUrl": null,
       "figmaId": null,
       "figmaLink": null,
@@ -9922,7 +10949,9 @@
         "exportName": "DialogDescription",
         "sizing": "panel"
       },
-      "consumers": [],
+      "consumers": [
+        "src/app/components/dialog.test.tsx"
+      ],
       "tokenMapping": {},
       "variantAxes": [],
       "componentProperties": [],
@@ -9942,6 +10971,7 @@
         "src/stories/dialog.stories.tsx"
       ],
       "storyIds": [
+        "primitives-dialog--dark-scope",
         "primitives-dialog--default",
         "primitives-dialog--destructive",
         "primitives-dialog--information",
@@ -9955,7 +10985,7 @@
       "hidden": false,
       "docExempt": true,
       "filePath": "src/app/components/dialog.tsx",
-      "description": "Dialog — modal dialog (shadcn baseline, compound parts). shadcn-baseline implementation (8s-7): Radix Dialog primitive (@radix-ui/react-dialog) themed with role tokens. Provides focus trap, scroll lock, ESC-to-close, backdrop scrim, and portal mounting out of the box. <Dialog> <Dialog.Trigger asChild> <Button>Open</Button> </Dialog.Trigger> <Dialog.Content> <Dialog.Header> <Dialog.Title>Confirm</Dialog.Title> <Dialog.Description>Are you sure?</Dialog.Description> </Dialog.Header> <Dialog.Footer> <Dialog.Close asChild> <Button variant=\"secondary\">Cancel</Button> </Dialog.Close> </Dialog.Footer> </Dialog.Content> </Dialog> Surface uses role.popover (semantic.color.surface.overlay) + shadow-overlay (semantic.shadow.overlay from 8e-1). The scrim is a foreground/80 wash so it picks up the theme without a hardcoded black. The close affordance is rendered as an absolutely-positioned X inside Content; pass `hideClose` to opt out for fully-custom layouts.",
+      "description": "Dialog — modal dialog (shadcn baseline, compound parts). shadcn-baseline implementation (8s-7): Radix Dialog primitive (@radix-ui/react-dialog) themed with role tokens. Provides focus trap, scroll lock, ESC-to-close, backdrop scrim, and portal mounting out of the box. <Dialog> <Dialog.Trigger asChild> <Button>Open</Button> </Dialog.Trigger> <Dialog.Content> <Dialog.Header> <Dialog.Title>Confirm</Dialog.Title> <Dialog.Description>Are you sure?</Dialog.Description> </Dialog.Header> <Dialog.Footer> <Dialog.Close asChild> <Button variant=\"secondary\">Cancel</Button> </Dialog.Close> </Dialog.Footer> </Dialog.Content> </Dialog> Surface uses role.popover (semantic.color.surface.overlay) + shadow-overlay (semantic.shadow.overlay from 8e-1). The scrim is role.scrim (semantic.color.surface.scrim) at 60% alpha: dark in both themes, black in dark mode. The overlay portals into the nearest `data-hds` scope so it inherits the active theme; pass `container` to override. The close affordance is rendered as an absolutely-positioned X inside Content; pass `hideClose` to opt out for fully-custom layouts.",
       "figmaUrl": null,
       "figmaId": null,
       "figmaLink": null,
@@ -9964,7 +10994,9 @@
         "exportName": "DialogFooter",
         "sizing": "panel"
       },
-      "consumers": [],
+      "consumers": [
+        "src/app/components/dialog.test.tsx"
+      ],
       "tokenMapping": {},
       "variantAxes": [],
       "componentProperties": [],
@@ -9979,6 +11011,7 @@
         "src/stories/dialog.stories.tsx"
       ],
       "storyIds": [
+        "primitives-dialog--dark-scope",
         "primitives-dialog--default",
         "primitives-dialog--destructive",
         "primitives-dialog--information",
@@ -9992,7 +11025,7 @@
       "hidden": false,
       "docExempt": true,
       "filePath": "src/app/components/dialog.tsx",
-      "description": "Dialog — modal dialog (shadcn baseline, compound parts). shadcn-baseline implementation (8s-7): Radix Dialog primitive (@radix-ui/react-dialog) themed with role tokens. Provides focus trap, scroll lock, ESC-to-close, backdrop scrim, and portal mounting out of the box. <Dialog> <Dialog.Trigger asChild> <Button>Open</Button> </Dialog.Trigger> <Dialog.Content> <Dialog.Header> <Dialog.Title>Confirm</Dialog.Title> <Dialog.Description>Are you sure?</Dialog.Description> </Dialog.Header> <Dialog.Footer> <Dialog.Close asChild> <Button variant=\"secondary\">Cancel</Button> </Dialog.Close> </Dialog.Footer> </Dialog.Content> </Dialog> Surface uses role.popover (semantic.color.surface.overlay) + shadow-overlay (semantic.shadow.overlay from 8e-1). The scrim is a foreground/80 wash so it picks up the theme without a hardcoded black. The close affordance is rendered as an absolutely-positioned X inside Content; pass `hideClose` to opt out for fully-custom layouts.",
+      "description": "Dialog — modal dialog (shadcn baseline, compound parts). shadcn-baseline implementation (8s-7): Radix Dialog primitive (@radix-ui/react-dialog) themed with role tokens. Provides focus trap, scroll lock, ESC-to-close, backdrop scrim, and portal mounting out of the box. <Dialog> <Dialog.Trigger asChild> <Button>Open</Button> </Dialog.Trigger> <Dialog.Content> <Dialog.Header> <Dialog.Title>Confirm</Dialog.Title> <Dialog.Description>Are you sure?</Dialog.Description> </Dialog.Header> <Dialog.Footer> <Dialog.Close asChild> <Button variant=\"secondary\">Cancel</Button> </Dialog.Close> </Dialog.Footer> </Dialog.Content> </Dialog> Surface uses role.popover (semantic.color.surface.overlay) + shadow-overlay (semantic.shadow.overlay from 8e-1). The scrim is role.scrim (semantic.color.surface.scrim) at 60% alpha: dark in both themes, black in dark mode. The overlay portals into the nearest `data-hds` scope so it inherits the active theme; pass `container` to override. The close affordance is rendered as an absolutely-positioned X inside Content; pass `hideClose` to opt out for fully-custom layouts.",
       "figmaUrl": null,
       "figmaId": null,
       "figmaLink": null,
@@ -10001,7 +11034,9 @@
         "exportName": "DialogHeader",
         "sizing": "panel"
       },
-      "consumers": [],
+      "consumers": [
+        "src/app/components/dialog.test.tsx"
+      ],
       "tokenMapping": {},
       "variantAxes": [],
       "componentProperties": [],
@@ -10016,6 +11051,7 @@
         "src/stories/dialog.stories.tsx"
       ],
       "storyIds": [
+        "primitives-dialog--dark-scope",
         "primitives-dialog--default",
         "primitives-dialog--destructive",
         "primitives-dialog--information",
@@ -10029,7 +11065,7 @@
       "hidden": false,
       "docExempt": true,
       "filePath": "src/app/components/dialog.tsx",
-      "description": "Dialog — modal dialog (shadcn baseline, compound parts). shadcn-baseline implementation (8s-7): Radix Dialog primitive (@radix-ui/react-dialog) themed with role tokens. Provides focus trap, scroll lock, ESC-to-close, backdrop scrim, and portal mounting out of the box. <Dialog> <Dialog.Trigger asChild> <Button>Open</Button> </Dialog.Trigger> <Dialog.Content> <Dialog.Header> <Dialog.Title>Confirm</Dialog.Title> <Dialog.Description>Are you sure?</Dialog.Description> </Dialog.Header> <Dialog.Footer> <Dialog.Close asChild> <Button variant=\"secondary\">Cancel</Button> </Dialog.Close> </Dialog.Footer> </Dialog.Content> </Dialog> Surface uses role.popover (semantic.color.surface.overlay) + shadow-overlay (semantic.shadow.overlay from 8e-1). The scrim is a foreground/80 wash so it picks up the theme without a hardcoded black. The close affordance is rendered as an absolutely-positioned X inside Content; pass `hideClose` to opt out for fully-custom layouts.",
+      "description": "Dialog — modal dialog (shadcn baseline, compound parts). shadcn-baseline implementation (8s-7): Radix Dialog primitive (@radix-ui/react-dialog) themed with role tokens. Provides focus trap, scroll lock, ESC-to-close, backdrop scrim, and portal mounting out of the box. <Dialog> <Dialog.Trigger asChild> <Button>Open</Button> </Dialog.Trigger> <Dialog.Content> <Dialog.Header> <Dialog.Title>Confirm</Dialog.Title> <Dialog.Description>Are you sure?</Dialog.Description> </Dialog.Header> <Dialog.Footer> <Dialog.Close asChild> <Button variant=\"secondary\">Cancel</Button> </Dialog.Close> </Dialog.Footer> </Dialog.Content> </Dialog> Surface uses role.popover (semantic.color.surface.overlay) + shadow-overlay (semantic.shadow.overlay from 8e-1). The scrim is role.scrim (semantic.color.surface.scrim) at 60% alpha: dark in both themes, black in dark mode. The overlay portals into the nearest `data-hds` scope so it inherits the active theme; pass `container` to override. The close affordance is rendered as an absolutely-positioned X inside Content; pass `hideClose` to opt out for fully-custom layouts.",
       "figmaUrl": null,
       "figmaId": null,
       "figmaLink": null,
@@ -10038,7 +11074,9 @@
         "exportName": "DialogOverlay",
         "sizing": "panel"
       },
-      "consumers": [],
+      "consumers": [
+        "src/app/components/dialog.test.tsx"
+      ],
       "tokenMapping": {},
       "variantAxes": [],
       "componentProperties": [],
@@ -10058,6 +11096,7 @@
         "src/stories/dialog.stories.tsx"
       ],
       "storyIds": [
+        "primitives-dialog--dark-scope",
         "primitives-dialog--default",
         "primitives-dialog--destructive",
         "primitives-dialog--information",
@@ -10071,7 +11110,7 @@
       "hidden": false,
       "docExempt": true,
       "filePath": "src/app/components/dialog.tsx",
-      "description": "Dialog — modal dialog (shadcn baseline, compound parts). shadcn-baseline implementation (8s-7): Radix Dialog primitive (@radix-ui/react-dialog) themed with role tokens. Provides focus trap, scroll lock, ESC-to-close, backdrop scrim, and portal mounting out of the box. <Dialog> <Dialog.Trigger asChild> <Button>Open</Button> </Dialog.Trigger> <Dialog.Content> <Dialog.Header> <Dialog.Title>Confirm</Dialog.Title> <Dialog.Description>Are you sure?</Dialog.Description> </Dialog.Header> <Dialog.Footer> <Dialog.Close asChild> <Button variant=\"secondary\">Cancel</Button> </Dialog.Close> </Dialog.Footer> </Dialog.Content> </Dialog> Surface uses role.popover (semantic.color.surface.overlay) + shadow-overlay (semantic.shadow.overlay from 8e-1). The scrim is a foreground/80 wash so it picks up the theme without a hardcoded black. The close affordance is rendered as an absolutely-positioned X inside Content; pass `hideClose` to opt out for fully-custom layouts.",
+      "description": "Dialog — modal dialog (shadcn baseline, compound parts). shadcn-baseline implementation (8s-7): Radix Dialog primitive (@radix-ui/react-dialog) themed with role tokens. Provides focus trap, scroll lock, ESC-to-close, backdrop scrim, and portal mounting out of the box. <Dialog> <Dialog.Trigger asChild> <Button>Open</Button> </Dialog.Trigger> <Dialog.Content> <Dialog.Header> <Dialog.Title>Confirm</Dialog.Title> <Dialog.Description>Are you sure?</Dialog.Description> </Dialog.Header> <Dialog.Footer> <Dialog.Close asChild> <Button variant=\"secondary\">Cancel</Button> </Dialog.Close> </Dialog.Footer> </Dialog.Content> </Dialog> Surface uses role.popover (semantic.color.surface.overlay) + shadow-overlay (semantic.shadow.overlay from 8e-1). The scrim is role.scrim (semantic.color.surface.scrim) at 60% alpha: dark in both themes, black in dark mode. The overlay portals into the nearest `data-hds` scope so it inherits the active theme; pass `container` to override. The close affordance is rendered as an absolutely-positioned X inside Content; pass `hideClose` to opt out for fully-custom layouts.",
       "figmaUrl": null,
       "figmaId": null,
       "figmaLink": null,
@@ -10080,7 +11119,9 @@
         "exportName": "DialogPortal",
         "sizing": "panel"
       },
-      "consumers": [],
+      "consumers": [
+        "src/app/components/dialog.test.tsx"
+      ],
       "tokenMapping": {},
       "variantAxes": [],
       "componentProperties": [],
@@ -10095,6 +11136,7 @@
         "src/stories/dialog.stories.tsx"
       ],
       "storyIds": [
+        "primitives-dialog--dark-scope",
         "primitives-dialog--default",
         "primitives-dialog--destructive",
         "primitives-dialog--information",
@@ -10108,7 +11150,7 @@
       "hidden": false,
       "docExempt": true,
       "filePath": "src/app/components/dialog.tsx",
-      "description": "Dialog — modal dialog (shadcn baseline, compound parts). shadcn-baseline implementation (8s-7): Radix Dialog primitive (@radix-ui/react-dialog) themed with role tokens. Provides focus trap, scroll lock, ESC-to-close, backdrop scrim, and portal mounting out of the box. <Dialog> <Dialog.Trigger asChild> <Button>Open</Button> </Dialog.Trigger> <Dialog.Content> <Dialog.Header> <Dialog.Title>Confirm</Dialog.Title> <Dialog.Description>Are you sure?</Dialog.Description> </Dialog.Header> <Dialog.Footer> <Dialog.Close asChild> <Button variant=\"secondary\">Cancel</Button> </Dialog.Close> </Dialog.Footer> </Dialog.Content> </Dialog> Surface uses role.popover (semantic.color.surface.overlay) + shadow-overlay (semantic.shadow.overlay from 8e-1). The scrim is a foreground/80 wash so it picks up the theme without a hardcoded black. The close affordance is rendered as an absolutely-positioned X inside Content; pass `hideClose` to opt out for fully-custom layouts.",
+      "description": "Dialog — modal dialog (shadcn baseline, compound parts). shadcn-baseline implementation (8s-7): Radix Dialog primitive (@radix-ui/react-dialog) themed with role tokens. Provides focus trap, scroll lock, ESC-to-close, backdrop scrim, and portal mounting out of the box. <Dialog> <Dialog.Trigger asChild> <Button>Open</Button> </Dialog.Trigger> <Dialog.Content> <Dialog.Header> <Dialog.Title>Confirm</Dialog.Title> <Dialog.Description>Are you sure?</Dialog.Description> </Dialog.Header> <Dialog.Footer> <Dialog.Close asChild> <Button variant=\"secondary\">Cancel</Button> </Dialog.Close> </Dialog.Footer> </Dialog.Content> </Dialog> Surface uses role.popover (semantic.color.surface.overlay) + shadow-overlay (semantic.shadow.overlay from 8e-1). The scrim is role.scrim (semantic.color.surface.scrim) at 60% alpha: dark in both themes, black in dark mode. The overlay portals into the nearest `data-hds` scope so it inherits the active theme; pass `container` to override. The close affordance is rendered as an absolutely-positioned X inside Content; pass `hideClose` to opt out for fully-custom layouts.",
       "figmaUrl": null,
       "figmaId": null,
       "figmaLink": null,
@@ -10117,7 +11159,9 @@
         "exportName": "DialogTitle",
         "sizing": "panel"
       },
-      "consumers": [],
+      "consumers": [
+        "src/app/components/dialog.test.tsx"
+      ],
       "tokenMapping": {},
       "variantAxes": [],
       "componentProperties": [],
@@ -10137,6 +11181,7 @@
         "src/stories/dialog.stories.tsx"
       ],
       "storyIds": [
+        "primitives-dialog--dark-scope",
         "primitives-dialog--default",
         "primitives-dialog--destructive",
         "primitives-dialog--information",
@@ -10150,7 +11195,7 @@
       "hidden": false,
       "docExempt": true,
       "filePath": "src/app/components/dialog.tsx",
-      "description": "Dialog — modal dialog (shadcn baseline, compound parts). shadcn-baseline implementation (8s-7): Radix Dialog primitive (@radix-ui/react-dialog) themed with role tokens. Provides focus trap, scroll lock, ESC-to-close, backdrop scrim, and portal mounting out of the box. <Dialog> <Dialog.Trigger asChild> <Button>Open</Button> </Dialog.Trigger> <Dialog.Content> <Dialog.Header> <Dialog.Title>Confirm</Dialog.Title> <Dialog.Description>Are you sure?</Dialog.Description> </Dialog.Header> <Dialog.Footer> <Dialog.Close asChild> <Button variant=\"secondary\">Cancel</Button> </Dialog.Close> </Dialog.Footer> </Dialog.Content> </Dialog> Surface uses role.popover (semantic.color.surface.overlay) + shadow-overlay (semantic.shadow.overlay from 8e-1). The scrim is a foreground/80 wash so it picks up the theme without a hardcoded black. The close affordance is rendered as an absolutely-positioned X inside Content; pass `hideClose` to opt out for fully-custom layouts.",
+      "description": "Dialog — modal dialog (shadcn baseline, compound parts). shadcn-baseline implementation (8s-7): Radix Dialog primitive (@radix-ui/react-dialog) themed with role tokens. Provides focus trap, scroll lock, ESC-to-close, backdrop scrim, and portal mounting out of the box. <Dialog> <Dialog.Trigger asChild> <Button>Open</Button> </Dialog.Trigger> <Dialog.Content> <Dialog.Header> <Dialog.Title>Confirm</Dialog.Title> <Dialog.Description>Are you sure?</Dialog.Description> </Dialog.Header> <Dialog.Footer> <Dialog.Close asChild> <Button variant=\"secondary\">Cancel</Button> </Dialog.Close> </Dialog.Footer> </Dialog.Content> </Dialog> Surface uses role.popover (semantic.color.surface.overlay) + shadow-overlay (semantic.shadow.overlay from 8e-1). The scrim is role.scrim (semantic.color.surface.scrim) at 60% alpha: dark in both themes, black in dark mode. The overlay portals into the nearest `data-hds` scope so it inherits the active theme; pass `container` to override. The close affordance is rendered as an absolutely-positioned X inside Content; pass `hideClose` to opt out for fully-custom layouts.",
       "figmaUrl": null,
       "figmaId": null,
       "figmaLink": null,
@@ -10159,7 +11204,9 @@
         "exportName": "DialogTrigger",
         "sizing": "panel"
       },
-      "consumers": [],
+      "consumers": [
+        "src/app/components/dialog.test.tsx"
+      ],
       "tokenMapping": {},
       "variantAxes": [],
       "componentProperties": [],
@@ -10179,6 +11226,7 @@
         "src/stories/dialog.stories.tsx"
       ],
       "storyIds": [
+        "primitives-dialog--dark-scope",
         "primitives-dialog--default",
         "primitives-dialog--destructive",
         "primitives-dialog--information",
@@ -10203,6 +11251,8 @@
       "consumers": [
         "src/app/components/asset-img.tsx",
         "src/app/components/hover-card.tsx",
+        "src/app/context/__tests__/portal-hydration.test.tsx",
+        "src/app/context/__tests__/portal-scope.test.tsx",
         "src/app/data/hdsEditorial.tsx",
         "src/index.ts",
         "src/stories/hds-tooltip.stories.tsx"
@@ -10243,13 +11293,19 @@
         "sizing": "panel"
       },
       "consumers": [
+        "src/app/components/combobox.tsx",
         "src/app/components/command-palette.tsx",
         "src/app/components/context-menu.tsx",
+        "src/app/components/data-table-section.tsx",
         "src/app/components/date-range-input.tsx",
         "src/app/components/hover-card.tsx",
         "src/app/components/menu.test.tsx",
         "src/app/components/multi-selector.tsx",
+        "src/app/components/select.tsx",
+        "src/app/context/__tests__/portal-hydration.test.tsx",
+        "src/app/context/__tests__/portal-scope.test.tsx",
         "src/docs-tooling/shell-controls.tsx",
+        "src/stories/context-menu.stories.tsx",
         "src/stories/menu.stories.tsx"
       ],
       "tokenMapping": {},
@@ -10270,6 +11326,58 @@
         "primitives-menu--with-checkbox-items",
         "primitives-menu--with-radio-group",
         "primitives-menu--with-submenu"
+      ],
+      "slots": [
+        {
+          "name": "trigger",
+          "description": "The element that opens the menu (Menu.Trigger).",
+          "source": "jsdoc"
+        },
+        {
+          "name": "content",
+          "description": "The popup holding the items (Menu.Content).",
+          "source": "jsdoc"
+        }
+      ],
+      "usage": {
+        "when": "Offer a list of actions from a trigger, closed until opened.",
+        "whenNot": "Choosing one value for a form field, or a set of options that must stay visible.",
+        "useInstead": [
+          {
+            "component": "Select",
+            "reason": "choosing a value for a form field"
+          }
+        ]
+      },
+      "keyboard": [
+        {
+          "keys": "Enter/Space/ArrowDown",
+          "effect": "Opens the menu from the trigger and highlights the first item."
+        },
+        {
+          "keys": "ArrowDown/ArrowUp",
+          "effect": "Moves the highlight; it stops at the first and last item."
+        },
+        {
+          "keys": "Home/End",
+          "effect": "Jumps to the first or last item."
+        },
+        {
+          "keys": "Character",
+          "effect": "Highlights the next item that starts with the typed letter."
+        },
+        {
+          "keys": "Enter",
+          "effect": "Selects the highlighted item and closes the menu."
+        },
+        {
+          "keys": "Escape",
+          "effect": "Closes the menu and returns focus to the trigger."
+        },
+        {
+          "keys": "Tab",
+          "effect": "Does not leave the open menu."
+        }
       ]
     },
     "Popover": {
@@ -10303,6 +11411,8 @@
         "src/app/components/multi-selector.test.tsx",
         "src/app/components/multi-selector.tsx",
         "src/app/components/popover.test.tsx",
+        "src/app/context/__tests__/portal-hydration.test.tsx",
+        "src/app/context/__tests__/portal-scope.test.tsx",
         "src/app/design-system/generated-token-descriptions.ts",
         "src/stories/combobox.stories.tsx",
         "src/stories/date-input.stories.tsx",
@@ -10416,6 +11526,7 @@
       "consumers": [
         "src/app/components/checkbox.test.tsx",
         "src/app/components/radio.tsx",
+        "src/app/components/toggle.tsx",
         "src/index.ts",
         "src/stories/checkbox.stories.tsx"
       ],
@@ -10453,6 +11564,393 @@
         "primitives-checkbox--disabled-checked",
         "primitives-checkbox--group",
         "primitives-checkbox--indeterminate"
+      ],
+      "usage": {
+        "when": "Let people tick one or more independent options, or a parent choice that is partly selected.",
+        "whenNot": "An immediate on/off setting, or a choice of exactly one option from a set.",
+        "useInstead": [
+          {
+            "component": "Toggle",
+            "reason": "a setting that applies as soon as it flips"
+          },
+          {
+            "component": "Radio",
+            "reason": "exactly one choice from a set"
+          }
+        ]
+      }
+    },
+    "FormActions": {
+      "category": "Actions",
+      "categorySource": "jsdoc",
+      "governedCategory": true,
+      "hidden": false,
+      "docExempt": false,
+      "filePath": "src/app/components/form-actions.tsx",
+      "description": "Form footer with one fixed order: destructive (far left, if any), then secondary, then primary last and right-most. Gap is the tight layout token.",
+      "figmaUrl": null,
+      "figmaId": null,
+      "figmaLink": null,
+      "tier": "pattern",
+      "preview": {
+        "exportName": "FormActions",
+        "sizing": "panel"
+      },
+      "consumers": [
+        "src/app/components/form-actions.test.tsx",
+        "src/stories/form-actions.stories.tsx",
+        "src/stories/patterns-client-detail.stories.tsx"
+      ],
+      "tokenMapping": {},
+      "variantAxes": [],
+      "componentProperties": [],
+      "props": {
+        "destructive": {
+          "type": "ReactNode",
+          "optional": true
+        },
+        "primary": {
+          "type": "ReactNode"
+        },
+        "secondary": {
+          "type": "ReactNode",
+          "optional": true
+        },
+        "sticky": {
+          "type": "boolean",
+          "default": false
+        }
+      },
+      "allowedChildren": [
+        "*"
+      ],
+      "propConstraints": {},
+      "requiredProps": [],
+      "a11yRules": [],
+      "storyFiles": [
+        "src/stories/form-actions.stories.tsx"
+      ],
+      "storyIds": [
+        "patterns-formactions--primary-only",
+        "patterns-formactions--sticky",
+        "patterns-formactions--with-destructive",
+        "patterns-formactions--with-secondary"
+      ]
+    },
+    "MetricTile": {
+      "category": "Display",
+      "categorySource": "jsdoc",
+      "governedCategory": true,
+      "hidden": false,
+      "docExempt": false,
+      "filePath": "src/app/components/metric-tiles.tsx",
+      "description": "One metric tile: eyebrow label, `heading2` value, caption sub line, on a raised surface at one fixed min-height. Wraps `Card.Metric` (the sibling with the eyebrow / h2 / caption scale) and adds the surface and the fixed height, so a tile needs no enclosing `Card`.",
+      "figmaUrl": null,
+      "figmaId": null,
+      "figmaLink": null,
+      "tier": "pattern",
+      "preview": {
+        "exportName": "MetricTile",
+        "sizing": "panel"
+      },
+      "consumers": [
+        "src/app/components/metric-tiles.test.tsx",
+        "src/stories/metric-tiles.stories.tsx",
+        "src/stories/patterns-client-detail.stories.tsx"
+      ],
+      "tokenMapping": {},
+      "variantAxes": [],
+      "componentProperties": [],
+      "props": {
+        "label": {
+          "type": "ReactNode"
+        },
+        "sub": {
+          "type": "ReactNode",
+          "optional": true
+        },
+        "tone": {
+          "type": "enum",
+          "values": [
+            "neutral",
+            "success",
+            "warning",
+            "danger",
+            "info"
+          ],
+          "default": "neutral"
+        },
+        "value": {
+          "type": "ReactNode"
+        }
+      },
+      "allowedChildren": [
+        "*"
+      ],
+      "propConstraints": {},
+      "requiredProps": [],
+      "a11yRules": [],
+      "storyFiles": [
+        "src/stories/metric-tiles.stories.tsx"
+      ],
+      "storyIds": [
+        "patterns-metrictiles--four-tiles",
+        "patterns-metrictiles--sub-line-optional",
+        "patterns-metrictiles--three-tiles",
+        "patterns-metrictiles--tones"
+      ]
+    },
+    "MetricTiles": {
+      "category": "Display",
+      "categorySource": "jsdoc",
+      "governedCategory": true,
+      "hidden": false,
+      "docExempt": false,
+      "filePath": "src/app/components/metric-tiles.tsx",
+      "description": "A row of `MetricTile`s. The grid has `min(tiles, 4)` columns, so three tiles fill three columns and never leave an empty fourth. The default for any row of headline numbers on a screen; use `Stat` only for an inline number inside prose or a dense list, `Card.Metric` only inside an existing `Card`, and `StatusTile` for state with notes (never a number).",
+      "figmaUrl": null,
+      "figmaId": null,
+      "figmaLink": null,
+      "tier": "pattern",
+      "preview": {
+        "exportName": "MetricTiles",
+        "sizing": "panel"
+      },
+      "consumers": [
+        "src/app/components/metric-tiles.test.tsx",
+        "src/stories/metric-tiles.stories.tsx",
+        "src/stories/patterns-client-detail.stories.tsx"
+      ],
+      "tokenMapping": {},
+      "variantAxes": [],
+      "componentProperties": [],
+      "props": {
+        "children": {
+          "type": "ReactNode"
+        }
+      },
+      "allowedChildren": [
+        "*"
+      ],
+      "propConstraints": {},
+      "requiredProps": [],
+      "a11yRules": [],
+      "storyFiles": [
+        "src/stories/metric-tiles.stories.tsx"
+      ],
+      "storyIds": [
+        "patterns-metrictiles--four-tiles",
+        "patterns-metrictiles--sub-line-optional",
+        "patterns-metrictiles--three-tiles",
+        "patterns-metrictiles--tones"
+      ]
+    },
+    "PageHeader": {
+      "category": "Layout",
+      "categorySource": "jsdoc",
+      "governedCategory": true,
+      "hidden": false,
+      "docExempt": false,
+      "filePath": "src/app/components/page-header.tsx",
+      "description": "Screen header: breadcrumb slot, the title at the one canonical page-title size (`heading2`), a status slot and an actions slot. Every screen has exactly one. `display` and `h1` type are reserved for marketing and landing surfaces. Distinct from the docs-only page header in `src/docs-tooling`.",
+      "figmaUrl": null,
+      "figmaId": null,
+      "figmaLink": null,
+      "tier": "pattern",
+      "preview": {
+        "exportName": "PageHeader",
+        "sizing": "panel"
+      },
+      "consumers": [
+        "src/app/components/page-header.test.tsx",
+        "src/stories/page-header.stories.tsx",
+        "src/stories/patterns-client-detail.stories.tsx"
+      ],
+      "tokenMapping": {},
+      "variantAxes": [],
+      "componentProperties": [],
+      "props": {
+        "actions": {
+          "type": "ReactNode",
+          "optional": true
+        },
+        "breadcrumb": {
+          "type": "ReactNode",
+          "optional": true
+        },
+        "level": {
+          "type": "PageHeaderLevel",
+          "default": 1
+        },
+        "status": {
+          "type": "ReactNode",
+          "optional": true
+        },
+        "title": {
+          "type": "ReactNode"
+        }
+      },
+      "allowedChildren": [
+        "*"
+      ],
+      "propConstraints": {},
+      "requiredProps": [],
+      "a11yRules": [],
+      "storyFiles": [
+        "src/stories/page-header.stories.tsx",
+        "src/stories/patterns-client-detail.stories.tsx"
+      ],
+      "storyIds": [
+        "patterns-client-detail-screen--compact",
+        "patterns-client-detail-screen--dark",
+        "patterns-client-detail-screen--light",
+        "patterns-client-detail-screen--phone-390",
+        "patterns-pageheader--default",
+        "patterns-pageheader--long-title-wraps",
+        "patterns-pageheader--nested-level",
+        "patterns-pageheader--title-only",
+        "patterns-pageheader--with-actions"
+      ]
+    },
+    "DataTableSection": {
+      "category": "Display",
+      "categorySource": "jsdoc",
+      "governedCategory": true,
+      "hidden": false,
+      "docExempt": false,
+      "filePath": "src/app/components/data-table-section.tsx",
+      "description": "Section heading and toolbar over a `Table`. Row actions are consumer nodes in a trailing column, the table scrolls horizontally on narrow widths without a `minWidth` from the caller, and zero rows shows an `EmptyState`.",
+      "figmaUrl": null,
+      "figmaId": null,
+      "figmaLink": null,
+      "tier": "pattern",
+      "preview": {
+        "exportName": "DataTableSection",
+        "sizing": "panel"
+      },
+      "consumers": [
+        "src/app/components/data-table-section.test.tsx",
+        "src/stories/data-table-section.stories.tsx",
+        "src/stories/patterns-client-detail.stories.tsx"
+      ],
+      "tokenMapping": {},
+      "variantAxes": [],
+      "componentProperties": [],
+      "props": {
+        "actionsLabel": {
+          "type": "string",
+          "default": "Actions"
+        },
+        "columns": {
+          "type": "TableColumn[]"
+        },
+        "emptyDescription": {
+          "type": "ReactNode",
+          "optional": true
+        },
+        "emptyTitle": {
+          "type": "ReactNode",
+          "default": "Nothing here yet"
+        },
+        "level": {
+          "type": "2 | 3 | 4 | 5 | 6",
+          "default": 2
+        },
+        "rows": {
+          "type": "DataTableSectionRow[]"
+        },
+        "title": {
+          "type": "ReactNode"
+        },
+        "toolbar": {
+          "type": "ReactNode",
+          "optional": true
+        }
+      },
+      "allowedChildren": [
+        "*"
+      ],
+      "propConstraints": {},
+      "requiredProps": [],
+      "a11yRules": [],
+      "storyFiles": [
+        "src/stories/data-table-section.stories.tsx"
+      ],
+      "storyIds": [
+        "patterns-datatablesection--dark",
+        "patterns-datatablesection--default",
+        "patterns-datatablesection--empty",
+        "patterns-datatablesection--phone-390",
+        "patterns-datatablesection--without-row-actions"
+      ]
+    },
+    "DestructiveSection": {
+      "category": "Actions",
+      "categorySource": "jsdoc",
+      "governedCategory": true,
+      "hidden": false,
+      "docExempt": false,
+      "filePath": "src/app/components/destructive-section.tsx",
+      "description": "Titled danger zone: a title, an explanation, and one danger `Button` that opens an `AlertDialog`. Pressing the button never runs the action; only the dialog's confirm does. Place it last on the screen, below the form.",
+      "figmaUrl": null,
+      "figmaId": null,
+      "figmaLink": null,
+      "tier": "pattern",
+      "preview": {
+        "exportName": "DestructiveSection",
+        "sizing": "panel"
+      },
+      "consumers": [
+        "src/app/components/destructive-section.test.tsx",
+        "src/stories/destructive-section.stories.tsx",
+        "src/stories/patterns-client-detail.stories.tsx"
+      ],
+      "tokenMapping": {},
+      "variantAxes": [],
+      "componentProperties": [],
+      "props": {
+        "actionLabel": {
+          "type": "ReactNode",
+          "optional": true
+        },
+        "cancelLabel": {
+          "type": "string",
+          "default": "Cancel"
+        },
+        "confirmBody": {
+          "type": "ReactNode"
+        },
+        "confirmLabel": {
+          "type": "string"
+        },
+        "description": {
+          "type": "ReactNode"
+        },
+        "level": {
+          "type": "2 | 3 | 4 | 5 | 6",
+          "default": 2
+        },
+        "onConfirm": {
+          "type": "() => void"
+        },
+        "title": {
+          "type": "ReactNode"
+        }
+      },
+      "allowedChildren": [
+        "*"
+      ],
+      "propConstraints": {},
+      "requiredProps": [],
+      "a11yRules": [],
+      "storyFiles": [
+        "src/stories/destructive-section.stories.tsx"
+      ],
+      "storyIds": [
+        "patterns-destructivesection--dark",
+        "patterns-destructivesection--default",
+        "patterns-destructivesection--phone",
+        "patterns-destructivesection--separate-button-label"
       ]
     },
     "HdsPhosphor": {
@@ -11443,7 +12941,7 @@
       "governedCategory": true,
       "hidden": false,
       "filePath": "src/docs-tooling/lab/legacy-token-list.tsx",
-      "description": "LegacyTokenList - legacy token grouping list retained for lab-side maintenance workflows. architecture per TASKS.md \"Stale / Superseded\" → \"Live token inspector UI\". Pruning deferred until /hds/tokens is retired or rewritten — see docs/archive/work/2026-05-01-token-explorer-prune-deferred.md.",
+      "description": "LegacyTokenList - legacy token grouping list retained for lab-side maintenance workflows.",
       "figmaUrl": null,
       "figmaId": null,
       "preview": {
@@ -11487,7 +12985,7 @@
       "governedCategory": true,
       "hidden": false,
       "filePath": "src/docs-tooling/lab/token-collection-list.tsx",
-      "description": "TokenCollectionList - grouped token inventory list for lab and explorer maintenance. architecture per TASKS.md \"Stale / Superseded\" → \"Live token inspector UI\". Pruning deferred until /hds/tokens is retired or rewritten — see docs/archive/work/2026-05-01-token-explorer-prune-deferred.md.",
+      "description": "TokenCollectionList - grouped token inventory list for lab and explorer maintenance.",
       "figmaUrl": null,
       "figmaId": null,
       "preview": {
@@ -11720,7 +13218,9 @@
       },
       "consumers": [
         "src/app/components/asset-img.tsx",
-        "src/app/components/hds-tooltip.tsx"
+        "src/app/components/hds-tooltip.tsx",
+        "src/app/context/__tests__/portal-hydration.test.tsx",
+        "src/app/context/__tests__/portal-scope.test.tsx"
       ],
       "tokenMapping": {},
       "variantAxes": [],