@eocrm/design-system 0.0.0-stage → 0.6.18

package/docs/components/DateRangePicker.md

@@ -0,0 +1,71 @@
+# `<DateRangePicker>` — date-range input + two-month popover
+
+```tsx
+const [range, setRange] = useState<DateRange | null>(null);
+<DateRangePicker value={range} onChange={setRange} min={new Date()} />;
+```
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `value` | `DateRange \| null` | no | Selected range. `null` = no range. Pair with `onChange` for controlled use. |
+| `defaultValue` | `DateRange \| null` | no | Initial range for uncontrolled use. |
+| `onChange` | `((range: DateRange \| null) => void)` | no | Fires when a complete range commits (after second click in grid, or successful typed parse on blur). |
+| `locale` | `string` | no | Override locale (otherwise reads `useLocale()`). |
+| `min` | `Date` | no | Earliest selectable date (inclusive). Both halves and typed input are gated. |
+| `max` | `Date` | no | Latest selectable date (inclusive). |
+| `isDateDisabled` | `((date: Date) => boolean)` | no | Per-date disable predicate; gates both the popover grid and typed-input parsing. |
+| `size` | `'sm' \| 'md' \| 'lg'` | no | Field height + type scale. Same scale as `<DatePicker>`. Defaults to `'md'`. Affects only the trigger row; the two-month popover grid is fixed-size. - `'sm'` — 24px tall. - `'md'` — 32px tall (default). - `'lg'` — 40px tall. |
+| `clearable` | `boolean` | no | Show the ✕ clear button when a range is set. Defaults to `true`. |
+| `invalid` | `boolean` | no | Toggle red border + focus ring + `aria-invalid="true"`. Pair with a visible error and `aria-describedby`. |
+| `nameStart` | `string` | no | Form name for the START half (hidden `<input>` with an ISO date, so native `<form>` submission works). Post both keys or just one. |
+| `nameEnd` | `string` | no | Form name for the END half. |
+| `granularity` | `'day' \| 'minute'` | no | Picker precision. - `'day'` (default) — date only; behavior unchanged from prior releases. - `'minute'` — adds two manual-entry time inputs (start + end) below the two-month grid. The trigger text shows `HH:mm` after each date. Hidden form mirrors (when `nameStart` / `nameEnd` are set) emit ISO local datetime (`2026-05-28T14:30`). At `'minute'` the start/end time inputs are shown and editable in the popover even before a range is picked (defaulting to `00:00` / `23:59`). Times entered in the empty state are applied when the range is committed (instead of the bare defaults), and existing times are preserved across date re-picks. Same-day ranges with end-time < start-time are silently clamped so end-time ≥ start-time. |
+| `timeStep` | `number` | no | Minutes step for the start + end `<TimeField>` popovers and for rounding typed time input on commit. Defaults to `15`. Set `1` to disable rounding. Only meaningful when `granularity='minute'`. |
+| `hourCycle` | `'12' \| '24' \| 'auto'` | no | Display cycle for the two embedded `<TimeField>`s + the trigger's time tails. - `'24'` — `"HH:mm"` in trigger + 24h hour lists in popovers. - `'12'` — `"h:mm AM/PM"` in trigger + 12h hour lists + AM/PM column. - `'auto'` (default) — derives from the active locale via Intl. en-US → `'12'`; ru-RU → `'24'`. Only meaningful when `granularity='minute'`. Typed input is lenient regardless of cycle — both `"14:30"` and `"2:30 PM"` parse on blur. |
+| …native | | | plus native `<input>` attributes |
+
+<!-- props:end -->
+
+- Date-range selection (date-only by default; opt into date+time on each side with `granularity="minute"`). Single-date → `<DatePicker>`. Multi-date / preset ranges (Today, Last 7 days) — out of scope for v1.
+- Looks like an `<Input>`. Click the input or press ArrowDown to open; the popover shows two months side-by-side. The 📅 button toggles, the ✕ button clears the whole range.
+- Selection flow: first click sets the start; hover (or keyboard-focus) another cell to preview the range; second click commits and closes. If the second pick is earlier than the start, the range is auto-swapped to `[earlier, later]`. A third click in a reopened popover restarts selection.
+- Typed input parses on blur / Enter using the active locale. Accepts `—` (em dash), `–` (en dash), `-` (hyphen with spaces), or `to` (case-insensitive word) as the separator. ISO `YYYY-MM-DD` works for each half too. Out-of-order typed input is auto-swapped. Anything unparseable / out-of-range / disabled reverts to the last committed value.
+- ARIA: typed input has `aria-haspopup="dialog"` + `aria-expanded`. Popover wrapper is `role="dialog"` (labelled by `aria-label={t('datePicker.openCalendar')}`); each grid inside is `role="grid"` with `gridcell` buttons. The range-start and range-end cells (and the live hover end during selection) carry `aria-selected="true"`.
+- Keyboard inside a grid: ←→↑↓ move focus by 1 day, Home/End to start/end of week, PageUp/PageDown step a month, Enter/Space drives the same first-click → second-click flow, Escape closes and returns focus to the input. With selection-start set, the focused cell acts as the hover end so the preview range follows arrow keys.
+- Reuses `<DatePickerGrid>` via `selectionMode='range'` + `rangeStart`/`rangeEnd`/`hoverDate`/`onHoverDate` + `chevrons={false}`. The two grids share the same cursor; the picker renders its own prev/next chevrons outside them.
+- **Granularity.** Pass `granularity="minute"` to add dual `<TimeField>`s (start + end) below the two-month grid; the trigger text becomes `MM/DD/YYYY HH:mm — MM/DD/YYYY HH:mm` (24h locales) or `MM/DD/YYYY h:mm AM/PM — MM/DD/YYYY h:mm AM/PM` (12h locales) and the hidden form mirrors emit ISO local datetime. Defaults to `'day'` (backward compat). The start/end time inputs are shown and editable in the popover even before a range is picked — defaulting to `00:00` start / `23:59` end. Times set in this empty state are applied when the range is committed (no need to seed a placeholder range), and existing times are preserved across subsequent date picks. Same-day ranges silently clamp end-time to ≥ start-time on every commit; different-day ranges are not clamped. `timeStep` (default `15`, in minutes) applies to BOTH TimeFields, controlling each minute-list row count AND rounding typed input in the time fields on commit; set `timeStep={1}` to disable rounding. The trigger text-input parses exactly as typed — `timeStep` does not round trigger input. `hourCycle` (default `'auto'`) forwards to both embedded TimeFields and controls the trigger text — `'12'` / `'24'` force a cycle, `'auto'` derives from locale.
+
+```tsx
+// Uncontrolled
+<DateRangePicker defaultValue={{ start: new Date(), end: new Date() }} />
+
+// Controlled, constrained to a 90-day window
+<DateRangePicker
+  value={range}
+  onChange={setRange}
+  min={new Date()}
+  max={new Date(Date.now() + 90 * 86_400_000)}
+/>
+
+// Form mirror, two separate fields
+<form action="/api/bookings">
+  <DateRangePicker nameStart="bookingStart" nameEnd="bookingEnd" />
+</form>
+```
+
+#### When NOT to use
+
+- Single date: use `<DatePicker>`.
+- Seconds-precision tracking: only `granularity="minute"` is supported.
+- Time-only fields (no date): out of scope.
+- Multi-date selection (3+ non-contiguous dates): out of scope.
+
+#### Anti-patterns
+
+- ❌ Passing `value` without `onChange` — the picker is fully controlled when `value` is set; user input has no effect.
+- ❌ Using `defaultValue` AND `value` together — pick one.

