@hirobius/design-system 0.20.0 → 0.22.0

package/public/hds-manifest.json

@@ -2,7 +2,7 @@
   "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-10-01T14:42:41.226Z",
+  "generated": "2026-10-07T17:58:53.026Z",
   "source": "hirobius.tokens.json",
   "format": "W3C DTCG 2025.10",
   "docs": "https://hirobius-design-system.vercel.app/",
@@ -109,7 +109,6 @@
     "Spinner",
     "Stack",
     "Stat",
-    "StatusDot",
     "StatusListItem",
     "StatusTile",
     "Surface",
@@ -130,76 +129,90 @@
   ],
   "typographyRamp": {
     "status": "active",
-    "styleCount": 9,
+    "styleCount": 6,
     "source": "hirobius.tokens.json semantic.typography",
     "tokens": [
       {
         "name": "display",
         "size": "48px",
-        "lineHeight": "1.0",
-        "role": "Hero headlines and landing-page displays"
+        "lineHeight": "1.05",
+        "weight": 700,
+        "role": "One per page, hero only"
       },
       {
-        "name": "heading1",
-        "size": "36px",
-        "lineHeight": "1.25",
-        "role": "Primary section headings and h1 text"
-      },
-      {
-        "name": "heading2",
-        "size": "30px",
-        "lineHeight": "1.25",
-        "role": "Secondary section headings and h2 text"
-      },
-      {
-        "name": "heading3",
+        "name": "title",
         "size": "24px",
         "lineHeight": "1.25",
-        "role": "Component headings, card headings, and h3 text"
+        "weight": 700,
+        "role": "Section and card headings"
       },
       {
         "name": "body",
         "size": "16px",
-        "lineHeight": "1.5",
-        "role": "Default long-form prose and body copy"
+        "lineHeight": "1.6",
+        "weight": 400,
+        "role": "Prose"
       },
       {
         "name": "ui",
         "size": "14px",
         "lineHeight": "1.5",
-        "role": "Standard interface text, nav labels, inputs, and controls"
+        "weight": 500,
+        "role": "Controls, nav, table text, values"
       },
       {
         "name": "caption",
         "size": "12px",
         "lineHeight": "1.5",
-        "role": "Active functional role for helper text, error metadata, secondary metadata, and form annotations"
-      },
-      {
-        "name": "technical",
-        "size": "12px",
-        "lineHeight": "1.0",
-        "role": "Monospace token keys, code snippets, keyboard shortcuts, hashes, and aligned data readouts"
+        "weight": 500,
+        "role": "Metadata, help text and labels, in sentence case"
       },
       {
-        "name": "badge",
-        "size": "10px",
-        "lineHeight": "1.0",
-        "role": "Status badges and compact tags only"
+        "name": "mono",
+        "size": "13px",
+        "lineHeight": "1.5",
+        "weight": 400,
+        "role": "Code and ids"
       }
     ],
     "deprecated": [
+      "heading1",
+      "heading2",
+      "heading3",
+      "h1",
+      "h2",
+      "h3",
+      "technical",
+      "badge",
+      "eyebrow",
+      "small",
       "displayXl",
+      "display1",
       "display2",
-      "title",
+      "headingHero",
+      "headingSection",
       "body2",
+      "bodyLarge",
+      "bodySmall",
       "label",
       "labelDescriptive",
       "labelTechnical",
       "micro",
       "monoXs",
       "monoSm"
-    ]
+    ],
+    "aliasOf": {
+      "heading1": "title",
+      "heading2": "title",
+      "heading3": "title",
+      "h1": "title",
+      "h2": "title",
+      "h3": "title",
+      "technical": "mono",
+      "badge": "caption",
+      "eyebrow": "caption",
+      "small": "ui"
+    }
   },
   "patternInventory": [
     "DataTableSection",
@@ -378,7 +391,7 @@
       "hidden": false,
       "filePath": "src/app/components/alert.tsx",
       "description": "Alert - compact feedback surface with contextual severity.",
-      "figmaUrl": "https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=33-34",
+      "figmaUrl": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=33-34",
       "figmaId": null,
       "preview": {
         "exportName": "Alert",
@@ -466,7 +479,7 @@
       "tier": "primitive",
       "docExempt": false,
       "sourcePath": "src/app/components/Alert.tsx",
-      "figmaLink": "https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=33-34",
+      "figmaLink": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=33-34",
       "props": {
         "children": {
           "type": "ReactNode"
@@ -524,7 +537,8 @@
             "reason": "a short status label"
           }
         ]
-      }
+      },
+      "core": true
     },
     "CodeBlock": {
       "category": "Display",
@@ -533,7 +547,7 @@
       "hidden": false,
       "filePath": "src/app/components/code-block.tsx",
       "description": "CodeBlock - code display with copy button and optional collapsible toggle.",
-      "figmaUrl": "https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=89-154",
+      "figmaUrl": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=89-154",
       "figmaId": null,
       "preview": {
         "exportName": "CodeBlock",
@@ -598,7 +612,7 @@
       "tier": "primitive",
       "docExempt": false,
       "sourcePath": "src/app/components/CodeBlock.tsx",
-      "figmaLink": "https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=89-154",
+      "figmaLink": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=89-154",
       "storyFiles": [
         "src/stories/code-block.stories.tsx"
       ],
@@ -697,7 +711,8 @@
           }
         ]
       },
-      "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. For a horizontal gutter, which Container does not support, put a Box with `style={{ paddingInline }}` inside it."
+      "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. For a horizontal gutter, which Container does not support, put a Box with `style={{ paddingInline }}` inside it.",
+      "core": true
     },
     "Disclosure": {
       "category": "Layout",
@@ -706,7 +721,7 @@
       "hidden": false,
       "filePath": "src/app/components/disclosure.tsx",
       "description": "Disclosure - compact disclosure surface for optional explanatory content.",
-      "figmaUrl": "https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=88-453",
+      "figmaUrl": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=88-453",
       "figmaId": null,
       "preview": {
         "exportName": "Disclosure",
@@ -810,7 +825,7 @@
         }
       ],
       "sourcePath": "src/app/components/Disclosure.tsx",
-      "figmaLink": "https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=88-453",
+      "figmaLink": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=88-453",
       "storyFiles": [
         "src/stories/disclosure.stories.tsx"
       ],
@@ -829,7 +844,8 @@
             "reason": "switching between panels of content"
           }
         ]
-      }
+      },
+      "core": true
     },
     "Divider": {
       "category": "Layout",
@@ -838,7 +854,7 @@
       "hidden": false,
       "filePath": "src/app/components/divider.tsx",
       "description": "Divider — semantic separator between content regions.",
-      "figmaUrl": "https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=89-26",
+      "figmaUrl": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=89-26",
       "figmaId": null,
       "preview": {
         "exportName": "Divider",
@@ -877,7 +893,7 @@
       "tier": "primitive",
       "docExempt": false,
       "sourcePath": "src/app/components/Divider.tsx",
-      "figmaLink": "https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=89-26",
+      "figmaLink": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=89-26",
       "props": {
         "orientation": {
           "type": "enum",
@@ -947,7 +963,8 @@
             "reason": "a bounded region with its own background"
           }
         ]
-      }
+      },
+      "core": true
     },
     "ErrorPattern": {
       "category": "Feedback",
@@ -1080,6 +1097,16 @@
       ],
       "tokenMapping": {},
       "props": {
+        "align": {
+          "type": "enum",
+          "values": [
+            "center",
+            "end",
+            "start",
+            "stretch"
+          ],
+          "default": "start"
+        },
         "as": {
           "type": "ElementType<any, keyof IntrinsicElements>",
           "default": "div"
@@ -1132,6 +1159,15 @@
         "*"
       ],
       "propConstraints": {
+        "align": {
+          "type": "enum",
+          "values": [
+            "center",
+            "end",
+            "start",
+            "stretch"
+          ]
+        },
         "className": {
           "type": "string"
         },
@@ -1211,7 +1247,8 @@
           }
         ]
       },
