@assure-one/design-system 1.35.0 → 1.36.0

package/docs/components.registry.json

@@ -0,0 +1,1586 @@
+{
+  "$comment": "Hand-maintained half of docs/components.md. `pnpm docs:catalogue` joins it with api/*.api.md; `pnpm docs:catalogue --check` (in test:contracts) fails when a public export has no row here or a row names an export that no longer exists. One row per component family: `parts` are the compound sub-components documented under the row, `helpers` the non-component exports of the family (cva tables, maps, formatters), `hooks` its hooks. `status` is derived (@deprecated from the API report, @experimental from the source JSDoc) unless set here. `story` defaults to the .stories.tsx next to the module. Categories: actions, forms, selection, feedback, overlays, navigation, layout, typography, data display, media, icons, shell/screens, hooks/utilities.",
+  "categories": {
+    "actions": "Things you press. Every clickable control is one of these; a `<button>`, `<a role=\"button\">` or `<div onClick>` in product code is a bug.",
+    "forms": "Controls that carry a value into a form. Every one binds to `Field` through `useFieldControl` (label, description, error, ids) and participates in native form submission (ADR-006); wrap them in `Field`, never in a hand-rolled label + input pair.",
+    "selection": "Pick one or many from a set: dropdowns, comboboxes, toggle groups, chips and filters.",
+    "feedback": "Tell the user what is happening: status messages, progress, loading and empty states.",
+    "overlays": "Layers above the page: dialogs, sheets, menus, popovers and tooltips. All portal, trap or manage focus, close on Escape and respect reduced motion.",
+    "navigation": "Move between places: tabs, breadcrumbs, pagination, steppers, trees and rails.",
+    "layout": "Arrange content: stacks, surfaces, cards, separators, section and page framing.",
+    "typography": "Text roles. Use these instead of bare `<h*>`, `<p>`, `<code>` and `<kbd>` so type scale, colour and letterspacing come from tokens.",
+    "data display": "Show records and status: tables, key/value grids, badges, dots, avatars, lists and cards for domain objects.",
+    "media": "Charts, previews and brand artwork.",
+    "shell/screens": "The application frame and full-screen composites: shell, sidebar, header, brand scope and product surfaces shared by more than one app.",
+    "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", "AlertDialog"], "notes": "`ConfirmActionButton` wraps the dialog around any trigger; `AlertDialog` when you compose the copy yourself." },
+    { "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." }
+  ],
+  "iconFamilies": [
+    {
+      "name": "Icons",
+      "pattern": "Icon$",
+      "exclude": "BrandIcon$",
+      "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"],
+      "story": "src/primitives/icons.stories.tsx",
+      "status": "experimental"
+    },
+    {
+      "name": "Brand icons",
+      "pattern": "BrandIcon$",
+      "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\">"],
+      "story": "src/primitives/logo.stories.tsx"
+    }
+  ],
+  "components": {
+    "Button": {
+      "category": "actions",
+      "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"],
+      "since": "0.0.0",
+      "docs": ["docs/adr/007-variant-intent-vocabulary.md"]
+    },
+    "IconButton": {
+      "category": "actions",
+      "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"],
+      "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"],
+      "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"],
+      "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"],
+      "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"],
+      "since": "0.0.0"
+    },
+    "ConfirmActionButton": {
+      "category": "actions",
+      "useWhen": "A destructive or irreversible action that needs a confirmation step: wraps `AlertDialog` around any trigger and retires `window.confirm()`.",
+      "dontUseWhen": "The confirmation needs a form or custom body (`AlertDialog` composed directly) or the action is reversible (act, then offer undo in a toast).",
+      "replacesRawHtml": ["window.confirm()", "useState + AlertDialog boilerplate"],
+      "related": ["AlertDialog", "DangerAction"],
+      "since": "0.3.0"
+    },
+    "PrimaryAction": {
+      "category": "actions",
+      "label": "Intent actions",
+      "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"],
+      "since": "0.3.0"
+    },
+    "BulkActionBar": {
+      "category": "actions",
+      "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"],
+      "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"],
+      "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"],
+      "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"],
+      "since": "1.25.0"
+    },
+    "Toolbar": {
+      "category": "actions",
+      "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"],
+      "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"],
+      "since": "1.5.0"
+    },
+
+    "Field": {
+      "category": "forms",
+      "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"],
+      "since": "unreleased",
+      "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"],
+      "since": "unreleased"
+    },
+    "Fieldset": {
+      "category": "forms",
+      "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"],
+      "since": "unreleased"
+    },
+    "Label": {
+      "category": "forms",
+      "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"],
+      "since": "0.0.0"
+    },
+    "Input": {
+      "category": "forms",
+      "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"],
+      "since": "0.0.0",
+      "docs": ["docs/design-system/control-sizes.md"]
+    },
+    "Textarea": {
+      "category": "forms",
+      "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"],
+      "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"],
+      "since": "unreleased"
+    },
+    "SearchInput": {
+      "category": "forms",
+      "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"],
+      "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"],
+      "since": "0.0.0"
+    },
+    "PhoneField": {
+      "category": "forms",
+      "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"],
+      "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"],
+      "since": "0.0.0"
+    },
+    "PhoneCountryInput": {
+      "category": "forms",
+      "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"],
+      "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"],
+      "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"],
+      "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"],
+      "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"],
+      "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"],
+      "since": "0.0.0"
+    },
+    "RadioGroup": {
+      "category": "forms",
+      "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"],
+      "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"],
+      "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"],
+      "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"],
+      "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"],
+      "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"],
+      "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"],
+      "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"],
+      "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"],
+      "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"],
+      "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"],
+      "since": "1.20.0"
+    },
+    "ProposalSignatureBlock": {
+      "category": "forms",
+      "label": "Proposal signing",
+      "parts": ["ProposalConsentGate", "ProposalPaymentCapture"],
+      "useWhen": "The signing step of a proposal: consent gate, signature capture, payment capture.",
+      "dontUseWhen": "An email signature (`SignatureEditor`).",
+      "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"],
+      "since": "0.4.1"
+    },
+    "FormError": {
+      "category": "forms",
+      "label": "FormError / 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"],
+      "since": "0.0.0"
+    },
+
+    "Select": {
+      "category": "selection",
+      "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"],
+      "since": "0.0.0"
+    },
+    "Combobox": {
+      "category": "selection",
+      "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"],
+      "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"],
+      "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"],
+      "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"],
+      "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"],
+      "since": "0.0.0"
+    },
+    "ToggleGroup": {
+      "category": "selection",
+      "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"],
+      "since": "0.0.0"
+    },
+    "Chip": {
+      "category": "selection",
+      "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"],
+      "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"],
+      "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"],
+      "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"],
+      "since": "1.12.0"
+    },
+
+    "Alert": {
+      "category": "feedback",
+      "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"],
+      "since": "0.0.0"
+    },
+    "ToastProvider": {
+      "category": "feedback",
+      "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"],
+      "since": "0.0.0"
+    },
+    "Spinner": {
+      "category": "feedback",
+      "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"],
+      "since": "0.15.0"
+    },
+    "Skeleton": {
+      "category": "feedback",
+      "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"],
+      "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"],
+      "since": "0.4.1"
+    },
+    "ProgressBar": {
+      "category": "feedback",
+      "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"],
+      "since": "0.0.0"
+    },
+    "ProgressRing": {
+      "category": "feedback",
+      "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"],
+      "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"],
+      "since": "1.2.0"
+    },
+    "SuiteProgress": {
+      "category": "feedback",
+      "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"],
+      "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"],
+      "since": "0.0.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"],
+      "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"],
+      "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"],
+      "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"],
+      "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"],
+      "since": "1.2.0"
+    },
+
+    "Dialog": {
+      "category": "overlays",
+      "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"],
+      "since": "0.0.0",
+      "docs": ["docs/adr/012-overlay-presence-motion.md"]
+    },
+    "AlertDialog": {
+      "category": "overlays",
+      "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"],
+      "since": "0.0.0"
+    },
+    "Sheet": {
+      "category": "overlays",
+      "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"],
+      "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"],
+      "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"],
+      "since": "1.3.0"
+    },
+    "Popover": {
+      "category": "overlays",
+      "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"],
+      "since": "0.0.0"
+    },
+    "HoverCard": {
+      "category": "overlays",
+      "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"],
+      "since": "0.0.0"
+    },
+    "Tooltip": {
+      "category": "overlays",
+      "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"],
+      "since": "0.0.0"
+    },
+    "DropdownMenu": {
+      "category": "overlays",
+      "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"],
+      "since": "0.0.0"
+    },
+    "ContextMenu": {
+      "category": "overlays",
+      "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"],
+      "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"],
+      "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"],
+      "since": "0.0.0"
+    },
+
+    "Tabs": {
+      "category": "navigation",
+      "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"],
+      "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"],
+      "since": "1.5.0"
+    },
+    "Breadcrumb": {
+      "category": "navigation",
+      "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"],
+      "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"],
+      "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"],
+      "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"],
+      "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"],
+      "since": "1.2.0"
+    },
+    "ClientRailItem": {
+      "category": "navigation",
+      "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"],
+      "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"],
+      "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"],
+      "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"],
+      "since": "1.33.0"
+    },
+    "Card": {
+      "category": "layout",
+      "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"],
+      "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"],
+      "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"],
+      "since": "0.0.0"
+    },
+    "ScrollArea": {
+      "category": "layout",
+      "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"],
+      "since": "0.0.0"
+    },
+    "Collapsible": {
+      "category": "layout",
+      "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"],
+      "since": "0.0.0"
+    },
+    "Accordion": {
+      "category": "layout",
+      "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"],
+      "since": "0.0.0"
+    },
+    "Section": {
+      "category": "layout",
+      "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"],
+      "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"],
+      "since": "0.0.0"
+    },
+    "PageHeader": {
+      "category": "layout",
+      "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"],
+      "since": "0.3.0"
+    },
+    "CategoryDivider": {
+      "category": "layout",
+      "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"],
+      "since": "1.3.0"
+    },
+    "StickyStack": {
+      "category": "layout",
+      "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"],
+      "since": "1.30.1"
+    },
+    "DetailGrid": {
+      "category": "layout",
+      "label": "Detail layout",
+      "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"],
+      "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"],
+      "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"],
+      "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"],
+      "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"],
+      "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"],
+      "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"],
+      "since": "1.33.0",
+      "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"],
+      "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"],
+      "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"],
+      "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"],
+      "since": "0.0.0"
+    },
+    "Eyebrow": {
+      "category": "typography",
+      "label": "Intent atoms",
+      "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"],
+      "since": "0.3.0"
+    },
+    "StarRating": {
+      "category": "data display",
+      "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"],
+      "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"],
+      "since": "0.0.0"
+    },
+
+    "Table": {
+      "category": "data display",
+      "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"],
+      "since": "0.0.0"
+    },
+    "DataTable": {
+      "category": "data display",
+      "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"],
+      "since": "0.3.0"
+    },
+    "DataTableView": {
+      "category": "data display",
+      "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"],
+      "since": "1.6.0"
+    },
+    "MetadataGrid": {
+      "category": "data display",
+      "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"],
+      "since": "0.4.1"
+    },
+    "KpiCard": {
+      "category": "data display",
+      "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"],
+      "since": "0.4.1"
+    },
+    "Badge": {
+      "category": "data display",
+      "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"],
+      "since": "0.0.0"
+    },
+    "StatusBadge": {
+      "category": "data display",
+      "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"],
+      "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"],
+      "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"],
+      "since": "1.5.0"
+    },
+    "StatusDot": {
+      "category": "data display",
+      "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"],
+      "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"],
+      "since": "0.8.0",
+      "story": "src/primitives/priority-status-icons.stories.tsx"
+    },
+    "PriorityIcon": {
+      "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"],
+      "since": "0.8.0",
+      "story": "src/primitives/priority-status-icons.stories.tsx"
+    },
+    "IconTile": {
+      "category": "data display",
+      "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"],
+      "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"],
+      "since": "0.0.0"
+    },
+    "FileTypeBadge": {
+      "category": "data display",
+      "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"],
+      "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"],
+      "since": "1.2.0"
+    },
+    "AttachmentChip": {
+      "category": "data display",
+      "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"],
+      "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"],
+      "since": "1.12.0"
+    },
+    "ActivityList": {
+      "category": "data display",
+      "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"],
+      "since": "0.3.0"
+    },
+    "NotificationPanel": {
+      "category": "data display",
+      "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"],
+      "since": "0.7.0"
+    },
+    "Kanban": {
+      "category": "data display",
+      "parts": ["KanbanColumn", "KanbanCard"],
+      "useWhen": "A board of columns and cards for stage-based work.",
+      "dontUseWhen": "The data is tabular (`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"],
+      "since": "1.2.0"
+    },
+    "EngagementTimeline": {
+      "category": "data display",
+      "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"],
+      "since": "1.2.0"
+    },
+    "MessageBubble": {
+      "category": "data display",
+      "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"],
+      "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"],
+      "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"],
+      "since": "1.21.0"
+    },
+    "DocumentDetailPanel": {
+      "category": "data display",
+      "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"],
+      "since": "1.8.0"
+    },
+    "DocumentFileRow": {
+      "category": "data display",
+      "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"],
+      "since": "1.4.0"
+    },
+    "DocumentRequestDetail": {
+      "category": "data display",
+      "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"],
+      "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"],
+      "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"],
+      "since": "0.15.0"
+    },
+    "ProposalPackageCard": {
+      "category": "data display",
+      "label": "Proposal pricing",
+      "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"],
+      "since": "1.12.0"
+    },
+    "ProposalSignerList": {
+      "category": "data display",
+      "label": "Proposal content",
+      "parts": ["ProposalNote", "ProposalCustomPage"],
+      "useWhen": "The content blocks of a proposal: signer list, notes, custom pages.",
+      "dontUseWhen": "Anything outside a proposal.",
+      "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"],
+      "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"],
+      "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"],
+      "since": "1.6.0"
+    },
+    "RankedBars": {
+      "category": "media",
+      "useWhen": "A ranked list of labelled values as horizontal bars.",
+      "dontUseWhen": "Stacked composition (`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"],
+      "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"],
+      "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"],
+      "since": "0.0.0"
+    },
+
+    "Shell": {
+      "category": "shell/screens",
+      "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"],
+      "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"],
+      "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"],
+      "since": "0.3.0"
+    },
+    "SidebarBrandSwitcher": {
+      "category": "shell/screens",
+      "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"],
+      "since": "0.11.2"
+    },
+    "AppHeader": {
+      "category": "shell/screens",
+      "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"],
+      "since": "0.3.0"
+    },
+    "DesignSystemProvider": {
+      "category": "shell/screens",
+      "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`, and the tooltip provider. `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"],
+      "since": "unreleased",
+      "story": "src/foundation/provider/design-system-provider.stories.tsx"
+    },
+    "ThemeScope": {
+      "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"],
+      "since": "unreleased",
+      "story": "src/primitives/behavior/portal.stories.tsx",
+      "docs": ["docs/integration/css.md"]
+    },
+    "BrandScope": {
+      "category": "shell/screens",
+      "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"],
+      "since": "1.18.0",
+      "docs": ["docs/integration/css.md"]
+    },
+    "AgreementViewer": {
+      "category": "shell/screens",
+      "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"],
+      "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"],
+      "since": "0.0.0",
+      "docs": ["docs/integration/css.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"],
+      "since": "1.32.0",
+      "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"],
+      "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"],
+      "since": "0.11.0"
+    },
+    "COUNTRY_CODES": {
+      "category": "hooks/utilities",
+      "label": "Country codes",
+      "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"],
+      "since": "1.1.0"
+    },
+    "serviceToneStyle": {
+      "category": "hooks/utilities",
+      "label": "Service tones",
+      "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"],
+      "since": "1.2.0"
+    },
+    "assetPath": {
+      "category": "hooks/utilities",
+      "label": "Asset base path",
+      "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"],
+      "since": "1.33.0"
+    },
+    "systemTokens": {
+      "category": "hooks/utilities",
+      "label": "Tokens (root re-export)",
+      "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"],
+      "since": "0.0.0",
+      "docs": ["docs/design-system/shape-roles.md"]
+    }
+  },
+  "entries": {
+    "next": {
+      "NextDesignSystemProvider": "`DesignSystemProvider` with `next/link` and `next/image` filled in; takes every other provider prop."
+    },
+    "tokens": {
+      "BRAND_THEME_PROPERTIES": "The custom-property names a brand theme sets.",
+      "breakpoints": "Viewport breakpoints as numbers.",
+      "colors": "Reference palette (programmatic access; never for component styling).",
+      "createBrandTheme": "Build a runtime brand theme from a seed (`docs/integration/css.md` §5). Experimental.",
+      "iconSizes": "The icon size scale in pixels.",
+      "layout": "Layout constants (sidebar width, header height, content pad).",
+      "motion": "Durations and easings.",
+      "overlays": "Overlay constants (z-index tiers, backdrop).",
+      "radii": "Radius scale.",
+      "reference": "All reference tokens in one object.",
+      "shadows": "Shadow scale.",
+      "spacing": "The 4px spacing scale.",
+      "surfaces": "The four canonical surface layers.",
+      "systemTokens": "System (semantic) tokens as CSS variable references — the ones components consume.",
+      "typography": "Font families, sizes, weights and letterspacing.",
+      "zIndex": "Z-index tiers."
+    },
+    "testing": {
+      "withAssureDesignSystem": "Jest config wrapper that makes the real package load (resolution, ESM transform, jsdom shims).",
+      "installDomPolyfills": "The jsdom shims alone, for Vitest or a custom setup file.",
+      "createToastRecorder": "Records the toasts a real `ToastProvider` shows.",
+      "selectOption": "Chooses an option in a design-system `Select` through the DOM.",
+      "openMenu": "Opens a design-system `DropdownMenu` and returns a handle to its items.",
+      "fillField": "Types into a text control found by its `Field` label.",
+      "pickDate": "Sets a design-system `DatePicker` to an ISO date through the DOM."
+    }
+  },
+  "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-*" }
+  ]
+}