@eocrm/design-system 0.0.0-stage → 0.6.17

package/docs/components/Accordion.md

@@ -0,0 +1,114 @@
+# `<Accordion>` — vertically-stacked collapsible panels
+
+Compound component for FAQ-style content, settings sections, and any case where you have a list of headings with optional drill-down detail. Two modes: `single` (one open at a time) or `multiple` (any combination).
+
+```tsx
+import { Accordion } from '@eocrm/design-system';
+
+// Single-open with collapsible (FAQ-style)
+<Accordion type="single" collapsible defaultValue="faq-2">
+  <Accordion.Item value="faq-1">
+    <Accordion.Trigger>How do I reset my password?</Accordion.Trigger>
+    <Accordion.Content>Visit Settings → Security → Reset.</Accordion.Content>
+  </Accordion.Item>
+  <Accordion.Item value="faq-2">
+    <Accordion.Trigger>How do I export my data?</Accordion.Trigger>
+    <Accordion.Content>Use the gear icon → Export → CSV.</Accordion.Content>
+  </Accordion.Item>
+</Accordion>
+
+// Multiple — independent sections
+<Accordion type="multiple" defaultValue={['account', 'notifications']}>
+  <Accordion.Item value="account">...</Accordion.Item>
+  <Accordion.Item value="notifications">...</Accordion.Item>
+</Accordion>
+
+// Disabled item
+<Accordion.Item value="advanced" disabled>...</Accordion.Item>
+
+// Controlled
+<Accordion type="single" value={open} onValueChange={setOpen}>...</Accordion>
+
+// Borderless + large, e.g. hero FAQ sections
+<Accordion type="single" collapsible variant="borderless" size="lg">...</Accordion>
+```
+
+<!-- props:start -->
+
+## Props
+
+### `AccordionProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `variant` | `'bordered' \| 'borderless'` | no | Visual variant. Defaults to `'bordered'`. |
+| `size` | `'sm' \| 'md' \| 'lg'` | no | Trigger size (font + padding). Defaults to `'md'`. |
+| `gap` | `'sm' \| 'md' \| 'lg'` | no | Gap between items → separated "card" look (each item gets its own border + radius; the outer container chrome is dropped). Omit for the joined default. |
+| `indicatorSide` | `'left' \| 'right'` | no | Which side the chevron indicator sits on. Defaults to `'right'`. |
+| `actionsWhenClosed` | `'show' \| 'hide'` | no | Whether `Accordion.Trigger` `actions` stay visible when the item is collapsed. Defaults to `'show'`; `'hide'` fades them out (and drops them from focus order) while closed. |
+| `children` | `ReactNode` | yes |  |
+| `type` | `"single" \| "multiple"` | yes |  |
+| `value` | `string \| string[]` | no | Controlled open item value. `''` = nothing open (only meaningful when `collapsible`). |
+| `defaultValue` | `string \| string[]` | no | Initial open item for uncontrolled use. |
+| `onValueChange` | `((next: string) => void) \| ((next: string[]) => void)` | no | Fires when the open item changes. |
+| `collapsible` | `boolean` | no | When true, clicking the currently-open item closes it. Default: `false` (matches Radix; prevents accidentally closing the only available content). |
+| …native | | | plus native HTML attributes |
+
+### `AccordionContentProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `children` | `ReactNode` | yes |  |
+| …native | | | plus native `<div>` attributes |
+
+### `AccordionItemProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `value` | `string` | yes | Unique value used to identify the item in the root's `value`/`onValueChange`. |
+| `disabled` | `boolean` | no | When true, the trigger is non-interactive and keyboard nav skips this item. |
+| `headerLevel` | `'h2' \| 'h3' \| 'h4' \| 'h5' \| 'h6'` | no | Heading level wrapping the trigger. WAI-ARIA APG requires triggers to live inside a heading element. Defaults to `'h3'`. |
+| `children` | `ReactNode` | yes |  |
+| …native | | | plus native `<div>` attributes |
+
+### `AccordionTriggerProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `icon` | `ReactNode` | no | Override the default trigger indicator icon (rotates 180° when open). Pass `null` to suppress the icon entirely. Default: `<ChevronDown />`. |
+| `actions` | `ReactNode` | no | Controls rendered at the **right of the header**, OUTSIDE the toggle button — so their buttons/menus are clickable without toggling the section, and the heading's accessible name stays just the title. Keep it to a few small controls (`<Button iconOnly>`, a `<DropdownMenu>` trigger, a `<Switch>`). |
+| `children` | `ReactNode` | yes |  |
+| …native | | | plus native `<button>` attributes |
+
+<!-- props:end -->
+
+- **`type="single"`** + `collapsible={true}` — one item open at a time, click to close.
+- **`type="multiple"`** — any combination.
+- **`variant`** — `"bordered"` (default; outer border + radius + item dividers) or `"borderless"` (no chrome; for nesting inside Cards or as a quiet section divider).
+- **`size`** — `"sm"` / `"md"` (default) / `"lg"` controls trigger font-size + padding (and content padding).
+- **`gap`** — `"sm"` / `"md"` / `"lg"` separates items into **collapsible cards** (each gets its own border + radius; the joined container chrome is dropped). Omit for the default joined look.
+- **`indicatorSide`** — `"right"` (default) or `"left"` to put the chevron before the title.
+- **`<Accordion.Trigger actions={…}>`** — a controls slot at the **right of the header**, rendered OUTSIDE the toggle button so its buttons/menus are clickable without toggling the section (and don't pollute the heading's accessible name). Keep it to a few small controls.
+- **`actionsWhenClosed`** — `"show"` (default) keeps `actions` always visible; `"hide"` fades them out (and drops them from focus order) while the item is collapsed — for dense sidebars of collapsed cards.
+- **Smooth animation** via CSS `grid-template-rows: 0fr → 1fr`. No JS measurement.
+- **Heading wrapping** — Trigger is wrapped in `<h3>` by default per WAI-ARIA APG. Override via `headerLevel` on Item.
+- **Keyboard**: ArrowDown/Up cycles between triggers, Home/End jumps to ends, Space/Enter toggles. Disabled items are skipped.
+- **Anatomy**: Content is `role="region"` with `aria-labelledby` pointing at its trigger. The Trigger's default indicator is a `<ChevronDown>` that rotates 180° when open.
+
+#### When NOT to use
+
+- ❌ Mutually-exclusive view switchers → `<Tabs>` (tabs imply parallel content; accordions imply hierarchy).
+- ❌ A simple show/hide toggle for a single section → use a `<Button>` + conditional render.
+- ❌ Step-by-step wizard flows → a dedicated Stepper (not shipped).
+
+#### Anti-patterns
+
+- ❌ Nesting `<Accordion.Trigger>` inside a heading the consumer also renders manually. Trigger ALREADY wraps itself in a heading.
+- ❌ Setting `aria-expanded` manually on the Trigger via `{...props}`. The component owns the ARIA contract.
+- ❌ Using `headerLevel="h1"`. There should only be one `<h1>` per page; Accordion lives below it.
+
+- ❌ Putting bulky or primary content in the Trigger `actions` slot. It is for a few small header controls (an icon `<Button>`, a `<DropdownMenu>` trigger, a `<Switch>`); the section's real content belongs in `<Accordion.Content>`.