-      "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, auto-fill, or subgrid modes already express the layout. Do NOT use Grid for simple one-dimensional stacks where Stack is sufficient."
+      "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, auto-fill, or subgrid modes already express the layout. Do NOT use Grid for simple one-dimensional stacks where Stack is sufficient.",
+      "core": true
     },
     "Icon": {
       "category": "Display",
@@ -1220,7 +1257,7 @@
       "hidden": false,
       "filePath": "src/app/components/icon.tsx",
       "description": "Icon — semantic icon wrapper for Lucide icons.",
-      "figmaUrl": null,
+      "figmaUrl": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=27-2",
       "figmaId": null,
       "preview": {
         "exportName": "Icon",
@@ -1356,7 +1393,7 @@
       "tier": "primitive",
       "docExempt": false,
       "sourcePath": "src/app/components/Icon.tsx",
-      "figmaLink": null,
+      "figmaLink": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=27-2",
       "storyFiles": [
         "src/stories/icon.stories.tsx"
       ],
@@ -1381,7 +1418,8 @@
             "reason": "a picture of a person or entity"
           }
         ]
-      }
+      },
+      "core": true
     },
     "InlineCode": {
       "category": "Display",
@@ -1390,7 +1428,7 @@
       "hidden": false,
       "filePath": "src/app/components/inline-code.tsx",
       "description": "InlineCode — inline code chip for token paths, file paths, and code-adjacent prose.",
-      "figmaUrl": "https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=89-155",
+      "figmaUrl": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=89-155",
       "figmaId": null,
       "preview": {
         "exportName": "InlineCode",
@@ -1446,7 +1484,7 @@
       "tier": "primitive",
       "docExempt": false,
       "sourcePath": "src/app/components/InlineCode.tsx",
-      "figmaLink": "https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=89-155",
+      "figmaLink": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=89-155",
       "storyFiles": [
         "src/stories/inline-code.stories.tsx"
       ],
@@ -1467,7 +1505,7 @@
       "hidden": false,
       "filePath": "src/app/components/inline-link.tsx",
       "description": "InlineLink ” inline navigation and external-link primitive for body copy.",
-      "figmaUrl": "https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=89-161",
+      "figmaUrl": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=89-161",
       "figmaId": null,
       "preview": {
         "exportName": "InlineLink",
@@ -1523,7 +1561,7 @@
       "tier": "primitive",
       "docExempt": false,
       "sourcePath": "src/app/components/InlineLink.tsx",
-      "figmaLink": "https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=89-161",
+      "figmaLink": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=89-161",
       "storyFiles": [
         "src/stories/inline-link.stories.tsx"
       ],
@@ -1546,7 +1584,8 @@
             "reason": "unlinked body copy"
           }
         ]
-      }
+      },
+      "core": true
     },
     "Input": {
       "category": "Inputs",
@@ -1555,7 +1594,7 @@
       "hidden": false,
       "filePath": "src/app/components/input.tsx",
       "description": "Input — text field primitive with label, helper, and error slots.",
-      "figmaUrl": "https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=38-20",
+      "figmaUrl": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=38-20",
       "figmaId": null,
       "preview": {
         "exportName": "Input",
@@ -1563,9 +1602,11 @@
       },
       "consumers": [
         "src/app/components/field.tsx",
+        "src/app/components/form-control.ts",
         "src/app/components/form.tsx",
         "src/app/components/input.test.tsx",
         "src/app/components/segmented-control.tsx",
+        "src/app/components/select.tsx",
         "src/app/components/slider.tsx",
         "src/app/components/textarea.tsx",
         "src/app/design-system/generated-token-descriptions.ts",
@@ -1805,7 +1846,7 @@
       ],
       "tier": "primitive",
       "docExempt": false,
-      "figmaLink": "https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=38-20",
+      "figmaLink": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=38-20",
       "storyFiles": [
         "src/stories/input.stories.tsx"
       ],
@@ -1837,7 +1878,8 @@
             "reason": "a long fixed list that needs search"
           }
         ]
-      }
+      },
+      "core": true
     },
     "SegmentedControl": {
       "category": "Inputs",
@@ -1846,7 +1888,7 @@
       "hidden": false,
       "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.",
-      "figmaUrl": "https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=82-334",
+      "figmaUrl": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=82-334",
       "figmaId": null,
       "preview": {
         "exportName": "SegmentedControl",
@@ -1962,7 +2004,7 @@
       "tier": "primitive",
       "docExempt": false,
       "sourcePath": "src/app/components/SegmentedControl.tsx",
-      "figmaLink": "https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=82-334",
+      "figmaLink": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=82-334",
       "storyFiles": [
         "src/stories/segmented-control.stories.tsx"
       ],
@@ -1989,7 +2031,8 @@
             "reason": "more than five options"
           }
         ]
-      }
+      },
+      "core": true
     },
     "Stack": {
       "category": "Layout",
@@ -2178,7 +2221,8 @@
           }
         ]
       },
-      "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."
+      "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.",
+      "core": true
     },
     "Table": {
       "category": "Display",
@@ -2187,7 +2231,7 @@
       "hidden": false,
       "filePath": "src/app/components/table.tsx",
       "description": "Table - structured data table primitive for documentation and compact UI matrices.",
-      "figmaUrl": "https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=89-300",
+      "figmaUrl": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=89-300",
       "figmaId": null,
       "preview": {
         "exportName": "Table",
@@ -2228,7 +2272,7 @@
         },
         "flush": {
           "type": "boolean",
-          "default": false
+          "default": true
         },
         "labelledBy": {
           "type": "string",
@@ -2283,7 +2327,7 @@
       "tier": "primitive",
       "docExempt": false,
       "sourcePath": "src/app/components/Table.tsx",
-      "figmaLink": "https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=89-300",
+      "figmaLink": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=89-300",
       "storyFiles": [
         "src/stories/table.stories.tsx"
       ],
@@ -2310,7 +2354,8 @@
             "reason": "a short list of items"
           }
         ]
-      }
+      },
+      "core": true
     },
     "Tag": {
       "category": "Inputs",
@@ -2319,7 +2364,7 @@
       "hidden": false,
       "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.",
-      "figmaUrl": "https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=32-11",
+      "figmaUrl": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=32-11",
       "figmaId": null,
       "preview": {
         "exportName": "Tag",
@@ -2435,7 +2480,7 @@
       "tier": "primitive",
       "docExempt": false,
       "sourcePath": "src/app/components/Tag.tsx",
-      "figmaLink": "https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=32-11",
+      "figmaLink": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=32-11",
       "storyFiles": [
         "src/stories/tag.stories.tsx"
       ],
@@ -2456,7 +2501,8 @@
             "reason": "a read-only status or count"
           }
         ]
-      }
+      },
+      "core": true
     },
     "Surface": {
       "category": "Layout",
@@ -2465,7 +2511,7 @@
       "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) - 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",
+      "figmaUrl": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=89-27",
       "figmaId": null,
       "preview": {
         "exportName": "Surface",
@@ -2479,6 +2525,7 @@
         "src/app/components/divider.tsx",
         "src/app/components/empty-state.tsx",
         "src/app/components/error-pattern.tsx",
+        "src/app/components/form-control.ts",
         "src/app/components/metric-tiles.tsx",
         "src/app/components/popover.tsx",
         "src/app/components/slider.tsx",
@@ -2559,7 +2606,7 @@
       "tier": "primitive",
       "docExempt": true,
       "sourcePath": "src/app/components/Surface.tsx",
-      "figmaLink": "https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=89-27",
+      "figmaLink": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=89-27",
       "states": [
         "default"
       ],
@@ -2587,7 +2634,8 @@
           }
         ]
       },