package/docs/components/DateStrip.md

@@ -0,0 +1,56 @@
+# `<DateStrip>` — week of selectable day tiles
+
+```tsx
+const [day, setDay] = useState<string | null>(null);
+<DateStrip
+  days={week} // [{ date: '2026-10-05', free: 3 }, … 7 days]
+  value={day}
+  onChange={setDay}
+  onPrevious={prevWeek}
+  onNext={nextWeek}
+  canPrevious={!isCurrentWeek}
+/>;
+```
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `days` | `DateStripDay[]` | yes | The days to show, in order — usually one week (7); one grid column per day. The month heading is derived from the first and last. |
+| `value` | `string \| null` | yes | Selected day (`'YYYY-MM-DD'`), or `null`. A value not in `days` checks nothing. |
+| `onChange` | `(date: string) => void` | yes | Called with the chosen day's `'YYYY-MM-DD'`. Controlled — update `value` yourself. |
+| `onPrevious` | `() => void` | yes | Previous-week button handler. Replace `days` with the earlier week. |
+| `onNext` | `() => void` | yes | Next-week button handler. Replace `days` with the later week. |
+| `canPrevious` | `boolean` | no | `false` disables the previous-week button (e.g. the current week). Default `true`. |
+| `canNext` | `boolean` | no | `false` disables the next-week button (end of the booking window). Default `true`. |
+| `titleOrder` | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | no | Heading level of the month label. Default `2`. |
+| `name` | `string` | no | Radio group `name` (also submitted with a form). Default: a generated id. |
+| `invalid` | `boolean` | no | Marks the group `aria-invalid` (the radios themselves do not support it). Field / SettingRow inject it. Default: `false`. |
+| `required` | `boolean` | no | Native `required` on the radios (the group then fails form validation until one is chosen). Field / SettingRow inject it; it used to land on the root as a stray attribute. |
+| …native | | | plus native `<fieldset>` attributes |
+
+<!-- props:end -->
+
+- `date` is an ISO `'YYYY-MM-DD'` calendar day (the business's day, not a `Date`); the strip formats weekday / number / month through the locale in UTC, so the browser timezone never shifts it. The month heading is derived ("October 2026", "September – October 2026").
+- `free: 0` → "No times", tile natively disabled (skipped by Tab and arrows). Keep full days in the array.
+- Native radios, one `name`: one Tab stop, arrows move AND select (so `onChange` fires per arrow press — debounce slot fetching if needed). Tiles are `role="radio"` named "Wednesday, October 7, 9 free"; query them that way in tests.
+- Controlled only.
+- In `<Field>` / `<SettingRow>`: the row label is merged in front of the month (group name "Day October 2026"), the error describes the group, `invalid` → `aria-invalid` on the group, `required` → native `required` on the radios. One column per day (`days.length`), so a 5-day week has 5 columns.
+- Previous/next use `aria-disabled` (not `disabled`) when `canPrevious`/`canNext` is false, so focus stays on the button that reached the boundary.
+- Changing week announces the new range politely; same-week re-renders stay silent.
+- ❌ No `aria-label` on the strip — the month heading names the group. ❌ No `Date`/`toISOString()` for `date`.
+- ❌ In an intrinsic-width context (`Split`'s default `auto` aside track, a `Cluster` item, `width: max-content`) it renders at width 0 — `container-type: inline-size` zeroes its intrinsic-width contribution; give the parent a concrete width (e.g. `asideWidth` on a Split). It is also the containing block for absolutely-positioned descendants (layout containment).
+- When NOT to use: any-date picking → `<InlineDatePicker>`; events → `<Calendar>`; times → `<SlotGrid>`.
+- ❌ Building `date` from `toISOString()` of a local-midnight `Date` — it shifts a day west of UTC. Produce the business-timezone calendar day.
+- When NOT to use: scheduling or showing events → `<Calendar>`; free-form time entry → `<TimeField>`.
+
+```tsx
+// Booking time step: DateStrip picks the day, SlotGrid the time.
+<Stack gap="lg">
+  <DateStrip days={week} value={day} onChange={setDay} onPrevious={prev} onNext={next} />
+  <SlotGrid groups={slotsFor(day)} value={slot} onChange={setSlot} />
+</Stack>
+```

package/docs/components/DefinitionList.md

@@ -0,0 +1,82 @@
+# `<DefinitionList>` — semantic key/value pairs (dl / dt / dd)
+
+For displaying entity properties — contact details, settings rows, metadata sidebars. Renders proper `<dl>`/`<dt>`/`<dd>` so screen readers announce term/description pairs natively. Compound: `DefinitionList`, `DefinitionList.Item`, `DefinitionList.Term`, `DefinitionList.Description`.
+
+```tsx
+<DefinitionList dividers>
+  <DefinitionList.Item>
+    <DefinitionList.Term>Email</DefinitionList.Term>
+    <DefinitionList.Description icon={<Mail size={14} />}>
+      ada@example.com
+    </DefinitionList.Description>
+  </DefinitionList.Item>
+  <DefinitionList.Item>
+    <DefinitionList.Term>Phone</DefinitionList.Term>
+    <DefinitionList.Description icon={<Phone size={14} />}>
+      +1 (415) 555-0142
+    </DefinitionList.Description>
+  </DefinitionList.Item>
+</DefinitionList>
+```
+
+<!-- props:start -->
+
+## Props
+
+### `DefinitionListProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `layout` | `'horizontal' \| 'stacked'` | no | Layout direction. See `DefinitionListLayout`. Default `'horizontal'`. |
+| `termWidth` | `string` | no | CSS length applied to the term column in horizontal layout (e.g. `'180px'`, `'20%'`, `'max-content'`). Default `'max-content'` — column sizes to the longest term across all rows. Set explicitly when you need consistent alignment across multiple DefinitionLists on the same screen. |
+| `spacing` | `'sm' \| 'md' \| 'lg'` | no | Vertical padding per item. See `DefinitionListSpacing`. Default `'sm'`. |
+| `dividers` | `boolean` | no | Render a 1px border between items. Default `false` (clean, dense look). Set when migrating from a `Card.List` and you want to preserve the table-row separator visual. |
+| …native | | | plus native `<dl>` attributes |
+
+### `DefinitionListDescriptionProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `icon` | `ReactNode` | no | Leading decorative icon, rendered inside the `<dd>` before children. Wrapped in an `aria-hidden` span — the `<dt>` carries the semantic label so the icon is purely visual. |
+| `children` | `ReactNode` | yes | The value content. Any ReactNode — text, Badges, Links, etc. |
+| …native | | | plus native HTML attributes |
+
+### `DefinitionListItemProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `children` | `ReactNode` | yes | A `DefinitionList.Term` and a `DefinitionList.Description`. |
+| …native | | | plus native `<div>` attributes |
+
+### `DefinitionListTermProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `children` | `ReactNode` | yes | The label text — kept short, terms are headings for their values. |
+| …native | | | plus native HTML attributes |
+
+<!-- props:end -->
+
+Use this instead of `Card.List` + `Card.ListRow` whenever the data is genuinely key/value (every row has a label and a value). Use `Card.List` when rows aren't keyed (activity feeds, list of cards).
+
+**Anti-patterns**
+
+- ❌ Wrapping a `<DefinitionList.Description>` directly in `<DefinitionList>` without an enclosing `<DefinitionList.Item>` — the dev warning fires and grid layout breaks.
+- ❌ Putting interactive content in `<DefinitionList.Term>`. Use `<DefinitionList.Description>` for values, including ones containing `<Link>` or `<Button>`.
+- ❌ Stacking multiple `<DefinitionList.Description>` children under one Item to render "multiple values for one key." Works HTML-wise but doesn't have styling support — render multiple Items with the same Term text if you need that pattern.
+
+Not for tabular data with multiple columns per row — use `Table` / `DataTable`.
+
+```tsx
+// Stacked (settings-style)
+<DefinitionList layout="stacked">
+  <DefinitionList.Item>
+    <DefinitionList.Term>Workspace name</DefinitionList.Term>
+    <DefinitionList.Description>Acme Corp</DefinitionList.Description>
+  </DefinitionList.Item>
+</DefinitionList>
+```

package/docs/components/Divider.md

@@ -0,0 +1,57 @@
+# `<Divider>` — separator primitive
+
+Thin rule between content sections. Horizontal (default) or vertical. Optional centered label slot. Three size tiers + solid/dashed variants.
+
+```tsx
+import { Divider } from '@eocrm/design-system';
+
+// Default horizontal
+<Divider />
+
+// Vertical inside a Cluster (toolbar separator)
+<Cluster gap="sm">
+  <Button>Edit</Button>
+  <Divider orientation="vertical" />
+  <Button>Duplicate</Button>
+</Cluster>
+
+// Labeled (auth-form pattern)
+<Divider>OR</Divider>
+
+// Variants + sizes
+<Divider variant="dashed" />
+<Divider size="lg" />
+```
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `orientation` | `'horizontal' \| 'vertical'` | no | Layout direction. Defaults to `'horizontal'`. |
+| `variant` | `'solid' \| 'dashed'` | no | Line style. Defaults to `'solid'`. |
+| `size` | `'sm' \| 'md' \| 'lg'` | no | Line thickness tier. Defaults to `'sm'`. |
+| `children` | `ReactNode` | no | Optional centered label rendered between two line segments. Common pattern: `<Divider>OR</Divider>` for auth-form section breaks. When `children` is set, the root becomes `<div role="separator">` instead of `<hr>` (HTML `<hr>` cannot have children). Works with `orientation="vertical"` but renders awkwardly (text wraps across two short line segments). Avoid vertical + label combos. |
+| …native | | | plus native HTML attributes |
+
+<!-- props:end -->
+
+- **Without `children`** it renders a native `<hr>` (the right semantic for a thematic break).
+- **Default**: solid, size `'sm'` (1px), horizontal.
+- **Labeled** dividers use `<div role="separator">` instead of `<hr>` because HTML `<hr>` can't have children.
+- **Vertical** dividers stretch to the parent's height — works inside Cluster/Stack/Flex but needs a parent with known height. Falls back to `--space-3` minimum height as a sanity floor.
+- **No spacing prop** — parent owns layout per Rule 4. Use Stack `gap` around the Divider.
+
+#### When NOT to use
+
+- ❌ Decorative under a heading → just style the heading's `border-bottom`.
+- ❌ Between unrelated stacked sections → use Stack with `gap` instead.
+- ❌ A tone-driven separator (warning/danger) → use `<Alert>` for persistent tone-tied messages.
+
+#### Anti-patterns
+
+- ❌ `<Divider>OR</Divider>` with `orientation="vertical"` — text wraps awkwardly across two short line segments.
+- ❌ `<Divider size="lg" />` for casual section breaks. Reserve `lg` (3px) for strong visual hierarchy.
+- ❌ Adding `margin` via inline `style`. The parent should own spacing.

package/docs/components/Dot.md

@@ -0,0 +1,26 @@
+# `<Dot>` — bare palette/tone colored circle
+
+```tsx
+// Palette color, paired with a label:
+<Cluster gap="xs"><Dot color="violet" /> Design</Cluster>
+
+// Semantic tone:
+<Dot tone="success" />
+```
+
+<!-- props:start -->
+
+## Props
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `color` | `PaletteColor` | no | One of the 30 `PaletteColor`s — renders the bare circle in that color's saturated `--color-palette-<name>-fg` token (the same color OptionsPicker groups and palette Badges use). Takes precedence over `tone`. |
+| `tone` | `'neutral' \| 'info' \| 'success' \| 'warning' \| 'danger' \| 'purple'` | no | A semantic `BadgeTone` (`neutral` default / `info` / `success` / `warning` / `danger` / `purple`) — used when `color` is omitted. Neither set → `neutral`. |
+| …native | | | plus native `<span>` attributes |
+
+<!-- props:end -->
+
+- A bare, background-less 6px circle (`--size-badge-dot`) for color-coding affordances — a leading dot on a filter / `FilterChip`, a status indicator, a legend swatch. Unlike `<Badge dot>` it paints NO badge surface; it is just the dot.
+- **Decorative**: `aria-hidden` by default (overridable). The dot alone conveys nothing to assistive tech — always pair it with a visible label / accessible text.
+- **When NOT to use**: a status pill WITH text → use `<Badge>` (it owns a surface + label). The sole signal of meaning → color isn't an accessible signal on its own; accompany with text.

package/docs/components/Drawer.md

@@ -0,0 +1,94 @@
+# `<Drawer>` — edge-anchored slide-in panel
+
+```tsx
+const [open, setOpen] = useState(false);
+
+<Button onClick={() => setOpen(true)}>Show filters</Button>
+
+<Drawer open={open} onOpenChange={setOpen} side="right" size="md">
+  <Drawer.Header>Filters</Drawer.Header>
+  <Drawer.Body>
+    <Stack gap="md">
+      <Input label="Name" value={...} onChange={...} />
+    </Stack>
+  </Drawer.Body>
+  <Drawer.Footer>
+    <Drawer.Close><Button variant="secondary">Cancel</Button></Drawer.Close>
+    <Button onClick={apply}>Apply</Button>
+  </Drawer.Footer>
+</Drawer>
+```
+
+<!-- props:start -->
+
+## Props
+
+### `DrawerProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `open` | `boolean` | yes | Controlled open state. Required — Drawer has no uncontrolled mode. |
+| `onOpenChange` | `(open: boolean) => void` | yes | Fired when Drawer wants to change open state — Esc, overlay click, Close, swipe, programmatic. |
+| `side` | `'left' \| 'right' \| 'top' \| 'bottom'` | no | Edge the drawer slides in from: `left`, `right` (default), `top`, `bottom`. |
+| `size` | `'sm' \| 'md' \| 'lg'` | no | Size preset: `sm` 320px, `md` 440px (default), `lg` 640px. Width for left/right, height for top/bottom. Capped to `viewport - 32px` on narrow viewports; always edge-anchored, never fullscreen. |
+| `overlay` | `'solid' \| 'blur'` | no | Overlay variant. 'solid' (default) \| 'blur' (frosted glass, `backdrop-filter: blur(4px)`). |
+| `stackMode` | `'replace' \| 'overlay'` | no | How this drawer relates to other open overlays (Modals or Drawers). 'overlay' (default): parent stays visible. 'replace': parent hidden via display:none. |
+| `disableEscapeClose` | `boolean` | no | Disable Escape-to-close. Default false. |
+| `dismissOnOverlayClick` | `boolean` | no | When false, overlay click does NOT close. Default true. |
+| `dragToClose` | `boolean` | no | Enable swipe-to-close gesture on touch devices (from Header). Default true. |
+| `initialFocusRef` | `RefObject<HTMLElement \| null>` | no | Initial focus target on open. |
+| `children` | `ReactNode` | yes |  |
+| `className` | `string` | no |  |
+| `style` | `CSSProperties` | no |  |
+| `aria-label` | `string` | no |  |
+| `aria-describedby` | `string` | no |  |
+
+### `DrawerBodyProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `padding` | `'none' \| 'default'` | no | Override body padding. Default 'default' (--space-4). 'none' for edge-to-edge. |
+| …native | | | plus native `<div>` attributes |
+
+### `DrawerCloseProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `children` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` | yes | Exactly one React element. Close clones it to inject an onClick that closes the drawer, chained with the child's existing onClick. |
+
+### `DrawerFooterProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `align` | `'start' \| 'end' \| 'space-between'` | no | Horizontal action alignment. Default 'end'. |
+| …native | | | plus native `<div>` attributes |
+
+### `DrawerHeaderProps`
+
+<!-- prettier-ignore -->
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `closeButton` | `boolean` | no | Show the built-in × close button. Default true. |
+| …native | | | plus native `<div>` attributes |
+
+<!-- props:end -->
+
+- **Compound API:** `<Drawer.Header>` — title, auto-wired `aria-labelledby`, built-in × close button unless `closeButton={false}`, and the drag-to-close origin; `<Drawer.Body>` — scrollable content; `<Drawer.Footer>` — pinned action bar; `<Drawer.Close>` — wraps a clickable child so activating it dismisses the drawer.
+- **Dialog semantics:** same focus-lock and scroll-lock as Modal. Passing neither `<Drawer.Header>` nor `aria-label` fires a dev warning.
+- **Drag-to-close** on mobile: swipe the Header in the dismiss direction (right drawer → swipe right, bottom → swipe down, etc.). Threshold: 40% of drawer size or 0.5 px/ms velocity. Opt out with `dragToClose={false}`.
+- **Stacks with Modal.** Both share one overlay registry — a Drawer can open from inside a Modal (and vice versa). Escape closes the topmost regardless of type — after yielding to any open floating surface (innermost-first: the first press closes the surface, the next closes the host); body scroll lock is shared.
+- **Focus return:** the element focused before the Drawer opened gets focus back on close — also when the Drawer mounts already open (`{seed && <Drawer open …/>}`) and when it unmounts while open. On unmount it only restores if focus was actually lost, so an element your own code focused after the unmount keeps focus.
+- **Forced step:** combine `disableEscapeClose + dismissOnOverlayClick={false} + dragToClose={false}` + `<Drawer.Header closeButton={false}>` + omit `<Drawer.Close>`.
+
+**Anti-patterns:**
+
+- ❌ Same-side stacked drawers as a navigation pattern. They visually overlap — use route changes instead.
+- ❌ Drag from inside `<Drawer.Body>` does not close the drawer. Only Header is draggable (so Body scroll works correctly).
+- ❌ For center-anchored dialogs, use `<Modal>` not Drawer. For lightweight popovers use `<Popover>` or `<DropdownMenu>`; for non-blocking notifications use `<Toast>` (not yet shipped).
+- ❌ Worrying about a `position: fixed` ancestor — the Drawer portals to `document.body`, so render it at any level.
+
+**See also:** `<Modal>` for center-anchored variant.