@eocrm/design-system 0.0.0-stage → 0.6.18

package/docs/components/Avatar.md

@@ -0,0 +1,49 @@
+# `<Avatar>` — profile circle
+
+```tsx
+<Avatar name="Alex Rivera" />
+<Avatar name="Alex Rivera" src="https://example.com/alex.jpg" size="lg" status="online" />
+
+// Hover-discoverable name (off by default; opt in)
+<Avatar name="Alex Rivera" tooltip />
+
+// In a table row
+<Cluster gap="sm" align="center">
+  <Avatar name={contact.name} size="sm" />
+  <span>{contact.name}</span>
+</Cluster>
+```
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `name` | `string` | yes | The person's name. Required — used as the `alt`/`aria-label`, as the source of the initials, and as the seed for the deterministic fallback color. The same name always renders the same color. When `tooltip` is true, also used as the tooltip body. |
+| `src` | `string` | no | Image URL. When provided, the `<img>` is rendered with `alt={name}`. Empty/whitespace strings are treated as missing. If the image fails to load (404, network), the component automatically falls back to initials. |
+| `size` | `'inline' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | no | Diameter. - `sm` (24px) — table rows, dense lists. - `md` (32px, default) — most uses. - `lg` (40px) — detail-page headers. - `xl` (80px) — member-card popovers / profile headers. - `inline` — one line of the surrounding text tall (`1lh`), initials scaled to match, so an avatar in a text row (a `DefinitionList` value, a table cell, a line of text) doesn't make it taller. Follows the text size; no size decision per call site. Not available on `<AvatarGroup>` — and don't set it per child inside one: the group's overlaps are sized for its fixed steps. Inside `<AvatarGroup>`, defaults to the group's `size`. |
+| `status` | `'online' \| 'busy' \| 'away' \| 'offline'` | no | Presence dot in the bottom-right. - `'online'` — green. - `'busy'` — red. - `'away'` — amber (the categorical amber, dark enough to read at dot size). - `'offline'` — gray. Omit to render no dot at all. Setting `status` changes the accessible name to `"{name}, {status}"` (localized), because colour alone cannot carry the status (WCAG 1.4.1); query with `getByRole('img', { name: 'Alex, online' })`. Each status also renders a distinct shape (filled / half / barred / hollow), so it survives colour-vision deficiency and greyscale; the dot stays `aria-hidden` so nothing is announced twice. |
+| `tooltip` | `boolean` | no | Whether to wrap the avatar in a `<Tooltip>` showing `name`. Defaults to `false` (back-compat — existing renders don't gain a hover affordance). Inside `<AvatarGroup>`, the group's `tooltip` prop becomes the default (which itself defaults to `true` for grouped avatars); explicit per-child still wins. |
+| …native | | | plus native `<span>` attributes |
+
+<!-- props:end -->
+
+- Inside `<AvatarGroup>`, the group's `size` and `tooltip` become defaults — explicit per-child props still win. The avatar also picks up a `--color-bg` ring so stacked siblings read as distinct.
+- Use `avatarColorIndex(name)` if you need to match an avatar's color elsewhere (e.g. a chart segment).
+
+#### When NOT to use
+
+- Company logos: Avatars are for people. Use a `Logo` component (not yet shipped) or an `<img>` with rounded corners.
+- As a clickable button. If clicking opens a profile, wrap the Avatar in a `<button>` or `<Link>`; don't make the Avatar itself interactive.
+
+#### Anti-patterns
+
+- ❌ `<Avatar name="" />`: `name` is required and is the accessible label.
+- ❌ Relying on the status dot's colour, or re-tinting it. The distinct shape is the channel that survives colour-vision deficiency, and `away` vs `busy` collapses without it.
+- ❌ Adding your own visually-hidden status text next to the avatar. It is announced twice, and inside the no-`src` branch (a `role="img"`) ARIA prunes children as presentational, so it would be silent there anyway.
+- ❌ Using Avatar for a non-person icon. Use an icon component.
+- ❌ Wrapping the result in `role="img"` again. With `src`, the inner `<img>` is the labeled image; without it, the wrapper has `role="img" aria-label={name}`, plus the localized `status` when set (`"Alex, online"`).
+
+For an AI agent acting on behalf of a member, see [`AgentAvatar`](AgentAvatar.md).

package/docs/components/AvatarGroup.md

@@ -0,0 +1,47 @@
+# `<AvatarGroup>` — Slack-style stacked row of avatars
+
+```tsx
+<AvatarGroup max={4} size="md" onOverflowClick={(_e, n) => openMembersPopover(n)}>
+  {team.map((m) => (
+    <Avatar key={m.id} name={m.name} src={m.avatarUrl} status={m.presence} />
+  ))}
+</AvatarGroup>
+
+// Static: without onOverflowClick the +N is non-interactive
+<AvatarGroup max={3}>
+  <Avatar name="Alex Rivera" />
+  <Avatar name="Priya Patel" />
+  <Avatar name="Tom Kim" />
+  <Avatar name="Sara Chen" />
+</AvatarGroup>
+```
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `children` | `ReactNode` | yes | Avatar children. |
+| `size` | `'sm' \| 'md' \| 'lg' \| 'xl'` | no | Diameter default for child avatars. Defaults to `'md'`. Each child can still override via its own `size` prop (idiomatic React composition — explicit prop wins). For a strictly uniform group, don't set `size` on individual children. - `sm` (24px) — table rows, dense lists. - `md` (32px, default) — most uses. - `lg` (40px) — detail-page headers. - `xl` (80px) — member-card popovers / profile headers. |
+| `max` | `number` | no | Maximum number of visible avatars. Children beyond this count collapse into a single `+N` button at the tail. Defaults to `4`. The `+N` only appears when there are STRICTLY more children than `max`. |
+| `tooltip` | `boolean` | no | Whether to render a name tooltip on each child avatar. Defaults to `true` inside the group (a standalone `<Avatar tooltip>` is opt-in; group context flips that default). Set `false` on the group to suppress all tooltips; overridable per-child by setting `tooltip` on the Avatar. |
+| `onOverflowClick` | `((event: MouseEvent<HTMLButtonElement, MouseEvent>, hiddenCount: number) => void)` | no | Fires when the user clicks the `+N` overflow button. The library does NOT render a popover — apps decide what happens (open a modal, navigate, etc.). When omitted, the `+N` is rendered as a non-interactive `<span>` (still labelled for AT). |
+| …native | | | plus native `<div>` attributes |
+
+<!-- props:end -->
+
+- Horizontal row of overlapping `<Avatar>`s with a `+N` overflow control when child count exceeds `max` (default `4`).
+- The group wrapper is `role="list"` and each visible avatar is wrapped in a `role="listitem"` div; the +N (button or span) is the last list item.
+- forwardRef to the outer `<div>`. `className` is merged.
+
+#### When NOT to use
+
+- A single avatar: use `<Avatar>` directly.
+- Showing member counts but not faces: use a `Badge` next to a label.
+
+#### Anti-patterns
+
+- ❌ Wrapping `<AvatarGroup>` in a `<button>` as one click target. The `+N` is the click affordance; the visible avatars are deliberately not interactive. Wrap individual avatars in `<button>` / `<Link>` if needed.
+- ❌ Mixing avatar sizes inside one group on purpose. Per-child `size` wins, which is useful for emphasising one member but visually noisy if used carelessly.

package/docs/components/Badge.md

@@ -0,0 +1,60 @@
+# `<Badge>` — status / category pill
+
+```tsx
+<Badge tone="success">Active</Badge>
+<Badge tone="danger">Churned</Badge>
+
+// Stripe variant — rectangular category marker with left stripe:
+<Badge variant="stripe" tone="info">Lead</Badge>
+<Badge variant="stripe" tone="warning">Renewal due</Badge>
+
+// Categorical palette color (non-semantic) — for tag-like labels:
+<Badge color="amber">Marketing</Badge>
+<Badge color="teal">Engineering</Badge>
+<Badge variant="stripe" color="violet">Design</Badge>
+
+// Tag list
+<Cluster gap="xs">
+  <Badge tone="purple">Enterprise</Badge>
+  <Badge tone="info">Pipeline 2026</Badge>
+</Cluster>
+
+// Inside a heading line: align="middle" so the badge doesn't ride the heading's baseline
+<Title order={1}>
+  <Text as="span" size="inherit" tone="muted">ENG-5</Text> Fix login flow{' '}
+  <Badge align="middle" tone="warning">In progress</Badge>
+</Title>
+```
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `tone` | `'neutral' \| 'info' \| 'success' \| 'warning' \| 'danger' \| 'purple'` | no | Semantic tone. - `neutral` (default) — generic tag, no semantic meaning. - `info` — new / in-progress / informational states ("Lead", "Pipeline 2026"). - `success` — positive states ("Active", "Won", "Healthy"). - `warning` — at-risk / pending states ("Renewal due", "Pending review"). - `danger` — negative states ("Churned", "Lost", "Blocked"). - `purple` — special / highlighted categories ("Enterprise", "VIP"). |
+| `size` | `'sm' \| 'md'` | no | Pill height and emphasis. - `md` (20px, default) — the standard "loud label" pill. Uppercase, tracked, semibold. Reads as a deliberate status marker. - `sm` (16px) — quieter inline tag for tight table cells, compact toolbars, or anywhere a 20px uppercase pill visually crowds adjacent text. Drops the uppercase transform and caps tracking so it sits next to body copy without shouting; case is preserved as-typed (write `Active`, get `Active`). Same 11px size and semibold weight as `md`. |
+| `dot` | `'start' \| 'end'` | no | Render a small filled circle in the badge's text color alongside the content. Useful when the dot is the primary status signal and the label is supporting context ("● Active", "Failed ●"). - `start` — dot before the content. - `end` — dot after the content. Omit for no dot. The dot is purely decorative (`aria-hidden`) — the badge text remains the accessible label. |
+| `variant` | `'filled' \| 'stripe'` | no | Visual variant. - `'filled'` (default) — solid tone-tinted pill. The standard "loud status" look. - `'stripe'` — rectangular block with a tone-colored left stripe + soft tinted body. Use for category markers or sidebar labels where pill emphasis is too loud. |
+| `color` | `PaletteColor` | no | Optional categorical palette color. When set, takes precedence over `tone`: the badge fills with the matching `--color-palette-<name>-bg/fg` tokens. Use for non-semantic categorical labels (e.g., audit event namespaces, tag colors) where the 6 semantic tones aren't enough. Both filled and stripe variants are supported; for stripe the left-border picks up the palette `fg` token. |
+| `align` | `'baseline' \| 'middle'` | no | Vertical alignment within the surrounding line of text. - `baseline` (default) — rides the text baseline; right for body-size text. - `middle` — centers the badge on the line box; use for a badge inside a heading line (`<Title>` / `<PageHeader.Title>`), where baseline riding makes the badge look sunken next to large text. |
+| …native | | | plus native `<span>` attributes |
+
+<!-- props:end -->
+
+- **Non-interactive.** If it's clickable, use `<Button>` instead.
+- Doesn't auto-add `role="status"`. Wrap the badge (or a parent region) in `aria-live="polite"` if a state change should be announced. **This is not an inconsistency with `EntityChip`, which announces its own state** — a Badge tone is a durable property of the row you are looking at, not a change that happens while you are elsewhere, so there is nothing for the component to announce. See [Transient state and screen readers](../transient-state.md) for the rule both follow.
+
+#### When NOT to use
+
+- ❌ As a button. Badges are non-interactive labels; if it's clickable use a `Button` or `Link`.
+- ❌ For long-form text. Badges are 1-2 words max.
+- ❌ `align="middle"` outside a heading line. It fixes the baseline-vs-line-box mismatch next to large text; keep the default `baseline` next to body-size text.
+
+#### Anti-patterns
+
+- ❌ Mixing tone meanings across pages. `success` may mean "Won" on Deals and "Active" on Contacts, but never use `success` for anything negative.
+- ❌ Stacking 4+ badges on a single row. If you have that many tags, the design problem is information density, not the badge.
+- ❌ Wrapping a Badge in a `<button>` to make it clickable. Use a `Button` with an appropriate variant.
+- ❌ Using `color` (palette) for status. Use `tone` (semantic); palette colors carry no built-in meaning and the mapping may shift over time.

package/docs/components/Banner.md

@@ -0,0 +1,89 @@
+# `<Banner>` — full-width system / app message bar
+
+Tinted, full-width bar for messages about the system or account, not the page: maintenance, "Email sending suspended", "Sending restored". Mount it ONLY in `<AppLayout>`'s `banner` (system-wide, above everything) or `contextBanner` (module/route-scoped, under the top bar) slot. For page content use `<Alert>`.
+
+```tsx
+import { AppLayout, Banner, Link } from '@eocrm/design-system';
+
+<AppLayout
+  banner={
+    <Banner
+      tone="warning"
+      title="Scheduled maintenance"
+      action={<Link href="/status">Details</Link>}
+    >
+      Sat 4 Oct, 22:00–23:00 CET. CRM will be read-only.
+    </Banner>
+  }
+  contextBanner={
+    inEmail &&
+    suspended && (
+      <Banner tone="danger" title="Email sending suspended.">
+        Bounce rate 7.2% (limit 5%).
+      </Banner>
+    )
+  }
+  topBar={<TopBar />}
+  sidebar={<Rail>{nav}</Rail>}
+>
+  {routes}
+</AppLayout>;
+
+// Module-scoped banner that appeared mid-session: danger + live is announced on insertion (role="alert")
+<Banner
+  tone="danger"
+  live
+  title="Email sending suspended."
+  action={
+    <Button size="xs" variant="secondary">
+      Review bounces
+    </Button>
+  }
+>
+  Bounce rate 7.2% (limit 5%).
+</Banner>;
+
+// Dismissible: the app persists the dismissal
+{
+  !dismissed && (
+    <Banner tone="success" onDismiss={() => setDismissed(true)}>
+      Email sending restored.
+    </Banner>
+  );
+}
+```
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `tone` | `'info' \| 'success' \| 'warning' \| 'danger'` | no | Tone. Defaults to `'info'`. `info` — advance notice; `success` — condition resolved; `warning` — imminent or degrading; `danger` — broken or blocked now. See `BannerTone`. |
+| `title` | `ReactNode` | no | Optional bold lead-in, rendered INLINE before `children` in the same text flow ("**Scheduled maintenance** Sat 22:00–23:00."). Keep it short — the banner is one line on desktop. Collapses the native HTML `title` (tooltip) attribute. |
+| `children` | `ReactNode` | no | Message text. Wraps with the title. Keep to one sentence. |
+| `icon` | `ReactNode` | no | Override the tone's default icon (any ReactNode, typically a 16px lucide icon with `aria-hidden`). `null` hides it. Defaults: `info` → `Info`, `success` → `CheckCircle2`, `warning` → `AlertTriangle`, `danger` → `XCircle`. |
+| `action` | `ReactNode` | no | One action pinned to the end of the row — typically a `<Link>` ("Details") or a `<Button size="xs">` ("Review bounces"). Banner doesn't lay out multiple actions; pass one. |
+| `live` | `boolean` | no | Whether the Banner is a live region. Defaults to `false`: `role="note"`, right for a banner that is present when the app loads. Pass `live` for a banner that APPEARS mid-session. Caveat: a mid-session Banner mounts together with its text, and a `role="status"` region that mounts with its text is not reliably announced. Only `tone="danger"` + `live` (`role="alert"`) is announced on insertion. For a must-hear non-danger message, pair the banner with a `<LiveRegion>` or a toast. Decide it at mount — flipping it on a mounted Banner announces nothing. |
+| `onDismiss` | `(() => void)` | no | Called when the × is clicked. When set, the × renders. **Controlled** — Banner keeps no hidden state and persists nothing; the app decides what "dismissed" means (per session, per incident, per user) and stops rendering it. |
+| …native | | | plus native `<div>` attributes |
+
+<!-- props:end -->
+
+- **The tone is spoken.** A visually hidden, localised prefix ("Warning: ") comes before the text.
+- The tone is `danger`, not Alert's `error`.
+- **`live` defaults to `false`** (`role="note"`), because banners are usually present at load. Pass `live` for one that appears mid-session — but a Banner mounts together with its text, so `role="status"` is not reliably announced; only `tone="danger"` + `live` (`role="alert"`) is. For a must-hear non-danger message, add a `<LiveRegion>` or a toast alongside the banner.
+- Neither slot is sticky; only the TopBar pins.
+
+**Anti-patterns**
+
+- ❌ A Banner inside page content. Use `<Alert>`.
+- ❌ `onDismiss` on a `danger` banner while the condition still holds.
+- ❌ Routine stacks of banners in one slot. Show the most severe first.
+- ❌ A system-wide message in `contextBanner`, or a route-specific one in `banner`.
+- ❌ `live` on a banner that is present when the app loads.
+- ❌ Relying on `live` for a non-danger banner to be announced on appearing. Add a `<LiveRegion>` or a toast.
+- ❌ Multiple actions or a paragraph of text. Link to a details page.
+
+**When NOT to use:** content about the current page or a section of it → `<Alert>`; a transient confirmation ("Saved") → `toast.success(...)`; anywhere other than `AppLayout`'s `banner` / `contextBanner` slots (inside page content it is just a borderless Alert).

package/docs/components/BrandIcon.md

@@ -0,0 +1,32 @@
+# `<BrandIcon>` — third-party brand marks
+
+```tsx
+<Button variant="secondary">
+  <BrandIcon name="google" size={16} /> Continue with Google
+</Button>
+
+// Standalone, labeled
+<BrandIcon name="yandex" title="Yandex" size={24} />
+```
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `name` | `'google' \| 'yandex'` | yes | Which brand mark to render. |
+| `size` | `number` | no | Square pixel size (width = height). Defaults to `20`. |
+| `title` | `string` | no | Accessible name. Omit (default) for a decorative icon beside a text label — the icon renders `aria-hidden`. Set it for a standalone icon (e.g. an icon-only button) → `role="img"` + `aria-label`. |
+| …native | | | plus native HTML attributes |
+
+<!-- props:end -->
+
+Full-color official brand marks for SSO buttons. Ships `google` + `yandex`.
+
+- Decorative by default (`aria-hidden`); pass `title` for a labeled standalone icon (`role="img"`).
+
+**When NOT to use:** generic UI glyphs → `lucide-react`. Don't recolor brand marks.
+
+**Anti-pattern:** ❌ a decorative `BrandIcon` next to visible brand text AND a `title` double-announces ("Google Continue with Google"). Keep it `aria-hidden` (the default) beside a label.

package/docs/components/Breadcrumb.md

@@ -0,0 +1,72 @@
+# `<Breadcrumb>` — navigation trail
+
+Compound (Breadcrumb.Item) navigation breadcrumb. Last child is auto-marked as the current page (`<span aria-current="page">`); non-last items are muted Links. Default separator is a ChevronRight icon.
+
+```tsx
+import { Breadcrumb, Link } from '@eocrm/design-system';
+import { Link as RouterLink } from 'react-router-dom';
+
+<Breadcrumb>
+  <Breadcrumb.Item as={RouterLink} to="/mockups">Mockups</Breadcrumb.Item>
+  <Breadcrumb.Item as={RouterLink} to="/mockups/contacts">Contacts</Breadcrumb.Item>
+  <Breadcrumb.Item>Acme Corp</Breadcrumb.Item>      {/* auto-current */}
+</Breadcrumb>
+
+// Custom separator
+<Breadcrumb separator={<Slash size={12} />}>
+  <Breadcrumb.Item as={RouterLink} to="/a">A</Breadcrumb.Item>
+  <Breadcrumb.Item>B</Breadcrumb.Item>
+</Breadcrumb>
+
+// External crumb (default <a>)
+<Breadcrumb>
+  <Breadcrumb.Item href="https://docs.example.com">Docs</Breadcrumb.Item>
+  <Breadcrumb.Item>This page</Breadcrumb.Item>
+</Breadcrumb>
+```
+
+<!-- props:start -->
+
+## Props
+
+### `BreadcrumbProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `children` | `ReactNode` | yes | One or more `<Breadcrumb.Item>` children. The component injects the separator between items and auto-marks the last child as current (renders as `<span aria-current="page">` instead of a link). |
+| `separator` | `ReactNode` | no | Custom separator between items. Defaults to a small `<ChevronRight>` lucide icon. The separator renders inside a `<span aria-hidden="true">` wrapper automatically. |
+| `ariaLabel` | `string` | no | Visible label for the `<nav>` element. Defaults to the i18n value at `breadcrumb.ariaLabel` (`'Breadcrumb'` in English) when omitted OR empty — an empty string is not an explicit name, so it takes the default too. Override when multiple breadcrumb instances coexist on the same page. |
+| `className` | `string` | no | Pass-through className applied to the `<nav>` wrapper. |
+
+### `BreadcrumbItemProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `as` | `ElementType` | no |  |
+| `current` | `boolean` | no | Mark this item as the current page. Forced to `true` automatically for the last child of `<Breadcrumb>` (auto-current). When `true`, the item renders as `<span aria-current="page">` and ignores all link-related props (`as`, `to`, `href`, etc.). |
+| `children` | `ReactNode` | no |  |
+| `className` | `string` | no |  |
+| …native | | | plus native attributes of the `as` element (default `<a>`) |
+
+<!-- props:end -->
+
+- **Compound API** — wrap each crumb in `<Breadcrumb.Item>`.
+- **Auto-current** — last child gets `aria-current="page"` and renders as `<span>`. Override with explicit `current` prop.
+- **Item is polymorphic** — same `as` pattern as Link. It is not `forwardRef`-wrapped because the return shape varies (`<span>` for current, `<Link>` for non-current); for a ref to a specific crumb, render the underlying link manually inside an Item, or use Link directly.
+- Separated by a customizable icon in an `<ol>` inside the `<nav>`.
+- **Default separator** is `<ChevronRight size={14} />`. Override via the `separator` prop.
+- **`<nav aria-label="Breadcrumb">` wrapper** — semantic landmark, AT-friendly.
+
+#### When NOT to use
+
+- ❌ Horizontal nav of equal-importance siblings → `<Tabs>` or `<ButtonGroup>`.
+- ❌ Step-by-step progress → a dedicated Stepper (not shipped).
+- ❌ Single-page apps with no parent hierarchy — omit Breadcrumb entirely.
+
+#### Anti-patterns
+
+- ❌ Making the current page clickable. Current items are non-link by design.
+- ❌ Long trails (5+ levels) — wrap and become illegible.
+- ❌ Building your own `<nav>` + chevron pattern. Use Breadcrumb.