-      "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."
+      "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.",
+      "core": true
     },
     "Card": {
       "category": "Display",
@@ -2596,7 +2644,7 @@
       "hidden": false,
       "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.",
-      "figmaUrl": "https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=39-11",
+      "figmaUrl": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=39-11",
       "figmaId": null,
       "consumers": [
         "src/app/components/box-sx.test.ts",
@@ -2770,7 +2818,7 @@
         "Body",
         "Footer"
       ],
-      "figmaLink": "https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=39-11",
+      "figmaLink": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=39-11",
       "propConstraints": {
         "bordered": {
           "type": "boolean"
@@ -2816,6 +2864,7 @@
         "primitives-card--padding-variants",
         "primitives-card--progress-slot",
         "primitives-card--selectable",
+        "primitives-card--tone-matrix",
         "primitives-card--variant-accent"
       ],
       "usage": {
@@ -2831,7 +2880,8 @@
             "reason": "a single headline figure"
           }
         ]
-      }
+      },
+      "core": true
     },
     "Text": {
       "category": "Typography",
@@ -2866,7 +2916,7 @@
       "a11yRules": [],
       "categorySource": "jsdoc",
       "governedCategory": true,
-      "figmaUrl": null,
+      "figmaUrl": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=2022-31",
       "figmaId": null,
       "preview": {
         "exportName": "Text",
@@ -2903,7 +2953,7 @@
       "tier": "primitive",
       "docExempt": true,
       "sourcePath": "src/app/components/Text.tsx",
-      "figmaLink": null,
+      "figmaLink": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=2022-31",
       "storyFiles": [
         "src/stories/text.stories.tsx"
       ],
@@ -2931,7 +2981,8 @@
             "reason": "a keyboard key hint"
           }
         ]
-      }
+      },
+      "core": true
     },
     "Dialog": {
       "category": "Overlays",
@@ -2941,7 +2992,7 @@
       "docExempt": true,
       "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.",
-      "figmaUrl": "https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=93-27",
+      "figmaUrl": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=93-27",
       "figmaId": null,
       "tier": "primitive",
       "preview": {
@@ -3128,7 +3179,7 @@
         "Description",
         "Close"
       ],
-      "figmaLink": "https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=93-27",
+      "figmaLink": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=93-27",
       "propConstraints": {
         "defaultOpen": {
           "type": "boolean"
@@ -3165,6 +3216,10 @@
           {
             "component": "ToastProvider",
             "reason": "a brief confirmation"
+          },
+          {
+            "component": "AlertDialog",
+            "reason": "confirming a destructive or irreversible action"
           }
         ]
       },
@@ -3185,7 +3240,8 @@
           "keys": "Shift+Tab",
           "effect": "Cycles focus backwards inside the open dialog."
         }
-      ]
+      ],
+      "core": true
     },
     "Button": {
       "category": "Actions",
@@ -3195,9 +3251,9 @@
       "docExempt": false,
       "filePath": "src/app/components/button.tsx",
       "description": "Triggers an action when activated.",
-      "figmaUrl": "https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=28-138",
+      "figmaUrl": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=28-138",
       "figmaId": null,
-      "figmaLink": "https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=28-138",
+      "figmaLink": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=28-138",
       "tier": "primitive",
       "preview": {
         "exportName": "Button",
@@ -3224,6 +3280,7 @@
         "src/app/components/pagination.tsx",
         "src/app/components/popover.tsx",
         "src/app/components/segmented-control.tsx",
+        "src/app/components/select.tsx",
         "src/app/components/toast.tsx",
         "src/app/context/DemoStateContext.tsx",
         "src/app/design-system/generated-token-descriptions.ts",
@@ -3457,7 +3514,8 @@
         "primitives-button--primary",
         "primitives-button--secondary",
         "primitives-button--small",
-        "primitives-button--tertiary"
+        "primitives-button--tertiary",
+        "primitives-button--tone-matrix"
       ],
       "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.",
@@ -3468,7 +3526,8 @@
             "reason": "navigation to another page"
           }
         ]
-      }
+      },
+      "core": true
     },
     "Callout": {
       "category": "Feedback",
@@ -3478,9 +3537,9 @@
       "docExempt": false,
       "filePath": "src/app/components/callout.tsx",
       "description": "Tone-driven side-rule callout for status, quotes, hypotheses.",
-      "figmaUrl": "https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=88-85",
+      "figmaUrl": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=88-85",
       "figmaId": null,
-      "figmaLink": "https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=88-85",
+      "figmaLink": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=88-85",
       "tier": "primitive",
       "preview": {
         "exportName": "Callout",
@@ -3555,9 +3614,9 @@
       "docExempt": false,
       "filePath": "src/app/components/empty-state.tsx",
       "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",
+      "figmaUrl": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=88-352",
       "figmaId": null,
-      "figmaLink": "https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=88-352",
+      "figmaLink": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=88-352",
       "tier": "primitive",
       "preview": {
         "exportName": "EmptyState",
@@ -3614,7 +3673,8 @@
           }
         ]
       },
-      "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."
+      "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.",
+      "core": true
     },
     "Field": {
       "category": "Display",
@@ -3624,9 +3684,9 @@
       "docExempt": false,
       "filePath": "src/app/components/field.tsx",
       "description": "Caption label paired with a value — used in metadata grids and read-only forms.",
-      "figmaUrl": "https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=85-81",
+      "figmaUrl": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=85-81",
       "figmaId": null,
-      "figmaLink": "https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=85-81",
+      "figmaLink": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=85-81",
       "tier": "primitive",
       "preview": {
         "exportName": "Field",
@@ -3730,7 +3790,8 @@
             "reason": "a headline figure inside a Card"
           }
         ]
