@eocrm/design-system 0.0.0-stage → 0.6.18

package/docs/components/Grid.md

@@ -0,0 +1,103 @@
+# `<Grid>` — 2D layout primitive
+
+```tsx
+// Auto-fit responsive (default) — columns reflow by container width.
+<Grid gap="md">
+  {cards.map(c => <Card key={c.id}>...</Card>)}
+</Grid>
+
+// Fixed N equal columns.
+<Grid columns={2} gap="lg">
+  <Input label="First name" />
+  <Input label="Last name" />
+</Grid>
+
+// Dashboard widgets — 12-column base, fraction spans, collapses under 640px.
+<Grid columns={12} gap="md" collapseBelow="md">
+  <Grid.Item span="25%"><Card>KPI</Card></Grid.Item>
+  <Grid.Item span="75%"><Card>Chart</Card></Grid.Item>
+  <Grid.Item span="33%"><Card>List</Card></Grid.Item>
+  <Grid.Item span="67%"><Card>Table</Card></Grid.Item>
+  <Grid.Item span="100%"><Card>Footer row</Card></Grid.Item>
+</Grid>
+```
+
+<!-- props:start -->
+
+## Props
+
+### `GridProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `gap` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl'` | no | Gap between cells. `xs` (4) / `sm` (8) / `md` (12, default) / `lg` (16) / `xl` (24) / `2xl` (32). Same scale as Stack and Cluster. |
+| `alignItems` | `'start' \| 'center' \| 'end' \| 'stretch'` | no | Cross-axis (vertical within row) alignment of each cell. Default browser behavior is `stretch`; omit to use the default. Useful for cards of varying intrinsic height. |
+| `justifyItems` | `'start' \| 'center' \| 'end' \| 'stretch'` | no | Main-axis (horizontal within track) alignment of each cell. Default browser behavior is `stretch`; omit to use the default. |
+| `as` | `'div' \| 'section' \| 'ul' \| 'ol' \| 'nav' \| 'main' \| 'aside' \| 'article' \| 'header' \| 'footer'` | no | Element to render. Default `'div'`. Limited to `div`, `section`, `ul`, `ol`, `nav`, `main`, `aside`, `article`, `header`, `footer` rather than fully polymorphic. |
+| `columns` | `number` | no | Fixed number of equal-width columns. Mutually exclusive with `minColumnWidth`. |
+| `minColumnWidth` | `string` | no | Minimum column width for auto-fit responsive layout. Columns reflow based on container width — no breakpoints needed. CSS length string like `'240px'` or `'15rem'`. Defaults to `'240px'` when neither `columns` nor `minColumnWidth` is provided. |
+| `collapseBelow` | `CollapseBreakpoint \| Partial<Record<CollapseBreakpoint, number>>` | no | Collapse to a single visual column when the GRID'S OWN width (container query, not viewport) drops below the preset: `sm` 480px / `md` 640px / `lg` 768px. Every child spans the full row below the threshold — `Grid.Item` spans included. Only valid with `columns` (auto-fit grids already reflow). Consumer inline `style={{ gridColumn }}` on a child still wins below the threshold (inline beats any stylesheet rule) — don't do that; use `Grid.Item span` instead. ❌ Anti-pattern: a `collapseBelow` grid must get its width from its parent. `container-type: inline-size` zeroes the grid's contribution to intrinsic sizing, so in an intrinsic-width context (`Split`'s default `auto` aside track, a `Cluster` item, `width: max-content`) it renders at width 0 — give the parent a concrete width instead. Whichever element carries the containment also becomes the containing block for absolutely-positioned descendants (layout containment) — the grid itself for the string form, the wrapper below for the map form. Also accepts a graduated breakpoint→columns map, e.g. `collapseBelow={{ md: 6, sm: 1 }}`: below 640px the grid re-templates to 6 columns (item spans clamp to fit — a span wider than the step becomes a full row), and below 480px to a single column. Use when jumping straight from N columns to 1 wastes tablet widths. When several breakpoints match, the smallest wins. Only `Grid.Item` children get span clamping; plain children auto-place into the step's tracks. ⚠️ The map form (and ONLY the map form) renders an extra wrapper `<div>` around the grid element — it carries `container-type: inline-size`, because re-templating the grid requires querying an ancestor, not the grid itself. Consequences: a `> child` CSS selector aimed at the grid from its parent now hits the wrapper instead, and layout the parent applies to "the Grid" (`flex: 1`, `grid-column`, `align-self` via `className`) lands on the grid *inside* the wrapper, where the parent's layout can't see it — put that layout on an element you control around the Grid. `ref`, `className`, `style`, `as` and all spread props stay on the grid element. |
+| …native | | | plus native HTML attributes |
+
+### `GridItemProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `span` | `GridItemSpan` | no | Column span. Omit for a single track (auto placement). - number — `span N` of the parent's `columns`. - `'25%' \| '33%' \| '50%' \| '67%' \| '75%'` — fractions of a 12-column grid; use with `columns={12}` (other counts won't produce the named fraction — documented, not validated). - `'100%'` / `'full'` — the entire row; safe with any Grid variant. |
+| `as` | `'div' \| 'li' \| 'section' \| 'article' \| 'aside'` | no | Element to render. Default `'div'`. Use `'li'` inside `<Grid as="ul">`. |
+| …native | | | plus native HTML attributes |
+
+<!-- props:end -->
+
+- **One of `columns` or `minColumnWidth`, not both.** TypeScript enforces it.
+
+**`<Grid.Item span>` — per-cell column span:**
+
+| `span`              | Tracks (12-col grid)                                      |
+| ------------------- | --------------------------------------------------------- |
+| `'25%'`             | 3/12                                                      |
+| `'33%'`             | 4/12                                                      |
+| `'50%'`             | 6/12                                                      |
+| `'67%'`             | 8/12                                                      |
+| `'75%'`             | 9/12                                                      |
+| `'100%'` / `'full'` | full row (`1 / -1`), safe in ANY grid                     |
+| number              | `span N` tracks of whatever `columns` the parent declares |
+
+Fractions assume a 12-column grid — pair them with `columns={12}` on the parent `<Grid>`. A numeric `span` is relative to the parent's actual `columns` count, no 12-col assumption. `Grid.Item` is opt-in; plain children remain valid Grid cells.
+
+**`collapseBelow` — collapse to one column below a width preset:**
+
+Only valid on a fixed-`columns` Grid (auto-fit grids already reflow). Presets: `'sm'` 480px / `'md'` 640px / `'lg'` 768px. This is a **container query on the Grid's own width, not the viewport** — it fires based on the space the Grid itself has, not the browser window, so it collapses correctly inside a narrow sidebar or split pane even on a wide screen — provided the pane gives the grid a definite width. Below the threshold every child spans the full row, `Grid.Item` spans included.
+
+For "one row while the content fits, stacked when it doesn't", use `<Cluster stretchWrapped>` instead of guessing a threshold.
+
+Also takes a graduated breakpoint→columns map instead of a single string, for a step-down rather than straight-to-1-column collapse — `Grid.Item` spans clamp to fit each step:
+
+```tsx
+<Grid columns={12} gap="md" collapseBelow={{ md: 6, sm: 1 }}>
+```
+
+The map form — and only the map form — renders an extra wrapper `<div>` around the grid element, because re-templating the grid needs the size container on an ancestor (a container query never restyles its own container). `ref`, `className`, `style`, `as` and spread props all stay on the grid element, so the only thing that changes for a consumer is the DOM: a `> child` selector aimed at the Grid from its parent now hits the wrapper, and layout meant for "the Grid" (`flex: 1`, `grid-column`, `align-self` via `className`) lands inside the wrapper where the parent can't see it — put that layout on your own element around the Grid. The string form's DOM is unchanged.
+
+**Anti-patterns:**
+
+- ❌ Grid for a single column of vertical flow — use Stack.
+- ❌ Grid for unaligned wrapping rows (toolbars, tag lists) — use Cluster.
+- ❌ `<Grid columns="auto 1fr">` strings — not supported in v1. For asymmetric / named tracks, use raw CSS Grid via className.
+- ❌ `<Grid as="ul">` with non-`<li>` children. The component doesn't enforce list semantics; consumers must.
+- ❌ Fraction spans (other than `'100%'`) on a Grid whose `columns` isn't 12 — the span is a fixed track count, so it overflows into implicit tracks on a non-12 grid.
+- ❌ A `collapseBelow` grid in an intrinsic-width context (`Split`'s default `auto` aside track, a `Cluster` item, `width: max-content`). `container-type: inline-size` makes the grid contribute zero intrinsic width, so it renders at width 0 — the grid must get its width from its parent; give the aside a concrete width instead. The element carrying the containment also becomes the containing block for absolutely-positioned descendants (layout containment) — the grid itself for the string form, the wrapper for the map form; same box geometry either way.
+- ❌ `<Grid>` for a list of clickable items — semantics matter; use `<ul><li>` or `<Grid as="ul">` with `<li>` children.
+- ❌ Inline `gridTemplateColumns` in `style` instead of `columns` / `minColumnWidth` — it bypasses tokens and the responsive default.
+- ❌ A numeric `Grid.Item` `span` larger than `columns` — it overflows into implicit tracks, like fraction spans on a non-12 grid.
+- Under a map-form `collapseBelow`, a `Grid.Item` span wider than a step's column count becomes a full row.
+
+```tsx
+// Photo gallery — auto-fit with a smaller minimum
+<Grid minColumnWidth="160px" gap="sm">{photos.map((p) => <img key={p.id} src={p.src} />)}</Grid>
+
+// Semantic element via `as`
+<Grid as="section" columns={3} gap="md" aria-labelledby="dashboard-title">...</Grid>
+```

package/docs/components/Highlight.md

@@ -0,0 +1,75 @@
+# `<Highlight>` — temporary attention ring on any block
+
+```tsx
+const [justAdded, setJustAdded] = useState<string | null>(null);
+
+<Highlight active={row.id === justAdded} onDone={() => setJustAdded(null)}>
+  <Table.Row>…</Table.Row>
+</Highlight>;
+```
+
+Draws a steady 1px ring just outside its single child, with two waves growing outward 20px from the edge, for `duration` ms (default 3000). The waves run for as long as it's on. After `duration` it fades out and calls `onDone`. It renders **no wrapper**: it clones the child to attach a ref and `data-highlight="on" | "fading"` (a hook for tests and consumers). Nothing else on the child changes, so a `Card` keeps its elevation shadow and tone stripe. It works on `<tr>`, `<li>`, grid cells and any DS component that forwards `ref` to a DOM element. It's decorative only: no role, `aria-*` or `tabIndex` changes.
+
+**How it's drawn:** the ring and waves are on a separate overlay (`aria-hidden`, `pointer-events: none`), portaled to `<body>` and `position: fixed` over the child. It tracks scroll, resize and layout shift. So the waves pass over neighbouring elements and are never clipped by a scroll container, a table's scroll wrapper or a `Card`'s `overflow`. The ring covers the child's **visible** part: the child's rect clipped by every ancestor with `overflow` ≠ `visible` and by the viewport. If the child is scrolled fully out of view, the overlay is hidden. The overlay sits above page content but below fixed app chrome (`--z-app-chrome`), so the top bar covers it when the child scrolls underneath, and dropdowns open above it. Inside a `Modal`, `Drawer`, `Popover` or `Tour`, it rises with its host.
+
+**Known limit:** the ring can paint over sticky elements (e.g. a sticky table header) that the highlighted element scrolls under during a run, unless that sticky element's container clips it.
+
+**Announcing it:** with `focus`, the focus move IS the announcement (the screen reader reads the focused block), so don't also fire a `LiveRegion`. Without `focus`, announce the event with `<LiveRegion>` (for example "Contact created").
+
+**Renamed / removed tokens:** `--highlight-ring` is now `--highlight-color` (override that to recolour the ring and waves). `--highlight-ring-peak`, `--highlight-glow`, `--highlight-glow-blur`, `--highlight-wave`, `--highlight-wave-blur` and `--highlight-wave-count` no longer exist. Use `--highlight-color` and the `--highlight-wave-*` tokens (`-duration`, `-delay`, `-reach`, `-edge`, `-glow`).
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `active` | `boolean` | yes | Turns the highlight on. Each false → true change starts it once: the ring and waves show, the optional scroll and focus run, and after `duration` it fades out and `onDone` fires. Setting it back to false early removes the ring at once WITHOUT calling `onDone`. Keeping it `true` doesn't restart anything; toggle false → true to highlight again. |
+| `duration` | `number` | no | How long the ring holds before fading, in ms. Read when the highlight starts; changing it mid-run has no effect. A non-finite value (`Infinity`, `NaN`) keeps it on until `active` goes false. Default: `3000`. |
+| `onDone` | `(() => void)` | no | Called once, after the fade ends (straight after `duration` under `prefers-reduced-motion`). Typically clears the consumer's `active` state. Not called when `active` is cleared early or on unmount. |
+| `scrollIntoView` | `boolean` | no | On activation, scroll the child to the vertical centre of its scroll container. Smooth, or instant under `prefers-reduced-motion`. Default: `false`. |
+| `focus` | `boolean` | no | On activation, move focus to the child (`preventScroll`, so it never fights `scrollIntoView`). The child must be focusable: give a non-interactive block (`Card`, `<section>`, `<tr>`) `tabIndex={-1}`. Highlight never adds it for you. Default: `false`. |
+| `color` | `PaletteColor` | no | Ring and wave colour, from the shared palette (its saturated `fg` half, readable in both themes). Unset = the accent ring colour. Use a palette colour when the highlight should match the thing it points to (e.g. a category colour); leave it unset otherwise. |
+| `children` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` | yes | Exactly one element that forwards `ref` to a DOM element (nothing else is needed): any DS component, or a native element such as `<tr>` or `<li>`. Highlight renders no wrapper and changes nothing on the child but a `data-highlight` attribute; the ring is drawn on a separate overlay. |
+
+<!-- props:end -->
+
+- **Bring it to the user's attention in one call:** `<Highlight active scrollIntoView focus>`. On activation it scrolls the child to the centre (instantly under `prefers-reduced-motion`) and focuses it with `preventScroll`. A non-interactive child needs `tabIndex={-1}` to take focus. The focus move announces it; no `LiveRegion` needed.
+- **Inside a `DashboardCanvas`:** wrap what `renderItem` returns:
+
+  ```tsx
+  renderItem={(id) => (
+    <Highlight active={id === addedId} scrollIntoView focus onDone={() => setAddedId(null)}>
+      <DashboardWidget tabIndex={-1} title={widgets[id].title}>…</DashboardWidget>
+    </Highlight>
+  )}
+  ```
+
+- **Colour:** `color` takes a palette colour (the saturated `fg` half, readable in both themes); unset is the accent. Use it to match what the highlight points to:
+
+  ```tsx
+  <Highlight active={id === movedId} color="green" onDone={() => setMovedId(null)}>
+    <Card>…</Card>
+  </Highlight>
+  ```
+
+- Under `prefers-reduced-motion` the ring is static (no waves, no fade). `onDone` fires straight after `duration`.
+- `duration={Infinity}` keeps it on until `active` goes false. `duration` is read when the highlight starts; changing it mid-run has no effect.
+- No `forwardRef` / prop spread: Highlight renders no DOM of its own (same as `Tooltip`); props go on the child.
+
+**When NOT to use:**
+
+- To mark a persistent selected or current state, use the component's own selected styling (`aria-selected`, `aria-current`).
+- To show focus, use `:focus-visible`.
+- To report an error, use `Field`'s invalid state or an `Alert`.
+
+#### Anti-patterns
+
+- ❌ `<Highlight active>{'text'}</Highlight>` or multiple children. It needs exactly one element child that forwards `ref`.
+- ❌ Expecting `onDone` after clearing `active` yourself. It only fires when the highlight runs its course.
+- ❌ Leaving `active` true forever with the default duration and expecting it to re-flash. Toggle it false → true to re-trigger.
+- ❌ Relying on the ring alone to tell screen-reader users something changed. Use `focus` (the focus move announces it) or, without `focus`, a `LiveRegion` announcement.
+- ❌ `focus` AND a `LiveRegion` for the same event. The screen reader announces it twice.
+- ❌ A child component that drops `ref` (doesn't forward it to a DOM element). No ring, scroll or focus happens, and Highlight warns in development.
+- ❌ `focus` on a child that can't take focus. Add `tabIndex={-1}`.

package/docs/components/HighlightedText.md

@@ -0,0 +1,50 @@
+# `<HighlightedText>` — `Text` with matched runs in `<mark>`
+
+**TL;DR:** render a plain-text excerpt (e.g. a search result) and highlight the matched substrings. Takes the same props as `Text`, plus `text` and `ranges` (UTF-16 offsets, as most search APIs return them).
+
+```tsx
+<HighlightedText
+  text={result.excerpt}
+  ranges={result.highlights} // [{ start: 12, length: 5 }]
+  size="sm"
+  tone="muted"
+  lineClamp={2}
+/>
+```
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `text` | `string` | yes | The plain text to render. Always rendered as text, never parsed as HTML — safe for untrusted search excerpts. |
+| `ranges` | `readonly HighlightRange[]` | no | Runs of `text` to highlight, as `{ start, length }` in UTF-16 code units (JavaScript string offsets — what most search APIs return). Out-of-range runs are clamped, empty ones dropped, overlapping or touching ones merged. Order doesn't matter. Defaults to `[]` (plain text). |
+| `htmlFor` | `string` | no | Associates a `<label>` with its form control. Only meaningful when `as="label"` — passes through as the native `for` attribute. |
+| `as` | `'p' \| 'span' \| 'div' \| 'label'` | no | Rendered element. Defaults to `'p'` (block, default body text). Use `'span'` for inline runs, `'div'` for block containers that can't be a `<p>` (e.g. when the body needs nested block-level elements that React would warn about inside `<p>`), `'label'` for form labels (pair with `htmlFor`). |
+| `size` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| 'inherit'` | no | Visual size. Defaults to `'md'` (body text). - `xs` — 11px, dense metadata / captions - `sm` — 12px, small body / labels - `md` — 14px, body text (default) - `lg` — 16px, large body / lead text - `xl` — 20px, very large body (rare) - `inherit` — no fixed size; font-size AND line-height inherit from the parent. For inline runs inside a heading (`as="span"` inside a `<Title>` / `<PageHeader.Title>`) that must keep the heading's size — e.g. a muted task-key prefix. Tone / weight still apply — font-weight stays Text's own (default `regular`), it does NOT inherit; pass `weight` to match the heading if needed. |
+| `tone` | `'default' \| 'muted' \| 'subtle' \| 'accent' \| 'danger' \| 'success' \| 'warning'` | no | Color tone. Defaults to `'default'`. - `default` — `--color-fg` - `muted` — `--color-fg-muted` (for secondary copy) - `subtle` — **@deprecated: resolves to `muted`. Use `muted`.** In LIGHT theme the two neutrals were indistinguishable: OKLab ΔE 0.0261 when the deprecation was filed, 0.0365 after `--color-fg-muted` was retuned, against the 0.065 floor this library's perceptual gates use. In DARK they were 0.0707 apart — a real step — so **this deprecation changes dark-theme appearance**: `subtle` text in dark gets lighter, moving from `--color-fg-subtle` to `--color-fg-muted`. That is the accepted trade (a tier that exists in one theme only is not a tier), but it is a visual change, not the removal of a duplicate. `--text-fg-subtle` now aliases `--text-fg-muted`, so nothing breaks at the type or build level; if you need the old dark value back, override `--text-fg-subtle`. - `accent` — `--color-accent` - `danger` / `success` / `warning` — state-coded text |
+| `weight` | `'regular' \| 'medium' \| 'semibold' \| 'bold'` | no | Font weight. Defaults to `'regular'`. |
+| `align` | `'left' \| 'center' \| 'right'` | no | Text alignment. Defaults to `'left'`. |
+| `truncate` | `boolean` | no | Truncate to a single line with ellipsis. Defaults to `false`. Use inside narrow containers (table cells, card list rows). Mutually exclusive with `lineClamp` — if both are set, `lineClamp` wins. |
+| `lineClamp` | `number` | no | Clamp to N lines with ellipsis (uses `-webkit-line-clamp`). Defaults to `undefined`. Overrides `truncate` when set. Example: `lineClamp={2}` for a 2-line description that ellipses on the third. If you also pass `style.WebkitLineClamp`, the `lineClamp` prop takes precedence — the component merges the dynamic line-clamp value into `style` AFTER spreading your `style`, so the prop wins. |
+| …native | | | plus native HTML attributes |
+
+<!-- props:end -->
+
+- Matches render as native `<mark>` (the HTML highlight role), so screen readers that report highlights see them — not just a colour change. Background is `--highlighted-text-mark-bg` (defaults to `--color-palette-yellow-bg`); matched text is always full-strength `--highlighted-text-mark-fg` (`--color-fg`) regardless of `tone` — muted and danger text fail AA contrast on the dark-theme yellow, and the stronger match text reads as emphasis anyway.
+- `text` is always rendered as text, never parsed as HTML — safe for untrusted excerpts.
+- Ranges are forgiving: unsorted, overlapping, touching, out-of-range and empty ranges are all fine (merged / clamped / dropped).
+
+#### When NOT to use
+
+- ❌ Drawing attention to a whole block, card or field — that's `Highlight` (an attention ring), not a text match.
+- ❌ Rich formatted content — `HighlightedText` takes a plain string. For formatted docs use `RichText`.
+- ❌ Emphasis that isn't a match (`<strong>`-style importance) — use `Text weight="semibold"`.
+
+#### Anti-patterns
+
+- ❌ Building the `<mark>` spans yourself with `dangerouslySetInnerHTML` from the API's highlighted HTML — XSS risk and no tokens. Pass the plain excerpt + `ranges`.
+- ❌ Computing ranges with code-point indices (`[...text]`) — offsets are UTF-16 (`text.slice` / `indexOf` units). Emoji and other astral characters shift otherwise.
+- ❌ Restyling the mark with an inline `style` — override `--highlighted-text-mark-bg` instead.

package/docs/components/IconPicker.md

@@ -0,0 +1,134 @@
+# `<IconPicker>` — choose one glyph from a consumer catalog
+
+**TL;DR:** controlled popover grid for choosing one icon from a consumer-curated catalog. Add `color` + `onColorChange` to also pick a palette colour, and `size` to match `Input` / `Select` heights.
+
+```tsx
+const options = [
+  { value: 'flame', label: 'Flame', icon: <Flame /> },
+  { value: 'zap', label: 'Lightning', icon: <Zap /> },
+];
+<Field label="Priority icon">
+  <IconPicker value={icon} options={options} onChange={setIcon} />
+</Field>;
+```
+
+<!-- props:start -->
+
+## Props
+
+### `IconPickerProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `value` | `string` | yes | Currently selected option value. Controlled — required. |
+| `options` | `IconPickerOption[]` | yes | Consumer-curated icons rendered in the supplied order. Values must be stable and unique. An empty list disables the trigger. |
+| `onChange` | `(value: string) => void` | yes | Fires exactly once with the chosen option value, including when it equals the controlled `value`. Closes the popover in icon-only mode; colour mode keeps it open. |
+| `disabled` | `boolean` | no | Disables the trigger, prevents opening and selection, and closes an open picker. Default: `false`. |
+| `size` | `'sm' \| 'md' \| 'lg'` | no | Trigger size, matching the sm/md/lg field heights. Default: `'md'`. |
+| `invalid` | `boolean` | no | Marks the focusable trigger invalid for Field composition. Default: `false`. |
+| `required` | `boolean` | no | Consumed for Field composition so Field can render its visible required marker. Native buttons do not support `aria-required`, so this does not add required semantics to the trigger. Default: `false`. |
+| `popoverPlacement` | `'top' \| 'top-start' \| 'top-end' \| 'bottom' \| 'bottom-start' \| 'bottom-end'` | no | Preferred popover placement. Floating UI may flip it to remain visible. - `'top'` — above, centered. - `'top-start'` — above, start-aligned. - `'top-end'` — above, end-aligned. - `'bottom'` — below, centered. - `'bottom-start'` — below, start-aligned. - `'bottom-end'` — below, end-aligned. Default: `'bottom-start'`. |
+| `aria-label` | `string` | no | Accessible picker purpose. It names the trigger with the selected icon appended and names the dialog without that suffix (in icon-only mode it names the radiogroup too; in colour mode the radiogroups are named by their visible "Colour"/"Icon" headings). Defaults to the localized `iconPicker.triggerLabel` value when omitted OR empty — an empty string is not an explicit name, so it takes the default too. In colour mode the default is `iconPicker.triggerLabelWithColor` and the trigger appends the colour name as well. |
+| `aria-labelledby` | `string` | no | Id(s) of external elements that provide the picker purpose. They name the dialog directly (and the radiogroup in icon-only mode; colour-mode radiogroups use their visible headings). The trigger also references hidden selected-option text, plus hidden colour-name text in colour mode, so its name remains the visible purpose plus the current selection. |
+| `aria-describedby` | `string` | no | Id(s) of element(s) that describe the trigger button. |
+| `color` | `PaletteColor` | no | Controlled palette colour. Passing it turns on colour mode. |
+| `onColorChange` | `(color: PaletteColor) => void` | no | Fires with the chosen palette colour; the popover stays open. |
+| `colors` | `readonly PaletteColor[]` | no | Offered colours, in order. Default: `PALETTE_COLORS`. |
+| …native | | | plus native HTML attributes |
+
+### `IconPickerBaseProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `value` | `string` | yes | Currently selected option value. Controlled — required. |
+| `options` | `IconPickerOption[]` | yes | Consumer-curated icons rendered in the supplied order. Values must be stable and unique. An empty list disables the trigger. |
+| `onChange` | `(value: string) => void` | yes | Fires exactly once with the chosen option value, including when it equals the controlled `value`. Closes the popover in icon-only mode; colour mode keeps it open. |
+| `disabled` | `boolean` | no | Disables the trigger, prevents opening and selection, and closes an open picker. Default: `false`. |
+| `size` | `'sm' \| 'md' \| 'lg'` | no | Trigger size, matching the sm/md/lg field heights. Default: `'md'`. |
+| `invalid` | `boolean` | no | Marks the focusable trigger invalid for Field composition. Default: `false`. |
+| `required` | `boolean` | no | Consumed for Field composition so Field can render its visible required marker. Native buttons do not support `aria-required`, so this does not add required semantics to the trigger. Default: `false`. |
+| `popoverPlacement` | `'top' \| 'top-start' \| 'top-end' \| 'bottom' \| 'bottom-start' \| 'bottom-end'` | no | Preferred popover placement. Floating UI may flip it to remain visible. - `'top'` — above, centered. - `'top-start'` — above, start-aligned. - `'top-end'` — above, end-aligned. - `'bottom'` — below, centered. - `'bottom-start'` — below, start-aligned. - `'bottom-end'` — below, end-aligned. Default: `'bottom-start'`. |
+| `aria-label` | `string` | no | Accessible picker purpose. It names the trigger with the selected icon appended and names the dialog without that suffix (in icon-only mode it names the radiogroup too; in colour mode the radiogroups are named by their visible "Colour"/"Icon" headings). Defaults to the localized `iconPicker.triggerLabel` value when omitted OR empty — an empty string is not an explicit name, so it takes the default too. In colour mode the default is `iconPicker.triggerLabelWithColor` and the trigger appends the colour name as well. |
+| `aria-labelledby` | `string` | no | Id(s) of external elements that provide the picker purpose. They name the dialog directly (and the radiogroup in icon-only mode; colour-mode radiogroups use their visible headings). The trigger also references hidden selected-option text, plus hidden colour-name text in colour mode, so its name remains the visible purpose plus the current selection. |
+| `aria-describedby` | `string` | no | Id(s) of element(s) that describe the trigger button. |
+| …native | | | plus native `<div>` attributes |
+
+### `IconPickerColorProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `color` | `PaletteColor` | no | Controlled palette colour. Passing it turns on colour mode. |
+| `onColorChange` | `(color: PaletteColor) => void` | no | Fires with the chosen palette colour; the popover stays open. |
+| `colors` | `readonly PaletteColor[]` | no | Offered colours, in order. Default: `PALETTE_COLORS`. |
+
+<!-- props:end -->
+
+`color` and `onColorChange` are required together (both or neither), even though the table above shows each as optional.
+
+- The consumer owns icon values, labels, glyphs, ordering, and controlled state.
+- `<Field label>` names the trigger with the visible label plus the selected option, and forwards description and invalid state to that button; the dialog and radiogroup use only the visible Field label. These attributes do not sit on the role-less wrapper. `required` remains a visible Field marker rather than unsupported `aria-required` on the native button.
+- Use it for compact visual choices; use `Select` when visible option text matters.
+- Labels must be human-readable and values unique. Do not pass icon codes as labels.
+- Controlled-only. Not for a small always-visible set of text choices (use `<RadioGroup>`) or for actions rather than a persistent value (use `<DropdownMenu>`).
+- Do not place buttons, links or other focusable content inside an option glyph.
+
+```tsx
+const [icon, setIcon] = useState('flame');
+<Cluster gap="sm" align="center">
+  <IconPicker value={icon} options={iconOptions} onChange={setIcon} />
+  <Text>{icon}</Text>
+</Cluster>;
+```
+
+## Colour mode
+
+Pass `color` + `onColorChange` (both or neither) to also pick a palette colour. The trigger is tinted, the popover shows "Colour" and "Icon" groups, and picking does not close it. `colors` defaults to every palette colour; narrow it to a subset. A disabled picker keeps its tint, dimmed.
+
+Wrapping: `IconPickerColorProps` is a union, so intersect with a type alias, not `interface extends`: `type MyProps = IconPickerBaseProps & IconPickerColorProps & { ... }`. To narrow safely, use `Omit<IconPickerBaseProps, ...> & IconPickerColorProps` (never `Omit` the union itself). For a record whose colour may be unset, pass a fallback: `color={record.color ?? 'slate'}`.
+
+Keyboard in colour mode: Tab moves between the Colour and Icon groups, arrows move and select, picking keeps the popover open, Esc closes and returns focus to the trigger.
+
+```tsx
+<Field label="Appearance">
+  <IconPicker
+    value={icon}
+    options={iconOptions}
+    onChange={setIcon}
+    color={color}
+    onColorChange={setColor}
+  />
+</Field>
+```
+
+## Beside an Input
+
+`size` (`sm` / `md` / `lg`, 24 / 32 / 40px) matches `Input` / `Select` heights. Without a label it is still named "Pick icon and colour"; when that is too generic, give it a specific purpose via `aria-label` or `<Field label>`.
+
+```tsx
+<Split
+  gap="sm"
+  align="center"
+  aside={
+    <IconPicker
+      size="md"
+      aria-label="Icon and colour" // localize this
+      value={icon}
+      options={iconOptions}
+      onChange={setIcon}
+      color={color}
+      onColorChange={setColor}
+    />
+  }
+>
+  <Input size="md" aria-label="Name" value={name} onChange={(e) => setName(e.target.value)} />
+</Split>
+```
+
+## When NOT to use
+
+- ❌ Pairing IconPicker with a separate colour `PillMenu` / `Select` — use colour mode.
+- ❌ Using it for arbitrary hex values — use `ColorPicker`.
+- ❌ A picker beside a Name input left with the generic default name when a specific purpose (`aria-label` or `<Field label>`) would help.

package/docs/components/IconTile.md

@@ -0,0 +1,30 @@
+# `<IconTile>` — palette-colored icon frame
+
+```tsx
+<IconTile color="blue" icon={<Zap size={16} />} />
+<IconTile color="amber" shape="circle" icon={<MailPlus size={14} />} />
+<IconTile color="green" label="Verified" icon={<Check size={16} />} />
+```
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `icon` | `ReactNode` | yes | The icon to frame — a lucide icon (sized by you, ~14–20px), custom SVG, or any ReactNode. Required; IconTile is purely an icon frame. |
+| `color` | `PaletteColor` | no | Palette color for the tint — one of the 30 categorical colors. Defaults to `'slate'`. Categorical (visual identity), NOT semantic; for status use a `<Badge tone>` instead. |
+| `size` | `'inline' \| 'xs' \| 'sm' \| 'md' \| 'lg'` | no | Tile box size. `'xs'` 20 / `'sm'` 24 / `'md'` 32 (**default**) / `'lg'` 40 px. Sizes the tile box — size your icon child separately. `'xs'` brackets a 14px glyph with ~3px of padding so the tile sits inside a text / Badge / EntityChip row without growing it. `'inline'` is font-relative: a `1em` tile (the surrounding text's font-size) centred on the text's capitals, whose glyph the tile sizes to `0.75em` — a direct `<svg>` child's (a lucide icon's) own `size` is overridden; wrap nothing around the icon. Use it in text contexts (`EntityChip` `icon` / `trailing`, `Badge` rows, dense lists, running text) where even `xs` towers over the capitals. It follows `font-size`, so there is no size decision per call site. Not for standalone tiles — it is only as big as the text. |
+| `shape` | `'square' \| 'circle'` | no | `'square'` (radius-md, **default**) or `'circle'` (radius-full). |
+| `label` | `string` | no | Accessible name. Omit (**default**) → the tile is decorative (`aria-hidden`), for use beside text that carries the meaning. Set it → `role="img"` + `aria-label`, for a standalone tile whose icon is the only indicator. |
+| …native | | | plus native `<span>` attributes |
+
+<!-- props:end -->
+
+- A small decorative tile framing one icon, tinted by a **Palette** `color` (one of the 30 categorical colors; default `'slate'`). For a person use `<Avatar>`; for text/status use `<Badge>`.
+- Color is categorical (visual identity), **not** semantic — use `<Badge tone>` for status.
+- A11y: decorative by default (`aria-hidden`); pass `label` to make it `role="img"` + `aria-label` when the icon is the only indicator.
+- Not for a plain icon with no tinted container — render the lucide icon directly.
+- ❌ A decorative IconTile as the ONLY indicator of meaning with no nearby text — pass a `label`.
+- ❌ `size="xs"` in a chip or text row where it towers over the text (it is a fixed 20px) — use `size="inline"`.

package/docs/components/Image.md

@@ -0,0 +1,84 @@
+# `<Image>` — image with loading + error states
+
+```tsx
+<Image src={url} alt="Quarterly revenue chart" aspectRatio="16 / 9" />
+```
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `src` | `string` | yes | Image URL. Changing it resets the component to the loading state. |
+| `alt` | `string` | yes | Alternative text (required). Describe the image's content or function. Pass an empty string (`alt=""`) for purely decorative images. |
+| `objectFit` | `'cover' \| 'contain' \| 'fill' \| 'none' \| 'scale-down'` | no | How the image fills its box. Defaults to `'cover'`. - `'cover'` — fill + crop (no distortion). Best for thumbnails / heroes. - `'contain'` — whole image, letterboxed; the bars show the surface, or the muted box with `background="muted"`. - `'fill'` — stretch to the box (may distort). - `'none'` / `'scale-down'` — native size / the smaller of none\|contain. |
+| `objectPosition` | `string` | no | Which part of the image stays in view when `objectFit` crops or letterboxes it. Any CSS `object-position` value. Defaults to `'center'`. Use `'top'` for document / screenshot thumbnails cropped square, so the header stays visible. |
+| `aspectRatio` | `string \| number` | no | Reserve the box at a fixed ratio to prevent layout shift while loading. Number (`1.5`) or CSS string (`'16 / 9'`). |
+| `size` | `'xs' \| 'sm' \| 'md' \| 'lg'` | no | Render a fixed **square** box of this size (from the shared `--size-*` scale: `'xs'` 20 / `'sm'` 24 / `'md'` 32 / `'lg'` 40 px) instead of filling the container's width. Use for dense thumbnails (e.g. a 40px image cell in a table row) so you don't need a consumer-owned fixed-width wrapper. Omit for the default responsive behavior. When set, `aspectRatio` is ignored (the box is already square); pair with `objectFit="cover"` to crop. Note that a sized image's error tile is icon-only and **not retryable** — see the component description. |
+| `radius` | `'none' \| 'sm' \| 'md' \| 'lg' \| 'full'` | no | Corner rounding. Defaults to `'md'`. Pass `'none'` for square corners; for circular profile images use `<Avatar>`. |
+| `background` | `'muted' \| 'none'` | no | Backdrop behind the loaded image. Defaults to `'none'`, so transparent assets (logos, PNG/SVG) show their surface. Pass `'muted'` for the muted fill (letterboxed `contain` images). The loading skeleton and the error tile keep their fill either way. |
+| `fallback` | `ReactNode` | no | Custom node rendered in place of the default broken-image placeholder when the image fails to load. Overrides the icon + message + retry entirely. This is also the only way to put a control on a failed fixed-`size` image, whose built-in error tile is icon-only. At a fixed `size` the node is rendered in a slot that fills the box (so it cannot flow outside the wrapper's clip); fitting your content into those 20-40px is still yours, and a labelled button does not fit any of them. |
+| `loading` | `'eager' \| 'lazy'` | no | Native lazy-loading hint. Defaults to `'lazy'`. Pass `'eager'` for above-the-fold / LCP images. |
+| `interactive` | `boolean` | no | Make the image a flush, keyboard-accessible click target — renders the image inside a chromeless `<button>` (no padding/border/background; DS focus ring on `:focus-visible`). Implied when `onClick` is set. Use for a thumbnail that opens a preview/lightbox. The broken-image error state is non-interactive (the fluid tile's Retry takes over when its box has room; otherwise there is no control). |
+| `onClick` | `MouseEventHandler<HTMLButtonElement>` | no | Click handler for the interactive trigger. Setting it implies `interactive`. Fires on click and on Enter/Space (native `<button>` keyboard behavior). |
+| `ariaLabel` | `string` | no | Accessible label for the interactive trigger — action-oriented, e.g. `"Preview report.png"`. Defaults to `alt` when omitted OR empty — an empty string is not an explicit name, so it takes the default too. Only used when interactive. Note: a native `aria-label` passed via `{...rest}` lands on the `<img>`, not the trigger button — use `ariaLabel` to name the trigger. |
+| …native | | | plus native `<img>` attributes |
+
+<!-- props:end -->
+
+Robust `<img>`: `Skeleton` while loading, fade-in on load, compact `ImageOff` error
+placeholder on failure — with a retry button when the image is fluid, icon-only when
+it has a fixed `size`.
+
+- `ref` → the `<img>`, which is re-created when `src` changes or on Retry (re-attach observers in an effect keyed on `src`); `className`/`style` → the wrapper box.
+
+**The error tile depends on `size`.** Without `size` it is icon + message + a **Retry** button when the box can hold them (about 96×104px or more at the default tokens; a longer custom `image.retry` label needs a wider box; the message is kept to two lines, then truncated with an ellipsis). A smaller box gets the icon alone: Retry is removed and the message stays for screen readers, so nothing is left clipped but still focusable. A fluid `Image` with no `aspectRatio` gets a 40px height on error rather than collapsing to 0, so it shows that icon-only tile. A height you set yourself (className/style) still wins. Reserve the box if you want the retry. With `size` (all four of `xs`/`sm`/`md`/`lg` — 20/24/32/40px) it is the **icon alone**, scaled to the box, and the failure is **not retryable**: none of those squares can hold the message _and_ an `sm` Button, and the one that used to render there sat outside the wrapper's `overflow: hidden`, painted nowhere yet still focusable. A screen reader still gets the failure — the sized icon is named `"{alt}: Image failed to load"` (just the phrase when `alt=""`), where the fluid tile leaves the phrase to its visible text. Need a control on a failed thumbnail at those sizes? Pass `fallback`: at a fixed `size` it renders in a slot filling the box, so it can't escape the wrapper, but sizing it to fit 20-40px is on you.
+
+**Backdrop.** `background` defaults to `'none'`: once loaded, the box has no fill, so transparent logos/PNGs show the surface behind them. The skeleton and error tile keep the muted fill. Pass `background="muted"` for the old backdrop (e.g. letterboxed `objectFit="contain"`).
+
+Changed: the loaded state used to paint the muted fill by default; pass `background="muted"` to keep that look.
+
+**Transparent logos**
+
+```tsx
+<Image src={logoSvg} alt="Acme" objectFit="contain" aspectRatio="16 / 9" />
+<Image src={logoSvg} alt="Acme" objectFit="contain" aspectRatio="16 / 9" background="muted" />
+```
+
+**When NOT to use:** circular avatars → `<Avatar>`; crop/zoom UI → `<ImageCrop>`; CSS
+backgrounds → `background-image`; icons → lucide / inline SVG.
+
+**Interactive (flush click target):** set `interactive` (or just `onClick`) to render the image inside a chromeless `<button>` (no padding/border/background; DS focus ring on `:focus-visible`) — a thumbnail that opens a preview/lightbox on click/Enter/Space. `ariaLabel` names the trigger (defaults to `alt`). The broken-image error state is non-interactive (the fluid tile's retry control takes over; a sized tile has no control at all); `ref` still forwards to the `<img>`.
+
+```tsx
+<Image
+  src={att.url}
+  alt={att.filename}
+  size="lg"
+  objectFit="cover"
+  onClick={() => openPreview(att)}
+  ariaLabel={`Preview ${att.filename}`}
+/>
+```
+
+```tsx
+// Fixed 40px thumbnail (dense table cell) — no width:100% stretch
+<Image src={url} alt="report.pdf preview" size="lg" objectFit="cover" />
+
+// Document / screenshot thumbnail cropped square from the TOP (keeps the header in view)
+<Image src={pageUrl} alt="invoice.pdf" aspectRatio={1} objectFit="cover" objectPosition="top" />
+
+// Logo contained on its muted box, square corners
+<Image src={logo} alt="Acme Corp" objectFit="contain" background="muted" radius="none" />
+
+// Eager above-the-fold hero with a custom error fallback
+<Image src={hero} alt="Welcome aboard" loading="eager" aspectRatio={2} fallback={<EmptyState title="Couldn't load the hero image" />} />
+```
+
+The wrapper fills its container's width: give it an `aspectRatio` (or a height) so the box is reserved before the image arrives, unless you pass `size`. Native `width` / `height` attributes on the `<img>` are intrinsic-ratio hints only, not the rendered size.
+
+- ❌ Empty `alt` for a meaningful image — pass a real description.
+- ❌ No `aspectRatio` / height when you care about layout shift.
+- ❌ Wrapping `<Image>` in a `<Button>` / `<Link>` for a clickable thumbnail — it paints button/link chrome over it; use `interactive` / `onClick` for a flush trigger.