@salesql/sql_components_vue3 2.0.0 → 2.1.1

package/llms-full.txt

@@ -0,0 +1,1350 @@
+# @salesql/sql_components_vue3 — SalesQL Design System (v2.1.1)
+
+> Librería de componentes Vue 3 (SalesQL) Presentational-only Vue 3 components (props in, events out; the consuming app owns state, i18n and data). This file is auto-generated from the component stories for LLM/agent consumption — do not edit by hand.
+
+## Using the library
+
+```ts
+import { DsButton, DsNotification } from '@salesql/sql_components_vue3';
+import '@salesql/sql_components_vue3/dist/style.css'; // once, at app entry
+```
+
+All components are named exports with the `Ds` prefix. Variant constants and TypeScript types ship alongside each component (e.g. `DS_BUTTON_VARIANTS`, `DsButtonVariant`). Components never fetch data or hold app state — drive them with props and listen to their events.
+
+## Components (30)
+
+- **DsAvatar** (Core) — Contact/user avatar: an image, generated initials with a deterministic color hash, or an
+- **DsBadge** (Core) — Solid, white-text pill for value types and counts (e.g. "Work", "New"). **Presentational
+- **DsButton** (Core) — Standard clickable control with the DS variant/size vocabulary, plus icon-only
+- **DsSpinner** (Core) — Indeterminate loading indicator — a circular SVG spinner. **Presentational only**: no
+- **DsTag** (Core) — Small bordered chip with an optional × close control. **Presentational only**: `close`
+- **DsCell** (Data) — A single `<td>` cell in the `DsTable` compound API. **Presentational only**: no props
+- **DsContactValue** (Data) — A single email/phone row: a verification glyph, the value itself, and a type badge
+- **DsCustomTag** (Data) — Static status chip (tinted background + matching border/text), non-interactive.
+- **DsDataCard** (Data) — The signature SalesQL emails/phones card: a header (icon, title, sort/edit/collapse/close
+- **DsEmptyState** (Data) — Centered empty-state panel for empty tables, lists, or search results: an optional
+- **DsPaginator** (Data) — Page-window pagination control: prev/next chevrons, numbered page buttons that collapse
+- **DsPill** (Data) — Small solid capsule with white text and a free-form background color (e.g. a dynamic
+- **DsPillWithBorder** (Data) — Bordered pill/chip rendered as a real `<button>`, with an optional leading icon slot and
+- **DsRow** (Data) — A `<tr>` row for the `DsTable` compound API, with hover and selected treatment;
+- **DsSegmentedProgressBar** (Data) — Horizontal, multi-segment data-viz track (e.g. a verification-quality breakdown), with an
+- **DsTable** (Data) — Data-dense table with two composition modes: **declarative** (`columns` + `rows`, with
+- **DsVerificationIcon** (Data) — Status glyph for a contact data point (email/phone): verified, unverified, or newly
+- **DsAlert** (Feedback) — Inline banner for status/confirmation messages (success, info, warning, error). It
+- **DsModal** (Feedback) — Centered dialog with an optional header (title + close button) and footer action row.
+- **DsNotification** (Feedback) — Fixed-position toast card for transient feedback (saved, updated, failed…). It renders
+- **DsTooltip** (Feedback) — Dark bubble that describes a wrapped trigger on hover or keyboard focus, with 4-way
+- **DsCheckbox** (Forms) — Checked / unchecked / indeterminate selection control. **Presentational only**.
+- **DsInput** (Forms) — Single-line text field — the DS "Input". **Presentational only**: it drives its own
+- **DsItemSelectorButton** (Forms) — Pill-shaped trigger that shows the currently assigned item (folder, tag, owner…)
+- **DsRadio** (Forms) — A single radio control (accent-ring dot when checked). **Presentational only**.
+- **DsSelect** (Forms) — Dropdown select — a native-`<select>`-like single/multi picker with a real
+- **DsSwitch** (Forms) — On/off toggle (accent track when on). **Presentational only**: it reflects the
+- **DsTextarea** (Forms) — Multi-line text field — the DS "Textarea", sibling of `DsInput` with the same
+- **DsMenuItem** (Navigation) — Sidebar navigation row: an icon with an optional label, usable full-width or collapsed to
+- **DsWizardStepper** (Navigation) — Numbered multi-step flow: a row of step chips (completed / active / incomplete / neutral)
+
+---
+<!-- DsAvatar · Core -->
+
+## DsAvatar
+
+Contact/user avatar: an image, generated initials with a deterministic color hash, or an
+empty placeholder — whichever is available, in that priority order. **Presentational
+only**: no events, no interaction.
+
+### Props
+
+| Prop         | Type               | Default     | Description                                                                                          |
+| ------------ | ------------------ | ----------- | ---------------------------------------------------------------------------------------------------- |
+| `image`      | `string`           | `''`        | Image URL. When set, renders an `<img>` (highest priority over initials/placeholder).                |
+| `firstName`  | `string`           | `''`        | Used with `lastName` to compute initials and seed the color hash.                                    |
+| `lastName`   | `string`           | `''`        | See `firstName`.                                                                                     |
+| `letters`    | `string`           | `''`        | Explicit initials — overrides the computed `firstName`+`lastName` initials when non-empty.           |
+| `uid`        | `string`           | `''`        | Seed for the deterministic background color hash (falls back to the name, then `letters`).           |
+| `size`       | `number`           | `40`        | Square box size in px (used for both width and height unless overridden).                            |
+| `width`      | `number`           | `undefined` | Explicit width in px — overrides `size` on that axis.                                                |
+| `height`     | `number`           | `undefined` | Explicit height in px — overrides `size` on that axis.                                               |
+| `textSize`   | `number`           | `undefined` | Initials font-size in px — overrides the computed ~40%-of-box value.                                 |
+| `fontWeight` | `number \| string` | `undefined` | Initials font-weight — overrides the default token weight (900).                                     |
+| `circular`   | `boolean`          | `false`     | Fully round avatar (vs the default rounded-square). Per the DS, reserve this for the logged-in user. |
+| `alt`        | `string`           | `undefined` | Accessible label for the image variant; falls back to the derived name/letters when omitted.         |
+
+### Accessibility
+
+- Image variant: `<img alt>` resolves from `alt`, falling back to the derived
+  `"First Last"` (or `letters`) when `alt` is not provided; pass `alt=""` to mark a
+  purely decorative image.
+- Initials variant: `role="img"` + `aria-label` with the same resolved label, so screen
+  readers announce the represented person.
+- Placeholder variant (no image and no initials): `aria-hidden="true"`, since there is
+  nothing meaningful to announce.
+
+### When to use
+
+- Contact/user avatars in lists, headers, and cards — pass `uid` so the color hash stays
+  stable per person across renders.
+- Reserve `circular` for the current/logged-in user per the design system convention;
+  other contacts use the default rounded-square shape.
+
+---
+
+<!-- DsBadge · Core -->
+
+## DsBadge
+
+Solid, white-text pill for value types and counts (e.g. "Work", "New"). **Presentational
+only**: no events, no interaction — it just renders its slot content on a solid tone
+background.
+
+### Props
+
+| Prop   | Type                                                                | Default    | Description              |
+| ------ | ------------------------------------------------------------------- | ---------- | ------------------------ |
+| `tone` | `'accent' \| 'grey' \| 'info' \| 'success' \| 'error' \| 'warning'` | `'accent'` | Solid fill color family. |
+
+### Accessibility
+
+- Purely presentational — no ARIA role is applied. The badge conveys its meaning
+  through the slotted text, not color alone, so always pass meaningful text content.
+
+### When to use
+
+- A solid, high-contrast pill for value types or counts (e.g. `Work`, `Direct`, `New`).
+- Not a status chip: for a tinted, bordered status label use `DsCustomTag`, and for a
+  removable/clickable value chip use `DsTag`.
+
+---
+
+<!-- DsButton · Core -->
+
+## DsButton
+
+Standard clickable control with the DS variant/size vocabulary, plus icon-only
+(`circle`/`square`), `loading`, and `selected` (toggle) states. **Presentational only**:
+it renders a native `<button>` and emits `click` — the consuming app owns what happens
+next.
+
+### Props
+
+| Prop         | Type                                                                                                                                | Default     | Description                                                                        |
+| ------------ | ----------------------------------------------------------------------------------------------------------------------------------- | ----------- | ---------------------------------------------------------------------------------- |
+| `variant`    | `'default' \| 'primary' \| 'secondary' \| 'tertiary' \| 'quaternary' \| 'quinary' \| 'senary' \| 'dotted' \| 'danger' \| 'warning'` | `'default'` | Visual style. `warning` is a legacy solid-red alias of `danger` — prefer `danger`. |
+| `size`       | `'small' \| 'medium' \| 'large' \| 'xlarge'`                                                                                        | `'medium'`  | Control height + padding.                                                          |
+| `nativeType` | `'button' \| 'submit' \| 'reset'`                                                                                                   | `'button'`  | Native `<button type>`.                                                            |
+| `leftIcon`   | `string`                                                                                                                            | `''`        | Material Icon name rendered before the label (or use the `#leading` slot).         |
+| `rightIcon`  | `string`                                                                                                                            | `''`        | Material Icon name rendered after the label (or use the `#trailing` slot).         |
+| `ariaLabel`  | `string`                                                                                                                            | `''`        | Accessible label — required for icon-only (`circle`/`square`) buttons.             |
+| `disabled`   | `boolean`                                                                                                                           | `false`     | Disables the button and blocks `click`.                                            |
+| `loading`    | `boolean`                                                                                                                           | `false`     | Shows a spinner overlay, natively disables the button, and blocks `click`.         |
+| `circle`     | `boolean`                                                                                                                           | `false`     | Round icon-only button (width === height).                                         |
+| `square`     | `boolean`                                                                                                                           | `false`     | Flat 4px-radius icon-only button (width === height).                               |
+| `noPadding`  | `boolean`                                                                                                                           | `false`     | Zero the square padding for a tight glyph (only takes effect with `square`).       |
+| `selected`   | `boolean`                                                                                                                           | `false`     | Toggle state — accent outline + fill, sets `aria-pressed`.                         |
+| `autofocus`  | `boolean`                                                                                                                           | `false`     | Native `autofocus`.                                                                |
+
+### Events
+
+| Event   | Payload      | When                                                           |
+| ------- | ------------ | -------------------------------------------------------------- |
+| `click` | `MouseEvent` | The button was clicked, unless `disabled` or `loading` is set. |
+
+### Accessibility
+
+- `aria-busy` is set while `loading`; `aria-disabled` while `disabled` or `loading` —
+  and the native `disabled` attribute is also applied in both cases, so the button
+  drops out of the tab order.
+- `aria-pressed` mirrors `selected` for toggle-button semantics.
+- `ariaLabel` maps to `aria-label` — always pass it for icon-only (`circle`/`square`)
+  buttons, since they render no visible label text.
+- While `loading`, the label/icons stay mounted but hidden (`aria-hidden`, visually
+  hidden) so the button keeps its width instead of jumping when the spinner appears.
+
+### When to use
+
+- `primary` for the page's main call to action; `secondary`/`tertiary` for lower
+  emphasis; `danger` for destructive actions (prefer it over the legacy `warning`).
+- Always set `ariaLabel` on `circle`/`square` icon-only buttons.
+- Use `loading` for in-flight async actions instead of swapping in a separate
+  `DsSpinner`.
+
+---
+
+<!-- DsSpinner · Core -->
+
+## DsSpinner
+
+Indeterminate loading indicator — a circular SVG spinner. **Presentational only**: no
+events, no timers; it spins for as long as it is mounted. Mount it while work is
+pending, unmount it when the work resolves.
+
+### Props
+
+| Prop    | Type                                       | Default     | Description                                                              |
+| ------- | ------------------------------------------ | ----------- | ------------------------------------------------------------------------ |
+| `size`  | `number \| 'small' \| 'medium' \| 'large'` | `'medium'`  | Diameter in px, or a named size token.                                   |
+| `tone`  | `'dark' \| 'light' \| 'accent'`            | `'dark'`    | Stroke color. Use `light` on dark surfaces, `accent` for brand emphasis. |
+| `label` | `string`                                   | `'Loading'` | Accessible label announced to screen readers (`aria-label` on the SVG).  |
+
+### Accessibility
+
+- The SVG carries `role="status"` + `aria-label`, so assistive tech announces the
+  loading state. Always pass a meaningful `label` when the default "Loading" is not
+  specific enough (e.g. `"Verifying email"`).
+- `tone="light"` needs a dark background to stay visible — see the **Tones** variant.
+
+### When to use
+
+- Inline within a button or field while an async action runs.
+- As a block-level placeholder for a panel whose data is still loading.
+
+For deterministic progress (a known percentage), use `DsSegmentedProgressBar` instead.
+
+---
+
+<!-- DsTag · Core -->
+
+## DsTag
+
+Small bordered chip with an optional × close control. **Presentational only**: `close`
+is emitted on click, but the parent owns whether/how the tag is actually removed from
+its list.
+
+### Props
+
+| Prop         | Type                                                                 | Default     | Description                                                                                  |
+| ------------ | -------------------------------------------------------------------- | ----------- | -------------------------------------------------------------------------------------------- |
+| `tone`       | `'default' \| 'grey' \| 'success' \| 'info' \| 'warning' \| 'error'` | `'default'` | Border/background color family. `grey` is a DS alias of `default`.                           |
+| `rounded`    | `boolean`                                                            | `false`     | Semicircular sides (vs the default control radius).                                          |
+| `closable`   | `boolean`                                                            | `false`     | Show a × control that emits `close`.                                                         |
+| `clickable`  | `boolean`                                                            | `false`     | Cursor: pointer affordance — set this when you attach a native `@click` listener.            |
+| `truncate`   | `boolean`                                                            | `false`     | Opt-in single-line ellipsis; cap the width via the `--ds-tag-max-width` CSS custom property. |
+| `closeLabel` | `string`                                                             | `''`        | Accessible label for the × control (icon-only).                                              |
+
+### Events
+
+| Event   | Payload | When                             |
+| ------- | ------- | -------------------------------- |
+| `close` | —       | The × close control was clicked. |
+
+### Accessibility
+
+- The × control is icon-only, so `closeLabel` maps to its `aria-label` — always pass it
+  when `closable` is set.
+- `clickable` only toggles the cursor style; the component can't detect an attached
+  native `@click` listener, so it does not add a role/tabindex/keyboard handler on its
+  own — if you make a tag clickable, ensure it stays keyboard-reachable on your side.
+
+### When to use
+
+- Removable or editable filter/value chips (`closable`). For a static, non-removable
+  status label use `DsCustomTag`; for a solid count/value pill use `DsBadge`.
+
+---
+
+<!-- DsCell · Data -->
+
+## DsCell
+
+A single `<td>` cell in the `DsTable` compound API. **Presentational only**: no props
+in, no events out — layout and state come entirely from its props, driven by the
+parent `DsTable`/`DsRow`.
+
+### Props
+
+| Prop           | Type                | Default | Description                                                                                                    |
+| -------------- | ------------------- | ------- | -------------------------------------------------------------------------------------------------------------- |
+| `first`        | `boolean`           | `false` | First cell in the row — pairs with `selected` to draw the 3px accent left rail.                                |
+| `selected`     | `boolean`           | `false` | Whether the owning row is selected (repeat it here, per the DS contract).                                      |
+| `width`        | `string \| number`  | `null`  | Fixed cell width (number → px, or any CSS length).                                                             |
+| `truncate`     | `boolean`           | `false` | Opt-in single-line ellipsis truncation. Off by default (the 72px cell allows multi-line).                      |
+| `pinned`       | `'left' \| 'right'` | `null`  | Pins this cell to the left/right edge (`position: sticky`) for horizontal scroll.                              |
+| `pinnedOffset` | `string \| number`  | `null`  | Cumulative offset from the pinned edge, for stacking several pinned cells on the same side. Defaults to `0px`. |
+
+### Accessibility
+
+- Renders a plain `<td>` — accessibility for the cell's content (labels, roles) is the
+  responsibility of whatever is passed into the default slot.
+- No interactive behavior of its own; keyboard/focus concerns belong to the controls
+  rendered inside it.
+
+### When to use
+
+- Always inside a `DsTable` row (or a `<tr>` built by hand to mirror it) — never as a
+  standalone cell outside a table structure.
+- Use `pinned` together with `pinnedOffset` when more than one column needs to stay
+  fixed on the same side during horizontal scroll.
+
+---
+
+<!-- DsContactValue · Data -->
+
+## DsContactValue
+
+A single email/phone row: a verification glyph, the value itself, and a type badge
+that "marquees" out on hover (or keyboard focus) to reveal copy and optional rating
+actions. **Presentational only**: it copies to the clipboard itself, but rating and
+any other consequence stay with the consuming app via events.
+
+### Props
+
+| Prop             | Type              | Default       | Description                                                                     |
+| ---------------- | ----------------- | ------------- | ------------------------------------------------------------------------------- |
+| `value`          | `string`          | —             | The email address or phone number (required).                                   |
+| `valueType`      | `string`          | `''`          | Type label shown as a badge ("Work", "Direct", "Mobile"…).                      |
+| `verified`       | `boolean \| null` | `null`        | Verification state, forwarded to `DsVerificationIcon`.                          |
+| `main`           | `boolean`         | `false`       | Highlights as the "most likely" value (accent badge + accent hover background). |
+| `isContactData`  | `boolean`         | `false`       | True for emails (affects the unverified glyph color).                           |
+| `showRate`       | `boolean`         | `false`       | Show thumbs up/down rating actions on hover.                                    |
+| `correct`        | `boolean \| null` | `null`        | Current rating: `true` = correct, `false` = incorrect, `null` = unrated.        |
+| `hideValue`      | `boolean`         | `false`       | Locks the value: a static lock glyph replaces copy + rating entirely.           |
+| `copyLabel`      | `string`          | `'Copy'`      | Accessible label / tooltip for the copy button.                                 |
+| `copiedLabel`    | `string`          | `'Copied!'`   | Accessible label / tooltip shown for ~1.2s after a successful copy.             |
+| `correctLabel`   | `string`          | `'Correct'`   | Accessible label / tooltip for the thumbs-up button.                            |
+| `incorrectLabel` | `string`          | `'Incorrect'` | Accessible label / tooltip for the thumbs-down button.                          |
+| `hideValueLabel` | `string`          | `''`          | Accessible name for the lock glyph. Empty → decorative (`aria-hidden`).         |
+
+### Events
+
+| Event       | Payload  | When                                                                             |
+| ----------- | -------- | -------------------------------------------------------------------------------- |
+| `copy`      | `string` | The copy button was clicked. Payload is the copied `value`.                      |
+| `correct`   | —        | The thumbs-up rating button was clicked (only rendered when `showRate` is on).   |
+| `incorrect` | —        | The thumbs-down rating button was clicked (only rendered when `showRate` is on). |
+
+### Accessibility
+
+- The copy and rating buttons are icon-only; `copyLabel`/`copiedLabel`/`correctLabel`/`incorrectLabel`
+  drive both their `aria-label` and `title`.
+- The rating buttons expose their state via `aria-pressed` (`correct === true` / `correct === false`).
+- The lock glyph (`hideValue`) is `aria-hidden` unless `hideValueLabel` is supplied, in which
+  case it becomes `role="img"` with that `aria-label`.
+- The type badge is not `aria-hidden` — it is real classification data, so screen readers
+  announce "value, type" even though it visually cross-fades with the actions on hover.
+
+### When to use
+
+- As a row inside `DsDataCard` for an individual email or phone value — `DsDataCard` already
+  wires `main`, `showRate`, and the rating/copy events for you.
+- Pass `hideValue` for a gated/locked datum instead of rendering the real value.
+
+---
+
+<!-- DsCustomTag · Data -->
+
+## DsCustomTag
+
+Static status chip (tinted background + matching border/text), non-interactive.
+**Presentational only**: no events, no close control — for that, use `DsTag`.
+
+### Props
+
+| Prop    | Type                                                                  | Default  | Description                                                                                                                                                                        |
+| ------- | --------------------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `type`  | `'success' \| 'warning' \| 'danger' \| 'info' \| 'draft' \| 'accent'` | `'info'` | Tint/border color family. `draft` is the only solid-fill variant; `danger`/`accent` map to the `error-*`/`info-*` token families respectively (intentional DS naming, kept as-is). |
+| `round` | `boolean`                                                             | `false`  | Fully rounded sides (vs the default control radius).                                                                                                                               |
+
+### Accessibility
+
+- Purely presentational — no ARIA role is applied. Meaning is conveyed through the
+  slotted text, not color alone, so always pass meaningful text content.
+
+### When to use
+
+- Static status labels (e.g. "Draft", "Verified") that never need to be dismissed or
+  clicked.
+- For a removable/clickable chip use `DsTag`; for a solid count/value pill use
+  `DsBadge`.
+
+---
+
+<!-- DsDataCard · Data -->
+
+## DsDataCard
+
+The signature SalesQL emails/phones card: a header (icon, title, sort/edit/collapse/close
+actions) over a body that renders a "most likely" `DsContactValue` plus a scrollable
+"more" list — or a loading spinner, an empty state, or a locked/upsell banner instead.
+**Presentational only**: loading/empty/locked/collapse are driven entirely by props;
+every user action bubbles out as an event.
+
+### Props
+
+| Prop              | Type                     | Default           | Description                                                                                                    |
+| ----------------- | ------------------------ | ----------------- | -------------------------------------------------------------------------------------------------------------- |
+| `title`           | `string`                 | —                 | Card header title (required).                                                                                  |
+| `icon`            | `string`                 | `'email'`         | Material Icon name for the header (and the empty-state badge).                                                 |
+| `loading`         | `boolean`                | `false`           | Swaps the body for a centered spinner. Wins over `empty`/`locked`/data.                                        |
+| `loadingLabel`    | `string`                 | `''`              | Accessible name for the loading spinner (falls back to `DsSpinner`'s own default). Overridable via `#loading`. |
+| `locked`          | `boolean`                | `false`           | Locked/upsell state: shows a banner instead of content. Wins over `empty`/data (loading still wins over it).   |
+| `mostLikely`      | `DsContactDatum \| null` | `null`            | The highlighted "most likely" data point, rendered as a `main` `DsContactValue`.                               |
+| `more`            | `DsContactDatum[]`       | `[]`              | Additional data points, rendered in a scrollable "MORE" list.                                                  |
+| `collapsible`     | `boolean`                | `false`           | Shows a chevron toggle in the header that collapses/expands the body.                                          |
+| `showSort`        | `boolean`                | `true`            | Show the sort icon-button in the header.                                                                       |
+| `showEdit`        | `boolean`                | `false`           | Show the text "Edit" action in the header.                                                                     |
+| `showClose`       | `boolean`                | `false`           | Show the × close button in the header.                                                                         |
+| `isContactData`   | `boolean`                | `false`           | Forwarded to every `DsContactValue` (true for emails).                                                         |
+| `showRate`        | `boolean`                | `false`           | Forwarded to every `DsContactValue` — shows thumbs up/down rating on hover.                                    |
+| `editLabel`       | `string`                 | `'Edit'`          | Visible text for the edit action.                                                                              |
+| `emptyLabel`      | `string`                 | `'No data found'` | Title shown in the empty state (no `mostLikely` and no `more`).                                                |
+| `emptySubtitle`   | `string`                 | `''`              | Optional muted line under the empty title.                                                                     |
+| `lockedLabel`     | `string`                 | `'Locked'`        | Fallback text for the locked banner when no `#locked` slot is provided.                                        |
+| `mostLikelyLabel` | `string`                 | `'MOST LIKELY'`   | Section label above the "most likely" value (shown only when there are more than 3 items total).               |
+| `moreLabel`       | `string`                 | `'MORE'`          | Section label above the "more" list (shown only when there are more than 3 items total).                       |
+| `sortLabel`       | `string`                 | `'Sort'`          | `aria-label` for the sort icon-button.                                                                         |
+| `toggleLabel`     | `string`                 | `'Toggle'`        | `aria-label` for the collapse/expand icon-button.                                                              |
+| `closeLabel`      | `string`                 | `'Close'`         | `aria-label` for the × close button.                                                                           |
+
+### Events
+
+| Event       | Payload          | When                                                                           |
+| ----------- | ---------------- | ------------------------------------------------------------------------------ |
+| `copy`      | `string`         | A `DsContactValue` row's copy button was clicked. Payload is the copied value. |
+| `sort`      | —                | The header's sort icon-button was clicked.                                     |
+| `edit`      | —                | The header's "Edit" action was clicked.                                        |
+| `close`     | —                | The header's × close button was clicked.                                       |
+| `correct`   | `DsContactDatum` | A row's thumbs-up rating was clicked. Payload is that row's datum.             |
+| `incorrect` | `DsContactDatum` | A row's thumbs-down rating was clicked. Payload is that row's datum.           |
+
+### Accessibility
+
+- The root `<section>` carries `aria-label` (the card `title`) and `aria-busy="true"`
+  while `loading`.
+- The header's action row stops click-through to the collapsible header via `@click.stop`,
+  so toggling collapse doesn't fire when clicking sort/edit/toggle/close.
+- All icon-only header buttons (`sort`, `toggle`, `close`) carry an `aria-label` from
+  their respective `*Label` prop.
+
+### When to use
+
+- The primary card for a contact's emails or phones — pass `showRate` when the consuming
+  app supports data-quality feedback.
+- Use `locked` for gated/upsell data instead of hiding the card entirely; drive the CTA
+  via the `#locked` slot.
+- For a single value row outside this card layout, use `DsContactValue` directly.
+
+---
+
+<!-- DsEmptyState · Data -->
+
+## DsEmptyState
+
+Centered empty-state panel for empty tables, lists, or search results: an optional
+illustration, a title, an optional subtitle, and slots for an action (`#button`) and a
+pinned table header (`#table-header`). **Presentational only**: no events, all text
+arrives via props/slots.
+
+### Props
+
+| Prop            | Type      | Default | Description                                                                                                                 |
+| --------------- | --------- | ------- | --------------------------------------------------------------------------------------------------------------------------- |
+| `image`         | `string`  | `''`    | Illustration URL rendered above the title. Decorative — always renders with `alt=""`.                                       |
+| `title`         | `string`  | `''`    | Empty-state heading. Rendered as a styled `<p>`, never an `<h1>`, so it can't corrupt the consuming page's heading outline. |
+| `subtitle`      | `string`  | `''`    | Supporting copy under the title. Supports embedded line breaks (`white-space: pre-line`).                                   |
+| `roundedBorder` | `boolean` | `false` | Rounds the panel corners (DS `radius-card-lg`) instead of the default square edge.                                          |
+
+### Accessibility
+
+- The illustration renders with `alt=""` since it is purely decorative — the title/subtitle
+  carry the meaning.
+- The title is a plain `<p>`, not a semantic heading — if the empty state needs a real
+  heading in the page's outline, provide one via the `#table-header` slot or the
+  surrounding app markup.
+
+### When to use
+
+- Tables/lists with zero results — pair with `#table-header` to keep a column header
+  visible above the empty message.
+- First-run/onboarding panels, paired with a call-to-action via `#button`.
+
+---
+
+<!-- DsPaginator · Data -->
+
+## DsPaginator
+
+Page-window pagination control: prev/next chevrons, numbered page buttons that collapse
+into ellipses past 7 pages, and a page-size `<select>`. **Presentational only**: it owns
+no page state itself — the consuming app supplies `currentPage`/`pageSize` and reacts to
+its events.
+
+### Props
+
+| Prop              | Type       | Default             | Description                                                                         |
+| ----------------- | ---------- | ------------------- | ----------------------------------------------------------------------------------- |
+| `total`           | `number`   | — (required)        | Total number of items being paginated; drives `pageCount` together with `pageSize`. |
+| `pageSize`        | `number`   | `25`                | Items per page.                                                                     |
+| `currentPage`     | `number`   | `1`                 | 1-based current page.                                                               |
+| `pageSizes`       | `number[]` | `[10, 25, 50, 100]` | Options rendered in the page-size `<select>`.                                       |
+| `limitMessage`    | `string`   | `''`                | Optional message shown before the pager (e.g. `"Showing 1-25 of 500"`).             |
+| `pageSizeSuffix`  | `string`   | `''`                | Appended to each page-size option label (e.g. consumer passes `'/page'`).           |
+| `prevLabel`       | `string`   | `''`                | `aria-label` for the icon-only prev chevron button.                                 |
+| `nextLabel`       | `string`   | `''`                | `aria-label` for the icon-only next chevron button.                                 |
+| `paginationLabel` | `string`   | `''`                | `aria-label` for the root `<nav>`.                                                  |
+| `pageSizeLabel`   | `string`   | `''`                | `aria-label` for the page-size `<select>`.                                          |
+
+### Events
+
+| Event              | Payload  | When                                                                                        |
+| ------------------ | -------- | ------------------------------------------------------------------------------------------- |
+| `page-change`      | `number` | A page button or a prev/next chevron was activated with a valid target page (1..pageCount). |
+| `page-size-change` | `number` | A new page-size option was chosen in the `<select>`.                                        |
+
+### Accessibility
+
+- The root is a `<nav>` — pass `paginationLabel` to give it an accessible name.
+- Prev/next chevrons are icon-only `DsButton`s — pass `prevLabel`/`nextLabel` or they
+  render without an `aria-label`.
+- The active page button carries `aria-current="page"`.
+- Ellipsis entries are `aria-hidden="true"` (decorative, not a control).
+- Prev/next disable natively (`disabled`) at the first/last page.
+
+### When to use
+
+- Any paged table or list where the consumer owns the current page/page-size state.
+
+---
+
+<!-- DsPill · Data -->
+
+## DsPill
+
+Small solid capsule with white text and a free-form background color (e.g. a dynamic
+tag/folder color), with an optional trailing icon button. **Presentational only**:
+label via the default slot, intent out via `click`.
+
+### Props
+
+| Prop         | Type     | Default | Description                                                                                                                    |
+| ------------ | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `icon`       | `string` | `''`    | Material Icons ligature name; when set, renders a trailing icon button.                                                        |
+| `background` | `string` | `''`    | Free-form CSS color (e.g. a dynamic tag/folder color); when empty, falls back to the default token background (`$slate-soft`). |
+| `iconLabel`  | `string` | `''`    | Accessible name for the trailing icon button (icon-only control).                                                              |
+
+### Events
+
+| Event   | Payload | When                                                                                      |
+| ------- | ------- | ----------------------------------------------------------------------------------------- |
+| `click` | —       | The trailing icon button was clicked. Only fires when `icon` is set — no icon, no button. |
+
+### Accessibility
+
+- The trailing icon button is icon-only, so `iconLabel` maps to its `aria-label` — always
+  pass it when using `icon`.
+- The icon glyph itself is `aria-hidden="true"`; only the button's `aria-label` is announced.
+- Long text truncates with an ellipsis instead of stretching the pill — the consumer must
+  bound the pill's width for this to trigger.
+
+### When to use
+
+- Tags/labels with a dynamic color (folder color, CRM tag color), optionally with a way
+  to remove/edit them via the icon button.
+- For a bordered, button-styled filter chip instead, see `DsPillWithBorder`.
+
+---
+
+<!-- DsPillWithBorder · Data -->
+
+## DsPillWithBorder
+
+Bordered pill/chip rendered as a real `<button>`, with an optional leading icon slot and
+a label from the default slot. **Presentational only**: no configurable props — content
+and click intent flow entirely through slots/events.
+
+### Props
+
+This component has no configurable props (its type contract is an intentionally empty
+interface, kept typed so it has a public contract to extend if the DS ever adds a
+variant/size). Content comes from the default slot (label) and the optional `#icon` slot
+(a pre-rendered leading icon node).
+
+### Events
+
+| Event   | Payload | When                                                                                                                |
+| ------- | ------- | ------------------------------------------------------------------------------------------------------------------- |
+| `click` | —       | The chip (the whole `<button>`) was activated — a mouse click or, via native `<button>` semantics, `Enter`/`Space`. |
+
+### Accessibility
+
+- Renders a real `<button>`, replacing the underlying Design System's non-interactive
+  `<div onClick>` — so it is keyboard-reachable and operable out of the box.
+- `:focus-visible` gets a visible outline ring.
+- The optional leading icon comes through the `#icon` slot; mark the icon node
+  `aria-hidden="true"` in the consumer's markup (as the examples below do) since the
+  button's accessible name is its text content.
+- Long labels truncate to a single line instead of wrapping — bound the chip's width to
+  trigger it.
+
+### When to use
+
+- Filter/segment chips (e.g. "Location", "Industry") that toggle a panel or apply a
+  filter on click.
+- For a solid, non-bordered tag-style pill instead, see `DsPill`.
+
+---
+
+<!-- DsRow · Data -->
+
+## DsRow
+
+A `<tr>` row for the `DsTable` compound API, with hover and selected treatment;
+`clickable` makes the whole row a keyboard-operable click target. **Presentational
+only**: always used inside a `<table>`/`<tbody>`, paired with `DsCell` children.
+
+### Props
+
+| Prop        | Type      | Default | Description                                                         |
+| ----------- | --------- | ------- | ------------------------------------------------------------------- |
+| `selected`  | `boolean` | `false` | Selected treatment (accent surface); wins over the hover state.     |
+| `clickable` | `boolean` | `false` | Makes the whole row an interactive, keyboard-operable click target. |
+
+### Events
+
+| Event   | Payload | When                                                                                                                                            |
+| ------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `click` | —       | The row was clicked, or activated via `Enter`/`Space` while focused. Only fires when `clickable` is `true` — a plain row is not a click target. |
+
+### Accessibility
+
+- `clickable` rows get `tabindex="0"` so they're keyboard-reachable; non-clickable rows
+  stay out of the tab order.
+- `Enter`/`Space` on a focused clickable row trigger the same `click` event as a mouse
+  click (`preventDefault()` stops the page from scrolling on `Space`).
+- `:focus-visible` gets a visible, inset outline ring so it doesn't clip against table
+  borders.
+- A pinned/sticky `DsCell` inside the row mirrors the row's hover/selected background via
+  `:deep()`, since it paints its own opaque background and can't inherit the row's colors.
+
+### When to use
+
+- Table body rows; pair `clickable` with rows that navigate to a detail view or open a
+  panel.
+- Combine with `selected` to reflect a row chosen elsewhere (a checkbox, external state).
+
+---
+
+<!-- DsSegmentedProgressBar · Data -->
+
+## DsSegmentedProgressBar
+
+Horizontal, multi-segment data-viz track (e.g. a verification-quality breakdown), with an
+optional legend beneath it. **Presentational only**: given `segments` and a `total`, it
+renders proportional colored bars — no events.
+
+### Props
+
+| Prop         | Type                                               | Default | Description                                                                                                              |
+| ------------ | -------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `segments`   | `DsProgressSegment[]` (`{ name?, amount, color }`) | `[]`    | The bar's segments; each renders as `amount / total` of the track width in `color`.                                      |
+| `total`      | `number`                                           | `100`   | The denominator. Segments summing under `total` leave the remainder as track background; segments must not exceed it.    |
+| `height`     | `number`                                           | `8`     | Track height in px.                                                                                                      |
+| `label`      | `string`                                           | `''`    | Accessible name for the whole track (`aria-label` on the `role="img"` element). Omitted from the DOM when empty.         |
+| `showLegend` | `boolean`                                          | `false` | Render an auto-generated color↔name legend below the track, for every _named_ segment. No-op if no segment has a `name`. |
+
+### Slots
+
+| Slot     | Description                                                                                                  |
+| -------- | ------------------------------------------------------------------------------------------------------------ |
+| `legend` | Replaces the auto-generated legend with custom content; implies a legend is shown even without `showLegend`. |
+
+### Accessibility
+
+- The track has `role="img"` and takes its accessible name entirely from the `label`
+  prop — always pass a summary (e.g. `"55% verified, 25% risky, 20% invalid"`), since
+  there is no other text alternative.
+- The auto legend is `aria-hidden` (it duplicates the `label` summary visually, not
+  semantically); a custom `#legend` slot is not forced hidden, since the consumer owns its
+  semantics.
+
+### When to use
+
+- A known, static percentage/quota breakdown by category (e.g. email verification quality).
+- For an indeterminate loading state use `DsSpinner` instead; for a linear multi-step flow
+  use `DsWizardStepper`.
+
+---
+
+<!-- DsTable · Data -->
+
+## DsTable
+
+Data-dense table with two composition modes: **declarative** (`columns` + `rows`, with
+per-cell slot overrides) and **compound** (opt-in shell where the consumer composes
+`DsRow`/`DsCell` in the default slot). Supports column pinning, a fixed row height,
+loading/empty states, and an optional "most likely" row highlight. **Presentational
+only**: sorting, pagination, and selection state all live in the consuming app.
+
+### Props
+
+| Prop             | Type                                                                         | Default | Description                                                                                                                            |
+| ---------------- | ---------------------------------------------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| `columns`        | `DsTableColumn[]` (`{ key, label, align?, width?, pinned? }`)                | `[]`    | Declarative API: column definitions.                                                                                                   |
+| `rows`           | `DsTableRow[]` (`{ id, [key]: unknown }`)                                    | `[]`    | Declarative API: row data, keyed by `id`.                                                                                              |
+| `emptyMessage`   | `string`                                                                     | `''`    | Text shown in the empty state (declarative API); overridable via the `empty` slot.                                                     |
+| `highlightRowId` | `string \| number \| null`                                                   | `null`  | Row `id` to render with the "most likely" accent surface.                                                                              |
+| `rowHeight`      | `string \| number \| null`                                                   | `null`  | Fixed row height (number → px). Pins row height and truncates overflowing cell text with an ellipsis.                                  |
+| `compound`       | `boolean`                                                                    | `false` | Opt into the compound shell: headers + sticky `thead` from `headers`, body from the default slot (`DsRow`/`DsCell`) instead of `rows`. |
+| `headers`        | `(string \| DsTableHeader)[]` (`DsTableHeader = { label, pinned?, width? }`) | `[]`    | Compound API: header labels, or the object form to pin/size a header column.                                                           |
+| `selectable`     | `boolean`                                                                    | `false` | Compound API: render a leading select-all checkbox column.                                                                             |
+| `allSelected`    | `boolean`                                                                    | `false` | Compound API: checked state of the select-all checkbox.                                                                                |
+| `someSelected`   | `boolean`                                                                    | `false` | Compound API: indeterminate state of the select-all checkbox (when not `allSelected`).                                                 |
+| `selectAllLabel` | `string`                                                                     | `''`    | `aria-label` for the select-all checkbox (no visible text in its narrow column).                                                       |
+| `height`         | `string \| number \| null`                                                   | `null`  | Compound API: fixed wrapper height, enabling the sticky-header scroll.                                                                 |
+| `loading`        | `boolean`                                                                    | `false` | Shows a single centered spinner row spanning every column, instead of rows/empty (wins over both).                                     |
+| `loadingLabel`   | `string`                                                                     | `''`    | Accessible name for the loading spinner; overridable via the `loading` slot.                                                           |
+
+### Slots
+
+| Slot                | Description                                                                                                        |
+| ------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| `cell-<column.key>` | Declarative API: custom cell content for a given column; receives `{ row }`. Default content is `row[column.key]`. |
+| `empty`             | Declarative API: custom empty-state content, overriding `emptyMessage`.                                            |
+| `loading`           | Both APIs: custom loading content, overriding the default `DsSpinner`.                                             |
+| default             | Compound API: the table body — compose `DsRow`/`DsCell` here.                                                      |
+
+### Events
+
+| Event        | Payload   | When                                               |
+| ------------ | --------- | -------------------------------------------------- |
+| `select-all` | `boolean` | Compound API: the select-all checkbox was toggled. |
+
+### Accessibility
+
+- `aria-busy="true"` is set on the table root while `loading`.
+- The select-all checkbox (compound API) takes its accessible name from `selectAllLabel`,
+  since its column has no visible text.
+- Pinned columns keep an opaque background and a directional shadow so sticky content
+  stays legible over what scrolls beneath it.
+
+### When to use
+
+- Any dense, tabular dataset — the declarative API for simple column/row data, the
+  compound API when rows need custom composition (checkboxes, rich cells) beyond a single
+  per-column slot.
+- For a single deterministic quota/percentage breakdown instead of tabular rows, use
+  `DsSegmentedProgressBar`.
+
+---
+
+<!-- DsVerificationIcon · Data -->
+
+## DsVerificationIcon
+
+Status glyph for a contact data point (email/phone): verified, unverified, or newly
+found. **Presentational only**: no events, its state is derived entirely from the
+`verified` prop.
+
+### Props
+
+| Prop            | Type              | Default | Description                                                                                          |
+| --------------- | ----------------- | ------- | ---------------------------------------------------------------------------------------------------- |
+| `verified`      | `boolean \| null` | `null`  | `true` = verified, `false` = not verified, `null`/undefined = newly found.                           |
+| `isContactData` | `boolean`         | `false` | Emails (`true`) use the coral "dangerous" glyph when unverified; phones use orange.                  |
+| `size`          | `number`          | `20`    | Glyph size in px (`font-size`).                                                                      |
+| `label`         | `string`          | `''`    | Override for the accessible label / tooltip (the app owns i18n). Empty → English default from state. |
+
+### Accessibility
+
+- Renders as `role="img"` with `aria-label` (and mirrored `title`) set from `label` or
+  the derived state label ("Verified", "Not verified", "Newly found").
+- Color alone never carries the meaning — the underlying glyph (`verified`, `dangerous`/`error`,
+  `new_releases`) also changes per state.
+
+### When to use
+
+- Always paired with a contact value — `DsContactValue` renders it automatically for
+  each email/phone row; use it standalone only when building a custom data row.
+
+---
+
+<!-- DsAlert · Feedback -->
+
+## DsAlert
+
+Inline banner for status/confirmation messages (success, info, warning, error). It
+renders in place — not fixed to the viewport — and can be dismissed with an optional ×
+button. **Presentational only**: it tracks its own open/closed state internally, but a
+consumer can opt into controlling it via `v-model:visible`.
+
+### Props
+
+| Prop          | Type                                          | Default   | Description                                                       |
+| ------------- | --------------------------------------------- | --------- | ----------------------------------------------------------------- |
+| `type`        | `'success' \| 'info' \| 'warning' \| 'error'` | `'info'`  | Semantic style + icon.                                            |
+| `effect`      | `'light' \| 'dark'`                           | `'light'` | `light` = tinted bg + mid border; `dark` = solid bg + white text. |
+| `title`       | `string`                                      | `''`      | Bold heading line (or use the `#title` slot for rich content).    |
+| `description` | `string`                                      | `''`      | Body copy (or use the default slot for rich content).             |
+| `showIcon`    | `boolean`                                     | `false`   | Show the leading type icon.                                       |
+| `closable`    | `boolean`                                     | `false`   | Show the × dismiss button.                                        |
+| `center`      | `boolean`                                     | `false`   | Center-align the alert's content.                                 |
+| `boldTitle`   | `boolean`                                     | `false`   | Force the title to bold weight even without a body.               |
+| `closeLabel`  | `string`                                      | `''`      | `aria-label` for the × button (icon-only control).                |
+| `visible`     | `boolean`                                     | `true`    | `v-model:visible` — opt-in controlled visibility from the parent. |
+
+### Events
+
+| Event            | Payload   | When                                                                        |
+| ---------------- | --------- | --------------------------------------------------------------------------- |
+| `close`          | —         | The × button was clicked (self-dismiss).                                    |
+| `update:visible` | `boolean` | Companion event of `v-model:visible` — fires `false` when the alert closes. |
+
+### Accessibility
+
+- The root carries `role="alert"` so assistive tech announces it.
+- The × button is icon-only, so `closeLabel` maps to its `aria-label` — always pass it
+  when `closable` is set.
+- The mount/dismiss fade transition respects `prefers-reduced-motion` (no transition
+  when reduced motion is requested).
+
+### When to use
+
+- Inline, persistent status or confirmation messages that live alongside content. For
+  transient, viewport-fixed toasts use `DsNotification` instead.
+- Pass `closable` + `closeLabel` whenever the user should be able to dismiss it
+  themselves; use `v-model:visible` when the parent also needs to reopen it later.
+
+---
+
+<!-- DsModal · Feedback -->
+
+## DsModal
+
+Centered dialog with an optional header (title + close button) and footer action row.
+Portal-based by default (`fixed`), with a focus trap, scroll lock, and Escape-to-close;
+opting out of `fixed` renders it in-flow for specimen/embedded use. **Presentational
+only**: it never closes itself — the consumer holds the `open` boolean and flips it off
+on `close`.
+
+### Props
+
+| Prop              | Type      | Default   | Description                                                                                                                                                  |
+| ----------------- | --------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `open`            | `boolean` | `false`   | Controls dialog visibility.                                                                                                                                  |
+| `title`           | `string`  | `''`      | Optional heading text; shows the header row (with `showClose`).                                                                                              |
+| `showClose`       | `boolean` | `true`    | Show the icon-only × close button in the header.                                                                                                             |
+| `width`           | `string`  | `'440px'` | Dialog width (any CSS length).                                                                                                                               |
+| `height`          | `string`  | `''`      | Explicit dialog height (any CSS length). Empty = content height.                                                                                             |
+| `top`             | `string`  | `'15vh'`  | Top offset of the dialog inside the fixed backdrop (portal mode).                                                                                            |
+| `center`          | `boolean` | `false`   | Center-align the body text.                                                                                                                                  |
+| `fixed`           | `boolean` | `true`    | `true` portals to `body` with a backdrop, focus trap, scroll lock and Escape-to-close. `false` renders in-flow with none of that, for specimen/embedded use. |
+| `closeOnBackdrop` | `boolean` | `true`    | Clicking the backdrop emits `close` (portal mode only).                                                                                                      |
+| `closeOnEscape`   | `boolean` | `true`    | Pressing Escape emits `close` (portal mode only).                                                                                                            |
+| `closeLabel`      | `string`  | `'Close'` | `aria-label` for the icon-only close button.                                                                                                                 |
+
+### Slots
+
+| Slot     | Description                                                                            |
+| -------- | -------------------------------------------------------------------------------------- |
+| default  | Dialog body content.                                                                   |
+| `footer` | Optional action row (buttons); the footer block is omitted entirely when not provided. |
+
+### Events
+
+| Event   | Payload | When                                                                                                                               |
+| ------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| `close` | —       | The × button was clicked, the backdrop was clicked (`closeOnBackdrop`), or Escape was pressed (`closeOnEscape`, portal mode only). |
+
+> The dialog never closes itself — the consumer must set `open` to `false` on `close`.
+
+### Accessibility
+
+- `role="dialog"` with `aria-modal="true"` in portal mode (`fixed`), `"false"` when in-flow.
+- `aria-labelledby` points at the title when set; falls back to `aria-label="dialog"` when
+  there is no title.
+- Focus trap (portal mode): Tab/Shift+Tab cycles within the dialog; focus moves to the
+  first focusable element on open and restores to the previously focused element on close.
+- Escape closes the dialog when `closeOnEscape` is true (portal mode only).
+- Body scroll locks (`overflow: hidden`) while a fixed/open modal is mounted.
+
+### When to use
+
+- Blocking decisions or confirmations (delete, discard changes) — pair with the `footer`
+  slot for the action buttons.
+- Use `fixed="false"` only for a static, in-flow specimen; real usage should keep the
+  portal, focus trap, and scroll lock.
+- For transient, non-blocking feedback use `DsNotification` instead.
+
+---
+
+<!-- DsNotification · Feedback -->
+
+## DsNotification
+
+Fixed-position toast card for transient feedback (saved, updated, failed…). It renders
+itself into one of the four viewport corners, optionally auto-dismisses, and can carry a
+single action link. **Presentational only**: it owns its own visibility timer, but all
+routing/consequences stay with the consuming app via events.
+
+### Props
+
+| Prop          | Type                                                           | Default         | Description                                                                   |
+| ------------- | -------------------------------------------------------------- | --------------- | ----------------------------------------------------------------------------- |
+| `type`        | `'success' \| 'info' \| 'warning' \| 'error'`                  | `'info'`        | Semantic style + icon.                                                        |
+| `position`    | `'top-left' \| 'top-right' \| 'bottom-left' \| 'bottom-right'` | `'bottom-left'` | Viewport corner the toast fixes to.                                           |
+| `title`       | `string`                                                       | —               | Bold heading line.                                                            |
+| `description` | `string`                                                       | —               | Body copy under the title.                                                    |
+| `link`        | `string`                                                       | —               | `href` for the optional action link.                                          |
+| `linkTitle`   | `string`                                                       | —               | Visible text for the link (required for the link to render).                  |
+| `linkTarget`  | `'_blank' \| '_self' \| '_parent' \| '_top'`                   | `'_blank'`      | `<a target>`. `_blank` adds `rel="noopener noreferrer"`.                      |
+| `showClose`   | `boolean`                                                      | `true`          | Show the × dismiss button.                                                    |
+| `closeLabel`  | `string`                                                       | `'Close'`       | `aria-label` for the × button (icon-only control).                            |
+| `duration`    | `number`                                                       | `0`             | Auto-dismiss delay in ms. `0` = stays until dismissed. Timer pauses on hover. |
+
+### Events
+
+| Event      | Payload      | When                                                                                     |
+| ---------- | ------------ | ---------------------------------------------------------------------------------------- |
+| `close`    | —            | The toast dismissed itself (× click or auto-dismiss timer).                              |
+| `navigate` | `MouseEvent` | The action link was clicked. `preventDefault()` it to route in-app with your own router. |
+
+> The link is a real `<a href>` (a11y + no-JS fallback). Default behaviour opens it natively;
+> listen to `navigate` and call `event.preventDefault()` to intercept and route inside the SPA.
+
+### Accessibility
+
+- The × button is icon-only, so `closeLabel` maps to its `aria-label` — always pass it.
+- Auto-dismiss (`duration > 0`) pauses while the pointer hovers the toast, so users get time to read.
+
+### When to use
+
+- Transient, non-blocking confirmations or errors. For blocking decisions use `DsModal`;
+  for inline persistent messages use `DsAlert`.
+
+---
+
+<!-- DsTooltip · Feedback -->
+
+## DsTooltip
+
+Dark bubble that describes a wrapped trigger on hover or keyboard focus, with 4-way
+placement. **Presentational only**: pure-CSS positioning, no floating-ui dependency, no
+events.
+
+### Props
+
+| Prop        | Type                                     | Default | Description                                                                                                                     |
+| ----------- | ---------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| `content`   | `string`                                 | `''`    | Bubble text. Use the `content` slot instead for rich content.                                                                   |
+| `placement` | `'top' \| 'bottom' \| 'left' \| 'right'` | `'top'` | Side of the trigger the bubble anchors to.                                                                                      |
+| `delay`     | `number`                                 | `300`   | Hover delay before showing, in ms. Keyboard focus always shows immediately.                                                     |
+| `block`     | `boolean`                                | `false` | Wrap a full-width/block trigger (e.g. `DsInput`) instead of the default `inline-flex`, so it doesn't get squashed.              |
+| `disabled`  | `boolean`                                | `false` | Force the tooltip off regardless of `content`/slot — lets a consumer show it only under a condition (e.g. only when truncated). |
+
+### Slots
+
+| Slot      | Description                                         |
+| --------- | --------------------------------------------------- |
+| default   | The trigger element(s) the tooltip wraps.           |
+| `content` | Rich bubble content, overriding the `content` prop. |
+
+### Accessibility
+
+- The bubble has `role="tooltip"`; the focused/hovered trigger gets `aria-describedby`
+  pointing at it (any pre-existing `aria-describedby` value is preserved and restored on hide).
+- Hover and keyboard focus are tracked independently — the tooltip stays open as long as
+  either is active, so moving the mouse away while still focused (or vice versa) doesn't hide it.
+- Escape hides an open tooltip.
+- Respects `prefers-reduced-motion` (the fade transition is skipped).
+
+### When to use
+
+- Short, supplementary hints on icon-only controls or truncated text — icon-only triggers
+  still need their own `aria-label`, since the tooltip is not a substitute for an accessible name.
+- For a persistent inline message use `DsAlert`; for a blocking one use `DsModal`.
+
+---
+
+<!-- DsCheckbox · Forms -->
+
+## DsCheckbox
+
+Checked / unchecked / indeterminate selection control. **Presentational only**.
+Binds via `v-model` (its `modelValue` is the checked boolean).
+
+### Props
+
+| Prop            | Type      | Default | Description                                                                                  |
+| --------------- | --------- | ------- | -------------------------------------------------------------------------------------------- |
+| `modelValue`    | `boolean` | `false` | v-model — checked state.                                                                     |
+| `indeterminate` | `boolean` | `false` | Visual "mixed" state (dash icon); kept in sync with the native DOM `indeterminate` property. |
+| `disabled`      | `boolean` | `false` | Disables the control and dims the whole label to 50% opacity.                                |
+| `name`          | `string`  | `''`    | Native `name` attribute.                                                                     |
+| `label`         | `string`  | `''`    | Visible label text; overridden by the default slot when present.                             |
+| `ariaLabel`     | `string`  | `''`    | Accessible name when there is no visible label (e.g. a "select all" checkbox in a table).    |
+
+### Events
+
+| Event               | Payload   | When                                                      |
+| ------------------- | --------- | --------------------------------------------------------- |
+| `update:modelValue` | `boolean` | The checkbox was toggled (click, or Space while focused). |
+
+### Accessibility
+
+- The native `<input type="checkbox">` is visually hidden (clip-rect pattern) but drives state, keyboard activation (Space), and focus — the DS box and check/dash mark are purely decorative (`aria-hidden`).
+- A focus ring (`:focus-visible`) renders on the decorative box when the native input is focused.
+- `indeterminate` is set as a DOM **property** (`el.indeterminate`), matching how assistive tech and CSS `:indeterminate` expect it — it is not exposed as an HTML attribute.
+- Pass `ariaLabel` (or wrap in your own `<label>`) whenever there is no visible `label`/slot text.
+
+### When to use
+
+- Independent on/off choices, or multi-select in a list/table (e.g. bulk selection with an indeterminate "select all").
+- For mutually exclusive single-choice options use `DsRadio`; for a single setting that takes effect immediately (not a form field to submit) consider `DsSwitch`.
+
+---
+
+<!-- DsInput · Forms -->
+
+## DsInput
+
+Single-line text field — the DS "Input". **Presentational only**: it drives its own
+password-reveal state and field-exit detection, but no store/HTTP access. Binds
+via `v-model` (its `modelValue` is the current string value).
+
+### Props
+
+| Prop            | Type                                                                        | Default     | Description                                                                                                                                              |
+| --------------- | --------------------------------------------------------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `modelValue`    | `string`                                                                    | `''`        | v-model — current text value.                                                                                                                            |
+| `type`          | `'text' \| 'email' \| 'password' \| 'tel' \| 'number' \| 'search' \| 'url'` | `'text'`    | Native input type. `password` renders a reveal toggle when `toggleLabel` is set; `search` always renders as a styled text input with a left search icon. |
+| `size`          | `'sm' \| 'md'`                                                              | `'sm'`      | Control height (36px / 48px).                                                                                                                            |
+| `placeholder`   | `string`                                                                    | `''`        | Native placeholder text.                                                                                                                                 |
+| `disabled`      | `boolean`                                                                   | `false`     | Disables the control.                                                                                                                                    |
+| `error`         | `boolean`                                                                   | `false`     | Error visual state (`aria-invalid`, coral border).                                                                                                       |
+| `errorMessage`  | `string`                                                                    | `''`        | Message shown under the field when `error` is true.                                                                                                      |
+| `showErrorIcon` | `boolean`                                                                   | `false`     | Shows a warning icon in the suffix when `error` is true.                                                                                                 |
+| `name`          | `string`                                                                    | `''`        | Native `name` attribute.                                                                                                                                 |
+| `id`            | `string`                                                                    | `''`        | Native `id`; also links the error message via `aria-describedby`.                                                                                        |
+| `autocomplete`  | `string`                                                                    | `''`        | Native `autocomplete` attribute.                                                                                                                         |
+| `toggleLabel`   | `string`                                                                    | `''`        | Accessible name for the password-reveal toggle button (`type="password"` only). No label → no toggle.                                                    |
+| `min`           | `number \| string`                                                          | `undefined` | Native `min` (relevant for `type="number"`).                                                                                                             |
+| `max`           | `number \| string`                                                          | `undefined` | Native `max` (relevant for `type="number"`).                                                                                                             |
+| `step`          | `number \| string`                                                          | `undefined` | Native `step` (relevant for `type="number"`).                                                                                                            |
+
+### Events
+
+| Event               | Payload      | When                                                                                                                      |
+| ------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------- |
+| `update:modelValue` | `string`     | Emitted continuously as the user types (v-model).                                                                         |
+| `focus`             | `FocusEvent` | The native input gained focus.                                                                                            |
+| `blur`              | `FocusEvent` | The native input lost focus — fires even when focus only moved to the component's own password toggle.                    |
+| `change`            | `Event`      | Native `change` — fires on blur/Enter once the value actually changed (distinct from the continuous `update:modelValue`). |
+| `field-blur`        | `FocusEvent` | Focus left the **whole** component (not just moved to the internal toggle) — the "real field exit" signal.                |
+
+### Accessibility
+
+- `aria-invalid` is set when `error` is true; `aria-describedby` links to the error message (`{id}-error`) when both `id` and `errorMessage` are present.
+- The password-reveal button is icon-only, so it only renders once `toggleLabel` is supplied (its `aria-label`), and exposes `aria-pressed` for its toggled state.
+- Text goes bold on focus (except `type="search"`, which stays regular) — a DS-specific affordance, not just a border change.
+- Exposes `focus()` and `focusAtEnd()` via `defineExpose` for imperative control (e.g. focusing a field after a panel opens) from the consuming app.
+
+### When to use
+
+- Any single-line text/email/password/tel/number/url/search field in a form.
+- Use `DsTextarea` instead for multi-line content.
+
+---
+
+<!-- DsItemSelectorButton · Forms -->
+
+## DsItemSelectorButton
+
+Pill-shaped trigger that shows the currently assigned item (folder, tag, owner…)
+or an empty-state prompt, and emits `click` to open an external picker.
+**Presentational only** — it holds no v-model and owns no picker/menu of its own,
+only the current selection it's handed via `item`.
+
+### Props
+
+| Prop         | Type                     | Default | Description                                                                                                                                                                                            |
+| ------------ | ------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `item`       | `DsSelectorItem \| null` | `null`  | Selected item (`{ name, color? }`); `null`/absent renders the empty state.                                                                                                                             |
+| `icon`       | `string`                 | `''`    | Material Icons ligature (e.g. `folder`); omitted entirely (no icon rendered) when unset.                                                                                                               |
+| `emptyTitle` | `string`                 | `''`    | Visible label shown when `item` is empty.                                                                                                                                                              |
+| `ariaLabel`  | `string`                 | `''`    | Accessible name for the button. Required when the empty state has no `emptyTitle` (otherwise the button would have no name); when `item.name`/`emptyTitle` render, that visible text already names it. |
+| `disabled`   | `boolean`                | `false` | Disables the button (opacity 0.6) and blocks the click handler.                                                                                                                                        |
+
+### Events
+
+| Event   | Payload      | When                                                                                     |
+| ------- | ------------ | ---------------------------------------------------------------------------------------- |
+| `click` | `MouseEvent` | The button was clicked (to open an external item picker) — not emitted while `disabled`. |
+
+### Accessibility
+
+- `aria-haspopup="listbox"` signals that activating the button opens a picker.
+- The label truncates with ellipsis at ~200px so long names stay legible; the full name is still the button's accessible name via the visible text node.
+- Pass `ariaLabel` whenever the empty state has no `emptyTitle` — otherwise the button has no accessible name.
+- Native `<button>` gets Enter/Space activation and a focus ring (`:focus-visible`) for free.
+
+### When to use
+
+- A compact trigger showing "what's currently assigned" (folder, tag, owner) that opens an external picker/menu on click.
+- The picker/menu itself is not part of this component — pair it with `DsSelect`, a custom dropdown, or a modal owned by the consuming app.
+
+---
+
+<!-- DsRadio · Forms -->
+
+## DsRadio
+
+A single radio control (accent-ring dot when checked). **Presentational only**.
+Binds via `v-model` (its `modelValue` is the checked boolean of **this** radio —
+not a shared group value).
+
+### Props
+
+| Prop         | Type      | Default | Description                                                                                  |
+| ------------ | --------- | ------- | -------------------------------------------------------------------------------------------- |
+| `modelValue` | `boolean` | `false` | v-model — checked state of this radio.                                                       |
+| `disabled`   | `boolean` | `false` | Disables the control (opacity 0.6).                                                          |
+| `label`      | `string`  | `''`    | Visible label text; overridden by the default slot when present.                             |
+| `name`       | `string`  | `''`    | Shared across a set of `DsRadio` to get native radio-group keyboard navigation (arrow keys). |
+| `value`      | `string`  | `''`    | Identifies this radio within its native `name` group.                                        |
+
+### Events
+
+| Event               | Payload   | When                                                                                                                                                             |
+| ------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `update:modelValue` | `boolean` | Always `true` — native radios never emit `false` on themselves; the app drives exclusivity by setting every other radio in the group's `model-value` to `false`. |
+
+### Accessibility
+
+- The native `<input type="radio">` is visually hidden but drives keyboard/focus/state; the DS dot is decorative (`aria-hidden`).
+- Sharing `name` across instances enables native arrow-key navigation between radios in the group — the app still owns which one reads as "selected" via each instance's `model-value`.
+- A focus ring (`:focus-visible`) renders on the decorative dot.
+- Pass `label`/slot text (or wrap in your own `<label>`) so the control has an accessible name.
+
+### When to use
+
+- A small, fixed set of mutually exclusive options where every choice should stay visible (contact type, plan tier).
+- For a longer list, or when only one option needs to be visible at a time, prefer `DsSelect`.
+
+---
+
+<!-- DsSelect · Forms -->
+
+## DsSelect
+
+Dropdown select — a native-`<select>`-like single/multi picker with a real
+interaction model (button trigger, `listbox`/`option` ARIA roles, full keyboard
+support) per the WAI-ARIA APG "Collapsible Dropdown Listbox" pattern.
+**Presentational only**: it owns its own open/closed and keyboard-navigation
+state, but no store/HTTP access — remote filtering and async loading are driven
+entirely by props the app passes in. Binds via `v-model`: scalar when `multiple`
+is false, an array of values when `multiple` is true.
+
+### Props
+
+| Prop                | Type                                                                     | Default              | Description                                                                                                                                                |
+| ------------------- | ------------------------------------------------------------------------ | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `modelValue`        | `string \| number \| (string \| number)[] \| null`                       | `null`               | v-model. Scalar when `multiple` is false, array of selected values when `multiple` is true.                                                                |
+| `options`           | `DsSelectOption[]` (required)                                            | —                    | The option list. Each option: `{ value, label, subLabel?, icon?, color?, group? }`.                                                                        |
+| `placeholder`       | `string`                                                                 | `'Select an option'` | Text shown when nothing is selected (and the label prefix for `filterSummary` mode).                                                                       |
+| `multiple`          | `boolean`                                                                | `false`              | Multi-select — the modelValue becomes an array and the dropdown stays open between picks.                                                                  |
+| `selectType`        | `'default' \| 'filterSummary'`                                           | `'default'`          | Visual style: grey pill, or the accent "filter chip" that flips color once something is selected.                                                          |
+| `showCheckbox`      | `boolean`                                                                | `false`              | Renders a (decorative, disabled) `DsCheckbox` next to each option; in single-select this also lets clicking the selected option deselect it.               |
+| `width`             | `'auto' \| 'small' \| 'medium' \| 'large' \| 'full' \| number \| string` | `'auto'`             | A named width step (fixed/stable), `'full'` (100% of the container), a custom number (px), or any CSS width string. `'auto'` shrinks to the label content. |
+| `disabled`          | `boolean`                                                                | `false`              | Disables the trigger and closes the dropdown if it was open.                                                                                               |
+| `filterable`        | `boolean`                                                                | `false`              | Renders a type-to-filter search input inside the open dropdown.                                                                                            |
+| `remote`            | `boolean`                                                                | `false`              | Skips the built-in local filter (no effect unless `filterable` is also set) — pair with the `search` event to filter server-side without double-filtering. |
+| `loading`           | `boolean`                                                                | `false`              | Shows a spinner (`#loading` slot to override) instead of options/empty state, with `aria-busy` on the listbox.                                             |
+| `searchLabel`       | `string`                                                                 | `'Filter options'`   | Accessible name (`aria-label`) for the filter search input.                                                                                                |
+| `searchPlaceholder` | `string`                                                                 | `'Search'`           | Visible placeholder for the filter search input.                                                                                                           |
+| `clearLabel`        | `string`                                                                 | `'Clear selection'`  | Accessible name for the `filterSummary` clear (×) button.                                                                                                  |
+| `emptyText`         | `string`                                                                 | `'No options'`       | Shown when the (possibly filtered) option list is empty; overridable via the `#empty` slot.                                                                |
+
+### Events
+
+| Event               | Payload                                             | When                                                                                                                                      |
+| ------------------- | --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `update:modelValue` | Current selection (scalar or array, per `multiple`) | An option was picked/toggled, or the clear (×) button ran.                                                                                |
+| `search`            | `string` (the typed filter text)                    | The filter input changed while `filterable`, or the dropdown closed with a non-empty query (emits `''` so a `remote` consumer can reset). |
+
+### Slots
+
+| Slot      | Scope                          | Description                                                                                        |
+| --------- | ------------------------------ | -------------------------------------------------------------------------------------------------- |
+| `option`  | `{ option, selected, active }` | Custom per-option content (avatar, arbitrary markup); the default renders icon + label + subLabel. |
+| `loading` | —                              | Overrides the default `DsSpinner` shown while `loading` is true.                                   |
+| `empty`   | —                              | Overrides the default `emptyText` message.                                                         |
+
+### Accessibility
+
+- Implements the WAI-ARIA APG "Collapsible Dropdown Listbox" (select-only combobox) pattern: `aria-haspopup="listbox"`, `aria-expanded`, `aria-controls`, `role="listbox"`/`role="option"`, `aria-selected`, `aria-activedescendant`.
+- Full keyboard support on the trigger: `ArrowUp`/`ArrowDown` open/navigate, `Home`/`End` jump, `Enter`/`Space` select, `Escape` closes (and stops propagation, so an ancestor `DsModal` doesn't also close), `Tab` collapses without stealing focus.
+- Grouped options (`option.group`) render as real `role="group"` regions labelled by their header; headers are never focusable/selectable.
+- When `filterable`, the search input carries `role="combobox"` and owns `aria-activedescendant` while open (focus moves there instead of staying on the trigger).
+- The `filterSummary` clear button is icon-only, so `clearLabel` maps to its `aria-label`.
+
+### When to use
+
+- A single- or multi-value picker from a short-to-medium list of options (with optional grouping, icons, or search).
+- For a small, fixed set of mutually exclusive choices that should all stay visible at once, prefer `DsRadio`.
+
+---
+
+<!-- DsSwitch · Forms -->
+
+## DsSwitch
+
+On/off toggle (accent track when on). **Presentational only**: it reflects the
+`modelValue`/`loading` it's given and owns no async logic itself. Binds via
+`v-model` (its `modelValue` is the on/off boolean).
+
+### Props
+
+| Prop         | Type      | Default     | Description                                                                                                                                                                                                                                                       |
+| ------------ | --------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `modelValue` | `boolean` | `false`     | v-model — on/off state.                                                                                                                                                                                                                                           |
+| `disabled`   | `boolean` | `false`     | Disables interaction (opacity 0.6).                                                                                                                                                                                                                               |
+| `loading`    | `boolean` | `false`     | Async "busy/pending" state: blocks interaction and shows a spinner in the thumb while a value change is pending (e.g. a server round-trip that may revert). Sets `aria-busy`. The app owns the optimistic update and any revert — this prop is purely reflective. |
+| `ariaLabel`  | `string`  | `undefined` | Accessible name — a switch has no visible text. Pass this, or an `aria-label` attribute directly (both land on the root `<button>`).                                                                                                                              |
+
+### Events
+
+| Event               | Payload   | When                                                                                                  |
+| ------------------- | --------- | ----------------------------------------------------------------------------------------------------- |
+| `update:modelValue` | `boolean` | The switch was toggled (click, or Enter/Space while focused) — blocked while `disabled` or `loading`. |
+
+### Accessibility
+
+- Native `<button role="switch">` with `aria-checked` reflecting state — gets Enter/Space activation for free.
+- `aria-busy` is set while `loading`; `aria-disabled` is set while `disabled` **or** `loading`.
+- A focus ring (`:focus-visible`) renders on the track.
+- Always pass `ariaLabel` (or an `aria-label` attribute) since the control renders no visible text of its own.
+
+### When to use
+
+- An immediate on/off setting that takes effect right away (notification toggle, feature flag) — pair `loading` with an app-owned optimistic update when the effect is async.
+- For a value that must be explicitly submitted as part of a form, consider `DsCheckbox` instead.
+
+---
+
+<!-- DsTextarea · Forms -->
+
+## DsTextarea
+
+Multi-line text field — the DS "Textarea", sibling of `DsInput` with the same
+border treatment. **Presentational only**. Binds via `v-model` (its `modelValue`
+is the current string value).
+
+### Props
+
+| Prop           | Type                                             | Default      | Description                                                       |
+| -------------- | ------------------------------------------------ | ------------ | ----------------------------------------------------------------- |
+| `modelValue`   | `string`                                         | `''`         | v-model — current text value.                                     |
+| `placeholder`  | `string`                                         | `''`         | Native placeholder text.                                          |
+| `rows`         | `number`                                         | `4`          | Native `rows` attribute (visible line count).                     |
+| `disabled`     | `boolean`                                        | `false`      | Disables the control.                                             |
+| `error`        | `boolean`                                        | `false`      | Error visual state (`aria-invalid`, coral border).                |
+| `errorMessage` | `string`                                         | `''`         | Message shown under the field when `error` is true.               |
+| `name`         | `string`                                         | `''`         | Native `name` attribute.                                          |
+| `id`           | `string`                                         | `''`         | Native `id`; also links the error message via `aria-describedby`. |
+| `resize`       | `'none' \| 'vertical' \| 'horizontal' \| 'both'` | `'vertical'` | CSS `resize` behavior of the control.                             |
+
+### Events
+
+| Event               | Payload      | When                                              |
+| ------------------- | ------------ | ------------------------------------------------- |
+| `update:modelValue` | `string`     | Emitted continuously as the user types (v-model). |
+| `focus`             | `FocusEvent` | The textarea gained focus.                        |
+| `blur`              | `FocusEvent` | The textarea lost focus.                          |
+
+### Accessibility
+
+- `aria-invalid` is set when `error` is true; `aria-describedby` links the error message (`{id}-error`) when both `id` and `errorMessage` are present.
+- `class`/`style`/`data-*` fall through to the root wrapper; every other attribute (e.g. `maxlength`, `autocomplete`, `spellcheck`, native listeners) forwards straight to the real `<textarea>` (`inheritAttrs: false` plus a manual split) — so ARIA and native control attributes land where assistive tech expects them.
+- Border transitions through rest/focus/disabled/error states like `DsInput`, though — unlike `DsInput` — text does **not** go bold on focus.
+
+### When to use
+
+- Multi-line free text: notes, descriptions, messages.
+- Use `DsInput` for single-line fields.
+
+---
+
+<!-- DsMenuItem · Navigation -->
+
+## DsMenuItem
+
+Sidebar navigation row: an icon with an optional label, usable full-width or collapsed to
+an icon-only rail. **Presentational only**: it renders as a real `<button>` and emits
+`select` — the consuming app owns the active-route logic.
+
+### Props
+
+| Prop        | Type      | Default      | Description                                                                                               |
+| ----------- | --------- | ------------ | --------------------------------------------------------------------------------------------------------- |
+| `icon`      | `string`  | — (required) | Material Icons ligature name.                                                                             |
+| `text`      | `string`  | `''`         | Row label; a default slot overrides it. Stays in the DOM (visually hidden, not removed) when `collapsed`. |
+| `active`    | `boolean` | `false`      | Marks the current row: white surface, tinted border, `aria-current="page"`.                               |
+| `collapsed` | `boolean` | `false`      | Icon-only collapsed rail.                                                                                 |
+
+### Slots
+
+| Slot    | Description                         |
+| ------- | ----------------------------------- |
+| default | Overrides `text` for the row label. |
+
+### Events
+
+| Event    | Payload      | When                 |
+| -------- | ------------ | -------------------- |
+| `select` | `MouseEvent` | The row was clicked. |
+
+### Accessibility
+
+- Renders a real `<button type="button">` (keyboard-reachable, visible focus ring)
+  instead of the design source's non-interactive `<div onClick>`.
+- `aria-current="page"` is set on the active row.
+- The label stays in the DOM when `collapsed` (visually hidden via clip, not
+  `display: none`), so screen readers still announce it; sighted hover users get the
+  native `title` fallback.
+
+### When to use
+
+- Sidebar/rail navigation items, both expanded (icon + label) and collapsed (icon-only)
+  layouts.
+- For a numbered multi-step flow instead of a persistent nav rail, use `DsWizardStepper`.
+
+---
+
+<!-- DsWizardStepper · Navigation -->
+
+## DsWizardStepper
+
+Numbered multi-step flow: a row of step chips (completed / active / incomplete / neutral)
+plus a trailing "next"/"final" action button. **Presentational only**: the consumer owns
+the current step (`value`) and the button copy.
+
+### Props
+
+| Prop             | Type             | Default | Description                                                                                   |
+| ---------------- | ---------------- | ------- | --------------------------------------------------------------------------------------------- |
+| `steps`          | `DsWizardStep[]` | `[]`    | Step definitions: `{ key?, label, completed?, visited? }`.                                    |
+| `value`          | `number`         | `1`     | Current step, 1-based.                                                                        |
+| `nextLabel`      | `string`         | `''`    | Label for the "advance" button (hidden without one, and never on the last step).              |
+| `finalStepLabel` | `string`         | `''`    | Label for the final-step action button (hidden without one, and only shown on the last step). |
+| `clickable`      | `boolean`        | `true`  | Whether the step chips themselves are clickable. The advance/final buttons are always active. |
+
+### Events
+
+| Event        | Payload            | When                                                                                             |
+| ------------ | ------------------ | ------------------------------------------------------------------------------------------------ |
+| `step`       | `number` (1-based) | A step chip was clicked (only when `clickable`), or the "advance" button moved to the next step. |
+| `final-step` | —                  | The final-step action button was clicked (last step only).                                       |
+
+### Accessibility
+
+- The current step carries `aria-current="step"`.
+- Step chips render as real `<button>`s when `clickable` (keyboard-reachable, focus ring);
+  as plain `<div>`s when not, since they aren't interactive.
+- An `incomplete` (visited-but-unfinished) step is marked with a red "!" marker, so it's
+  distinguishable from `completed`/`neutral` beyond color alone.
+
+### When to use
+
+- Linear, numbered flows (e.g. a multi-step form: Compose → Recipients → Send) where the
+  user needs to see progress and jump back to prior steps.
+- For a non-linear sidebar/rail instead, use `DsMenuItem`; for an unlabeled
+  percentage/quota breakdown use `DsSegmentedProgressBar`.