-      }
+      },
+      "core": true
     },
     "Page": {
       "category": "Layout",
@@ -3824,10 +3885,10 @@
       "hidden": false,
       "docExempt": false,
       "filePath": "src/app/components/stat.tsx",
-      "description": "Headline metric — large value, uppercase caption label, optional sub-line.",
-      "figmaUrl": "https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=88-247",
+      "description": "Headline metric — large value, caption label, optional sub-line.",
+      "figmaUrl": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=88-247",
       "figmaId": null,
-      "figmaLink": "https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=88-247",
+      "figmaLink": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=88-247",
       "tier": "primitive",
       "preview": {
         "exportName": "Stat",
@@ -3902,9 +3963,13 @@
         "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.",
+        "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)"
@@ -3924,9 +3989,9 @@
       "docExempt": false,
       "filePath": "src/app/components/status-list-item.tsx",
       "description": "Status dot + title row with optional muted notes and trailing slot (e.g. badge).",
-      "figmaUrl": "https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=88-350",
+      "figmaUrl": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=88-350",
       "figmaId": null,
-      "figmaLink": "https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=88-350",
+      "figmaLink": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=88-350",
       "tier": "pattern",
       "preview": {
         "exportName": "StatusListItem",
@@ -4006,9 +4071,9 @@
       "docExempt": false,
       "filePath": "src/app/components/status-tile.tsx",
       "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.",
-      "figmaUrl": "https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=88-292",
+      "figmaUrl": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=88-292",
       "figmaId": null,
-      "figmaLink": "https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=88-292",
+      "figmaLink": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=88-292",
       "tier": "pattern",
       "preview": {
         "exportName": "StatusTile",
@@ -4069,11 +4134,15 @@
       ],
       "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",
@@ -4171,9 +4240,9 @@
       "governedCategory": true,
       "hidden": false,
       "docExempt": false,
-      "figmaUrl": "https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=31-15",
+      "figmaUrl": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=31-15",
       "figmaId": null,
-      "figmaLink": "https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=31-15",
+      "figmaLink": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=31-15",
       "tier": "primitive",
       "preview": {
         "exportName": "Badge",
@@ -4185,8 +4254,6 @@
         "src/app/components/badge.test.tsx",
         "src/app/components/card.tsx",
         "src/app/components/page-header.tsx",
-        "src/app/components/status-dot.test.tsx",
-        "src/app/components/status-dot.tsx",
         "src/app/components/tag.tsx",
         "src/app/design-system/generated-token-descriptions.ts",
         "src/mui/index.ts",
@@ -4230,7 +4297,8 @@
             "reason": "a message that needs a sentence"
           }
         ]
-      }
+      },
+      "core": true
     },
     "AssetImg": {
       "category": "Display",
@@ -4240,9 +4308,9 @@
       "docExempt": false,
       "filePath": "src/app/components/asset-img.tsx",
       "description": "AssetImg - responsive asset frame with fallback placeholder handling. Contexts: default, lightbox, and detail.",
-      "figmaUrl": null,
+      "figmaUrl": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=2041-67",
       "figmaId": null,
-      "figmaLink": null,
+      "figmaLink": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=2041-67",
       "tier": "primitive",
       "preview": {
         "exportName": "AssetImg",
@@ -4414,9 +4482,9 @@
       "docExempt": false,
       "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.",
-      "figmaUrl": "https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=86-89",
+      "figmaUrl": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=86-89",
       "figmaId": null,
-      "figmaLink": "https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=86-89",
+      "figmaLink": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=86-89",
       "tier": "primitive",
       "preview": {
         "exportName": "Tabs",
@@ -4499,7 +4567,8 @@
             "reason": "optional content that expands in place"
           }
         ]
-      }
+      },
+      "core": true
     },
     "TabsContent": {
       "category": "Navigation",
@@ -4657,7 +4726,7 @@
       "hidden": false,
       "filePath": "src/app/components/radio.tsx",
       "description": "Radio — radio button with animated selection indicator.",
-      "figmaUrl": "https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=36-17",
+      "figmaUrl": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=36-17",
       "figmaId": null,
       "preview": {
         "exportName": "Radio",
@@ -4707,7 +4776,7 @@
       "componentProperties": [],
       "tier": "primitive",
       "docExempt": false,
-      "figmaLink": "https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=36-17",
+      "figmaLink": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=36-17",
       "storyFiles": [
         "src/stories/radio.stories.tsx"
       ],
@@ -4735,7 +4804,8 @@
             "reason": "a compact switch between two to five views or modes"
           }
         ]
-      }
+      },
+      "core": true
     },
     "Select": {
       "category": "Inputs",
@@ -4744,7 +4814,7 @@
       "hidden": false,
       "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.",
-      "figmaUrl": "https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=82-49",
+      "figmaUrl": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=82-49",
       "figmaId": null,
       "preview": {
         "exportName": "Select",
@@ -4754,6 +4824,7 @@
         "src/app/components/checkbox.test.tsx",
         "src/app/components/combobox.test.tsx",
         "src/app/components/combobox.tsx",
+        "src/app/components/form-control.ts",
         "src/app/components/form.tsx",
         "src/app/components/input.tsx",
         "src/app/components/menu.tsx",
@@ -4820,7 +4891,7 @@
       "componentProperties": [],
       "tier": "primitive",
       "docExempt": false,
-      "figmaLink": "https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=82-49",
+      "figmaLink": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=82-49",
       "storyFiles": [
         "src/stories/select.stories.tsx"
       ],
@@ -4872,7 +4943,8 @@
           "keys": "Tab",
           "effect": "Does not leave the open listbox."
         }
-      ]
+      ],
+      "core": true
     },
     "Slider": {
       "category": "Inputs",
@@ -4881,13 +4953,14 @@
       "hidden": false,
       "filePath": "src/app/components/slider.tsx",
       "description": "Slider — range slider with label and value display.",
-      "figmaUrl": "https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=82-265",
+      "figmaUrl": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=82-265",
       "figmaId": null,
       "preview": {
         "exportName": "Slider",
         "sizing": "panel"
       },
       "consumers": [
+        "src/app/components/form-control.ts",
         "src/stories/slider.stories.tsx"
       ],
       "tokenMapping": {
@@ -4927,7 +5000,7 @@
       "componentProperties": [],
       "tier": "primitive",
       "docExempt": false,
-      "figmaLink": "https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=82-265",
+      "figmaLink": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=82-265",
       "storyFiles": [
         "src/stories/slider.stories.tsx"
       ],
@@ -4946,7 +5019,8 @@
             "reason": "a precise typed value (type=\"number\")"
           }
         ]
-      }
+      },
+      "core": true
     },
     "Toggle": {
       "category": "Inputs",
@@ -4955,7 +5029,7 @@
       "hidden": false,
       "filePath": "src/app/components/toggle.tsx",
       "description": "Toggle — boolean on/off toggle with animated thumb.",
-      "figmaUrl": "https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=37-19",
+      "figmaUrl": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=37-19",
       "figmaId": null,
       "preview": {
         "exportName": "Toggle",
@@ -5002,7 +5076,7 @@
       "componentProperties": [],
       "tier": "primitive",
       "docExempt": false,
-      "figmaLink": "https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=37-19",
+      "figmaLink": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=37-19",
       "storyFiles": [
         "src/stories/toggle.stories.tsx"
       ],
@@ -5026,7 +5100,8 @@
             "reason": "one choice from a set"
           }
         ]
-      }
+      },
+      "core": true
     },
     "Avatar": {
       "category": "Display",
@@ -5036,9 +5111,9 @@
       "docExempt": false,
       "filePath": "src/app/components/avatar.tsx",
       "description": "Circular avatar. Renders the image when available, else initials from `alt`.",
-      "figmaUrl": "https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=34-18",
+      "figmaUrl": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=34-18",
       "figmaId": null,
-      "figmaLink": "https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=34-18",
+      "figmaLink": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=34-18",
       "tier": "primitive",
       "preview": {
         "exportName": "Avatar",
@@ -5110,7 +5185,8 @@
             "reason": "a status marker"
           }
         ]
-      }
+      },
+      "core": true
     },
     "Progress": {
       "category": "Feedback",
@@ -5120,9 +5196,9 @@
       "docExempt": false,
       "filePath": "src/app/components/progress.tsx",
       "description": "Linear bar or circular ring. Determinate when `value` is a number, else indeterminate.",
-      "figmaUrl": "https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=88-91",
+      "figmaUrl": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=88-91",
       "figmaId": null,
-      "figmaLink": "https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=88-91",
+      "figmaLink": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=88-91",
       "tier": "primitive",
       "preview": {
         "exportName": "Progress",
@@ -5214,7 +5290,8 @@
             "reason": "placeholder shapes for loading content"
           }
         ]
-      }
+      },
+      "core": true
     },
     "Skeleton": {
       "category": "Feedback",
@@ -5224,9 +5301,9 @@
       "docExempt": false,
       "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.",
-      "figmaUrl": "https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=88-95",
+      "figmaUrl": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=88-95",
       "figmaId": null,
-      "figmaLink": "https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=88-95",
+      "figmaLink": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=88-95",
       "tier": "primitive",
       "preview": {
         "exportName": "Skeleton",
@@ -5292,7 +5369,8 @@
             "reason": "a short wait with no layout to reserve"
           }
         ]
-      }
+      },
+      "core": true
     },
     "Spinner": {
       "category": "Feedback",
@@ -5302,9 +5380,9 @@
       "docExempt": false,
       "filePath": "src/app/components/spinner.tsx",
       "description": "Indeterminate spinner. Inherits the surrounding text color via currentColor.",
-      "figmaUrl": "https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=88-106",
+      "figmaUrl": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=88-106",
       "figmaId": null,
-      "figmaLink": "https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=88-106",
+      "figmaLink": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=88-106",
       "tier": "primitive",
       "preview": {
         "exportName": "Spinner",
@@ -5364,7 +5442,8 @@
             "reason": "a region whose layout is known"
           }
         ]