package/docs/components/Button.md

@@ -0,0 +1,107 @@
+# `<Button>` — action triggers
+
+```tsx
+<Button onClick={save}>Save</Button>
+<Button variant="danger" size="sm">Delete</Button>
+<Button variant="secondary" disabled>Cancel</Button>
+<Button
+  variant="secondary"
+  size="sm"
+  selected={ownerApplied}
+  aria-pressed={ownerApplied}
+  onClick={() => setOwnerApplied((value) => !value)}
+>
+  Owner: {ownerLabel}
+</Button>
+
+// Icon-only square button (20×20 at xs, 32×32 at md); aria-label is the accessible name
+<Button size="xs" variant="ghost" iconOnly aria-label="Remove">
+  <X size={12} />
+</Button>
+
+// Destination that must look like a button: a real <a>; rel="noreferrer" belongs with target="_blank"
+<Button as="a" href={idpConsoleUrl} target="_blank" rel="noreferrer" variant="secondary">
+  Open identity console
+</Button>
+
+// Form footer
+<Cluster justify="end" gap="sm">
+  <Button variant="secondary">Cancel</Button>
+  <Button type="submit">Save</Button>
+</Cluster>
+
+// Status quick actions painted like the status pill they set. `noShow` / `completed`
+// are your status records, each with a `color: PaletteColor` that also feeds the
+// PillMenuOption, so a tenant recolouring a status recolours its button too.
+<Cluster gap="sm">
+  <PillMenu current={current} options={statuses} onSelect={setStatusId} />
+  <Button size="sm" color={noShow.color} onClick={() => setStatusId(noShow.id)}>No show</Button>
+  <Button size="sm" color={completed.color} onClick={() => setStatusId(completed.id)}>Completed</Button>
+</Cluster>
+```
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `variant` | `'primary' \| 'secondary' \| 'ghost' \| 'danger' \| 'danger-outline' \| 'success'` | no | Visual variant. - `primary` (default) — the section's main action. Use **one** per page section. - `secondary` — supporting actions like "Cancel", "Export", "Filter". - `ghost` — tertiary actions in dense UIs (toolbar buttons, row actions). - `danger` — destructive operations only (Delete, Revoke, Remove). Pair with a confirmation if irreversible. - `danger-outline` — a destructive action that must not dominate: surface fill, danger text and border. For a Remove repeated on every row, or a destructive action beside a primary one. Use filled `danger` for the confirm step itself. - `success` — **transient confirmation only**, not an initial state. Flip to `success` for ~1.5s after an action resolves (Save → "Saved!"), then flip back. Never render a button as `success` on mount — it has no action-intent meaning, only post-action feedback. See the `@example` below for the timer pattern. |
+| `size` | `'xs' \| 'sm' \| 'md' \| 'lg'` | no | Control height (matches the shared `--size-*` scale used by Input and Avatar). - `xs` (20px) — icon-only or very dense inline actions (row controls, chip-adjacent buttons). Pass `aria-label` when icon-only. Below WCAG 2.5.5 Level AAA touch-target guidance; reserve for desktop-first surfaces. - `sm` (24px) — dense toolbars, tables, inline actions. - `md` (32px, default) — most contexts. - `lg` (40px) — marketing-style empty states or emphasized primary actions. |
+| `iconOnly` | `boolean` | no | Render the button as a square icon-only target — `aspect-ratio` is forced to 1 so width tracks the size's `height` token (`xs` → 20×20, `sm` → 24×24, `md` → 32×32, `lg` → 40×40) and `padding` is tightened to a small inset (4px) so the icon has breathing room without changing the outer shape. **Always pass `aria-label`** when `iconOnly` is set, otherwise the button has no accessible name. Pass a single icon as `children`. Use for inline density (row controls, chip-adjacent actions, toolbar affordances). For an icon + short text label, leave `iconOnly` off — the button will lay out as a normal rectangle with the existing gap. |
+| `selected` | `boolean` | no | Controlled persistent paint for an applied filter or toolbar value. Selected paint applies only to `secondary` and `ghost` Buttons; `primary`, `danger`, and `success` retain their intent paint. This prop is visual only and does not add toggle-button semantics. Pass native `aria-pressed` explicitly only when activating the Button itself toggles the selected state; menu and disclosure triggers keep their own semantics. The consumer owns the state. Not for transient success feedback or for mutually exclusive `<ButtonGroup>` choices. Defaults to `undefined` (not selected). |
+| `color` | `PaletteColor` | no | Paint the button with a palette color's soft pair (`--color-palette-<color>-bg` fill, `-fg` text) — the same pair a palette-colored `<PillMenu>` or `<Badge color>` uses, in both themes. For a quick action that moves a record to a status and must look like that status's pill (amber "No show" beside an amber status PillMenu). Not a decorative stand-in for `danger`/`success`: palette colors carry no meaning. When set it wins over `variant` and `selected` (like `<Badge color>` over `tone`). Hover/pressed darken via `filter: brightness()`. Defaults to `undefined` (use `variant`). |
+| `as` | `ElementType` | no | Render a different element — the case that matters is `as="a"` with `href`, for a link that must LOOK like a button (an external console, a download, an IdP hand-off). The element named here is what actually renders, and its own attributes are typed: `href` is REQUIRED when `as="a"` (an anchor without one is neither focusable nor a link) and rejected otherwise; `target`/`rel`/`download` come through. Never navigate from `onClick`. Reach for `<Link>` first. `<Link>` is link-SHAPED navigation — inline text in a sentence, a table cell, a breadcrumb. `<Button as="a">` is for a destination that sits in a row of buttons and must carry their weight. Either way the element is a real anchor, so assistive tech announces a link and the browser gives middle-click, "open in new tab", and the status bar preview — none of which a `<button onClick={() => navigate()}>` has. `type="button"` is emitted only for a real `<button>`; an anchor never gets it. Everything else — variant, size, `iconOnly`, `selected`, the focus ring — is unchanged. Default: `'button'`. |
+| …native | | | plus native attributes of the `as` element (default `<button>`) |
+
+<!-- props:end -->
+
+- Always renders `<button type="button">` unless you pass `type="submit"` — or unless you pass `as`. It won't submit ancestor forms by default.
+- `aria-disabled="true"` keeps an unavailable action focusable (so keyboard users can discover it and its explanation) with the unavailable visual treatment, but does not set native `disabled` or prevent events: the consumer's handler must suppress activation while it is unavailable.
+- `variant="success"` is a **transient confirmation state**, not an action intent. Flip to it for ~1.5s after the action resolves, then flip back to `primary`. The timer is the consumer's responsibility — Button stays stateless. Never render a button as `success` on initial mount. Track the timer in a `useRef` and clear on unmount + on rapid re-clicks so the flash doesn't outlive the component or get cut short.
+
+  ```tsx
+  const [saved, setSaved] = useState(false);
+  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  useEffect(
+    () => () => {
+      if (timerRef.current) clearTimeout(timerRef.current);
+    },
+    [],
+  );
+  const handleSave = async () => {
+    await save();
+    if (timerRef.current) clearTimeout(timerRef.current);
+    setSaved(true);
+    timerRef.current = setTimeout(() => setSaved(false), 1500);
+  };
+  <Button variant={saved ? 'success' : 'primary'} onClick={handleSave}>
+    {saved ? 'Saved!' : 'Save'}
+  </Button>;
+  ```
+
+#### When NOT to use
+
+- ❌ Navigation in running text, a table cell, or a breadcrumb → `<Link>`.
+- ❌ Toggle state (on/off) → `Switch` or `Checkbox`, not a Button with internal state.
+- ❌ Mutually exclusive choices → `<ButtonGroup>`, which supplies the group-level selection semantics.
+- ❌ A clickable table row → make the row itself the interactive surface; don't nest a button.
+- ❌ Decorative color for an ordinary action → `variant`. `color` is only for an action that must match a palette-colored `<PillMenu>` / `<Badge color>` (a status or category it sets); resolve it from the same source as that pill so a recolored status carries its button along.
+- On touch-first surfaces prefer `size="sm"` or larger: `xs` (20px×~28px, or 20×20 with `iconOnly`) is below WCAG 2.5.5 Level AAA touch-target guidance (24×24); acceptable here because the CRM is desktop-first.
+
+#### Anti-patterns
+
+- ❌ Two `variant="primary"` Buttons in the same section. Pick one; others are `secondary`.
+- ❌ `<Button style={{ marginLeft: 'auto' }}>` — wrap in `<Cluster justify="end">` (or `justify="between"` with a sibling) instead.
+- ❌ Overriding padding/height via `className`. A different visual size is a missing variant: request it.
+- ❌ `variant="ghost"` for the page's primary action. Users won't discover it.
+- ❌ `<Button variant="success">Save</Button>` on initial mount. Start as `primary` and flip to `success` after the action resolves.
+- ❌ `<Button color="red">Delete</Button>` or `color="green"` for a confirm. Palette colors carry no meaning; destructive is `variant="danger"`, post-action feedback is `variant="success"`.
+- ❌ `<Button color="amber" variant="secondary">`. `color` wins over `variant` (and `selected`), so the `variant` is dead code — pass one or the other.
+- ❌ `size="xs"` for the primary or most prominent action. `xs` is for inline density, not emphasis; reach for `md` or `lg`.
+- ❌ `<Button iconOnly><X /></Button>` without `aria-label`: screen readers announce nothing.
+- ❌ Assuming `selected` adds toggle semantics. It is paint only; pass `aria-pressed` explicitly when activating the Button toggles that state, and not on menu or disclosure triggers.
+- ❌ Assuming `aria-disabled="true"` blocks activation. It preserves native focusability and pointer events; guard your handler.
+- ❌ `<Button onClick={() => (window.location.href = url)}>` for navigation: it announces as a button, with no middle-click, no open-in-new-tab and no status-bar preview. Use `<Button as="a" href={url}>`.
+- ❌ `<Button as="a">` with no `href`, for a click handler you wanted to look like a link. An anchor without one is neither focusable nor activatable; the type requires `href` whenever `as="a"`, so this does not compile.

