@hegemonart/get-design-done 1.15.0 → 1.18.0

package/reference/components/command-palette.md

@@ -0,0 +1,228 @@
+# Command Palette — Benchmark Spec
+
+**Harvested from**: Linear, Raycast, Radix CMDK, GitHub Primer, UUPM (app-interface, MIT)
+**Wave**: 4 · **Category**: Navigation & Data
+
+---
+
+## Purpose
+
+A command palette is a keyboard-first global launcher that lets users search across commands, pages, and actions from anywhere in the application without navigating menus. Triggered by Cmd+K (macOS) / Ctrl+K (Windows/Linux), it provides fast access to frequently used actions and deep navigation. It is distinct from a local search input (scoped to one page) and from a Menu (contextual, anchored). *(Linear command palette, Raycast, Radix CMDK, GitHub Primer all converge on Cmd/Ctrl+K trigger + dialog + combobox + listbox pattern)*
+
+---
+
+## Anatomy
+
+```
+┌─────────────────────────────────────────────────┐
+│ role="dialog" aria-modal="true"                 │
+│ aria-label="Command palette"                    │
+│ ┌─────────────────────────────────────────────┐ │
+│ │ 🔍 [Search commands…              ]         │ │  role="combobox"
+│ └─────────────────────────────────────────────┘ │  aria-autocomplete="list"
+│ ┌─────────────────────────────────────────────┐ │
+│ │ role="listbox" id="cmd-results"             │ │
+│ │ ── Recent ──────────  role="group"          │ │
+│ │   Dashboard            role="option"        │ │
+│ │ ── Commands ──────────  role="group"        │ │
+│ │ ▶ New Project          role="option" ●      │ │  aria-selected="true"
+│ │   Invite member        role="option"        │ │
+│ └─────────────────────────────────────────────┘ │
+└─────────────────────────────────────────────────┘
+```
+
+| Part | Required | Notes |
+|------|----------|-------|
+| Dialog overlay | Yes | `role="dialog"` + `aria-modal="true"` + `aria-label="Command palette"` |
+| Focus trap | Yes | Tab/Shift+Tab cycle within dialog only |
+| Search input | Yes | `role="combobox"` + `aria-expanded` + `aria-autocomplete="list"` + `aria-controls` |
+| Results list | Yes | `role="listbox"` + `id` (target of `aria-controls`) |
+| Result items | Yes | `role="option"` + `aria-selected` |
+| Section groups | No | `role="group"` + `aria-label` per section (Recent, Commands, Pages) |
+| Empty state | Yes | "No results for X" text; `aria-live="polite"` on result region |
+| Keyboard shortcut hints | No | `aria-hidden="true"`; display-only |
+
+---
+
+## Variants
+
+| Variant | Description | Systems |
+|---------|-------------|---------|
+| Default | Cmd/Ctrl+K global trigger; full-width results | Linear, Raycast, Radix CMDK |
+| Inline search | Embedded within a page; narrower context | Primer, Atlassian |
+| Global search | Cross-section nav + recent pages + action shortcuts | UUPM app-interface (MIT) |
+| With categories | Grouped results by type (Recent / Commands / Pages) | Linear, Raycast, UUPM |
+| With icons | Category and action icons beside results | Linear, Raycast |
+| Nested commands | Select a command to reveal sub-commands | Raycast, Radix CMDK |
+
+**Norm** (≥4 systems agree): `role="dialog"` + focus trap + `role="combobox"` input + `role="listbox"` results.
+**Diverge**: Raycast supports nested command flows (select command → enter parameters); Linear/CMDK keep it flat for speed.
+
+---
+
+## States
+
+| State | Trigger | Visual | ARIA |
+|-------|---------|--------|------|
+| closed | — | Dialog hidden | — |
+| open | Cmd/Ctrl+K | Dialog visible; input focused | `aria-expanded="true"` on combobox |
+| empty | no query | Placeholder or recent items | `aria-expanded="true"` |
+| searching | typing | Results update in real-time | `aria-live="polite"` on results region |
+| result-focus | ArrowDown/Up | Item highlighted | `aria-selected="true"` on option |
+| no-results | no matches | "No results for X" message | `aria-live="polite"` announces update |
+| loading | async search | Spinner in input or results | `aria-busy="true"` on listbox |
+
+---
+
+## Sizing & Spacing
+
+| Element | Value | Notes |
+|---------|-------|-------|
+| Dialog width | 560–640px | Centered horizontally |
+| Dialog max-height | 480px | Results region scrolls beyond this |
+| Input height | 48–56px | Generous; primary interaction surface |
+| Result item height | 40px | Icon + label + shortcut hint |
+| Section label height | 28px | Muted heading; non-interactive |
+| Backdrop | 40–60% opacity black | `rgba(0,0,0,0.5)`; click to dismiss |
+
+**Norm**: 560–640px width (Linear, Raycast, CMDK all converge). Input height 48px+ for legibility.
+
+---
+
+## Typography
+
+- Input placeholder: body-md (15–16px), `color: --text-placeholder`
+- Input value: body-md (15–16px), weight 400
+- Result item label: body-sm (13–14px), weight 400; matched substring bold/highlighted
+- Section heading: label-xs (11px), uppercase, weight 600, `color: --text-subtle`, `aria-hidden="true"` if role="group" handles it
+- Keyboard shortcut hints: label-xs (11px), `color: --text-subtle`, right-aligned, `aria-hidden="true"`
+
+Cross-link: `reference/typography.md` — body-md, label scale
+
+---
+
+## Keyboard & Accessibility
+
+> **WAI-ARIA role**: `dialog` (overlay), `combobox` (input), `listbox` (results), `option` (items), `group` (sections)
+> **Required attributes**: `aria-modal="true"` on dialog; `aria-label="Command palette"` on dialog; `aria-expanded` + `aria-autocomplete="list"` + `aria-controls` on combobox; `aria-selected` on options; `aria-label` on each `role="group"`
+
+### Keyboard Contract
+
+*Quoted verbatim from WAI-ARIA APG — https://www.w3.org/WAI/ARIA/apg/patterns/combobox/ and https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/ — W3C — 2024*
+
+| Key | Action |
+|-----|--------|
+| Cmd+K / Ctrl+K | Opens the command palette (global shortcut) |
+| ArrowDown | Moves focus to first result (from input) or next result |
+| ArrowUp | Moves focus to previous result; loops to input |
+| Home | Moves focus to first result in list |
+| End | Moves focus to last result in list |
+| Enter | Executes the selected result |
+| Escape | Closes the palette; returns focus to trigger element |
+| Tab / Shift+Tab | Cycles focus within dialog (focus trap) |
+
+### Accessibility Rules
+
+- Dialog MUST have `aria-modal="true"` — prevents AT from reading content outside the palette
+- `role="combobox"` input MUST have `aria-controls` pointing to the `role="listbox"` `id`
+- `aria-live="polite"` on the results region ensures AT announces result count changes and empty state
+- Focus MUST be trapped within the dialog while it is open (Tab/Shift+Tab cycle inside)
+- On close, focus MUST return to the element that triggered the palette (not body)
+- Keyboard shortcut hints (`⌘K`, `↵`) MUST be `aria-hidden="true"` — the shortcut must be registered separately
+
+Cross-link: `reference/accessibility.md` — dialog focus trap, combobox pattern, live regions
+
+---
+
+## Motion
+
+| Transition | Duration | Easing | Notes |
+|------------|----------|--------|-------|
+| Dialog open | 150ms | ease-out | Scale 0.96→1 + opacity 0→1 |
+| Dialog close | 100ms | ease-in | Opacity 1→0 |
+| Results update | 80ms | ease-out | Fade new results; avoid reflow |
+| Backdrop fade in | 150ms | ease-out | Opacity 0→0.5 |
+| Item selection flash | 80ms | ease-out | Brief fill before execute |
+
+**BAN**: Do not animate result item reordering as the user types — causes visual instability and is disorienting for AT users with animations enabled.
+
+Cross-link: `reference/motion.md` — dialog entry, BAN-04
+
+---
+
+## Do / Don't
+
+### Do
+- Trap focus inside the dialog while open *(WAI-ARIA APG dialog pattern, WCAG 2.1.2)*
+- Set `aria-live="polite"` on the results region *(WCAG 4.1.3, Radix CMDK)*
+- Return focus to the trigger element on close *(WAI-ARIA APG)*
+- Use `role="group"` + `aria-label` for result sections *(WAI-ARIA APG, Linear, Raycast)*
+
+### Don't
+- Don't build a custom overlay without `role="dialog"` + `aria-modal` — screen readers will read background content *(WCAG 1.3.1)*
+- Don't omit `aria-controls` on the combobox — AT cannot associate input with results *(WAI-ARIA APG combobox)*
+- Don't open on hover or auto-focus — Cmd/Ctrl+K is the expected trigger *(Linear, Raycast convention)*
+- Don't dismiss on every Escape keypress inside nested command flows — first Escape should exit sub-level, second closes palette *(Raycast, Linear)*
+
+---
+
+## Anti-patterns Cross-links
+
+| Anti-pattern | Entry |
+|--------------|-------|
+| BAN-04 | `transition: all` on results list — `reference/anti-patterns.md#ban-04` |
+
+---
+
+## Benchmark Citations
+
+| Claim | Sources |
+|-------|---------|
+| role="dialog" + aria-modal="true" + focus trap | WAI-ARIA APG dialog pattern |
+| role="combobox" + aria-controls for input | WAI-ARIA APG combobox pattern |
+| Cmd/Ctrl+K universal trigger | Linear, Raycast, GitHub, VS Code (industry convention) |
+| aria-live="polite" on results region | WAI-ARIA APG, WCAG 4.1.3 |
+| role="group" + aria-label for result sections | WAI-ARIA APG, Radix CMDK |
+
+Full system URLs: `connections/design-corpora.md`
+
+---
+
+## Grep Signatures
+
+```bash
+# Dialog overlay missing aria-modal
+grep -rn 'command.*palette\|cmdk\|command-menu' src/ | grep 'role="dialog"' | grep -v 'aria-modal'
+
+# Combobox missing aria-controls pointing to listbox
+grep -rn 'role="combobox"' src/ | grep -v 'aria-controls'
+
+# Results listbox missing id (needed for aria-controls target)
+grep -rn 'role="listbox"' src/ | grep -v 'id='
+
+# Missing aria-live on results region
+grep -rn 'command.*palette\|cmd.*results\|cmdk' src/ | grep 'results\|listbox' | grep -v 'aria-live'
+```
+
+---
+
+## Failing Example
+
+```html
+<!-- BAD: custom overlay with keyboard handling but no ARIA roles -->
+<div class="command-palette" style="display:block">  <!-- no role="dialog", no aria-modal -->
+  <input type="text" placeholder="Search commands…">  <!-- no role="combobox", no aria-controls -->
+  <div class="results">  <!-- no role="listbox" -->
+    <div class="result-item active" onclick="execute('new-project')">
+      New Project
+    </div>
+    <div class="result-item" onclick="execute('invite')">
+      Invite member
+    </div>
+  </div>
+</div>
+```
+
+**Why it fails**: No `role="dialog"` — AT does not treat this as a modal, and screen readers continue reading background content; no focus trap; input lacks `role="combobox"` and `aria-controls`; results have no `role="listbox"`; items have no `role="option"` or `aria-selected`; no `aria-live` region for result updates.
+**Grep detection**: `grep -rn 'command.*palette\|cmdk\|command-menu' src/ | grep '<div' | grep -v 'role='`
+**Fix**: Use `role="dialog"` + `aria-modal="true"` on the overlay; implement focus trap; add `role="combobox"` + `aria-controls` to input; add `role="listbox"` to results container; add `role="option"` + `aria-selected` to each item; add `aria-live="polite"` to results region.

