@assure-one/design-system 1.37.0 → 1.38.0

package/docs/components.registry.json

@@ -15,74 +15,455 @@
     "hooks/utilities": "Non-rendering exports: hooks, class-name helpers, formatters and token objects."
   },
   "needs": [
-    { "need": "Trigger an action", "use": ["Button", "IconButton"], "notes": "`IconButton` when the control is only an icon (it requires an accessible name and shows a tooltip). Same `variant` × `intent` × `size` axes." },
-    { "need": "Navigate somewhere with a button look", "use": ["LinkButton"], "notes": "Renders an `<a href>`; `Button asChild` around your router's `Link` is the alternative." },
-    { "need": "Submit a form", "use": ["SubmitButton"], "notes": "Full-width by default; `type=\"submit\"` and pending state handled." },
-    { "need": "Make something that is not a button clickable", "use": ["Pressable"], "notes": "Keyboard, focus ring, disabled handling, no button chrome. Never `<div onClick>`." },
-    { "need": "Confirm a destructive action", "use": ["ConfirmActionButton", "ConfirmDialog", "ConfirmHost"], "notes": "`ConfirmActionButton` wraps the dialog around any trigger; `ConfirmDialog` when you control `open` or need a form field in the body; `useConfirm()` / `usePrompt()` to `await` an answer from an event handler (needs `DesignSystemProvider confirm` or a `ConfirmHost`)." },
-    { "need": "Act on selected rows", "use": ["BulkActionBar"], "notes": "Floating bar with the count and the row actions." },
-    { "need": "Keep Save / Cancel visible at the bottom of a long form", "use": ["StickyActionBar"] },
-    { "need": "Label + help + error around any control", "use": ["Field"], "notes": "`Label`, `FieldDescription`, `FieldError` inside; controls bind automatically. `Fieldset` groups several. `FieldControl` wires a non-DS control." },
-    { "need": "Free text, one line", "use": ["Input"], "notes": "`SearchInput` for search boxes, `NumberInput` for numbers, `PhoneField` for phone numbers, `OTPInput` for codes." },
-    { "need": "A phone number", "use": ["PhoneField"], "notes": "Country picker + national number, E.164 value. `PhoneInput` and `PhoneCountryInput` are deprecated." },
-    { "need": "Free text, several lines", "use": ["Textarea"] },
-    { "need": "A number with formatting or steppers", "use": ["NumberInput"] },
-    { "need": "A date, or a date range", "use": ["DatePicker", "DateRangePicker"], "notes": "`Calendar` alone when the picker should be inline rather than in a popover." },
-    { "need": "Upload files", "use": ["FileUpload"], "notes": "`DocumentRequestUpload` for the client-portal request flow." },
-    { "need": "Yes / no", "use": ["Checkbox", "Switch"], "notes": "`Switch` when the change applies immediately, `Checkbox` when it is submitted with the form or is one of several." },
-    { "need": "One of a few visible options", "use": ["RadioGroup", "ToggleGroup"], "notes": "`RadioGroup` in forms; `ToggleGroup` for view/mode switches with immediate effect." },
-    { "need": "One of many options in a dropdown", "use": ["Select", "Combobox"], "notes": "`Select` for short static lists; `Combobox` when the user should type to filter or the list is large or async." },
-    { "need": "Several of many options", "use": ["MultiSelect", "MultiSelectField"], "notes": "`MultiSelect` is the searchable dropdown; `MultiSelectField` a visible pill toggle row for a handful of options." },
-    { "need": "Pick a client or a team member", "use": ["ClientSelect", "TeamMemberSelect"] },
-    { "need": "Filter a list", "use": ["Toolbar", "MultiFilterPill", "DisplayMenu"], "notes": "`FilterChip` inside `Toolbar` for one-value filters, `MultiFilterPill` for multi-value, `DisplayMenu` for the Linear-style filter/group/sort/columns menu." },
-    { "need": "Removable or toggleable tokens (tags, applied filters)", "use": ["Chip"], "notes": "`DismissibleChip` is the older single-purpose removable chip." },
-    { "need": "A slider value", "use": ["Slider"] },
-    { "need": "Show a message inline (success, warning, error, info)", "use": ["Alert"] },
-    { "need": "Notify after an action", "use": ["ToastProvider"], "notes": "`useToast()` from inside the provider." },
-    { "need": "Show loading", "use": ["Spinner", "Skeleton", "LoadingRows"], "notes": "`Spinner` inside a control or small area, `Skeleton` for a shape, `LoadingRows` for list/table rows." },
-    { "need": "Show progress", "use": ["ProgressBar", "ProgressRing", "SegmentedProgress", "Stepper"], "notes": "`Stepper` when the steps have names; `SuiteProgress` for the suite's segmented percent meter." },
-    { "need": "Nothing to show yet", "use": ["EmptyState", "ComingSoon"] },
-    { "need": "A modal task or message", "use": ["Dialog", "ResponsiveDialog"], "notes": "`ResponsiveDialog` becomes a `Sheet` on small screens." },
-    { "need": "A side panel", "use": ["Sheet", "SideDrawer"], "notes": "`Sheet` is the Radix-based standard; `SideDrawer` is the older API kept for existing call sites." },
-    { "need": "A contextual menu of actions", "use": ["DropdownMenu", "ContextMenu", "NewMenu"], "notes": "`ContextMenu` on right-click; `NewMenu` is the ready-made \"+ New\" creation menu." },
-    { "need": "Extra content on hover or click", "use": ["Tooltip", "Popover", "HoverCard"], "notes": "`Tooltip` for a short label, `Popover` for interactive content, `HoverCard` for a rich preview on hover." },
-    { "need": "A global command / search box", "use": ["CommandPalette", "KeyboardShortcutsDialog"] },
-    { "need": "Switch between views", "use": ["Tabs", "ChannelTabs", "BottomNav"], "notes": "`BottomNav` is the mobile tab bar." },
-    { "need": "Where am I", "use": ["Breadcrumb", "PageHeader", "AppHeader"] },
-    { "need": "Page through results", "use": ["Pagination"], "notes": "`DataTablePagination` inside a `DataTable`." },
-    { "need": "A tree or a rail of items", "use": ["FolderTree", "ClientRailItem"] },
-    { "need": "Space things out", "use": ["Stack", "Inline"], "notes": "Tokenised gap and alignment; never ad-hoc `flex gap-*` in product code." },
-    { "need": "A bordered box or card", "use": ["Surface", "Card"], "notes": "`Card` adds header/title/description/footer parts and an interactive variant." },
-    { "need": "A divider", "use": ["Separator", "CategoryDivider"] },
-    { "need": "Collapse content", "use": ["Collapsible", "Accordion"] },
-    { "need": "Scroll a region", "use": ["ScrollArea"] },
-    { "need": "Title a page or a section", "use": ["PageHeader", "SectionHeader", "Heading"] },
-    { "need": "Body text, captions, code, keys", "use": ["Text", "Code", "Kbd", "Blockquote"] },
-    { "need": "A number with a caption", "use": ["Stat", "KpiCard"], "notes": "`KpiCard` is the dashboard tile with tone and hint." },
-    { "need": "A table of records", "use": ["DataTableView", "DataTable", "Table"], "notes": "`DataTableView` is config-driven (columns + data, owns search/sort/pagination); `DataTable` the composable parts; `Table` the bare semantic table." },
-    { "need": "Label / value pairs", "use": ["MetadataGrid"] },
-    { "need": "A status word or count", "use": ["StatusBadge", "Badge", "StatusPill", "StatusDot"], "notes": "`StatusBadge` for statuses (use `defineStatusMap`), `Badge` for counts and neutral labels, `StatusDot` for a dot alone." },
-    { "need": "A person or a file", "use": ["Avatar", "FileTypeBadge", "FileChip", "AttachmentChip"] },
-    { "need": "An activity feed or notifications", "use": ["ActivityList", "NotificationPanel"] },
-    { "need": "A chart", "use": ["AreaChart", "DonutChart", "StackedBarChart", "RankedBars"] },
-    { "need": "Preview a document", "use": ["PdfPreview", "SpreadsheetPreview"] },
-    { "need": "An icon", "use": ["Icons"], "notes": "From the catalogue only, never an inline `<svg>`; brand marks from the brand icon family or `Logo`." },
-    { "need": "The application frame", "use": ["Shell", "Sidebar", "AppHeader"], "notes": "`DesignSystemProvider` (or `/next`'s `NextDesignSystemProvider`) once in the root layout; `BrandScope` sets the product theme of a subtree." },
-    { "need": "Configure strings, locale, links or the portal container", "use": ["DesignSystemProvider"], "notes": "Once, in the root layout. `useDsMessages` reads the resolved strings." },
-    { "need": "Theme one subtree (scheme, brand, density) including its overlays", "use": ["ThemeScope", "BrandScope"], "notes": "`ThemeScope` re-stamps portalled overlays; `BrandScope` is product brand only." },
-    { "need": "Hide text visually but keep it for screen readers", "use": ["VisuallyHidden"] },
-    { "need": "Merge class names", "use": ["cn"], "notes": "Consumer classes win over component classes by cascade; `cn` only dedupes." }
+    {
+      "need": "Trigger an action",
+      "use": [
+        "Button",
+        "IconButton"
+      ],
+      "notes": "`IconButton` when the control is only an icon (it requires an accessible name and shows a tooltip). Same `variant` × `intent` × `size` axes."
+    },
+    {
+      "need": "Navigate somewhere with a button look",
+      "use": [
+        "LinkButton"
+      ],
+      "notes": "Renders an `<a href>`; `Button asChild` around your router's `Link` is the alternative."
+    },
+    {
+      "need": "Submit a form",
+      "use": [
+        "SubmitButton"
+      ],
+      "notes": "Full-width by default; `type=\"submit\"` and pending state handled."
+    },
+    {
+      "need": "Make something that is not a button clickable",
+      "use": [
+        "Pressable"
+      ],
+      "notes": "Keyboard, focus ring, disabled handling, no button chrome. Never `<div onClick>`."
+    },
+    {
+      "need": "Confirm a destructive action",
+      "use": [
+        "ConfirmActionButton",
+        "ConfirmDialog",
+        "ConfirmHost"
+      ],
+      "notes": "`ConfirmActionButton` wraps the dialog around any trigger; `ConfirmDialog` when you control `open` or need a form field in the body; `useConfirm()` / `usePrompt()` to `await` an answer from an event handler (needs `DesignSystemProvider confirm` or a `ConfirmHost`)."
+    },
+    {
+      "need": "Act on selected rows",
+      "use": [
+        "BulkActionBar"
+      ],
+      "notes": "Floating bar with the count and the row actions."
+    },
+    {
+      "need": "Keep Save / Cancel visible at the bottom of a long form",
+      "use": [
+        "StickyActionBar"
+      ]
+    },
+    {
+      "need": "Label + help + error around any control",
+      "use": [
+        "Field"
+      ],
+      "notes": "`Label`, `FieldDescription`, `FieldError` inside; controls bind automatically. `Fieldset` groups several. `FieldControl` wires a non-DS control."
+    },
+    {
+      "need": "Free text, one line",
+      "use": [
+        "Input"
+      ],
+      "notes": "`SearchInput` for search boxes, `NumberInput` for numbers, `PhoneField` for phone numbers, `OTPInput` for codes."
+    },
+    {
+      "need": "A phone number",
+      "use": [
+        "PhoneField"
+      ],
+      "notes": "Country picker + national number, E.164 value. `PhoneInput` and `PhoneCountryInput` are deprecated."
+    },
+    {
+      "need": "Free text, several lines",
+      "use": [
+        "Textarea"
+      ]
+    },
+    {
+      "need": "A number with formatting or steppers",
+      "use": [
+        "NumberInput"
+      ]
+    },
+    {
+      "need": "A date, or a date range",
+      "use": [
+        "DatePicker",
+        "DateRangePicker"
+      ],
+      "notes": "`Calendar` alone when the picker should be inline rather than in a popover."
+    },
+    {
+      "need": "Upload files",
+      "use": [
+        "FileUpload"
+      ],
+      "notes": "`DocumentRequestUpload` for the client-portal request flow."
+    },
+    {
+      "need": "Yes / no",
+      "use": [
+        "Checkbox",
+        "Switch"
+      ],
+      "notes": "`Switch` when the change applies immediately, `Checkbox` when it is submitted with the form or is one of several."
+    },
+    {
+      "need": "One of a few visible options",
+      "use": [
+        "RadioGroup",
+        "ToggleGroup"
+      ],
+      "notes": "`RadioGroup` in forms; `ToggleGroup` for view/mode switches with immediate effect."
+    },
+    {
+      "need": "One of many options in a dropdown",
+      "use": [
+        "Select",
+        "Combobox"
+      ],
+      "notes": "`Select` for short static lists; `Combobox` when the user should type to filter or the list is large or async."
+    },
+    {
+      "need": "Several of many options",
+      "use": [
+        "MultiSelect",
+        "MultiSelectField"
+      ],
+      "notes": "`MultiSelect` is the searchable dropdown; `MultiSelectField` a visible pill toggle row for a handful of options."
+    },
+    {
+      "need": "Pick a client or a team member",
+      "use": [
+        "ClientSelect",
+        "TeamMemberSelect"
+      ]
+    },
+    {
+      "need": "Filter a list",
+      "use": [
+        "Toolbar",
+        "MultiFilterPill",
+        "DisplayMenu"
+      ],
+      "notes": "`FilterChip` inside `Toolbar` for one-value filters, `MultiFilterPill` for multi-value, `DisplayMenu` for the Linear-style filter/group/sort/columns menu."
+    },
+    {
+      "need": "Removable or toggleable tokens (tags, applied filters)",
+      "use": [
+        "Chip"
+      ],
+      "notes": "`DismissibleChip` is the older single-purpose removable chip."
+    },
+    {
+      "need": "A slider value",
+      "use": [
+        "Slider"
+      ]
+    },
+    {
+      "need": "Show a message inline (success, warning, error, info)",
+      "use": [
+        "Alert"
+      ]
+    },
+    {
+      "need": "Notify after an action",
+      "use": [
+        "ToastProvider"
+      ],
+      "notes": "`useToast()` from inside the provider."
+    },
+    {
+      "need": "Show loading",
+      "use": [
+        "Spinner",
+        "Skeleton",
+        "LoadingRows"
+      ],
+      "notes": "`Spinner` inside a control or small area, `Skeleton` for a shape, `LoadingRows` for list/table rows."
+    },
+    {
+      "need": "Show progress",
+      "use": [
+        "ProgressBar",
+        "ProgressRing",
+        "SegmentedProgress",
+        "Stepper"
+      ],
+      "notes": "`Stepper` when the steps have names; `SuiteProgress` for the suite's segmented percent meter."
+    },
+    {
+      "need": "Nothing to show yet",
+      "use": [
+        "EmptyState",
+        "ComingSoon"
+      ]
+    },
+    {
+      "need": "A modal task or message",
+      "use": [
+        "Dialog",
+        "ResponsiveDialog"
+      ],
+      "notes": "`ResponsiveDialog` becomes a `Sheet` on small screens."
+    },
+    {
+      "need": "A side panel",
+      "use": [
+        "Sheet",
+        "SideDrawer"
+      ],
+      "notes": "`Sheet` is the Radix-based standard; `SideDrawer` is the older API kept for existing call sites."
+    },
+    {
+      "need": "A contextual menu of actions",
+      "use": [
+        "DropdownMenu",
+        "ContextMenu",
+        "NewMenu"
+      ],
+      "notes": "`ContextMenu` on right-click; `NewMenu` is the ready-made \"+ New\" creation menu."
+    },
+    {
+      "need": "Extra content on hover or click",
+      "use": [
+        "Tooltip",
+        "Popover",
+        "HoverCard"
+      ],
+      "notes": "`Tooltip` for a short label, `Popover` for interactive content, `HoverCard` for a rich preview on hover."
+    },
+    {
+      "need": "A global command / search box",
+      "use": [
+        "CommandPalette",
+        "KeyboardShortcutsDialog"
+      ]
+    },
+    {
+      "need": "Switch between views",
+      "use": [
+        "Tabs",
+        "ChannelTabs",
+        "BottomNav"
+      ],
+      "notes": "`BottomNav` is the mobile tab bar."
+    },
+    {
+      "need": "Where am I",
+      "use": [
+        "Breadcrumb",
+        "PageHeader",
+        "AppHeader"
+      ]
+    },
+    {
+      "need": "Page through results",
+      "use": [
+        "Pagination"
+      ],
+      "notes": "`DataTablePagination` is the same pager with the table's 25-row default; `pageSizeOptions` adds a rows-per-page picker."
+    },
+    {
+      "need": "A tree or a rail of items",
+      "use": [
+        "FolderTree",
+        "ClientRailItem"
+      ]
+    },
+    {
+      "need": "Space things out",
+      "use": [
+        "Stack",
+        "Inline"
+      ],
+      "notes": "Tokenised gap and alignment; never ad-hoc `flex gap-*` in product code."
+    },
+    {
+      "need": "A bordered box or card",
+      "use": [
+        "Surface",
+        "Card"
+      ],
+      "notes": "`Card` adds header/title/description/footer parts and an interactive variant."
+    },
+    {
+      "need": "A divider",
+      "use": [
+        "Separator",
+        "CategoryDivider"
+      ]
+    },
+    {
+      "need": "Collapse content",
+      "use": [
+        "Collapsible",
+        "Accordion"
+      ]
+    },
+    {
+      "need": "Scroll a region",
+      "use": [
+        "ScrollArea"
+      ]
+    },
+    {
+      "need": "Title a page or a section",
+      "use": [
+        "PageHeader",
+        "SectionHeader",
+        "Heading"
+      ]
+    },
+    {
+      "need": "Body text, captions, code, keys",
+      "use": [
+        "Text",
+        "Code",
+        "Kbd",
+        "Blockquote"
+      ]
+    },
+    {
+      "need": "A number with a caption",
+      "use": [
+        "Stat",
+        "KpiCard"
+      ],
+      "notes": "`KpiCard` is the dashboard tile with tone and hint."
+    },
+    {
+      "need": "A table of records",
+      "use": [
+        "DataTableView",
+        "DataTable",
+        "Table"
+      ],
+      "notes": "`DataTableView` is config-driven (columns + data, owns search/sort/pagination); `DataTable` the composable parts; `Table` the bare semantic table."
+    },
+    {
+      "need": "Label / value pairs",
+      "use": [
+        "MetadataGrid"
+      ]
+    },
+    {
+      "need": "A status word or count",
+      "use": [
+        "StatusBadge",
+        "Badge",
+        "StatusPill",
+        "StatusDot"
+      ],
+      "notes": "`StatusBadge` for statuses (use `defineStatusMap`), `Badge` for counts and neutral labels, `StatusDot` for a dot alone."
+    },
+    {
+      "need": "A person or a file",
+      "use": [
+        "Avatar",
+        "FileTypeBadge",
+        "FileChip",
+        "AttachmentChip"
+      ]
+    },
+    {
+      "need": "An activity feed or notifications",
+      "use": [
+        "ActivityList",
+        "NotificationPanel"
+      ]
+    },
+    {
+      "need": "A chart",
+      "use": [
+        "AreaChart",
+        "DonutChart",
+        "StackedBarChart",
+        "RankedBars"
+      ]
+    },
+    {
+      "need": "Preview a document",
+      "use": [
+        "PdfPreview",
+        "SpreadsheetPreview"
+      ]
+    },
+    {
+      "need": "An icon",
+      "use": [
+        "Icons"
+      ],
+      "notes": "From the catalogue only, never an inline `<svg>`; brand marks from the brand icon family or `Logo`."
+    },
+    {
+      "need": "The application frame",
+      "use": [
+        "Shell",
+        "Sidebar",
+        "AppHeader"
+      ],
+      "notes": "`DesignSystemProvider` (or `/next`'s `NextDesignSystemProvider`) once in the root layout; `BrandScope` sets the product theme of a subtree."
+    },
+    {
+      "need": "Configure strings, locale, links or the portal container",
+      "use": [
+        "DesignSystemProvider"
+      ],
+      "notes": "Once, in the root layout. `useDsMessages` reads the resolved strings."
+    },
+    {
+      "need": "Theme one subtree (scheme, brand, density) including its overlays",
+      "use": [
+        "ThemeScope",
+        "BrandScope"
+      ],
+      "notes": "`ThemeScope` re-stamps portalled overlays; `BrandScope` is product brand only."
+    },
+    {
+      "need": "Hide text visually but keep it for screen readers",
+      "use": [
+        "VisuallyHidden"
+      ]
+    },
+    {
+      "need": "Merge class names",
+      "use": [
+        "cn"
+      ],
+      "notes": "Consumer classes win over component classes by cascade; `cn` only dedupes."
+    }
   ],
   "iconFamilies": [
     {
       "name": "Icons",
       "pattern": "Icon$",
       "exclude": "BrandIcon$",
-      "helpers": ["createIcon"],
+      "helpers": [
+        "createIcon"
+      ],
       "description": "The UI glyph catalogue: 24-unit grid, `currentColor` 1.5 strokes, `aria-hidden` unless titled. Import from `@assure-one/design-system/icons` (server-safe) or the root.",
       "useWhen": "Any glyph in a control, a list row, a status, an empty state; `createIcon` to register a one-off glyph in the same contract.",
       "dontUseWhen": "You need a product mark (brand icon family or `Logo`), a state-driven glyph (`StatusIcon`, `PriorityIcon`) or an illustration.",
-      "replacesRawHtml": ["<svg>", "lucide-react"],
+      "replacesRawHtml": [
+        "<svg>",
+        "lucide-react"
+      ],
       "story": "src/primitives/icons.stories.tsx",
       "status": "experimental"
     },
@@ -92,1089 +473,2114 @@
       "description": "Product and third-party marks: the Assure products plus Google and Microsoft. The `BrandIcon` suffix is the contract disclosure that the drawing is a trademark.",
       "useWhen": "A product switcher, a sign-in provider button, a suite tile.",
       "dontUseWhen": "A generic glyph is meant (use the icon catalogue) or the full wordmark is wanted (`Logo`).",
-      "replacesRawHtml": ["<img src=\"…logo.svg\">"],
+      "replacesRawHtml": [
+        "<img src=\"…logo.svg\">"
+      ],
       "story": "src/primitives/logo.stories.tsx"
     }
   ],
   "components": {
     "Button": {
       "category": "actions",
-      "helpers": ["buttonVariants", "resolveButtonStyle"],
+      "helpers": [
+        "buttonVariants",
+        "resolveButtonStyle"
+      ],
       "useWhen": "Any action the user triggers: `variant` (solid, soft, outline, ghost, link) × `intent` (brand, neutral, success, danger) × `size` (xs…xl); `loading`, `iconStart`/`iconEnd`, `asChild` for a router link.",
       "dontUseWhen": "The control is icon-only (`IconButton`), navigates (`LinkButton`), submits a form (`SubmitButton`) or is a clickable non-button surface (`Pressable`).",
-      "replacesRawHtml": ["<button>", "<a role=\"button\">", "<div onClick>", "<input type=\"button\">"],
-      "related": ["IconButton", "LinkButton", "SubmitButton", "Pressable", "PrimaryAction"],
+      "replacesRawHtml": [
+        "<button>",
+        "<a role=\"button\">",
+        "<div onClick>",
+        "<input type=\"button\">"
+      ],
+      "related": [
+        "IconButton",
+        "LinkButton",
+        "SubmitButton",
+        "Pressable",
+        "PrimaryAction"
+      ],
       "since": "0.0.0",
-      "docs": ["docs/adr/007-variant-intent-vocabulary.md"]
+      "docs": [
+        "docs/adr/007-variant-intent-vocabulary.md"
+      ]
     },
     "IconButton": {
       "category": "actions",
-      "helpers": ["iconButtonVariants"],
+      "helpers": [
+        "iconButtonVariants"
+      ],
       "useWhen": "An icon-only action (close, edit, more): square control-scale geometry, a required accessible name, a tooltip by default, the Button family's variants and intents.",
       "dontUseWhen": "The action has a visible text label (`Button` with `iconStart`) or is a menu trigger that shows the chosen value.",
-      "replacesRawHtml": ["<button><svg/></button>"],
-      "related": ["Button", "Tooltip"],
+      "replacesRawHtml": [
+        "<button><svg/></button>"
+      ],
+      "related": [
+        "Button",
+        "Tooltip"
+      ],
       "since": "1.35.0"
     },
     "LinkButton": {
       "category": "actions",
       "useWhen": "Navigation that should look like a button: an `<a href>` with the Button variants, intents, sizes and icon slots.",
       "dontUseWhen": "The action does not change the URL (`Button`) or the link should read as inline text (`Text asChild` around your router link).",
-      "replacesRawHtml": ["<a class=\"btn\">"],
-      "related": ["Button", "LinkAction"],
+      "replacesRawHtml": [
+        "<a class=\"btn\">"
+      ],
+      "related": [
+        "Button",
+        "LinkAction"
+      ],
       "since": "0.0.0"
     },
     "SubmitButton": {
       "category": "actions",
       "useWhen": "The primary submit of a form: `type=\"submit\"`, full width by default (`fullWidth={false}` inline), shows `pendingText` while the form's `useFormStatus` is pending.",
       "dontUseWhen": "The button is not a form submit or you need a secondary action next to the submit (`Button`).",
-      "replacesRawHtml": ["<button type=\"submit\">", "<input type=\"submit\">"],
-      "related": ["Button", "Field"],
+      "replacesRawHtml": [
+        "<button type=\"submit\">",
+        "<input type=\"submit\">"
+      ],
+      "related": [
+        "Button",
+        "Field"
+      ],
       "since": "0.0.0"
     },
     "Pressable": {
       "category": "actions",
       "useWhen": "A clickable region without button chrome: a card, a row, a tile. Renders a `<button>` (or `asChild`) with keyboard activation, focus ring and disabled handling.",
       "dontUseWhen": "A visible button is meant (`Button`) or the region contains its own interactive controls (use `Card variant=\"interactive\"` with an explicit action).",
-      "replacesRawHtml": ["<div onClick>", "<span role=\"button\">", "<li onClick>"],
-      "related": ["Button", "Card"],
+      "replacesRawHtml": [
+        "<div onClick>",
+        "<span role=\"button\">",
+        "<li onClick>"
+      ],
+      "related": [
+        "Button",
+        "Card"
+      ],
       "since": "1.35.0"
     },
     "CopyButton": {
       "category": "actions",
       "useWhen": "Copy a value to the clipboard with check-mark feedback (ids, codes, links).",
       "dontUseWhen": "The copy needs a confirmation toast or copies rich content — compose `IconButton` + `useToast`.",
-      "replacesRawHtml": ["navigator.clipboard.writeText + useState"],
-      "related": ["IconButton", "ToastProvider"],
+      "replacesRawHtml": [
+        "navigator.clipboard.writeText + useState"
+      ],
+      "related": [
+        "IconButton",
+        "ToastProvider"
+      ],
       "since": "0.0.0"
     },
     "ConfirmActionButton": {
       "category": "actions",
       "useWhen": "A destructive or irreversible action that needs a confirmation step: a trigger plus `ConfirmDialog`, retiring `window.confirm()`. `destructive={false}` (alias of `intent=\"brand\"`) for a non-destructive confirm.",
       "dontUseWhen": "The confirmation is imperative (`useConfirm`) or the action is reversible (act, then offer undo in a toast).",
-      "replacesRawHtml": ["window.confirm()", "useState + AlertDialog boilerplate"],
-      "related": ["ConfirmDialog", "AlertDialog", "DangerAction"],
+      "replacesRawHtml": [
+        "window.confirm()",
+        "useState + AlertDialog boilerplate"
+      ],
+      "related": [
+        "ConfirmDialog",
+        "AlertDialog",
+        "DangerAction"
+      ],
       "since": "0.3.0"
     },
     "ConfirmDialog": {
       "category": "overlays",
       "useWhen": "The confirmation pattern (target architecture §34): `title`, `description`, optional body content (a form field the decision depends on), `intent` (`danger` default — focus starts on Cancel; `brand` / `neutral` / `success` render the action through the Button recipe), async `onConfirm` with a built-in pending state, a rejection or a resolved `false` keeps it open and shows the error inline. Labels default to the `confirm` messages namespace.",
       "dontUseWhen": "A one-line confirm around a trigger (`ConfirmActionButton`, which is this pattern with a `trigger`) or an imperative `await` from an event handler (`useConfirm`).",
-      "replacesRawHtml": ["window.confirm()", "useState + AlertDialog + pending flag boilerplate"],
-      "related": ["ConfirmActionButton", "AlertDialog", "ConfirmHost"],
+      "replacesRawHtml": [
+        "window.confirm()",
+        "useState + AlertDialog + pending flag boilerplate"
+      ],
+      "related": [
+        "ConfirmActionButton",
+        "AlertDialog",
+        "ConfirmHost"
+      ],
       "since": "unreleased"
     },
     "ConfirmHost": {
       "category": "overlays",
-      "hooks": ["useConfirm", "usePrompt"],
+      "hooks": [
+        "useConfirm",
+        "usePrompt"
+      ],
       "useWhen": "Imperative confirmation: `const confirm = useConfirm(); if (await confirm({ title, intent: \"danger\" })) …` resolves `true` / `false`; `usePrompt()` resolves the entered string or `null`. Mount one `ConfirmHost` high in the tree (`DesignSystemProvider confirm` does) and every hook below shares its queue; without a host, or on the server, a request resolves as cancelled.",
       "dontUseWhen": "The confirmation is part of the markup (`ConfirmDialog`, `ConfirmActionButton`) or needs a custom body beyond one input (`ConfirmDialog` with children).",
-      "replacesRawHtml": ["window.confirm()", "window.prompt()", "PromptDialog.ask() singletons"],
-      "related": ["ConfirmDialog", "DesignSystemProvider"],
+      "replacesRawHtml": [
+        "window.confirm()",
+        "window.prompt()",
+        "PromptDialog.ask() singletons"
+      ],
+      "related": [
+        "ConfirmDialog",
+        "DesignSystemProvider"
+      ],
       "since": "unreleased",
       "story": "src/patterns/confirm/use-confirm.stories.tsx"
     },
     "PrimaryAction": {
       "category": "actions",
       "label": "Intent actions",
-      "parts": ["SecondaryAction", "DangerAction", "LinkAction", "IconAction"],
+      "parts": [
+        "SecondaryAction",
+        "DangerAction",
+        "LinkAction",
+        "IconAction"
+      ],
       "useWhen": "Intent-named `Button` wrappers for product code that reads by role: primary, secondary, danger, link-styled, icon-only.",
       "dontUseWhen": "You need the full variant × intent matrix or a size outside the defaults (`Button`, `IconButton`).",
-      "related": ["Button", "IconButton", "LinkButton"],
+      "related": [
+        "Button",
+        "IconButton",
+        "LinkButton"
+      ],
       "since": "0.3.0"
     },
     "BulkActionBar": {
       "category": "actions",
-      "parts": ["BulkActionBarAction", "BulkActionBarSeparator"],
+      "parts": [
+        "BulkActionBarAction",
+        "BulkActionBarSeparator"
+      ],
       "useWhen": "A floating bar that appears when rows are selected: selection count, actions, separators, clear.",
       "dontUseWhen": "Actions apply to one record (row menu via `DropdownMenu`) or belong to the page (`PageHeader` actions).",
-      "related": ["DataTable", "StickyActionBar"],
+      "related": [
+        "DataTable",
+        "StickyActionBar"
+      ],
       "since": "0.15.0"
     },
     "StickyActionBar": {
       "category": "actions",
       "useWhen": "Save / Cancel that stays visible at the bottom of a long form or settings page, with an optional hint and mobile-nav offset.",
       "dontUseWhen": "The form fits the viewport (put the `SubmitButton` at the end) or the actions belong to a dialog (`DialogFooter`).",
-      "replacesRawHtml": ["<div class=\"sticky bottom-0\">"],
-      "related": ["SubmitButton", "BulkActionBar"],
+      "replacesRawHtml": [
+        "<div class=\"sticky bottom-0\">"
+      ],
+      "related": [
+        "SubmitButton",
+        "BulkActionBar"
+      ],
       "since": "1.3.0"
     },
     "NewMenu": {
       "category": "actions",
       "useWhen": "The \"+ New\" creation menu of an app: grouped actions with icons and shortcuts on a `DropdownMenu`.",
       "dontUseWhen": "The menu is contextual to one record (`DropdownMenu`) or has a single action (`Button`).",
-      "related": ["DropdownMenu", "AppHeader"],
+      "related": [
+        "DropdownMenu",
+        "AppHeader"
+      ],
       "since": "1.2.0"
     },
     "DisplayMenu": {
       "category": "actions",
       "useWhen": "The Linear-style Display control of a list surface: filters, grouping, ordering and column visibility in one searchable menu, driven by a `sections` array.",
       "dontUseWhen": "There is one filter (`FilterChip`) or one multi-value filter (`MultiFilterPill`).",
-      "related": ["Toolbar", "MultiFilterPill", "DataTableView"],
+      "related": [
+        "Toolbar",
+        "MultiFilterPill",
+        "DataTableView"
+      ],
       "since": "1.25.0"
     },
     "Toolbar": {
       "category": "actions",
-      "parts": ["FilterChip"],
-      "helpers": ["filterChipVariants"],
+      "parts": [
+        "FilterChip"
+      ],
+      "helpers": [
+        "filterChipVariants"
+      ],
       "useWhen": "The row of controls above a list or dashboard; `FilterChip` for a single-value filter toggle inside it. Controls share one control size so the row reads as one line.",
       "dontUseWhen": "The controls belong to a table card (`DataTableToolbar`) or the filter is multi-value (`MultiFilterPill`).",
-      "replacesRawHtml": ["<div class=\"flex items-center gap-2\"> above a list"],
-      "related": ["MultiFilterPill", "DisplayMenu", "DataTable"],
+      "replacesRawHtml": [
+        "<div class=\"flex items-center gap-2\"> above a list"
+      ],
+      "related": [
+        "MultiFilterPill",
+        "DisplayMenu",
+        "DataTable"
+      ],
       "since": "0.3.0"
     },
     "SuggestionPills": {
       "category": "actions",
       "useWhen": "A strip of AI quick-reply pills floated above a composer; renders nothing when empty and not loading, so mount it unconditionally.",
       "dontUseWhen": "The choices are a form value (`MultiSelectField`) or filters (`FilterChip`).",
-      "related": ["MessageComposer", "AiDraftCard"],
+      "related": [
+        "MessageComposer",
+        "AiDraftCard"
+      ],
       "since": "1.5.0"
     },
-
     "Field": {
       "category": "forms",
-      "parts": ["FieldDescription", "FieldError"],
+      "parts": [
+        "FieldDescription",
+        "FieldError"
+      ],
       "useWhen": "Every form control: owns ids, states and ARIA wiring for one control and its `Label`, `FieldDescription` and `FieldError`; design-system controls bind automatically.",
       "dontUseWhen": "Grouping several controls (`Fieldset`) or wiring a control the design system does not ship (`FieldControl`).",
-      "replacesRawHtml": ["<label for> + <input id> + <p id> aria-describedby", "<p class=\"text-red-500\">"],
-      "related": ["Label", "Fieldset", "FieldControl", "useFieldControl"],
+      "replacesRawHtml": [
+        "<label for> + <input id> + <p id> aria-describedby",
+        "<p class=\"text-red-500\">"
+      ],
+      "related": [
+        "Label",
+        "Fieldset",
+        "FieldControl",
+        "useFieldControl"
+      ],
       "since": "unreleased",
-      "docs": ["docs/forms.md", "docs/adr/006-field-native-form-participation.md"]
+      "docs": [
+        "docs/forms.md",
+        "docs/adr/006-field-native-form-participation.md"
+      ]
     },
     "FieldControl": {
       "category": "forms",
       "useWhen": "A control that is not a design-system component (a rich-text editor, a canvas, a plain `<input>`) that must still get the `Field` wiring; a Slot that renders no element of its own.",
       "dontUseWhen": "The control is a design-system component — it already calls `useFieldControl`.",
-      "related": ["Field", "useFieldControl"],
+      "related": [
+        "Field",
+        "useFieldControl"
+      ],
       "since": "unreleased"
     },
     "Fieldset": {
       "category": "forms",
-      "parts": ["FieldsetLegend"],
+      "parts": [
+        "FieldsetLegend"
+      ],
       "useWhen": "Group related controls under one legend (a radio group, a set of checkboxes, a date range, a composite field): native `<fieldset>`/`<legend>`, `disabled` disables all.",
       "dontUseWhen": "There is a single control (`Field`) or the grouping is only visual (`Section`, `Card`).",
-      "replacesRawHtml": ["<fieldset>", "<legend>", "<div role=\"group\">"],
-      "related": ["Field", "RadioGroup", "FormSection"],
+      "replacesRawHtml": [
+        "<fieldset>",
+        "<legend>",
+        "<div role=\"group\">"
+      ],
+      "related": [
+        "Field",
+        "RadioGroup",
+        "FormSection"
+      ],
       "since": "unreleased"
     },
     "Label": {
       "category": "forms",
-      "helpers": ["labelVariants"],
+      "helpers": [
+        "labelVariants"
+      ],
       "useWhen": "The visible name of a control, inside a `Field` (binds automatically) or with an explicit `htmlFor`.",
       "dontUseWhen": "The text is not a control's name (`Text`) or a heading (`Heading`).",
-      "replacesRawHtml": ["<label>"],
-      "related": ["Field", "Input"],
+      "replacesRawHtml": [
+        "<label>"
+      ],
+      "related": [
+        "Field",
+        "Input"
+      ],
       "since": "0.0.0"
     },
+    "InfoHint": {
+      "category": "data display",
+      "useWhen": "The \u24d8 beside a label or a figure (W7-15): `label` names what the hint is about, `children` is the explanation, `presentation=\"tooltip\"` (default) or `\"popover\"` for an explanation with a paragraph or a link. The trigger is a real `IconButton`, so the hint is reachable by keyboard and by touch.",
+      "dontUseWhen": "The text belongs in the layout (`FieldDescription` under a field) or the surface is a rich hover preview (`HoverCard`).",
+      "replacesRawHtml": ["<svg title>", "<span title>"],
+      "related": ["Tooltip", "Popover", "IconButton", "FieldDescription"],
+      "since": "unreleased"
+    },
+    "PeoplePicker": {
+      "category": "selection",
+      "useWhen": "Pick a person or people from the firm's roster (W7-10): `people`, single or `multiple`, avatars with an optional second line, an \"assign to me\" shortcut from `currentUserId`, and an `unassignedLabel` row that reports `null`. Search, keyboard, `Field` binding and form submission come from `Combobox`.",
+      "dontUseWhen": "The options are not people (`Combobox`, `MultiSelect`), or a plain roster select with no roster affordances is enough (`Select`). `TeamMemberSelect` is the predecessor it replaces.",
+      "replacesRawHtml": ["hand-rolled assignee popover with checkboxes"],
+      "related": ["Combobox", "MultiSelect", "Avatar", "TeamMemberSelect"],
+      "since": "unreleased"
+    },
+    "SegmentedControl": {
+      "category": "selection",
+      "useWhen": "One of a few mutually exclusive views or scopes, shown side by side (W7-17): `options` with an optional `count` per segment, `size` on the control scale, radio semantics and arrow-key movement from `ToggleGroup`. The active segment cannot be cleared by clicking it again.",
+      "dontUseWhen": "The set is long or open-ended (`Select`, `Combobox`), more than one may be active (`ToggleGroup type=\"multiple\"`), or the segments switch page regions rather than a value (`Tabs`).",
+      "replacesRawHtml": ["pill Tabs used as a filter", "<div> of <button> with a manual active class"],
+      "related": ["ToggleGroup", "Tabs", "Select", "MultiFilterPill"],
+      "since": "unreleased"
+    },
     "Input": {
       "category": "forms",
-      "helpers": ["inputVariants"],
+      "helpers": [
+        "inputVariants"
+      ],
       "useWhen": "Single-line text, email, password, url, tel, file: `size` on the control scale, `variant` default/ghost, invalid state, start/end adornments, `label`/`description`/`error` sugar, `classNames` per part.",
       "dontUseWhen": "Multi-line (`Textarea`), numbers (`NumberInput`), search (`SearchInput`), phone (`PhoneField`), codes (`OTPInput`), dates (`DatePicker`), files with drop zone (`FileUpload`).",
-      "replacesRawHtml": ["<input>", "<input type=\"text\">", "<input type=\"email\">", "<input type=\"password\">"],
-      "related": ["Field", "Textarea", "NumberInput", "SearchInput"],
+      "replacesRawHtml": [
+        "<input>",
+        "<input type=\"text\">",
+        "<input type=\"email\">",
+        "<input type=\"password\">"
+      ],
+      "related": [
+        "Field",
+        "Textarea",
+        "NumberInput",
+        "SearchInput"
+      ],
       "since": "0.0.0",
-      "docs": ["docs/design-system/control-sizes.md"]
+      "docs": [
+        "docs/design-system/control-sizes.md"
+      ]
     },
     "Textarea": {
       "category": "forms",
-      "helpers": ["textareaVariants"],
+      "helpers": [
+        "textareaVariants"
+      ],
       "useWhen": "Multi-line free text with the Input chrome, sizes, invalid state and Field binding.",
       "dontUseWhen": "Rich text (bring your editor inside `FieldControl` or `MessageComposer`) or a single line (`Input`).",
-      "replacesRawHtml": ["<textarea>"],
-      "related": ["Input", "Field", "MessageComposer"],
+      "replacesRawHtml": [
+        "<textarea>"
+      ],
+      "related": [
+        "Input",
+        "Field",
+        "MessageComposer"
+      ],
       "since": "0.0.0"
     },
     "NumberInput": {
       "category": "forms",
       "useWhen": "A `number | null` value with locale formatting, min/max/step, optional stepper buttons and a text fallback while typing.",
       "dontUseWhen": "Money entered as text with a mask (`Input` + your formatter) or a bounded visual value (`Slider`).",
-      "replacesRawHtml": ["<input type=\"number\">"],
-      "related": ["Input", "Slider"],
+      "replacesRawHtml": [
+        "<input type=\"number\">"
+      ],
+      "related": [
+        "Input",
+        "Slider"
+      ],
       "since": "unreleased"
     },
     "SearchInput": {
       "category": "forms",
-      "helpers": ["searchInputVariants"],
+      "helpers": [
+        "searchInputVariants"
+      ],
       "useWhen": "A search box: search icon, clear affordance, `size`, debounced `onValueChange`.",
       "dontUseWhen": "The search filters a dropdown's options (`Combobox`) or the whole app (`CommandPalette`).",
-      "replacesRawHtml": ["<input type=\"search\">"],
-      "related": ["Input", "Combobox", "DataTable"],
+      "replacesRawHtml": [
+        "<input type=\"search\">"
+      ],
+      "related": [
+        "Input",
+        "Combobox",
+        "DataTable"
+      ],
       "since": "0.0.0"
     },
     "OTPInput": {
       "category": "forms",
       "useWhen": "A one-time code split into cells: paste handling, auto-advance, one hidden form value, named by the surrounding `Label`.",
       "dontUseWhen": "A plain numeric field (`NumberInput`) or a password (`Input type=\"password\"`).",
-      "replacesRawHtml": ["six <input maxlength=\"1\">"],
-      "related": ["Input", "Field"],
+      "replacesRawHtml": [
+        "six <input maxlength=\"1\">"
+      ],
+      "related": [
+        "Input",
+        "Field"
+      ],
       "since": "0.0.0"
     },
     "PhoneField": {
       "category": "forms",
-      "helpers": ["DEFAULT_PHONE_FIELD_MESSAGES"],
+      "helpers": [
+        "DEFAULT_PHONE_FIELD_MESSAGES"
+      ],
       "useWhen": "The one phone control: a `Combobox` country picker beside the national-number input on the shared control chrome; E.164 value (`+14155550100` or `null`), `onValueChange(value, { country, nationalNumber })`, lazy-loaded flags, Field binding and native submission; `DEFAULT_PHONE_FIELD_MESSAGES` to localise its strings.",
       "dontUseWhen": "The value is not a phone number (`Input type=\"tel\"` is never right either — an extension or a PIN is an `Input`/`OTPInput`).",
-      "replacesRawHtml": ["<input type=\"tel\">", "<select> of dial codes + <input type=\"tel\">"],
-      "related": ["Combobox", "Field", "PhoneInput", "PhoneCountryInput"],
+      "replacesRawHtml": [
+        "<input type=\"tel\">",
+        "<select> of dial codes + <input type=\"tel\">"
+      ],
+      "related": [
+        "Combobox",
+        "Field",
+        "PhoneInput",
+        "PhoneCountryInput"
+      ],
       "since": "unreleased"
     },
     "PhoneInput": {
       "category": "forms",
       "useWhen": "Only in code that already uses it: US-only phone formatting on the `Input` chrome.",
       "dontUseWhen": "New code — `PhoneField` (deprecated, removed in 3.0).",
-      "related": ["PhoneField", "Input"],
+      "related": [
+        "PhoneField",
+        "Input"
+      ],
       "since": "0.0.0"
     },
     "PhoneCountryInput": {
       "category": "forms",
-      "parts": ["CountrySelect", "CountryFlag"],
+      "parts": [
+        "CountrySelect",
+        "CountryFlag"
+      ],
       "useWhen": "Only in code that already uses it: the pre-PhoneField country `Select` + `tel` input pair; `parsePhoneForEditing` seeds it from a stored E.164 string.",
       "dontUseWhen": "New code — `PhoneField` (its country picker is a `Combobox`; deprecated, removed in 3.0).",
-      "related": ["PhoneField", "COUNTRY_CODES"],
+      "related": [
+        "PhoneField",
+        "COUNTRY_CODES"
+      ],
       "since": "1.1.0"
     },
     "FileUpload": {
       "category": "forms",
       "useWhen": "Pick or drop files: accept/multiple/max size, file list with remove, keyboard-focusable input, Field binding.",
       "dontUseWhen": "The upload belongs to a client document request (`DocumentRequestUpload`) or you only show already-uploaded files (`AttachmentChip`, `FileChip`).",
-      "replacesRawHtml": ["<input type=\"file\">", "drop-zone div with onDrop"],
-      "related": ["DocumentRequestUpload", "AttachmentChip", "FileTypeBadge"],
+      "replacesRawHtml": [
+        "<input type=\"file\">",
+        "drop-zone div with onDrop"
+      ],
+      "related": [
+        "DocumentRequestUpload",
+        "AttachmentChip",
+        "FileTypeBadge"
+      ],
       "since": "0.0.0"
     },
     "DatePicker": {
       "category": "forms",
       "useWhen": "One date (or a year in year mode) typed with a mask or picked from a `Calendar` popover; ISO `YYYY-MM-DD` value, `onValueChange`, deterministic `en-US` display.",
       "dontUseWhen": "A range (`DateRangePicker`) or an always-visible calendar (`Calendar`).",
-      "replacesRawHtml": ["<input type=\"date\">"],
-      "related": ["DateRangePicker", "Calendar", "isoToDisplay"],
+      "replacesRawHtml": [
+        "<input type=\"date\">"
+      ],
+      "related": [
+        "DateRangePicker",
+        "Calendar",
+        "isoToDisplay"
+      ],
       "since": "0.0.0"
     },
     "DateRangePicker": {
       "category": "forms",
       "useWhen": "A from/to pair in one control; posts `${name}_from` / `${name}_to`.",
       "dontUseWhen": "A single date (`DatePicker`) or two independent dates in a form (two `DatePicker`s in a `Fieldset`).",
-      "replacesRawHtml": ["two <input type=\"date\">"],
-      "related": ["DatePicker", "Calendar"],
+      "replacesRawHtml": [
+        "two <input type=\"date\">"
+      ],
+      "related": [
+        "DatePicker",
+        "Calendar"
+      ],
       "since": "0.11.0"
     },
     "Calendar": {
       "category": "forms",
       "useWhen": "An inline month grid (react-day-picker) for choosing a day or range without a popover.",
       "dontUseWhen": "The date belongs in a form field (`DatePicker`, `DateRangePicker`).",
-      "related": ["DatePicker", "DateRangePicker"],
+      "related": [
+        "DatePicker",
+        "DateRangePicker"
+      ],
       "since": "0.0.0"
     },
     "Checkbox": {
       "category": "forms",
       "useWhen": "A boolean or one of several independent choices; `checked` accepts `\"indeterminate\"` for select-all; native form participation.",
       "dontUseWhen": "The change applies immediately as a setting (`Switch`) or the choices are exclusive (`RadioGroup`).",
-      "replacesRawHtml": ["<input type=\"checkbox\">"],
-      "related": ["Switch", "RadioGroup", "DataTable"],
+      "replacesRawHtml": [
+        "<input type=\"checkbox\">"
+      ],
+      "related": [
+        "Switch",
+        "RadioGroup",
+        "DataTable"
+      ],
       "since": "0.0.0"
     },
     "RadioGroup": {
       "category": "forms",
-      "parts": ["RadioGroupItem"],
+      "parts": [
+        "RadioGroupItem"
+      ],
       "useWhen": "Exclusive choice among a few visible options in a form; wrap in `Fieldset` for the legend.",
       "dontUseWhen": "More than about six options (`Select`) or an immediate view switch (`ToggleGroup`).",
-      "replacesRawHtml": ["<input type=\"radio\">"],
-      "related": ["Fieldset", "ToggleGroup", "Select"],
+      "replacesRawHtml": [
+        "<input type=\"radio\">"
+      ],
+      "related": [
+        "Fieldset",
+        "ToggleGroup",
+        "Select"
+      ],
       "since": "0.0.0"
     },
     "Switch": {
       "category": "forms",
       "useWhen": "An on/off setting that takes effect immediately.",
       "dontUseWhen": "The value is submitted with the form (`Checkbox`).",
-      "replacesRawHtml": ["<input type=\"checkbox\" role=\"switch\">"],
-      "related": ["Checkbox"],
+      "replacesRawHtml": [
+        "<input type=\"checkbox\" role=\"switch\">"
+      ],
+      "related": [
+        "Checkbox"
+      ],
       "since": "0.0.0"
     },
     "Slider": {
       "category": "forms",
       "useWhen": "A bounded numeric value chosen by dragging (one or two thumbs).",
       "dontUseWhen": "Exact numbers matter (`NumberInput`).",
-      "replacesRawHtml": ["<input type=\"range\">"],
-      "related": ["NumberInput"],
+      "replacesRawHtml": [
+        "<input type=\"range\">"
+      ],
+      "related": [
+        "NumberInput"
+      ],
       "since": "0.0.0"
     },
     "MultiSelectField": {
       "category": "forms",
       "useWhen": "A visible row of pill buttons that toggle membership in a comma-separated value: a handful of options everyone should see.",
       "dontUseWhen": "Many options or search (`MultiSelect`), or the pills are filters rather than a form value (`FilterChip`).",
-      "replacesRawHtml": ["<input type=\"checkbox\"> styled as pills"],
-      "related": ["MultiSelect", "ToggleGroup", "Chip"],
+      "replacesRawHtml": [
+        "<input type=\"checkbox\"> styled as pills"
+      ],
+      "related": [
+        "MultiSelect",
+        "ToggleGroup",
+        "Chip"
+      ],
       "since": "0.0.0"
     },
     "Grid": {
       "category": "forms",
       "useWhen": "A matrix of typed cells (rows × columns of text, number, select, checkbox) edited as one controlled value with an accessible name per cell.",
       "dontUseWhen": "Read-only data (`Table`, `DataTable`) or a single column of fields (`Stack` of `Field`s).",
-      "replacesRawHtml": ["<table> of <input>s"],
-      "related": ["Table", "Questions"],
+      "replacesRawHtml": [
+        "<table> of <input>s"
+      ],
+      "related": [
+        "Table",
+        "Questions"
+      ],
       "since": "1.20.0"
     },
     "Questions": {
       "category": "forms",
       "useWhen": "One questionnaire question card: index, title, description, type, required flag, `chrome` card or plain.",
       "dontUseWhen": "You are laying out the whole questionnaire (`QuestionnairePanel`) or a plain form field (`Field`).",
-      "related": ["QuestionnairePanel", "Field"],
+      "related": [
+        "QuestionnairePanel",
+        "Field"
+      ],
       "since": "1.17.0"
     },
     "QuestionnairePanel": {
       "category": "forms",
       "useWhen": "The questionnaire container of the client portal: `cards` or `navigation` variant with eyebrow and title.",
       "dontUseWhen": "A settings form (`Fieldset` inside `Card`).",
-      "related": ["Questions", "Fieldset"],
+      "related": [
+        "Questions",
+        "Fieldset"
+      ],
       "since": "1.17.0"
     },
     "MessageComposer": {
       "category": "forms",
       "useWhen": "The chat input of a thread: one card chrome, optional quick-reply chips, your editor as `children`, a footer with a built-in Send.",
       "dontUseWhen": "A plain multi-line field (`Textarea`) or an email signature editor (`SignatureEditor`).",
-      "related": ["Textarea", "SuggestionPills", "AiDraftCard", "MessageBubble"],
+      "related": [
+        "Textarea",
+        "SuggestionPills",
+        "AiDraftCard",
+        "MessageBubble"
+      ],
       "since": "0.14.0"
     },
     "SignatureEditor": {
       "category": "forms",
       "useWhen": "The panel chrome for editing a personal email signature: header with Add image, your editor as `children`, Save / Insert footer; drop it in a `Popover` or use standalone.",
       "dontUseWhen": "Capturing a drawn e-signature (`ProposalSignatureBlock`).",
-      "related": ["MessageComposer", "Popover"],
+      "related": [
+        "MessageComposer",
+        "Popover"
+      ],
       "since": "1.5.0"
     },
     "DocumentRequestField": {
       "category": "forms",
       "useWhen": "One row of a document request form: a slot for your document-type select plus description and required toggle.",
       "dontUseWhen": "A generic form field (`Field`).",
-      "related": ["DocumentRequestDetail", "Field", "Select"],
+      "related": [
+        "DocumentRequestDetail",
+        "Field",
+        "Select"
+      ],
       "since": "1.4.0"
     },
     "DocumentRequestUpload": {
       "category": "forms",
       "useWhen": "The client-portal upload for a requested document: drop zone, progress and states tied to the request.",
       "dontUseWhen": "A generic file field (`FileUpload`).",
-      "related": ["FileUpload", "DocumentChecklist", "DocumentRequestDetail"],
+      "related": [
+        "FileUpload",
+        "DocumentChecklist",
+        "DocumentRequestDetail"
+      ],
       "since": "1.20.0"
     },
     "ProposalSignatureBlock": {
       "category": "forms",
       "label": "Proposal signing",
-      "parts": ["ProposalConsentGate", "ProposalPaymentCapture"],
+      "parts": [
+        "ProposalConsentGate",
+        "ProposalPaymentCapture"
+      ],
       "useWhen": "The signing step of a proposal: consent gate, signature capture, payment capture.",
       "dontUseWhen": "An email signature (`SignatureEditor`).",
-      "related": ["AgreementViewer", "ProposalPackageCard"],
+      "related": [
+        "AgreementViewer",
+        "ProposalPackageCard"
+      ],
       "since": "1.12.0"
     },
     "FormSection": {
       "category": "forms",
       "useWhen": "Only in code that already uses it: a titled `<fieldset>` block of a settings form with description and trailing action.",
       "dontUseWhen": "New code — use `Fieldset` + `FieldsetLegend` (deprecated, removed in 3.0).",
-      "related": ["Fieldset", "Field"],
+      "related": [
+        "Fieldset",
+        "Field"
+      ],
       "since": "0.4.1"
     },
     "FormError": {
       "category": "forms",
       "label": "FormError / FormSuccess",
-      "parts": ["FormSuccess"],
+      "parts": [
+        "FormSuccess"
+      ],
       "useWhen": "Only in code that already uses them: the pre-Field inline error and success messages (contract C-FORM-MSG).",
       "dontUseWhen": "New code — `FieldError` and `FieldDescription` inside a `Field`, or a toast for a saved form (deprecated, removed in 3.0).",
-      "related": ["Field", "ToastProvider"],
+      "related": [
+        "Field",
+        "ToastProvider"
+      ],
       "since": "0.0.0"
     },
-
     "Select": {
       "category": "selection",
-      "parts": ["SelectRoot", "SelectTrigger", "SelectValue", "SelectContent", "SelectItem", "SelectGroup", "SelectLabel", "SelectSeparator", "SelectScrollUpButton", "SelectScrollDownButton"],
+      "parts": [
+        "SelectRoot",
+        "SelectTrigger",
+        "SelectValue",
+        "SelectContent",
+        "SelectItem",
+        "SelectGroup",
+        "SelectLabel",
+        "SelectSeparator",
+        "SelectScrollUpButton",
+        "SelectScrollDownButton"
+      ],
       "useWhen": "One of a short static list in a dropdown: the sealed `Select` takes `options`; the `Select*` parts compose custom items. Empty value is a real empty (no sentinel option), `size`, `classNames`, Field binding.",
       "dontUseWhen": "The user should type to filter, the list is long or async (`Combobox`), several values (`MultiSelect`), or a few options that can all be visible (`RadioGroup`, `ToggleGroup`).",
-      "replacesRawHtml": ["<select>", "<option>"],
-      "related": ["Combobox", "MultiSelect", "ClientSelect", "TeamMemberSelect"],
+      "replacesRawHtml": [
+        "<select>",
+        "<option>"
+      ],
+      "related": [
+        "Combobox",
+        "MultiSelect",
+        "ClientSelect",
+        "TeamMemberSelect"
+      ],
       "since": "0.0.0"
     },
     "Combobox": {
       "category": "selection",
-      "helpers": ["DEFAULT_COMBOBOX_MESSAGES"],
+      "helpers": [
+        "DEFAULT_COMBOBOX_MESSAGES"
+      ],
       "useWhen": "A searchable pick: one input, a portalled listbox, the `Option<T>` model (`{ value, label }`), async loading and empty messages, single or `multiple`.",
       "dontUseWhen": "A short static list (`Select`) or free text with suggestions that need not match (`Input` + `Popover`).",
-      "replacesRawHtml": ["<input list> + <datalist>", "<select> with a search box"],
-      "related": ["Select", "MultiSelect", "SearchSelect"],
+      "replacesRawHtml": [
+        "<input list> + <datalist>",
+        "<select> with a search box"
+      ],
+      "related": [
+        "Select",
+        "MultiSelect",
+        "SearchSelect"
+      ],
       "since": "unreleased"
     },
     "MultiSelect": {
       "category": "selection",
       "useWhen": "Several of many options with search: `Combobox` in `multiple` mode with selected chips.",
       "dontUseWhen": "A handful of options that should all be visible (`MultiSelectField`) or one value (`Combobox`, `Select`).",
-      "replacesRawHtml": ["<select multiple>"],
-      "related": ["Combobox", "MultiSelectField", "Chip"],
+      "replacesRawHtml": [
+        "<select multiple>"
+      ],
+      "related": [
+        "Combobox",
+        "MultiSelectField",
+        "Chip"
+      ],
       "since": "unreleased"
     },
     "SearchSelect": {
       "category": "selection",
       "useWhen": "Only in code that already uses it: the pre-Combobox searchable select with `{ id, label }` options (contract C-SEARCHSELECT).",
       "dontUseWhen": "New code — `Combobox` with `Option` (deprecated, removed in 3.0; CM-08 rewrites single-mode call sites).",
-      "related": ["Combobox", "MultiSelect"],
+      "related": [
+        "Combobox",
+        "MultiSelect"
+      ],
       "since": "0.0.0"
     },
     "ClientSelect": {
       "category": "selection",
       "useWhen": "Pick one client: avatar, name and email rows on the `Select` primitive, long names truncated.",
       "dontUseWhen": "Searching thousands of clients (`Combobox` with async options) or any other entity (`Select`).",
-      "related": ["Select", "TeamMemberSelect", "Combobox"],
+      "related": [
+        "Select",
+        "TeamMemberSelect",
+        "Combobox"
+      ],
       "since": "0.0.0"
     },
     "TeamMemberSelect": {
       "category": "selection",
       "useWhen": "Pick an assignee: avatar and name rows on the `Select` primitive, with an unassigned option.",
       "dontUseWhen": "Several assignees (`MultiSelect`) or any other entity (`Select`).",
-      "related": ["Select", "ClientSelect", "DataTableView"],
+      "related": [
+        "Select",
+        "ClientSelect",
+        "DataTableView"
+      ],
       "since": "0.0.0"
     },
     "ToggleGroup": {
       "category": "selection",
-      "parts": ["ToggleGroupItem"],
+      "parts": [
+        "ToggleGroupItem"
+      ],
       "useWhen": "A view or mode switch with immediate effect (list/grid, day/week), single or multiple, roving focus.",
       "dontUseWhen": "The choice is a form value (`RadioGroup`, `MultiSelectField`) or navigation between panels (`Tabs`).",
-      "replacesRawHtml": ["group of <button aria-pressed>"],
-      "related": ["Tabs", "RadioGroup", "DocumentSourceFilter"],
+      "replacesRawHtml": [
+        "group of <button aria-pressed>"
+      ],
+      "related": [
+        "Tabs",
+        "RadioGroup",
+        "DocumentSourceFilter"
+      ],
       "since": "0.0.0"
     },
     "Chip": {
       "category": "selection",
-      "helpers": ["chipVariants", "resolveChipStyle"],
+      "helpers": [
+        "chipVariants",
+        "resolveChipStyle"
+      ],
       "useWhen": "A removable, toggleable or clickable token: applied filters, tags, selected values; `variant` × `intent` × `size`, `onRemove`, `pressed`.",
       "dontUseWhen": "A static label (`Badge`), a status (`StatusBadge`) or a file (`FileChip`, `AttachmentChip`).",
-      "replacesRawHtml": ["<span class=\"rounded-full …\"><button>×</button></span>"],
-      "related": ["DismissibleChip", "Badge", "Toolbar", "MultiSelect"],
+      "replacesRawHtml": [
+        "<span class=\"rounded-full …\"><button>×</button></span>"
+      ],
+      "related": [
+        "DismissibleChip",
+        "Badge",
+        "Toolbar",
+        "MultiSelect"
+      ],
       "since": "1.35.0"
     },
     "DismissibleChip": {
       "category": "selection",
       "useWhen": "Only in code that already uses it: a label with a remove button.",
       "dontUseWhen": "New code — `Chip` with `onRemove` covers it with the shared variants and sizes.",
-      "related": ["Chip"],
+      "related": [
+        "Chip"
+      ],
       "since": "0.4.0"
     },
     "MultiFilterPill": {
       "category": "selection",
       "useWhen": "A toolbar filter with a multi-select dropdown and a count of applied values.",
       "dontUseWhen": "A single-value filter (`FilterChip`) or the full display menu (`DisplayMenu`).",
-      "related": ["Toolbar", "DisplayMenu", "MultiSelect"],
+      "related": [
+        "Toolbar",
+        "DisplayMenu",
+        "MultiSelect"
+      ],
       "since": "0.0.0"
     },
     "DocumentSourceFilter": {
       "category": "selection",
       "useWhen": "Scope a document list to a provenance bucket (all, uploaded, emailed, …) with counts: a `ToggleGroup` that reuses `DocumentSourceTag`'s glyphs.",
       "dontUseWhen": "Any other segmented filter (`ToggleGroup`).",
-      "related": ["ToggleGroup", "DocumentSourceTag", "DocumentDetailPanel"],
+      "related": [
+        "ToggleGroup",
+        "DocumentSourceTag",
+        "DocumentDetailPanel"
+      ],
       "since": "1.12.0"
     },
-
     "Alert": {
       "category": "feedback",
-      "parts": ["AlertTitle", "AlertDescription"],
-      "helpers": ["alertVariants"],
+      "parts": [
+        "AlertTitle",
+        "AlertDescription"
+      ],
+      "helpers": [
+        "alertVariants"
+      ],
       "useWhen": "An inline banner in the page flow: success, warning, danger or info, with title, description and optional action.",
       "dontUseWhen": "Feedback after an action that should disappear (`ToastProvider`), a per-field error (`FieldError`) or a blocking message (`AlertDialog`).",
-      "replacesRawHtml": ["<div role=\"alert\">", "coloured bordered div"],
-      "related": ["ToastProvider", "Field", "AlertDialog"],
+      "replacesRawHtml": [
+        "<div role=\"alert\">",
+        "coloured bordered div"
+      ],
+      "related": [
+        "ToastProvider",
+        "Field",
+        "AlertDialog"
+      ],
       "since": "0.0.0"
     },
     "ToastProvider": {
       "category": "feedback",
-      "hooks": ["useToast"],
+      "hooks": [
+        "useToast"
+      ],
       "useWhen": "Transient notifications after an action: mount `ToastProvider` once, call `useToast()` anywhere below; `/testing` ships `createToastRecorder`.",
       "dontUseWhen": "The message must stay until read (`Alert`) or is tied to a field (`FieldError`).",
-      "replacesRawHtml": ["alert()", "hand-rolled toast portal"],
-      "related": ["Alert", "CopyButton"],
+      "replacesRawHtml": [
+        "alert()",
+        "hand-rolled toast portal"
+      ],
+      "related": [
+        "Alert",
+        "CopyButton"
+      ],
       "since": "0.0.0"
     },
     "Spinner": {
       "category": "feedback",
-      "helpers": ["spinnerVariants", "SPINNER_TONE_TO_INTENT"],
+      "helpers": [
+        "spinnerVariants",
+        "SPINNER_TONE_TO_INTENT"
+      ],
       "useWhen": "Indeterminate activity in a small area or inside a control; inherits `currentColor` unless an `intent` is set.",
       "dontUseWhen": "Loading content with a known shape (`Skeleton`, `LoadingRows`) or a button's own pending state (`Button loading`).",
-      "replacesRawHtml": ["animate-spin svg"],
-      "related": ["Skeleton", "LoadingRows", "ProgressBar"],
+      "replacesRawHtml": [
+        "animate-spin svg"
+      ],
+      "related": [
+        "Skeleton",
+        "LoadingRows",
+        "ProgressBar"
+      ],
       "since": "0.15.0"
     },
     "Skeleton": {
       "category": "feedback",
-      "parts": ["SkeletonText", "SkeletonCircle"],
+      "parts": [
+        "SkeletonText",
+        "SkeletonCircle"
+      ],
       "useWhen": "A placeholder in the shape of the content that is loading: block, text lines, circle.",
       "dontUseWhen": "Rows of a list or table (`LoadingRows`) or an operation with no layout to reserve (`Spinner`).",
-      "replacesRawHtml": ["<div class=\"animate-pulse bg-…\">"],
-      "related": ["LoadingRows", "Spinner"],
+      "replacesRawHtml": [
+        "<div class=\"animate-pulse bg-…\">"
+      ],
+      "related": [
+        "LoadingRows",
+        "Spinner"
+      ],
       "since": "0.0.0"
     },
     "LoadingRows": {
       "category": "feedback",
       "useWhen": "N uniform skeleton rows while a list or table loads.",
       "dontUseWhen": "A single shape (`Skeleton`).",
-      "replacesRawHtml": ["Array.from({ length }).map(<Skeleton/>)"],
-      "related": ["Skeleton", "DataTable"],
+      "replacesRawHtml": [
+        "Array.from({ length }).map(<Skeleton/>)"
+      ],
+      "related": [
+        "Skeleton",
+        "DataTable"
+      ],
       "since": "0.4.1"
     },
     "ProgressBar": {
       "category": "feedback",
-      "helpers": ["progressBarVariants", "PROGRESS_LEGACY_TO_INTENT"],
+      "helpers": [
+        "progressBarVariants",
+        "PROGRESS_LEGACY_TO_INTENT"
+      ],
       "useWhen": "A determinate (or indeterminate) horizontal meter; `intent` sets the colour, otherwise it follows the value.",
       "dontUseWhen": "A compact circular meter (`ProgressRing`), discrete steps (`SegmentedProgress`, `Stepper`) or the suite's percent readout (`SuiteProgress`).",
-      "replacesRawHtml": ["<progress>", "nested div with width:%"],
-      "related": ["ProgressRing", "SegmentedProgress", "SuiteProgress"],
+      "replacesRawHtml": [
+        "<progress>",
+        "nested div with width:%"
+      ],
+      "related": [
+        "ProgressRing",
+        "SegmentedProgress",
+        "SuiteProgress"
+      ],
       "since": "0.0.0"
     },
     "ProgressRing": {
       "category": "feedback",
-      "helpers": ["progressRingVariants"],
+      "helpers": [
+        "progressRingVariants"
+      ],
       "useWhen": "A circular meter for a card or tile, with the same `intent` and value-driven colour rule as `ProgressBar`.",
       "dontUseWhen": "A wide layout (`ProgressBar`) or a donut of several series (`DonutChart`).",
-      "related": ["ProgressBar", "DonutChart"],
+      "related": [
+        "ProgressBar",
+        "DonutChart"
+      ],
       "since": "0.0.0"
     },
     "SegmentedProgress": {
       "category": "feedback",
       "useWhen": "Progress through a known number of steps as filled segments (onboarding, checklists).",
       "dontUseWhen": "The steps have names (`Stepper`) or the value is continuous (`ProgressBar`).",
-      "related": ["Stepper", "ProgressBar", "SuiteProgress"],
+      "related": [
+        "Stepper",
+        "ProgressBar",
+        "SuiteProgress"
+      ],
       "since": "1.2.0"
     },
     "SuiteProgress": {
       "category": "feedback",
-      "helpers": ["suiteProgressFillVariants"],
+      "helpers": [
+        "suiteProgressFillVariants"
+      ],
       "useWhen": "The suite's discrete segmented meter with a percent readout, tinted per product or `intent`.",
       "dontUseWhen": "A generic segmented meter (`SegmentedProgress`) or a continuous one (`ProgressBar`).",
-      "related": ["SegmentedProgress", "ProgressBar"],
+      "related": [
+        "SegmentedProgress",
+        "ProgressBar"
+      ],
       "since": "1.34.0"
     },
     "EmptyState": {
       "category": "feedback",
       "useWhen": "A list or panel has nothing to show: icon, title, description and one action.",
       "dontUseWhen": "The feature does not exist yet (`ComingSoon`) or content is loading (`Skeleton`).",
-      "replacesRawHtml": ["centred div with an icon and grey text"],
-      "related": ["ComingSoon", "LoadingRows"],
+      "replacesRawHtml": [
+        "centred div with an icon and grey text"
+      ],
+      "related": [
+        "ComingSoon",
+        "LoadingRows",
+        "ErrorState"
+      ],
       "since": "0.0.0"
     },
+    "SectionCard": {
+      "category": "layout",
+      "useWhen": "A titled panel: `title`, optional `description`, trailing `actions`, body and optional `footer` — `Card`'s header/body/footer composed once. `flush` for a body that owns its row insets.",
+      "dontUseWhen": "The surface has no heading (`Card`) or it is a whole page header (`PageHeader`).",
+      "replacesRawHtml": [
+        "section with a border, a heading row and a padded body"
+      ],
+      "related": [
+        "Card",
+        "PageHeader",
+        "Surface"
+      ],
+      "since": "1.38.0"
+    },
+    "AvatarGroup": {
+      "category": "data display",
+      "useWhen": "An overlapping stack of `Avatar`s with a `+N` overflow bubble: `max` caps the faces, `total` carries the real count, `size` cascades from Avatar's scale.",
+      "dontUseWhen": "A single person (`Avatar`) or a list that needs names (`DescriptionList`).",
+      "replacesRawHtml": [
+        "flex row of avatars with negative margins and a +N circle"
+      ],
+      "related": [
+        "Avatar",
+        "TeamMemberSelect"
+      ],
+      "since": "1.38.0"
+    },
+    "ErrorState": {
+      "category": "feedback",
+      "useWhen": "A list or panel failed to load: danger icon tile, title, description and a retry button (`onRetry`). `size=\"compact\"` inside a table.",
+      "dontUseWhen": "There is simply nothing to show (`EmptyState`) or the error belongs to a form field (`FieldError`).",
+      "replacesRawHtml": [
+        "centred div with a warning icon and a Try again button"
+      ],
+      "related": [
+        "EmptyState",
+        "TableError"
+      ],
+      "since": "1.38.0"
+    },
     "ComingSoon": {
       "category": "feedback",
       "useWhen": "A placeholder for a feature that is not available yet: icon, title, description and a feature list.",
       "dontUseWhen": "The feature exists but has no data (`EmptyState`).",
-      "related": ["EmptyState"],
+      "related": [
+        "EmptyState"
+      ],
       "since": "0.0.0"
     },
     "AttentionItem": {
       "category": "feedback",
       "useWhen": "One row of an attention queue: icon, title, description, service tone and trailing action.",
       "dontUseWhen": "A notification (`NotificationPanel` items) or an activity event (`ActivityList` items).",
-      "related": ["NotificationPanel", "ActivityList", "KpiCard"],
+      "related": [
+        "NotificationPanel",
+        "ActivityList",
+        "KpiCard"
+      ],
       "since": "1.2.0"
     },
     "MissingDocumentsPanel": {
       "category": "feedback",
       "useWhen": "The firm-side panel listing documents a client has not provided, with a Request action.",
       "dontUseWhen": "The client-side checklist (`DocumentChecklist`).",
-      "related": ["DocumentChecklist", "DocumentRequestDetail"],
+      "related": [
+        "DocumentChecklist",
+        "DocumentRequestDetail"
+      ],
       "since": "1.4.0"
     },
     "AiDraftCard": {
       "category": "feedback",
       "useWhen": "Present an AI-generated draft inside a composer: one `state` prop drives loading, refining, error and ready (collapsible); you pass the body and actions.",
       "dontUseWhen": "A human message (`MessageBubble`) or AI quick replies (`SuggestionPills`).",
-      "related": ["MessageComposer", "SuggestionPills", "AIReceiptPanel"],
+      "related": [
+        "MessageComposer",
+        "SuggestionPills",
+        "AIReceiptPanel"
+      ],
       "since": "1.5.0"
     },
     "AIReceiptPanel": {
       "category": "feedback",
       "useWhen": "The receipt-reading panel: idle, reading and done states with the extracted result and an Attach action.",
       "dontUseWhen": "A generic upload (`FileUpload`) or a draft message (`AiDraftCard`).",
-      "related": ["AiDraftCard", "FileUpload"],
+      "related": [
+        "AiDraftCard",
+        "FileUpload"
+      ],
       "since": "1.2.0"
     },
-
     "Dialog": {
       "category": "overlays",
-      "parts": ["DialogTrigger", "DialogPortal", "DialogOverlay", "DialogContent", "DialogHeader", "DialogTitle", "DialogDescription", "DialogBody", "DialogFooter", "DialogClose"],
+      "parts": [
+        "DialogTrigger",
+        "DialogPortal",
+        "DialogOverlay",
+        "DialogContent",
+        "DialogHeader",
+        "DialogTitle",
+        "DialogDescription",
+        "DialogBody",
+        "DialogFooter",
+        "DialogClose"
+      ],
       "useWhen": "A modal task or message: focus trap, Escape, overlay, `DialogTitle` required for the accessible name; `size` up to `xl` (or the `--ds-dialog-width` variable), `height`, and `DialogBody` as the scrolling region between header and footer.",
       "dontUseWhen": "A confirmation that must be answered (`AlertDialog`), a side panel (`Sheet`), a mobile-friendly modal (`ResponsiveDialog`) or non-modal content (`Popover`).",
-      "replacesRawHtml": ["<dialog>", "fixed inset-0 div"],
-      "related": ["AlertDialog", "Sheet", "ResponsiveDialog", "CommandPalette"],
+      "replacesRawHtml": [
+        "<dialog>",
+        "fixed inset-0 div"
+      ],
+      "related": [
+        "AlertDialog",
+        "Sheet",
+        "ResponsiveDialog",
+        "CommandPalette"
+      ],
       "since": "0.0.0",
-      "docs": ["docs/adr/012-overlay-presence-motion.md"]
+      "docs": [
+        "docs/adr/012-overlay-presence-motion.md"
+      ]
     },
     "AlertDialog": {
       "category": "overlays",
-      "parts": ["AlertDialogTrigger", "AlertDialogPortal", "AlertDialogOverlay", "AlertDialogContent", "AlertDialogHeader", "AlertDialogTitle", "AlertDialogDescription", "AlertDialogFooter", "AlertDialogAction", "AlertDialogCancel"],
+      "parts": [
+        "AlertDialogTrigger",
+        "AlertDialogPortal",
+        "AlertDialogOverlay",
+        "AlertDialogContent",
+        "AlertDialogHeader",
+        "AlertDialogTitle",
+        "AlertDialogDescription",
+        "AlertDialogFooter",
+        "AlertDialogAction",
+        "AlertDialogCancel"
+      ],
       "useWhen": "A decision the user must make before continuing (delete, discard): no outside-click dismiss, explicit Action and Cancel.",
       "dontUseWhen": "A dismissible task (`Dialog`) or a one-line confirm around a trigger (`ConfirmActionButton`).",
-      "replacesRawHtml": ["window.confirm()"],
-      "related": ["Dialog", "ConfirmActionButton"],
+      "replacesRawHtml": [
+        "window.confirm()"
+      ],
+      "related": [
+        "Dialog",
+        "ConfirmActionButton"
+      ],
       "since": "0.0.0"
     },
     "Sheet": {
       "category": "overlays",
-      "parts": ["SheetTrigger", "SheetPortal", "SheetOverlay", "SheetContent", "SheetHeader", "SheetTitle", "SheetDescription", "SheetBody", "SheetFooter", "SheetClose"],
+      "parts": [
+        "SheetTrigger",
+        "SheetPortal",
+        "SheetOverlay",
+        "SheetContent",
+        "SheetHeader",
+        "SheetTitle",
+        "SheetDescription",
+        "SheetBody",
+        "SheetFooter",
+        "SheetClose"
+      ],
       "useWhen": "A panel sliding in from an edge for a secondary task or detail: `side`, sizes, the Dialog accessibility model, `SheetBody` as the scrolling region between header and footer.",
       "dontUseWhen": "Centred content (`Dialog`) or a persistent split view (`MasterDetailLayout`).",
-      "replacesRawHtml": ["fixed right-0 h-full div"],
-      "related": ["SideDrawer", "Dialog", "ResponsiveDialog"],
+      "replacesRawHtml": [
+        "fixed right-0 h-full div"
+      ],
+      "related": [
+        "SideDrawer",
+        "Dialog",
+        "ResponsiveDialog"
+      ],
       "since": "0.0.0"
     },
     "SideDrawer": {
       "category": "overlays",
       "useWhen": "Only in code that already uses it: the earlier slide-in panel API (`open`, `onClose`, `title`, `width`).",
       "dontUseWhen": "New code — `Sheet` has the same behaviour with composable parts.",
-      "related": ["Sheet"],
+      "related": [
+        "Sheet"
+      ],
       "since": "0.0.0"
     },
     "ResponsiveDialog": {
       "category": "overlays",
       "useWhen": "A modal that should be a `Dialog` on desktop and a bottom `Sheet` below the `sm` breakpoint, decided after mount.",
       "dontUseWhen": "The presentation must be fixed (`Dialog`, `Sheet`).",
-      "related": ["Dialog", "Sheet"],
+      "related": [
+        "Dialog",
+        "Sheet"
+      ],
       "since": "1.3.0"
     },
     "Popover": {
       "category": "overlays",
-      "parts": ["PopoverTrigger", "PopoverAnchor", "PopoverPortal", "PopoverContent", "PopoverClose"],
+      "parts": [
+        "PopoverTrigger",
+        "PopoverAnchor",
+        "PopoverPortal",
+        "PopoverContent",
+        "PopoverClose"
+      ],
       "useWhen": "Interactive content anchored to a trigger: a small form, a picker, a filter panel.",
       "dontUseWhen": "A short non-interactive label (`Tooltip`), a preview on hover (`HoverCard`) or a list of actions (`DropdownMenu`).",
-      "replacesRawHtml": ["absolute-positioned div toggled by state"],
-      "related": ["Tooltip", "HoverCard", "DropdownMenu"],
+      "replacesRawHtml": [
+        "absolute-positioned div toggled by state"
+      ],
+      "related": [
+        "Tooltip",
+        "HoverCard",
+        "DropdownMenu"
+      ],
       "since": "0.0.0"
     },
     "HoverCard": {
       "category": "overlays",
-      "parts": ["HoverCardTrigger", "HoverCardPortal", "HoverCardContent"],
+      "parts": [
+        "HoverCardTrigger",
+        "HoverCardPortal",
+        "HoverCardContent"
+      ],
       "useWhen": "A rich preview when hovering a link or name (a person card, a record summary), for sighted pointer users.",
       "dontUseWhen": "The content is essential (it is hover-only) or interactive (`Popover`).",
-      "related": ["Popover", "Tooltip"],
+      "related": [
+        "Popover",
+        "Tooltip"
+      ],
       "since": "0.0.0"
     },
     "Tooltip": {
       "category": "overlays",
-      "parts": ["TooltipProvider", "TooltipTrigger", "TooltipPortal", "TooltipContent"],
+      "parts": [
+        "TooltipProvider",
+        "TooltipTrigger",
+        "TooltipPortal",
+        "TooltipContent"
+      ],
       "useWhen": "A short label for a control on hover and focus; the sealed `Tooltip` takes `content`, the parts compose.",
       "dontUseWhen": "The text is essential to use the control (make it visible) or interactive (`Popover`).",
-      "replacesRawHtml": ["title=\"…\""],
-      "related": ["IconButton", "Popover", "Kbd"],
+      "replacesRawHtml": [
+        "title=\"…\""
+      ],
+      "related": [
+        "IconButton",
+        "Popover",
+        "Kbd"
+      ],
       "since": "0.0.0"
     },
     "DropdownMenu": {
       "category": "overlays",
-      "parts": ["DropdownMenuTrigger", "DropdownMenuPortal", "DropdownMenuContent", "DropdownMenuItem", "DropdownMenuCheckboxItem", "DropdownMenuRadioGroup", "DropdownMenuRadioItem", "DropdownMenuGroup", "DropdownMenuLabel", "DropdownMenuSeparator", "DropdownMenuShortcut", "DropdownMenuSub", "DropdownMenuSubTrigger", "DropdownMenuSubContent"],
+      "parts": [
+        "DropdownMenuTrigger",
+        "DropdownMenuPortal",
+        "DropdownMenuContent",
+        "DropdownMenuItem",
+        "DropdownMenuCheckboxItem",
+        "DropdownMenuRadioGroup",
+        "DropdownMenuRadioItem",
+        "DropdownMenuGroup",
+        "DropdownMenuLabel",
+        "DropdownMenuSeparator",
+        "DropdownMenuShortcut",
+        "DropdownMenuSub",
+        "DropdownMenuSubTrigger",
+        "DropdownMenuSubContent"
+      ],
       "useWhen": "A menu of actions from a button: items, checkbox and radio items, groups, shortcuts, submenus; `/testing` ships `openMenu`.",
       "dontUseWhen": "Choosing a form value (`Select`), right-click (`ContextMenu`) or a form inside (`Popover`).",
-      "replacesRawHtml": ["<ul> shown on click", "<select> used as a menu"],
-      "related": ["ContextMenu", "NewMenu", "Select", "Popover"],
+      "replacesRawHtml": [
+        "<ul> shown on click",
+        "<select> used as a menu"
+      ],
+      "related": [
+        "ContextMenu",
+        "NewMenu",
+        "Select",
+        "Popover"
+      ],
       "since": "0.0.0"
     },
     "ContextMenu": {
       "category": "overlays",
-      "parts": ["ContextMenuTrigger", "ContextMenuPortal", "ContextMenuContent", "ContextMenuItem", "ContextMenuCheckboxItem", "ContextMenuRadioGroup", "ContextMenuRadioItem", "ContextMenuGroup", "ContextMenuLabel", "ContextMenuSeparator", "ContextMenuShortcut", "ContextMenuSub", "ContextMenuSubTrigger", "ContextMenuSubContent"],
+      "parts": [
+        "ContextMenuTrigger",
+        "ContextMenuPortal",
+        "ContextMenuContent",
+        "ContextMenuItem",
+        "ContextMenuCheckboxItem",
+        "ContextMenuRadioGroup",
+        "ContextMenuRadioItem",
+        "ContextMenuGroup",
+        "ContextMenuLabel",
+        "ContextMenuSeparator",
+        "ContextMenuShortcut",
+        "ContextMenuSub",
+        "ContextMenuSubTrigger",
+        "ContextMenuSubContent"
+      ],
       "useWhen": "Actions on right-click or long-press over a region, with the same item model as `DropdownMenu`.",
       "dontUseWhen": "The actions must be discoverable (`DropdownMenu` from a visible trigger).",
-      "replacesRawHtml": ["onContextMenu + positioned div"],
-      "related": ["DropdownMenu"],
+      "replacesRawHtml": [
+        "onContextMenu + positioned div"
+      ],
+      "related": [
+        "DropdownMenu"
+      ],
       "since": "0.0.0"
     },
     "CommandPalette": {
       "category": "overlays",
       "useWhen": "The ⌘K command and search dialog: `cmdk` inside `Dialog`, groups, shortcuts, async results.",
       "dontUseWhen": "Searching one list (`SearchInput`) or picking a form value (`Combobox`).",
-      "related": ["Dialog", "KeyboardShortcutsDialog", "Combobox"],
+      "related": [
+        "Dialog",
+        "KeyboardShortcutsDialog",
+        "Combobox"
+      ],
       "since": "0.0.0"
     },
     "KeyboardShortcutsDialog": {
       "category": "overlays",
       "useWhen": "The \"?\" help dialog listing keyboard shortcuts by section; no props shows the universal General section.",
       "dontUseWhen": "Showing one shortcut next to a control (`Kbd`, `KbdHint`).",
-      "related": ["Kbd", "CommandPalette"],
+      "related": [
+        "Kbd",
+        "CommandPalette"
+      ],
       "since": "0.0.0"
     },
-
     "Tabs": {
       "category": "navigation",
-      "parts": ["TabsList", "TabsTrigger", "TabsContent"],
+      "parts": [
+        "TabsList",
+        "TabsTrigger",
+        "TabsContent"
+      ],
       "useWhen": "Switch between panels of one page; roving focus, `value`/`onValueChange`.",
       "dontUseWhen": "The switch changes a mode rather than showing another panel (`ToggleGroup`), or it is the mobile app-level bar (`BottomNav`).",
-      "replacesRawHtml": ["<ul role=\"tablist\">", "buttons toggling useState panels"],
-      "related": ["ToggleGroup", "ChannelTabs", "BottomNav"],
+      "replacesRawHtml": [
+        "<ul role=\"tablist\">",
+        "buttons toggling useState panels"
+      ],
+      "related": [
+        "ToggleGroup",
+        "ChannelTabs",
+        "BottomNav"
+      ],
       "since": "0.0.0"
     },
     "ChannelTabs": {
       "category": "navigation",
       "useWhen": "Pill tabs switching between communication channels on a thread, each with a toned status dot and unread count; fully controlled.",
       "dontUseWhen": "Generic panels (`Tabs`).",
-      "related": ["Tabs", "StatusDot", "MessageBubble"],
+      "related": [
+        "Tabs",
+        "StatusDot",
+        "MessageBubble"
+      ],
       "since": "1.5.0"
     },
     "Breadcrumb": {
       "category": "navigation",
-      "parts": ["BreadcrumbList", "BreadcrumbItem", "BreadcrumbLink", "BreadcrumbPage", "BreadcrumbSeparator"],
+      "parts": [
+        "BreadcrumbList",
+        "BreadcrumbItem",
+        "BreadcrumbLink",
+        "BreadcrumbPage",
+        "BreadcrumbSeparator"
+      ],
       "useWhen": "The path to the current page; `BreadcrumbPage` marks the current one, `BreadcrumbLink asChild` wraps your router link.",
       "dontUseWhen": "The page title itself (`PageHeader`) or the app-level bar (`AppHeaderBreadcrumb` inside `AppHeader`).",
-      "replacesRawHtml": ["<nav aria-label=\"breadcrumb\"><ol>"],
-      "related": ["PageHeader", "AppHeader"],
+      "replacesRawHtml": [
+        "<nav aria-label=\"breadcrumb\"><ol>"
+      ],
+      "related": [
+        "PageHeader",
+        "AppHeader"
+      ],
       "since": "0.0.0"
     },
     "Pagination": {
       "category": "navigation",
       "useWhen": "Page controls for a paged list: current/total pages, sibling count, optional total items.",
-      "dontUseWhen": "Inside a `DataTable` (`DataTablePagination`) or infinite scroll.",
-      "replacesRawHtml": ["<nav> of page number buttons"],
-      "related": ["DataTable", "DataTableView"],
+      "dontUseWhen": "Infinite scroll. Inside a `DataTable`, `DataTablePagination` is the same component with the table defaults.",
+      "replacesRawHtml": [
+        "<nav> of page number buttons"
+      ],
+      "related": [
+        "DataTable",
+        "DataTableView"
+      ],
       "since": "0.0.0"
     },
     "Stepper": {
       "category": "navigation",
       "useWhen": "Named steps of a multi-step flow, horizontal or vertical, with the current step marked.",
       "dontUseWhen": "Unnamed progress (`SegmentedProgress`) or a timeline of past events (`EngagementTimeline`).",
-      "related": ["SegmentedProgress", "EngagementTimeline"],
+      "related": [
+        "SegmentedProgress",
+        "EngagementTimeline"
+      ],
       "since": "0.0.0"
     },
     "BottomNav": {
       "category": "navigation",
       "useWhen": "The mobile tab bar at the bottom of the app: tabs with icons and badges, controlled `value`.",
       "dontUseWhen": "Desktop navigation (`Sidebar`) or in-page panels (`Tabs`).",
-      "related": ["Sidebar", "Tabs", "StickyActionBar"],
+      "related": [
+        "Sidebar",
+        "Tabs",
+        "StickyActionBar"
+      ],
       "since": "1.2.0"
     },
     "FolderTree": {
       "category": "navigation",
       "useWhen": "A collapsible tree of folders with an active node, default-open ids and selection callback.",
       "dontUseWhen": "A flat list (`ClientRailItem`) or a file list (`DocumentList`).",
-      "related": ["DocumentsWorkspaceLayout", "ClientRailItem", "Collapsible"],
+      "related": [
+        "DocumentsWorkspaceLayout",
+        "ClientRailItem",
+        "Collapsible"
+      ],
       "since": "1.2.0"
     },
     "ClientRailItem": {
       "category": "navigation",
-      "parts": ["ClientRailGroupHeader"],
+      "parts": [
+        "ClientRailGroupHeader"
+      ],
       "useWhen": "One client row in the Documents left rail (avatar, name, counts) plus the section label above a group.",
       "dontUseWhen": "Picking a client in a form (`ClientSelect`) or the main navigation (`SidebarLink`).",
-      "related": ["DocumentsWorkspaceLayout", "ClientSelect", "Sidebar"],
+      "related": [
+        "DocumentsWorkspaceLayout",
+        "ClientSelect",
+        "Sidebar"
+      ],
       "since": "1.4.0"
     },
-
     "Stack": {
       "category": "layout",
       "useWhen": "A vertical (or `direction=\"row\"`) flex container that owns the gap between its children with tokenised `gap` and alignment.",
       "dontUseWhen": "A wrapping horizontal row (`Inline`) or a bordered box (`Surface`).",
-      "replacesRawHtml": ["<div class=\"flex flex-col gap-4\">"],
-      "related": ["Inline", "Surface"],
+      "replacesRawHtml": [
+        "<div class=\"flex flex-col gap-4\">"
+      ],
+      "related": [
+        "Inline",
+        "Surface"
+      ],
       "since": "1.33.0"
     },
     "Inline": {
       "category": "layout",
       "useWhen": "A horizontal wrapping row with children centred on the baseline and a tokenised gap: a row of chips, a button row, meta items.",
       "dontUseWhen": "A column (`Stack`) or a toolbar of controls that must share one control size (`Toolbar`).",
-      "replacesRawHtml": ["<div class=\"flex flex-wrap items-center gap-2\">"],
-      "related": ["Stack", "Toolbar"],
+      "replacesRawHtml": [
+        "<div class=\"flex flex-wrap items-center gap-2\">"
+      ],
+      "related": [
+        "Stack",
+        "Toolbar"
+      ],
       "since": "1.33.0"
     },
     "Surface": {
       "category": "layout",
       "useWhen": "The bordered box content sits on: surface background, 1px rule, radius, `padding` role (none/sm/md/lg).",
       "dontUseWhen": "You need header/title/footer parts or an interactive variant (`Card`).",
-      "replacesRawHtml": ["<div class=\"rounded-xl border bg-white p-4\">"],
-      "related": ["Card", "Stack"],
+      "replacesRawHtml": [
+        "<div class=\"rounded-xl border bg-white p-4\">"
+      ],
+      "related": [
+        "Card",
+        "Stack"
+      ],
       "since": "1.33.0"
     },
     "Card": {
       "category": "layout",
-      "parts": ["CardHeader", "CardTitle", "CardDescription", "CardAction", "CardContent", "CardFooter"],
-      "helpers": ["cardVariants"],
+      "parts": [
+        "CardHeader",
+        "CardTitle",
+        "CardDescription",
+        "CardAction",
+        "CardContent",
+        "CardFooter"
+      ],
+      "helpers": [
+        "cardVariants"
+      ],
       "useWhen": "A surface with structure: header, title, description, trailing action, content, footer; `variant` default, interactive (hover border) or flat (nested).",
       "dontUseWhen": "A plain box without parts (`Surface`), a KPI tile (`KpiCard`) or a domain card that already exists (`EngagementCard`, `DocumentFileRow`).",
-      "replacesRawHtml": ["<div class=\"rounded-xl border shadow\">"],
-      "related": ["Surface", "KpiCard", "Pressable"],
+      "replacesRawHtml": [
+        "<div class=\"rounded-xl border shadow\">"
+      ],
+      "related": [
+        "Surface",
+        "KpiCard",
+        "Pressable"
+      ],
       "since": "0.0.0"
     },
     "Separator": {
       "category": "layout",
       "useWhen": "A horizontal or vertical rule between groups, decorative or semantic.",
       "dontUseWhen": "The divider carries a category label (`CategoryDivider`) or sits inside a menu (`DropdownMenuSeparator`).",
-      "replacesRawHtml": ["<hr>", "<div class=\"border-t\">"],
-      "related": ["CategoryDivider"],
+      "replacesRawHtml": [
+        "<hr>",
+        "<div class=\"border-t\">"
+      ],
+      "related": [
+        "CategoryDivider"
+      ],
       "since": "0.0.0"
     },
     "AspectRatio": {
       "category": "layout",
       "useWhen": "Reserve a fixed ratio box for an image, video or embed.",
       "dontUseWhen": "The media has intrinsic size (plain `<img>` with width/height).",
-      "replacesRawHtml": ["padding-top percentage hack"],
-      "related": ["PdfPreview"],
+      "replacesRawHtml": [
+        "padding-top percentage hack"
+      ],
+      "related": [
+        "PdfPreview"
+      ],
       "since": "0.0.0"
     },
     "ScrollArea": {
       "category": "layout",
-      "parts": ["ScrollBar"],
+      "parts": [
+        "ScrollBar"
+      ],
       "useWhen": "A scrollable region with styled, consistent scrollbars (panels, menus, side rails).",
       "dontUseWhen": "The document scrolls (leave it to the browser).",
-      "replacesRawHtml": ["<div class=\"overflow-auto\">"],
-      "related": ["Sheet", "Sidebar"],
+      "replacesRawHtml": [
+        "<div class=\"overflow-auto\">"
+      ],
+      "related": [
+        "Sheet",
+        "Sidebar"
+      ],
       "since": "0.0.0"
     },
     "Collapsible": {
       "category": "layout",
-      "parts": ["CollapsibleTrigger", "CollapsibleContent"],
+      "parts": [
+        "CollapsibleTrigger",
+        "CollapsibleContent"
+      ],
       "useWhen": "Show/hide one region from a trigger, animated and reduced-motion aware.",
       "dontUseWhen": "Several mutually exclusive sections (`Accordion`).",
-      "replacesRawHtml": ["<details>/<summary>", "useState toggle"],
-      "related": ["Accordion", "FolderTree"],
+      "replacesRawHtml": [
+        "<details>/<summary>",
+        "useState toggle"
+      ],
+      "related": [
+        "Accordion",
+        "FolderTree"
+      ],
       "since": "0.0.0"
     },
     "Accordion": {
       "category": "layout",
-      "parts": ["AccordionItem", "AccordionTrigger", "AccordionContent"],
+      "parts": [
+        "AccordionItem",
+        "AccordionTrigger",
+        "AccordionContent"
+      ],
       "useWhen": "A list of expandable sections, single or multiple open.",
       "dontUseWhen": "One region (`Collapsible`) or navigation between panels (`Tabs`).",
-      "replacesRawHtml": ["stack of <details>"],
-      "related": ["Collapsible", "Tabs"],
+      "replacesRawHtml": [
+        "stack of <details>"
+      ],
+      "related": [
+        "Collapsible",
+        "Tabs"
+      ],
       "since": "0.0.0"
     },
     "Section": {
       "category": "layout",
-      "parts": ["SectionHead"],
+      "parts": [
+        "SectionHead"
+      ],
       "useWhen": "A max-width centred content section with the canonical `--content-pad` gutter and a `SectionHead` title row.",
       "dontUseWhen": "The page already sits in `Content` of the `Shell` and needs a page title (`PageHeader`).",
-      "replacesRawHtml": ["<section class=\"mx-auto max-w-… px-8\">"],
-      "related": ["SectionHeader", "PageHeader", "Shell"],
+      "replacesRawHtml": [
+        "<section class=\"mx-auto max-w-… px-8\">"
+      ],
+      "related": [
+        "SectionHeader",
+        "PageHeader",
+        "Shell"
+      ],
       "since": "0.0.0"
     },
     "SectionHeader": {
       "category": "layout",
       "useWhen": "A title + description block for a marketing-style or settings section.",
       "dontUseWhen": "The top of a page (`PageHeader`) or a form group (`FieldsetLegend`).",
-      "replacesRawHtml": ["<h2> + <p> pair"],
-      "related": ["PageHeader", "Heading", "Section"],
+      "replacesRawHtml": [
+        "<h2> + <p> pair"
+      ],
+      "related": [
+        "PageHeader",
+        "Heading",
+        "Section"
+      ],
       "since": "0.0.0"
     },
     "PageHeader": {
       "category": "layout",
-      "parts": ["PageHeaderSpec", "PageHeaderSep"],
+      "parts": [
+        "PageHeaderSpec",
+        "PageHeaderSep"
+      ],
       "useWhen": "The top-of-page title block: eyebrow, headline with trailing actions, description and a meta row (`PageHeaderSpec` items separated by `PageHeaderSep`).",
       "dontUseWhen": "The sticky app bar (`AppHeader`) or a section inside the page (`SectionHeader`).",
-      "replacesRawHtml": ["<div class=\"flex items-center justify-between\"><h1>"],
-      "related": ["AppHeader", "SectionHeader", "Breadcrumb"],
+      "replacesRawHtml": [
+        "<div class=\"flex items-center justify-between\"><h1>"
+      ],
+      "related": [
+        "AppHeader",
+        "SectionHeader",
+        "Breadcrumb"
+      ],
       "since": "0.3.0"
     },
     "CategoryDivider": {
       "category": "layout",
-      "parts": ["CategoryTag"],
+      "parts": [
+        "CategoryTag"
+      ],
       "useWhen": "Separate a run of items by service line: a tone-tinted category pill, a hairline and an optional count — the one place per-service colour is allowed.",
       "dontUseWhen": "A plain rule (`Separator`) or a status (`StatusBadge`).",
-      "related": ["Separator", "serviceToneStyle"],
+      "related": [
+        "Separator",
+        "serviceToneStyle"
+      ],
       "since": "1.3.0"
     },
     "StickyStack": {
       "category": "layout",
-      "parts": ["StickyStackLayer", "StickyStackSticky", "StickyStackSectionHeader"],
+      "parts": [
+        "StickyStackLayer",
+        "StickyStackSticky",
+        "StickyStackSectionHeader"
+      ],
       "useWhen": "Several fixed layers (app header, toolbar, section headers) that must stack without overlapping: layers are measured and sticky regions consume the offset.",
       "dontUseWhen": "One sticky element (`position: sticky` on it) or a bottom bar (`StickyActionBar`).",
-      "replacesRawHtml": ["hard-coded top-[56px] sticky offsets"],
-      "related": ["AppHeader", "StickyActionBar"],
+      "replacesRawHtml": [
+        "hard-coded top-[56px] sticky offsets"
+      ],
+      "related": [
+        "AppHeader",
+        "StickyActionBar"
+      ],
       "since": "1.30.1"
     },
     "DetailGrid": {
       "category": "layout",
       "label": "Detail layout",
-      "parts": ["DetailSpine", "DetailSpineHeader", "DetailSpineSection", "DetailSpineStats", "DetailMain"],
+      "parts": [
+        "DetailSpine",
+        "DetailSpineHeader",
+        "DetailSpineSection",
+        "DetailSpineStats",
+        "DetailMain"
+      ],
       "useWhen": "A record detail page: a sticky 320px spine (identity, key facts, stats) and a scrolling main column for tabs, sections and feeds.",
       "dontUseWhen": "A list with a selected item beside it (`MasterDetailLayout`) or a plain page (`Section`).",
-      "replacesRawHtml": ["<div class=\"grid grid-cols-[320px_1fr]\">"],
-      "related": ["MasterDetailLayout", "MetadataGrid", "Tabs"],
+      "replacesRawHtml": [
+        "<div class=\"grid grid-cols-[320px_1fr]\">"
+      ],
+      "related": [
+        "MasterDetailLayout",
+        "MetadataGrid",
+        "Tabs"
+      ],
       "since": "0.3.0"
     },
     "MasterDetailLayout": {
       "category": "layout",
       "useWhen": "A list on the left and the selected item's detail on the right, collapsing to one pane on small screens.",
       "dontUseWhen": "A record page with a spine (`DetailGrid`) or the three-pane documents workspace (`DocumentsWorkspaceLayout`).",
-      "related": ["DetailGrid", "DocumentsWorkspaceLayout"],
+      "related": [
+        "DetailGrid",
+        "DocumentsWorkspaceLayout"
+      ],
       "since": "1.3.0"
     },
     "DocumentsWorkspaceLayout": {
       "category": "layout",
       "useWhen": "The three-pane documents workspace: clients rail, folder tree and files area as slots.",
       "dontUseWhen": "Two panes (`MasterDetailLayout`).",
-      "related": ["ClientRailItem", "FolderTree", "DocumentDetailPanel", "MasterDetailLayout"],
+      "related": [
+        "ClientRailItem",
+        "FolderTree",
+        "DocumentDetailPanel",
+        "MasterDetailLayout"
+      ],
       "since": "1.4.0"
     },
     "DashGrid": {
       "category": "layout",
       "useWhen": "A dashboard of reorderable widgets in 2–4 columns with the order persisted under `storageKey`.",
       "dontUseWhen": "A static grid of cards (CSS grid of `Card`s).",
-      "related": ["KpiCard", "Card"],
+      "related": [
+        "KpiCard",
+        "Card"
+      ],
       "since": "1.2.0"
     },
     "RouteTransition": {
       "category": "layout",
       "useWhen": "Fade and slide a page panel in when `routeKey` changes; respects reduced motion.",
       "dontUseWhen": "Animating a component's own presence (the overlays already do) or a list (leave static).",
-      "related": ["Shell"],
+      "related": [
+        "Shell"
+      ],
       "since": "1.3.0"
     },
     "VisuallyHidden": {
       "category": "layout",
       "useWhen": "Text for assistive technology that must not be seen: the name of an icon-only control you compose yourself, a live-region message.",
       "dontUseWhen": "Hiding from everyone (`hidden`) or an `IconButton` (it names itself).",
-      "replacesRawHtml": ["class=\"sr-only\""],
-      "related": ["IconButton"],
+      "replacesRawHtml": [
+        "class=\"sr-only\""
+      ],
+      "related": [
+        "IconButton"
+      ],
       "since": "0.0.0"
     },
-
     "Heading": {
       "category": "typography",
       "useWhen": "A heading: `level` sets the element (h1–h6), `size` the visual role when it differs; h1 once per screen.",
       "dontUseWhen": "A label for a control (`Label`) or emphasised body text (`Text weight`).",
-      "replacesRawHtml": ["<h1>", "<h2>", "<h3>", "<h4>"],
-      "related": ["Text", "PageHeader", "SectionHeader"],
+      "replacesRawHtml": [
+        "<h1>",
+        "<h2>",
+        "<h3>",
+        "<h4>"
+      ],
+      "related": [
+        "Text",
+        "PageHeader",
+        "SectionHeader"
+      ],
       "since": "1.33.0",
-      "docs": ["docs/design-system/typography-roles.md"]
+      "docs": [
+        "docs/design-system/typography-roles.md"
+      ]
     },
     "Text": {
       "category": "typography",
       "useWhen": "Body, caption and label text: `size` is the typography role, `color` the token, `asChild` renders your element (a link, a `<p>`).",
       "dontUseWhen": "A heading (`Heading`), an identifier or snippet (`Code`) or a control's label (`Label`).",
-      "replacesRawHtml": ["<p>", "<span class=\"text-sm text-gray-500\">"],
-      "related": ["Heading", "Code", "Eyebrow"],
+      "replacesRawHtml": [
+        "<p>",
+        "<span class=\"text-sm text-gray-500\">"
+      ],
+      "related": [
+        "Heading",
+        "Code",
+        "Eyebrow"
+      ],
       "since": "1.33.0"
     },
     "Code": {
       "category": "typography",
       "useWhen": "Monospace text: an identifier, a path, a value, a snippet (inline or block); server-safe.",
       "dontUseWhen": "A keyboard key (`Kbd`) or tabular figures in body text (`Numeric`).",
-      "replacesRawHtml": ["<code>", "<pre>"],
-      "related": ["Kbd", "Eyebrow"],
+      "replacesRawHtml": [
+        "<code>",
+        "<pre>"
+      ],
+      "related": [
+        "Kbd",
+        "Eyebrow"
+      ],
       "since": "1.33.0"
     },
     "Kbd": {
       "category": "typography",
       "useWhen": "A keyboard key or shortcut, with platform spelling decided after mount (⌘ vs Ctrl).",
       "dontUseWhen": "A hint next to a control in the intent-atom style (`KbdHint`) or code (`Code`).",
-      "replacesRawHtml": ["<kbd>"],
-      "related": ["Eyebrow", "KeyboardShortcutsDialog"],
+      "replacesRawHtml": [
+        "<kbd>"
+      ],
+      "related": [
+        "Eyebrow",
+        "KeyboardShortcutsDialog"
+      ],
       "since": "1.33.0"
     },
     "Blockquote": {
       "category": "typography",
       "useWhen": "A quoted passage with the design system's rule and spacing.",
       "dontUseWhen": "A callout with an intent (`Alert`).",
-      "replacesRawHtml": ["<blockquote>"],
-      "related": ["Alert", "Text"],
+      "replacesRawHtml": [
+        "<blockquote>"
+      ],
+      "related": [
+        "Alert",
+        "Text"
+      ],
       "since": "0.0.0"
     },
     "Eyebrow": {
       "category": "typography",
       "label": "Intent atoms",
-      "parts": ["MutedSpec", "Numeric", "KbdHint"],
+      "parts": [
+        "MutedSpec",
+        "Numeric",
+        "KbdHint"
+      ],
       "useWhen": "Intent-named text atoms that bake in typography and colour tokens: `Eyebrow` (small caps label), `MutedSpec` (secondary spec text), `Numeric` (tabular figures), `KbdHint` (a key hint).",
       "dontUseWhen": "General body text with a chosen role (`Text`) or a heading (`Heading`).",
-      "related": ["Text", "Kbd", "Stat"],
+      "related": [
+        "Text",
+        "Kbd",
+        "Stat"
+      ],
       "since": "0.3.0"
     },
     "StarRating": {
       "category": "data display",
-      "helpers": ["starRatingVariants"],
+      "helpers": [
+        "starRatingVariants"
+      ],
       "useWhen": "A display-only rating: fractional stars, `max`, sized variants.",
       "dontUseWhen": "Capturing a rating (compose `RadioGroup` or `ToggleGroup` with star icons).",
-      "related": ["Badge", "KpiCard"],
+      "related": [
+        "Badge",
+        "KpiCard"
+      ],
       "since": "0.0.0"
     },
     "Stat": {
       "category": "typography",
       "useWhen": "A large number with a caption in display type.",
       "dontUseWhen": "A dashboard tile with tone, icon and hint (`KpiCard`).",
-      "related": ["KpiCard", "Eyebrow"],
+      "related": [
+        "KpiCard",
+        "Eyebrow"
+      ],
       "since": "0.0.0"
     },
-
     "Table": {
       "category": "data display",
-      "parts": ["TableHeader", "TableBody", "TableFooter", "TableRow", "TableHead", "TableCell", "TableCaption"],
+      "parts": [
+        "TableHeader",
+        "TableBody",
+        "TableFooter",
+        "TableRow",
+        "TableHead",
+        "TableCell",
+        "TableCaption"
+      ],
       "useWhen": "A bare semantic table with the design system's row, header and caption styling.",
       "dontUseWhen": "A records table with toolbar, sorting and pagination (`DataTable`, `DataTableView`) or an editable matrix (`Grid`).",
-      "replacesRawHtml": ["<table>", "<tr>", "<td>", "<th>"],
-      "related": ["DataTable", "DataTableView", "MetadataGrid"],
+      "replacesRawHtml": [
+        "<table>",
+        "<tr>",
+        "<td>",
+        "<th>"
+      ],
+      "related": [
+        "DataTable",
+        "DataTableView",
+        "MetadataGrid"
+      ],
       "since": "0.0.0"
     },
     "DataTable": {
       "category": "data display",
-      "parts": ["DataTableToolbar", "DataTableSearch", "DataTableSpacer", "DataTableResultsCount", "DataTableHead", "DataTableHeader", "DataTableBody", "DataTableRow", "DataTableCell", "DataTableCellName", "DataTableCellMono", "DataTableCellId", "DataTableCellDue", "DataTableCheckbox", "DataTablePagination"],
+      "parts": [
+        "DataTableToolbar",
+        "DataTableSearch",
+        "DataTableSpacer",
+        "DataTableResultsCount",
+        "DataTableHead",
+        "DataTableHeader",
+        "DataTableBody",
+        "DataTableRow",
+        "DataTableCell",
+        "DataTableCellName",
+        "DataTableCellMono",
+        "DataTableCellId",
+        "DataTableCellDue",
+        "DataTableCheckbox",
+        "DataTablePagination"
+      ],
       "useWhen": "The composable records table: card frame, toolbar with search and count, sortable headers, typed cells (name, mono, id, due), row checkbox, pagination.",
       "dontUseWhen": "A config-driven table is enough (`DataTableView`) or the table is a plain semantic one (`Table`).",
-      "replacesRawHtml": ["<table> + hand-rolled toolbar and pager"],
-      "related": ["DataTableView", "Table", "BulkActionBar", "LoadingRows"],
+      "replacesRawHtml": [
+        "<table> + hand-rolled toolbar and pager"
+      ],
+      "related": [
+        "DataTableView",
+        "Table",
+        "BulkActionBar",
+        "LoadingRows",
+        "TableLoading"
+      ],
       "since": "0.3.0"
     },
+    "TableLoading": {
+      "category": "data display",
+      "useWhen": "The `<tbody aria-busy>` of a data table while its rows load: skeleton rows sized to the columns. Slots in place of `DataTableBody`.",
+      "dontUseWhen": "A list outside a table (`LoadingRows`) or a single shape (`Skeleton`).",
+      "replacesRawHtml": [
+        "<tbody> of hand-rolled skeleton <td>s"
+      ],
+      "related": [
+        "TableEmpty",
+        "TableError",
+        "DataTable",
+        "LoadingRows"
+      ],
+      "since": "1.38.0"
+    },
+    "TableEmpty": {
+      "category": "data display",
+      "useWhen": "The `<tbody>` of a data table with no rows: one full-width row holding a compact `EmptyState`.",
+      "dontUseWhen": "An empty panel outside a table (`EmptyState`).",
+      "replacesRawHtml": [
+        "<tr><td colSpan> with centred grey text"
+      ],
+      "related": [
+        "TableLoading",
+        "TableError",
+        "EmptyState",
+        "DataTable"
+      ],
+      "since": "1.38.0"
+    },
+    "TableError": {
+      "category": "data display",
+      "useWhen": "The `<tbody>` of a data table whose rows failed to load: one full-width row holding a compact `ErrorState` with retry.",
+      "dontUseWhen": "An error panel outside a table (`ErrorState`).",
+      "replacesRawHtml": [
+        "<tr><td colSpan> with an error message and a retry button"
+      ],
+      "related": [
+        "TableLoading",
+        "TableEmpty",
+        "ErrorState",
+        "DataTable"
+      ],
+      "since": "1.38.0"
+    },
     "DataTableView": {
       "category": "data display",
-      "parts": ["StagePill", "Assignee", "MoneyCell", "TagsCell", "Dash"],
+      "parts": [
+        "StagePill",
+        "Assignee",
+        "MoneyCell",
+        "TagsCell",
+        "Dash"
+      ],
       "useWhen": "A list screen as configuration: `columns` + `data` (+ filters, search keys, sort); owns search/filter/sort/pagination state. Cell renderers `StagePill`, `Assignee`, `MoneyCell`, `TagsCell`, `Dash` for `column.render`.",
       "dontUseWhen": "You need custom table composition (`DataTable`).",
-      "related": ["DataTable", "DisplayMenu", "Toolbar"],
+      "related": [
+        "DataTable",
+        "DisplayMenu",
+        "Toolbar"
+      ],
       "since": "1.6.0"
     },
     "MetadataGrid": {
       "category": "data display",
-      "parts": ["DataItem"],
+      "parts": [
+        "DataItem"
+      ],
       "useWhen": "Label / value pairs on a detail surface as a semantic `<dl>`; `DataItem span={2}` for full-row values.",
       "dontUseWhen": "Tabular records (`Table`) or a stat tile (`KpiCard`).",
-      "replacesRawHtml": ["<dl>", "two-column label/value divs"],
-      "related": ["DetailGrid", "Table"],
+      "replacesRawHtml": [
+        "<dl>",
+        "two-column label/value divs"
+      ],
+      "related": [
+        "DetailGrid",
+        "Table"
+      ],
       "since": "0.4.1"
     },
     "KpiCard": {
       "category": "data display",
-      "parts": ["SelectableKpiCard"],
+      "parts": [
+        "SelectableKpiCard"
+      ],
       "useWhen": "A single-stat dashboard tile: label, value, optional tone, icon and hint; `SelectableKpiCard` when tiles act as filters.",
       "dontUseWhen": "A number inside running content (`Stat`) or a chart (`DonutChart`).",
-      "related": ["Stat", "DashGrid", "Card"],
+      "related": [
+        "Stat",
+        "DashGrid",
+        "Card"
+      ],
       "since": "0.4.1"
     },
     "Badge": {
       "category": "data display",
-      "helpers": ["badgeVariants", "resolveBadgeAppearance"],
+      "helpers": [
+        "badgeVariants",
+        "resolveBadgeAppearance"
+      ],
       "useWhen": "A short static label or count: `variant` (solid, soft, outline) × `intent`.",
       "dontUseWhen": "A status with a shared vocabulary (`StatusBadge`), a removable token (`Chip`) or a machine-suggested intent (`IntentBadge`).",
-      "replacesRawHtml": ["<span class=\"rounded-full px-2 text-xs\">"],
-      "related": ["StatusBadge", "Chip", "IntentBadge", "StatusDot"],
+      "replacesRawHtml": [
+        "<span class=\"rounded-full px-2 text-xs\">"
+      ],
+      "related": [
+        "StatusBadge",
+        "Chip",
+        "IntentBadge",
+        "StatusDot"
+      ],
       "since": "0.0.0"
     },
     "StatusBadge": {
       "category": "data display",
-      "helpers": ["defineStatusMap"],
+      "helpers": [
+        "defineStatusMap"
+      ],
       "useWhen": "The presentation of a status: soft badge, indicator dot, icon; define the product's statuses once with `defineStatusMap` and spread an entry onto it.",
       "dontUseWhen": "A count or neutral label (`Badge`) or a stage pill inside `DataTableView` (`StagePill`).",
-      "related": ["Badge", "StatusDot", "StatusPill", "DataTableView"],
+      "related": [
+        "Badge",
+        "StatusDot",
+        "StatusPill",
+        "DataTableView"
+      ],
       "since": "1.35.0"
     },
     "StatusPill": {
       "category": "data display",
       "useWhen": "Only in code that already uses it: the fixed-vocabulary pill (`status`, optional dot) for authoritative state.",
       "dontUseWhen": "New code — `StatusBadge` with `defineStatusMap`.",
-      "related": ["StatusBadge", "IntentBadge"],
+      "related": [
+        "StatusBadge",
+        "IntentBadge"
+      ],
       "since": "1.2.0"
     },
     "IntentBadge": {
       "category": "data display",
       "useWhen": "A dashed-outline badge for an AI-classified intent: signals machine-suggested, not yet confirmed.",
       "dontUseWhen": "Authoritative state (`StatusBadge`).",
-      "related": ["StatusBadge", "Badge", "AiDraftCard"],
+      "related": [
+        "StatusBadge",
+        "Badge",
+        "AiDraftCard"
+      ],
       "since": "1.5.0"
     },
     "StatusDot": {
       "category": "data display",
-      "helpers": ["statusDotVariants", "STATUS_DOT_TONE_TO_INTENT"],
+      "helpers": [
+        "statusDotVariants",
+        "STATUS_DOT_TONE_TO_INTENT"
+      ],
       "useWhen": "A standalone attention / unread / presence dot on non-avatar surfaces: nav rails, bells, list rows; `intent` colours it.",
       "dontUseWhen": "Next to an avatar (`Avatar` renders its own presence dot) or with a label (`StatusBadge`).",
-      "replacesRawHtml": ["<span class=\"h-2 w-2 rounded-full bg-red-500\">"],
-      "related": ["StatusBadge", "Avatar", "Sidebar"],
+      "replacesRawHtml": [
+        "<span class=\"h-2 w-2 rounded-full bg-red-500\">"
+      ],
+      "related": [
+        "StatusBadge",
+        "Avatar",
+        "Sidebar"
+      ],
       "since": "1.3.0"
     },
     "StatusIcon": {
       "category": "icons",
       "useWhen": "A progress-aware state circle for pipeline stages (`state`, optional `progress`).",
       "dontUseWhen": "A status with text (`StatusBadge`) or a fixed glyph (icon catalogue).",
-      "related": ["PriorityIcon", "StatusBadge", "ProgressRing"],
+      "related": [
+        "PriorityIcon",
+        "StatusBadge",
+        "ProgressRing"
+      ],
       "since": "0.8.0",
       "story": "src/primitives/priority-status-icons.stories.tsx"
     },
@@ -1182,267 +2588,501 @@
       "category": "icons",
       "useWhen": "The glyph for the fixed none/low/medium/high/urgent priority scale.",
       "dontUseWhen": "A generic arrow or flag (icon catalogue) or a status (`StatusIcon`).",
-      "related": ["StatusIcon", "StackedBarChart"],
+      "related": [
+        "StatusIcon",
+        "StackedBarChart"
+      ],
       "since": "0.8.0",
       "story": "src/primitives/priority-status-icons.stories.tsx"
     },
     "IconTile": {
       "category": "data display",
-      "helpers": ["iconTileVariants", "ICON_TILE_TONE_TO_INTENT"],
+      "helpers": [
+        "iconTileVariants",
+        "ICON_TILE_TONE_TO_INTENT"
+      ],
       "useWhen": "The tinted rounded-square icon chip that leads a list row or card: `intent` tints the square and the glyph.",
       "dontUseWhen": "An action (`IconButton`) or a file type (`FileTypeBadge`).",
-      "replacesRawHtml": ["<div class=\"grid place-items-center rounded-lg bg-…\"><svg/>"],
-      "related": ["FileTypeBadge", "Avatar", "IconButton"],
+      "replacesRawHtml": [
+        "<div class=\"grid place-items-center rounded-lg bg-…\"><svg/>"
+      ],
+      "related": [
+        "FileTypeBadge",
+        "Avatar",
+        "IconButton"
+      ],
       "since": "1.3.0"
     },
     "Avatar": {
       "category": "data display",
       "useWhen": "A person or organisation: image with initials fallback, sizes, optional presence dot.",
       "dontUseWhen": "A file (`FileTypeBadge`) or a product mark (brand icons, `Logo`).",
-      "replacesRawHtml": ["<img class=\"rounded-full\">"],
-      "related": ["StatusDot", "DataTableView", "TeamMemberSelect"],
+      "replacesRawHtml": [
+        "<img class=\"rounded-full\">"
+      ],
+      "related": [
+        "StatusDot",
+        "DataTableView",
+        "TeamMemberSelect"
+      ],
       "since": "0.0.0"
     },
     "FileTypeBadge": {
       "category": "data display",
-      "helpers": ["fileTypeBadgeVariants", "fileTypeFromName"],
+      "helpers": [
+        "fileTypeBadgeVariants",
+        "fileTypeFromName"
+      ],
       "useWhen": "The coloured format square (PDF, IMG, DOC…) for a file; `fileTypeFromName` derives the type.",
       "dontUseWhen": "A whole file row (`AttachmentChip`, `FileChip`, `DocumentFileRow`).",
-      "related": ["AttachmentChip", "FileChip", "IconTile"],
+      "related": [
+        "AttachmentChip",
+        "FileChip",
+        "IconTile"
+      ],
       "since": "1.3.0"
     },
     "FileChip": {
       "category": "data display",
       "useWhen": "A compact file token: name, meta, kind icon, one action.",
       "dontUseWhen": "A full attachment row with view/download (`AttachmentChip`) or a document in the portal (`DocumentFileRow`).",
-      "related": ["AttachmentChip", "FileTypeBadge", "Chip"],
+      "related": [
+        "AttachmentChip",
+        "FileTypeBadge",
+        "Chip"
+      ],
       "since": "1.2.0"
     },
     "AttachmentChip": {
       "category": "data display",
-      "helpers": ["attachmentChipVariants"],
+      "helpers": [
+        "attachmentChipVariants"
+      ],
       "useWhen": "A full attachment row: `FileTypeBadge`, truncated name with meta, trailing view/download and your actions; presentational.",
       "dontUseWhen": "A compact token (`FileChip`) or an upload control (`FileUpload`).",
-      "related": ["FileChip", "FileTypeBadge", "FileUpload"],
+      "related": [
+        "FileChip",
+        "FileTypeBadge",
+        "FileUpload"
+      ],
       "since": "1.3.0"
     },
     "DocumentSourceTag": {
       "category": "data display",
       "useWhen": "Where a document came from (uploaded, emailed, scanned…): glyph + label tag.",
       "dontUseWhen": "Filtering by source (`DocumentSourceFilter`).",
-      "related": ["DocumentSourceFilter", "DocumentDetailPanel"],
+      "related": [
+        "DocumentSourceFilter",
+        "DocumentDetailPanel"
+      ],
       "since": "1.12.0"
     },
     "ActivityList": {
       "category": "data display",
-      "parts": ["ActivityItem", "ActivityEventItem"],
+      "parts": [
+        "ActivityItem",
+        "ActivityEventItem"
+      ],
       "useWhen": "An activity feed: actor/text/target rows (`ActivityItem`) and titled events with a time and coloured dot (`ActivityEventItem`).",
       "dontUseWhen": "Notifications with filters and read state (`NotificationPanel`) or a process timeline (`EngagementTimeline`).",
-      "replacesRawHtml": ["<ul> of hand-styled feed rows"],
-      "related": ["NotificationPanel", "EngagementTimeline", "AttentionItem"],
+      "replacesRawHtml": [
+        "<ul> of hand-styled feed rows"
+      ],
+      "related": [
+        "NotificationPanel",
+        "EngagementTimeline",
+        "AttentionItem"
+      ],
       "since": "0.3.0"
     },
     "NotificationPanel": {
       "category": "data display",
-      "parts": ["NotificationPanelHeader", "NotificationFilter", "NotificationList", "NotificationItem", "NotificationPanelFooter"],
+      "parts": [
+        "NotificationPanelHeader",
+        "NotificationFilter",
+        "NotificationList",
+        "NotificationItem",
+        "NotificationPanelFooter"
+      ],
       "useWhen": "The notifications flyout: header, filter, list of items with read state, footer actions.",
       "dontUseWhen": "A page-level activity feed (`ActivityList`).",
-      "related": ["ActivityList", "StatusDot", "Popover"],
+      "related": [
+        "ActivityList",
+        "StatusDot",
+        "Popover"
+      ],
       "since": "0.7.0"
     },
     "Kanban": {
       "category": "data display",
-      "parts": ["KanbanColumn", "KanbanCard"],
+      "parts": [
+        "KanbanColumn",
+        "KanbanCard"
+      ],
       "useWhen": "A board of columns and cards for stage-based work.",
       "dontUseWhen": "The data is tabular (`DataTableView`).",
-      "related": ["DataTableView"],
+      "related": [
+        "DataTableView"
+      ],
       "since": "0.3.0"
     },
     "EngagementCard": {
       "category": "data display",
       "useWhen": "The client-portal card for one engagement: service, tone, title, progress and next step.",
       "dontUseWhen": "A generic card (`Card`) or a KPI (`KpiCard`).",
-      "related": ["EngagementTimeline", "Card", "serviceToneStyle"],
+      "related": [
+        "EngagementTimeline",
+        "Card",
+        "serviceToneStyle"
+      ],
       "since": "1.2.0"
     },
     "EngagementTimeline": {
       "category": "data display",
-      "parts": ["EngagementTimelineStep"],
+      "parts": [
+        "EngagementTimelineStep"
+      ],
       "useWhen": "The steps of an engagement as a toned vertical timeline.",
       "dontUseWhen": "A flow the user navigates (`Stepper`) or an activity feed (`ActivityList`).",
-      "related": ["EngagementCard", "Stepper", "ActivityList"],
+      "related": [
+        "EngagementCard",
+        "Stepper",
+        "ActivityList"
+      ],
       "since": "1.2.0"
     },
     "MessageBubble": {
       "category": "data display",
-      "parts": ["MessageBubbleAction", "MessageBubbleTombstone"],
+      "parts": [
+        "MessageBubbleAction",
+        "MessageBubbleTombstone"
+      ],
       "useWhen": "One chat message in a thread, inbound or outbound, with hover actions and a tombstone for deleted messages.",
       "dontUseWhen": "An email (`EmailMessageCard`) or an AI draft (`AiDraftCard`).",
-      "related": ["EmailMessageCard", "MessageComposer", "ChannelTabs"],
+      "related": [
+        "EmailMessageCard",
+        "MessageComposer",
+        "ChannelTabs"
+      ],
       "since": "0.12.0"
     },
     "EmailMessageCard": {
       "category": "data display",
       "useWhen": "An email in a thread as an envelope card (header, readable body, footer) with auto-clamp and show-full toggle; you sanitise the HTML.",
       "dontUseWhen": "A chat message (`MessageBubble`).",
-      "related": ["MessageBubble", "AttachmentChip"],
+      "related": [
+        "MessageBubble",
+        "AttachmentChip"
+      ],
       "since": "1.5.0"
     },
     "DocumentChecklist": {
       "category": "data display",
       "useWhen": "The client's view of requested documents by lifecycle: awaiting, in review, received, complete.",
       "dontUseWhen": "The firm's missing-documents view (`MissingDocumentsPanel`).",
-      "related": ["MissingDocumentsPanel", "DocumentRequestUpload"],
+      "related": [
+        "MissingDocumentsPanel",
+        "DocumentRequestUpload"
+      ],
       "since": "1.21.0"
     },
     "DocumentDetailPanel": {
       "category": "data display",
-      "parts": ["DocumentDetailHeader", "DocumentDetailTitle", "DocumentDetailRequester", "DocumentDetailMetaRow", "DocumentDetailBody", "DocumentDetailActions", "DocumentList", "DocumentListSection", "DocumentRow"],
+      "parts": [
+        "DocumentDetailHeader",
+        "DocumentDetailTitle",
+        "DocumentDetailRequester",
+        "DocumentDetailMetaRow",
+        "DocumentDetailBody",
+        "DocumentDetailActions",
+        "DocumentList",
+        "DocumentListSection",
+        "DocumentRow"
+      ],
       "useWhen": "The document detail side panel and the document list it opens from: header, title, requester, meta, body, actions; `DocumentList` sections of `DocumentRow`s.",
       "dontUseWhen": "A file outside the documents workspace (`AttachmentChip`).",
-      "related": ["DocumentsWorkspaceLayout", "DocumentFileRow", "DocumentSourceTag"],
+      "related": [
+        "DocumentsWorkspaceLayout",
+        "DocumentFileRow",
+        "DocumentSourceTag"
+      ],
       "since": "1.8.0"
     },
     "DocumentFileRow": {
       "category": "data display",
-      "parts": ["DocumentFileCard", "DocumentFileLine"],
+      "parts": [
+        "DocumentFileCard",
+        "DocumentFileLine"
+      ],
       "useWhen": "A file in the documents workspace as a row, a card or a selectable line (named checkbox).",
       "dontUseWhen": "An attachment outside the workspace (`AttachmentChip`).",
-      "related": ["DocumentDetailPanel", "FileTypeBadge", "AttachmentChip"],
+      "related": [
+        "DocumentDetailPanel",
+        "FileTypeBadge",
+        "AttachmentChip"
+      ],
       "since": "1.4.0"
     },
     "DocumentRequestDetail": {
       "category": "data display",
-      "parts": ["DocumentRequestCard"],
+      "parts": [
+        "DocumentRequestCard"
+      ],
       "useWhen": "A document request as a card in a list and as the expanded detail.",
       "dontUseWhen": "The request form field (`DocumentRequestField`) or the client's upload (`DocumentRequestUpload`).",
-      "related": ["DocumentRequestField", "DocumentRequestUpload", "MissingDocumentsPanel"],
+      "related": [
+        "DocumentRequestField",
+        "DocumentRequestUpload",
+        "MissingDocumentsPanel"
+      ],
       "since": "1.9.0"
     },
     "TimeLogger": {
       "category": "data display",
-      "parts": ["TimeLoggerHeader", "TimeLoggerTimer", "TimeLoggerContextRow", "TimeLoggerField", "TimeLoggerBillable", "TimeLoggerNotes", "TimeLoggerEntryList", "TimeLoggerEntry", "TimeLoggerActions", "TimeLoggerFooter"],
-      "helpers": ["formatClock", "formatDuration", "parseDuration", "formatCurrency"],
-      "hooks": ["useStopwatch"],
+      "parts": [
+        "TimeLoggerHeader",
+        "TimeLoggerTimer",
+        "TimeLoggerContextRow",
+        "TimeLoggerField",
+        "TimeLoggerBillable",
+        "TimeLoggerNotes",
+        "TimeLoggerEntryList",
+        "TimeLoggerEntry",
+        "TimeLoggerActions",
+        "TimeLoggerFooter"
+      ],
+      "helpers": [
+        "formatClock",
+        "formatDuration",
+        "parseDuration",
+        "formatCurrency"
+      ],
+      "hooks": [
+        "useStopwatch"
+      ],
       "useWhen": "The compact time-entry panel: compose only the rows a surface needs (timer, context, billable, notes, entries); `useStopwatch` and the duration formatters drive it.",
       "dontUseWhen": "A single duration field (`Input` + `parseDuration`).",
-      "related": ["Popover", "NumberInput"],
+      "related": [
+        "Popover",
+        "NumberInput"
+      ],
       "since": "0.15.0"
     },
     "ProposalPackageCard": {
       "category": "data display",
       "label": "Proposal pricing",
-      "parts": ["ProposalServiceRow", "ProposalAddOn", "ProposalBillingTerms", "ProposalPricingSummary"],
+      "parts": [
+        "ProposalServiceRow",
+        "ProposalAddOn",
+        "ProposalBillingTerms",
+        "ProposalPricingSummary"
+      ],
       "useWhen": "The Services & Pricing blocks of a proposal preview: package card, service rows, add-ons, billing terms, summary; inherit the firm accent inside `AgreementViewer`.",
       "dontUseWhen": "Anything outside a proposal (`Card`, `MetadataGrid`).",
-      "related": ["AgreementViewer", "ProposalSignatureBlock", "ProposalSignerList"],
+      "related": [
+        "AgreementViewer",
+        "ProposalSignatureBlock",
+        "ProposalSignerList"
+      ],
       "since": "1.12.0"
     },
     "ProposalSignerList": {
       "category": "data display",
       "label": "Proposal content",
-      "parts": ["ProposalNote", "ProposalCustomPage"],
+      "parts": [
+        "ProposalNote",
+        "ProposalCustomPage"
+      ],
       "useWhen": "The content blocks of a proposal: signer list, notes, custom pages.",
       "dontUseWhen": "Anything outside a proposal.",
-      "related": ["AgreementViewer", "ProposalPackageCard"],
+      "related": [
+        "AgreementViewer",
+        "ProposalPackageCard"
+      ],
       "since": "1.12.0"
     },
