@eocrm/design-system 0.0.0-stage → 0.6.17

package/docs/components/DashboardWidget.md

@@ -0,0 +1,131 @@
+# `<DashboardWidget>` — card for a DashboardCanvas cell
+
+A widget card that fills its `DashboardCanvas` cell, in five presentations: `standard`, `list`, `kpi`, `chart` and `stats`. Owns the header (title, actions), the body chrome and a variant-matched loading skeleton. The app keeps data, error state, permissions and the overflow menu.
+
+```tsx
+import {
+  Card,
+  Chart,
+  DashboardCanvas,
+  DashboardWidget,
+  EmptyState,
+  ErrorState,
+} from '@eocrm/design-system';
+
+<DashboardCanvas
+  items={layout}
+  onItemsChange={setLayout}
+  renderItem={(id) => (
+    <DashboardWidget
+      variant="kpi"
+      title="Open deals"
+      actions={menu}
+      value="128"
+      trend={{ label: '+12% vs last month', direction: 'up' }}
+    />
+  )}
+/>;
+
+// kpi with a trend graphic: a Sparkline child renders under value/trend
+<DashboardWidget variant="kpi" title="Open deals" value="128">
+  <Sparkline label="Open deals per day" values={dailyCounts} />
+</DashboardWidget>;
+
+// kpi, where "up" is bad
+<DashboardWidget
+  variant="kpi"
+  title="Churned accounts"
+  value="14"
+  trend={{ label: '+3 vs last month', direction: 'up', sentiment: 'negative' }}
+/>;
+
+// list: Card.List bleeds edge to edge
+<DashboardWidget variant="list" title="Tasks due" actions={menu} loading={isLoading}>
+  <Card.List>{/* rows */}</Card.List>
+</DashboardWidget>;
+
+// chart: the plot fills the cell; a note under it goes in Chart's `footnote`
+<DashboardWidget variant="chart" title="Revenue">
+  <Chart
+    type="line"
+    label="Revenue per month"
+    categories={months}
+    series={revenue}
+    formatValue={formatCurrency}
+    footnote="3 deals in other currencies not included"
+  />
+</DashboardWidget>;
+
+// stats: a StatGroup KPI strip; compact padding leaves slack in a 3-row cell
+<DashboardWidget variant="stats" title="Key metrics">
+  <StatGroup aria-label="Key metrics">{/* StatTiles */}</StatGroup>
+</DashboardWidget>;
+
+// quiet view-mode header: actions appear on hover / focus
+<DashboardWidget title="Pipeline" actions={menu} actionsReveal="hover">
+  {/* body */}
+</DashboardWidget>;
+
+// standard (default), with error and empty states as children
+<DashboardWidget title="Recent activity" loading={isLoading}>
+  {error ? (
+    <ErrorState title="Could not load" headingLevel={4} />
+  ) : items.length === 0 ? (
+    <EmptyState title="Nothing yet" />
+  ) : (
+    <Feed items={items} />
+  )}
+</DashboardWidget>;
+```
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `variant` | `'standard' \| 'list' \| 'kpi' \| 'chart' \| 'stats'` | no | Presentation variant. Default `'standard'`. - `'standard'` — header (title + actions) over a padded scrolling body. Today's widget card. - `'list'` — same fixed header as `standard`; flush scrolling body so `Card.List` bleeds edge to edge. - `'kpi'` — compact muted title, a large `value`, optional `trend`; optional `children` below. No scrolling. - `'chart'` — compact header; flush non-scrolling body that fills the cell (give the plot `height: 100%`). - `'stats'` — compact header and padding over a scrolling body, for a `StatGroup` KPI strip; unlike `standard` it leaves vertical slack in a 3-row cell. |
+| `title` | `ReactNode` | yes | Widget title, rendered as the heading at `headerLevel`. Required. |
+| `meta` | `ReactNode` | no | Secondary, non-interactive header text such as freshness ("Updated 3 minutes ago") or status. Sits before `actions` and yields first in a narrow cell: it truncates (then hides visually, still read by screen readers) before the title shrinks, while `actions` never shrinks. Also describes the body region (`aria-describedby`) for `standard` / `list` / `stats`. Repeat it in the refresh button's tooltip if it matters when truncated. |
+| `actions` | `ReactNode` | no | Header actions, e.g. the edit-mode overflow `DropdownMenu`. Never wraps. |
+| `actionsReveal` | `'always' \| 'hover'` | no | When `actions` are visible. Default `'always'`. - `'always'` — always shown. - `'hover'` — dimmed to invisible until the card is hovered or holds focus (they stay in the tab order, and Tab into the card reveals them); an open menu launched from an action keeps them shown. On touch / `(hover: none)` they stay visible. They keep their layout width. |
+| `headerLevel` | `'h2' \| 'h3' \| 'h4' \| 'h5' \| 'h6'` | no | Heading level of the title. Default `'h3'`. |
+| `value` | `ReactNode` | no | KPI value (`variant="kpi"` only), e.g. `"128"` or a formatted currency node. |
+| `trend` | `DashboardWidgetTrend` | no | KPI trend (`variant="kpi"` only). |
+| `loading` | `boolean` | no | Show a variant-matched loading skeleton instead of the body (and, for kpi, instead of `value`/`trend`); title and actions stay. Adds visually hidden "Loading…" body text and `aria-busy`. Deliberately NO live region: a dashboard loads many widgets at once, so per-widget announcements would flood screen readers — announce "dashboard loaded" once at page level if needed. Default `false`. |
+| `children` | `ReactNode` | no | Widget body. Pass `ErrorState` / `EmptyState` here for error and empty states. |
+| …native | | | plus native `<div>` attributes |
+
+<!-- props:end -->
+
+- **Fills its cell.** It is a `<Card fill padding="none">`; `DashboardCanvas` sizes the cell, the widget fills it. The root is a `div` with a heading (no landmark; 20 regions on one dashboard is noise). Heading level is `headerLevel` (default `h3`).
+- **Variants.** `standard`: header + padded scrolling body. `list`: same fixed header as `standard`, flush scrolling body so `Card.List` bleeds edge to edge. `kpi`: compact muted title, large `value`, optional `trend`, optional `children` below; does not scroll. `chart`: compact header, flush body that does not scroll and fills the remaining height, so give the plot `height: 100%`. `stats`: compact header and padding over a scrolling body, for a [`StatGroup`](StatGroup.md) KPI strip; scrolls only on real overflow.
+- **Only `standard`, `list` and `stats` scroll.** `kpi` and `chart` bodies are non-scrolling (`Card.Body` without `scroll`).
+- **`value` / `trend` are kpi only** and ignored on other variants.
+- **Trend.** Direction icon plus a visually hidden "Increase / Decrease / No change" before `label`. Colour is by `sentiment`, which defaults from direction (up positive, down negative, flat neutral). Set `sentiment` explicitly when the direction is not the judgement (churn, overdue tasks up = `negative`).
+- **`loading`** swaps the body (for kpi, the value and trend) for a skeleton matching the variant (standard: lines, list: rows, kpi: value + trend, chart: bars, stats: kpi shape). Title and actions stay. For `stats`, prefer `StatGroup loading` (per-tile skeletons) over widget `loading`, which shows a single kpi blob; don't set both. The skeleton is `aria-hidden`; the body instead contains visually hidden "Loading..." text and the root gets `aria-busy` as a hint.
+- **No live region, on purpose.** A dashboard loads 10 to 20 widgets at once; a live region per widget would flood a screen reader. If you want an announcement, make one at page level ("Dashboard loaded") once all widgets settle. That is the app's job.
+- **Error and empty states** are the app's `ErrorState` / `EmptyState`, passed as `children` (for kpi, as `value` or `children`).
+- **`actions`** (e.g. an edit-mode `DropdownMenu`) sit at the header's end and never wrap.
+- **`actionsReveal="hover"`** (default `'always'`) is for quiet view-mode headers: the actions are transparent until the card is hovered or holds focus (`:focus-within`, so Tab into the card reveals them), and stay shown while a menu launched from them is open. They are hidden with opacity only: they keep their layout width (the title and meta do not jump) and stay in the tab order. On touch / `(hover: none)` they are always visible.
+- **`meta`** is secondary, non-interactive header text (freshness such as "Updated 3 minutes ago", or status). It sits just before `actions`, muted and on one line, and yields first in a narrow cell: it truncates with an ellipsis, then hides visually (screen readers still read it) once only a sliver is left, before the title gives up any width, while `actions` keeps its width. For `standard` / `list` / `stats` it also describes the body region (`aria-describedby`). If the text matters when truncated, repeat it in the refresh button's tooltip.
+
+#### When NOT to use
+
+- ❌ A generic content card outside a dashboard → `<Card>`.
+- ❌ A standalone stat with no grid cell → `<Card>` with your own layout.
+- ❌ A placeholder in a widget catalog → `<WidgetPreview>`.
+
+#### Anti-patterns
+
+- ❌ `actionsReveal="hover"` when the only way to reach an essential action is that header. Touch users see it, but mouse users get no visible cue; keep primary actions visible.
+- ❌ Wrapping `DashboardWidget` in another `Card`. It already is one.
+- ❌ Freshness or status text in `actions`. `actions` never shrinks, so the title gets crushed in a narrow cell; use `meta`.
+- ❌ Buttons or links in `meta`. They can be truncated out of reach; controls go in `actions`.
+- ❌ `standard` for a `StatGroup` KPI strip in a 3-row widget: the roomy padding leaves no slack and the strip scrolls. Use `stats`.
+- ❌ Passing `value` / `trend` to `standard`, `list`, `chart` or `stats`. They are ignored; put content in `children`.
+- ❌ Rendering your own `Skeleton` in `children` instead of `loading`. You lose the variant-matched shape, the hidden "Loading..." text and `aria-busy`.
+- ❌ Adding a live region (`role="status"`, `aria-live`) to each widget while loading.
+- ❌ Relying on direction-derived colour when up is bad. Set `sentiment`.
+- ❌ A scrolling or fixed-height wrapper inside a `kpi` / `chart` body. The cell is the size; size the plot at `height: 100%`.