package/reference/components/date-picker.md

@@ -0,0 +1,227 @@
+# Date Picker — Benchmark Spec
+
+**Harvested from**: Material 3, Carbon Design System, Atlassian Design System, Mantine DatePicker
+**Wave**: 5 · **Category**: Advanced
+**Spec file**: `reference/components/date-picker.md`
+
+---
+
+## Purpose
+
+A Date Picker lets users select a single date or a date range through a calendar popover attached to a text input. It combines a formatted text field (for direct keyboard entry) with a visual month grid (for pointer or keyboard navigation). Use Date Picker when the date is human-meaningful and users may want to browse relative to a calendar context. Use a plain `<input type="date">` when native behavior is sufficient or a mobile-first audience is expected. *(Material 3, Carbon, Atlassian, Mantine agree: calendar popover + text input pairing is the canonical desktop pattern.)*
+
+---
+
+## Anatomy
+
+```
+[ Input field "MM/DD/YYYY" ] [ Calendar icon button ]
+         │
+         └── Popover (role="dialog", aria-modal="true")
+               ├── Header: [ ← ] [ Month Year ] [ → ]
+               ├── Day-of-week row (aria-hidden="true")
+               └── Month grid (role="grid")
+                     └── Week rows (role="row")
+                           └── Day cells (role="gridcell")
+                                 └── Day button (role="button")
+
+Range variant adds a second input field for end date.
+```
+
+| Part | Required | Notes |
+|------|----------|-------|
+| Text input | Yes | Shows selected date; accepts direct keyboard entry |
+| Format hint label | Yes | Visible "MM/DD/YYYY" supplement — NOT placeholder only |
+| Calendar trigger button | Yes | Opens/closes popover; `aria-label="Open calendar"` |
+| Popover (dialog) | Yes | `role="dialog"` + `aria-modal="true"` + focus trap |
+| Month navigation | Yes | Previous/next month buttons; keyboard Page Up/Down |
+| Month grid | Yes | `role="grid"` |
+| Day cell | Yes | `role="gridcell"` containing `role="button"` for selectable days |
+| Range highlight | No (range variant only) | Visual fill between start and end dates |
+
+---
+
+## Variants
+
+| Variant | Description | Systems |
+|---------|-------------|---------|
+| Single date | One input + calendar popover | Material 3, Carbon, Atlassian, Mantine |
+| Date range | Start + end input pair sharing one calendar | Carbon (DateRangePicker), Mantine (DateRangePicker), Atlassian |
+| Date-time | Date selection + time selector panel | Material 3 (DateTimePicker), Mantine |
+| Inline calendar | Calendar always visible, no popover | Mantine (Calendar), Material 3 (docked) |
+
+**Norm** (≥3/4 systems agree): popover calendar attached to a text input is the dominant pattern; range uses two inputs sharing one calendar panel.
+**Diverge**: Material 3 uses a modal dialog for mobile; Carbon and Mantine use an anchored popover for all viewports.
+
+---
+
+## States
+
+| State | Trigger | Visual | ARIA |
+|-------|---------|--------|------|
+| default | — | Resting input + trigger icon | — |
+| open | Trigger click or input focus + Enter | Popover visible, focus moves inside | `aria-expanded="true"` on trigger |
+| day hover | Pointer over day | Background highlight | — |
+| day focus | Keyboard navigation | Focus-visible ring on day button | — |
+| day selected | Enter/Space or click | Filled background (brand color) | `aria-pressed="true"` on day button |
+| range-in-progress | Start selected, end not yet | Partial fill from start | — |
+| range-complete | Both start and end selected | Full highlight between dates | — |
+| disabled date | Date excluded by min/max/filter | Muted; `tabindex="-1"` | `aria-disabled="true"` on day button |
+| error | Invalid date typed | Red border + error message | `aria-invalid="true"` on input |
+
+---
+
+## Sizing & Spacing
+
+| Size | Input Height | Popover Width | Day Cell Size | Font |
+|------|-------------|---------------|---------------|------|
+| sm | 32px | 256px | 32px | 13px |
+| md (default) | 40px | 288px | 40px | 14px |
+| lg | 48px | 320px | 44px | 16px |
+
+**Norm**: 288px popover width fits a standard 7-column month grid with comfortable padding *(Carbon, Mantine)*.
+Day cells must be ≥32px to meet minimum touch-target guidance; prefer 40px for mixed pointer/touch contexts.
+
+Cross-link: `reference/surfaces.md` — minimum 44×44px accessible tap target via padding.
+
+---
+
+## Typography
+
+- Input text: body-md weight 400; monospace or tabular-nums variant for date digits aids alignment
+- Day numbers: body-sm, center-aligned within cell
+- Month/year header: body-md weight 600
+- Format hint ("MM/DD/YYYY"): caption-sm, secondary color — attached as visible `<label>` supplement or `<span aria-hidden="true">` paired with `aria-describedby` on the input
+
+Cross-link: `reference/typography.md` — tabular-nums for date/time fields.
+
+---
+
+## Keyboard & Accessibility
+
+> **WAI-ARIA role**: `dialog` (popover), `grid` (month table), `button` (day cells)
+> **Required attributes**: `role="dialog"` + `aria-modal="true"` + `aria-label="Choose date"` on popover; `role="grid"` on month table; `role="gridcell"` + `role="button"` on each day
+
+### Keyboard Contract
+
+*Adapted from WAI-ARIA APG — https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/ and grid pattern — W3C — 2024*
+
+| Key | Action |
+|-----|--------|
+| Enter / Space | Open calendar when focus is on trigger; select focused day |
+| Arrow Left / Right | Move focus to previous / next day |
+| Arrow Up / Down | Move focus to same day in previous / next week |
+| Page Up | Navigate to previous month |
+| Page Down | Navigate to next month |
+| Ctrl + Page Up | Navigate to previous year |
+| Ctrl + Page Down | Navigate to next year |
+| Home | Move focus to first day of current week |
+| End | Move focus to last day of current week |
+| Escape | Close calendar popover; return focus to trigger button |
+| Tab | Move focus through interactive elements inside popover |
+
+### Accessibility Rules
+
+- Calendar popover MUST use `role="dialog"` + `aria-modal="true"` — do not use a plain `<div>` overlay
+- Focus MUST be trapped inside the open calendar; Escape closes and returns focus to the trigger
+- Each selectable day MUST be a `<button>` (or element with `role="button"`) so keyboard and AT users can activate it
+- Date format hint MUST be visible text, not only a placeholder (placeholder disappears on input and is not consistently announced)
+- Disabled dates MUST use `aria-disabled="true"` and `tabindex="-1"` so they are skipped but still communicated to AT
+- Range variant: announce selected range via `aria-label` on day buttons (e.g., `aria-label="April 15, 2025, start of range"`)
+- Mobile: provide native `<input type="date">` fallback when touch device detected or user preference set
+
+Cross-link: `reference/accessibility.md` — focus-trap pattern, dialog role requirements.
+
+---
+
+## Motion
+
+| Transition | Duration | Easing | Notes |
+|------------|----------|--------|-------|
+| Popover open | 150ms | ease-out | Fade + subtle scale from trigger |
+| Popover close | 100ms | ease-in | Fade out |
+| Month change | 200ms | ease-in-out | Slide left/right or cross-fade |
+| Day selection | 80ms | ease-out | Fill background color |
+| Range fill | 150ms | ease-out | Animate fill between dates |
+
+**BAN**: Do not animate the calendar grid with a full-page slide — disorienting for keyboard users navigating by month.
+
+Cross-link: `reference/motion.md` — reduced-motion: omit slide, keep instant day selection.
+
+---
+
+## Do / Don't
+
+### Do
+- Show the date format as visible text ("MM/DD/YYYY") near the input *(Carbon, Atlassian)*
+- Ensure keyboard users can navigate the entire calendar without a pointer *(WAI-ARIA APG)*
+- Allow direct text entry in the input field — some users know the date and do not need the calendar *(Mantine, Carbon)*
+- Support locale-aware first day of week (Sunday vs. Monday) and locale month/day names *(Material 3, Mantine)*
+
+### Don't
+- Don't use `<table>` with click-only cells — add `role="grid"` and full keyboard navigation *(WCAG 2.1 §2.1.1)*
+- Don't use placeholder text alone to convey the date format — placeholder vanishes on input *(Carbon, Atlassian)*
+- Don't trap focus permanently — Escape must always close the popover and restore focus *(WAI-ARIA APG)*
+- Don't omit the native `<input type="date">` for mobile — custom calendars are unusable on small touch screens *(Material 3)*
+
+---
+
+## Anti-patterns Cross-links
+
+| Anti-pattern | Entry |
+|--------------|-------|
+| BAN-07 | Placeholder as only label/hint — `reference/anti-patterns.md#ban-07` |
+| BAN-12 | Custom overlay without focus trap — `reference/anti-patterns.md#ban-12` |
+
+---
+
+## Benchmark Citations
+
+| Claim | Sources |
+|-------|---------|
+| Popover uses role="dialog" + aria-modal | WAI-ARIA APG dialog pattern, Carbon, Atlassian |
+| Month grid uses role="grid" | WAI-ARIA APG grid pattern, Mantine docs |
+| Arrow keys navigate days; Page Up/Down change month | WAI-ARIA APG, Carbon DatePicker keyboard docs |
+| Format hint must be visible text, not only placeholder | Carbon, Atlassian design guidelines |
+| Native input fallback for mobile | Material 3, Mantine (mobile prop) |
+
+Full system URLs: `connections/design-corpora.md`
+
+---
+
+## Grep Signatures
+
+```bash
+# Calendar popover missing role="dialog" (uses plain div overlay)
+grep -rn 'calendar\|datepicker\|date-picker' src/ | grep -v 'role="dialog"'
+
+# Day buttons missing keyboard handler (click-only calendar)
+grep -rn 'role="gridcell"\|\.day\|\.calendar-day' src/ | grep -v 'onKeyDown\|on:keydown\|handleKey'
+
+# Date input using placeholder for format hint only (no visible label supplement)
+grep -rn '<input.*type="text".*date\|DateInput' src/ | grep 'placeholder.*MM\|placeholder.*dd' | grep -v 'aria-describedby\|<label\|hint'
+
+# Missing aria-modal on calendar popover
+grep -rn 'role="dialog"' src/ | grep -v 'aria-modal'
+```
+
+---
+
+## Failing Example
+
+```html
+<!-- BAD: calendar using <table> with click-only day cells, no keyboard navigation -->
+<table class="calendar">
+  <tbody>
+    <tr>
+      <td class="day" onclick="selectDate('2025-04-01')">1</td>
+      <td class="day" onclick="selectDate('2025-04-02')">2</td>
+      <!-- ... -->
+    </tr>
+  </tbody>
+</table>
+```
+
+**Why it fails**: `<td>` cells are not focusable by default; no keyboard navigation; AT users cannot select dates; no `role="grid"` or `role="gridcell"`; click handler is the only interaction path.
+**Grep detection**: `grep -rn '<table.*calendar\|<td.*onclick.*date\|<td.*selectDate' src/`
+**Fix**: Replace with `<table role="grid">`, `<td role="gridcell">`, `<button>` inside each cell, and full Arrow/Page/Home/End keyboard handlers. Add `role="dialog"` + `aria-modal="true"` + focus trap on the popover wrapper.