-      }
+      },
+      "core": true
     },
     "Breadcrumb": {
       "category": "Navigation",
@@ -5374,9 +5453,9 @@
       "docExempt": false,
       "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\".",
-      "figmaUrl": "https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=86-159",
+      "figmaUrl": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=86-159",
       "figmaId": null,
-      "figmaLink": "https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=86-159",
+      "figmaLink": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=86-159",
       "tier": "pattern",
       "preview": {
         "exportName": "Breadcrumb",
@@ -5432,7 +5511,8 @@
             "reason": "stepping through pages of results"
           }
         ]
-      }
+      },
+      "core": true
     },
     "Pagination": {
       "category": "Navigation",
@@ -5442,9 +5522,9 @@
       "docExempt": false,
       "filePath": "src/app/components/pagination.tsx",
       "description": "Paged navigation with first/last anchors, sibling pages, and ellipses.",
-      "figmaUrl": "https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=86-194",
+      "figmaUrl": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=86-194",
       "figmaId": null,
-      "figmaLink": "https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=86-194",
+      "figmaLink": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=86-194",
       "tier": "pattern",
       "preview": {
         "exportName": "Pagination",
@@ -5503,7 +5583,8 @@
             "reason": "a hierarchy trail"
           }
         ]
-      }
+      },
+      "core": true
     },
     "ToastProvider": {
       "category": "Feedback",
@@ -5513,15 +5594,16 @@
       "docExempt": true,
       "filePath": "src/app/components/toast.tsx",
       "description": "Provider + viewport for the toast system. Wrap the app root once.",
-      "figmaUrl": "https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=93-367",
+      "figmaUrl": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=93-367",
       "figmaId": null,
-      "figmaLink": "https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=93-367",
+      "figmaLink": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=93-367",
       "tier": "pattern",
       "preview": {
         "exportName": "ToastProvider",
         "sizing": "panel"
       },
       "consumers": [
+        "src/app/components/alert-dialog.tsx",
         "src/app/components/alert.tsx",
         "src/app/components/dialog.tsx",
         "src/app/components/toast.test.tsx",
@@ -5573,7 +5655,8 @@
             "reason": "a message that needs a decision"
           }
         ]
-      }
+      },
+      "core": true
     },
     "Combobox": {
       "category": "Inputs",
@@ -5583,9 +5666,9 @@
       "docExempt": true,
       "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\" />",
-      "figmaUrl": "https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=82-237",
+      "figmaUrl": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=82-237",
       "figmaId": null,
-      "figmaLink": "https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=82-237",
+      "figmaLink": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=82-237",
       "tier": "pattern",
       "preview": {
         "exportName": "Combobox",
@@ -5593,6 +5676,7 @@
       },
       "consumers": [
         "src/app/components/combobox.test.tsx",
+        "src/app/components/form-control.ts",
         "src/app/components/form.tsx",
         "src/app/components/input.tsx",
         "src/app/components/select.tsx",
@@ -5714,7 +5798,8 @@
           "keys": "Tab",
           "effect": "Stays inside the open list."
         }
-      ]
+      ],
+      "core": true
     },
     "Form": {
       "category": "Inputs",
@@ -5724,9 +5809,9 @@
       "docExempt": true,
       "filePath": "src/app/components/form.tsx",
       "description": "Styled `<form>` with consistent vertical field rhythm. Tagged per-export: FormField and FormFieldShell share this module and have no Figma node, so a file-level @figma would claim this one for all three.",
-      "figmaUrl": "https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=85-94",
+      "figmaUrl": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=85-94",
       "figmaId": null,
-      "figmaLink": "https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=85-94",
+      "figmaLink": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=85-94",
       "tier": "pattern",
       "preview": {
         "exportName": "Form",
@@ -5988,7 +6073,8 @@
             "reason": "a single region with its own background"
           }
         ]
-      }
+      },
+      "core": true
     },
     "AvatarGroup": {
       "category": "Display",
@@ -5998,9 +6084,9 @@
       "docExempt": false,
       "filePath": "src/app/components/avatar-group.tsx",
       "description": "Renders up to `max` overlapping avatars followed by a `+N` overflow chip.",
-      "figmaUrl": null,
+      "figmaUrl": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=2030-63",
       "figmaId": null,
-      "figmaLink": null,
+      "figmaLink": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=2030-63",
       "tier": "primitive",
       "preview": {
         "exportName": "AvatarGroup",
@@ -6054,9 +6140,9 @@
       "docExempt": false,
       "filePath": "src/app/components/blockquote.tsx",
       "description": "A quoted passage; pass `cite` for the source URL and `attribution` for a byline.",
-      "figmaUrl": null,
+      "figmaUrl": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=2024-18",
       "figmaId": null,
-      "figmaLink": null,
+      "figmaLink": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=2024-18",
       "tier": "primitive",
       "preview": {
         "exportName": "Blockquote",
@@ -6107,9 +6193,9 @@
       "docExempt": false,
       "filePath": "src/app/components/kbd.tsx",
       "description": "Renders a keyboard key or shortcut token, e.g. `<Kbd>⌘K</Kbd>`.",
-      "figmaUrl": null,
+      "figmaUrl": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=2026-9",
       "figmaId": null,
-      "figmaLink": null,
+      "figmaLink": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=2026-9",
       "tier": "primitive",
       "preview": {
         "exportName": "Kbd",
@@ -6157,83 +6243,8 @@
             "reason": "inline code and other typography"
           }
         ]
-      }
-    },
-    "StatusDot": {
-      "category": "Feedback",
-      "categorySource": "jsdoc",
-      "governedCategory": true,
-      "hidden": false,
-      "docExempt": false,
-      "filePath": "src/app/components/status-dot.tsx",
-      "description": "A small solid dot conveying a semantic status via `tone`.",
-      "figmaUrl": null,
-      "figmaId": null,
-      "figmaLink": null,
-      "tier": "primitive",
-      "preview": {
-        "exportName": "StatusDot",
-        "sizing": "panel"
-      },
-      "consumers": [
-        "src/app/components/status-dot.test.tsx",
-        "src/stories/status-dot.stories.tsx"
-      ],
-      "tokenMapping": {},
-      "variantAxes": [],
-      "componentProperties": [],
-      "props": {
-        "label": {
-          "type": "string",
-          "optional": true
-        },
-        "size": {
-          "type": "enum",
-          "values": [
-            "sm",
-            "md",
-            "lg"
-          ],
-          "optional": true
-        },
-        "tone": {
-          "type": "enum",
-          "values": [
-            "success",
-            "danger",
-            "warning",
-            "info",
-            "neutral",
-            "inProgress"
-          ],
-          "optional": true
-        }
-      },
-      "allowedChildren": [
-        "*"
-      ],
-      "propConstraints": {},
-      "requiredProps": [],
-      "a11yRules": [],
-      "storyFiles": [
-        "src/stories/status-dot.stories.tsx"
-      ],
-      "storyIds": [
-        "primitives-status-dot--default",
-        "primitives-status-dot--tones",
-        "primitives-status-dot--with-label-text"
-      ],
-      "usage": {
-        "useInstead": [
-          {
-            "component": "Badge",
-            "reason": "with `dot`"
-          }
-        ]
       },
-      "deprecated": "Use `<Badge dot>`: `tone`, `size` and `label` are the same, and so is the dot. Badge takes no `style`, so move a `style` to a wrapper or a `className` first (MIGRATIONS.md, hds#395). Kept in 0.20.0 because ops passes StatusDot a `style` no codemod can carry over.",
-      "removeIn": "0.21.0",
-      "useInstead": "Badge"
+      "core": true
     },
     "Timestamp": {
       "category": "Display",
@@ -6243,9 +6254,9 @@
       "docExempt": false,
       "filePath": "src/app/components/timestamp.tsx",
       "description": "Presents a date/time with a machine-readable `dateTime` for accessibility.",
-      "figmaUrl": null,
+      "figmaUrl": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=2031-11",
       "figmaId": null,
-      "figmaLink": null,
+      "figmaLink": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=2031-11",
       "tier": "primitive",
       "preview": {
         "exportName": "Timestamp",
@@ -6345,7 +6356,8 @@
             "reason": "text that everyone should read"
           }
         ]
