@eocrm/design-system 0.0.0-stage → 0.6.17

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.

package/docs/components/Calendar.md

@@ -0,0 +1,158 @@
+# `<Calendar>` — month / week / day / agenda views
+
+```tsx
+// Uncontrolled
+<Calendar events={events} defaultView="week" />;
+
+// Controlled cursor + view
+const [cursor, setCursor] = useState(new Date());
+const [view, setView] = useState<CalendarView>('month');
+<Calendar
+  value={cursor}
+  onChange={setCursor}
+  view={view}
+  onViewChange={setView}
+  events={events}
+  onEventClick={(e) => openDetail(e)}
+/>;
+```
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `events` | `readonly CalendarEvent[]` | no | Events to display. |
+| `view` | `'month' \| 'week' \| 'day' \| 'agenda'` | no | Active view (controlled). Pair with `onViewChange`. |
+| `defaultView` | `'month' \| 'week' \| 'day' \| 'agenda'` | no | Initial view (uncontrolled). Defaults to `'month'`. |
+| `onViewChange` | `((view: CalendarView) => void)` | no | Fires when the user clicks the view switcher. |
+| `value` | `Date` | no | Navigation cursor (controlled). |
+| `defaultValue` | `Date` | no | Initial cursor (uncontrolled). Defaults to `new Date()`. |
+| `onChange` | `((date: Date) => void)` | no | Fires on prev/next/today/keyboard navigation. |
+| `onDayClick` | `((date: Date) => void)` | no | Fires when the user clicks a day cell's empty space. - Month view: empty space in a day cell, the "+N more" overflow chip, or keyboard activation (Enter/Space) on a focused cell. - Week/Day view: empty hour-grid space inside that day's column — **mouse click only**. There is no keyboard equivalent in v3; consumers needing keyboard activation in week/day should surface their detail UI through the focusable event chips (which fire `onEventClick`). |
+| `onEventClick` | `((event: CalendarEvent) => void)` | no | Fires when the user clicks an event chip. |
+| `locale` | `string` | no | Override locale. Defaults to `useLocale()`. |
+| `weekStartsOn` | `0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6` | no | Override locale-derived first day of week. |
+| `maxLanesPerWeek` | `number` | no | Lane cap per week (month view). Default 3. Events beyond it collapse into a "+N more" chip; clicking it fires `onDayClick(date)`. |
+| `hourRange` | `[number, number]` | no | Hour range shown in week/day views (inclusive start, exclusive end). Defaults to `[7, 19]` (7am–7pm). Hours outside this range are NOT rendered (no row in the grid). |
+| `hourRowHeight` | `number` | no | Pixel height per hour row in week/day views. Default 48. |
+| `resources` | `readonly CalendarResource[]` | no | Split `view="day"` into one column per bookable subject — practitioner, chair, room, bay — all sharing a single time axis and a single scroll container. This is the "resource day view" of scheduling products. Events are routed by `CalendarEvent.resourceId`. A timed event whose `resourceId` matches nothing (or is absent) lands in a trailing "unassigned" column, which is only rendered when such an event exists. All-day events without a `resourceId` are day-wide and span every column. Ignored by month, week and agenda views — those have their own column meaning. Don't approximate it with N side-by-side `<Calendar view="day">` in a `Split`: each brings its own header, gutter and scroll, so they drift. |
+| `backgroundIntervals` | `readonly CalendarBackgroundInterval[]` | no | Availability underlay for week/day views: non-interactive bands painted behind the events, distinguishing "closed" from "open and free". "Open and busy" already reads from the event blocks themselves. An interval list rather than a weekly-hours object, because working hours vary by day (a lunch break), by date (a holiday, a short day) and by column (per-practitioner shifts). Bands take no part in the event collision cascade and never intercept clicks — `onDayClick` still fires through them. Every interval is clipped to each column's own date, so a week view needs one interval per day rather than one that all seven columns share. |
+| `onEventMove` | `((event: CalendarEvent, next: CalendarEventMove) => CalendarDropResult)` | no | Enables drag-to-reschedule in week/day views. Called on drop with the proposed placement; the event's duration is preserved. **Nothing moves until you commit it.** `events` stays the source of truth — apply the change to your own state to make it stick. To refuse a drop (the server rejects overlaps, out-of-hours bookings, …) return `false`, or a promise that resolves `false` or rejects: the block snaps back and the preview is discarded. Prefer `canDropEvent` for rules you can evaluate synchronously — it refuses the drop *during* the drag, so the user sees it before releasing. Omit to keep today's read-only behaviour. |
+| `onEventResize` | `((event: CalendarEvent, next: CalendarEventResize) => CalendarDropResult)` | no | Enables drag-to-resize in week/day views (a handle on the block's bottom edge). `startsAt` is unchanged; only `endsAt` moves. Same commit and rejection semantics as `onEventMove`. |
+| `canDropEvent` | `((event: CalendarEvent, next: CalendarDropCandidate) => boolean)` | no | Synchronous veto, evaluated continuously while dragging. Return `false` and the placement renders as a refused drop and is never proposed to `onEventMove` / `onEventResize`. Use for rules you can check locally (opening hours, overlaps within the loaded event set); use the handler's own return value for rules only the server can settle. `next.mode` says which gesture is being judged, and narrows the payload: `'move'` carries the target `resourceId`, `'resize'` cannot change the column so it doesn't. Rules like "shortening is always fine, relocating needs approval" are otherwise inexpressible — the predicate fires while the pointer is still at the origin, where both gestures report the event's own start. Note that `backgroundIntervals` does NOT gate drops. Shading a slot closed is presentation; enforcing it is this predicate's job. Derive both from one source so they cannot drift. |
+| `dragSnapMinutes` | `number` | no | Snap granularity for drags, in minutes. Default 15 — a drag lands on a quarter-hour boundary rather than an arbitrary pixel offset. Also the step size for the keyboard equivalent (Alt + arrow keys). Values below 1 (including 0 and negatives) are treated as 1 minute. |
+| `renderEvent` | `RenderEvent` | no | Optional custom renderer for the inner content of every event chip across views (month chips, week/day timed blocks, all-day band chips). The returned ReactNode replaces the default `<time> · <title>` markup inside the chip's button wrapper — the wrapper still handles tone background, click, tooltip, and (for timed blocks) absolute positioning. To override colors, return content with inline styling that fills the wrapper (e.g., `position: absolute; inset: 0; background: <color>`). The `ctx` argument carries view-aware metadata: `view`, `asAllDay`, `continuesLeft`/`continuesRight` (multi-day), `timeLabel`, `duration`. |
+| …native | | | plus native `<div>` attributes |
+
+<!-- props:end -->
+
+- Four views: `'month'` (continuous event bars across the grid), `'week'` (7 columns × hour rows + all-day band), `'day'` (single column × hour rows), `'agenda'` (chronological list of the cursor's current week, grouped by day with empty days hidden).
+- Events are `{ id, title, startsAt, endsAt?, tone?, color?, allDay?, resourceId? }`. Multi-day events render as continuous bars in both the month grid and the week/day all-day band. `resourceId` routes a timed event to its column in the resource day view and is ignored by every other view.
+- **Two colour axes, and they do not compete.** `tone` is _semantic_ — what STATE the event is in: `neutral` (default) / `accent` / `success` / `warning` / `danger`. `color` is _identity_ — WHICH category it belongs to, as one of the 30 `PaletteColor`s. Use `color` when your events belong to a colour-bearing category the tenant chose (an appointment type, a calendar, a resource class).
+- With **no** `color`, tone paints the whole block exactly as it always has, and `allDay: true` renders as a tone-filled band (no time prefix). With `color` set, `color` takes the fill (palette tint background, saturated palette colour for text and border) and a non-`neutral` `tone` moves to a saturated stripe down the event's **leading edge** — so a category-coloured event can still show a state that must not be missed. There is no precedence rule to remember because the axes occupy different pixels.
+
+  ```tsx
+  // Category only — a clean single colour.
+  { id: '1', title: 'Consultation', startsAt, color: 'violet' }
+  // Category AND state — violet block, danger stripe. Both readable.
+  { id: '2', title: 'Consultation', startsAt, color: 'violet', tone: 'danger' }
+  ```
+
+  Don't map categories onto tones instead: tones are semantic and finite, two categories would collide on one tone, and the result is wrong in both directions — a `danger` chip that is merely a category, and a genuinely urgent event that looks like one.
+
+- **This is the opposite of `Badge`**, where `color` takes precedence over `tone` and the tone is discarded. Calendar renders both, because a calendar tone can carry states closer to safety than decoration (a masked hour, a released slot) and dropping one would make a free hour read as a booked one. Don't carry the Badge rule across.
+- **Both axes are visual only** — neither sets ARIA, and a 3px band is not an accessible signal (same contract as `Badge`). If a state must reach assistive tech, keep it in the event `title`. And pick category colours that contrast with the tones you use — measured RGB distance between the band colour and the category's own saturated colour — grouped by tone and ordered within each group: `success` + `mint` (11) / `emerald` (15) / `teal` (35) / `green` (41); `danger` + `red` (17) / `coral` (44); `warning` + `orange` (16) / `coral` (25) / `red` (43) / `amber` (44); `accent` + `blue` (40). Read it as a threshold, not a ranking. The worst pair is `success` + `mint` at 11, and anything under ~20 is effectively invisible at the rendered 4px (a 3px band plus the 1px border in the same colour; the agenda row has no border, so 3px there); the low 20s are detectable side-by-side but unreliable alone, and the low 40s are where this list stops rather than where the problem does. These moved (`success` + `mint` 18 → 11, `danger` + `red` 36 → 17) when those tones were raised to clear WCAG AA; `Calendar.collisions.test.ts` recomputes the list from the shipped tokens. Nothing enforces this — keep the state in the title too when a tenant's category colour collides.
+
+- In the **agenda** view the row is never filled (a tint would clash with the today-group accent and the hover background), so `color` sets the leading dot and `tone` still gets the edge stripe.
+- A coloured **all-day** chip uses the same palette tint as a timed one rather than the tone-filled treatment: the palette ships a `bg`/`fg` pair, and a filled variant would mean inventing 30 more tokens and asserting contrast at 12px for each. **The visible consequence:** a coloured all-day event renders at _timed-chip weight_ — same tint, same border, only the time prefix missing — so in a band that mixes coloured and uncoloured all-day events, the coloured ones read lighter. Colour the whole category or none of it if that bothers you.
+- On a multi-day bar the band repeats on **every** segment, including ones that continue from a previous week. It marks the event's state, not its start.
+- Controlled cursor via `value` / `onChange`, or uncontrolled via `defaultValue`. Controlled view via `view` / `onViewChange`, or uncontrolled via `defaultView`.
+- Overlapping timed events in week/day views render as a Google-Calendar-style cascade: each lane is offset to the right by a small constant step but every block extends to the column's right edge, with later lanes overlaying earlier ones via `z-index`. Hovering or keyboard-focusing a block lifts it to full width on top of all neighbours. A horizontal "now" line marks the current time in today's column.
+- Locale-aware via `useLocale()`; override with `locale` prop. UI strings (`today`, `viewMonth`, etc.) come from the i18n provider (`useTranslation`) — override them with `<I18nProvider overrides={{ calendar: { today: '…' } }}>`. There is no `labels` prop. For Russian copy and dates: `<I18nProvider locale="ru"><Calendar locale="ru-RU" … /></I18nProvider>`.
+- Read-mostly **by default**: `onDayClick` and `onEventClick` callbacks; opt into editing by wiring `onEventMove` / `onEventResize` (see _Drag to move and resize_ below). `onDayClick` fires across all views — month-cell click, "+N more" chip, keyboard activation (Enter/Space) on a focused cell, and (in week/day views) clicks on the empty hour-grid space of a day column. No built-in popover or modal — wire your own detail UI.
+- ARIA: month view is `role="grid" aria-readonly="true"`; arrow keys move focus, PageUp/PageDown navigates months, Enter/Space calls `onDayClick`. Week/day views are also `role="grid"` with `role="row"` + `role="columnheader"` headers and standard sequential tab order for event blocks — `aria-readonly="true"` there too, until a drag handler is wired (see below). Agenda view exposes the visible week as `role="list"` with each day group as a `role="listitem"` and the day label as an `<h3>` heading inside — screen readers announce the date grouping before reading each event row. **Known v3 gap:** in week/day views, `onDayClick` on empty hour-grid space is **mouse-only** (no keyboard equivalent). Consumers needing keyboard activation should drive their detail UI through the focusable event chips via `onEventClick`.
+
+#### Resource columns — one day, N lanes
+
+```tsx
+<Calendar
+  view="day"
+  events={appointments} // each carries resourceId
+  resources={[
+    { id: 'ana', label: 'Ana' },
+    { id: 'ben', label: 'Ben' },
+  ]}
+/>
+```
+
+- Routing is by `CalendarEvent.resourceId`. A **timed** event whose `resourceId` matches nothing (or is absent) lands in a trailing **Unassigned** column, which is only rendered when at least one such event exists. An **all-day** event with no `resourceId` is day-wide and spans every column; with one, it pins to that column.
+- Two bookings at the same hour in _different_ columns are not a collision — each takes lane 0 and full column width. The cascade still applies within one column.
+- Month, week and agenda views ignore `resources` — their columns already mean something else.
+
+#### Availability underlay — shade closed time, tint free time
+
+```tsx
+<Calendar
+  view="day"
+  events={appointments}
+  resources={resources}
+  backgroundIntervals={[
+    { startsAt: at(7, 0), endsAt: at(9, 0), resourceId: 'ana', tone: 'unavailable' },
+    { startsAt: at(9, 0), endsAt: at(17, 0), resourceId: 'ana', tone: 'available' },
+  ]}
+/>
+```
+
+- A booking calendar has three states and `hourRange` alone expresses none of them: **closed** (rendered but greyed), **busy** (an event covers it — already works), **free** (clickable). `backgroundIntervals` paints the first and third behind the events.
+- An interval list, not a weekly-hours object, because working hours vary by day (a lunch break), by date (a holiday, a short day) and by column (per-practitioner shifts).
+- `tone`: `'unavailable'` (default) shades; `'available'` tints. `resourceId` restricts the band to one resource column and is ignored in week view (and in a resource-less day view).
+- **Intervals are always clipped to each column's own date**, `resourceId` or not. Shading 08:00–09:00 across a week takes seven intervals, one per day — a single interval does not span the columns.
+- Bands render beneath events, take no part in the collision cascade, are `aria-hidden`, and are `pointer-events: none` — `onDayClick` still fires through them. Intervals are clipped to each column's day and to `hourRange`; ones that fall entirely outside are dropped.
+- Don't fake this with all-day events — that pollutes the `events` array you also read back.
+- **The underlay is paint, not policy.** Bands never gate drops — `backgroundIntervals` and `canDropEvent` are independent, and shading a slot closed does not stop a drag landing in it. A screen that shades shifts _and_ enables drag must express the same rule twice: once as intervals to draw it, once in `canDropEvent` to enforce it. Derive both from one source so they cannot drift.
+
+#### Drag to move and resize
+
+```tsx
+<Calendar
+  view="day"
+  events={appointments}
+  resources={resources}
+  dragSnapMinutes={15}
+  canDropEvent={(ev, next) => isWithinOpeningHours(next)}
+  onEventMove={async (ev, next) => {
+    const ok = await api.reschedule(ev.id, next);
+    if (!ok) return false; // rejected → the block snaps back
+    setAppointments((prev) => applyMove(prev, ev.id, next));
+  }}
+  onEventResize={(ev, next) => setAppointments((p) => applyResize(p, ev.id, next))}
+/>
+```
+
+- Both handlers are optional and additive — omit them and the calendar behaves exactly as before (read-only). `onEventMove` makes blocks draggable; `onEventResize` adds a handle on the block's bottom edge.
+- **A drop is proposed, never applied.** `events` stays the source of truth: commit the change to your own state or the block snaps back. `next` is `{ startsAt, endsAt, resourceId? }` for a move (duration preserved; `resourceId` is the column it landed on) and `{ startsAt, endsAt }` for a resize (`startsAt` unchanged).
+- **Two ways to refuse a drop.** `canDropEvent` is a synchronous predicate evaluated _continuously during_ the drag — the placement renders as refused for as long as the pointer rests on it, and never reaches the handler. Its `next.mode` says which gesture is being judged and narrows the payload (`'move'` carries the target `resourceId`; `'resize'` can't change the column, so it doesn't), which is what makes rules like "shortening is fine, relocating needs approval" expressible. The handler itself can return `false`, or a promise resolving `false` or rejecting, for rules only the server can settle; that verdict is announced in the live region rather than styled (the gesture is over by then), and the preview is held until the promise settles so an accepted drop doesn't flash back mid-request.
+- Dragging sideways crosses columns: another weekday in week view, another resource lane in the resource day view.
+- **Keyboard equivalent**, so rescheduling isn't mouse-only: on a focused block, `Alt`+`↑`/`↓` moves by one snap step, `Alt`+`←`/`→` moves a column, `Alt`+`Shift`+`↑`/`↓` changes the end time. Every block carries the full shortcut list as its `aria-describedby` description — it has to live on the blocks, since `role="grid"` here is not focusable and a description there would never be announced — and an assertive live region names the event and reports each proposed slot, each refusal, and each gesture that was already at the edge of what the bounds allow. With a drag handler wired, the grid drops `aria-readonly`.
+- **Bounds.** One rule governs both gestures: **the allowed range always contains where the event already is**, so a bound can refuse to move something further but never moves it the opposite way. Within that, a move keeps the start inside the visible `hourRange` — an unclamped upward drag would project into the previous calendar day — while the end runs past it freely, so an overnight booking keeps its duration; and a resize may grow or shrink the event by at most a day per gesture — the bound is on the CHANGE, not the absolute duration, so a multi-day booking stays adjustable — which lets an event be extended past midnight while stopping a runaway pointer delta rolling through whole dates. An event that already starts before `hourRange` (its block renders clipped at the top) is _not_ pulled into the window.
+- A gesture the bounds refuse outright proposes nothing: the handler is not called (it is typically an API write) and the live region says the event cannot move further.
+- Every time comes from the `CalendarEvent`, never from the rendered block — the layout clips a block that ends on a later day, so it is shorter than the event it represents.
+- **A move preserves ELAPSED duration**, not the row count. The two differ only on a daylight-saving day, where the grid necessarily draws wall-clock rows (01:00–05:00 occupies four rows though three hours pass) while a booking is its real duration — a 30-minute appointment takes 30 real minutes on any day of the year. This is also why a drop onto the skipped hour can't come back zero-length.
+- **Known gaps.** `onDayClick` still reports only a date, so in a resource day view it cannot say which column a free slot belongs to. After a keyboard column move, the block re-parents into the new column and loses focus, so nudges can't be chained. `touch-action: none` on a movable block means a touch that starts on an event drags it rather than scrolling the grid. Resource columns are `1fr` with no minimum width, so a dozen lanes squash rather than scroll — the all-day band lays itself out separately and would drift out of alignment if only the hour grid could scroll.
+- The click that terminates a drag is swallowed, so `onEventClick` doesn't fire on a reschedule. A plain click still opens your detail UI.
+- Drag-to-**create** (dragging empty grid space to draft a new event) is still out of scope — use `onDayClick` plus your own form.
+
+#### When NOT to use
+
+- ❌ Single-date or date-range selection → `<DatePicker>` / `<DateRangePicker>`.
+- ❌ Drag-to-create (see above).
+
+#### Anti-patterns
+
+- ❌ Mounting `<Calendar>` with no `events` AND no `onDayClick`: the grid is fully inert.
+- ❌ Pre-grouping events by day in the consumer. Pass the flat array; the layout algorithms group and lane internally.
+- ❌ Treating `onEventMove` as the thing that moves the event. It proposes; your state disposes, and not committing means the block snaps back.
+- ❌ Faking the availability underlay with all-day events, or approximating resource columns with N side-by-side day calendars (see above). Use `backgroundIntervals` and `resources`.

package/docs/components/Card.md

@@ -0,0 +1,165 @@
+# `<Card>` — bordered container
+
+- `fill` makes the Card fill a definite-height parent (`height: 100%`) and
+  applies `min-width: 0` so it can shrink inside narrow Grid, Sortable, and
+  DashboardCanvas cells. When a direct `Card.Body` is present, it also creates
+  Card's internal column/min-height chain. It does not create a height by
+  itself; bound the parent (for example with `Constrain height`) when needed.
+
+```tsx
+<Card padding="md">
+  <Stack gap="md">...</Stack>
+</Card>
+
+// Tone-coded stat card — 3px left-edge stripe in the tone color:
+<Card padding="md" tone="accent">Open deals</Card>
+```
+
+<!-- props:start -->
+
+## Props
+
+### `CardProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `padding` | `'none' \| 'sm' \| 'md' \| 'lg'` | no | Inner padding. - `none` — use when the card contains a table or list that should bleed edge-to-edge; inner sections manage their own padding. - `sm` (12px) — dense info cards. - `md` (16px) — default for plain-content cards. - `lg` (24px) — emphasis cards, marketing-style panels. When omitted, defaults to `'md'` for plain content, or `'none'` when the card contains compound subcomponents (`Card.Header` / `Card.Body` / `Card.List` / `Card.ListRow`) so its sections bleed to the card edge automatically. Pass an explicit value to override the auto-detect. **Detection is shallow:** only direct children are inspected. Fragments (`<>...</>`) are transparent — the detection recurses into them, so conditional renders that wrap compound children in a Fragment still trigger the auto-detect. But wrapping a `Card.Header` in any other element (`<div>`, `<Stack>`, etc.) defeats the heuristic — pass `padding="none"` explicitly in that case. |
+| `tone` | `'accent' \| 'info' \| 'success' \| 'warning' \| 'danger'` | no | Optional left-edge tone stripe (3px). Useful for "stat card" / "status card" patterns where one card in a row needs visual emphasis. Default: no stripe (the card keeps its standard bordered look). Uses the same tone vocabulary as `Alert`: `accent` / `info` / `success` / `warning` / `danger`. |
+| `overflow` | `'hidden' \| 'visible'` | no | How the card clips its children at the rounded border. - `hidden` (default) — children are clipped to the rounded border. This prevents the visible seam that appears at the corners when a child has square corners (Table's internal scroll wrapper, images, full-bleed media). Overlays in this library (DropdownMenu, Tooltip, Popover, Drawer, Modal) portal to `document.body` and are NOT clipped by this. Focus rings are NOT exempt: an `outline` is clipped by an ancestor's overflow, so a focusable flush against the card edge loses that band — draw its ring inset by passing `$offset: calc(-1 * var(--ring-offset))` to the `focus-ring` mixin, not a separate `outline-offset` after the `@include` (a `structure.test.ts` gate fails the build on that shape). - `visible` — opt out of clipping. Use when a direct child needs to overhang the card edge — decorative badges that protrude from a corner, hover-lift transforms whose shadow extends past the card border, etc. |
+| `fill` | `boolean` | no | Fill the containing block's height and allow the Card to shrink within a narrow grid cell. Use in stretched Grid, Sortable, or DashboardCanvas cells whose wrapper already has a definite height. When a direct `Card.Body` child is present, `fill` also establishes Card's internal column and minimum-height chain; add `scroll` to the Body to keep a sibling Header fixed above a scrolling content region. Defaults to `false`. |
+| …native | | | plus native `<div>` attributes |
+
+### `CardBodyProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `scroll` | `boolean` | no | Makes the body the flexible vertical scroll region of a `fill` Card while sibling `Card.Header` content stays fixed. The Card's parent must provide a definite height. Defaults to `false`. |
+| …native | | | plus native `<div>` attributes |
+
+### `CardHeaderProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `headerLevel` | `'h2' \| 'h3' \| 'h4' \| 'h5' \| 'h6'` | no | Heading level for the title text. Defaults to `'h3'` (assumes the page has an h1/h2 above). Override when this section sits beneath an h1 directly (`headerLevel="h2"`) or further nested (`headerLevel="h4"`). |
+| `surface` | `'default' \| 'subtle'` | no | `'subtle'` paints the header on a tinted (sunken) surface, for a nested editable sub-section inside a `Card.Body` (e.g. a condition group). Defaults to `'default'`. |
+| `controls` | `ReactNode` | no | Optional interactive slot right after the title (e.g. a `ButtonGroup` mode switch). Rendered outside the heading, so it is not part of the heading's name. Order: title, controls, meta, action. Controls never shrink: on a wide header the title ellipsizes down to a short minimum width; on a narrow header (under ~360px of content) the controls wrap onto a second row under the title, which keeps the first row with meta and action. Keep titles short, or pass a `title` attribute for long ones. |
+| `action` | `ReactNode` | no | Optional right-aligned slot — typically a `<Link>` or `<Button>` that lets the user navigate to a full list or take a section-level action. Rendered inside a `<span>` that never shrinks or wraps (flex-shrink: 0; with `meta` or `controls`, min-width: max-content). Beside `controls` it is the removal/section action of a nested sub-group (e.g. a ghost delete button), right-aligned after any meta. |
+| `meta` | `ReactNode` | no | Optional secondary, non-interactive text beside the title — freshness ("Updated 3 minutes ago") or status. Muted and single-line; sits just before `action` and is the first thing to give way at narrow widths: it truncates with an ellipsis before the title gives up any width, while `action` keeps its width. In a `fill` Card (which needs a parent of definite width) it is also visually hidden, still read by screen readers, once only a sliver would show. Not part of the heading's name. Put controls in `controls` or `action`, never here. `false` and `''` count as no meta. |
+| `children` | `ReactNode` | yes | Title content. Becomes the inner text of the heading element. Typically a plain string, but can contain inline elements if needed. |
+| …native | | | plus native `<div>` attributes |
+
+### `CardListProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `children` | `ReactNode` | yes | Row items — typically `<Card.ListRow>` elements. |
+| …native | | | plus native `<ul>` attributes |
+
+### `CardListRowProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `children` | `ReactNode` | yes | Row content — typically a `<Stack>` or `<Cluster>` of text and metadata. |
+| …native | | | plus native `<li>` attributes |
+
+<!-- props:end -->
+
+```tsx
+// Fixed header + scrolling body in a definite-height dashboard cell.
+<Constrain height="sm">
+  <Card fill>
+    <Card.Header>Pipeline</Card.Header>
+    <Card.Body scroll>
+      <Stack gap="sm">...</Stack>
+    </Card.Body>
+  </Card>
+</Constrain>
+```
+
+```tsx
+// Compound API — section card with header + list (Dashboard's "Deals needing attention" pattern).
+// No `padding` prop needed — Card auto-detects compound children and defaults to padding="none".
+<Card>
+  <Card.Header
+    action={
+      <Link as={RouterLink} to="/deals">
+        View all
+      </Link>
+    }
+  >
+    Deals needing attention
+  </Card.Header>
+  <Card.List>
+    {deals.map((d) => (
+      <Card.ListRow key={d.id}>
+        <Stack gap="xs">
+          <span>{d.title}</span>
+          <span>{d.company}</span>
+        </Stack>
+        <Avatar name={d.owner} size="sm" />
+      </Card.ListRow>
+    ))}
+  </Card.List>
+</Card>
+```
+
+- **Compound API** — `Card.Header` / `Card.Body` / `Card.List` / `Card.ListRow` for section-card patterns. Drop `padding="none"` — the parent Card auto-detects compound children.
+- `Card.Header`: title row (`h3` by default, override via `headerLevel`) with optional right-aligned `action` slot and bottom-border separator. Optional `meta` is muted secondary text (freshness, status) just before `action`; at narrow widths it truncates before the title shrinks (in a `fill` Card it then hides visually, staying readable by screen readers), and `action` never shrinks. Keep controls out of `meta`. With `controls` the order is title · controls … meta · action: controls and `action` never shrink, meta truncates first, and `action` stays right-aligned.
+- With `controls`, the title stays on one line. On a wide header it ellipsizes down to a short minimum width rather than pushing the controls out; on a narrow header (under ~360px of content) the controls wrap onto a second row under the title, and the first row keeps title · meta · action. For long titles beside `controls`, pass a `title` attribute so the full text stays reachable (`<Card.Header controls={…}><span title={name}>{name}</span></Card.Header>`), or keep titles short.
+- `Card.Body`: padded `<div>` content section. Add `scroll` beneath a Header in a `fill` Card to make Body the flexible vertical scroll region while Header stays fixed. Card intentionally owns this layout because it relates only its own compound pieces; the parent still owns the Card's definite outer height. `scroll` also sets `tabIndex={0}`, because a scroll container with no focusable descendant is unreachable by keyboard (axe `scrollable-region-focusable`) — pair it with `role="group"` and an `aria-label` when the content is worth naming, and pass `tabIndex={-1}` to opt out if the body already contains something focusable.
+- `Card.List`: semantic `<ul>` with list-reset styling — screen readers announce "list with N items".
+- `Card.ListRow`: `<li>` with padded content and bottom dividing border; last-child border suppressed automatically.
+- **Never nest Card in Card** — except an editable, repeatable sub-group (e.g. a condition group) inside a `Card.Body`, using `Card.Header surface="subtle"`; never for display-only content or as a layout wrapper. `controls` holds the sub-section's inline controls and `action` its remove button:
+
+```tsx
+<Card>
+  <Card.Header>Rules</Card.Header>
+  <Card.Body>
+    <Card>
+      <Card.Header
+        surface="subtle"
+        controls={
+          <ButtonGroup value={mode} onValueChange={setMode} aria-label="Match">
+            <ButtonGroup.Item value="all">Match all</ButtonGroup.Item>
+            <ButtonGroup.Item value="any">Match any</ButtonGroup.Item>
+          </ButtonGroup>
+        }
+        action={
+          <Button iconOnly variant="ghost" aria-label="Delete group">
+            <X size={12} />
+          </Button>
+        }
+      >
+        Group
+      </Card.Header>
+      <Card.Body>…conditions…</Card.Body>
+    </Card>
+  </Card.Body>
+</Card>
+```
+
+- `Card.Header` sits flush with the card edge inside `<Card padding="none">`. It renders a `<div>` holding the heading element plus an optional `<span>` wrapping `action` (with `meta`, a muted `<span>` between them and the header switches to a grid). With `controls`, the header is an inline-size container holding one inner `<div>` grid of four items — heading · controls `<span>` · meta (or an empty spacer) · action (or an empty placeholder) — so `action` stays right-aligned; a container query moves the controls to a second row when the header is narrow. The containment means a controls header contributes no intrinsic width, so give its Card a definite width (any block parent does). Under an `h1` with no `h2` above, pass `headerLevel="h2"`.
+- `Card.List` / `Card.ListRow`: row dividers use a `:last-child` selector to suppress the final bottom border. Fragments are transparent, but wrapping rows in an extra `<div>` or other element breaks the match and leaves a stray divider on the last row. Render rows as direct children (or via `.map`).
+- `Card.Body` keeps `scroll` for a bounded `fill` Card (Grid, Sortable or DashboardCanvas cell); for page-level scrolling let the page or `AppLayout` own the scroll area. Keep it a direct child of Card (Fragments are transparent) so Card can detect the compound structure.
+
+#### When NOT to use
+
+- ❌ Inside another Card, except the editable sub-group exception above (`Card.Header surface="subtle"` in a `Card.Body`). Never as the only child of another Card, or as a layout primitive (use `Stack` / `Cluster` / `Grid`). Card is for semantic grouping.
+- ❌ For every container. If the page looks like a deck of cards, nothing is visually grouped.
+- ❌ `Card.Body` outside a Card. It owns padding and sizing only as part of Card's compound structure.
+
+#### Anti-patterns
+
+- ❌ `<Card style={{ padding: 20 }}>`: use `padding`. A missing value is a token/scale conversation.
+- ❌ `<Card style={{ overflow: 'visible' }}>`: use `<Card overflow="visible">`.
+- ❌ `<Card style={{ height: '100%' }}>`: use `<Card fill>`, which also applies the shrink-safe minimum width for narrow grid cells.
+- ❌ Hand-rolling a flex column and scrolling body in a Card, or consumer CSS for `flex: 1`, `min-height: 0` or `overflow-y: auto`. Use `<Card fill>` with `<Card.Body scroll>`.
+- ❌ Expecting `scroll` to create a height. The Card's parent must provide a definite height; `fill` carries that bound into the body.
+- ❌ Hover shadows to make Cards "interactive". If the whole card is clickable, that's a different component (`LinkCard`).
+- ❌ Hand-rolling a left stripe via `className` / `style`. Use `tone`; it reserves the border-left space so layout never shifts.
+- ❌ Hand-rolling `.cardHeader` / `.list` / `.listRow` SCSS. Use the compound API.