package/docs/components/AgentAvatar.md

@@ -0,0 +1,58 @@
+# `<AgentAvatar>` — AI agent tile with the acting member
+
+**TL;DR:** a neutral tile with the agent's mark, plus a badge of the member it acts for. Use it where the agent is the actor and stands alone, such as a Thread or activity node. In a row with a name, use `PersonDisplay.AgentAvatar` instead (see [PersonDisplay](PersonDisplay.md)).
+
+```tsx
+// Agent acting for a member: neutral tile + the member's avatar as a badge
+<AgentAvatar name="Scout" member={{ name: 'Sarah Chen', src: '/avatars/sarah.png' }} />
+
+// Agent alone (no `member`): no badge
+<AgentAvatar name="Scout" />
+
+// Erased member (`null` or an empty name): placeholder badge, "former member" label
+<AgentAvatar name="Scout" member={null} />
+
+// Custom mark; inherits currentColor in the tile
+<AgentAvatar name="Scout" mark={<ScoutLogo />} member={{ name: 'Sarah Chen' }} size="lg" />
+
+// Thread node beside a visible byline that already names both: decorative
+<Thread.Item node={<AgentAvatar name="Scout" member={{ name: 'Sarah Chen' }} size="sm" decorative />}>
+  <PersonDisplay size="inline">
+    <PersonDisplay.Name>Scout</PersonDisplay.Name>
+    <PersonDisplay.OnBehalfOf>Sarah Chen</PersonDisplay.OnBehalfOf>
+  </PersonDisplay>
+  …
+</Thread.Item>
+```
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `name` | `string` | yes | Agent label; drives the accessible name (an empty label reads as "?", like `Avatar`). Unused when `decorative`. |
+| `mark` | `ReactNode` | no | Agent mark, inherits `currentColor` (a neutral foreground), so pass a glyph drawn with `fill`/`stroke="currentColor"`; marks with hard-coded fills keep their colours (the app's responsibility). Defaults to a lucide `Bot`. |
+| `member` | `AgentAvatarMember \| null` | no | The member the agent acts for. Omit for an agent alone (no badge); `null` or an empty name for an erased member (placeholder badge). |
+| `size` | `'inline' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | no | Diameter, same scale as `Avatar`. The member badge is hidden at `inline`. |
+| `decorative` | `boolean` | no | Hide the avatar from assistive tech (`aria-hidden`, no role or label). Use when visible text next to it already names the agent and the member, e.g. a Thread node beside a "Scout for Sarah Chen" byline; otherwise both are announced. Without such text keep the default: a `role="img"` named "{agent}, on behalf of {member}". `PersonDisplay.AgentAvatar` always sets it. Defaults to `false`. |
+| …native | | | plus native `<span>` attributes |
+
+<!-- props:end -->
+
+- Same `size` scale as [`Avatar`](Avatar.md). At `inline` the member badge is hidden (too small to read); the label still names the member.
+- Accessible name: `role="img"` with `"{agent}, on behalf of {member}"` (localized), `"{agent}, on behalf of a former member"` when erased, or just the agent name when `member` is omitted. An empty `name` reads as `"?"`, as with `Avatar`.
+- `decorative`: set it when visible text next to the avatar already names the agent and the member (a Thread node beside a byline). It renders `aria-hidden` with no role or label, so nothing is announced twice. With no such text, keep the default `role="img"`. `PersonDisplay.AgentAvatar` always sets it.
+
+#### When NOT to use
+
+- For a human. A person is an [`Avatar`](Avatar.md) (or `PersonDisplay.Avatar`).
+- Next to an agent name in a row. Use `PersonDisplay.AgentAvatar` + `PersonDisplay.OnBehalfOf`, which localize "for {member}" and truncate it.
+
+#### Anti-patterns
+
+- ❌ Leaving the default `role="img"` beside a visible "Scout for Sarah Chen" byline. Screen readers announce the agent and member twice; pass `decorative`.
+- ❌ `decorative` with no visible text naming the agent. The avatar then says nothing at all.
+- ❌ Passing a multi-colour brand `mark` and expecting it to come out neutral. The tile only sets `color` (a neutral foreground); draw the glyph with `fill`/`stroke="currentColor"`. Hard-coded fills keep their colours, which is the app's responsibility.
+- ❌ Deriving the brand `mark` from a client-chosen name. Pick the mark from a trusted, server-known agent identity, or an agent can impersonate another product.

package/docs/components/Alert.md

@@ -0,0 +1,81 @@
+# `<Alert>` — persistent in-flow notification
+
+Tone-driven banner for messages that need to stay visible while the user reads the page (subscription warnings, save failures, "update available" notices). Complements `<Toast>` (transient).
+
+```tsx
+import { Alert } from '@eocrm/design-system';
+
+// Basic
+<Alert tone="info" title="Synced 5 minutes ago" />
+<Alert tone="warning">Your storage is at 85% capacity.</Alert>
+
+// With actions
+<Alert tone="warning" title="Update available" actions={<Button size="sm">Reload</Button>}>
+  A new version is ready. Reload to apply.
+</Alert>
+
+// Dismissible (controlled by consumer)
+const [show, setShow] = useState(true);
+{show && (
+  <Alert tone="success" onDismiss={() => setShow(false)}>
+    Changes saved.
+  </Alert>
+)}
+
+// Static callout that is part of the page, not a status change (no live region)
+<Alert tone="warning" live={false} title="Needs action">
+  The client asked for a revised quote by Friday.
+</Alert>
+
+// Custom icon / suppressed icon
+<Alert tone="info" icon={<Bell size={16} />} title="New mention" />
+<Alert tone="info" icon={null}>Quietly informative.</Alert>
+```
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `tone` | `'info' \| 'success' \| 'warning' \| 'error'` | no | Tone. Defaults to `'info'`. See `AlertTone` for full descriptions. |
+| `title` | `ReactNode` | no | Optional bold heading. Renders above the description. ReactNode so you can embed inline emphasis (`<>Update <strong>1.2.3</strong> available</>`). The native HTML `title` attribute (tooltip-on-hover) is collapsed by this prop. Use `aria-label` if you need that. |
+| `children` | `ReactNode` | no | Description body. Rendered below the title in muted color. |
+| `icon` | `ReactNode` | no | Override the tone's default icon. Pass any ReactNode (typically a lucide-react icon). Pass `null` to hide the icon entirely. Defaults: `info` → `Info`, `success` → `CheckCircle2`, `warning` → `AlertTriangle`, `error` → `XCircle`. |
+| `actions` | `ReactNode` | no | Optional action row rendered below the description. Typically a single Button or a Cluster of two ("Retry", "Dismiss"). The component doesn't manage the action row's layout — pass a pre-laid-out node. |
+| `live` | `boolean` | no | Whether the Alert is a live region. Defaults to `true`: `role="status"` (polite), or `role="alert"` (assertive) for `tone="error"` — right for a message that APPEARS in response to something (a save failed, an update arrived). Pass `false` for a callout that is simply part of the page when it opens — a "Needs action" note in each card of a list, a standing warning in a form. It renders `role="note"` with the same visuals and no live semantics, so screen readers read it in place instead of announcing it. N live Alerts mounting together can queue N announcements. The tone is shown by the icon's shape and the colour only; it is not exposed to assistive tech in either mode (the icon is decorative). With `live={false}`, `tone="error"` also loses the "alert" role that browse-mode readers speak. So put the urgency in `title` ("Needs action"). Decide it at mount: flipping `false` → `true` on a mounted Alert turns content that is already there into a live region, which announces nothing. |
+| `onDismiss` | `(() => void)` | no | Called when the user clicks the close (×) button. When set, the close button renders; when omitted, no close button. Alert is **controlled** — the component does NOT manage internal hidden state. Hide via conditional render in the consumer: (example below) |
+| …native | | | plus native HTML attributes |
+
+**`onDismiss`** example:
+
+<!-- prettier-ignore -->
+```tsx
+const [show, setShow] = useState(true);
+{show && <Alert tone="success" onDismiss={() => setShow(false)}>Saved</Alert>}
+```
+
+<!-- props:end -->
+
+- **Four tones** (`info` / `success` / `warning` / `error`). Default icon + accent stripe per tone.
+- **`role="alert"`** only for `error` (assertive, interrupts SR). Others use `role="status"` (polite). Both only while `live` (the default).
+- **`live={false}`** for a static callout that is part of the page when it opens (a "Needs action" note in each card of a list): renders `role="note"`, the same visuals, and no live region, so N of them don't queue N announcements. Keep the default for messages that appear in response to something. The tone (icon + colour) is never exposed to assistive tech, and `tone="error" live={false}` also loses the spoken "alert" role, so put the urgency in `title`. Decide `live` at mount: flipping it later announces nothing.
+- **Persistent** — no auto-dismiss. Use Toast for transient messages.
+- **Controlled dismiss** — `onDismiss` callback fires on × click; consumer hides via conditional render.
+- **`icon={null}`** suppresses the icon entirely; any ReactNode overrides the default.
+
+#### When NOT to use
+
+- ❌ Transient confirmations → `<Toast>` / `toast.success(...)`.
+- ❌ Empty-state placeholders ("No deals yet") → `<EmptyState>`.
+- ❌ Form-field validation messages → inline error text + `aria-describedby`.
+- ❌ Destructive confirmations needing yes/no → `<ConfirmationPopover>` or `<Modal>`.
+
+#### Anti-patterns
+
+- ❌ Auto-dismissing the Alert with a `setTimeout` — that's what Toast is for.
+- ❌ Using `tone="error"` for non-critical warnings. Reserve `error` for genuine failures; `role="alert"` interrupts screen readers.
+- ❌ Multiple stacked Alerts above a page — pick one (most urgent tone) or compose into the page layout with explicit hierarchy.
+- ❌ A live Alert (the default) for content that exists when the page opens, especially one per list item — each is a live region and some screen readers queue an announcement per item. Pass `live={false}`.
+- ❌ `live={false}` for a message that appears in response to an action (a failed save) — it is never announced. For a must-hear reactive message use `tone="error"` (`role="alert"` is announced on insertion) or a Toast. A polite live Alert that mounts together with its text is not reliably announced either.

package/docs/components/AppLayout.md

@@ -0,0 +1,70 @@
+# `<AppLayout>` — viewport-filling app shell
+
+```tsx
+<AppLayout topBar={<TopBar />} sidebar={<Rail>{nav}</Rail>}>
+  <Page>{content}</Page>
+</AppLayout>
+
+// No sidebar — top bar + content only
+<AppLayout topBar={<TopBar />}>
+  <Page>{content}</Page>
+</AppLayout>
+
+// Tall pages: pin the sidebar so a Rail's footer/CollapseToggle stays at the viewport bottom
+<AppLayout sidebar={<Rail>{nav}<Rail.Footer>{footer}</Rail.Footer></Rail>} sidebarPinned>
+  <Page>{content}</Page>
+</AppLayout>
+
+// System banner above everything + a module-scoped one under the top bar
+<AppLayout
+  banner={<Banner tone="info" title="Maintenance Saturday 22:00.">CRM will be read-only.</Banner>}
+  contextBanner={suspended && <Banner tone="danger" title="Email sending suspended." />}
+  topBar={<TopBar />}
+  sidebar={<Rail>{nav}</Rail>}
+>
+  <Page>{content}</Page>
+</AppLayout>
+```
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `banner` | `ReactNode` | no | System-wide banner slot — full WINDOW width, above the sidebar + content row. For messages that apply wherever the user is: maintenance, billing overdue, impersonation. Pass a `<Banner>` (or several, most severe first). Not sticky: it scrolls away with the page while the `topBar` stays pinned. Omit (or pass `null` / `false`) for no wrapper. With `sidebarPinned`, the pinned sidebar starts below this banner, so at scroll position 0 its bottom (a `Rail.Footer`) sits up to one banner height below the fold until the page scrolls past the banner. This is accepted — banners are temporary. |
+| `contextBanner` | `ReactNode` | no | Context banner slot — inside the content column, between the `topBar` and the padded content region, full-bleed within the column. For messages scoped to a module or route ("Email sending suspended" on the Email pages); the app decides which routes render it. Pass a `<Banner>`. Not sticky. Page-level messages belong in the content as `<Alert>` instead. |
+| `topBar` | `ReactNode` | no | Top bar slot — sits above the main content, spanning the content column to the right of the sidebar (not the full window width). Omit for no top bar. |
+| `sidebar` | `ReactNode` | no | Sidebar slot — runs the full height down the left, alongside both the top bar and the content. Sets its own width (intrinsic). Omit for no sidebar. |
+| `sidebarPinned` | `boolean` | no | Pin the sidebar to the viewport: `position: sticky; top: 0; height: 100dvh` with internal overflow scrolling. On pages taller than the viewport the sidebar (and a `Rail` inside it — including its `Rail.Footer` / CollapseToggle) spans exactly the SCREEN, keeping the footer glued to the viewport bottom instead of the page bottom. Default `false` (sidebar stretches to the full row/page height — the original behavior). Prefer this over wrapping the sidebar slot in `Sticky` — the rail pins its footer by filling its own `height: 100%` box, which needs a DEFINITE height to resolve against. `Sticky` sets `align-self: start`, which drops the row stretch that made it definite, so the footer stops pinning. `100dvh` is always relative to the real browser viewport, never to a nested scroll container — so this only pins correctly when AppLayout is the actual outermost, page-scroll shell (its documented top-level use). Nest it inside another scrollable region and the sidebar will size to the whole window, not that region, and overflow it. |
+| `sidebarOverlayBelow` | `'sm' \| 'md' \| 'lg'` | no | Move the sidebar out of the flow and into a left-anchored `<Drawer>` while the **viewport** is at or below a width threshold: `'sm'` 480px / `'md'` 640px / `'lg'` 768px. Omit for no responsive behavior (the default) — the sidebar always renders in the flow. Below the threshold the content column claims the full viewport width, and the sidebar is reachable only by opening the drawer. Render your own trigger (a hamburger in the `topBar`) and drive it with `sidebarOpen` + `onSidebarOpenChange` — AppLayout deliberately renders no trigger of its own, since where it belongs in the bar is the consumer's call, which means both props are effectively required together (see `sidebarOpen`'s doc). Use the exported `useBelowBreakpoint` hook to show that trigger only while the overlay mode is active. `sidebarPinned` is ignored below the threshold: the drawer owns the sidebar's box there, and a `sticky; height: 100dvh` wrapper inside it would size the rail to the window instead of the drawer. Measures the viewport (`matchMedia`), not a container — the sidebar's presence in the row is exactly what the threshold changes, so a container query would be circular. Same scale and same basis as `<Rail collapseBelow>`. The `sidebar` node moves between the in-flow slot and the `Drawer`, remounting it, so a `Rail`'s internal state (expanded `Rail.Group`s, scroll position) resets each time, by design. A `<Rail>` in the drawer scrolls its own body while its footer stays visible; a custom non-`Rail` sidebar needs its own height-filling scroll container, especially on short viewports (phone landscape, ~380px). |
+| `sidebarOpen` | `boolean` | no | Open state of the overlay sidebar. Technically optional, but effectively required together with `onSidebarOpenChange` whenever `sidebarOverlayBelow` is set — AppLayout renders no trigger of its own (see `sidebarOverlayBelow`), so with both omitted nothing can ever open the drawer; Esc/backdrop close it, but there's no way in. Has no effect unless `sidebarOverlayBelow` is set and the viewport is below it. |
+| `onSidebarOpenChange` | `((open: boolean) => void)` | no | Fires whenever the overlay sidebar opens or closes — close button, Esc, backdrop click, swipe, or programmatic. Pair with `sidebarOpen` — see its doc. |
+| `mainLandmark` | `boolean` | no | Render the content region as a `<main>` landmark instead of a plain `<div>`. Pass it on the outermost app shell so the page gets its single `main` landmark without a wrapper element. Leave it off (default) for nested use — demos, documentation previews — so the page never gets two `main`s. |
+| `children` | `ReactNode` | yes | Main content slot — fills the remaining space below the top bar. |
+| …native | | | plus native `<div>` attributes |
+
+<!-- props:end -->
+
+- Top-level shell layout, mounted **once** at the app root. Matches the CRM shell topology: a **full-height `sidebar`** down the left, an optional `topBar` **over the content column** (not full window width), and the main `children` below it. Root is `min-height: 100vh`.
+- Layout-owning primitive (the `<Page>` / `<Screen>` / `<Rail>` exception to "no layout properties"). Its only own-styling is the main region's gutter + subtle canvas (both token-driven, below); the slots bring their own surfaces. Don't nest inside `<Page>` / `<Screen>`, and don't nest inside another `AppLayout` **in product code** — the only sanctioned AppLayout-in-AppLayout nesting is a demo/documentation preview (see the landmark note below); for a chromeless page use `<Screen>`, for in-page layout use `<Stack>` / `<Cluster>`.
+- **Content padding (default):** the main region ships the canonical shell gutter (`--app-layout-content-padding`, default `var(--space-6)`, stepping down to `var(--space-4)` at ≤640px viewport width) — routed content is padded with **no prop and no raw CSS**. For a full-bleed main region, override the token (`--app-layout-content-padding: 0`) in your scope; there is no prop. Scope the override to a class or `body`, not another `:root` rule — the narrow-viewport step-down is itself a `:root` rule at the same specificity, so two `:root` rules fight on load order below 640px. _Migration:_ if you previously shimmed this gutter with your own `padding: var(--space-6)` wrapper, remove that shim now or the padding doubles.
+- **Content canvas (default):** the main region paints a subtle canvas (`--app-layout-content-background`, default `var(--color-bg-subtle)`) so white `<Card>`s lift off it — matches every mockup, **no prop, no raw CSS**. For a flat content area, override the token (`--app-layout-content-background: transparent`); there is no prop. _Migration:_ if you shimmed your own `background: var(--color-bg-subtle)` on the content region, remove it.
+- **Page-scroll shell:** `min-height: 100vh` means tall content scrolls the whole window, but the chrome doesn't scroll away with it — `topBar` is always pinned (`position: sticky`), and `sidebar` pins too when `sidebarPinned` is set. Only the main content region scrolls. For fixed chrome + independently-scrolling content, override the root to a fixed `height: 100vh` / `100dvh` via `className`.
+- **`sidebarPinned`** (default `false`): on pages taller than the viewport, pins the sidebar wrapper (`position: sticky; top: 0; height: 100dvh; overflow-y: auto`) so a `Rail`'s footer/`CollapseToggle` stays glued to the viewport bottom instead of scrolling away with the page. Don't reach for wrapping the sidebar slot in `<Sticky>` instead — the Rail pins its footer by filling its own `height: 100%` box, and `Sticky`'s `align-self: start` drops the row stretch that made that height definite, so the footer-pinning doesn't work. `100dvh` is always relative to the real browser viewport, not a nested scroll container — only use it when AppLayout is the outermost, page-scroll shell (its documented top-level use); nested inside another scrollable region, the sidebar sizes to the whole window and overflows it.
+- **`sidebarOverlayBelow`** (default: none): below a **viewport** threshold (`'sm'` 480 / `'md'` 640 / `'lg'` 768) the sidebar leaves the flow and renders in a left `<Drawer>`, so the content column gets the full viewport width — the fix for a 240px rail eating a phone screen. **AppLayout renders no trigger** — put a hamburger in your `topBar` and gate it with the `useBelowBreakpoint` hook (see below) so it only shows while the overlay is active. Because there's no built-in trigger, `sidebarOpen` + `onSidebarOpenChange` are technically optional props but **effectively required together**: with both omitted nothing can ever open the drawer. Once open, the drawer has a visible close button and a header that can be swiped left to dismiss, in addition to Esc/backdrop dismissal. `sidebarPinned` is ignored below the threshold (the drawer owns the sidebar's box there).
+- The `children` slot renders inside a plain `<div>` by default, not a `<main>` — `AppLayout` can be nested in a demo or documentation preview (never in product code, see above), so it must not unilaterally claim the page's `main` landmark. The outermost app shell passes **`mainLandmark`** so the content region itself becomes the page's single `<main>` (no wrapper element, same styling); nested previews keep the default. Never set it on more than one `AppLayout` per page.
+
+- A `<Sticky>` inside the main region must clear the pinned `topBar`: use `<Sticky top="topbar">`, which resolves to the standard top-bar height plus the normal content gap. Override `--sticky-top-topbar` when your chrome uses a custom height or clearance.
+
+#### When NOT to use
+
+- ❌ In-page content layout: use `<Stack>` / `<Cluster>` / `<Grid>`.
+- ❌ A chromeless full-bleed page (sign-in / 404 / error): use `<Screen>`.
+
+#### Anti-patterns
+
+- ❌ Setting `sidebarOverlayBelow` without rendering a trigger: the sidebar becomes unreachable below the threshold.
+- ❌ Duplicating the threshold as a raw media query in consumer CSS to hide the trigger. Use `useBelowBreakpoint(bp)` with the same token so the two can't drift.
+- ❌ `<Rail collapseBelow>` and `sidebarOverlayBelow` at the same breakpoint: the rail would render icon-only inside a drawer that already has room for labels. Pick one behavior per width.

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.