-      }
+      },
+      "core": true
     },
     "MetadataList": {
       "category": "Display",
@@ -6355,9 +6367,9 @@
       "docExempt": false,
       "filePath": "src/app/components/metadata-list.tsx",
       "description": "Renders object metadata as a semantic `<dl>` of term/description pairs.",
-      "figmaUrl": null,
+      "figmaUrl": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=2041-47",
       "figmaId": null,
-      "figmaLink": null,
+      "figmaLink": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=2041-47",
       "tier": "pattern",
       "preview": {
         "exportName": "MetadataList",
@@ -6418,9 +6430,9 @@
       "docExempt": true,
       "filePath": "src/app/components/alert-dialog.tsx",
       "description": "AlertDialog root + parts. Controlled via `open`/`onOpenChange`, or uncontrolled with `defaultOpen`.",
-      "figmaUrl": null,
+      "figmaUrl": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=2035-24",
       "figmaId": null,
-      "figmaLink": null,
+      "figmaLink": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=2035-24",
       "tier": "primitive",
       "preview": {
         "exportName": "AlertDialog",
@@ -6429,6 +6441,7 @@
       "consumers": [
         "src/app/components/alert-dialog.test.tsx",
         "src/app/components/destructive-section.tsx",
+        "src/app/components/dialog.tsx",
         "src/app/context/__tests__/portal-hydration.test.tsx",
         "src/app/context/__tests__/portal-scope.test.tsx",
         "src/stories/alert-dialog.stories.tsx",
@@ -6468,7 +6481,21 @@
       "storyIds": [
         "primitives-alert-dialog--dark-scope",
         "primitives-alert-dialog--default"
-      ]
+      ],
+      "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"
+          }
+        ]
+      }
     },
     "Box": {
       "category": "Layout",
@@ -6554,7 +6581,8 @@
           }
         ]
       },
-      "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."
+      "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.",
+      "core": true
     },
     "Sidebar": {
       "category": "Layout",
@@ -6859,16 +6887,18 @@
       "docExempt": false,
       "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.",
-      "figmaUrl": "https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=85-14",
+      "figmaUrl": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=85-14",
       "figmaId": null,
-      "figmaLink": "https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=85-14",
+      "figmaLink": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=85-14",
       "tier": "primitive",
       "preview": {
         "exportName": "Textarea",
         "sizing": "panel"
       },
       "consumers": [
+        "src/app/components/form-control.ts",
         "src/app/components/input.tsx",
+        "src/app/components/select.tsx",
         "src/stories/patterns-client-detail.stories.tsx",
         "src/stories/textarea.stories.tsx"
       ],
@@ -6934,7 +6964,8 @@
             "reason": "a single line of text"
           }
         ]
-      }
+      },
+      "core": true
     },
     "CardBody": {
       "category": "Display",
@@ -6943,7 +6974,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 — 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.",
       "figmaUrl": null,
       "figmaId": null,
       "figmaLink": null,
@@ -6979,6 +7010,7 @@
         "primitives-card--padding-variants",
         "primitives-card--progress-slot",
         "primitives-card--selectable",
+        "primitives-card--tone-matrix",
         "primitives-card--variant-accent"
       ]
     },
@@ -6989,7 +7021,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 — 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.",
       "figmaUrl": null,
       "figmaId": null,
       "figmaLink": null,
@@ -7025,6 +7057,7 @@
         "primitives-card--padding-variants",
         "primitives-card--progress-slot",
         "primitives-card--selectable",
+        "primitives-card--tone-matrix",
         "primitives-card--variant-accent"
       ]
     },
@@ -7035,7 +7068,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 — 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.",
       "figmaUrl": null,
       "figmaId": null,
       "figmaLink": null,
@@ -7071,6 +7104,7 @@
         "primitives-card--padding-variants",
         "primitives-card--progress-slot",
         "primitives-card--selectable",
+        "primitives-card--tone-matrix",
         "primitives-card--variant-accent"
       ]
     },
@@ -7081,7 +7115,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 — 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.",
       "figmaUrl": null,
       "figmaId": null,
       "figmaLink": null,
@@ -7122,6 +7156,7 @@
         "primitives-card--padding-variants",
         "primitives-card--progress-slot",
         "primitives-card--selectable",
+        "primitives-card--tone-matrix",
         "primitives-card--variant-accent"
       ]
     },
@@ -7132,7 +7167,7 @@
       "hidden": false,
       "docExempt": false,
       "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.",
       "figmaUrl": null,
       "figmaId": null,
       "figmaLink": null,
@@ -7190,11 +7225,18 @@
         "primitives-card--padding-variants",
         "primitives-card--progress-slot",
         "primitives-card--selectable",
+        "primitives-card--tone-matrix",
         "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."
+        "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"
+          }
+        ]
       }
     },
     "CardProgress": {
@@ -7204,7 +7246,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 — 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.",
       "figmaUrl": null,
       "figmaId": null,
       "figmaLink": null,
@@ -7263,6 +7305,7 @@
         "primitives-card--padding-variants",
         "primitives-card--progress-slot",
         "primitives-card--selectable",
+        "primitives-card--tone-matrix",
         "primitives-card--variant-accent"
       ]
     },
@@ -7273,7 +7316,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 — 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.",
       "figmaUrl": null,
       "figmaId": null,
       "figmaLink": null,
@@ -7309,6 +7352,7 @@
         "primitives-card--padding-variants",
         "primitives-card--progress-slot",
         "primitives-card--selectable",
+        "primitives-card--tone-matrix",
         "primitives-card--variant-accent"
       ]
     },
@@ -7763,7 +7807,7 @@
       "docExempt": true,
       "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`.",
-      "figmaUrl": "https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=93-15",
+      "figmaUrl": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=93-15",
       "figmaId": null,
       "tier": "primitive",
       "preview": {
@@ -7782,7 +7826,7 @@
       "tokenMapping": {},
       "variantAxes": [],
       "componentProperties": [],
-      "figmaLink": "https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=93-15",
+      "figmaLink": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=93-15",
       "props": {
         "children": {
           "type": "React.ReactNode",
@@ -7849,7 +7893,8 @@
           "keys": "Tab",
           "effect": "Moves on to the next control and closes the tooltip."
         }
-      ]
+      ],
+      "core": true
     },
     "Menu": {
       "category": "Overlays",
@@ -7859,9 +7904,9 @@
       "docExempt": true,
       "filePath": "src/app/components/menu.tsx",
       "description": "Menu root + parts. Controlled via `open`/`onOpenChange`, or uncontrolled with `defaultOpen`.",
-      "figmaUrl": "https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=93-59",
+      "figmaUrl": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=93-59",
       "figmaId": null,
-      "figmaLink": "https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=93-59",
+      "figmaLink": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=93-59",
       "tier": "primitive",
       "preview": {
         "exportName": "Menu",
@@ -7972,7 +8017,8 @@
           "keys": "Tab",
           "effect": "Does not leave the open menu."
         }
-      ]
+      ],
+      "core": true
     },
     "Popover": {
       "category": "Overlays",
@@ -7982,9 +8028,9 @@
       "docExempt": true,
       "filePath": "src/app/components/popover.tsx",
       "description": "Popover root + parts. Controlled via `open`/`onOpenChange`, or uncontrolled with `defaultOpen`.",
-      "figmaUrl": "https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=93-32",
+      "figmaUrl": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=93-32",
       "figmaId": null,
-      "figmaLink": "https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=93-32",
+      "figmaLink": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=93-32",
       "tier": "primitive",
       "preview": {
         "exportName": "Popover",
@@ -8073,7 +8119,8 @@
           "keys": "Tab",
           "effect": "Cycles focus inside the open popover; the page behind stays reachable."
         }
-      ]
+      ],
+      "core": true
     },
     "Checkbox": {
       "category": "Inputs",
@@ -8083,9 +8130,9 @@
       "docExempt": false,
       "filePath": "src/app/components/checkbox.tsx",
       "description": "Checkbox — custom-drawn checkbox with check / indeterminate glyph.",
-      "figmaUrl": "https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=35-29",
+      "figmaUrl": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=35-29",
       "figmaId": null,
-      "figmaLink": "https://www.figma.com/design/c8MaVgwxOlxm4wr8wnH0Z4/HDS-Tokens-Components?node-id=35-29",
+      "figmaLink": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=35-29",
       "tier": "primitive",
       "preview": {
         "exportName": "Checkbox",
@@ -8145,7 +8192,8 @@
             "reason": "exactly one choice from a set"
           }
         ]