-
     "AreaChart": {
       "category": "media",
       "useWhen": "A trend over time as a filled area, in design-system colours.",
       "dontUseWhen": "Parts of a whole (`DonutChart`) or category comparison (`StackedBarChart`, `RankedBars`).",
-      "replacesRawHtml": ["ad-hoc recharts with hex colours"],
-      "related": ["DonutChart", "StackedBarChart", "RankedBars"],
+      "replacesRawHtml": [
+        "ad-hoc recharts with hex colours"
+      ],
+      "related": [
+        "DonutChart",
+        "StackedBarChart",
+        "RankedBars"
+      ],
       "since": "1.2.0"
     },
     "DonutChart": {
       "category": "media",
       "useWhen": "Parts of a whole with a centre label.",
       "dontUseWhen": "One value's progress (`ProgressRing`).",
-      "related": ["ProgressRing", "AreaChart"],
+      "related": [
+        "ProgressRing",
+        "AreaChart"
+      ],
       "since": "1.2.0"
     },
     "StackedBarChart": {
       "category": "media",
       "useWhen": "Composition per category as stacked bars (e.g. work by priority).",
       "dontUseWhen": "A ranked list of values (`RankedBars`).",
-      "related": ["RankedBars", "AreaChart", "PriorityIcon"],
+      "related": [
+        "RankedBars",
+        "AreaChart",
+        "PriorityIcon"
+      ],
       "since": "1.6.0"
     },
     "RankedBars": {
       "category": "media",
       "useWhen": "A ranked list of labelled values as horizontal bars.",
       "dontUseWhen": "Stacked composition (`StackedBarChart`).",
-      "related": ["StackedBarChart"],
+      "related": [
+        "StackedBarChart"
+      ],
       "since": "1.2.0"
     },
     "PdfPreview": {
       "category": "media",
       "useWhen": "Render a PDF inline with paging and zoom.",
       "dontUseWhen": "A spreadsheet (`SpreadsheetPreview`) or just a file row (`AttachmentChip`).",
-      "related": ["SpreadsheetPreview", "AttachmentChip", "AspectRatio"],
+      "related": [
+        "SpreadsheetPreview",
+        "AttachmentChip",
+        "AspectRatio"
+      ],
       "since": "1.7.0"
     },
     "SpreadsheetPreview": {
       "category": "media",
       "useWhen": "Render a spreadsheet's sheets and cells inline.",
       "dontUseWhen": "A PDF (`PdfPreview`) or an editable grid (`Grid`).",
-      "related": ["PdfPreview", "Table"],
+      "related": [
+        "PdfPreview",
+        "Table"
+      ],
       "since": "1.7.0"
     },
     "Logo": {
       "category": "media",
       "useWhen": "The Assure suite or product wordmark: official artwork with a glyph + text fallback; `assetPath` resolves the artwork base.",
       "dontUseWhen": "A small product mark alone (brand icon family).",
-      "replacesRawHtml": ["<img src=\"/brand/….svg\">"],
-      "related": ["Sidebar", "assetPath"],
+      "replacesRawHtml": [
+        "<img src=\"/brand/….svg\">"
+      ],
+      "related": [
+        "Sidebar",
+        "assetPath"
+      ],
       "since": "0.0.0"
     },