package/reference/components/drawer.md

@@ -0,0 +1,201 @@
+# Drawer / Sheet — Benchmark Spec
+
+**Harvested from**: Material 3, Polaris (Sheet), Carbon, Atlassian, Mantine, shadcn/ui, Headless UI, Apple HIG
+**Wave**: 2 · **Category**: Containers
+
+---
+
+## Purpose
+
+A drawer (or sheet) is a panel that slides in from an edge of the viewport. It is less disruptive than a modal for workflows that benefit from co-existing with the background — detail panels, navigation menus, filter sidebars, multi-step flows. Like a modal, it traps focus and requires Escape to close. Unlike a modal, the backdrop is optional and can be semi-transparent. *(Material 3, Carbon, Polaris all position drawer as less disruptive than modal)*
+
+---
+
+## Anatomy
+
+```
+Side drawer (right):
+┌────────────────┬──────────────┐
+│                │ [✕] Title    │
+│   Page         │──────────────│
+│   content      │  Body        │
+│   (inert)      │  content     │
+│                │──────────────│
+│                │  [Actions]   │
+└────────────────┴──────────────┘
+
+Bottom sheet (mobile):
+┌──────────────────────────────┐
+│   Page content               │
+├──────────────────────────────┤  ← handle / drag indicator
+│   Sheet content              │  ← slides up; partial height
+└──────────────────────────────┘
+```
+
+| Part | Required | Notes |
+|------|----------|-------|
+| Panel container | Yes | `role="dialog"` + `aria-modal="true"` |
+| Title | Yes | `id` → `aria-labelledby` on panel |
+| Close button | Yes | Top-right; keyboard accessible |
+| Backdrop | Conditional | Semi-transparent; may click-to-close (configurable) |
+| Drag handle | No | Bottom sheet only; swipe gesture affordance |
+| Scroll container | Conditional | Body scrollable when content exceeds height |
+
+---
+
+## Variants
+
+| Variant | Direction | Use case | Systems |
+|---------|-----------|----------|---------|
+| Right side | Slides from right | Detail panels, settings | All |
+| Left side | Slides from left | Navigation menus | Material 3, Carbon |
+| Bottom sheet | Slides from bottom | Mobile actions, filters | Material 3, Apple HIG |
+| Top | Slides from top | Notifications, alerts | Rare; avoid |
+| Full-height | 100vh, pushes content | Persistent navigation | Material 3 |
+| Partial height | 60–80vh, overlays | Mobile bottom sheet | Apple HIG, Material 3 |
+
+**Norm** (≥5/18): right-side is default; bottom sheet for mobile.
+**Diverge**: backdrop-click-to-close — same debate as modal; for navigation drawers, backdrop click should close; for form/detail drawers, configurable.
+
+---
+
+## States
+
+Same as Modal/Dialog — see `modal-dialog.md`. Key differences:
+
+| State | Drawer-specific |
+|-------|-----------------|
+| open | Slides in from edge; `aria-expanded="true"` on trigger (nav drawer) |
+| closed | Slides out; `aria-expanded="false"` |
+| partial (bottom sheet) | Dragged to partial height; swipe-up to expand |
+
+---
+
+## Sizing & Spacing
+
+| Variant | Width / Height | Notes |
+|---------|---------------|-------|
+| Right side | 400–480px (desktop), 100% (mobile) | `min-width: 280px` |
+| Left side (nav) | 240–320px | 256px is common (Carbon, Material 3) |
+| Bottom sheet | 60–100vh | Drag handle at 12px × 36px |
+| Padding | 20–24px | Match modal padding |
+
+Cross-link: `reference/surfaces.md` — shadow on drawer edge (unilateral shadow)
+
+---
+
+## Typography
+
+- Title: 16–18px/600
+- Body: 14px/400
+- Section headers within body: 12px/600 uppercase muted
+
+---
+
+## Keyboard & Accessibility
+
+> **WAI-ARIA role**: `dialog` (same as modal — drawer is a type of dialog)
+> **Required attributes**: `aria-modal="true"`, `aria-labelledby` (title id)
+
+### Keyboard Contract
+
+*Quoted verbatim from WAI-ARIA APG — https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/ — W3C — 2024*
+
+Same Tab/Shift+Tab/Escape contract as modal (see `modal-dialog.md`).
+
+### Drawer-specific Accessibility Rules
+
+- Focus trap: MUST trap focus inside the drawer while open — same as modal
+- On open: focus moves to first focusable element (or close button if no primary action)
+- On close: focus MUST return to the element that triggered the drawer open
+- Navigation drawer (`role="navigation"`): if the drawer IS the main nav, use `role="navigation"` + `aria-label="Main"` instead of `role="dialog"`; different keyboard contract (no focus trap — it IS a landmark)
+- Background `inert`: set `inert` attribute (or equivalent) on background content when drawer is open
+
+---
+
+## Motion
+
+| Transition | Duration | Easing | Notes |
+|------------|----------|--------|-------|
+| Slide in (right) | 250ms | ease-out (cubic-bezier 0.4,0,0.2,1) | |
+| Slide out (right) | 200ms | ease-in | |
+| Bottom sheet expand | 300ms | spring (bounce: 0) | |
+| Backdrop fade | 200ms | ease | opacity 0→0.4 |
+
+Swipe-to-close (bottom sheet): detect `pointerup` with velocity + displacement threshold.
+Cross-link: `reference/motion.md` — spring bounce=0, `prefers-reduced-motion` (disable slide, instant toggle)
+
+---
+
+## Do / Don't
+
+### Do
+- Trap focus inside the drawer when open — same rule as modal *(WAI-ARIA APG)*
+- Return focus to the trigger element on close *(WAI-ARIA APG, Radix, Mantine)*
+- Use right-side drawer for content-detail panels; left-side for navigation *(Material 3, Carbon)*
+- Support swipe-to-close on bottom sheets for mobile *(Apple HIG, Material 3)*
+
+### Don't
+- Don't use `role="navigation"` for content drawers — only for navigation-purpose drawers *(WAI-ARIA APG)*
+- Don't let Tab escape the drawer while it's open *(WAI-ARIA APG)*
+- Don't disable background scroll without setting `overflow:hidden` on body *(all systems)*
+- Don't slide from top for content — top drawers conflict with browser UI and notifications *(Material 3)*
+
+---
+
+## Anti-patterns Cross-links
+
+| Anti-pattern | Entry |
+|--------------|-------|
+| Focus escaping drawer | `reference/anti-patterns.md` |
+| No focus return on close | `reference/anti-patterns.md` |
+
+---
+
+## Benchmark Citations
+
+| Claim | Sources |
+|-------|---------|
+| role="dialog" for content drawers | WAI-ARIA APG, Radix |
+| Focus trap required | WAI-ARIA APG |
+| Swipe-to-close on bottom sheet | Apple HIG, Material 3 |
+| 256px left nav width | Carbon, Material 3 |
+| ease-out 250ms slide-in | Material 3 motion spec |
+
+Full system URLs: `connections/design-corpora.md`
+
+---
+
+## Grep Signatures
+
+```bash
+# Drawer without focus trap
+grep -rn 'drawer\|sheet\|sidebar' src/ | grep -L 'FocusTrap\|focus-trap\|inert'
+
+# Drawer missing aria-modal
+grep -rn 'class.*drawer\|class.*sheet' src/ | grep 'role="dialog"' | grep -v 'aria-modal'
+
+# Background scroll not prevented
+grep -rn 'drawer.*open\|isOpen.*drawer' src/ | grep -v 'overflow\|body\.'
+```
+
+---
+
+## Failing Example
+
+```jsx
+// BAD: drawer panel with no focus management — Tab escapes to background
+function Drawer({ isOpen }) {
+  return isOpen ? (
+    <div className="drawer-panel">
+      <button onClick={close}>✕</button>
+      <h2>Settings</h2>
+      <SettingsForm />
+    </div>
+  ) : null;
+}
+```
+
+**Why it fails**: No `role="dialog"`, no `aria-modal`, no focus trap. Tab navigates freely into the background while the drawer is open. Escape does nothing.
+**Grep detection**: `grep -rn 'class.*drawer\|class.*panel' src/ | grep -v 'role=\|aria-modal'`
+**Fix**: Use Radix `<Dialog>` with `data-side` variant, or Vaul (drawer library), which handles focus trap, Escape, portal, and `aria-modal` automatically.