package/docs/components/ButtonGroup.md

@@ -0,0 +1,78 @@
+# `<ButtonGroup>` — joined Buttons + segmented control
+
+```tsx
+// Visual mode — joined Buttons, no shared state.
+<ButtonGroup aria-label="Edit actions">
+  <Button>Cut</Button>
+  <Button>Copy</Button>
+  <Button>Paste</Button>
+</ButtonGroup>
+
+// Segmented mode — single-select toggle group.
+<ButtonGroup value={view} onValueChange={setView} aria-label="View mode">
+  <ButtonGroup.Item value="grid">Grid</ButtonGroup.Item>
+  <ButtonGroup.Item value="list">List</ButtonGroup.Item>
+  <ButtonGroup.Item value="calendar">Calendar</ButtonGroup.Item>
+</ButtonGroup>
+
+// Size propagation: group-level size flows to children, per-child override wins
+<ButtonGroup size="sm">
+  <Button>Cut</Button>
+  <Button>Copy</Button>
+  <Button size="md">Paste</Button>
+</ButtonGroup>
+```
+
+<!-- props:start -->
+
+## Props
+
+### `ButtonGroupProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `size` | `'xs' \| 'sm' \| 'md' \| 'lg'` | no | Size propagated to children. Per-child `size` (Button or Item) wins when explicitly set. In visual mode this happens via cloneElement on Button children. In segmented mode, `<ButtonGroup.Item>` reads from context. |
+| `disabled` | `boolean` | no | Disabled state for the whole group. In segmented mode this is authoritative (all items become aria-disabled, clicks no-op). In visual mode this is a no-op — pass `disabled` per `<Button>` instead. |
+| `invalid` | `boolean` | no | Segmented mode: `aria-invalid` on the radiogroup. Visual mode: consumed and ignored. Field / SettingRow inject it — it used to leak onto the group div as a stray attribute. Default: `false`. |
+| `required` | `boolean` | no | Segmented mode: `aria-required` on the radiogroup. Visual mode: consumed and ignored. Field / SettingRow inject it. Default: `false`. |
+| `className` | `string` | no |  |
+| `style` | `CSSProperties` | no |  |
+| `value` | `string` | no | Visual mode marker. Never set; absence flips to visual. |
+| `onValueChange` | `(next: string) => void` | no | Fired when a different Item is selected. Consumers wanting literal-union narrowing can cast the setter: `onValueChange={(v) => setView(v as 'grid' \| 'list')}`. |
+| `aria-label` | `string` | no | Accessible name for the group landmark. Optional but recommended. |
+| …native | | | plus native HTML attributes |
+
+### `ButtonGroupItemProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `value` | `string` | yes | Value emitted to `onValueChange` when this item is selected. |
+| `disabled` | `boolean` | no | Per-item disabled. Group-level disabled is OR-merged. |
+| `className` | `string` | no | className merges onto the rendered <button>. |
+| `aria-label` | `string` | no | Accessible name for the radio, when the visible text is an abbreviation (`S` / `M` / `L` → "Small tiles"). Start it with the visible text where you can ("S, small tiles") so voice-control users can say what they see (WCAG 2.5.3). Omit it when `children` already reads as a full name. |
+| `aria-describedby` | `string` | no | id(s) of element(s) describing the option — forwarded to the radio. |
+| `children` | `ReactNode` | yes |  |
+
+<!-- props:end -->
+
+- **Mode detection** is by props: with `value` + `onValueChange` you get segmented; without, you get visual joining. Visual mode joins `<Button>` children with shared borders and outer-only rounded corners (toolbar action groups); segmented mode is a single-select radiogroup (view-mode toggles, timeframe filters). A discriminated union enforces "`value` AND `onValueChange` together OR neither".
+- **`<ButtonGroup.Item>`** (segmented only) renders `<button role="radio">` with roving tabindex and `aria-checked` driven by the parent's `value`. Using it in visual mode (no `value` on the parent) throws at render time: it has no group to belong to, by design.
+- **Abbreviated options** (`S` / `M` / `L`) take `aria-label` on the Item, forwarded to the radio: `<ButtonGroup.Item value="s" aria-label="S, small tiles">S</ButtonGroup.Item>`. Start the name with the visible text (WCAG 2.5.3); don't hide the letter and add visually-hidden text instead. `aria-describedby` is forwarded too.
+- **Children differ by mode.** Visual: `<Button>` children. Segmented: `<ButtonGroup.Item>` children. Mixing the two is undefined behavior.
+- **Size propagation** — `size` on the group propagates to children. Per-child override wins.
+- **Segmented height = Button height** — the segmented TRACK (not each item) is the `--size-*` height, so a `size="md"` segmented control lines up with a `size="md"` Button. Items render at that height minus the track padding on both sides.
+- **Keyboard nav (segmented only)** — Arrow keys move selection + focus; Home / End jump to ends; Tab moves IN/OUT of the group on the currently-selected item. Disabled items are skipped.
+- **ARIA** — visual mode is `role="group"`; segmented mode is `role="radiogroup"` (requires `aria-label`).
+
+**Anti-patterns:**
+
+- ❌ Mixing visual `<Button>` children with `<ButtonGroup.Item>` in the same ButtonGroup — undefined behavior.
+- ❌ Using ButtonGroup as a routing tab strip. That's what `<Tabs>` is for.
+- ❌ Passing only `value` (no `onValueChange`) or only `onValueChange` (no `value`) — a type error, and broken at runtime too.
+- ❌ Wrapping a `<ButtonGroup.Item>` in a user component. The parent focuses items on Arrow nav, which depends on them being direct children.
+- ❌ Using it for non-button content groupings. Use `<Cluster>` or `<Stack>`.
+- ❌ Multi-select via clever workarounds. Compose Checkboxes for that.
+
+**See also:** `<Tabs>` for routing-style content switching, `<Radio>` for vertical radio lists.