-
     "Shell": {
       "category": "shell/screens",
-      "parts": ["Main", "Content"],
+      "parts": [
+        "Main",
+        "Content"
+      ],
       "useWhen": "The application frame: `Shell` holds the `Sidebar` and `Main`; `Main` holds `AppHeader` and `Content`.",
       "dontUseWhen": "A public or marketing page (`Section`).",
-      "replacesRawHtml": ["<div class=\"flex h-screen\">"],
-      "related": ["Sidebar", "AppHeader", "BrandScope"],
+      "replacesRawHtml": [
+        "<div class=\"flex h-screen\">"
+      ],
+      "related": [
+        "Sidebar",
+        "AppHeader",
+        "BrandScope"
+      ],
       "since": "0.3.0"
     },
     "Sidebar": {
       "category": "shell/screens",
-      "parts": ["SidebarProvider", "SidebarTrigger", "SidebarBrand", "SidebarBrandText", "SidebarSection", "SidebarLinkGroup", "SidebarLink", "SidebarLinkLabel", "SidebarLinkBadge", "SidebarLinkAction", "SidebarPinButton", "SidebarUser", "SidebarFooter"],
-      "helpers": ["sidebarLinkBadgeVariants"],
-      "hooks": ["useSidebarState", "useSidebarPeekLock"],
+      "parts": [
+        "SidebarProvider",
+        "SidebarTrigger",
+        "SidebarBrand",
+        "SidebarBrandText",
+        "SidebarSection",
+        "SidebarLinkGroup",
+        "SidebarLink",
+        "SidebarLinkLabel",
+        "SidebarLinkBadge",
+        "SidebarLinkAction",
+        "SidebarPinButton",
+        "SidebarUser",
+        "SidebarFooter"
+      ],
+      "helpers": [
+        "sidebarLinkBadgeVariants"
+      ],
+      "hooks": [
+        "useSidebarState",
+        "useSidebarPeekLock"
+      ],
       "useWhen": "The app navigation rail: expanded/collapsed/peek states from `SidebarProvider`, brand, sections, link groups with badges and actions, user and footer.",
       "dontUseWhen": "Mobile (`BottomNav`) or a rail of records (`ClientRailItem`).",
-      "replacesRawHtml": ["<aside> + <nav> hand-rolled"],
-      "related": ["Shell", "SidebarBrandSwitcher", "BottomNav"],
+      "replacesRawHtml": [
+        "<aside> + <nav> hand-rolled"
+      ],
+      "related": [
+        "Shell",
+        "SidebarBrandSwitcher",
+        "BottomNav",
+        "SidebarDrawer"
+      ],
       "since": "0.3.0"
     },
     "SidebarBrandSwitcher": {
       "category": "shell/screens",
-      "parts": ["SidebarBrandSwitcherTile"],
+      "parts": [
+        "SidebarBrandSwitcherTile"
+      ],
       "useWhen": "Switch between Assure products from the sidebar brand slot: tiles for available, current and coming-soon products.",
       "dontUseWhen": "A single-product app (`SidebarBrand`).",
-      "related": ["Sidebar", "BrandScope", "Logo"],
+      "related": [
+        "Sidebar",
+        "BrandScope",
+        "Logo"
+      ],
       "since": "0.11.2"
     },
     "AppHeader": {
       "category": "shell/screens",
-      "parts": ["AppHeaderBreadcrumb", "AppHeaderTitle", "AppHeaderSearch", "AppHeaderActions"],
+      "parts": [
+        "AppHeaderBreadcrumb",
+        "AppHeaderTitle",
+        "AppHeaderSearch",
+        "AppHeaderActions"
+      ],
       "useWhen": "The sticky 56px top bar inside `Main`: breadcrumb, title, search and actions slots in any order.",
       "dontUseWhen": "The page's own title block (`PageHeader`).",
-      "related": ["Shell", "PageHeader", "NewMenu", "NotificationPanel"],
+      "related": [
+        "Shell",
+        "PageHeader",
+        "NewMenu",
+        "NotificationPanel"
+      ],
       "since": "0.3.0"
     },
     "DesignSystemProvider": {
       "category": "shell/screens",
-      "hooks": ["useDsMessages"],
+      "hooks": [
+        "useDsMessages"
+      ],
       "useWhen": "Mount once in the root layout to configure the whole design system: `messages` overrides for the generic strings components render, `locale` (default `en-US`, pass the one your app knows server-side), `dir`, the portal container, the router `linkComponent` and `imageComponent` for `LinkButton` and `Logo`, the tooltip provider, and opt-in `toasts` / `confirm` regions. `useDsMessages(namespace, override?)` reads the resolved strings inside your own components.",
       "dontUseWhen": "You are on Next.js — `NextDesignSystemProvider` from `/next` fills in the adapters. Theming a subtree is `ThemeScope` / `BrandScope`, not a nested provider.",
-      "replacesRawHtml": ["hand-rolled i18n or router context for design-system strings and links"],
-      "related": ["ThemeScope", "BrandScope", "Tooltip", "LinkButton", "Logo"],
+      "replacesRawHtml": [
+        "hand-rolled i18n or router context for design-system strings and links"
+      ],
+      "related": [
+        "ThemeScope",
+        "BrandScope",
+        "Tooltip",
+        "LinkButton",
+        "Logo"
+      ],
       "since": "unreleased",
       "story": "src/foundation/provider/design-system-provider.stories.tsx"
     },