package/docs/components/DataTable.md

@@ -0,0 +1,88 @@
+# `<DataTable>` — server-driven data table with column features
+
+- The table owns its polite live region; do not wrap it in another — two regions would fire for one event.
+
+```tsx
+const instance = useDataTable<Deal>({
+  data,
+  columns,
+  getRowId: (r) => r.id,
+  enableRowSelection: true,
+  sort,
+  onSortChange: setSort,
+});
+
+<Cluster>
+  <ColumnVisibilityTrigger instance={instance} />
+</Cluster>
+<DataTable instance={instance} aria-label="Deals" />
+```
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `instance` | `DataTableInstance<T>` | yes |  |
+| `density` | `'comfortable' \| 'dense'` | no |  |
+| `striped` | `boolean` | no |  |
+| `hover` | `boolean` | no | Hover highlight on body rows. Defaults TRUE (DataTable rows are usually interactive). |
+| `bordered` | `boolean` | no |  |
+| `loading` | `boolean` | no | Marks the table busy. Empty tables show skeleton rows; populated tables keep their rows mounted during a refetch so focus and local row state are preserved. Defaults to `false`. Announced from a polite live region the table owns, gated on the SKELETON rather than on this prop: a load shorter than `skeletonDelay` shows nothing and so says nothing, and a refetch over rows already on screen is silent because nothing visibly changes. The resolution is announced too — "Rows loaded" or "No rows loaded". `aria-busy` is also set, but reaches no screen reader on its own. |
+| `loadingRowCount` | `number` | no | Number of skeleton rows when `loading`. Defaults 10. |
+| `skeletonDelay` | `number` | no | Milliseconds to wait before showing skeleton rows for an empty initial load. Defaults to `0`; fast loads that finish inside the delay never show a skeleton. |
+| `skeletonMinDuration` | `number` | no | Minimum milliseconds skeleton rows remain visible after appearing. Defaults to `0`. Arriving rows and the empty state remain hidden until the visual tail finishes. `aria-busy` still follows actual `loading`, not the skeleton's visual tail. |
+| `emptyState` | `ReactNode` | no | Element shown when `data` is empty and not loading. Defaults to a stock <EmptyState>. |
+| `collapseBelow` | `'sm' \| 'md' \| 'lg'` | no | Stacks responsive data cells below this container-query breakpoint: `sm` (480px), `md` (640px), or `lg` (768px). Selection, expansion, sorting, row actions, and column visibility remain usable. Column sizing, pinning, and ordering state is retained, but resize/reorder controls and sticky pin presentation are unavailable while stacked and return after widening. This adds a wrapper with `container-type: inline-size`, so the breakpoint measures the table's available container width, not the viewport. Avoid an intrinsic-width parent such as `width: max-content`: inline-size containment can make the wrapper contribute zero intrinsic width there. |
+| `aria-label` | `string` | no | Required for a11y when no caption is provided. |
+| `caption` | `ReactNode` | no |  |
+| `dragWholeColumn` | `boolean` | no | Drag the whole column while reordering, not just its header cell. Default `true` — the dragged column's body cells travel with its header, and every column the drag displaces shifts its body cells too, so the header row and the body never disagree mid-drag. Costs one CSS-variable write per shifted column per frame; the cells move on the compositor, so the table body is not re-rendered during pointer movement. It does cost two full body reconciliations per drag — one at drag start, one at drag end — because the drag-active flag is component state and body rows are not memoized; that is the number to weigh for a very large table. Set `false` for the cheaper preview: only the dragged header cell follows the pointer and the body stays put until drop. Worth it for very large tables on low-end hardware, or to restore the previous behavior. Pinned columns never move under either setting — they are excluded from reordering entirely. The two settings also differ on **what a release means when no unpinned slot is under the column** — over a pinned column, or off the table entirely. Default: the drop commits the slot the preview is showing. The opt-out: the drop is discarded, because dnd-kit's own preview retracts (the header snaps back home) in that situation, and a commit would contradict it. See `docs/components/DataTable.md`, the column-drag bullet. |
+| `className` | `string` | no |  |
+
+<!-- props:end -->
+
+- Config-driven via `columns: ColumnDef<T>[]`. Each column has a stable `id` used as the key for all per-column state.
+- **Column header names.** The `<th>` is named by the label span's content — the header text — so the resize handle is never folded into it. The one override: a header that renders no TEXT OF ITS OWN — a ReactNode, a render function, or `''` — is named by `visibilityLabel` when you set one. So `header: <strong>Revenue</strong>` announces "Revenue", and adding `visibilityLabel="Revenue (USD)"` makes it announce "Revenue (USD)". That is a name-vs-label mismatch, and a WCAG 2.5.3 one only when `sortable` makes the label a button — 2.5.3 is scoped to user interface components, and it is violated only when the label does not CONTAIN the visible text, so "Revenue (USD)" over "Revenue" passes. Accepted because the alternative — a runtime measurement deciding which source names the header — produced UNNAMED column headers ten separate times before it was deleted. A string header that renders text is always named by that text; `visibilityLabel` does not override it. `header: ''` is not such a string: it renders nothing, so the label wins, which is what the trailing row-actions column wants. `column.id` is used for nothing a user hears — not the header, not the drag grip, not the resize handle. What such a header announces, measured off Chromium's AX tree: an `aria-labelledby` resolving to no text is marked INVALID, not treated as a name, so naming falls through to the cell's contents — the drag grip, or under `collapseBelow` the resize handle's live pixel width. `header: ''` is special-cased to a generic "Unlabelled column" so the width cannot win; a ReactNode rendering nothing is indistinguishable from one that names itself, so it is not. Either way it is not a name you chose, so set `visibilityLabel` on every text-less header. That is a change from before the fix, where such a header WAS named — from content, which swept in the resize handle, so it announced the handle's label, `column.id` when the column had nothing better. That name was the bug, not a feature worth preserving. (The "Resize … column" wrapper came with that fix; before it the handle's label was the bare identifier.) There is no dev warning for it: nothing static can tell a node that names itself (`<strong>Revenue</strong>`) from one that does not (an icon), so a warning fired on the commonest valid shape and was removed. Give any non-text header a `visibilityLabel`.
+- **Responsive rows:** `collapseBelow="sm" | "md" | "lg"` re-templates rows as labelled cards based on the DataTable container. Labels use `visibilityLabel`, then a string `header`; give non-text headers a `visibilityLabel` when a visible card label is required. Plain non-sortable string headers leave the compact strip, while React-node and render-function headers remain because they may contain controls. Sorting, selection, expansion, row actions, and `ColumnVisibilityTrigger` remain available. Column sizing, pinning, and ordering state is retained while stacked, but resize/reorder controls and sticky pin presentation are unavailable until the table widens again. Give the table concrete available width because inline-size containment has no intrinsic-width contribution.
+- All state pieces (column order/sizing/visibility/pinning, row selection/expansion, sort) follow the Radix controlled/uncontrolled pattern: `value` + `onValueChange`, OR `defaultValue` only, OR neither.
+- Server-driven sort/search/pagination. DataTable does NOT transform data — `data` must be the server's pre-sorted, pre-paginated slice. `onSortChange` is your trigger to refetch.
+- `enableRowSelection: true` adds a leading checkbox column with select-all (indeterminate when partial). `toggleAllOnPage` ignores `pinnedRows`.
+- Drag-to-reorder is keyboard-accessible (Tab to grip → Space to pick up → ←/→ to move → Space/Enter to drop → Esc to cancel). The grip is hover-revealed on desktop.
+- Resize via the right-edge handle. Without `collapseBelow`, the legacy keyboard path stays on a focused sortable header label: `←`/`→` for −/+8px; Shift+`←`/`→` for ±32px. With `collapseBelow`, the wide presentation exposes a dedicated focusable resize separator with the same keys; the separator and resize interaction are unavailable while stacked and return after widening.
+- `ColumnVisibilityTrigger` is the only built-in companion. For column pinning UI (Phase 2 ships state, no built-in UI), wire your own using `instance.pinColumn(id, side)`.
+- **Phase 2 ships pinning rendering.** `columnPinning` now applies sticky CSS with cumulative offsets and an inside-edge shadow; `pinnedRows` renders in a separate `<tbody>` above the main body. The selection auto-column is auto-left-pinned at offset 0. Pinned columns are LOCKED in place — no drag grip, can't be reordered. Their sort still works. Declare initial pinning either on the hook (`defaultColumnPinning: { left: ['name'], right: ['actions'] }`) or directly on each column (`pin: 'left' | 'right'`); the hook prop wins when both are set. **Phase 3 ships expandable rows.** Pass `renderExpandedRow: (row) => ReactNode` to add a per-row chevron auto-column at the left edge. Clicking the chevron toggles a detail row beneath the main row, spanning all columns. ARIA-wired with `aria-expanded` + `aria-controls`. The chevron auto-column is sticky-left like the selection cell; when both are enabled, selection is first and expand is second. DataTable is now feature-complete per the original spec.
+- **Cell content is single-line + ellipsized by default.** DataTable's internal table uses `table-layout: fixed` so column widths from `ColumnDef.size` (or runtime `columnSizing`) are authoritative, and every cell gets `overflow: hidden; text-overflow: ellipsis; white-space: nowrap`. Wide content truncates with `…` at the column boundary; the column does NOT expand to fit. If you need multi-line cells, render `<Table>` directly — DataTable is opinionated here so pinning offsets stay pixel-correct.
+- **A column drag commits wherever the preview parked it** — however far the pointer roams, including over a pinned column or clear off the table. There is no "outside" to release into: the column is clamped to the unpinned band, so the preview is always showing a real slot and the drop honors it. This deliberately differs from `Kanban`, where releasing outside the columns cancels — there the pointer can genuinely aim somewhere else. **Escape is the only cancel.** The `dragWholeColumn={false}` opt-out is the exception: its preview is dnd-kit's own and RETRACTS (the header snaps home) when no unpinned slot is under the column, so a release there is discarded — matching what that preview shows.
+
+**When NOT to use:**
+
+- A static read-only table without column features — use `<Table>` directly.
+- Huge datasets (10k+ rows on screen at once): rows are not virtualized, so it gets slow.
+- Excel-like cell editing or cell selection — out of scope; compose it yourself.
+
+**Anti-patterns:**
+
+- ❌ Mutating `columns` array identity on every render. `useDataTable` captures `defaultColumnOrder` from `columns` once at mount — later identity changes don't trigger a re-derive of the default order. Use a stable reference (`useMemo` or module-level).
+- ❌ Client-sorting `data` AND passing `sort` controlled. Pick one — server is the canonical source. Spinning both means rows reorder twice and ghost-rows appear during fetches. `data` is the server's pre-paginated, pre-sorted slice.
+- ❌ Rolling your own column visibility UI when `ColumnVisibilityTrigger` does the job. The built-in handles the "last column" guard for you.
+- ❌ Using `<Table>` directly when you want any of: ordering, sizing, visibility, selection, sort indicator wiring. Compose `<DataTable>` instead — the primitive `<Table>` is for static read-only views.
+- ❌ Putting interactive controls in `renderExpandedRow` that need to participate in row selection or row click. The detail row is its own `<tr>`, not part of the main row — `onRowClick` doesn't fire from inside it (by design), and `rowSelection` only tracks main-row checkboxes.
+- ⚠ Pinned rows (passed via `pinnedRows`) ALSO render a chevron when `renderExpandedRow` is set — they're expandable just like main-body rows. Decide whether your starred/anchored rows should reveal detail; if not, omit `renderExpandedRow` or filter `expandedRows` state in the consumer to ignore pinned-row ids.
+
+#### `<ColumnVisibilityTrigger>`
+
+Companion for `<DataTable>`: a ghost Button trigger plus a DropdownMenu of CheckboxItems, one per column where `enableHide !== false`. When only one hidable column is visible its item renders disabled, so the table can never reach a zero-column state. Pass the same `instance` to both `<DataTable>` and `<ColumnVisibilityTrigger>` so visibility state stays in sync.
+
+```tsx
+// Custom label + right-aligned menu
+<ColumnVisibilityTrigger instance={instance} label="Manage columns" align="end" />
+
+// Icon-only trigger
+<ColumnVisibilityTrigger instance={instance} label={null} />
+```
+
+- When NOT to use: you want a different visibility UI (a settings drawer, a multi-select combobox, a Popover with column grouping) — build it against `instance.columns`, `instance.columnVisibility` and `instance.toggleColumnVisibility`; or every column has `enableHide: false` (the menu would be empty — don't render it).
+- ❌ Passing a different `instance` to the trigger than to `<DataTable>`: visibility changes in one won't reflect in the other.
+- ❌ Rendering it when every column has `enableHide: false` — check `instance.columns` first and suppress the trigger.

package/docs/components/DatePicker.md

@@ -0,0 +1,68 @@
+# `<DatePicker>` — single-date input + popover
+
+```tsx
+const [value, setValue] = useState<Date | null>(null);
+<DatePicker value={value} onChange={setValue} min={new Date()} />;
+```
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `value` | `Date \| null` | no | Selected date. `null` = no value. Pair with `onChange` for controlled use. |
+| `defaultValue` | `Date \| null` | no | Initial selected date for uncontrolled use. |
+| `onChange` | `((date: Date \| null) => void)` | no | Fires when the value changes. |
+| `locale` | `string` | no | Override locale (otherwise reads `useLocale()`). |
+| `min` | `Date` | no | Earliest selectable date (inclusive, day-granular). Gates both the grid and typed input. |
+| `max` | `Date` | no | Latest selectable date (inclusive). |
+| `isDateDisabled` | `((date: Date) => boolean)` | no | Per-date disable callback; applied per grid cell and to parsed typed input. |
+| `clearable` | `boolean` | no | Show the ✕ clear button when a value is set. Defaults to `true`. |
+| `invalid` | `boolean` | no | Toggle red border + focus ring + `aria-invalid="true"`. Pair with a visible error and `aria-describedby`. |
+| `name` | `string` | no | Form name. When set, renders a hidden mirror `<input>` with the ISO date so native `<form>` submission works. |
+| `size` | `'sm' \| 'md' \| 'lg'` | no | Field height + type scale. Same scale as `<Input>`. Defaults to `'md'`. Affects only the trigger row; the popover month grid is fixed-size. - `'sm'` — 24px tall. - `'md'` — 32px tall (default). - `'lg'` — 40px tall. |
+| `granularity` | `'day' \| 'minute'` | no | Picker precision. - `'day'` (default) — date only; behavior unchanged from prior releases. - `'minute'` — adds a manual-entry time input below the calendar grid. The trigger text shows `HH:mm` after the date. The hidden form mirror (when `name` is set) emits ISO local datetime (`2026-05-28T14:30`). Time is preserved across date re-picks. Picking from a `null` value defaults the time to `00:00`. In `'minute'` mode picking a day keeps the popover open and moves focus to the time input; Enter there (or Escape / outside click) closes it. |
+| `timeStep` | `number` | no | Minutes step for the `<TimeField>` popover and for rounding typed time input on commit. Defaults to `15`. Set `1` to disable rounding. Only meaningful when `granularity='minute'`. |
+| `hourCycle` | `'12' \| '24' \| 'auto'` | no | Display cycle for the embedded `<TimeField>` + the trigger's time tail. - `'24'` — `"HH:mm"` in the trigger; 24h hour list in the time popover. - `'12'` — `"h:mm AM/PM"` in the trigger; 12h hour list + AM/PM column. - `'auto'` (default) — derives from the active locale via Intl. en-US → `'12'`; ru-RU / de-DE / fr-FR → `'24'`. Only meaningful when `granularity='minute'`. Typed input is lenient regardless of cycle — both `"14:30"` and `"2:30 PM"` parse on blur. |
+| …native | | | plus native `<input>` attributes |
+
+<!-- props:end -->
+
+- Single-date selection (date-only by default; opt into date+time with `granularity="minute"`). Range → `<DateRangePicker>`. Year-picker — out of scope for v1.
+- Looks like an `<Input>`. Click the input or press ArrowDown to open the popover. The 📅 button toggles and the ✕ button clears; clicking either never moves focus while it's in the field or the open popover, so half-typed trigger text survives the toggle and is discarded by clear. Reaching them by keyboard (Tab) leaves the input first, which commits the typed text. Toggling closed from inside the popover commits a time typed into the time input and returns focus to the input; clear from there wins over the typed time (one `onChange(null)`).
+- Typed input parses on Enter, or when focus leaves the field — ArrowDown into the open calendar, an outside click, or Tabbing away (Tab from the trigger goes ✕ → 📅 → the page; the portaled calendar is reached with ArrowDown) — using the active locale: en-US `M/D/YYYY`, ru-RU `D.M.YYYY`, ja-JP `Y/M/D`. ISO `YYYY-MM-DD` is always accepted as a paste fallback. Unparseable / out-of-range / disabled input reverts to the last committed value.
+- Locale-aware via `useLocale()`; override with `locale` prop. UI strings (previousMonth / nextMonth / openCalendar / clear) translate via `datePicker.*` keys — override with `<I18nProvider overrides={{ datePicker: { ... } }}>`.
+- ARIA: typed input has `aria-haspopup="dialog"` + `aria-expanded`. Popover wrapper is `role="dialog"` (labelled by `aria-label={t('datePicker.openCalendar')}`); the grid inside is `role="grid"` with `role="gridcell"` buttons that carry `aria-selected` / `aria-disabled` as appropriate.
+- Keyboard inside the grid: ←→↑↓ move focus by 1 day, Home/End to start/end of week, PageUp/PageDown step a month, Enter/Space selects, Escape closes and returns focus to the input. Tab / Shift+Tab out of the popover closes it and returns focus to the input (both granularities).
+- **Granularity.** Pass `granularity="minute"` to add a `<TimeField>` below the calendar grid; the trigger text becomes `MM/DD/YYYY HH:mm` (24h locales) or `MM/DD/YYYY h:mm AM/PM` (12h locales) and the hidden form mirror emits ISO local datetime (`2026-05-28T14:30`). Defaults to `'day'` (backward compat — date-only). Picking a different date re-uses the existing time-of-day, so the grid feels like it "just changes the date"; picking from `null` defaults to `00:00`. Picking a day does NOT close the popover in minute mode: focus moves to the embedded time input so the time is reachable; Enter in the time input (with its clock closed) or Escape closes it and returns focus to the trigger input; an outside click closes it and leaves focus where the user clicked; Tabbing out of the popover closes it and returns focus to the trigger input, so the next Tab continues in page order. Every close path keeps a date typed into the trigger and a time typed into the time input. The `<TimeField>` accepts free text (parsed on blur / Enter via `parseTime` — both 24h and AM/PM shapes) AND a chevron-toggled popover with hour + minute (+ AM/PM in 12h mode) lists, plus a "Now" footer button. `timeStep` (default `15`, in minutes) controls the minute-list row count AND rounds typed input in the time field on commit; set `timeStep={1}` to disable rounding. The trigger text-input parses exactly as typed — `timeStep` does not round trigger input. `hourCycle` (default `'auto'`) forwards to the embedded TimeField and controls the trigger text — `'12'` / `'24'` force a cycle, `'auto'` derives from locale (en-US → 12h, ru-RU → 24h).
+
+```tsx
+// Uncontrolled, today as the default
+<DatePicker defaultValue={new Date()} onChange={(d) => console.log(d)} />
+
+// Constrained
+<DatePicker
+  value={value}
+  onChange={setValue}
+  min={new Date()}
+  isDateDisabled={(d) => d.getDay() === 0 || d.getDay() === 6}
+/>
+
+// Form integration via the hidden mirror
+<form action="/dates"><DatePicker name="dob" /></form>
+```
+
+The popover is portaled into `document.body`, so it escapes overflow-hidden ancestors.
+
+#### When NOT to use
+
+- Datetime with seconds precision: only `granularity="minute"` is supported; compose with a separate input.
+- Time-only fields (no date): out of scope.
+- Free-form date strings without a clear locale: use a plain `<Input>`.
+
+#### Anti-patterns
+
+- ❌ Wrapping the picker in `<label htmlFor={id}>` while also passing `aria-label` — pick one. The wrapper label is preferred.
+- ❌ Using `value` without `onChange` and expecting state to update on user input — the picker is fully controlled when `value` is passed.

package/docs/components/DateRangePicker.md

@@ -0,0 +1,71 @@
+# `<DateRangePicker>` — date-range input + two-month popover
+
+```tsx
+const [range, setRange] = useState<DateRange | null>(null);
+<DateRangePicker value={range} onChange={setRange} min={new Date()} />;
+```
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `value` | `DateRange \| null` | no | Selected range. `null` = no range. Pair with `onChange` for controlled use. |
+| `defaultValue` | `DateRange \| null` | no | Initial range for uncontrolled use. |
+| `onChange` | `((range: DateRange \| null) => void)` | no | Fires when a complete range commits (after second click in grid, or successful typed parse on blur). |
+| `locale` | `string` | no | Override locale (otherwise reads `useLocale()`). |
+| `min` | `Date` | no | Earliest selectable date (inclusive). Both halves and typed input are gated. |
+| `max` | `Date` | no | Latest selectable date (inclusive). |
+| `isDateDisabled` | `((date: Date) => boolean)` | no | Per-date disable predicate; gates both the popover grid and typed-input parsing. |
+| `size` | `'sm' \| 'md' \| 'lg'` | no | Field height + type scale. Same scale as `<DatePicker>`. Defaults to `'md'`. Affects only the trigger row; the two-month popover grid is fixed-size. - `'sm'` — 24px tall. - `'md'` — 32px tall (default). - `'lg'` — 40px tall. |
+| `clearable` | `boolean` | no | Show the ✕ clear button when a range is set. Defaults to `true`. |
+| `invalid` | `boolean` | no | Toggle red border + focus ring + `aria-invalid="true"`. Pair with a visible error and `aria-describedby`. |
+| `nameStart` | `string` | no | Form name for the START half (hidden `<input>` with an ISO date, so native `<form>` submission works). Post both keys or just one. |
+| `nameEnd` | `string` | no | Form name for the END half. |
+| `granularity` | `'day' \| 'minute'` | no | Picker precision. - `'day'` (default) — date only; behavior unchanged from prior releases. - `'minute'` — adds two manual-entry time inputs (start + end) below the two-month grid. The trigger text shows `HH:mm` after each date. Hidden form mirrors (when `nameStart` / `nameEnd` are set) emit ISO local datetime (`2026-05-28T14:30`). At `'minute'` the start/end time inputs are shown and editable in the popover even before a range is picked (defaulting to `00:00` / `23:59`). Times entered in the empty state are applied when the range is committed (instead of the bare defaults), and existing times are preserved across date re-picks. Same-day ranges with end-time < start-time are silently clamped so end-time ≥ start-time. |
+| `timeStep` | `number` | no | Minutes step for the start + end `<TimeField>` popovers and for rounding typed time input on commit. Defaults to `15`. Set `1` to disable rounding. Only meaningful when `granularity='minute'`. |
+| `hourCycle` | `'12' \| '24' \| 'auto'` | no | Display cycle for the two embedded `<TimeField>`s + the trigger's time tails. - `'24'` — `"HH:mm"` in trigger + 24h hour lists in popovers. - `'12'` — `"h:mm AM/PM"` in trigger + 12h hour lists + AM/PM column. - `'auto'` (default) — derives from the active locale via Intl. en-US → `'12'`; ru-RU → `'24'`. Only meaningful when `granularity='minute'`. Typed input is lenient regardless of cycle — both `"14:30"` and `"2:30 PM"` parse on blur. |
+| …native | | | plus native `<input>` attributes |
+
+<!-- props:end -->
+
+- Date-range selection (date-only by default; opt into date+time on each side with `granularity="minute"`). Single-date → `<DatePicker>`. Multi-date / preset ranges (Today, Last 7 days) — out of scope for v1.
+- Looks like an `<Input>`. Click the input or press ArrowDown to open; the popover shows two months side-by-side. The 📅 button toggles, the ✕ button clears the whole range.
+- Selection flow: first click sets the start; hover (or keyboard-focus) another cell to preview the range; second click commits and closes. If the second pick is earlier than the start, the range is auto-swapped to `[earlier, later]`. A third click in a reopened popover restarts selection.
+- Typed input parses on blur / Enter using the active locale. Accepts `—` (em dash), `–` (en dash), `-` (hyphen with spaces), or `to` (case-insensitive word) as the separator. ISO `YYYY-MM-DD` works for each half too. Out-of-order typed input is auto-swapped. Anything unparseable / out-of-range / disabled reverts to the last committed value.
+- ARIA: typed input has `aria-haspopup="dialog"` + `aria-expanded`. Popover wrapper is `role="dialog"` (labelled by `aria-label={t('datePicker.openCalendar')}`); each grid inside is `role="grid"` with `gridcell` buttons. The range-start and range-end cells (and the live hover end during selection) carry `aria-selected="true"`.
+- Keyboard inside a grid: ←→↑↓ move focus by 1 day, Home/End to start/end of week, PageUp/PageDown step a month, Enter/Space drives the same first-click → second-click flow, Escape closes and returns focus to the input. With selection-start set, the focused cell acts as the hover end so the preview range follows arrow keys.
+- Reuses `<DatePickerGrid>` via `selectionMode='range'` + `rangeStart`/`rangeEnd`/`hoverDate`/`onHoverDate` + `chevrons={false}`. The two grids share the same cursor; the picker renders its own prev/next chevrons outside them.
+- **Granularity.** Pass `granularity="minute"` to add dual `<TimeField>`s (start + end) below the two-month grid; the trigger text becomes `MM/DD/YYYY HH:mm — MM/DD/YYYY HH:mm` (24h locales) or `MM/DD/YYYY h:mm AM/PM — MM/DD/YYYY h:mm AM/PM` (12h locales) and the hidden form mirrors emit ISO local datetime. Defaults to `'day'` (backward compat). The start/end time inputs are shown and editable in the popover even before a range is picked — defaulting to `00:00` start / `23:59` end. Times set in this empty state are applied when the range is committed (no need to seed a placeholder range), and existing times are preserved across subsequent date picks. Same-day ranges silently clamp end-time to ≥ start-time on every commit; different-day ranges are not clamped. `timeStep` (default `15`, in minutes) applies to BOTH TimeFields, controlling each minute-list row count AND rounding typed input in the time fields on commit; set `timeStep={1}` to disable rounding. The trigger text-input parses exactly as typed — `timeStep` does not round trigger input. `hourCycle` (default `'auto'`) forwards to both embedded TimeFields and controls the trigger text — `'12'` / `'24'` force a cycle, `'auto'` derives from locale.
+
+```tsx
+// Uncontrolled
+<DateRangePicker defaultValue={{ start: new Date(), end: new Date() }} />
+
+// Controlled, constrained to a 90-day window
+<DateRangePicker
+  value={range}
+  onChange={setRange}
+  min={new Date()}
+  max={new Date(Date.now() + 90 * 86_400_000)}
+/>
+
+// Form mirror, two separate fields
+<form action="/api/bookings">
+  <DateRangePicker nameStart="bookingStart" nameEnd="bookingEnd" />
+</form>
+```
+
+#### When NOT to use
+
+- Single date: use `<DatePicker>`.
+- Seconds-precision tracking: only `granularity="minute"` is supported.
+- Time-only fields (no date): out of scope.
+- Multi-date selection (3+ non-contiguous dates): out of scope.
+
+#### Anti-patterns
+
+- ❌ Passing `value` without `onChange` — the picker is fully controlled when `value` is set; user input has no effect.
+- ❌ Using `defaultValue` AND `value` together — pick one.

package/docs/components/DateStrip.md

@@ -0,0 +1,56 @@
+# `<DateStrip>` — week of selectable day tiles
+
+```tsx
+const [day, setDay] = useState<string | null>(null);
+<DateStrip
+  days={week} // [{ date: '2026-10-05', free: 3 }, … 7 days]
+  value={day}
+  onChange={setDay}
+  onPrevious={prevWeek}
+  onNext={nextWeek}
+  canPrevious={!isCurrentWeek}
+/>;
+```
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `days` | `DateStripDay[]` | yes | The days to show, in order — usually one week (7); one grid column per day. The month heading is derived from the first and last. |
+| `value` | `string \| null` | yes | Selected day (`'YYYY-MM-DD'`), or `null`. A value not in `days` checks nothing. |
+| `onChange` | `(date: string) => void` | yes | Called with the chosen day's `'YYYY-MM-DD'`. Controlled — update `value` yourself. |
+| `onPrevious` | `() => void` | yes | Previous-week button handler. Replace `days` with the earlier week. |
+| `onNext` | `() => void` | yes | Next-week button handler. Replace `days` with the later week. |
+| `canPrevious` | `boolean` | no | `false` disables the previous-week button (e.g. the current week). Default `true`. |
+| `canNext` | `boolean` | no | `false` disables the next-week button (end of the booking window). Default `true`. |
+| `titleOrder` | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | no | Heading level of the month label. Default `2`. |
+| `name` | `string` | no | Radio group `name` (also submitted with a form). Default: a generated id. |
+| `invalid` | `boolean` | no | Marks the group `aria-invalid` (the radios themselves do not support it). Field / SettingRow inject it. Default: `false`. |
+| `required` | `boolean` | no | Native `required` on the radios (the group then fails form validation until one is chosen). Field / SettingRow inject it; it used to land on the root as a stray attribute. |
+| …native | | | plus native `<fieldset>` attributes |
+
+<!-- props:end -->
+
+- `date` is an ISO `'YYYY-MM-DD'` calendar day (the business's day, not a `Date`); the strip formats weekday / number / month through the locale in UTC, so the browser timezone never shifts it. The month heading is derived ("October 2026", "September – October 2026").
+- `free: 0` → "No times", tile natively disabled (skipped by Tab and arrows). Keep full days in the array.
+- Native radios, one `name`: one Tab stop, arrows move AND select (so `onChange` fires per arrow press — debounce slot fetching if needed). Tiles are `role="radio"` named "Wednesday, October 7, 9 free"; query them that way in tests.
+- Controlled only.
+- In `<Field>` / `<SettingRow>`: the row label is merged in front of the month (group name "Day October 2026"), the error describes the group, `invalid` → `aria-invalid` on the group, `required` → native `required` on the radios. One column per day (`days.length`), so a 5-day week has 5 columns.
+- Previous/next use `aria-disabled` (not `disabled`) when `canPrevious`/`canNext` is false, so focus stays on the button that reached the boundary.
+- Changing week announces the new range politely; same-week re-renders stay silent.
+- ❌ No `aria-label` on the strip — the month heading names the group. ❌ No `Date`/`toISOString()` for `date`.
+- ❌ In an intrinsic-width context (`Split`'s default `auto` aside track, a `Cluster` item, `width: max-content`) it renders at width 0 — `container-type: inline-size` zeroes its intrinsic-width contribution; give the parent a concrete width (e.g. `asideWidth` on a Split). It is also the containing block for absolutely-positioned descendants (layout containment).
+- When NOT to use: any-date picking → `<InlineDatePicker>`; events → `<Calendar>`; times → `<SlotGrid>`.
+- ❌ Building `date` from `toISOString()` of a local-midnight `Date` — it shifts a day west of UTC. Produce the business-timezone calendar day.
+- When NOT to use: scheduling or showing events → `<Calendar>`; free-form time entry → `<TimeField>`.
+
+```tsx
+// Booking time step: DateStrip picks the day, SlotGrid the time.
+<Stack gap="lg">
+  <DateStrip days={week} value={day} onChange={setDay} onPrevious={prev} onNext={next} />
+  <SlotGrid groups={slotsFor(day)} value={slot} onChange={setSlot} />
+</Stack>
+```

package/docs/components/DefinitionList.md

@@ -0,0 +1,82 @@
+# `<DefinitionList>` — semantic key/value pairs (dl / dt / dd)
+
+For displaying entity properties — contact details, settings rows, metadata sidebars. Renders proper `<dl>`/`<dt>`/`<dd>` so screen readers announce term/description pairs natively. Compound: `DefinitionList`, `DefinitionList.Item`, `DefinitionList.Term`, `DefinitionList.Description`.
+
+```tsx
+<DefinitionList dividers>
+  <DefinitionList.Item>
+    <DefinitionList.Term>Email</DefinitionList.Term>
+    <DefinitionList.Description icon={<Mail size={14} />}>
+      ada@example.com
+    </DefinitionList.Description>
+  </DefinitionList.Item>
+  <DefinitionList.Item>
+    <DefinitionList.Term>Phone</DefinitionList.Term>
+    <DefinitionList.Description icon={<Phone size={14} />}>
+      +1 (415) 555-0142
+    </DefinitionList.Description>
+  </DefinitionList.Item>
+</DefinitionList>
+```
+
+<!-- props:start -->
+
+## Props
+
+### `DefinitionListProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `layout` | `'horizontal' \| 'stacked'` | no | Layout direction. See `DefinitionListLayout`. Default `'horizontal'`. |
+| `termWidth` | `string` | no | CSS length applied to the term column in horizontal layout (e.g. `'180px'`, `'20%'`, `'max-content'`). Default `'max-content'` — column sizes to the longest term across all rows. Set explicitly when you need consistent alignment across multiple DefinitionLists on the same screen. |
+| `spacing` | `'sm' \| 'md' \| 'lg'` | no | Vertical padding per item. See `DefinitionListSpacing`. Default `'sm'`. |
+| `dividers` | `boolean` | no | Render a 1px border between items. Default `false` (clean, dense look). Set when migrating from a `Card.List` and you want to preserve the table-row separator visual. |
+| …native | | | plus native `<dl>` attributes |
+
+### `DefinitionListDescriptionProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `icon` | `ReactNode` | no | Leading decorative icon, rendered inside the `<dd>` before children. Wrapped in an `aria-hidden` span — the `<dt>` carries the semantic label so the icon is purely visual. |
+| `children` | `ReactNode` | yes | The value content. Any ReactNode — text, Badges, Links, etc. |
+| …native | | | plus native HTML attributes |
+
+### `DefinitionListItemProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `children` | `ReactNode` | yes | A `DefinitionList.Term` and a `DefinitionList.Description`. |
+| …native | | | plus native `<div>` attributes |
+
+### `DefinitionListTermProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `children` | `ReactNode` | yes | The label text — kept short, terms are headings for their values. |
+| …native | | | plus native HTML attributes |
+
+<!-- props:end -->
+
+Use this instead of `Card.List` + `Card.ListRow` whenever the data is genuinely key/value (every row has a label and a value). Use `Card.List` when rows aren't keyed (activity feeds, list of cards).
+
+**Anti-patterns**
+
+- ❌ Wrapping a `<DefinitionList.Description>` directly in `<DefinitionList>` without an enclosing `<DefinitionList.Item>` — the dev warning fires and grid layout breaks.
+- ❌ Putting interactive content in `<DefinitionList.Term>`. Use `<DefinitionList.Description>` for values, including ones containing `<Link>` or `<Button>`.
+- ❌ Stacking multiple `<DefinitionList.Description>` children under one Item to render "multiple values for one key." Works HTML-wise but doesn't have styling support — render multiple Items with the same Term text if you need that pattern.
+
+Not for tabular data with multiple columns per row — use `Table` / `DataTable`.
+
+```tsx
+// Stacked (settings-style)
+<DefinitionList layout="stacked">
+  <DefinitionList.Item>
+    <DefinitionList.Term>Workspace name</DefinitionList.Term>
+    <DefinitionList.Description>Acme Corp</DefinitionList.Description>
+  </DefinitionList.Item>
+</DefinitionList>
+```

package/docs/components/Divider.md

@@ -0,0 +1,57 @@
+# `<Divider>` — separator primitive
+
+Thin rule between content sections. Horizontal (default) or vertical. Optional centered label slot. Three size tiers + solid/dashed variants.
+
+```tsx
+import { Divider } from '@eocrm/design-system';
+
+// Default horizontal
+<Divider />
+
+// Vertical inside a Cluster (toolbar separator)
+<Cluster gap="sm">
+  <Button>Edit</Button>
+  <Divider orientation="vertical" />
+  <Button>Duplicate</Button>
+</Cluster>
+
+// Labeled (auth-form pattern)
+<Divider>OR</Divider>
+
+// Variants + sizes
+<Divider variant="dashed" />
+<Divider size="lg" />
+```
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `orientation` | `'horizontal' \| 'vertical'` | no | Layout direction. Defaults to `'horizontal'`. |
+| `variant` | `'solid' \| 'dashed'` | no | Line style. Defaults to `'solid'`. |
+| `size` | `'sm' \| 'md' \| 'lg'` | no | Line thickness tier. Defaults to `'sm'`. |
+| `children` | `ReactNode` | no | Optional centered label rendered between two line segments. Common pattern: `<Divider>OR</Divider>` for auth-form section breaks. When `children` is set, the root becomes `<div role="separator">` instead of `<hr>` (HTML `<hr>` cannot have children). Works with `orientation="vertical"` but renders awkwardly (text wraps across two short line segments). Avoid vertical + label combos. |
+| …native | | | plus native HTML attributes |
+
+<!-- props:end -->
+
+- **Without `children`** it renders a native `<hr>` (the right semantic for a thematic break).
+- **Default**: solid, size `'sm'` (1px), horizontal.
+- **Labeled** dividers use `<div role="separator">` instead of `<hr>` because HTML `<hr>` can't have children.
+- **Vertical** dividers stretch to the parent's height — works inside Cluster/Stack/Flex but needs a parent with known height. Falls back to `--space-3` minimum height as a sanity floor.
+- **No spacing prop** — parent owns layout per Rule 4. Use Stack `gap` around the Divider.
+
+#### When NOT to use
+
+- ❌ Decorative under a heading → just style the heading's `border-bottom`.
+- ❌ Between unrelated stacked sections → use Stack with `gap` instead.
+- ❌ A tone-driven separator (warning/danger) → use `<Alert>` for persistent tone-tied messages.
+
+#### Anti-patterns
+
+- ❌ `<Divider>OR</Divider>` with `orientation="vertical"` — text wraps awkwardly across two short line segments.
+- ❌ `<Divider size="lg" />` for casual section breaks. Reserve `lg` (3px) for strong visual hierarchy.
+- ❌ Adding `margin` via inline `style`. The parent should own spacing.

package/docs/components/Dot.md

@@ -0,0 +1,26 @@
+# `<Dot>` — bare palette/tone colored circle
+
+```tsx
+// Palette color, paired with a label:
+<Cluster gap="xs"><Dot color="violet" /> Design</Cluster>
+
+// Semantic tone:
+<Dot tone="success" />
+```
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `color` | `PaletteColor` | no | One of the 30 `PaletteColor`s — renders the bare circle in that color's saturated `--color-palette-<name>-fg` token (the same color OptionsPicker groups and palette Badges use). Takes precedence over `tone`. |
+| `tone` | `'neutral' \| 'info' \| 'success' \| 'warning' \| 'danger' \| 'purple'` | no | A semantic `BadgeTone` (`neutral` default / `info` / `success` / `warning` / `danger` / `purple`) — used when `color` is omitted. Neither set → `neutral`. |
+| …native | | | plus native `<span>` attributes |
+
+<!-- props:end -->
+
+- A bare, background-less 6px circle (`--size-badge-dot`) for color-coding affordances — a leading dot on a filter / `FilterChip`, a status indicator, a legend swatch. Unlike `<Badge dot>` it paints NO badge surface; it is just the dot.
+- **Decorative**: `aria-hidden` by default (overridable). The dot alone conveys nothing to assistive tech — always pair it with a visible label / accessible text.
+- **When NOT to use**: a status pill WITH text → use `<Badge>` (it owns a surface + label). The sole signal of meaning → color isn't an accessible signal on its own; accompany with text.