-      }
+      },
+      "core": true
     },
     "FormActions": {
       "category": "Actions",
@@ -8155,9 +8203,9 @@
       "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,
+      "figmaUrl": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=2075-87",
       "figmaId": null,
-      "figmaLink": null,
+      "figmaLink": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=2075-87",
       "tier": "pattern",
       "preview": {
         "exportName": "FormActions",
@@ -8212,9 +8260,9 @@
       "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,
+      "figmaUrl": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=2075-114",
       "figmaId": null,
-      "figmaLink": null,
+      "figmaLink": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=2075-114",
       "tier": "pattern",
       "preview": {
         "exportName": "MetricTile",
@@ -8222,6 +8270,8 @@
       },
       "consumers": [
         "src/app/components/metric-tiles.test.tsx",
+        "src/app/components/stat.tsx",
+        "src/stories/metric-tile.stories.tsx",
         "src/stories/metric-tiles.stories.tsx",
         "src/stories/patterns-client-detail.stories.tsx"
       ],
@@ -8258,9 +8308,12 @@
       "requiredProps": [],
       "a11yRules": [],
       "storyFiles": [
+        "src/stories/metric-tile.stories.tsx",
         "src/stories/metric-tiles.stories.tsx"
       ],
       "storyIds": [
+        "patterns-metrictile--danger",
+        "patterns-metrictile--default",
         "patterns-metrictiles--four-tiles",
         "patterns-metrictiles--sub-line-optional",
         "patterns-metrictiles--three-tiles",
@@ -8284,7 +8337,11 @@
         "sizing": "panel"
       },
       "consumers": [
+        "src/app/components/card.tsx",
         "src/app/components/metric-tiles.test.tsx",
+        "src/app/components/stat.tsx",
+        "src/app/components/status-tile.tsx",
+        "src/stories/metric-tile.stories.tsx",
         "src/stories/metric-tiles.stories.tsx",
         "src/stories/patterns-client-detail.stories.tsx"
       ],
@@ -8303,9 +8360,12 @@
       "requiredProps": [],
       "a11yRules": [],
       "storyFiles": [
+        "src/stories/metric-tile.stories.tsx",
         "src/stories/metric-tiles.stories.tsx"
       ],
       "storyIds": [
+        "patterns-metrictile--danger",
+        "patterns-metrictile--default",
         "patterns-metrictiles--four-tiles",
         "patterns-metrictiles--sub-line-optional",
         "patterns-metrictiles--three-tiles",
@@ -8387,9 +8447,9 @@
       "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,
+      "figmaUrl": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=2075-268",
       "figmaId": null,
-      "figmaLink": null,
+      "figmaLink": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=2075-268",
       "tier": "pattern",
       "preview": {
         "exportName": "DataTableSection",
@@ -8459,9 +8519,9 @@
       "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,
+      "figmaUrl": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=2076-3",
       "figmaId": null,
-      "figmaLink": null,
+      "figmaLink": "https://www.figma.com/design/2VgBbVpKiDnu0aftJEVyBQ/HDS-Tokens-Components?node-id=2076-3",
       "tier": "pattern",
       "preview": {
         "exportName": "DestructiveSection",
@@ -8561,7 +8621,8 @@
       "storyIds": [],
       "usage": {
         "when": "Wrap the app root once so HDS links and navigation use your client router; with no provider they stay plain anchors."
-      }
+      },
+      "core": true
     },
     "HdsPhosphor": {
       "category": "Compiler",
@@ -9658,7 +9719,7 @@
         "path": "primitive.typography.family.display",
         "cssVar": "--primitive-typography-family-display",
         "type": "fontFamily",
-        "description": "Display face: Satoshi Bold (ITF), bound to display/h1/h2/h3 composites.",
+        "description": "Display face: Satoshi Bold (ITF), bound to the display and title composites.",
         "value": "Satoshi, system-ui, -apple-system, BlinkMacSystemFont, \"Segoe UI\", sans-serif"
       },
       {
@@ -9738,6 +9799,13 @@
         "description": "Swiss-canon display size (hds#283 ramp). Static desktop value; fluid in theme.css. Tailwind 4 default text-6xl.",
         "value": "60px"
       },
+      {
+        "path": "primitive.typography.size.code",
+        "cssVar": "--primitive-typography-size-code",
+        "type": "dimension",
+        "description": "13px code size. The mono role (hds#485): one px below ui so code sits level with 14px prose.",
+        "value": "13px"
+      },
       {
         "path": "primitive.typography.weight.regular",
         "cssVar": "--primitive-typography-weight-regular",
@@ -9794,6 +9862,20 @@
         "description": "Swiss-canon relaxed rhythm (10t-5). Used by body/small/mono composites for long-form prose comfort.",
         "value": "1.625"
       },
+      {
+        "path": "primitive.typography.lineHeight.display",
+        "cssVar": "--primitive-typography-lineHeight-display",
+        "type": "number",
+        "description": "Display role leading (hds#485).",
+        "value": "1.05"
+      },
+      {
+        "path": "primitive.typography.lineHeight.body",
+        "cssVar": "--primitive-typography-lineHeight-body",
+        "type": "number",
+        "description": "Body role leading (hds#485).",
+        "value": "1.6"
+      },
       {
         "path": "primitive.typography.letterSpacing.tight",
         "cssVar": "--primitive-typography-letterSpacing-tight",
@@ -10904,65 +10986,39 @@
         "path": "semantic.typography.display",
         "cssVar": "--semantic-typography-display",
         "type": "typography",
-        "description": "Display headline. 60px / Satoshi bold 700 / leading-none (hds#283: was 72px/5xl).",
-        "composite": {
-          "fontFamily": "Satoshi, system-ui, -apple-system, BlinkMacSystemFont, \"Segoe UI\", sans-serif",
-          "fontSize": "60px",
-          "fontWeight": "700",
-          "letterSpacing": "-0.01em",
-          "lineHeight": "1"
-        }
-      },
-      {
-        "path": "semantic.typography.h1",
-        "cssVar": "--semantic-typography-h1",
-        "type": "typography",
-        "description": "Primary section headings (h1). 48px / Satoshi bold 700 / leading-tight (hds#283: rung renamed 4xl→5xl, px unchanged).",
+        "description": "One per page, hero only. 48px / 1.05 / 700. Role 1 of 6.",
         "composite": {
           "fontFamily": "Satoshi, system-ui, -apple-system, BlinkMacSystemFont, \"Segoe UI\", sans-serif",
           "fontSize": "48px",
           "fontWeight": "700",
           "letterSpacing": "-0.01em",
-          "lineHeight": "1.25"
+          "lineHeight": "1.05"
         }
       },
       {
-        "path": "semantic.typography.h2",
-        "cssVar": "--semantic-typography-h2",
+        "path": "semantic.typography.title",
+        "cssVar": "--semantic-typography-title",
         "type": "typography",
-        "description": "Secondary section headings (h2). Satoshi bold 700, 30px, line-height 40px (hds#283: rung renamed, was 42px).",
+        "description": "Section and card headings. 24px / 1.25 / 700. Role 2 of 6.",
         "composite": {
           "fontFamily": "Satoshi, system-ui, -apple-system, BlinkMacSystemFont, \"Segoe UI\", sans-serif",
-          "fontSize": "30px",
+          "fontSize": "24px",
           "fontWeight": "700",
           "letterSpacing": "-0.01em",
-          "lineHeight": "40px"
-        }
-      },
-      {
-        "path": "semantic.typography.h3",
-        "cssVar": "--semantic-typography-h3",
-        "type": "typography",
-        "description": "Component and card headers (h3). 20px / Satoshi bold 700 500 / leading-snug (hds#283: rung renamed lg→xl, px unchanged).",
-        "composite": {
-          "fontFamily": "Satoshi, system-ui, -apple-system, BlinkMacSystemFont, \"Segoe UI\", sans-serif",
-          "fontSize": "20px",
-          "fontWeight": "700",
-          "letterSpacing": "0em",
-          "lineHeight": "28px"
+          "lineHeight": "1.25"
         }
       },
       {
         "path": "semantic.typography.body",
         "cssVar": "--semantic-typography-body",
         "type": "typography",
-        "description": "Body prose. Satoshi medium, 16px, line-height 24px, max 60ch measure (hds#283: was 17px/28px).",
+        "description": "Prose. 16px / 1.6 / 400, 60ch measure. Role 3 of 6.",
         "composite": {
           "fontFamily": "Satoshi, system-ui, -apple-system, BlinkMacSystemFont, \"Segoe UI\", sans-serif",
           "fontSize": "16px",
-          "fontWeight": "500",
+          "fontWeight": "400",
           "letterSpacing": "0em",
-          "lineHeight": "24px",
+          "lineHeight": "1.6",
           "maxWidth": "60ch"
         }
       },
@@ -10970,13 +11026,13 @@
         "path": "semantic.typography.ui",
         "cssVar": "--semantic-typography-ui",
         "type": "typography",
-        "description": "UI text for nav, labels, captions. Satoshi medium, 14px, line-height 20px (hds#283: was 15px/24px).",
+        "description": "Controls, nav, table text, values. 14px / 1.5 / 500. Role 4 of 6.",
         "composite": {
           "fontFamily": "Satoshi, system-ui, -apple-system, BlinkMacSystemFont, \"Segoe UI\", sans-serif",
           "fontSize": "14px",
           "fontWeight": "500",
           "letterSpacing": "0em",
-          "lineHeight": "20px",
+          "lineHeight": "1.5",
           "maxWidth": "60ch"
         }
       },
@@ -10984,41 +11040,79 @@
         "path": "semantic.typography.caption",
         "cssVar": "--semantic-typography-caption",
         "type": "typography",
-        "description": "Caption / helper text. Satoshi medium, 12px, line-height 16px. Matches the Figma typography/caption text style; now sourced from primitive.xs (hds#283).",
+        "description": "Metadata, help text and labels, in sentence case. 12px / 1.5 / 500. Role 5 of 6.",
         "composite": {
           "fontFamily": "Satoshi, system-ui, -apple-system, BlinkMacSystemFont, \"Segoe UI\", sans-serif",
           "fontSize": "12px",
           "fontWeight": "500",
           "letterSpacing": "0em",
-          "lineHeight": "16px"
+          "lineHeight": "1.5"
         }
       },
       {
-        "path": "semantic.typography.eyebrow",
-        "cssVar": "--semantic-typography-eyebrow",
+        "path": "semantic.typography.mono",
+        "cssVar": "--semantic-typography-mono",
+        "type": "typography",
+        "description": "Code and ids. 13px / 1.5 / 400. The mono companion, role 6 of 6.",
+        "composite": {
+          "fontFamily": "\"Geist Mono\", \"Courier New\", monospace",
+          "fontSize": "13px",
+          "fontWeight": "400",
+          "letterSpacing": "0em",
+          "lineHeight": "1.5",
+          "maxWidth": "60ch"
+        }
+      },
+      {
+        "path": "semantic.typography.h1",
+        "cssVar": "--semantic-typography-h1",
         "type": "typography",
-        "description": "Eyebrow / kicker label. Satoshi medium, 12px, caps tracking, uppercase (hds#283: was 13px/20px).",
+        "description": "deprecated: use semantic.typography.title",
         "composite": {
           "fontFamily": "Satoshi, system-ui, -apple-system, BlinkMacSystemFont, \"Segoe UI\", sans-serif",
-          "fontSize": "12px",
-          "fontWeight": "500",
-          "letterSpacing": "0.06em",
-          "lineHeight": "16px",
-          "textTransform": "uppercase"
+          "fontSize": "24px",
+          "fontWeight": "700",
+          "letterSpacing": "-0.01em",
+          "lineHeight": "1.25"
         }
       },
       {
-        "path": "semantic.typography.mono",
-        "cssVar": "--semantic-typography-mono",
+        "path": "semantic.typography.h2",
+        "cssVar": "--semantic-typography-h2",
         "type": "typography",
-        "description": "Monospace for code, token names, shortcuts. Geist Mono regular, 14px (hds#283: repointed xs→sm; xs alone would give 12px).",
+        "description": "deprecated: use semantic.typography.title",
         "composite": {
-          "fontFamily": "\"Geist Mono\", \"Courier New\", monospace",
-          "fontSize": "14px",
-          "fontWeight": "400",
+          "fontFamily": "Satoshi, system-ui, -apple-system, BlinkMacSystemFont, \"Segoe UI\", sans-serif",
+          "fontSize": "24px",
+          "fontWeight": "700",
+          "letterSpacing": "-0.01em",
+          "lineHeight": "1.25"
+        }
+      },
+      {
+        "path": "semantic.typography.h3",
+        "cssVar": "--semantic-typography-h3",
+        "type": "typography",
+        "description": "deprecated: use semantic.typography.title",
+        "composite": {
+          "fontFamily": "Satoshi, system-ui, -apple-system, BlinkMacSystemFont, \"Segoe UI\", sans-serif",
+          "fontSize": "24px",
+          "fontWeight": "700",
+          "letterSpacing": "-0.01em",
+          "lineHeight": "1.25"
+        }
+      },
+      {
+        "path": "semantic.typography.eyebrow",
+        "cssVar": "--semantic-typography-eyebrow",
+        "type": "typography",
+        "description": "deprecated: use semantic.typography.caption",
+        "composite": {
+          "fontFamily": "Satoshi, system-ui, -apple-system, BlinkMacSystemFont, \"Segoe UI\", sans-serif",
+          "fontSize": "12px",
+          "fontWeight": "500",
           "letterSpacing": "0em",
-          "lineHeight": "20px",
-          "maxWidth": "60ch"
+          "lineHeight": "1.5"
         }
       },
       {
@@ -11483,10 +11577,10 @@
       {
         "path": "component.tag.lineHeight",
         "cssVar": "--component-tag-lineHeight",
-        "type": "dimension",
+        "type": "number",
         "description": "Readable label rhythm for tags.",
         "alias": "{primitive.typography.lineHeight.normal}",
-        "resolvedValue": "undefinedundefined"
+        "resolvedValue": "1.5"
       },
       {
         "path": "component.tag.minWidth",