@@ -1450,93 +3090,237 @@
       "category": "shell/screens",
       "useWhen": "A subtree that renders with its own colour `scheme`, `brand`, `density`, `dir` or runtime brand theme: stamps the `data-ds-*` attributes on its element and registers them so portalled overlays opened from inside (Dialog, Popover, menus) come up in the same theme; nested scopes merge.",
       "dontUseWhen": "The whole app shares one theme (set the attributes on the document root) or only the product brand changes (`BrandScope`).",
-      "replacesRawHtml": ["<div data-ds-scheme=\"dark\"> whose dialogs come up in the root theme"],
-      "related": ["BrandScope", "DesignSystemProvider", "Dialog", "Popover"],
+      "replacesRawHtml": [
+        "<div data-ds-scheme=\"dark\"> whose dialogs come up in the root theme"
+      ],
+      "related": [
+        "BrandScope",
+        "DesignSystemProvider",
+        "Dialog",
+        "Popover"
+      ],
       "since": "unreleased",
       "story": "src/primitives/behavior/portal.stories.tsx",
-      "docs": ["docs/integration/css.md"]
+      "docs": [
+        "docs/integration/css.md"
+      ]
     },
     "BrandScope": {
       "category": "shell/screens",
-      "parts": ["BrandScopeProvider"],
-      "helpers": ["BRAND_PRODUCTS", "brandLabel", "brandScope"],
-      "hooks": ["useBrandScope"],
+      "parts": [
+        "BrandScopeProvider"
+      ],
+      "helpers": [
+        "BRAND_PRODUCTS",
+        "brandLabel",
+        "brandScope"
+      ],
+      "hooks": [
+        "useBrandScope"
+      ],
       "useWhen": "Theme a subtree as a product: stamps `data-brand` and provides it so portalled surfaces re-stamp themselves; `brandScope(product)` for the attribute alone.",
       "dontUseWhen": "Colouring by service line (`serviceToneStyle`) or by status (`intent`).",
-      "related": ["Shell", "SidebarBrandSwitcher"],
+      "related": [
+        "Shell",
+        "SidebarBrandSwitcher"
+      ],
       "since": "1.18.0",
-      "docs": ["docs/integration/css.md"]
+      "docs": [
+        "docs/integration/css.md"
+      ]
     },
     "AgreementViewer": {
       "category": "shell/screens",
-      "parts": ["AgreementPaneHeading"],
+      "parts": [
+        "AgreementPaneHeading"
+      ],
       "useWhen": "The client-facing agreement / proposal viewer: cover, steps, firm accent scope for the proposal blocks.",
       "dontUseWhen": "Previewing a PDF (`PdfPreview`).",
-      "related": ["ProposalPackageCard", "ProposalSignatureBlock", "ProposalSignerList"],
+      "related": [
+        "ProposalPackageCard",
+        "ProposalSignatureBlock",
+        "ProposalSignerList"
+      ],
       "since": "1.12.0"
     },
