@assure-one/design-system 1.34.0 → 1.36.0

package/docs/components.md

@@ -0,0 +1,601 @@
+# Component catalogue
+
+<!-- Generated by `pnpm docs:catalogue` from api/*.api.md and docs/components.registry.json. Do not edit by hand; edit the registry and regenerate. -->
+
+Every public component of `@assure-one/design-system`, in one place: **547 component exports** — 166 component families with 228 compound parts, and 153 icons — plus the hooks, utilities, tokens and testing helpers the package exports. The list is derived from the API reports, so a public component cannot be missing from this page (`pnpm docs:catalogue --check` runs in `pnpm test:contracts`).
+
+**How to use this page.** Start from the ["Pick a component"](#pick-a-component) table with the UI need you have, or from ["Never hand-roll"](#never-hand-roll) with the raw element you were about to write; links land on the category section that holds the row. Every row links to the story that shows the states. The short rulebook for agents and new contributors is [`docs/for-ai-agents.md`](./for-ai-agents.md).
+
+```tsx
+import { Button, Field, Input, Select } from "@assure-one/design-system";
+import { CheckIcon } from "@assure-one/design-system/icons"; // server-safe icons
+import { systemTokens } from "@assure-one/design-system/tokens";
+```
+
+**Status words.** *stable* — covered by the compatibility contract; *experimental* — `@experimental` in the source (ADR-011), may change in a minor; *deprecated* — `@deprecated` in the API report, replaced as the [aliases table](#deprecated-aliases-and-their-replacements) says and removed in 3.0.
+
+## Contents
+
+- [Pick a component](#pick-a-component)
+- [Actions](#actions)
+- [Forms](#forms)
+- [Selection](#selection)
+- [Feedback](#feedback)
+- [Overlays](#overlays)
+- [Navigation](#navigation)
+- [Layout](#layout)
+- [Typography](#typography)
+- [Data display](#data-display)
+- [Media](#media)
+- [Icons](#icons)
+- [Shell/screens](#shell-screens)
+- [Hooks/utilities](#hooks-utilities)
+- [Never hand-roll](#never-hand-roll)
+- [Deprecated aliases and their replacements](#deprecated-aliases-and-their-replacements)
+- [`/tokens` entry](#tokens-entry)
+- [`/testing` entry](#testing-entry)
+- [`/next` entry](#next-entry)
+
+## Pick a component
+
+The UI need on the left, the design-system answer on the right. When two components are listed the first is the default; the note says when to reach for the other.
+
+| I need to… | Use | Notes |
+| --- | --- | --- |
+| Trigger an action | [Button](#actions), [IconButton](#actions) | `IconButton` when the control is only an icon (it requires an accessible name and shows a tooltip). Same `variant` × `intent` × `size` axes. |
+| Navigate somewhere with a button look | [LinkButton](#actions) | Renders an `<a href>`; `Button asChild` around your router's `Link` is the alternative. |
+| Submit a form | [SubmitButton](#actions) | Full-width by default; `type="submit"` and pending state handled. |
+| Make something that is not a button clickable | [Pressable](#actions) | Keyboard, focus ring, disabled handling, no button chrome. Never `<div onClick>`. |
+| Confirm a destructive action | [ConfirmActionButton](#actions), [AlertDialog](#overlays) | `ConfirmActionButton` wraps the dialog around any trigger; `AlertDialog` when you compose the copy yourself. |
+| Act on selected rows | [BulkActionBar](#actions) | Floating bar with the count and the row actions. |
+| Keep Save / Cancel visible at the bottom of a long form | [StickyActionBar](#actions) |  |
+| Label + help + error around any control | [Field](#forms) | `Label`, `FieldDescription`, `FieldError` inside; controls bind automatically. `Fieldset` groups several. `FieldControl` wires a non-DS control. |
+| Free text, one line | [Input](#forms) | `SearchInput` for search boxes, `NumberInput` for numbers, `PhoneField` for phone numbers, `OTPInput` for codes. |
+| A phone number | [PhoneField](#forms) | Country picker + national number, E.164 value. `PhoneInput` and `PhoneCountryInput` are deprecated. |
+| Free text, several lines | [Textarea](#forms) |  |
+| A number with formatting or steppers | [NumberInput](#forms) |  |
+| A date, or a date range | [DatePicker](#forms), [DateRangePicker](#forms) | `Calendar` alone when the picker should be inline rather than in a popover. |
+| Upload files | [FileUpload](#forms) | `DocumentRequestUpload` for the client-portal request flow. |
+| Yes / no | [Checkbox](#forms), [Switch](#forms) | `Switch` when the change applies immediately, `Checkbox` when it is submitted with the form or is one of several. |
+| One of a few visible options | [RadioGroup](#forms), [ToggleGroup](#selection) | `RadioGroup` in forms; `ToggleGroup` for view/mode switches with immediate effect. |
+| One of many options in a dropdown | [Select](#selection), [Combobox](#selection) | `Select` for short static lists; `Combobox` when the user should type to filter or the list is large or async. |
+| Several of many options | [MultiSelect](#selection), [MultiSelectField](#forms) | `MultiSelect` is the searchable dropdown; `MultiSelectField` a visible pill toggle row for a handful of options. |
+| Pick a client or a team member | [ClientSelect](#selection), [TeamMemberSelect](#selection) |  |
+| Filter a list | [Toolbar](#actions), [MultiFilterPill](#selection), [DisplayMenu](#actions) | `FilterChip` inside `Toolbar` for one-value filters, `MultiFilterPill` for multi-value, `DisplayMenu` for the Linear-style filter/group/sort/columns menu. |
+| Removable or toggleable tokens (tags, applied filters) | [Chip](#selection) | `DismissibleChip` is the older single-purpose removable chip. |
+| A slider value | [Slider](#forms) |  |
+| Show a message inline (success, warning, error, info) | [Alert](#feedback) |  |
+| Notify after an action | [ToastProvider](#feedback) | `useToast()` from inside the provider. |
+| Show loading | [Spinner](#feedback), [Skeleton](#feedback), [LoadingRows](#feedback) | `Spinner` inside a control or small area, `Skeleton` for a shape, `LoadingRows` for list/table rows. |
+| Show progress | [ProgressBar](#feedback), [ProgressRing](#feedback), [SegmentedProgress](#feedback), [Stepper](#navigation) | `Stepper` when the steps have names; `SuiteProgress` for the suite's segmented percent meter. |
+| Nothing to show yet | [EmptyState](#feedback), [ComingSoon](#feedback) |  |
+| A modal task or message | [Dialog](#overlays), [ResponsiveDialog](#overlays) | `ResponsiveDialog` becomes a `Sheet` on small screens. |
+| A side panel | [Sheet](#overlays), [SideDrawer](#overlays) | `Sheet` is the Radix-based standard; `SideDrawer` is the older API kept for existing call sites. |
+| A contextual menu of actions | [DropdownMenu](#overlays), [ContextMenu](#overlays), [NewMenu](#actions) | `ContextMenu` on right-click; `NewMenu` is the ready-made "+ New" creation menu. |
+| Extra content on hover or click | [Tooltip](#overlays), [Popover](#overlays), [HoverCard](#overlays) | `Tooltip` for a short label, `Popover` for interactive content, `HoverCard` for a rich preview on hover. |
+| A global command / search box | [CommandPalette](#overlays), [KeyboardShortcutsDialog](#overlays) |  |
+| Switch between views | [Tabs](#navigation), [ChannelTabs](#navigation), [BottomNav](#navigation) | `BottomNav` is the mobile tab bar. |
+| Where am I | [Breadcrumb](#navigation), [PageHeader](#layout), [AppHeader](#shell-screens) |  |
+| Page through results | [Pagination](#navigation) | `DataTablePagination` inside a `DataTable`. |
+| A tree or a rail of items | [FolderTree](#navigation), [ClientRailItem](#navigation) |  |
+| Space things out | [Stack](#layout), [Inline](#layout) | Tokenised gap and alignment; never ad-hoc `flex gap-*` in product code. |
+| A bordered box or card | [Surface](#layout), [Card](#layout) | `Card` adds header/title/description/footer parts and an interactive variant. |
+| A divider | [Separator](#layout), [CategoryDivider](#layout) |  |
+| Collapse content | [Collapsible](#layout), [Accordion](#layout) |  |
+| Scroll a region | [ScrollArea](#layout) |  |
+| Title a page or a section | [PageHeader](#layout), [SectionHeader](#layout), [Heading](#typography) |  |
+| Body text, captions, code, keys | [Text](#typography), [Code](#typography), [Kbd](#typography), [Blockquote](#typography) |  |
+| A number with a caption | [Stat](#typography), [KpiCard](#data-display) | `KpiCard` is the dashboard tile with tone and hint. |
+| A table of records | [DataTableView](#data-display), [DataTable](#data-display), [Table](#data-display) | `DataTableView` is config-driven (columns + data, owns search/sort/pagination); `DataTable` the composable parts; `Table` the bare semantic table. |
+| Label / value pairs | [MetadataGrid](#data-display) |  |
+| A status word or count | [StatusBadge](#data-display), [Badge](#data-display), [StatusPill](#data-display), [StatusDot](#data-display) | `StatusBadge` for statuses (use `defineStatusMap`), `Badge` for counts and neutral labels, `StatusDot` for a dot alone. |
+| A person or a file | [Avatar](#data-display), [FileTypeBadge](#data-display), [FileChip](#data-display), [AttachmentChip](#data-display) |  |
+| An activity feed or notifications | [ActivityList](#data-display), [NotificationPanel](#data-display) |  |
+| A chart | [AreaChart](#media), [DonutChart](#media), [StackedBarChart](#media), [RankedBars](#media) |  |
+| Preview a document | [PdfPreview](#media), [SpreadsheetPreview](#media) |  |
+| An icon | [Icons](#icons) | From the catalogue only, never an inline `<svg>`; brand marks from the brand icon family or `Logo`. |
+| The application frame | [Shell](#shell-screens), [Sidebar](#shell-screens), [AppHeader](#shell-screens) | `DesignSystemProvider` (or `/next`'s `NextDesignSystemProvider`) once in the root layout; `BrandScope` sets the product theme of a subtree. |
+| Configure strings, locale, links or the portal container | [DesignSystemProvider](#shell-screens) | Once, in the root layout. `useDsMessages` reads the resolved strings. |
+| Theme one subtree (scheme, brand, density) including its overlays | [ThemeScope](#shell-screens), [BrandScope](#shell-screens) | `ThemeScope` re-stamps portalled overlays; `BrandScope` is product brand only. |
+| Hide text visually but keep it for screen readers | [VisuallyHidden](#layout) |  |
+| Merge class names | [cn](#hooks-utilities) | Consumer classes win over component classes by cascade; `cn` only dedupes. |
+
+## 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.
+
+| Component | Use when | Don't use when | Replaces raw HTML | Related | Links |
+| --- | --- | --- | --- | --- | --- |
+| **Button**<br>also: `buttonVariants`, `resolveButtonStyle`<br>since 0.0.0 | 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. | The control is icon-only (`IconButton`), navigates (`LinkButton`), submits a form (`SubmitButton`) or is a clickable non-button surface (`Pressable`). | `<button>`, `<a role="button">`, `<div onClick>`, `<input type="button">` | [IconButton](#actions), [LinkButton](#actions), [SubmitButton](#actions), [Pressable](#actions), [PrimaryAction](#actions) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/button.stories.tsx) · [docs](https://github.com/Assure-One/design-system/blob/main/docs/adr/007-variant-intent-vocabulary.md) |
+| **IconButton** (experimental)<br>also: `iconButtonVariants`<br>since 1.35.0 | 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. | The action has a visible text label (`Button` with `iconStart`) or is a menu trigger that shows the chosen value. | `<button><svg/></button>` | [Button](#actions), [Tooltip](#overlays) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/icon-button.stories.tsx) |
+| **LinkButton**<br>since 0.0.0 | Navigation that should look like a button: an `<a href>` with the Button variants, intents, sizes and icon slots. | The action does not change the URL (`Button`) or the link should read as inline text (`Text asChild` around your router link). | `<a class="btn">` | [Button](#actions), [LinkAction](#actions) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/link-button.stories.tsx) |
+| **SubmitButton**<br>since 0.0.0 | The primary submit of a form: `type="submit"`, full width by default (`fullWidth={false}` inline), shows `pendingText` while the form's `useFormStatus` is pending. | The button is not a form submit or you need a secondary action next to the submit (`Button`). | `<button type="submit">`, `<input type="submit">` | [Button](#actions), [Field](#forms) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/submit-button.stories.tsx) |
+| **Pressable** (experimental)<br>since 1.35.0 | 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. | A visible button is meant (`Button`) or the region contains its own interactive controls (use `Card variant="interactive"` with an explicit action). | `<div onClick>`, `<span role="button">`, `<li onClick>` | [Button](#actions), [Card](#layout) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/pressable.stories.tsx) |
+| **CopyButton**<br>since 0.0.0 | Copy a value to the clipboard with check-mark feedback (ids, codes, links). | The copy needs a confirmation toast or copies rich content — compose `IconButton` + `useToast`. | `navigator.clipboard.writeText + useState` | [IconButton](#actions), [ToastProvider](#feedback) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/copy-button.stories.tsx) |
+| **ConfirmActionButton**<br>since 0.3.0 | A destructive or irreversible action that needs a confirmation step: wraps `AlertDialog` around any trigger and retires `window.confirm()`. | The confirmation needs a form or custom body (`AlertDialog` composed directly) or the action is reversible (act, then offer undo in a toast). | `window.confirm()`, `useState + AlertDialog boilerplate` | [AlertDialog](#overlays), [DangerAction](#actions) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/confirm-action-button.stories.tsx) |
+| **Intent actions**<br>parts: `SecondaryAction`, `DangerAction`, `LinkAction`, `IconAction`<br>since 0.3.0 | Intent-named `Button` wrappers for product code that reads by role: primary, secondary, danger, link-styled, icon-only. | You need the full variant × intent matrix or a size outside the defaults (`Button`, `IconButton`). | — | [Button](#actions), [IconButton](#actions), [LinkButton](#actions) | [story](https://github.com/Assure-One/design-system/blob/main/src/composites/intent-actions.stories.tsx) |
+| **BulkActionBar**<br>parts: `BulkActionBarAction`, `BulkActionBarSeparator`<br>since 0.15.0 | A floating bar that appears when rows are selected: selection count, actions, separators, clear. | Actions apply to one record (row menu via `DropdownMenu`) or belong to the page (`PageHeader` actions). | — | [DataTable](#data-display), [StickyActionBar](#actions) | [story](https://github.com/Assure-One/design-system/blob/main/src/composites/bulk-action-bar.stories.tsx) |
+| **StickyActionBar**<br>since 1.3.0 | Save / Cancel that stays visible at the bottom of a long form or settings page, with an optional hint and mobile-nav offset. | The form fits the viewport (put the `SubmitButton` at the end) or the actions belong to a dialog (`DialogFooter`). | `<div class="sticky bottom-0">` | [SubmitButton](#actions), [BulkActionBar](#actions) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/sticky-action-bar.stories.tsx) |
+| **NewMenu**<br>since 1.2.0 | The "+ New" creation menu of an app: grouped actions with icons and shortcuts on a `DropdownMenu`. | The menu is contextual to one record (`DropdownMenu`) or has a single action (`Button`). | — | [DropdownMenu](#overlays), [AppHeader](#shell-screens) | [story](https://github.com/Assure-One/design-system/blob/main/src/composites/new-menu.stories.tsx) |
+| **DisplayMenu**<br>since 1.25.0 | The Linear-style Display control of a list surface: filters, grouping, ordering and column visibility in one searchable menu, driven by a `sections` array. | There is one filter (`FilterChip`) or one multi-value filter (`MultiFilterPill`). | — | [Toolbar](#actions), [MultiFilterPill](#selection), [DataTableView](#data-display) | [story](https://github.com/Assure-One/design-system/blob/main/src/composites/display-menu.stories.tsx) |
+| **Toolbar**<br>parts: `FilterChip`<br>also: `filterChipVariants`<br>since 0.3.0 | 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. | The controls belong to a table card (`DataTableToolbar`) or the filter is multi-value (`MultiFilterPill`). | `<div class="flex items-center gap-2"> above a list` | [MultiFilterPill](#selection), [DisplayMenu](#actions), [DataTable](#data-display) | [story](https://github.com/Assure-One/design-system/blob/main/src/composites/toolbar.stories.tsx) |
+| **SuggestionPills**<br>since 1.5.0 | A strip of AI quick-reply pills floated above a composer; renders nothing when empty and not loading, so mount it unconditionally. | The choices are a form value (`MultiSelectField`) or filters (`FilterChip`). | — | [MessageComposer](#forms), [AiDraftCard](#feedback) | [story](https://github.com/Assure-One/design-system/blob/main/src/composites/suggestion-pills.stories.tsx) |
+
+## 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.
+
+| Component | Use when | Don't use when | Replaces raw HTML | Related | Links |
+| --- | --- | --- | --- | --- | --- |
+| **Field** (experimental)<br>parts: `FieldDescription`, `FieldError`<br>since unreleased | Every form control: owns ids, states and ARIA wiring for one control and its `Label`, `FieldDescription` and `FieldError`; design-system controls bind automatically. | Grouping several controls (`Fieldset`) or wiring a control the design system does not ship (`FieldControl`). | `<label for> + <input id> + <p id> aria-describedby`, `<p class="text-red-500">` | [Label](#forms), [Fieldset](#forms), [FieldControl](#forms), [useFieldControl](#hooks-utilities) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/field/field.stories.tsx) · [docs](https://github.com/Assure-One/design-system/blob/main/docs/forms.md) · [docs](https://github.com/Assure-One/design-system/blob/main/docs/adr/006-field-native-form-participation.md) |
+| **FieldControl** (experimental)<br>since unreleased | 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. | The control is a design-system component — it already calls `useFieldControl`. | — | [Field](#forms), [useFieldControl](#hooks-utilities) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/field/field-control.stories.tsx) |
+| **Fieldset** (experimental)<br>parts: `FieldsetLegend`<br>since unreleased | 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. | There is a single control (`Field`) or the grouping is only visual (`Section`, `Card`). | `<fieldset>`, `<legend>`, `<div role="group">` | [Field](#forms), [RadioGroup](#forms), [FormSection](#forms) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/field/fieldset.stories.tsx) |
+| **Label**<br>also: `labelVariants`<br>since 0.0.0 | The visible name of a control, inside a `Field` (binds automatically) or with an explicit `htmlFor`. | The text is not a control's name (`Text`) or a heading (`Heading`). | `<label>` | [Field](#forms), [Input](#forms) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/label.stories.tsx) |
+| **Input**<br>also: `inputVariants`<br>since 0.0.0 | 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. | Multi-line (`Textarea`), numbers (`NumberInput`), search (`SearchInput`), phone (`PhoneField`), codes (`OTPInput`), dates (`DatePicker`), files with drop zone (`FileUpload`). | `<input>`, `<input type="text">`, `<input type="email">`, `<input type="password">` | [Field](#forms), [Textarea](#forms), [NumberInput](#forms), [SearchInput](#forms) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/input.stories.tsx) · [docs](https://github.com/Assure-One/design-system/blob/main/docs/design-system/control-sizes.md) |
+| **Textarea**<br>also: `textareaVariants`<br>since 0.0.0 | Multi-line free text with the Input chrome, sizes, invalid state and Field binding. | Rich text (bring your editor inside `FieldControl` or `MessageComposer`) or a single line (`Input`). | `<textarea>` | [Input](#forms), [Field](#forms), [MessageComposer](#forms) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/textarea.stories.tsx) |
+| **NumberInput** (experimental)<br>since unreleased | A `number \| null` value with locale formatting, min/max/step, optional stepper buttons and a text fallback while typing. | Money entered as text with a mask (`Input` + your formatter) or a bounded visual value (`Slider`). | `<input type="number">` | [Input](#forms), [Slider](#forms) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/number-input.stories.tsx) |
+| **SearchInput**<br>also: `searchInputVariants`<br>since 0.0.0 | A search box: search icon, clear affordance, `size`, debounced `onValueChange`. | The search filters a dropdown's options (`Combobox`) or the whole app (`CommandPalette`). | `<input type="search">` | [Input](#forms), [Combobox](#selection), [DataTable](#data-display) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/search-input.stories.tsx) |
+| **OTPInput**<br>since 0.0.0 | A one-time code split into cells: paste handling, auto-advance, one hidden form value, named by the surrounding `Label`. | A plain numeric field (`NumberInput`) or a password (`Input type="password"`). | `six <input maxlength="1">` | [Input](#forms), [Field](#forms) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/otp-input.stories.tsx) |
+| **PhoneField** (experimental)<br>also: `DEFAULT_PHONE_FIELD_MESSAGES`<br>since unreleased | 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. | The value is not a phone number (`Input type="tel"` is never right either — an extension or a PIN is an `Input`/`OTPInput`). | `<input type="tel">`, `<select> of dial codes + <input type="tel">` | [Combobox](#selection), [Field](#forms), [PhoneInput](#forms), [PhoneCountryInput](#forms) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/phone-field.stories.tsx) |
+| **PhoneInput** (deprecated)<br>since 0.0.0 | Only in code that already uses it: US-only phone formatting on the `Input` chrome. | New code — `PhoneField` (deprecated, removed in 3.0). | — | [PhoneField](#forms), [Input](#forms) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/phone-input.stories.tsx) |
+| **PhoneCountryInput** (deprecated)<br>parts: `CountrySelect` (deprecated), `CountryFlag` (deprecated)<br>since 1.1.0 | Only in code that already uses it: the pre-PhoneField country `Select` + `tel` input pair; `parsePhoneForEditing` seeds it from a stored E.164 string. | New code — `PhoneField` (its country picker is a `Combobox`; deprecated, removed in 3.0). | — | [PhoneField](#forms), [COUNTRY_CODES](#hooks-utilities) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/phone-country-input.stories.tsx) |
+| **FileUpload**<br>since 0.0.0 | Pick or drop files: accept/multiple/max size, file list with remove, keyboard-focusable input, Field binding. | The upload belongs to a client document request (`DocumentRequestUpload`) or you only show already-uploaded files (`AttachmentChip`, `FileChip`). | `<input type="file">`, `drop-zone div with onDrop` | [DocumentRequestUpload](#forms), [AttachmentChip](#data-display), [FileTypeBadge](#data-display) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/file-upload.stories.tsx) |
+| **DatePicker**<br>since 0.0.0 | 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. | A range (`DateRangePicker`) or an always-visible calendar (`Calendar`). | `<input type="date">` | [DateRangePicker](#forms), [Calendar](#forms), [isoToDisplay](#hooks-utilities) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/date-picker.stories.tsx) |
+| **DateRangePicker**<br>since 0.11.0 | A from/to pair in one control; posts `${name}_from` / `${name}_to`. | A single date (`DatePicker`) or two independent dates in a form (two `DatePicker`s in a `Fieldset`). | `two <input type="date">` | [DatePicker](#forms), [Calendar](#forms) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/date-range-picker.stories.tsx) |
+| **Calendar**<br>since 0.0.0 | An inline month grid (react-day-picker) for choosing a day or range without a popover. | The date belongs in a form field (`DatePicker`, `DateRangePicker`). | — | [DatePicker](#forms), [DateRangePicker](#forms) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/calendar.stories.tsx) |
+| **Checkbox**<br>since 0.0.0 | A boolean or one of several independent choices; `checked` accepts `"indeterminate"` for select-all; native form participation. | The change applies immediately as a setting (`Switch`) or the choices are exclusive (`RadioGroup`). | `<input type="checkbox">` | [Switch](#forms), [RadioGroup](#forms), [DataTable](#data-display) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/checkbox.stories.tsx) |
+| **RadioGroup**<br>parts: `RadioGroupItem`<br>since 0.0.0 | Exclusive choice among a few visible options in a form; wrap in `Fieldset` for the legend. | More than about six options (`Select`) or an immediate view switch (`ToggleGroup`). | `<input type="radio">` | [Fieldset](#forms), [ToggleGroup](#selection), [Select](#selection) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/radio-group.stories.tsx) |
+| **Switch**<br>since 0.0.0 | An on/off setting that takes effect immediately. | The value is submitted with the form (`Checkbox`). | `<input type="checkbox" role="switch">` | [Checkbox](#forms) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/switch.stories.tsx) |
+| **Slider**<br>since 0.0.0 | A bounded numeric value chosen by dragging (one or two thumbs). | Exact numbers matter (`NumberInput`). | `<input type="range">` | [NumberInput](#forms) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/slider.stories.tsx) |
+| **MultiSelectField**<br>since 0.0.0 | A visible row of pill buttons that toggle membership in a comma-separated value: a handful of options everyone should see. | Many options or search (`MultiSelect`), or the pills are filters rather than a form value (`FilterChip`). | `<input type="checkbox"> styled as pills` | [MultiSelect](#selection), [ToggleGroup](#selection), [Chip](#selection) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/multi-select-field.stories.tsx) |
+| **Grid**<br>since 1.20.0 | A matrix of typed cells (rows × columns of text, number, select, checkbox) edited as one controlled value with an accessible name per cell. | Read-only data (`Table`, `DataTable`) or a single column of fields (`Stack` of `Field`s). | `<table> of <input>s` | [Table](#data-display), [Questions](#forms) | [story](https://github.com/Assure-One/design-system/blob/main/src/composites/grid.stories.tsx) |
+| **Questions**<br>since 1.17.0 | One questionnaire question card: index, title, description, type, required flag, `chrome` card or plain. | You are laying out the whole questionnaire (`QuestionnairePanel`) or a plain form field (`Field`). | — | [QuestionnairePanel](#forms), [Field](#forms) | [story](https://github.com/Assure-One/design-system/blob/main/src/composites/questions.stories.tsx) |
+| **QuestionnairePanel**<br>since 1.17.0 | The questionnaire container of the client portal: `cards` or `navigation` variant with eyebrow and title. | A settings form (`Fieldset` inside `Card`). | — | [Questions](#forms), [Fieldset](#forms) | [story](https://github.com/Assure-One/design-system/blob/main/src/composites/questionnaire-panel.stories.tsx) |
+| **MessageComposer**<br>since 0.14.0 | The chat input of a thread: one card chrome, optional quick-reply chips, your editor as `children`, a footer with a built-in Send. | A plain multi-line field (`Textarea`) or an email signature editor (`SignatureEditor`). | — | [Textarea](#forms), [SuggestionPills](#actions), [AiDraftCard](#feedback), [MessageBubble](#data-display) | [story](https://github.com/Assure-One/design-system/blob/main/src/composites/message-composer.stories.tsx) |
+| **SignatureEditor**<br>since 1.5.0 | 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. | Capturing a drawn e-signature (`ProposalSignatureBlock`). | — | [MessageComposer](#forms), [Popover](#overlays) | [story](https://github.com/Assure-One/design-system/blob/main/src/composites/signature-editor.stories.tsx) |
+| **DocumentRequestField**<br>since 1.4.0 | One row of a document request form: a slot for your document-type select plus description and required toggle. | A generic form field (`Field`). | — | [DocumentRequestDetail](#data-display), [Field](#forms), [Select](#selection) | [story](https://github.com/Assure-One/design-system/blob/main/src/composites/document-request-field.stories.tsx) |
+| **DocumentRequestUpload**<br>since 1.20.0 | The client-portal upload for a requested document: drop zone, progress and states tied to the request. | A generic file field (`FileUpload`). | — | [FileUpload](#forms), [DocumentChecklist](#data-display), [DocumentRequestDetail](#data-display) | [story](https://github.com/Assure-One/design-system/blob/main/src/composites/document-request-upload.stories.tsx) |
+| **Proposal signing**<br>parts: `ProposalConsentGate`, `ProposalPaymentCapture`<br>since 1.12.0 | The signing step of a proposal: consent gate, signature capture, payment capture. | An email signature (`SignatureEditor`). | — | [AgreementViewer](#shell-screens), [ProposalPackageCard](#data-display) | [story](https://github.com/Assure-One/design-system/blob/main/src/composites/proposal-signing.stories.tsx) |
+| **FormSection** (deprecated)<br>since 0.4.1 | Only in code that already uses it: a titled `<fieldset>` block of a settings form with description and trailing action. | New code — use `Fieldset` + `FieldsetLegend` (deprecated, removed in 3.0). | — | [Fieldset](#forms), [Field](#forms) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/form-section.stories.tsx) |
+| **FormError / FormSuccess** (deprecated)<br>parts: `FormSuccess` (deprecated)<br>since 0.0.0 | Only in code that already uses them: the pre-Field inline error and success messages (contract C-FORM-MSG). | New code — `FieldError` and `FieldDescription` inside a `Field`, or a toast for a saved form (deprecated, removed in 3.0). | — | [Field](#forms), [ToastProvider](#feedback) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/form-message.stories.tsx) |
+
+## Selection
+
+Pick one or many from a set: dropdowns, comboboxes, toggle groups, chips and filters.
+
+| Component | Use when | Don't use when | Replaces raw HTML | Related | Links |
+| --- | --- | --- | --- | --- | --- |
+| **Select**<br>parts: `SelectRoot`, `SelectTrigger`, `SelectValue`, `SelectContent`, `SelectItem`, `SelectGroup`, `SelectLabel`, `SelectSeparator`, `SelectScrollUpButton`, `SelectScrollDownButton`<br>since 0.0.0 | 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. | 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`). | `<select>`, `<option>` | [Combobox](#selection), [MultiSelect](#selection), [ClientSelect](#selection), [TeamMemberSelect](#selection) | — |
+| **Combobox** (experimental)<br>also: `DEFAULT_COMBOBOX_MESSAGES`<br>since unreleased | A searchable pick: one input, a portalled listbox, the `Option<T>` model (`{ value, label }`), async loading and empty messages, single or `multiple`. | A short static list (`Select`) or free text with suggestions that need not match (`Input` + `Popover`). | `<input list> + <datalist>`, `<select> with a search box` | [Select](#selection), [MultiSelect](#selection), [SearchSelect](#selection) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/combobox.stories.tsx) |
+| **MultiSelect** (experimental)<br>since unreleased | Several of many options with search: `Combobox` in `multiple` mode with selected chips. | A handful of options that should all be visible (`MultiSelectField`) or one value (`Combobox`, `Select`). | `<select multiple>` | [Combobox](#selection), [MultiSelectField](#forms), [Chip](#selection) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/multi-select.stories.tsx) |
+| **SearchSelect** (deprecated)<br>since 0.0.0 | Only in code that already uses it: the pre-Combobox searchable select with `{ id, label }` options (contract C-SEARCHSELECT). | New code — `Combobox` with `Option` (deprecated, removed in 3.0; CM-08 rewrites single-mode call sites). | — | [Combobox](#selection), [MultiSelect](#selection) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/search-select.stories.tsx) |
+| **ClientSelect**<br>since 0.0.0 | Pick one client: avatar, name and email rows on the `Select` primitive, long names truncated. | Searching thousands of clients (`Combobox` with async options) or any other entity (`Select`). | — | [Select](#selection), [TeamMemberSelect](#selection), [Combobox](#selection) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/client-select.stories.tsx) |
+| **TeamMemberSelect**<br>since 0.0.0 | Pick an assignee: avatar and name rows on the `Select` primitive, with an unassigned option. | Several assignees (`MultiSelect`) or any other entity (`Select`). | — | [Select](#selection), [ClientSelect](#selection), [DataTableView](#data-display) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/team-member-select.stories.tsx) |
+| **ToggleGroup**<br>parts: `ToggleGroupItem`<br>since 0.0.0 | A view or mode switch with immediate effect (list/grid, day/week), single or multiple, roving focus. | The choice is a form value (`RadioGroup`, `MultiSelectField`) or navigation between panels (`Tabs`). | `group of <button aria-pressed>` | [Tabs](#navigation), [RadioGroup](#forms), [DocumentSourceFilter](#selection) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/toggle-group.stories.tsx) |
+| **Chip** (experimental)<br>also: `chipVariants`, `resolveChipStyle`<br>since 1.35.0 | A removable, toggleable or clickable token: applied filters, tags, selected values; `variant` × `intent` × `size`, `onRemove`, `pressed`. | A static label (`Badge`), a status (`StatusBadge`) or a file (`FileChip`, `AttachmentChip`). | `<span class="rounded-full …"><button>×</button></span>` | [DismissibleChip](#selection), [Badge](#data-display), [Toolbar](#actions), [MultiSelect](#selection) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/chip.stories.tsx) |
+| **DismissibleChip**<br>since 0.4.0 | Only in code that already uses it: a label with a remove button. | New code — `Chip` with `onRemove` covers it with the shared variants and sizes. | — | [Chip](#selection) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/dismissible-chip.stories.tsx) |
+| **MultiFilterPill**<br>since 0.0.0 | A toolbar filter with a multi-select dropdown and a count of applied values. | A single-value filter (`FilterChip`) or the full display menu (`DisplayMenu`). | — | [Toolbar](#actions), [DisplayMenu](#actions), [MultiSelect](#selection) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/multi-filter-pill.stories.tsx) |
+| **DocumentSourceFilter**<br>since 1.12.0 | Scope a document list to a provenance bucket (all, uploaded, emailed, …) with counts: a `ToggleGroup` that reuses `DocumentSourceTag`'s glyphs. | Any other segmented filter (`ToggleGroup`). | — | [ToggleGroup](#selection), [DocumentSourceTag](#data-display), [DocumentDetailPanel](#data-display) | [story](https://github.com/Assure-One/design-system/blob/main/src/composites/document-source-filter.stories.tsx) |
+
+## Feedback
+
+Tell the user what is happening: status messages, progress, loading and empty states.
+
+| Component | Use when | Don't use when | Replaces raw HTML | Related | Links |
+| --- | --- | --- | --- | --- | --- |
+| **Alert**<br>parts: `AlertTitle`, `AlertDescription`<br>also: `alertVariants`<br>since 0.0.0 | An inline banner in the page flow: success, warning, danger or info, with title, description and optional action. | Feedback after an action that should disappear (`ToastProvider`), a per-field error (`FieldError`) or a blocking message (`AlertDialog`). | `<div role="alert">`, `coloured bordered div` | [ToastProvider](#feedback), [Field](#forms), [AlertDialog](#overlays) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/alert.stories.tsx) |
+| **ToastProvider**<br>also: `useToast`<br>since 0.0.0 | Transient notifications after an action: mount `ToastProvider` once, call `useToast()` anywhere below; `/testing` ships `createToastRecorder`. | The message must stay until read (`Alert`) or is tied to a field (`FieldError`). | `alert()`, `hand-rolled toast portal` | [Alert](#feedback), [CopyButton](#actions) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/toast.stories.tsx) |
+| **Spinner**<br>also: `spinnerVariants`, `SPINNER_TONE_TO_INTENT`<br>since 0.15.0 | Indeterminate activity in a small area or inside a control; inherits `currentColor` unless an `intent` is set. | Loading content with a known shape (`Skeleton`, `LoadingRows`) or a button's own pending state (`Button loading`). | `animate-spin svg` | [Skeleton](#feedback), [LoadingRows](#feedback), [ProgressBar](#feedback) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/spinner.stories.tsx) |
+| **Skeleton**<br>parts: `SkeletonText`, `SkeletonCircle`<br>since 0.0.0 | A placeholder in the shape of the content that is loading: block, text lines, circle. | Rows of a list or table (`LoadingRows`) or an operation with no layout to reserve (`Spinner`). | `<div class="animate-pulse bg-…">` | [LoadingRows](#feedback), [Spinner](#feedback) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/skeleton.stories.tsx) |
+| **LoadingRows**<br>since 0.4.1 | N uniform skeleton rows while a list or table loads. | A single shape (`Skeleton`). | `Array.from({ length }).map(<Skeleton/>)` | [Skeleton](#feedback), [DataTable](#data-display) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/loading-rows.stories.tsx) |
+| **ProgressBar**<br>also: `progressBarVariants`, `PROGRESS_LEGACY_TO_INTENT`<br>since 0.0.0 | A determinate (or indeterminate) horizontal meter; `intent` sets the colour, otherwise it follows the value. | A compact circular meter (`ProgressRing`), discrete steps (`SegmentedProgress`, `Stepper`) or the suite's percent readout (`SuiteProgress`). | `<progress>`, `nested div with width:%` | [ProgressRing](#feedback), [SegmentedProgress](#feedback), [SuiteProgress](#feedback) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/progress-bar.stories.tsx) |
+| **ProgressRing**<br>also: `progressRingVariants`<br>since 0.0.0 | A circular meter for a card or tile, with the same `intent` and value-driven colour rule as `ProgressBar`. | A wide layout (`ProgressBar`) or a donut of several series (`DonutChart`). | — | [ProgressBar](#feedback), [DonutChart](#media) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/progress-ring.stories.tsx) |
+| **SegmentedProgress**<br>since 1.2.0 | Progress through a known number of steps as filled segments (onboarding, checklists). | The steps have names (`Stepper`) or the value is continuous (`ProgressBar`). | — | [Stepper](#navigation), [ProgressBar](#feedback), [SuiteProgress](#feedback) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/segmented-progress.stories.tsx) |
+| **SuiteProgress**<br>also: `suiteProgressFillVariants`<br>since 1.34.0 | The suite's discrete segmented meter with a percent readout, tinted per product or `intent`. | A generic segmented meter (`SegmentedProgress`) or a continuous one (`ProgressBar`). | — | [SegmentedProgress](#feedback), [ProgressBar](#feedback) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/suite-progress.stories.tsx) |
+| **EmptyState**<br>since 0.0.0 | A list or panel has nothing to show: icon, title, description and one action. | The feature does not exist yet (`ComingSoon`) or content is loading (`Skeleton`). | `centred div with an icon and grey text` | [ComingSoon](#feedback), [LoadingRows](#feedback) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/empty-state.stories.tsx) |
+| **ComingSoon**<br>since 0.0.0 | A placeholder for a feature that is not available yet: icon, title, description and a feature list. | The feature exists but has no data (`EmptyState`). | — | [EmptyState](#feedback) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/coming-soon.stories.tsx) |
+| **AttentionItem**<br>since 1.2.0 | One row of an attention queue: icon, title, description, service tone and trailing action. | A notification (`NotificationPanel` items) or an activity event (`ActivityList` items). | — | [NotificationPanel](#data-display), [ActivityList](#data-display), [KpiCard](#data-display) | [story](https://github.com/Assure-One/design-system/blob/main/src/composites/attention-item.stories.tsx) |
+| **MissingDocumentsPanel**<br>since 1.4.0 | The firm-side panel listing documents a client has not provided, with a Request action. | The client-side checklist (`DocumentChecklist`). | — | [DocumentChecklist](#data-display), [DocumentRequestDetail](#data-display) | [story](https://github.com/Assure-One/design-system/blob/main/src/composites/missing-documents-panel.stories.tsx) |
+| **AiDraftCard**<br>since 1.5.0 | Present an AI-generated draft inside a composer: one `state` prop drives loading, refining, error and ready (collapsible); you pass the body and actions. | A human message (`MessageBubble`) or AI quick replies (`SuggestionPills`). | — | [MessageComposer](#forms), [SuggestionPills](#actions), [AIReceiptPanel](#feedback) | [story](https://github.com/Assure-One/design-system/blob/main/src/composites/ai-draft-card.stories.tsx) |
+| **AIReceiptPanel**<br>since 1.2.0 | The receipt-reading panel: idle, reading and done states with the extracted result and an Attach action. | A generic upload (`FileUpload`) or a draft message (`AiDraftCard`). | — | [AiDraftCard](#feedback), [FileUpload](#forms) | [story](https://github.com/Assure-One/design-system/blob/main/src/composites/ai-receipt-panel.stories.tsx) |
+
+## Overlays
+
+Layers above the page: dialogs, sheets, menus, popovers and tooltips. All portal, trap or manage focus, close on Escape and respect reduced motion.
+
+| Component | Use when | Don't use when | Replaces raw HTML | Related | Links |
+| --- | --- | --- | --- | --- | --- |
+| **Dialog**<br>parts: `DialogTrigger`, `DialogPortal`, `DialogOverlay`, `DialogContent`, `DialogHeader`, `DialogTitle`, `DialogDescription`, `DialogBody`, `DialogFooter`, `DialogClose`<br>since 0.0.0 | 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. | A confirmation that must be answered (`AlertDialog`), a side panel (`Sheet`), a mobile-friendly modal (`ResponsiveDialog`) or non-modal content (`Popover`). | `<dialog>`, `fixed inset-0 div` | [AlertDialog](#overlays), [Sheet](#overlays), [ResponsiveDialog](#overlays), [CommandPalette](#overlays) | [docs](https://github.com/Assure-One/design-system/blob/main/docs/adr/012-overlay-presence-motion.md) |
+| **AlertDialog**<br>parts: `AlertDialogTrigger`, `AlertDialogPortal`, `AlertDialogOverlay`, `AlertDialogContent`, `AlertDialogHeader`, `AlertDialogTitle`, `AlertDialogDescription`, `AlertDialogFooter`, `AlertDialogAction`, `AlertDialogCancel`<br>since 0.0.0 | A decision the user must make before continuing (delete, discard): no outside-click dismiss, explicit Action and Cancel. | A dismissible task (`Dialog`) or a one-line confirm around a trigger (`ConfirmActionButton`). | `window.confirm()` | [Dialog](#overlays), [ConfirmActionButton](#actions) | — |
+| **Sheet**<br>parts: `SheetTrigger`, `SheetPortal`, `SheetOverlay`, `SheetContent`, `SheetHeader`, `SheetTitle`, `SheetDescription`, `SheetBody`, `SheetFooter`, `SheetClose`<br>since 0.0.0 | 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. | Centred content (`Dialog`) or a persistent split view (`MasterDetailLayout`). | `fixed right-0 h-full div` | [SideDrawer](#overlays), [Dialog](#overlays), [ResponsiveDialog](#overlays) | — |
+| **SideDrawer**<br>since 0.0.0 | Only in code that already uses it: the earlier slide-in panel API (`open`, `onClose`, `title`, `width`). | New code — `Sheet` has the same behaviour with composable parts. | — | [Sheet](#overlays) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/side-drawer.stories.tsx) |
+| **ResponsiveDialog**<br>since 1.3.0 | A modal that should be a `Dialog` on desktop and a bottom `Sheet` below the `sm` breakpoint, decided after mount. | The presentation must be fixed (`Dialog`, `Sheet`). | — | [Dialog](#overlays), [Sheet](#overlays) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/responsive-dialog.stories.tsx) |
+| **Popover**<br>parts: `PopoverTrigger`, `PopoverAnchor`, `PopoverPortal`, `PopoverContent`, `PopoverClose`<br>since 0.0.0 | Interactive content anchored to a trigger: a small form, a picker, a filter panel. | A short non-interactive label (`Tooltip`), a preview on hover (`HoverCard`) or a list of actions (`DropdownMenu`). | `absolute-positioned div toggled by state` | [Tooltip](#overlays), [HoverCard](#overlays), [DropdownMenu](#overlays) | — |
+| **HoverCard**<br>parts: `HoverCardTrigger`, `HoverCardPortal`, `HoverCardContent`<br>since 0.0.0 | A rich preview when hovering a link or name (a person card, a record summary), for sighted pointer users. | The content is essential (it is hover-only) or interactive (`Popover`). | — | [Popover](#overlays), [Tooltip](#overlays) | — |
+| **Tooltip**<br>parts: `TooltipProvider`, `TooltipTrigger`, `TooltipPortal`, `TooltipContent`<br>since 0.0.0 | A short label for a control on hover and focus; the sealed `Tooltip` takes `content`, the parts compose. | The text is essential to use the control (make it visible) or interactive (`Popover`). | `title="…"` | [IconButton](#actions), [Popover](#overlays), [Kbd](#typography) | — |
+| **DropdownMenu**<br>parts: `DropdownMenuTrigger`, `DropdownMenuPortal`, `DropdownMenuContent`, `DropdownMenuItem`, `DropdownMenuCheckboxItem`, `DropdownMenuRadioGroup`, `DropdownMenuRadioItem`, `DropdownMenuGroup`, `DropdownMenuLabel`, `DropdownMenuSeparator`, `DropdownMenuShortcut`, `DropdownMenuSub`, `DropdownMenuSubTrigger`, `DropdownMenuSubContent`<br>since 0.0.0 | A menu of actions from a button: items, checkbox and radio items, groups, shortcuts, submenus; `/testing` ships `openMenu`. | Choosing a form value (`Select`), right-click (`ContextMenu`) or a form inside (`Popover`). | `<ul> shown on click`, `<select> used as a menu` | [ContextMenu](#overlays), [NewMenu](#actions), [Select](#selection), [Popover](#overlays) | — |
+| **ContextMenu**<br>parts: `ContextMenuTrigger`, `ContextMenuPortal`, `ContextMenuContent`, `ContextMenuItem`, `ContextMenuCheckboxItem`, `ContextMenuRadioGroup`, `ContextMenuRadioItem`, `ContextMenuGroup`, `ContextMenuLabel`, `ContextMenuSeparator`, `ContextMenuShortcut`, `ContextMenuSub`, `ContextMenuSubTrigger`, `ContextMenuSubContent`<br>since 0.0.0 | Actions on right-click or long-press over a region, with the same item model as `DropdownMenu`. | The actions must be discoverable (`DropdownMenu` from a visible trigger). | `onContextMenu + positioned div` | [DropdownMenu](#overlays) | — |
+| **CommandPalette**<br>since 0.0.0 | The ⌘K command and search dialog: `cmdk` inside `Dialog`, groups, shortcuts, async results. | Searching one list (`SearchInput`) or picking a form value (`Combobox`). | — | [Dialog](#overlays), [KeyboardShortcutsDialog](#overlays), [Combobox](#selection) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/command-palette.stories.tsx) |
+| **KeyboardShortcutsDialog**<br>since 0.0.0 | The "?" help dialog listing keyboard shortcuts by section; no props shows the universal General section. | Showing one shortcut next to a control (`Kbd`, `KbdHint`). | — | [Kbd](#typography), [CommandPalette](#overlays) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/keyboard-shortcuts-dialog.stories.tsx) |
+
+## Navigation
+
+Move between places: tabs, breadcrumbs, pagination, steppers, trees and rails.
+
+| Component | Use when | Don't use when | Replaces raw HTML | Related | Links |
+| --- | --- | --- | --- | --- | --- |
+| **Tabs**<br>parts: `TabsList`, `TabsTrigger`, `TabsContent`<br>since 0.0.0 | Switch between panels of one page; roving focus, `value`/`onValueChange`. | The switch changes a mode rather than showing another panel (`ToggleGroup`), or it is the mobile app-level bar (`BottomNav`). | `<ul role="tablist">`, `buttons toggling useState panels` | [ToggleGroup](#selection), [ChannelTabs](#navigation), [BottomNav](#navigation) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/tabs.stories.tsx) |
+| **ChannelTabs**<br>since 1.5.0 | Pill tabs switching between communication channels on a thread, each with a toned status dot and unread count; fully controlled. | Generic panels (`Tabs`). | — | [Tabs](#navigation), [StatusDot](#data-display), [MessageBubble](#data-display) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/channel-tabs.stories.tsx) |
+| **Breadcrumb**<br>parts: `BreadcrumbList`, `BreadcrumbItem`, `BreadcrumbLink`, `BreadcrumbPage`, `BreadcrumbSeparator`<br>since 0.0.0 | The path to the current page; `BreadcrumbPage` marks the current one, `BreadcrumbLink asChild` wraps your router link. | The page title itself (`PageHeader`) or the app-level bar (`AppHeaderBreadcrumb` inside `AppHeader`). | `<nav aria-label="breadcrumb"><ol>` | [PageHeader](#layout), [AppHeader](#shell-screens) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/breadcrumb.stories.tsx) |
+| **Pagination**<br>since 0.0.0 | Page controls for a paged list: current/total pages, sibling count, optional total items. | Inside a `DataTable` (`DataTablePagination`) or infinite scroll. | `<nav> of page number buttons` | [DataTable](#data-display), [DataTableView](#data-display) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/pagination.stories.tsx) |
+| **Stepper**<br>since 0.0.0 | Named steps of a multi-step flow, horizontal or vertical, with the current step marked. | Unnamed progress (`SegmentedProgress`) or a timeline of past events (`EngagementTimeline`). | — | [SegmentedProgress](#feedback), [EngagementTimeline](#data-display) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/stepper.stories.tsx) |
+| **BottomNav**<br>since 1.2.0 | The mobile tab bar at the bottom of the app: tabs with icons and badges, controlled `value`. | Desktop navigation (`Sidebar`) or in-page panels (`Tabs`). | — | [Sidebar](#shell-screens), [Tabs](#navigation), [StickyActionBar](#actions) | [story](https://github.com/Assure-One/design-system/blob/main/src/composites/bottom-nav.stories.tsx) |
+| **FolderTree**<br>since 1.2.0 | A collapsible tree of folders with an active node, default-open ids and selection callback. | A flat list (`ClientRailItem`) or a file list (`DocumentList`). | — | [DocumentsWorkspaceLayout](#layout), [ClientRailItem](#navigation), [Collapsible](#layout) | [story](https://github.com/Assure-One/design-system/blob/main/src/composites/folder-tree.stories.tsx) |
+| **ClientRailItem**<br>parts: `ClientRailGroupHeader`<br>since 1.4.0 | One client row in the Documents left rail (avatar, name, counts) plus the section label above a group. | Picking a client in a form (`ClientSelect`) or the main navigation (`SidebarLink`). | — | [DocumentsWorkspaceLayout](#layout), [ClientSelect](#selection), [Sidebar](#shell-screens) | [story](https://github.com/Assure-One/design-system/blob/main/src/composites/client-rail-item.stories.tsx) |
+
+## Layout
+
+Arrange content: stacks, surfaces, cards, separators, section and page framing.
+
+| Component | Use when | Don't use when | Replaces raw HTML | Related | Links |
+| --- | --- | --- | --- | --- | --- |
+| **Stack** (experimental)<br>since 1.33.0 | A vertical (or `direction="row"`) flex container that owns the gap between its children with tokenised `gap` and alignment. | A wrapping horizontal row (`Inline`) or a bordered box (`Surface`). | `<div class="flex flex-col gap-4">` | [Inline](#layout), [Surface](#layout) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/layout/stack.stories.tsx) |
+| **Inline** (experimental)<br>since 1.33.0 | A horizontal wrapping row with children centred on the baseline and a tokenised gap: a row of chips, a button row, meta items. | A column (`Stack`) or a toolbar of controls that must share one control size (`Toolbar`). | `<div class="flex flex-wrap items-center gap-2">` | [Stack](#layout), [Toolbar](#actions) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/layout/inline.stories.tsx) |
+| **Surface** (experimental)<br>since 1.33.0 | The bordered box content sits on: surface background, 1px rule, radius, `padding` role (none/sm/md/lg). | You need header/title/footer parts or an interactive variant (`Card`). | `<div class="rounded-xl border bg-white p-4">` | [Card](#layout), [Stack](#layout) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/layout/surface.stories.tsx) |
+| **Card**<br>parts: `CardHeader`, `CardTitle`, `CardDescription`, `CardAction`, `CardContent`, `CardFooter`<br>also: `cardVariants`<br>since 0.0.0 | A surface with structure: header, title, description, trailing action, content, footer; `variant` default, interactive (hover border) or flat (nested). | A plain box without parts (`Surface`), a KPI tile (`KpiCard`) or a domain card that already exists (`EngagementCard`, `DocumentFileRow`). | `<div class="rounded-xl border shadow">` | [Surface](#layout), [KpiCard](#data-display), [Pressable](#actions) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/card.stories.tsx) |
+| **Separator**<br>since 0.0.0 | A horizontal or vertical rule between groups, decorative or semantic. | The divider carries a category label (`CategoryDivider`) or sits inside a menu (`DropdownMenuSeparator`). | `<hr>`, `<div class="border-t">` | [CategoryDivider](#layout) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/separator.stories.tsx) |
+| **AspectRatio**<br>since 0.0.0 | Reserve a fixed ratio box for an image, video or embed. | The media has intrinsic size (plain `<img>` with width/height). | `padding-top percentage hack` | [PdfPreview](#media) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/aspect-ratio.stories.tsx) |
+| **ScrollArea**<br>parts: `ScrollBar`<br>since 0.0.0 | A scrollable region with styled, consistent scrollbars (panels, menus, side rails). | The document scrolls (leave it to the browser). | `<div class="overflow-auto">` | [Sheet](#overlays), [Sidebar](#shell-screens) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/scroll-area.stories.tsx) |
+| **Collapsible**<br>parts: `CollapsibleTrigger`, `CollapsibleContent`<br>since 0.0.0 | Show/hide one region from a trigger, animated and reduced-motion aware. | Several mutually exclusive sections (`Accordion`). | `<details>/<summary>`, `useState toggle` | [Accordion](#layout), [FolderTree](#navigation) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/collapsible.stories.tsx) |
+| **Accordion**<br>parts: `AccordionItem`, `AccordionTrigger`, `AccordionContent`<br>since 0.0.0 | A list of expandable sections, single or multiple open. | One region (`Collapsible`) or navigation between panels (`Tabs`). | `stack of <details>` | [Collapsible](#layout), [Tabs](#navigation) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/accordion.stories.tsx) |
+| **Section**<br>parts: `SectionHead`<br>since 0.0.0 | A max-width centred content section with the canonical `--content-pad` gutter and a `SectionHead` title row. | The page already sits in `Content` of the `Shell` and needs a page title (`PageHeader`). | `<section class="mx-auto max-w-… px-8">` | [SectionHeader](#layout), [PageHeader](#layout), [Shell](#shell-screens) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/section.stories.tsx) |
+| **SectionHeader**<br>since 0.0.0 | A title + description block for a marketing-style or settings section. | The top of a page (`PageHeader`) or a form group (`FieldsetLegend`). | `<h2> + <p> pair` | [PageHeader](#layout), [Heading](#typography), [Section](#layout) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/section-header.stories.tsx) |
+| **PageHeader**<br>parts: `PageHeaderSpec`, `PageHeaderSep`<br>since 0.3.0 | The top-of-page title block: eyebrow, headline with trailing actions, description and a meta row (`PageHeaderSpec` items separated by `PageHeaderSep`). | The sticky app bar (`AppHeader`) or a section inside the page (`SectionHeader`). | `<div class="flex items-center justify-between"><h1>` | [AppHeader](#shell-screens), [SectionHeader](#layout), [Breadcrumb](#navigation) | [story](https://github.com/Assure-One/design-system/blob/main/src/composites/page-header.stories.tsx) |
+| **CategoryDivider**<br>parts: `CategoryTag`<br>since 1.3.0 | 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. | A plain rule (`Separator`) or a status (`StatusBadge`). | — | [Separator](#layout), [serviceToneStyle](#hooks-utilities) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/category-divider.stories.tsx) |
+| **StickyStack**<br>parts: `StickyStackLayer`, `StickyStackSticky`, `StickyStackSectionHeader`<br>since 1.30.1 | Several fixed layers (app header, toolbar, section headers) that must stack without overlapping: layers are measured and sticky regions consume the offset. | One sticky element (`position: sticky` on it) or a bottom bar (`StickyActionBar`). | `hard-coded top-[56px] sticky offsets` | [AppHeader](#shell-screens), [StickyActionBar](#actions) | [story](https://github.com/Assure-One/design-system/blob/main/src/composites/sticky-stack.stories.tsx) |
+| **Detail layout**<br>parts: `DetailSpine`, `DetailSpineHeader`, `DetailSpineSection`, `DetailSpineStats`, `DetailMain`<br>since 0.3.0 | A record detail page: a sticky 320px spine (identity, key facts, stats) and a scrolling main column for tabs, sections and feeds. | A list with a selected item beside it (`MasterDetailLayout`) or a plain page (`Section`). | `<div class="grid grid-cols-[320px_1fr]">` | [MasterDetailLayout](#layout), [MetadataGrid](#data-display), [Tabs](#navigation) | [story](https://github.com/Assure-One/design-system/blob/main/src/composites/detail.stories.tsx) |
+| **MasterDetailLayout**<br>since 1.3.0 | A list on the left and the selected item's detail on the right, collapsing to one pane on small screens. | A record page with a spine (`DetailGrid`) or the three-pane documents workspace (`DocumentsWorkspaceLayout`). | — | [DetailGrid](#layout), [DocumentsWorkspaceLayout](#layout) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/master-detail-layout.stories.tsx) |
+| **DocumentsWorkspaceLayout**<br>since 1.4.0 | The three-pane documents workspace: clients rail, folder tree and files area as slots. | Two panes (`MasterDetailLayout`). | — | [ClientRailItem](#navigation), [FolderTree](#navigation), [DocumentDetailPanel](#data-display), [MasterDetailLayout](#layout) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/documents-workspace-layout.stories.tsx) |
+| **DashGrid**<br>since 1.2.0 | A dashboard of reorderable widgets in 2–4 columns with the order persisted under `storageKey`. | A static grid of cards (CSS grid of `Card`s). | — | [KpiCard](#data-display), [Card](#layout) | [story](https://github.com/Assure-One/design-system/blob/main/src/composites/dash-grid.stories.tsx) |
+| **RouteTransition**<br>since 1.3.0 | Fade and slide a page panel in when `routeKey` changes; respects reduced motion. | Animating a component's own presence (the overlays already do) or a list (leave static). | — | [Shell](#shell-screens) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/route-transition.stories.tsx) |
+| **VisuallyHidden**<br>since 0.0.0 | Text for assistive technology that must not be seen: the name of an icon-only control you compose yourself, a live-region message. | Hiding from everyone (`hidden`) or an `IconButton` (it names itself). | `class="sr-only"` | [IconButton](#actions) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/visually-hidden.stories.tsx) |
+
+## Typography
+
+Text roles. Use these instead of bare `<h*>`, `<p>`, `<code>` and `<kbd>` so type scale, colour and letterspacing come from tokens.
+
+| Component | Use when | Don't use when | Replaces raw HTML | Related | Links |
+| --- | --- | --- | --- | --- | --- |
+| **Heading** (experimental)<br>since 1.33.0 | A heading: `level` sets the element (h1–h6), `size` the visual role when it differs; h1 once per screen. | A label for a control (`Label`) or emphasised body text (`Text weight`). | `<h1>`, `<h2>`, `<h3>`, `<h4>` | [Text](#typography), [PageHeader](#layout), [SectionHeader](#layout) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/typography/heading.stories.tsx) · [docs](https://github.com/Assure-One/design-system/blob/main/docs/design-system/typography-roles.md) |
+| **Text** (experimental)<br>since 1.33.0 | Body, caption and label text: `size` is the typography role, `color` the token, `asChild` renders your element (a link, a `<p>`). | A heading (`Heading`), an identifier or snippet (`Code`) or a control's label (`Label`). | `<p>`, `<span class="text-sm text-gray-500">` | [Heading](#typography), [Code](#typography), [Eyebrow](#typography) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/typography/text.stories.tsx) |
+| **Code** (experimental)<br>since 1.33.0 | Monospace text: an identifier, a path, a value, a snippet (inline or block); server-safe. | A keyboard key (`Kbd`) or tabular figures in body text (`Numeric`). | `<code>`, `<pre>` | [Kbd](#typography), [Eyebrow](#typography) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/typography/code.stories.tsx) |
+| **Kbd** (experimental)<br>since 1.33.0 | A keyboard key or shortcut, with platform spelling decided after mount (⌘ vs Ctrl). | A hint next to a control in the intent-atom style (`KbdHint`) or code (`Code`). | `<kbd>` | [Eyebrow](#typography), [KeyboardShortcutsDialog](#overlays) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/typography/kbd.stories.tsx) |
+| **Blockquote**<br>since 0.0.0 | A quoted passage with the design system's rule and spacing. | A callout with an intent (`Alert`). | `<blockquote>` | [Alert](#feedback), [Text](#typography) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/blockquote.stories.tsx) |
+| **Intent atoms**<br>parts: `MutedSpec`, `Numeric`, `KbdHint`<br>since 0.3.0 | 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). | General body text with a chosen role (`Text`) or a heading (`Heading`). | — | [Text](#typography), [Kbd](#typography), [Stat](#typography) | [story](https://github.com/Assure-One/design-system/blob/main/src/composites/intent-atoms.stories.tsx) |
+| **Stat**<br>since 0.0.0 | A large number with a caption in display type. | A dashboard tile with tone, icon and hint (`KpiCard`). | — | [KpiCard](#data-display), [Eyebrow](#typography) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/stat.stories.tsx) |
+
+## Data display
+
+Show records and status: tables, key/value grids, badges, dots, avatars, lists and cards for domain objects.
+
+| Component | Use when | Don't use when | Replaces raw HTML | Related | Links |
+| --- | --- | --- | --- | --- | --- |
+| **StarRating**<br>also: `starRatingVariants`<br>since 0.0.0 | A display-only rating: fractional stars, `max`, sized variants. | Capturing a rating (compose `RadioGroup` or `ToggleGroup` with star icons). | — | [Badge](#data-display), [KpiCard](#data-display) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/star-rating.stories.tsx) |
+| **Table**<br>parts: `TableHeader`, `TableBody`, `TableFooter`, `TableRow`, `TableHead`, `TableCell`, `TableCaption`<br>since 0.0.0 | A bare semantic table with the design system's row, header and caption styling. | A records table with toolbar, sorting and pagination (`DataTable`, `DataTableView`) or an editable matrix (`Grid`). | `<table>`, `<tr>`, `<td>`, `<th>` | [DataTable](#data-display), [DataTableView](#data-display), [MetadataGrid](#data-display) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/table.stories.tsx) |
+| **DataTable**<br>parts: `DataTableToolbar`, `DataTableSearch`, `DataTableSpacer`, `DataTableResultsCount`, `DataTableHead`, `DataTableHeader`, `DataTableBody`, `DataTableRow`, `DataTableCell`, `DataTableCellName`, `DataTableCellMono`, `DataTableCellId`, `DataTableCellDue`, `DataTableCheckbox`, `DataTablePagination`<br>since 0.3.0 | The composable records table: card frame, toolbar with search and count, sortable headers, typed cells (name, mono, id, due), row checkbox, pagination. | A config-driven table is enough (`DataTableView`) or the table is a plain semantic one (`Table`). | `<table> + hand-rolled toolbar and pager` | [DataTableView](#data-display), [Table](#data-display), [BulkActionBar](#actions), [LoadingRows](#feedback) | [story](https://github.com/Assure-One/design-system/blob/main/src/composites/data-table.stories.tsx) |
+| **DataTableView**<br>parts: `StagePill`, `Assignee`, `MoneyCell`, `TagsCell`, `Dash`<br>since 1.6.0 | 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`. | You need custom table composition (`DataTable`). | — | [DataTable](#data-display), [DisplayMenu](#actions), [Toolbar](#actions) | [story](https://github.com/Assure-One/design-system/blob/main/src/composites/data-table-view.stories.tsx) |
+| **MetadataGrid**<br>parts: `DataItem`<br>since 0.4.1 | Label / value pairs on a detail surface as a semantic `<dl>`; `DataItem span={2}` for full-row values. | Tabular records (`Table`) or a stat tile (`KpiCard`). | `<dl>`, `two-column label/value divs` | [DetailGrid](#layout), [Table](#data-display) | [story](https://github.com/Assure-One/design-system/blob/main/src/composites/metadata-grid.stories.tsx) |
+| **KpiCard**<br>parts: `SelectableKpiCard`<br>since 0.4.1 | A single-stat dashboard tile: label, value, optional tone, icon and hint; `SelectableKpiCard` when tiles act as filters. | A number inside running content (`Stat`) or a chart (`DonutChart`). | — | [Stat](#typography), [DashGrid](#layout), [Card](#layout) | [story](https://github.com/Assure-One/design-system/blob/main/src/composites/kpi-card.stories.tsx) |
+| **Badge**<br>also: `badgeVariants`, `resolveBadgeAppearance`<br>since 0.0.0 | A short static label or count: `variant` (solid, soft, outline) × `intent`. | A status with a shared vocabulary (`StatusBadge`), a removable token (`Chip`) or a machine-suggested intent (`IntentBadge`). | `<span class="rounded-full px-2 text-xs">` | [StatusBadge](#data-display), [Chip](#selection), [IntentBadge](#data-display), [StatusDot](#data-display) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/badge.stories.tsx) |
+| **StatusBadge**<br>also: `defineStatusMap`<br>since 1.35.0 | The presentation of a status: soft badge, indicator dot, icon; define the product's statuses once with `defineStatusMap` and spread an entry onto it. | A count or neutral label (`Badge`) or a stage pill inside `DataTableView` (`StagePill`). | — | [Badge](#data-display), [StatusDot](#data-display), [StatusPill](#data-display), [DataTableView](#data-display) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/status-badge.stories.tsx) |
+| **StatusPill**<br>since 1.2.0 | Only in code that already uses it: the fixed-vocabulary pill (`status`, optional dot) for authoritative state. | New code — `StatusBadge` with `defineStatusMap`. | — | [StatusBadge](#data-display), [IntentBadge](#data-display) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/status-pill.stories.tsx) |
+| **IntentBadge**<br>since 1.5.0 | A dashed-outline badge for an AI-classified intent: signals machine-suggested, not yet confirmed. | Authoritative state (`StatusBadge`). | — | [StatusBadge](#data-display), [Badge](#data-display), [AiDraftCard](#feedback) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/intent-badge.stories.tsx) |
+| **StatusDot**<br>also: `statusDotVariants`, `STATUS_DOT_TONE_TO_INTENT`<br>since 1.3.0 | A standalone attention / unread / presence dot on non-avatar surfaces: nav rails, bells, list rows; `intent` colours it. | Next to an avatar (`Avatar` renders its own presence dot) or with a label (`StatusBadge`). | `<span class="h-2 w-2 rounded-full bg-red-500">` | [StatusBadge](#data-display), [Avatar](#data-display), [Sidebar](#shell-screens) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/status-dot.stories.tsx) |
+| **IconTile**<br>also: `iconTileVariants`, `ICON_TILE_TONE_TO_INTENT`<br>since 1.3.0 | The tinted rounded-square icon chip that leads a list row or card: `intent` tints the square and the glyph. | An action (`IconButton`) or a file type (`FileTypeBadge`). | `<div class="grid place-items-center rounded-lg bg-…"><svg/>` | [FileTypeBadge](#data-display), [Avatar](#data-display), [IconButton](#actions) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/icon-tile.stories.tsx) |
+| **Avatar**<br>since 0.0.0 | A person or organisation: image with initials fallback, sizes, optional presence dot. | A file (`FileTypeBadge`) or a product mark (brand icons, `Logo`). | `<img class="rounded-full">` | [StatusDot](#data-display), [DataTableView](#data-display), [TeamMemberSelect](#selection) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/avatar.stories.tsx) |
+| **FileTypeBadge**<br>also: `fileTypeBadgeVariants`, `fileTypeFromName`<br>since 1.3.0 | The coloured format square (PDF, IMG, DOC…) for a file; `fileTypeFromName` derives the type. | A whole file row (`AttachmentChip`, `FileChip`, `DocumentFileRow`). | — | [AttachmentChip](#data-display), [FileChip](#data-display), [IconTile](#data-display) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/file-type-badge.stories.tsx) |
+| **FileChip**<br>since 1.2.0 | A compact file token: name, meta, kind icon, one action. | A full attachment row with view/download (`AttachmentChip`) or a document in the portal (`DocumentFileRow`). | — | [AttachmentChip](#data-display), [FileTypeBadge](#data-display), [Chip](#selection) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/file-chip.stories.tsx) |
+| **AttachmentChip**<br>also: `attachmentChipVariants`<br>since 1.3.0 | A full attachment row: `FileTypeBadge`, truncated name with meta, trailing view/download and your actions; presentational. | A compact token (`FileChip`) or an upload control (`FileUpload`). | — | [FileChip](#data-display), [FileTypeBadge](#data-display), [FileUpload](#forms) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/attachment-chip.stories.tsx) |
+| **DocumentSourceTag**<br>since 1.12.0 | Where a document came from (uploaded, emailed, scanned…): glyph + label tag. | Filtering by source (`DocumentSourceFilter`). | — | [DocumentSourceFilter](#selection), [DocumentDetailPanel](#data-display) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/document-source-tag.stories.tsx) |
+| **ActivityList**<br>parts: `ActivityItem`, `ActivityEventItem`<br>since 0.3.0 | An activity feed: actor/text/target rows (`ActivityItem`) and titled events with a time and coloured dot (`ActivityEventItem`). | Notifications with filters and read state (`NotificationPanel`) or a process timeline (`EngagementTimeline`). | `<ul> of hand-styled feed rows` | [NotificationPanel](#data-display), [EngagementTimeline](#data-display), [AttentionItem](#feedback) | [story](https://github.com/Assure-One/design-system/blob/main/src/composites/activity-list.stories.tsx) |
+| **NotificationPanel**<br>parts: `NotificationPanelHeader`, `NotificationFilter`, `NotificationList`, `NotificationItem`, `NotificationPanelFooter`<br>since 0.7.0 | The notifications flyout: header, filter, list of items with read state, footer actions. | A page-level activity feed (`ActivityList`). | — | [ActivityList](#data-display), [StatusDot](#data-display), [Popover](#overlays) | [story](https://github.com/Assure-One/design-system/blob/main/src/composites/notification-panel.stories.tsx) |
+| **Kanban**<br>parts: `KanbanColumn`, `KanbanCard`<br>since 0.3.0 | A board of columns and cards for stage-based work. | The data is tabular (`DataTableView`). | — | [DataTableView](#data-display) | [story](https://github.com/Assure-One/design-system/blob/main/src/composites/kanban.stories.tsx) |
+| **EngagementCard**<br>since 1.2.0 | The client-portal card for one engagement: service, tone, title, progress and next step. | A generic card (`Card`) or a KPI (`KpiCard`). | — | [EngagementTimeline](#data-display), [Card](#layout), [serviceToneStyle](#hooks-utilities) | [story](https://github.com/Assure-One/design-system/blob/main/src/composites/engagement-card.stories.tsx) |
+| **EngagementTimeline**<br>parts: `EngagementTimelineStep`<br>since 1.2.0 | The steps of an engagement as a toned vertical timeline. | A flow the user navigates (`Stepper`) or an activity feed (`ActivityList`). | — | [EngagementCard](#data-display), [Stepper](#navigation), [ActivityList](#data-display) | [story](https://github.com/Assure-One/design-system/blob/main/src/composites/engagement-timeline.stories.tsx) |
+| **MessageBubble**<br>parts: `MessageBubbleAction`, `MessageBubbleTombstone`<br>since 0.12.0 | One chat message in a thread, inbound or outbound, with hover actions and a tombstone for deleted messages. | An email (`EmailMessageCard`) or an AI draft (`AiDraftCard`). | — | [EmailMessageCard](#data-display), [MessageComposer](#forms), [ChannelTabs](#navigation) | [story](https://github.com/Assure-One/design-system/blob/main/src/composites/message-bubble.stories.tsx) |
+| **EmailMessageCard**<br>since 1.5.0 | An email in a thread as an envelope card (header, readable body, footer) with auto-clamp and show-full toggle; you sanitise the HTML. | A chat message (`MessageBubble`). | — | [MessageBubble](#data-display), [AttachmentChip](#data-display) | [story](https://github.com/Assure-One/design-system/blob/main/src/composites/email-message-card.stories.tsx) |
+| **DocumentChecklist**<br>since 1.21.0 | The client's view of requested documents by lifecycle: awaiting, in review, received, complete. | The firm's missing-documents view (`MissingDocumentsPanel`). | — | [MissingDocumentsPanel](#feedback), [DocumentRequestUpload](#forms) | [story](https://github.com/Assure-One/design-system/blob/main/src/composites/document-checklist.stories.tsx) |
+| **DocumentDetailPanel**<br>parts: `DocumentDetailHeader`, `DocumentDetailTitle`, `DocumentDetailRequester`, `DocumentDetailMetaRow`, `DocumentDetailBody`, `DocumentDetailActions`, `DocumentList`, `DocumentListSection`, `DocumentRow`<br>since 1.8.0 | The document detail side panel and the document list it opens from: header, title, requester, meta, body, actions; `DocumentList` sections of `DocumentRow`s. | A file outside the documents workspace (`AttachmentChip`). | — | [DocumentsWorkspaceLayout](#layout), [DocumentFileRow](#data-display), [DocumentSourceTag](#data-display) | [story](https://github.com/Assure-One/design-system/blob/main/src/composites/document-detail-panel.stories.tsx) |
+| **DocumentFileRow**<br>parts: `DocumentFileCard`, `DocumentFileLine`<br>since 1.4.0 | A file in the documents workspace as a row, a card or a selectable line (named checkbox). | An attachment outside the workspace (`AttachmentChip`). | — | [DocumentDetailPanel](#data-display), [FileTypeBadge](#data-display), [AttachmentChip](#data-display) | [story](https://github.com/Assure-One/design-system/blob/main/src/composites/document-file-row.stories.tsx) |
+| **DocumentRequestDetail**<br>parts: `DocumentRequestCard`<br>since 1.9.0 | A document request as a card in a list and as the expanded detail. | The request form field (`DocumentRequestField`) or the client's upload (`DocumentRequestUpload`). | — | [DocumentRequestField](#forms), [DocumentRequestUpload](#forms), [MissingDocumentsPanel](#feedback) | [story](https://github.com/Assure-One/design-system/blob/main/src/composites/document-request-detail.stories.tsx) |
+| **TimeLogger**<br>parts: `TimeLoggerHeader`, `TimeLoggerTimer`, `TimeLoggerContextRow`, `TimeLoggerField`, `TimeLoggerBillable`, `TimeLoggerNotes`, `TimeLoggerEntryList`, `TimeLoggerEntry`, `TimeLoggerActions`, `TimeLoggerFooter`<br>also: `formatClock`, `formatDuration`, `parseDuration`, `formatCurrency`, `useStopwatch`<br>since 0.15.0 | The compact time-entry panel: compose only the rows a surface needs (timer, context, billable, notes, entries); `useStopwatch` and the duration formatters drive it. | A single duration field (`Input` + `parseDuration`). | — | [Popover](#overlays), [NumberInput](#forms) | [story](https://github.com/Assure-One/design-system/blob/main/src/composites/time-logger.stories.tsx) |
+| **Proposal pricing**<br>parts: `ProposalServiceRow`, `ProposalAddOn`, `ProposalBillingTerms`, `ProposalPricingSummary`<br>since 1.12.0 | The Services & Pricing blocks of a proposal preview: package card, service rows, add-ons, billing terms, summary; inherit the firm accent inside `AgreementViewer`. | Anything outside a proposal (`Card`, `MetadataGrid`). | — | [AgreementViewer](#shell-screens), [ProposalSignatureBlock](#forms), [ProposalSignerList](#data-display) | [story](https://github.com/Assure-One/design-system/blob/main/src/composites/proposal-pricing.stories.tsx) |
+| **Proposal content**<br>parts: `ProposalNote`, `ProposalCustomPage`<br>since 1.12.0 | The content blocks of a proposal: signer list, notes, custom pages. | Anything outside a proposal. | — | [AgreementViewer](#shell-screens), [ProposalPackageCard](#data-display) | [story](https://github.com/Assure-One/design-system/blob/main/src/composites/proposal-content.stories.tsx) |
+
+## Media
+
+Charts, previews and brand artwork.
+
+| Component | Use when | Don't use when | Replaces raw HTML | Related | Links |
+| --- | --- | --- | --- | --- | --- |
+| **AreaChart**<br>since 1.2.0 | A trend over time as a filled area, in design-system colours. | Parts of a whole (`DonutChart`) or category comparison (`StackedBarChart`, `RankedBars`). | `ad-hoc recharts with hex colours` | [DonutChart](#media), [StackedBarChart](#media), [RankedBars](#media) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/area-chart.stories.tsx) |
+| **DonutChart**<br>since 1.2.0 | Parts of a whole with a centre label. | One value's progress (`ProgressRing`). | — | [ProgressRing](#feedback), [AreaChart](#media) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/donut-chart.stories.tsx) |
+| **StackedBarChart**<br>since 1.6.0 | Composition per category as stacked bars (e.g. work by priority). | A ranked list of values (`RankedBars`). | — | [RankedBars](#media), [AreaChart](#media), [PriorityIcon](#icons) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/stacked-bar-chart.stories.tsx) |
+| **RankedBars**<br>since 1.2.0 | A ranked list of labelled values as horizontal bars. | Stacked composition (`StackedBarChart`). | — | [StackedBarChart](#media) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/ranked-bars.stories.tsx) |
+| **PdfPreview**<br>since 1.7.0 | Render a PDF inline with paging and zoom. | A spreadsheet (`SpreadsheetPreview`) or just a file row (`AttachmentChip`). | — | [SpreadsheetPreview](#media), [AttachmentChip](#data-display), [AspectRatio](#layout) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/pdf-preview.stories.tsx) |
+| **SpreadsheetPreview**<br>since 1.7.0 | Render a spreadsheet's sheets and cells inline. | A PDF (`PdfPreview`) or an editable grid (`Grid`). | — | [PdfPreview](#media), [Table](#data-display) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/spreadsheet-preview.stories.tsx) |
+| **Logo**<br>since 0.0.0 | The Assure suite or product wordmark: official artwork with a glyph + text fallback; `assetPath` resolves the artwork base. | A small product mark alone (brand icon family). | `<img src="/brand/….svg">` | [Sidebar](#shell-screens), [assetPath](#hooks-utilities) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/logo.stories.tsx) |
+
+## Icons
+
+Every glyph comes from the catalogue; never inline an `<svg>` or add `lucide-react`. Icons are `aria-hidden` unless given a `title`; size with `size` (`xs`…`lg` or a pixel number). The `/icons` entry is server-safe (no `"use client"`); the root re-exports the same components. See [`docs/design-system/icons.md`](./design-system/icons.md).
+
+### Icons (experimental)
+
+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. 147 exports, plus `createIcon`.
+
+**Use when:** Any glyph in a control, a list row, a status, an empty state; `createIcon` to register a one-off glyph in the same contract.  
+**Don't use when:** You need a product mark (brand icon family or `Logo`), a state-driven glyph (`StatusIcon`, `PriorityIcon`) or an illustration.  
+**Replaces:** `<svg>`, `lucide-react`  
+**Story:** [src/primitives/icons.stories.tsx](https://github.com/Assure-One/design-system/blob/main/src/primitives/icons.stories.tsx)  
+
+`AlertCircleIcon` · `AlertTriangleIcon` · `AlertTriangleSolidIcon` · `ArchiveIcon` · `ArrowDownIcon` · `ArrowLeftIcon` · `ArrowRightIcon` · `ArrowUpIcon` · `AtSignIcon` · `BarChartIcon` · `BellIcon` · `BoldIcon` · `BrainIcon` · `BriefcaseIcon` · `Building2Icon` · `BuildingIcon` · `CalendarIcon` · `ChatBubbleIcon` · `CheckCircle2Icon` · `CheckCircleSolidIcon` · `CheckIcon` · `ChevronDownIcon` · `ChevronLeftIcon` · `ChevronRightIcon` · `ChevronsDownUpIcon` · `ChevronsUpDownIcon` · `ChevronUpIcon` · `CircleDotIcon` · `CircleIcon` · `ClipboardCheckIcon` · `ClockIcon` · `CommandIcon` · `CopyIcon` · `CornerDownLeftIcon` · `CreditCardIcon` · `DocumentIcon` · `DollarSignIcon` · `DownloadIcon` · `ExternalLinkIcon` · `ExtractIcon` · `EyeIcon` · `EyeOffIcon` · `FileIcon` · `FileReturnIcon` · `FileTextIcon` · `FilterIcon` · `FlagIcon` · `FolderClosedIcon` · `FolderOpenIcon` · `FolderPlusIcon` · `FolderUpIcon` · `GlobeIcon` · `GripVerticalIcon` · `HelpCircleIcon` · `HistoryIcon` · `HomeIcon` · `InboxIcon` · `InfoCircleSolidIcon` · `InfoIcon` · `ItalicIcon` · `KanbanIcon` · `KeyIcon` · `LandmarkIcon` · `LayersIcon` · `LayoutDashboardIcon` · `LayoutGridIcon` · `LayoutListIcon` · `LightningIcon` · `Link2Icon` · `LinkIcon` · `ListChecksIcon` · `ListIcon` · `ListOrderedIcon` · `LoaderIcon` · `LockIcon` · `LockKeyholeIcon` · `LockOpenIcon` · `LogOutIcon` · `MailIcon` · `MapPinIcon` · `MaximizeIcon` · `MenuIcon` · `MessageCircleIcon` · `MessageCircleWarningIcon` · `MicIcon` · `MinimizeIcon` · `MinusIcon` · `MonitorIcon` · `MoonIcon` · `MoreHorizontalIcon` · `MoveIcon` · `PaletteIcon` · `PanelLeftCloseIcon` · `PanelLeftIcon` · `PanelRightIcon` · `PaperclipIcon` · `PauseIcon` · `PencilIcon` · `PenSignIcon` · `PenToolIcon` · `PhoneIcon` · `PlayIcon` · `PlusIcon` · `ReceiptIcon` · `RefreshCwIcon` · `ReplyIcon` · `RotateCcwIcon` · `SaveIcon` · `SearchIcon` · `SendIcon` · `SettingsIcon` · `ShieldIcon` · `SigmaIcon` · `SlashIcon` · `SmartphoneIcon` · `SparkleIcon` · `SparklesIcon` · `StarIcon` · `StopIcon` · `StrikethroughIcon` · `SunIcon` · `TableIcon` · `TagIcon` · `TeamIcon` · `ThumbsDownIcon` · `ThumbsUpIcon` · `TimerIcon` · `Trash2Icon` · `TrashIcon` · `TrashSolidIcon` · `TrendingDownIcon` · `TrendingUpIcon` · `UnderlineIcon` · `UploadIcon` · `UserCircleIcon` · `UserIcon` · `UsersIcon` · `VideoIcon` · `Volume2Icon` · `VolumeXIcon` · `WorkflowIcon` · `XCircleSolidIcon` · `XIcon` · `ZoomInIcon` · `ZoomOutIcon`
+
+Deprecated aliases (same drawing under an older name): `ArrowRightSmallIcon`, `CloseIcon`.
+
+### Brand icons
+
+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. 6 exports.
+
+**Use when:** A product switcher, a sign-in provider button, a suite tile.  
+**Don't use when:** A generic glyph is meant (use the icon catalogue) or the full wordmark is wanted (`Logo`).  
+**Replaces:** `<img src="…logo.svg">`  
+**Story:** [src/primitives/logo.stories.tsx](https://github.com/Assure-One/design-system/blob/main/src/primitives/logo.stories.tsx)  
+
+`AssureAuditBrandIcon` · `AssureBooksBrandIcon` · `AssureProBrandIcon` · `AssureTaxBrandIcon` · `GoogleBrandIcon` · `MicrosoftBrandIcon`
+
+### State-driven icons
+
+| Component | Use when | Don't use when | Replaces raw HTML | Related | Links |
+| --- | --- | --- | --- | --- | --- |
+| **StatusIcon**<br>since 0.8.0 | A progress-aware state circle for pipeline stages (`state`, optional `progress`). | A status with text (`StatusBadge`) or a fixed glyph (icon catalogue). | — | [PriorityIcon](#icons), [StatusBadge](#data-display), [ProgressRing](#feedback) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/priority-status-icons.stories.tsx) |
+| **PriorityIcon**<br>since 0.8.0 | The glyph for the fixed none/low/medium/high/urgent priority scale. | A generic arrow or flag (icon catalogue) or a status (`StatusIcon`). | — | [StatusIcon](#icons), [StackedBarChart](#media) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/priority-status-icons.stories.tsx) |
+
+## Shell/screens
+
+The application frame and full-screen composites: shell, sidebar, header, brand scope and product surfaces shared by more than one app.
+
+| Component | Use when | Don't use when | Replaces raw HTML | Related | Links |
+| --- | --- | --- | --- | --- | --- |
+| **Shell**<br>parts: `Main`, `Content`<br>since 0.3.0 | The application frame: `Shell` holds the `Sidebar` and `Main`; `Main` holds `AppHeader` and `Content`. | A public or marketing page (`Section`). | `<div class="flex h-screen">` | [Sidebar](#shell-screens), [AppHeader](#shell-screens), [BrandScope](#shell-screens) | [story](https://github.com/Assure-One/design-system/blob/main/src/composites/shell.stories.tsx) |
+| **Sidebar**<br>parts: `SidebarProvider`, `SidebarTrigger`, `SidebarBrand`, `SidebarBrandText`, `SidebarSection`, `SidebarLinkGroup`, `SidebarLink`, `SidebarLinkLabel`, `SidebarLinkBadge`, `SidebarLinkAction`, `SidebarPinButton`, `SidebarUser`, `SidebarFooter`<br>also: `sidebarLinkBadgeVariants`, `useSidebarState`, `useSidebarPeekLock`<br>since 0.3.0 | The app navigation rail: expanded/collapsed/peek states from `SidebarProvider`, brand, sections, link groups with badges and actions, user and footer. | Mobile (`BottomNav`) or a rail of records (`ClientRailItem`). | `<aside> + <nav> hand-rolled` | [Shell](#shell-screens), [SidebarBrandSwitcher](#shell-screens), [BottomNav](#navigation) | [story](https://github.com/Assure-One/design-system/blob/main/src/composites/sidebar.stories.tsx) |
+| **SidebarBrandSwitcher**<br>parts: `SidebarBrandSwitcherTile`<br>since 0.11.2 | Switch between Assure products from the sidebar brand slot: tiles for available, current and coming-soon products. | A single-product app (`SidebarBrand`). | — | [Sidebar](#shell-screens), [BrandScope](#shell-screens), [Logo](#media) | [story](https://github.com/Assure-One/design-system/blob/main/src/composites/sidebar-brand-switcher.stories.tsx) |
+| **AppHeader**<br>parts: `AppHeaderBreadcrumb`, `AppHeaderTitle`, `AppHeaderSearch`, `AppHeaderActions`<br>since 0.3.0 | The sticky 56px top bar inside `Main`: breadcrumb, title, search and actions slots in any order. | The page's own title block (`PageHeader`). | — | [Shell](#shell-screens), [PageHeader](#layout), [NewMenu](#actions), [NotificationPanel](#data-display) | [story](https://github.com/Assure-One/design-system/blob/main/src/composites/app-header.stories.tsx) |
+| **DesignSystemProvider** (experimental)<br>also: `useDsMessages`<br>since unreleased | 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. | You are on Next.js — `NextDesignSystemProvider` from `/next` fills in the adapters. Theming a subtree is `ThemeScope` / `BrandScope`, not a nested provider. | `hand-rolled i18n or router context for design-system strings and links` | [ThemeScope](#shell-screens), [BrandScope](#shell-screens), [Tooltip](#overlays), [LinkButton](#actions), [Logo](#media) | [story](https://github.com/Assure-One/design-system/blob/main/src/foundation/provider/design-system-provider.stories.tsx) |
+| **ThemeScope** (experimental)<br>since unreleased | 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. | The whole app shares one theme (set the attributes on the document root) or only the product brand changes (`BrandScope`). | `<div data-ds-scheme="dark"> whose dialogs come up in the root theme` | [BrandScope](#shell-screens), [DesignSystemProvider](#shell-screens), [Dialog](#overlays), [Popover](#overlays) | [story](https://github.com/Assure-One/design-system/blob/main/src/primitives/behavior/portal.stories.tsx) · [docs](https://github.com/Assure-One/design-system/blob/main/docs/integration/css.md) |
+| **BrandScope**<br>parts: `BrandScopeProvider`<br>also: `BRAND_PRODUCTS`, `brandLabel`, `brandScope`, `useBrandScope`<br>since 1.18.0 | Theme a subtree as a product: stamps `data-brand` and provides it so portalled surfaces re-stamp themselves; `brandScope(product)` for the attribute alone. | Colouring by service line (`serviceToneStyle`) or by status (`intent`). | — | [Shell](#shell-screens), [SidebarBrandSwitcher](#shell-screens) | [docs](https://github.com/Assure-One/design-system/blob/main/docs/integration/css.md) |
+| **AgreementViewer**<br>parts: `AgreementPaneHeading`<br>since 1.12.0 | The client-facing agreement / proposal viewer: cover, steps, firm accent scope for the proposal blocks. | Previewing a PDF (`PdfPreview`). | — | [ProposalPackageCard](#data-display), [ProposalSignatureBlock](#forms), [ProposalSignerList](#data-display) | [story](https://github.com/Assure-One/design-system/blob/main/src/composites/agreement-viewer.stories.tsx) |
+
+## Hooks/utilities
+
+Non-rendering exports: hooks, class-name helpers, formatters and token objects.
+
+| Component | Use when | Don't use when | Replaces raw HTML | Related | Links |
+| --- | --- | --- | --- | --- | --- |
+| **cn**<br>since 0.0.0 | Merge class names (clsx + tailwind-merge) when composing `className`; consumer classes still win by cascade, `cn` only dedupes. | Overriding a component part — pass `className`/`classNames` instead of rebuilding its classes. | — | [Button](#actions) | [docs](https://github.com/Assure-One/design-system/blob/main/docs/integration/css.md) |
+| **useFieldControl** (experimental)<br>since 1.32.0 | 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. | Wrapping an existing element once (`FieldControl`). | — | [Field](#forms), [FieldControl](#forms) | [docs](https://github.com/Assure-One/design-system/blob/main/docs/adr/006-field-native-form-participation.md) |
+| **Date utilities**<br>also: `displayToIso`, `applyMask`, `applyYearMask`, `isoToDate`, `dateToIso`, `isoToYear`, `yearToIso`, `DATE_DISPLAY_PLACEHOLDER`, `YEAR_DISPLAY_PLACEHOLDER`<br>since 0.11.0 | Convert between ISO `YYYY-MM-DD`, the `MM/DD/YYYY` display format and JS `Date` the way `DatePicker` does, and apply its typing masks. | Locale-aware formatting for display text (`Intl.DateTimeFormat`). | — | [DatePicker](#forms), [DateRangePicker](#forms) | — |
+| **Country codes**<br>also: `getFlagEmoji`, `parsePhoneForEditing`<br>since 1.1.0 | The ISO country / dial-code table behind `PhoneCountryInput`, a flag emoji fallback, and splitting a stored phone string for editing. | Full phone validation (bring libphonenumber). | — | [PhoneField](#forms), [PhoneCountryInput](#forms) | — |
+| **Service tones**<br>also: `SERVICE_TONES`, `serviceToneLabel`<br>since 1.2.0 | Tone a portal surface per service line by setting `--tone` / `--tone-bg` once on its root; labels for chips and headings. | Status colour (`intent`) or product theming (`BrandScope`). | — | [CategoryDivider](#layout), [EngagementCard](#data-display), [BrandScope](#shell-screens) | — |
+| **Asset base path**<br>also: `getAssetBasePath`, `setAssetBasePath`<br>since 1.33.0 | The app is served from a subpath: call `setAssetBasePath` once so the design system's own artwork (`Logo`) resolves. | Your own assets (use your framework's base path). | — | [Logo](#media) | — |
+| **Tokens (root re-export)**<br>also: `reference`, `colors`, `spacing`, `radii`, `shadows`, `surfaces`, `typography`<br>since 0.0.0 | Token objects from JavaScript when a utility class cannot reach (inline styles, charts, motion); prefer the `/tokens` entry for a smaller import. | Styling components — use the `--ds-*` custom properties and utilities; never read `reference`/`colors` in component code. | — | [BrandScope](#shell-screens) | [docs](https://github.com/Assure-One/design-system/blob/main/docs/design-system/shape-roles.md) |
+
+## Never hand-roll
+
+The raw element or pattern on the left already has a design-system component. Writing the left column in a product means re-implementing focus rings, sizes, disabled and invalid states, form participation and the `ds:` vocabulary the apps depend on — use the right column.
+
+| Instead of | Use |
+| --- | --- |
+| `<a class="btn">` | [LinkButton](#actions) |
+| `<a role="button">` | [Button](#actions) |
+| `<aside> + <nav> hand-rolled` | [Sidebar](#shell-screens) |
+| `<blockquote>` | [Blockquote](#typography) |
+| `<button type="submit">` | [SubmitButton](#actions) |
+| `<button>` | [Button](#actions) |
+| `<button><svg/></button>` | [IconButton](#actions) |
+| `<code>` | [Code](#typography) |
+| `<details>/<summary>` | [Collapsible](#layout) |
+| `<dialog>` | [Dialog](#overlays) |
+| `<div class="animate-pulse bg-…">` | [Skeleton](#feedback) |
+| `<div class="border-t">` | [Separator](#layout) |
+| `<div class="flex flex-col gap-4">` | [Stack](#layout) |
+| `<div class="flex flex-wrap items-center gap-2">` | [Inline](#layout) |
+| `<div class="flex h-screen">` | [Shell](#shell-screens) |
+| `<div class="flex items-center gap-2"> above a list` | [Toolbar](#actions) |
+| `<div class="flex items-center justify-between"><h1>` | [PageHeader](#layout) |
+| `<div class="grid grid-cols-[320px_1fr]">` | [Detail layout](#layout) |
+| `<div class="grid place-items-center rounded-lg bg-…"><svg/>` | [IconTile](#data-display) |
+| `<div class="overflow-auto">` | [ScrollArea](#layout) |
+| `<div class="rounded-xl border bg-white p-4">` | [Surface](#layout) |
+| `<div class="rounded-xl border shadow">` | [Card](#layout) |
+| `<div class="sticky bottom-0">` | [StickyActionBar](#actions) |
+| `<div data-ds-scheme="dark"> whose dialogs come up in the root theme` | [ThemeScope](#shell-screens) |
+| `<div onClick>` | [Button](#actions), [Pressable](#actions) |
+| `<div role="alert">` | [Alert](#feedback) |
+| `<div role="group">` | [Fieldset](#forms) |
+| `<dl>` | [MetadataGrid](#data-display) |
+| `<fieldset>` | [Fieldset](#forms) |
+| `<h1>` | [Heading](#typography) |
+| `<h2>` | [Heading](#typography) |
+| `<h2> + <p> pair` | [SectionHeader](#layout) |
+| `<h3>` | [Heading](#typography) |
+| `<h4>` | [Heading](#typography) |
+| `<hr>` | [Separator](#layout) |
+| `<img class="rounded-full">` | [Avatar](#data-display) |
+| `<img src="…logo.svg">` | [Brand icons](#icons) |
+| `<img src="/brand/….svg">` | [Logo](#media) |
+| `<input list> + <datalist>` | [Combobox](#selection) |
+| `<input type="button">` | [Button](#actions) |
+| `<input type="checkbox" role="switch">` | [Switch](#forms) |
+| `<input type="checkbox">` | [Checkbox](#forms) |
+| `<input type="checkbox"> styled as pills` | [MultiSelectField](#forms) |
+| `<input type="date">` | [DatePicker](#forms) |
+| `<input type="email">` | [Input](#forms) |
+| `<input type="file">` | [FileUpload](#forms) |
+| `<input type="number">` | [NumberInput](#forms) |
+| `<input type="password">` | [Input](#forms) |
+| `<input type="radio">` | [RadioGroup](#forms) |
+| `<input type="range">` | [Slider](#forms) |
+| `<input type="search">` | [SearchInput](#forms) |
+| `<input type="submit">` | [SubmitButton](#actions) |
+| `<input type="tel">` | [PhoneField](#forms) |
+| `<input type="text">` | [Input](#forms) |
+| `<input>` | [Input](#forms) |
+| `<kbd>` | [Kbd](#typography) |
+| `<label for> + <input id> + <p id> aria-describedby` | [Field](#forms) |
+| `<label>` | [Label](#forms) |
+| `<legend>` | [Fieldset](#forms) |
+| `<li onClick>` | [Pressable](#actions) |
+| `<nav aria-label="breadcrumb"><ol>` | [Breadcrumb](#navigation) |
+| `<nav> of page number buttons` | [Pagination](#navigation) |
+| `<option>` | [Select](#selection) |
+| `<p class="text-red-500">` | [Field](#forms) |
+| `<p>` | [Text](#typography) |
+| `<pre>` | [Code](#typography) |
+| `<progress>` | [ProgressBar](#feedback) |
+| `<section class="mx-auto max-w-… px-8">` | [Section](#layout) |
+| `<select multiple>` | [MultiSelect](#selection) |
+| `<select>` | [Select](#selection) |
+| `<select> of dial codes + <input type="tel">` | [PhoneField](#forms) |
+| `<select> used as a menu` | [DropdownMenu](#overlays) |
+| `<select> with a search box` | [Combobox](#selection) |
+| `<span class="h-2 w-2 rounded-full bg-red-500">` | [StatusDot](#data-display) |
+| `<span class="rounded-full …"><button>×</button></span>` | [Chip](#selection) |
+| `<span class="rounded-full px-2 text-xs">` | [Badge](#data-display) |
+| `<span class="text-sm text-gray-500">` | [Text](#typography) |
+| `<span role="button">` | [Pressable](#actions) |
+| `<svg>` | [Icons](#icons) |
+| `<table>` | [Table](#data-display) |
+| `<table> + hand-rolled toolbar and pager` | [DataTable](#data-display) |
+| `<table> of <input>s` | [Grid](#forms) |
+| `<td>` | [Table](#data-display) |
+| `<textarea>` | [Textarea](#forms) |
+| `<th>` | [Table](#data-display) |
+| `<tr>` | [Table](#data-display) |
+| `<ul role="tablist">` | [Tabs](#navigation) |
+| `<ul> of hand-styled feed rows` | [ActivityList](#data-display) |
+| `<ul> shown on click` | [DropdownMenu](#overlays) |
+| `absolute-positioned div toggled by state` | [Popover](#overlays) |
+| `ad-hoc recharts with hex colours` | [AreaChart](#media) |
+| `alert()` | [ToastProvider](#feedback) |
+| `animate-spin svg` | [Spinner](#feedback) |
+| `Array.from({ length }).map(<Skeleton/>)` | [LoadingRows](#feedback) |
+| `buttons toggling useState panels` | [Tabs](#navigation) |
+| `centred div with an icon and grey text` | [EmptyState](#feedback) |
+| `class="sr-only"` | [VisuallyHidden](#layout) |
+| `coloured bordered div` | [Alert](#feedback) |
+| `drop-zone div with onDrop` | [FileUpload](#forms) |
+| `fixed inset-0 div` | [Dialog](#overlays) |
+| `fixed right-0 h-full div` | [Sheet](#overlays) |
+| `group of <button aria-pressed>` | [ToggleGroup](#selection) |
+| `hand-rolled i18n or router context for design-system strings and links` | [DesignSystemProvider](#shell-screens) |
+| `hand-rolled toast portal` | [ToastProvider](#feedback) |
+| `hard-coded top-[56px] sticky offsets` | [StickyStack](#layout) |
+| `lucide-react` | [Icons](#icons) |
+| `navigator.clipboard.writeText + useState` | [CopyButton](#actions) |
+| `nested div with width:%` | [ProgressBar](#feedback) |
+| `onContextMenu + positioned div` | [ContextMenu](#overlays) |
+| `padding-top percentage hack` | [AspectRatio](#layout) |
+| `six <input maxlength="1">` | [OTPInput](#forms) |
+| `stack of <details>` | [Accordion](#layout) |
+| `title="…"` | [Tooltip](#overlays) |
+| `two <input type="date">` | [DateRangePicker](#forms) |
+| `two-column label/value divs` | [MetadataGrid](#data-display) |
+| `useState + AlertDialog boilerplate` | [ConfirmActionButton](#actions) |
+| `useState toggle` | [Collapsible](#layout) |
+| `window.confirm()` | [ConfirmActionButton](#actions), [AlertDialog](#overlays) |
+
+## Deprecated aliases and their replacements
+
+Every deprecated name keeps rendering exactly what it did (zero visual diff) until 3.0. The codemod column names the transform in [`codemods/README.md`](../codemods/README.md) that rewrites call sites (`node node_modules/@assure-one/design-system/codemods/run.mjs <id> src`); a dash means the change is a hand edit. Deprecated exports in the API report: `ArrowRightSmallIcon`, `CloseIcon`, `CountryFlag`, `CountrySelect`, `FormError`, `FormSection`, `FormSuccess`, `PhoneCountryInput`, `PhoneInput`, `SearchSelect`.
+
+| Deprecated | Use instead | Codemod | Contract |
+| --- | --- | --- | --- |
+| `Button variant="primary"` | `variant="solid" intent="brand"` (the default) | CM-04 | C-BTN-VARIANT |
+| `Button variant="secondary"` | `variant="soft" intent="neutral"` | CM-04 | C-BTN-VARIANT |
+| `Button variant="destructive"` | `variant="solid" intent="danger"` | CM-04 | C-BTN-VARIANT |
+| `Button variant="success"` | `variant="solid" intent="success"` | CM-04 | C-BTN-VARIANT |
+| `Button variant="accent"` / `"dashed"` | Reported by CM-04 for review: `accent` is a brand look, `dashed` an outline look; both keep rendering until 3.0 | CM-04 (report) | C-BTN-VARIANT |
+| `Button intent="destructive"` | `intent="danger"` | — | C-BTN-VARIANT |
+| `Button size="compact"` / `"default"` / `"comfortable"`, `"icon-xs"` / `"icon-sm"` / `"icon"` | `size="sm"` / `"md"` / `"lg"`; icon sizes → `IconButton size` | CM-02 (explicit `size="md"`) | C-BTN-SIZE |
+| `Button` / `LinkButton` / `SubmitButton` `iconLeft` / `iconRight` | `iconStart` / `iconEnd` | CM-05 | C-BTN-ICONPROPS |
+| `Button` without `type` inside a form | `type="submit"` where evident, or `SubmitButton` | CM-12 | — |
+| `Input` / `Textarea` / `SearchInput` `inputSize` | `size` | CM-07 | C-INPUT-SIZE |
+| `InputSizeAlias` `compact` / `default` / `comfortable` | `sm` / `md` / `lg` | — | C-INPUT-SIZE |
+| `Select` `triggerClassName` / `contentClassName` | `classNames={{ trigger, content }}` | — | C-SELECT-CLASSNAMES |
+| `Select searchable` | `Combobox` | — | — |
+| `Select` sentinel option values standing in for "no value" | A real empty value (`value=""`, `clearable`) | CM-20 (finder) | C-SELECT-EMPTY |
+| `SearchSelect` (`{ id, label }` options) | `Combobox` with `Option` (`{ value, label }`) | CM-08 | C-SEARCHSELECT |
+| `Checkbox indeterminate` | `checked="indeterminate"` | — | C-CHECKBOX-INDET |
+| `DatePicker onChange={e => f(e.target.value)}` (fake event) | `onValueChange={value => f(value)}` | CM-10 | C-DATE-FAKEEVENT |
+| `StatusDot` / `IconTile` / `Spinner` / `SegmentedProgress` / `SuiteProgress` `tone` | `intent` (`pro` → `brand`, `muted` → `neutral`, `accent` → `info`, `destructive` → `danger`) | CM-06 | C-TONE |
+| `ProgressBar` / `ProgressRing` `variant` (`default`, `destructive`, …) | `intent` (`brand`, `danger`, …); value-driven auto colour written down explicitly | CM-19 | C-PROGRESS |
+| `Badge variant="default"` / `"secondary"` / `"destructive"` / `"success"` / `"warning"` / `"info"` / `"outline"` | `variant` (`solid`, `soft`, `outline`) + `intent` | — | C-BADGE |
+| `FormError` | `FieldError` inside a `Field` | — | C-FORM-MSG |
+| `FormSuccess` | `FieldDescription` inside a `Field`, or a toast for a saved form | — | C-FORM-MSG |
+| `FormSection` | `Fieldset` + `FieldsetLegend` | — | — |
+| `PhoneInput`, `PhoneCountryInput` (+ `CountrySelect`, `CountryFlag`) | `PhoneField` (E.164 value, `Combobox` country picker) | — | — |
+| `Sidebar gutterPx` | The sidebar's own geometry tokens | — | — |
+| `CloseIcon`, `ArrowRightSmallIcon` | `XIcon`, `ArrowRightIcon` (same drawing) | — | — |
+| Hidden `<input name>` mirrors added because a control posted nothing | Remove them: every control participates in the form through `FormBridge` | CM-14 (finder) | C-HIDDEN-MIRRORS |
+| Selectors into a component's internal DOM | `className` / `classNames` and `data-slot` selectors (ADR-008) | CM-15 (finder) | C-DOM-* |
+
+## `/tokens` entry
+
+Design tokens as JavaScript (`@assure-one/design-system/tokens`), for the places a utility class cannot reach: inline styles, motion configs, charts, design-tool sync. In CSS and Tailwind classes use the `--ds-*` custom properties and the generated utilities instead; components never read reference tokens directly (see [`docs/design-system/`](./design-system/)).
+
+| Export | Kind | What it is |
+| --- | --- | --- |
+| `BRAND_THEME_PROPERTIES` | utility | The custom-property names a brand theme sets. |
+| `breakpoints` | utility | Viewport breakpoints as numbers. |
+| `colors` | utility | Reference palette (programmatic access; never for component styling). |
+| `createBrandTheme` | utility | Build a runtime brand theme from a seed (`docs/integration/css.md` §5). Experimental. |
+| `iconSizes` | utility | The icon size scale in pixels. |
+| `layout` | utility | Layout constants (sidebar width, header height, content pad). |
+| `motion` | utility | Durations and easings. |
+| `overlays` | utility | Overlay constants (z-index tiers, backdrop). |
+| `radii` | utility | Radius scale. |
+| `reference` | utility | All reference tokens in one object. |
+| `shadows` | utility | Shadow scale. |
+| `spacing` | utility | The 4px spacing scale. |
+| `surfaces` | utility | The four canonical surface layers. |
+| `systemTokens` | utility | System (semantic) tokens as CSS variable references — the ones components consume. |
+| `typography` | utility | Font families, sizes, weights and letterspacing. |
+| `zIndex` | utility | Z-index tiers. |
+
+## `/testing` entry
+
+Helpers that let an application's Jest or Vitest suite render the real package instead of a stub (`@assure-one/design-system/testing`, **experimental**). Full guide: [`docs/testing.md`](./testing.md).
+
+| Export | Kind | What it is |
+| --- | --- | --- |
+| `createToastRecorder` | utility | Records the toasts a real `ToastProvider` shows. |
+| `fillField` | utility | Types into a text control found by its `Field` label. |
+| `installDomPolyfills` | utility | The jsdom shims alone, for Vitest or a custom setup file. |
+| `openMenu` | utility | Opens a design-system `DropdownMenu` and returns a handle to its items. |
+| `pickDate` | utility | Sets a design-system `DatePicker` to an ISO date through the DOM. |
+| `selectOption` | utility | Chooses an option in a design-system `Select` through the DOM. |
+| `withAssureDesignSystem` | utility | Jest config wrapper that makes the real package load (resolution, ESM transform, jsdom shims). |
+
+## `/next` entry
+
+The Next.js adapter (`@assure-one/design-system/next`, **experimental**): `DesignSystemProvider` preconfigured with `next/link` and `next/image`, so `LinkButton` and `Logo` render the framework's link and image. Mount it once in the root layout instead of the plain provider.
+
+| Export | Kind | What it is |
+| --- | --- | --- |
+| `NextDesignSystemProvider` | component | `DesignSystemProvider` with `next/link` and `next/image` filled in; takes every other provider prop. |
+
+## Proposing a component that is not here
+
+Do not build it locally in a product. A pattern that two products need is promoted into the shared layer through [ADR-009](./adr/009-shared-product-promotion.md): open an issue or PR in this repository with the use case, the products that need it and the story; it ships `@experimental` first. Product-specific composites stay in the product until a second product needs them.
+