@hirobius/design-system 0.20.0 → 0.21.0

package/src/app/data/component-api.json

@@ -1,10 +1,11 @@
 {
-  "generatedAt": "2026-10-01T16:58:58.109Z",
+  "generatedAt": "2026-10-07T18:55:36.429Z",
   "source": "react-docgen-typescript@2.4.0",
   "components": {
     "Alert": {
       "filePath": "src/app/components/alert.tsx",
       "description": "Alert - compact feedback surface with contextual severity.",
+      "core": true,
       "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.",
@@ -47,8 +48,23 @@
     "AlertDialog": {
       "filePath": "src/app/components/alert-dialog.tsx",
       "description": "AlertDialog root + parts. Controlled via `open`/`onOpenChange`, or uncontrolled with `defaultOpen`.",
+      "usage": {
+        "when": "Confirm a destructive or irreversible action (delete, archive, remove) before it runs, with Cancel and Action buttons.",
+        "whenNot": "A modal that collects input or shows content, or a confirmation after the action is done.",
+        "useInstead": [
+          {
+            "component": "Dialog",
+            "reason": "a modal with a form or other content"
+          },
+          {
+            "component": "ToastProvider",
+            "reason": "a brief confirmation after the action"
+          }
+        ]
+      },
       "category": "Overlays",
       "hidden": false,
+      "figmaUrl": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components-Copy?node-id=2035-24",
       "props": [
         {
           "name": "children",
@@ -81,6 +97,7 @@
       "description": "AssetImg - responsive asset frame with fallback placeholder handling. Contexts: default, lightbox, and detail.",
       "category": "Display",
       "hidden": false,
+      "figmaUrl": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components-Copy?node-id=2041-67",
       "props": [
         {
           "name": "alt",
@@ -201,6 +218,7 @@
     "Avatar": {
       "filePath": "src/app/components/avatar.tsx",
       "description": "Circular avatar. Renders the image when available, else initials from `alt`.",
+      "core": true,
       "usage": {
         "when": "Show a person or entity as an image with an initials fallback.",
         "whenNot": "A generic pictogram, or a status marker.",
@@ -250,6 +268,7 @@
       "description": "Renders up to `max` overlapping avatars followed by a `+N` overflow chip.",
       "category": "Display",
       "hidden": false,
+      "figmaUrl": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components-Copy?node-id=2030-63",
       "props": [
         {
           "name": "children",
@@ -274,6 +293,7 @@
     "Badge": {
       "filePath": "src/app/components/badge.tsx",
       "description": "Compact metadata/status chip. Tone is the only styling input.",
+      "core": true,
       "usage": {
         "when": "Label a status, state or count with a compact neutral or semantic chip, or a dot.",
         "whenNot": "A chip people can toggle, or a message that needs a sentence.",
@@ -310,7 +330,7 @@
           "name": "label",
           "type": "string",
           "required": false,
-          "description": "Names the dot: role=\"status\" with this aria-label. Without it the dot is aria-hidden."
+          "description": "Names a `dot` badge: role=\"img\" with this aria-label. Without it the dot is aria-hidden. A text badge ignores it: put the text in `children`."
         },
         {
           "name": "size",
@@ -331,6 +351,7 @@
       "description": "A quoted passage; pass `cite` for the source URL and `attribution` for a byline.",
       "category": "Typography",
       "hidden": false,
+      "figmaUrl": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components-Copy?node-id=2024-18",
       "props": [
         {
           "name": "attribution",
@@ -349,6 +370,7 @@
     "Box": {
       "filePath": "src/app/components/box.tsx",
       "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) take the t-shirt scale ('xs'|'sm'|'md'|'lg'|'xl' → `--semantic-space-scale-*`, hds#206) through the resolver Stack's `gap` shares. Numbers still resolve as a count of 4px units (`p: 4` is 16px), and the deprecated 'tight'|'normal'|'inset'|'spacious' still read `--semantic-space-layout-*`, fixed px that compact density does not remap. HDS source may not use raw integers (check-spacing-vocabulary). - `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.",
+      "core": true,
       "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.",
@@ -395,6 +417,7 @@
     "Breadcrumb": {
       "filePath": "src/app/components/breadcrumb.tsx",
       "description": "Breadcrumb trail. Links route through the HDS router seam (plain anchors with no router, client-side nav when a router adapter is provided). The final item is marked aria-current=\"page\".",
+      "core": true,
       "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.",
@@ -431,6 +454,7 @@
     "Button": {
       "filePath": "src/app/components/button.tsx",
       "description": "Triggers an action when activated.",
+      "core": true,
       "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 and label; for an on/off toggle pass pressed.",
         "whenNot": "Navigating to another page, where a link is the correct element.",
@@ -524,7 +548,7 @@
           "name": "variant",
           "type": "\"primary\" | \"secondary\" | \"tertiary\" | null",
           "required": false,
-          "description": ""
+          "description": "Visual treatment: `primary`, `secondary` or `tertiary`. Defaults to `secondary` (an outline), so pass `primary` for the main action."
         }
       ]
     },
@@ -554,6 +578,7 @@
     "Card": {
       "filePath": "src/app/components/card.tsx",
       "description": "Tagged per-export, not on the file block: this module exports eight components and a file-level @figma would hand all eight this one node.",
+      "core": true,
       "usage": {
         "when": "Group related content on a raised surface with header, body, footer and metric slots, or as one selectable option.",
         "whenNot": "A bare padded background with no slot anatomy, or a single headline figure.",
@@ -644,28 +669,28 @@
     },
     "CardBody": {
       "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 — 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 + big value (title) + 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.",
       "category": "Display",
       "hidden": false,
       "props": []
     },
     "CardDescription": {
       "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 — 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 + big value (title) + 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.",
       "category": "Display",
       "hidden": false,
       "props": []
     },
     "CardFooter": {
       "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 — 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 + big value (title) + 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.",
       "category": "Display",
       "hidden": false,
       "props": []
     },
     "CardHeader": {
       "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 — 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 + big value (title) + 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.",
       "category": "Display",
       "hidden": false,
       "props": [
@@ -679,10 +704,16 @@
     },
     "CardMetric": {
       "filePath": "src/app/components/card.tsx",
-      "description": "Card.Metric — one uppercase label, a large value and an optional sub-line inside a Card.",
+      "description": "Card.Metric — one label, a large value and an optional sub-line inside a Card.",
       "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."
+        "whenNot": "A metric outside a Card, or several figures that share one label.",
+        "useInstead": [
+          {
+            "component": "MetricTiles",
+            "reason": "a row of headline numbers with no enclosing Card"
+          }
+        ]
       },
       "category": "Display",
       "hidden": false,
@@ -716,7 +747,7 @@
     },
     "CardProgress": {
       "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 — 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 + big value (title) + 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.",
       "category": "Display",
       "hidden": false,
       "props": [
@@ -750,7 +781,7 @@
     },
     "CardTitle": {
       "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 — 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 + big value (title) + 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.",
       "category": "Display",
       "hidden": false,
       "props": []
@@ -758,6 +789,7 @@
     "Checkbox": {
       "filePath": "src/app/components/checkbox.tsx",
       "description": "Checkbox — custom-drawn checkbox with check / indeterminate glyph.",
+      "core": true,
       "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.",
@@ -867,6 +899,7 @@
     "Combobox": {
       "filePath": "src/app/components/combobox.tsx",
       "description": "Combobox — searchable single- or multi-select (Popover + filtered listbox). A select-with-search built on the HDS Popover. The trigger shows the current selection (with `multiple`, a count and a removable chip per value); opening reveals a search field that filters the option list. Full keyboard support (↑/↓ to move, Enter to choose, Esc/outside-click to close) and listbox/option ARIA. Controlled via `value` + `onChange`. <Combobox options={[{ value: 'us', label: 'United States' }, …]} value={country} onChange={setCountry} placeholder=\"Select a country\" />",
+      "core": true,
       "usage": {
         "when": "Pick one value, or several with `multiple`, 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.",
@@ -998,6 +1031,7 @@
     "Container": {
       "filePath": "src/app/components/container.tsx",
       "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>",
+      "core": true,
       "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.",
@@ -1059,6 +1093,7 @@
       "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`.",
       "category": "Display",
       "hidden": false,
+      "figmaUrl": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components-Copy?node-id=2075-268",
       "props": [
         {
           "name": "actionsLabel",
@@ -1118,6 +1153,7 @@
       "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.",
       "category": "Actions",
       "hidden": false,
+      "figmaUrl": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components-Copy?node-id=2076-3",
       "props": [
         {
           "name": "actionLabel",
@@ -1174,6 +1210,7 @@
     "Dialog": {
       "filePath": "src/app/components/dialog.tsx",
       "description": "Tagged per-export, not on the file block: this module exports ten components and a file-level @figma would hand all ten this one node.",
+      "core": true,
       "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.",
@@ -1189,6 +1226,10 @@
           {
             "component": "ToastProvider",
             "reason": "a brief confirmation"
+          },
+          {
+            "component": "AlertDialog",
+            "reason": "confirming a destructive or irreversible action"
           }
         ]
       },
@@ -1468,6 +1509,7 @@
     "Disclosure": {
       "filePath": "src/app/components/disclosure.tsx",
       "description": "Disclosure - compact disclosure surface for optional explanatory content.",
+      "core": true,
       "usage": {
         "when": "Hide optional explanatory content behind a heading that people can expand.",
         "whenNot": "Content people must see, or switching between panels.",
@@ -1550,6 +1592,7 @@
     "Divider": {
       "filePath": "src/app/components/divider.tsx",
       "description": "Divider — semantic separator between content regions.",
+      "core": true,
       "usage": {
         "when": "Separate two regions of content with a thin semantic rule.",
         "whenNot": "Spacing alone would do, or the separation needs a container.",
@@ -1598,6 +1641,7 @@
     "EmptyState": {
       "filePath": "src/app/components/empty-state.tsx",
       "description": "EmptyState — consistent no-data placeholder for lists, grids, and sections.",
+      "core": true,
       "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.",
@@ -1640,6 +1684,7 @@
     "Field": {
       "filePath": "src/app/components/field.tsx",
       "description": "Caption label paired with a value — used in metadata grids and read-only forms.",
+      "core": true,
       "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.",
@@ -1703,6 +1748,7 @@
       "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.",
       "category": "Actions",
       "hidden": false,
+      "figmaUrl": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components-Copy?node-id=2075-87",
       "props": [
         {
           "name": "destructive",
@@ -1836,6 +1882,7 @@
     "Grid": {
       "filePath": "src/app/components/grid.tsx",
       "description": "Grid — responsive grid composition primitive. Enforces semantic gap and column values. No arbitrary CSS grid. - layout='fixed': responsive base (collapses via CSS at tablet/mobile). `columns` sets desktop count (default 12). Tablet/mobile clamp to min(8, cols) and min(4, cols) respectively. - layout='auto-fit': responsive card wrapping via auto-fit. - layout='auto-fill': tile wrapping at `minItemWidth` (TileGrid's recipe; 0.20.0 removed TileGrid). - subgrid=true: sets gridTemplateColumns:'subgrid' for nested alignment. Usage (default responsive 12-col): <Grid> <Grid.Item colSpan={6}>…</Grid.Item> <Grid.Item colSpan={6}>…</Grid.Item> </Grid> Usage (responsive auto-fit): <Grid layout=\"auto-fit\"> <Card /> <Card /> </Grid>",
+      "core": true,
       "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.",
@@ -1854,6 +1901,13 @@
       "category": "Layout",
       "hidden": false,
       "props": [
+        {
+          "name": "align",
+          "type": "\"center\" | \"end\" | \"start\" | \"stretch\"",
+          "default": "start",
+          "required": false,
+          "description": "Cross-axis alignment of items in a row. Defaults to 'start': items hug their own height. Pass 'stretch' where a row of tiles must share one height."
+        },
         {
           "name": "as",
           "type": "ElementType<any, keyof IntrinsicElements>",
@@ -1918,6 +1972,7 @@
     "HdsRouterProvider": {
       "filePath": "src/app/context/RouterContext.tsx",
       "description": "Provide a router adapter to all HDS components below. Wrap your app root once.",
+      "core": true,
       "usage": {
         "when": "Wrap the app root once so HDS links and navigation use your client router; with no provider they stay plain anchors."
       },
@@ -1941,6 +1996,7 @@
     "HdsThemeProvider": {
       "filePath": "src/app/context/hds-theme.tsx",
       "description": "Renders a `data-hds` scope wrapper that carries the four theming dials as root attributes + CSS vars, and exposes them to `useHdsTheme()`.",
+      "core": true,
       "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.",
@@ -2014,6 +2070,7 @@
     "Icon": {
       "filePath": "src/app/components/icon.tsx",
       "description": "Icon — semantic icon wrapper for Lucide icons.",
+      "core": true,
       "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.",
@@ -2030,6 +2087,7 @@
       },
       "category": "Display",
       "hidden": false,
+      "figmaUrl": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components-Copy?node-id=27-2",
       "props": [
         {
           "name": "aria-hidden",
@@ -2121,6 +2179,7 @@
     "InlineLink": {
       "filePath": "src/app/components/inline-link.tsx",
       "description": "InlineLink ” inline navigation and external-link primitive for body copy.",
+      "core": true,
       "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.",
@@ -2163,6 +2222,7 @@
     "Input": {
       "filePath": "src/app/components/input.tsx",
       "description": "Input — text field primitive with label, helper, and error slots.",
+      "core": true,
       "usage": {
         "when": "Collect a single line of text, a number, an email, a password, a date or a time, with label, helper and error slots.",
         "whenNot": "Multi-line text, or choosing from a fixed list of options.",
@@ -2284,6 +2344,7 @@
     "Kbd": {
       "filePath": "src/app/components/kbd.tsx",
       "description": "Renders a keyboard key or shortcut token, e.g. `<Kbd>⌘K</Kbd>`.",
+      "core": true,
       "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.",
@@ -2296,6 +2357,7 @@
       },
       "category": "Display",
       "hidden": false,
+      "figmaUrl": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components-Copy?node-id=2026-9",
       "props": [
         {
           "name": "size",
@@ -2310,6 +2372,7 @@
       "description": "Renders object metadata as a semantic `<dl>` of term/description pairs.",
       "category": "Display",
       "hidden": false,
+      "figmaUrl": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components-Copy?node-id=2041-47",
       "props": [
         {
           "name": "footer",
@@ -2344,6 +2407,7 @@
       "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`.",
       "category": "Display",
       "hidden": false,
+      "figmaUrl": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components-Copy?node-id=2075-114",
       "props": [
         {
           "name": "label",
@@ -2468,6 +2532,7 @@
     "Pagination": {
       "filePath": "src/app/components/pagination.tsx",
       "description": "Paged navigation with first/last anchors, sibling pages, and ellipses.",
+      "core": true,
       "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.",
@@ -2560,6 +2625,7 @@
     "Progress": {
       "filePath": "src/app/components/progress.tsx",
       "description": "Linear bar or circular ring. Determinate when `value` is a number, else indeterminate.",
+      "core": true,
       "usage": {
         "when": "Show how far a task has got, as a bar or ring that is determinate or indeterminate.",
         "whenNot": "A wait of unknown length with no bar, or content that is still loading.",
@@ -2624,6 +2690,7 @@
     "Radio": {
       "filePath": "src/app/components/radio.tsx",
       "description": "Radio — radio button with animated selection indicator.",
+      "core": true,
       "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.",
@@ -2710,6 +2777,7 @@
     "SegmentedControl": {
       "filePath": "src/app/components/segmented-control.tsx",
       "description": "SegmentedControl \" segmented selection input for compact mutually-exclusive choices. The active×hover×pressed×disabled×secondary state matrix is expressed through `cva` compound variants keyed by `active` / `interaction` (the live-or-frozen-demo hover/pressed/rest sub-state) / `variant` / `disabled`, each resolving to the same `--semantic-*` custom properties the pre-Tailwind inline styles referenced — same tokens, same pixels, just Tailwind classes instead of a `style` object. Per ADR-015 this control keeps its own hover/focus tracking (per-segment `string | null` cardinality) rather than the shared `useInteractionState` single-element machine; only the class composition changed, not the state machine feeding it.",
+      "core": true,
       "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.",
@@ -2800,6 +2868,7 @@
     "Select": {
       "filePath": "src/app/components/select.tsx",
       "description": "Select — dropdown selector built on Radix Select (ADR-001 Radix convention). Radix owns the listbox a11y contract: managed focus + active-descendant, typeahead, full keyboard (Home/End/PageUp-Down/wrap), Popper collision/flip positioning, and dismissal. The HDS surface is styled with the token-backed Tailwind idiom used by tabs.tsx / command-palette.tsx; `ref` targets the trigger button.",
+      "core": true,
       "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.",
@@ -2970,6 +3039,7 @@
     "Skeleton": {
       "filePath": "src/app/components/skeleton.tsx",
       "description": "Decorative loading placeholder. Marked aria-hidden — announce the loading state on the surrounding region (e.g. aria-busy) rather than per skeleton.",
+      "core": true,
       "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.",
@@ -2992,7 +3062,7 @@
           "name": "height",
           "type": "string | number",
           "required": false,
-          "description": "Explicit height (number → px, or any CSS length). For `text`, defaults to 1em."
+          "description": "Explicit height (number → px, or any CSS length). For `text`, defaults to 1em; for `rectangular`, 5rem."
         },
         {
           "name": "variant",
@@ -3012,6 +3082,7 @@
     "Slider": {
       "filePath": "src/app/components/slider.tsx",
       "description": "Slider — range slider with label and value display.",
+      "core": true,
       "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.",
@@ -3068,6 +3139,7 @@
     "Spinner": {
       "filePath": "src/app/components/spinner.tsx",
       "description": "Indeterminate spinner. Inherits the surrounding text color via currentColor.",
+      "core": true,
       "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.",
@@ -3104,6 +3176,7 @@
     "Stack": {
       "filePath": "src/app/components/stack.tsx",
       "description": "Stack — one-dimensional layout primitive.",
+      "core": true,
       "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.",
@@ -3183,11 +3256,15 @@
     },
     "Stat": {
       "filePath": "src/app/components/stat.tsx",
-      "description": "Headline metric — large value, uppercase caption label, optional sub-line.",
+      "description": "Headline metric — large value, caption label, optional sub-line.",
       "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.",
+        "when": "Show one headline figure inline, inside prose or a dense list, with its label and an optional sub-line.",
+        "whenNot": "A row of headline numbers on a screen, a figure inside a Card, or a status with a trailing badge.",
         "useInstead": [
+          {
+            "component": "MetricTiles",
+            "reason": "a row of headline numbers (one MetricTile per number)"
+          },
           {
             "component": "Card.Metric",
             "reason": "a figure inside a Card (hds#254 folds Stat into the Card slot)"
@@ -3228,40 +3305,6 @@
         }
       ]
     },
-    "StatusDot": {
-      "filePath": "src/app/components/status-dot.tsx",
-      "description": "A small solid dot conveying a semantic status via `tone`.",
-      "usage": {
-        "useInstead": [
-          {
-            "component": "Badge",
-            "reason": "with `dot`"
-          }
-        ]
-      },
-      "category": "Feedback",
-      "hidden": false,
-      "props": [
-        {
-          "name": "label",
-          "type": "string",
-          "required": false,
-          "description": "Accessible name for the status. When provided the dot is exposed as a `role=\"status\"` with this label; when omitted the dot is decorative (`aria-hidden`) and a sibling should carry the meaning."
-        },
-        {
-          "name": "size",
-          "type": "\"sm\" | \"md\" | \"lg\" | null",
-          "required": false,
-          "description": ""
-        },
-        {
-          "name": "tone",
-          "type": "\"success\" | \"danger\" | \"warning\" | \"info\" | \"neutral\" | \"inProgress\" | null",
-          "required": false,
-          "description": ""
-        }
-      ]
-    },
     "StatusListItem": {
       "filePath": "src/app/components/status-list-item.tsx",
       "description": "Status dot + title row with optional muted notes and trailing slot (e.g. badge).",
@@ -3300,11 +3343,15 @@
       "description": "Block-layout sibling of StatusListItem. Renders a raised surface tile with title, optional muted notes, and a trailing slot for a badge or affordance. Status colour belongs in the trailing slot, never as a left rule on the tile — every tile should look the same so feedback signals stay reserved for genuinely interrupting states.",
       "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.",
+        "whenNot": "A headline number (never a value), or a row inside a list.",
         "useInstead": [
+          {
+            "component": "MetricTiles",
+            "reason": "a row of headline numbers"
+          },
           {
             "component": "Card.Metric",
-            "reason": "a headline figure (hds#254 folds StatusTile into the Card slot)"
+            "reason": "a headline figure inside a Card (hds#254 folds StatusTile into the Card slot)"
           },
           {
             "component": "StatusListItem",
@@ -3346,6 +3393,7 @@
     "Surface": {
       "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) - 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>",
+      "core": true,
       "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.",
@@ -3475,6 +3523,7 @@
     "Table": {
       "filePath": "src/app/components/table.tsx",
       "description": "Table - structured data table primitive for documentation and compact UI matrices.",
+      "core": true,
       "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.",
@@ -3526,9 +3575,9 @@
         {
           "name": "flush",
           "type": "boolean",
-          "default": "false",
+          "default": "true",
           "required": false,
-          "description": ""
+          "description": "Drop the scroll region's own inset. On by default: every cell already carries the surface inset, so a padded region doubled it (48px at the edges, hds#522). Pass `flush={false}` to restore the extra region padding."
         },
         {
           "name": "labelledBy",
@@ -3598,6 +3647,7 @@
     "Tabs": {
       "filePath": "src/app/components/tabs.tsx",
       "description": "The tab set itself. Tagged here rather than in the file block because TabsList and TabsContent share this module and have no Figma node of their own — a file-level @figma would silently claim this node for all four.",
+      "core": true,
       "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.",
@@ -3729,6 +3779,7 @@
     "Tag": {
       "filePath": "src/app/components/tag.tsx",
       "description": "Tag — interactive filter and category chip. The outer <button> carries the accessible 44px hit target directly via the size token while the inner pill keeps the visible surface compact. Colors (background, border-color, color) live in the pill's cva variants, painted through `group-hover`/`group-active` so the pill reacts to interaction on the shared outer button (converted off the former .hds-tag-btn/.hds-tag-pill theme.css rules for #60 — same behavior, now token-driven Tailwind classes). The `active` prop (aria-pressed selected state) is not one of the variant contract's four axes — it's expressed as the pill's `selected` cva variant, carrying the same rest → hover → pressed → focus-visible state matrix the contract expects, just keyed by selection instead of tone/size/density.",
+      "core": true,
       "usage": {
         "when": "Show an interactive filter or category chip that people can toggle.",
         "whenNot": "A read-only status or count label.",
@@ -3761,6 +3812,7 @@
     "Text": {
       "filePath": "src/app/components/text.tsx",
       "description": "Text — polymorphic typography primitive spanning the full HDS type ramp.",
+      "core": true,
       "usage": {
         "when": "Set any text on the type ramp, with the element chosen by `as`.",
         "whenNot": "Navigation links, or a keyboard hint.",
@@ -3777,6 +3829,7 @@
       },
       "category": "Typography",
       "hidden": false,
+      "figmaUrl": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components-Copy?node-id=2022-31",
       "props": [
         {
           "name": "as",
@@ -3814,6 +3867,7 @@
     "Textarea": {
       "filePath": "src/app/components/textarea.tsx",
       "description": "Textarea — multi-line text field primitive with label, helper, and error slots. Mirrors Input's shell + token skin as a native `<textarea>`. Figma parity: the four states Default / Focus / Error / Disabled map to the focus-ring, `error`, and `disabled` treatments below.",
+      "core": true,
       "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.",
@@ -3884,6 +3938,7 @@
       "description": "Presents a date/time with a machine-readable `dateTime` for accessibility.",
       "category": "Display",
       "hidden": false,
+      "figmaUrl": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components-Copy?node-id=2031-11",
       "props": [
         {
           "name": "date",
@@ -3915,6 +3970,7 @@
     "ToastProvider": {
       "filePath": "src/app/components/toast.tsx",
       "description": "Provider + viewport for the toast system. Wrap the app root once.",
+      "core": true,
       "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.",
@@ -3958,6 +4014,7 @@
     "Toggle": {
       "filePath": "src/app/components/toggle.tsx",
       "description": "Toggle — boolean on/off toggle with animated thumb.",
+      "core": true,
       "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.",
@@ -3999,6 +4056,7 @@
     "VisuallyHidden": {
       "filePath": "src/app/components/visually-hidden.tsx",
       "description": "Renders its children off-screen (Tailwind `sr-only`) so they are announced by screen readers without occupying visual space — e.g. a text label for an icon-only control.",
+      "core": true,
       "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.",
@@ -4024,6 +4082,7 @@
     "Menu": {
       "filePath": "src/app/components/menu.tsx",
       "description": "Menu root + parts. Controlled via `open`/`onOpenChange`, or uncontrolled with `defaultOpen`.",
+      "core": true,
       "category": "Overlays",
       "usage": {
         "when": "Offer a list of actions from a trigger, closed until opened.",
@@ -4119,6 +4178,7 @@
     "Popover": {
       "filePath": "src/app/components/popover.tsx",
       "description": "Popover root + parts. Controlled via `open`/`onOpenChange`, or uncontrolled with `defaultOpen`.",
+      "core": true,
       "category": "Overlays",
       "usage": {
         "when": "Anchor interactive content, such as a short form, a filter set or a picker, to a trigger people click to open.",
@@ -4190,6 +4250,7 @@
     "Tooltip": {
       "filePath": "src/app/components/hds-tooltip.tsx",
       "description": "Tooltip root. Bakes in the Radix Provider so a single `<Tooltip>` is self-contained — no app-level provider required. Controlled via `open`/`onOpenChange`, or uncontrolled with `defaultOpen`.",
+      "core": true,
       "category": "Overlays",
       "usage": {
         "when": "Name an icon-only control, or add a short hint that appears on hover and keyboard focus.",