-
     "cn": {
       "category": "hooks/utilities",
       "useWhen": "Merge class names (clsx + tailwind-merge) when composing `className`; consumer classes still win by cascade, `cn` only dedupes.",
       "dontUseWhen": "Overriding a component part — pass `className`/`classNames` instead of rebuilding its classes.",
-      "related": ["Button"],
+      "related": [
+        "Button"
+      ],
       "since": "0.0.0",
-      "docs": ["docs/integration/css.md"]
+      "docs": [
+        "docs/integration/css.md"
+      ]
+    },
+    "useDataTable": {
+      "category": "hooks/utilities",
+      "label": "Data-table controller",
+      "helpers": [
+        "compareSortValues",
+        "nextSortDirection"
+      ],
+      "useWhen": "Building a data table: owns sorting, pagination, search, selection, column visibility and filters (each controllable or uncontrolled), derives the rows to render, and in `manual` mode only emits state for a server-driven table.",
+      "dontUseWhen": "A static table with no state (the `Table` parts alone), or the data-driven convenience (`DataTableView`) once it is rebuilt on the hook.",
+      "related": [
+        "Table",
+        "DataTable",
+        "DataTableView",
+        "Pagination"
+      ],
+      "since": "unreleased",
+      "docs": [
+        "docs/data-tables.md"
+      ]
     },
     "useFieldControl": {
       "category": "hooks/utilities",
       "useWhen": "Building your own form control that should bind to `Field` like the design-system ones: returns ids, `aria-*`, invalid/disabled/required wiring; explicit props win.",
       "dontUseWhen": "Wrapping an existing element once (`FieldControl`).",
-      "related": ["Field", "FieldControl"],
+      "related": [
+        "Field",
+        "FieldControl"
+      ],
       "since": "1.32.0",
-      "docs": ["docs/adr/006-field-native-form-participation.md"]
+      "docs": [
+        "docs/adr/006-field-native-form-participation.md"
+      ]
     },
     "isoToDisplay": {
       "category": "hooks/utilities",
       "label": "Date utilities",
-      "helpers": ["displayToIso", "applyMask", "applyYearMask", "isoToDate", "dateToIso", "isoToYear", "yearToIso", "DATE_DISPLAY_PLACEHOLDER", "YEAR_DISPLAY_PLACEHOLDER"],
+      "helpers": [
+        "displayToIso",
+        "applyMask",
+        "applyYearMask",
+        "isoToDate",
+        "dateToIso",
+        "isoToYear",
+        "yearToIso",
+        "DATE_DISPLAY_PLACEHOLDER",
+        "YEAR_DISPLAY_PLACEHOLDER"
+      ],
       "useWhen": "Convert between ISO `YYYY-MM-DD`, the `MM/DD/YYYY` display format and JS `Date` the way `DatePicker` does, and apply its typing masks.",
       "dontUseWhen": "Locale-aware formatting for display text (`Intl.DateTimeFormat`).",
-      "related": ["DatePicker", "DateRangePicker"],
+      "related": [
+        "DatePicker",
+        "DateRangePicker"
+      ],
       "since": "0.11.0"
     },
     "COUNTRY_CODES": {
       "category": "hooks/utilities",
       "label": "Country codes",
-      "helpers": ["getFlagEmoji", "parsePhoneForEditing"],
+      "helpers": [
+        "getFlagEmoji",
+        "parsePhoneForEditing"
+      ],
       "useWhen": "The ISO country / dial-code table behind `PhoneCountryInput`, a flag emoji fallback, and splitting a stored phone string for editing.",
       "dontUseWhen": "Full phone validation (bring libphonenumber).",
-      "related": ["PhoneField", "PhoneCountryInput"],
+      "related": [
+        "PhoneField",
+        "PhoneCountryInput"
+      ],
       "since": "1.1.0"
     },
     "serviceToneStyle": {
       "category": "hooks/utilities",
       "label": "Service tones",
-      "helpers": ["SERVICE_TONES", "serviceToneLabel"],
+      "helpers": [
+        "SERVICE_TONES",
+        "serviceToneLabel"
+      ],
       "useWhen": "Tone a portal surface per service line by setting `--tone` / `--tone-bg` once on its root; labels for chips and headings.",
       "dontUseWhen": "Status colour (`intent`) or product theming (`BrandScope`).",
-      "related": ["CategoryDivider", "EngagementCard", "BrandScope"],
+      "related": [
+        "CategoryDivider",
+        "EngagementCard",
+        "BrandScope"
+      ],
       "since": "1.2.0"
     },
     "assetPath": {
       "category": "hooks/utilities",
       "label": "Asset base path",
-      "helpers": ["getAssetBasePath", "setAssetBasePath"],
+      "helpers": [
+        "getAssetBasePath",
+        "setAssetBasePath"
+      ],
       "useWhen": "The app is served from a subpath: call `setAssetBasePath` once so the design system's own artwork (`Logo`) resolves.",
       "dontUseWhen": "Your own assets (use your framework's base path).",
-      "related": ["Logo"],
+      "related": [
+        "Logo"
+      ],
       "since": "1.33.0"
     },
     "systemTokens": {
       "category": "hooks/utilities",
       "label": "Tokens (root re-export)",
-      "helpers": ["reference", "colors", "spacing", "radii", "shadows", "surfaces", "typography"],
+      "helpers": [
+        "reference",
+        "colors",
+        "spacing",
+        "radii",
+        "shadows",
+        "surfaces",
+        "typography"
+      ],
       "useWhen": "Token objects from JavaScript when a utility class cannot reach (inline styles, charts, motion); prefer the `/tokens` entry for a smaller import.",
       "dontUseWhen": "Styling components — use the `--ds-*` custom properties and utilities; never read `reference`/`colors` in component code.",
-      "related": ["BrandScope"],
+      "related": [
+        "BrandScope"
+      ],
       "since": "0.0.0",
-      "docs": ["docs/design-system/shape-roles.md"]
+      "docs": [
+        "docs/design-system/shape-roles.md"
+      ]
+    },
+    "DataTablePattern": {
+      "category": "data display",
+      "label": "DataTable (compound)",
+      "useWhen": "A records table driven by `useDataTable`: the toolbar with a labelled search, filters and a column-visibility menu, the table on the `Table*` parts with sort and selection wired to the controller, bulk actions, the merged pager and the built-in loading / empty / error bodies. `classNames.search` and `--ds-data-table-search-width` size the search field.",
+      "dontUseWhen": "A table with no state (the `Table` parts alone), the hand-written `DataTable*` parts a product already composes, or the config-driven convenience (`DataTableView`).",
+      "replacesRawHtml": [
+        "hand-rolled toolbar + <table> + pager around per-table useState"
+      ],
+      "related": [
+        "useDataTable",
+        "Table",
+        "DataTable",
+        "DataTableView",
+        "Pagination",
+        "BulkActionBar",
+        "TableLoading"
+      ],
+      "since": "unreleased",
+      "docs": [
+        "docs/data-tables.md"
+      ]
+    },
+    "EmptyValue": {
+      "category": "data display",
+      "status": "experimental",
+      "useWhen": "A table or detail cell has no value: renders the em dash placeholder consistently.",
+      "dontUseWhen": "The value is genuinely empty text a user typed — render it as-is.",
+      "replacesRawHtml": [
+        "<span>—</span>"
+      ],
+      "since": "unreleased",
+      "story": "src/composites/data-table-view.stories.tsx"
+    },
+    "SidebarDrawer": {
+      "category": "shell/screens",
+      "useWhen": "The sidebar nav off-canvas on small viewports: the same tree in a left-hand Sheet, with the focus trap, scroll lock and dismissal the overlay parts already provide.",
+      "dontUseWhen": "Desktop widths (`Sidebar`) or a bottom tab bar (`BottomNav`).",
+      "related": [
+        "Sidebar",
+        "Sheet",
+        "Shell"
+      ],
+      "status": "experimental",
+      "since": "1.38.0"
     }
   },
   "entries": {
@@ -1572,33 +3356,185 @@
     }
   },
   "deprecatedAliases": [
-    { "deprecated": "`Button variant=\"primary\"`", "replacement": "`variant=\"solid\" intent=\"brand\"` (the default)", "codemod": "CM-04", "contract": "C-BTN-VARIANT" },
-    { "deprecated": "`Button variant=\"secondary\"`", "replacement": "`variant=\"soft\" intent=\"neutral\"`", "codemod": "CM-04", "contract": "C-BTN-VARIANT" },
-    { "deprecated": "`Button variant=\"destructive\"`", "replacement": "`variant=\"solid\" intent=\"danger\"`", "codemod": "CM-04", "contract": "C-BTN-VARIANT" },
-    { "deprecated": "`Button variant=\"success\"`", "replacement": "`variant=\"solid\" intent=\"success\"`", "codemod": "CM-04", "contract": "C-BTN-VARIANT" },
-    { "deprecated": "`Button variant=\"accent\"` / `\"dashed\"`", "replacement": "Reported by CM-04 for review: `accent` is a brand look, `dashed` an outline look; both keep rendering until 3.0", "codemod": "CM-04 (report)", "contract": "C-BTN-VARIANT" },
-    { "deprecated": "`Button intent=\"destructive\"`", "replacement": "`intent=\"danger\"`", "codemod": "—", "contract": "C-BTN-VARIANT" },
-    { "deprecated": "`Button size=\"compact\"` / `\"default\"` / `\"comfortable\"`, `\"icon-xs\"` / `\"icon-sm\"` / `\"icon\"`", "replacement": "`size=\"sm\"` / `\"md\"` / `\"lg\"`; icon sizes → `IconButton size`", "codemod": "CM-02 (explicit `size=\"md\"`)", "contract": "C-BTN-SIZE" },
-    { "deprecated": "`Button` / `LinkButton` / `SubmitButton` `iconLeft` / `iconRight`", "replacement": "`iconStart` / `iconEnd`", "codemod": "CM-05", "contract": "C-BTN-ICONPROPS" },
-    { "deprecated": "`Button` without `type` inside a form", "replacement": "`type=\"submit\"` where evident, or `SubmitButton`", "codemod": "CM-12", "contract": "—" },
-    { "deprecated": "`Input` / `Textarea` / `SearchInput` `inputSize`", "replacement": "`size`", "codemod": "CM-07", "contract": "C-INPUT-SIZE" },
-    { "deprecated": "`InputSizeAlias` `compact` / `default` / `comfortable`", "replacement": "`sm` / `md` / `lg`", "codemod": "—", "contract": "C-INPUT-SIZE" },
-    { "deprecated": "`Select` `triggerClassName` / `contentClassName`", "replacement": "`classNames={{ trigger, content }}`", "codemod": "—", "contract": "C-SELECT-CLASSNAMES" },
-    { "deprecated": "`Select searchable`", "replacement": "`Combobox`", "codemod": "—", "contract": "—" },
-    { "deprecated": "`Select` sentinel option values standing in for \"no value\"", "replacement": "A real empty value (`value=\"\"`, `clearable`)", "codemod": "CM-20 (finder)", "contract": "C-SELECT-EMPTY" },
-    { "deprecated": "`SearchSelect` (`{ id, label }` options)", "replacement": "`Combobox` with `Option` (`{ value, label }`)", "codemod": "CM-08", "contract": "C-SEARCHSELECT" },
-    { "deprecated": "`Checkbox indeterminate`", "replacement": "`checked=\"indeterminate\"`", "codemod": "—", "contract": "C-CHECKBOX-INDET" },
-    { "deprecated": "`DatePicker onChange={e => f(e.target.value)}` (fake event)", "replacement": "`onValueChange={value => f(value)}`", "codemod": "CM-10", "contract": "C-DATE-FAKEEVENT" },
-    { "deprecated": "`StatusDot` / `IconTile` / `Spinner` / `SegmentedProgress` / `SuiteProgress` `tone`", "replacement": "`intent` (`pro` → `brand`, `muted` → `neutral`, `accent` → `info`, `destructive` → `danger`)", "codemod": "CM-06", "contract": "C-TONE" },
-    { "deprecated": "`ProgressBar` / `ProgressRing` `variant` (`default`, `destructive`, …)", "replacement": "`intent` (`brand`, `danger`, …); value-driven auto colour written down explicitly", "codemod": "CM-19", "contract": "C-PROGRESS" },
-    { "deprecated": "`Badge variant=\"default\"` / `\"secondary\"` / `\"destructive\"` / `\"success\"` / `\"warning\"` / `\"info\"` / `\"outline\"`", "replacement": "`variant` (`solid`, `soft`, `outline`) + `intent`", "codemod": "—", "contract": "C-BADGE" },
-    { "deprecated": "`FormError`", "replacement": "`FieldError` inside a `Field`", "codemod": "—", "contract": "C-FORM-MSG" },
-    { "deprecated": "`FormSuccess`", "replacement": "`FieldDescription` inside a `Field`, or a toast for a saved form", "codemod": "—", "contract": "C-FORM-MSG" },
-    { "deprecated": "`FormSection`", "replacement": "`Fieldset` + `FieldsetLegend`", "codemod": "—", "contract": "—" },
-    { "deprecated": "`PhoneInput`, `PhoneCountryInput` (+ `CountrySelect`, `CountryFlag`)", "replacement": "`PhoneField` (E.164 value, `Combobox` country picker)", "codemod": "—", "contract": "—" },
-    { "deprecated": "`Sidebar gutterPx`", "replacement": "The sidebar's own geometry tokens", "codemod": "—", "contract": "—" },
-    { "deprecated": "`CloseIcon`, `ArrowRightSmallIcon`", "replacement": "`XIcon`, `ArrowRightIcon` (same drawing)", "codemod": "—", "contract": "—" },
-    { "deprecated": "Hidden `<input name>` mirrors added because a control posted nothing", "replacement": "Remove them: every control participates in the form through `FormBridge`", "codemod": "CM-14 (finder)", "contract": "C-HIDDEN-MIRRORS" },
-    { "deprecated": "Selectors into a component's internal DOM", "replacement": "`className` / `classNames` and `data-slot` selectors (ADR-008)", "codemod": "CM-15 (finder)", "contract": "C-DOM-*" }
+    {
+      "deprecated": "`Button variant=\"primary\"`",
+      "replacement": "`variant=\"solid\" intent=\"brand\"` (the default)",
+      "codemod": "CM-04",
+      "contract": "C-BTN-VARIANT"
+    },
+    {
+      "deprecated": "`Button variant=\"secondary\"`",
+      "replacement": "`variant=\"soft\" intent=\"neutral\"`",
+      "codemod": "CM-04",
+      "contract": "C-BTN-VARIANT"
+    },
+    {
+      "deprecated": "`Button variant=\"destructive\"`",
+      "replacement": "`variant=\"solid\" intent=\"danger\"`",
+      "codemod": "CM-04",
+      "contract": "C-BTN-VARIANT"
+    },
+    {
+      "deprecated": "`Button variant=\"success\"`",
+      "replacement": "`variant=\"solid\" intent=\"success\"`",
+      "codemod": "CM-04",
+      "contract": "C-BTN-VARIANT"
+    },
+    {
+      "deprecated": "`Button variant=\"accent\"` / `\"dashed\"`",
+      "replacement": "Reported by CM-04 for review: `accent` is a brand look, `dashed` an outline look; both keep rendering until 3.0",
+      "codemod": "CM-04 (report)",
+      "contract": "C-BTN-VARIANT"
+    },
+    {
+      "deprecated": "`Button intent=\"destructive\"`",
+      "replacement": "`intent=\"danger\"`",
+      "codemod": "—",
+      "contract": "C-BTN-VARIANT"
+    },
+    {
+      "deprecated": "`Button size=\"compact\"` / `\"default\"` / `\"comfortable\"`, `\"icon-xs\"` / `\"icon-sm\"` / `\"icon\"`",
+      "replacement": "`size=\"sm\"` / `\"md\"` / `\"lg\"`; icon sizes → `IconButton size`",
+      "codemod": "CM-02 (explicit `size=\"md\"`)",
+      "contract": "C-BTN-SIZE"
+    },
+    {
+      "deprecated": "`Button` / `LinkButton` / `SubmitButton` `iconLeft` / `iconRight`",
+      "replacement": "`iconStart` / `iconEnd`",
+      "codemod": "CM-05",
+      "contract": "C-BTN-ICONPROPS"
+    },
+    {
+      "deprecated": "`Button` without `type` inside a form",
+      "replacement": "`type=\"submit\"` where evident, or `SubmitButton`",
+      "codemod": "CM-12",
+      "contract": "—"
+    },
+    {
+      "deprecated": "`Input` / `Textarea` / `SearchInput` `inputSize`",
+      "replacement": "`size`",
+      "codemod": "CM-07",
+      "contract": "C-INPUT-SIZE"
+    },
+    {
+      "deprecated": "`InputSizeAlias` `compact` / `default` / `comfortable`",
+      "replacement": "`sm` / `md` / `lg`",
+      "codemod": "—",
+      "contract": "C-INPUT-SIZE"
+    },
+    {
+      "deprecated": "`Select` `triggerClassName` / `contentClassName`",
+      "replacement": "`classNames={{ trigger, content }}`",
+      "codemod": "—",
+      "contract": "C-SELECT-CLASSNAMES"
+    },
+    {
+      "deprecated": "`Dash` (DataTableView cell)",
+      "replacement": "`EmptyValue`",
+      "codemod": "—",
+      "contract": "—"
+    },
+    {
+      "deprecated": "`StagePill` / `Assignee` / `MoneyCell` / `TableTone` (DataTableView product cells)",
+      "replacement": "Product-owned renderers in `column.render` (`StatusBadge`, `Avatar`, `Intl.NumberFormat`, `EmptyValue`); hand-over to TAX in W8-13",
+      "codemod": "—",
+      "contract": "—"
+    },
+    {
+      "deprecated": "`Select searchable`",
+      "replacement": "`Combobox`",
+      "codemod": "—",
+      "contract": "—"
+    },
+    {
+      "deprecated": "`Select` sentinel option values standing in for \"no value\"",
+      "replacement": "A real empty value (`value=\"\"`, `clearable`)",
+      "codemod": "CM-20 (finder)",
+      "contract": "C-SELECT-EMPTY"
+    },
+    {
+      "deprecated": "`SearchSelect` (`{ id, label }` options)",
+      "replacement": "`Combobox` with `Option` (`{ value, label }`)",
+      "codemod": "CM-08",
+      "contract": "C-SEARCHSELECT"
+    },
+    {
+      "deprecated": "`Checkbox indeterminate`",
+      "replacement": "`checked=\"indeterminate\"`",
+      "codemod": "—",
+      "contract": "C-CHECKBOX-INDET"
+    },
+    {
+      "deprecated": "`DatePicker onChange={e => f(e.target.value)}` (fake event)",
+      "replacement": "`onValueChange={value => f(value)}`",
+      "codemod": "CM-10",
+      "contract": "C-DATE-FAKEEVENT"
+    },
+    {
+      "deprecated": "`StatusDot` / `IconTile` / `Spinner` / `SegmentedProgress` / `SuiteProgress` `tone`",
+      "replacement": "`intent` (`pro` → `brand`, `muted` → `neutral`, `accent` → `info`, `destructive` → `danger`)",
+      "codemod": "CM-06",
+      "contract": "C-TONE"
+    },
+    {
+      "deprecated": "`ProgressBar` / `ProgressRing` `variant` (`default`, `destructive`, …)",
+      "replacement": "`intent` (`brand`, `danger`, …); value-driven auto colour written down explicitly",
+      "codemod": "CM-19",
+      "contract": "C-PROGRESS"
+    },
+    {
+      "deprecated": "`Badge variant=\"default\"` / `\"secondary\"` / `\"destructive\"` / `\"success\"` / `\"warning\"` / `\"info\"` / `\"outline\"`",
+      "replacement": "`variant` (`solid`, `soft`, `outline`) + `intent`",
+      "codemod": "—",
+      "contract": "C-BADGE"
+    },
+    {
+      "deprecated": "`FormError`",
+      "replacement": "`FieldError` inside a `Field`",
+      "codemod": "—",
+      "contract": "C-FORM-MSG"
+    },
+    {
+      "deprecated": "`FormSuccess`",
+      "replacement": "`FieldDescription` inside a `Field`, or a toast for a saved form",
+      "codemod": "—",
+      "contract": "C-FORM-MSG"
+    },
+    {
+      "deprecated": "`FormSection`",
+      "replacement": "`Fieldset` + `FieldsetLegend`",
+      "codemod": "—",
+      "contract": "—"
+    },
+    {
+      "deprecated": "`PhoneInput`, `PhoneCountryInput` (+ `CountrySelect`, `CountryFlag`)",
+      "replacement": "`PhoneField` (E.164 value, `Combobox` country picker)",
+      "codemod": "—",
+      "contract": "—"
+    },
+    {
+      "deprecated": "`Sidebar gutterPx`",
+      "replacement": "The sidebar's own geometry tokens",
+      "codemod": "—",
+      "contract": "—"
+    },
+    {
+      "deprecated": "`CloseIcon`, `ArrowRightSmallIcon`",
+      "replacement": "`XIcon`, `ArrowRightIcon` (same drawing)",
+      "codemod": "—",
+      "contract": "—"
+    },
+    {
+      "deprecated": "Hidden `<input name>` mirrors added because a control posted nothing",
+      "replacement": "Remove them: every control participates in the form through `FormBridge`",
+      "codemod": "CM-14 (finder)",
+      "contract": "C-HIDDEN-MIRRORS"
+    },
+    {
+      "deprecated": "Selectors into a component's internal DOM",
+      "replacement": "`className` / `classNames` and `data-slot` selectors (ADR-008)",
+      "codemod": "CM-15 (finder)",
+      "contract": "C-DOM-*"
+    }
   ]
 }