@eocrm/design-system 0.0.0-stage → 0.6.18

package/README.md

@@ -1,3 +1,267 @@
-# Temporary Holding Version
+# @eocrm/design-system
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+React 19 design system for the EOCRM. Source-distributed (consumers' bundlers process `.tsx` and `.module.scss` directly — no compile step in this package).
+
+Its web tokens are generated and versioned by `@eocrm/design-tokens`. Existing
+consumer imports remain unchanged: the design-system Sass entry points forward
+to the token package.
+
+Component contracts live in **[`docs/components/<Name>.md`](./docs/components)** (props table, anti-patterns). AI agents consuming this package should read **[AI-PRIMER.md](./AI-PRIMER.md)** first.
+
+**Live playground** (every component, demoed against `main`): <https://eocrm.github.io/design-system/components>
+
+---
+
+## Install
+
+### 1. Registry
+
+`@eocrm/design-system` and `@eocrm/design-tokens` are public on npmjs, so no
+`.npmrc` or token is needed. Every release is also published, with identical
+tarballs, to GitHub Packages (`@eocrm:registry=https://npm.pkg.github.com` plus a
+`read:packages` token) for consumers that have not switched yet. Point the whole
+`@eocrm` scope at one registry — the design system pins `@eocrm/design-tokens` to
+its exact version.
+
+### 2. Install
+
+```bash
+npm install @eocrm/design-system
+```
+
+### 3. Use
+
+```ts
+// Once, at the app's root (e.g. main.tsx):
+import '@eocrm/design-system/styles/global.scss';
+
+// Anywhere:
+import {
+  Avatar,
+  Badge,
+  Button,
+  Card,
+  Cluster,
+  DropdownMenu,
+  Input,
+  Stack,
+  Tabs,
+} from '@eocrm/design-system';
+```
+
+---
+
+## What `global.scss` does
+
+Importing `@eocrm/design-system/styles/global.scss` once at your app root applies three things:
+
+1. **Tokens** — defines every `--color-*`, `--space-*`, `--radius-*`, `--font-*`, `--shadow-*` etc. on `:root`. Required.
+2. **Modern reset** — including `* { margin: 0 }`. **All default browser margins on every element are zeroed.** Headings, paragraphs, lists have no intrinsic vertical rhythm; space them via `Stack`/`Cluster` or with the parent's own margin in CSS. The document background uses `--document-background` (default `var(--color-bg-subtle)`) so route transitions between full-screen surfaces do not flash a different base color; override that token after the global import for a different application canvas. The reset also applies `scrollbar-width: thin` + a token-colored `scrollbar-color` to every element, so **every** scroll container — library components and your own — gets a thin themed scrollbar instead of the OS default. (One deliberate exception: a collapsed `<Rail>` hides its bar entirely, since a gutter is about a quarter of the 56px rail's inner width.) It's declared at specificity 0-0-0; opt a scroller out with its own `scrollbar-width: auto` / `scrollbar-color: auto`. Note that Chromium ignores `::-webkit-scrollbar` rules on any scroller where these standard properties are set — if you already style scrollbars that way, they'll stop applying.
+3. **Base typography** — `body` font + size, `h1`–`h4` sizes, link color. Global rules, not scoped.
+
+If you need only the tokens (you're providing your own reset), import `@eocrm/design-system/styles/tokens.scss` directly. Other available subpath imports: `./styles/reset.scss`, `./styles/typography.scss`, `./styles/mixins.scss`.
+
+---
+
+## Accent
+
+The accent family defaults to blue. To switch the whole app to **Teal pine**, set `data-accent="tealpine"` on `<html>` (omit the attribute for blue):
+
+```html
+<html data-accent="tealpine" data-theme="dark"></html>
+```
+
+It swaps `--color-accent`, `-hover`, `-pressed`, `-fg`, `-bg-subtle`, `-subtle-bg` and `--ring-accent`, plus the default `Link` colour (`--color-link-fg` / `-hover`), in light, forced dark (`data-theme="dark"`) and OS dark. It ships in the existing `tokens.scss` / `dark.scss`, so there is no new import. `AppProvider`'s `tokens` / `darkTokens` overrides win over `data-accent` in every theme (see [docs/setup.md](docs/setup.md)). Info colours stay blue under any accent; DropdownMenu checked items, the OptionsPicker selected row and StagePath done states follow the accent. In light theme, default `Link`s use a slightly brighter teal than the accent (`#007676`, AA on every grey surface) at medium weight (not inside headings, `<strong>` or `<th>`), because the accent alone sits too close to the navy body text to read as a link.
+
+Compose: `EocrmTealPineLightTokens` / `EocrmTealPineDarkTokens` sit beside `EocrmLightTokens` / `EocrmDarkTokens`; only accent colours differ. The link colour tokens are web-only (Compose has no `Link`), so Compose links keep the accent colour.
+
+**Known issue:** in light theme, Teal pine and `--color-success` are close in hue (both green-teal). Review success/accent pairings visually before switching the CRM.
+
+---
+
+## Bundler notes
+
+The package ships **source files** (`.tsx`, `.module.scss`). Your bundler compiles them.
+
+- **Vite**: works out of the box.
+- **Next.js**: add `transpilePackages: ['@eocrm/design-system']` to `next.config.js`.
+- **Webpack 5**: ensure your TS/SCSS loaders don't `exclude: /node_modules/` for this package.
+- **Create React App (ejected)**: same as Webpack.
+
+If TypeScript can't resolve types, set `moduleResolution: "bundler"` (or `"node16"`) in your `tsconfig.json`.
+
+**Tests.** Vitest works out of the box. Jest (CommonJS) must transform this package (TSX source) and its ESM-only dependencies (`d3-*`, `internmap`, used by `Chart`), and map `.module.scss` imports:
+
+```js
+// jest.config.js — the pattern covers npm/yarn and pnpm (node_modules/.pnpm/<name>@<version>/…) layouts
+transformIgnorePatterns: [
+  '/node_modules/(?!(\\.pnpm/)?(@eocrm[/+]design-system|d3-[^/@]+|internmap)[/@])',
+],
+moduleNameMapper: { '\\.module\\.scss$': 'identity-obj-proxy' },
+```
+
+- Install `identity-obj-proxy` as a dev dependency.
+- The transformer must compile TSX and convert ESM to CommonJS inside `node_modules`:
+  - `babel-jest`: a root `babel.config.js` (a `.babelrc` does not apply to `node_modules`) with `@babel/preset-env` (`targets: { node: 'current' }`, which converts `import`/`export`), `@babel/preset-react` (`runtime: 'automatic'`) and `@babel/preset-typescript`.
+  - `ts-jest`: `preset: 'ts-jest/presets/js-with-ts'` (so `.js` files are transformed too), with `allowJs: true`, `jsx: 'react-jsx'` and `module: 'commonjs'` in the tsconfig it uses, and `isolatedModules: true` (transpile only). The package does not ship a `*.module.scss` type declaration, so a type-checking ts-jest reports TS2307 on its style imports unless you declare `*.module.scss` yourself.
+
+---
+
+## Components
+
+Grouped for navigation. Per-component contracts are in `docs/components/<Name>.md`; [AI-PRIMER.md](./AI-PRIMER.md) indexes them with the tokens table.
+
+**Typography**
+
+- `Title` — semantic heading
+- `Text` — body / inline text
+- `Code` — inline `<code>` chip
+- `Kbd` — keyboard key hint
+
+**Actions**
+
+- `Button` — action triggers
+- `ButtonGroup` — joined Buttons + segmented control
+- `SocialButton` — provider sign-in button
+- `Link` — polymorphic styled anchor
+- `DropdownMenu` — action menu from a trigger
+
+**Form controls**
+
+- `Input` — single-line text
+- `Textarea` — multi-line text
+- `OtpInput` — one-time-code entry, single-character boxes
+- `PasswordInput` — password field with eye toggle + optional warnings
+- `PasswordStrengthMeter` — 4-segment strength visualization
+- `Select` — value picker (single, multi, searchable, async, creatable)
+- `OptionsPicker` — filter picker (multi/single, grouped, searchable)
+- `Checkbox` — checkbox with native input + custom paint
+- `Radio` / `RadioGroup` — single radio + fieldset wrapper
+- `Switch` — binary toggle
+- `Slider` — controlled slider (single + range, horizontal + vertical)
+- `ColorPicker` — controlled HEX color picker (popover + inline)
+- `IconPicker` — controlled icon picker with a popover radio grid
+- `FileUpload` — controlled file picker with dropzone
+- `ImageCrop` — controlled image cropper
+
+**Form layout**
+
+- `Field` — labeled-control unit
+- `FormSection` — titled group of fields
+- `FormRow` — fields side by side
+- `SettingRow` / `SettingRow.List` — settings-screen row with a shared label column, adornments and a footer slot
+
+**Date & time**
+
+- `Calendar` — month / week / day / agenda views
+- `DatePicker` / `InlineDatePicker` — single-date input + popover, or in flow
+- `DateRangePicker` / `InlineDateRangePicker` — date-range input + popover, or in flow
+- `TimeField` — standalone time-of-day input
+
+**Layout & structure**
+
+- `Stack` — vertical layout
+- `Cluster` — horizontal layout that wraps
+- `Grid` — 2D layout primitive
+- `Masonry` — height-balanced masonry layout
+- `Constrain` — width / height / flex constraint
+- `Divider` — separator primitive
+- `Page` — page-root layout primitive
+- `Screen` — full-bleed / centered screen layout
+- `AppLayout` — viewport-filling app shell
+- `PageHeader` — top-of-page heading area
+
+**Navigation & app chrome**
+
+- `Rail` — collapsible left-side navigation
+- `TopBar` — sticky application top bar
+- `Tabs` — horizontal tab strip
+- `Breadcrumb` — navigation trail
+- `Pagination` — numbered nav with windowing
+- `CursorPagination` — prev / next for streams without a total
+
+**Overlays**
+
+- `Modal` — focus-locked dialog
+- `Drawer` — edge-anchored slide-in panel
+- `Popover` — non-modal floating panel for interactive content
+- `ConfirmationPopover` — opinionated "Are you sure?" preset
+- `Tooltip` — small floating label on hover / keyboard focus
+
+**Feedback & status**
+
+- `Alert` — persistent in-flow notification
+- `Toast` (`ToastViewport` + `toast`) — transient notifications
+- `Progress` — linear progress bar
+- `CircularProgress` — circular progress / spinner
+- `Skeleton` — loading placeholder
+- `EmptyState` — "nothing here" container
+- `ErrorState` — page-level status / result screen
+- `Badge` — status / category pill
+- `FilterChip` — dismissible "active filter" pill
+
+**Data display**
+
+- `Card` — bordered container
+- `LinkCard` — clickable, full-surface Card
+- `DefinitionList` — semantic key/value pairs (`dl` / `dt` / `dd`)
+- `Table` — tabular data primitive
+- `DataTable` — server-driven data table with column features
+- `Accordion` — vertically-stacked collapsible panels
+- `Kanban` — multi-column board (drag-to-reorder + cross-column drag)
+- `Sortable` — drag-to-reorder list (single column)
+- `Image` — image with loading + error states
+
+**Identity & media**
+
+- `Avatar` / `AvatarGroup` — profile circle / Slack-style stacked row
+- `PersonDisplay` — Avatar + name (+ optional description lines)
+- `Logo` — brand logo lockup
+- `BrandIcon` — third-party brand marks
+- `IconTile` — palette-colored icon frame
+
+> The library also ships an `AppProvider` (theme + i18n + locale wiring), `LocaleProvider` / `I18nProvider`, the `useTranslation` / `useLocale` hooks, the `palette` helpers, and Calendar primitive hooks (`useMonth`, `useWeek`, `useDay`, `useAgenda`). See [AI-PRIMER.md](./AI-PRIMER.md) for those.
+
+---
+
+## Releasing a new version
+
+Releases are **automatic**. Merging to `main` triggers the `Release` workflow (`.github/workflows/release.yml`), which:
+
+1. Runs the quality gate (typecheck, test, lint, build, tarball-contents check).
+2. If the library actually changed, computes the next version from the latest `v*` git tag (patch bump by default) and refuses if that tag already exists.
+3. Synchronizes `@eocrm/design-tokens`, `@eocrm/design-system`, and the generated token contract to one version.
+4. Publishes the token npm package, then the design-system npm package, then `com.eocrm.design:design-tokens-compose`.
+5. Verifies all three registry versions before creating and pushing the `v<version>` git tag.
+6. Re-deploys the playground (see below).
+
+There is no manual "Run workflow" button — merging to `main` is the only way to release. Playground-only changes skip the publish step (no version bump for a demo tweak) but still redeploy the playground.
+
+**Forcing a minor/major bump**: edit `BUMP` (`patch` → `minor` / `major`) in `release.yml` on a branch and merge. There is no other override by design.
+
+**One-time repo setup**: Settings → Actions → General → Workflow permissions → "Read and write permissions".
+
+The package name `@eocrm/design-system` must match an organization (or user) you have publish access to on GitHub. If your org isn't `eocrm`, rename the package in `package.json` and the `scope:` in the workflow.
+
+---
+
+## Playground deployment
+
+The playground (live component gallery) deploys to GitHub Pages automatically as the final step of the `Release` workflow, so the live site at <https://eocrm.github.io/design-system/> always reflects `main`. It redeploys whenever the quality gate passes — even on playground-only changes, and even if a publish hiccups.
+
+**This repo and its Pages site are public.** The playground bakes the library's source into its bundle via `?raw` imports, so the source is world-readable — that's intentional for a source-distributed library.
+
+**One-time setup**: Settings → Pages → Source = "GitHub Actions" (not "Deploy from a branch").
+
+---
+
+## Where docs live (so you don't have to grep)
+
+- **README.md** (this file) — install, setup, bundler notes, publishing/deploy ops.
+- **[AI-PRIMER.md](./AI-PRIMER.md)** — concise primer for AI coding agents. Token table and component index.
+- **`docs/components/<Name>.md`** — per-component contract: props table, examples, anti-patterns. Also `docs/setup.md`, `docs/theming.md`, `docs/transient-state.md`.
+- **[CLAUDE.md](./CLAUDE.md)** — rules for someone **modifying this library** (not for consumers).
+
+## License
+
+[Apache License 2.0](./LICENSE).

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.