@hegemonart/get-design-done 1.16.0 → 1.19.0

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/file-upload.md

@@ -0,0 +1,219 @@
+# File Upload — Benchmark Spec
+
+**Harvested from**: Polaris (DropZone), Carbon (FileUploader), Atlassian Design System, Material 3
+**Wave**: 5 · **Category**: Advanced
+**Spec file**: `reference/components/file-upload.md`
+
+---
+
+## Purpose
+
+A File Upload component lets users attach one or more files by dragging them onto a drop zone or clicking to open the native file picker. It must work for all users: keyboard-only users activate the hidden-but-accessible `<input type="file">`, while pointer users can drag-drop. A file list tracks upload progress, status, and provides remove actions. *(Polaris, Carbon, Atlassian agree: drop zone + accessible file input + per-file status list is the canonical pattern.)*
+
+---
+
+## Anatomy
+
+```
+┌─────────────────────────────────┐
+│  Drop zone                      │
+│  [ Cloud icon ]                 │
+│  "Drag files here or"           │
+│  [ Browse files ] ← triggers    │
+│    <input type="file">          │
+└─────────────────────────────────┘
+
+File list (appears after selection):
+┌────────────────────────────────────────────────┐
+│ 📄 report.pdf  245 KB  [========   ] 80%  [✕] │
+│ 📄 photo.jpg   1.2 MB  ✓ Done             [✕] │
+│ 📄 data.csv    88 KB   ✗ Error            [✕] │
+└────────────────────────────────────────────────┘
+```
+
+| Part | Required | Notes |
+|------|----------|-------|
+| Drop zone container | Yes | Dashed border; drag-over changes fill + border color |
+| `<input type="file">` | Yes | MUST be accessible (not `display:none`) — keyboard fallback |
+| Browse trigger button | Yes | Visually activates the file input; must be a `<button>` or `<label>` |
+| File list | Yes (when files selected) | Per-file name, size, status, progress bar, remove button |
+| Progress bar | Yes (during upload) | `role="progressbar"` + `aria-valuenow` per file or overall |
+| Remove button | Yes | `aria-label="Remove [filename]"` |
+| Error region | Yes (on error) | `aria-live="assertive"` for upload errors |
+
+---
+
+## Variants
+
+| Variant | Description | Systems |
+|---------|-------------|---------|
+| Drop zone | Large dashed-border target area with drag-and-drop | Polaris, Carbon, Atlassian, Material 3 |
+| Compact / inline | Small "Attach file" button only; no large drop area | Carbon (FileUploaderItem), Atlassian |
+| Avatar/image uploader | Circular or rectangular crop zone for single image | Material 3, Polaris |
+| Multi-file | `multiple` attr; list of uploaded files | All systems |
+| Single-file | No `multiple`; replaces previous selection | Carbon, Polaris |
+
+**Norm** (≥3/4 systems agree): drop zone + browse button + file list is the standard desktop pattern; progress bar per file during upload.
+**Diverge**: Polaris auto-starts upload on drop; Carbon shows "Add files" button after initial selection to allow adding more; Material 3 defers to app logic.
+
+---
+
+## States
+
+| State | Trigger | Visual | ARIA |
+|-------|---------|--------|------|
+| default | — | Dashed border, instructional text | — |
+| drag-over | File dragged over zone | Filled background + solid border color change | `aria-dropeffect="copy"` (deprecated but still useful) |
+| drag-invalid | Wrong file type dragged over | Error border color; tooltip/message | — |
+| uploading | File being sent | Per-file progress bar animating | `aria-valuenow` on progressbar |
+| upload-done | Transfer complete | Check icon; status text "Done" | — |
+| upload-error | Transfer failed | Error icon; error message per file | `aria-live="assertive"` error region |
+| disabled | `disabled` prop | 38% opacity; drag events ignored | `aria-disabled="true"` on zone |
+
+---
+
+## Sizing & Spacing
+
+| Size | Drop Zone Min Height | Border Radius | Font |
+|------|---------------------|---------------|------|
+| sm | 80px | 4px | 13px |
+| md (default) | 128px | 8px | 14px |
+| lg | 200px | 12px | 16px |
+
+**Norm**: Drop zone should be large enough that it is comfortably hittable — 128px minimum height for default. File list rows are 48–56px tall for accessible remove-button target size *(Carbon, Polaris)*.
+
+Cross-link: `reference/surfaces.md` — minimum 44×44px touch targets for remove buttons.
+
+---
+
+## Typography
+
+- Drop zone instruction: body-md, centered, secondary color
+- "Browse files" link/button: body-md, primary link or button style
+- File name in list: body-sm, truncated with ellipsis (max-width on container), full name in `title` attribute
+- File size: caption-sm, secondary color
+- Status text (Done / Error): caption-sm, success or error semantic color
+
+Cross-link: `reference/typography.md` — truncation rules.
+
+---
+
+## Keyboard & Accessibility
+
+> **WAI-ARIA role**: `button` (browse trigger); `progressbar` (upload progress); `status` or `log` (file list updates)
+> **Required attributes**: `aria-label="Remove [filename]"` on remove buttons; `aria-valuenow` + `aria-valuemin` + `aria-valuemax` on progressbar; `aria-live="assertive"` on error region
+
+### Keyboard Contract
+
+*Derived from native `<input type="file">` behavior and WAI-ARIA APG button pattern — W3C — 2024*
+
+| Key | Action |
+|-----|--------|
+| Tab | Move focus to browse button / file input |
+| Enter / Space | Activate browse button — opens native file picker dialog |
+| Tab (in file list) | Move through file items and remove buttons |
+| Enter / Space (on remove button) | Remove file from list |
+
+Drag-and-drop is pointer-only; keyboard users MUST be able to complete the entire task via the file input alone.
+
+### Accessibility Rules
+
+- `<input type="file">` MUST NOT use `display:none` or `visibility:hidden` — use `opacity:0` positioned absolutely with dimensions matching the trigger, OR keep a visible file input alongside the drop zone
+- The browse trigger MUST be a `<button>` or `<label for="file-input">` so it is keyboard-focusable and activates the input
+- Remove buttons MUST have `aria-label="Remove [filename]"` — an icon-only ✕ with no accessible name fails AT users
+- Upload errors MUST be announced via `aria-live="assertive"` — do not rely solely on visual indicators
+- Progress bars MUST keep `aria-valuenow` updated throughout upload
+- `accept` attribute MUST match the visible allowed-types hint text so users are not surprised by rejection
+- File list additions/removals should be announced via `aria-live="polite"` on the list container
+
+Cross-link: `reference/accessibility.md` — aria-live regions, accessible file input patterns.
+
+---
+
+## Motion
+
+| Transition | Duration | Easing | Notes |
+|------------|----------|--------|-------|
+| Drop zone drag-over | 100ms | ease-out | Background fill + border color |
+| File list item enter | 200ms | ease-out | Slide-in from top or fade-in |
+| File list item remove | 150ms | ease-in | Fade + collapse height |
+| Progress bar fill | continuous | linear | Matches upload byte progress |
+| Upload complete tick | 200ms | ease-out | Check icon draw animation |
+
+**BAN**: Do not animate progress bar with CSS only at a fixed pace — progress MUST reflect actual upload percentage via `aria-valuenow`.
+
+Cross-link: `reference/motion.md` — reduced-motion: skip slide/collapse animations; keep progress bar updates.
+
+---
+
+## Do / Don't
+
+### Do
+- Keep `<input type="file">` accessible at all times (opacity:0 trick or visible) *(WAI-ARIA, Polaris, Carbon)*
+- Provide `aria-label="Remove [filename]"` on every remove button *(Carbon, Atlassian)*
+- Show file name, size, and status in the file list *(Polaris, Carbon, Atlassian)*
+- Announce upload errors via `aria-live="assertive"` *(WCAG 2.1 §4.1.3 Status Messages)*
+
+### Don't
+- Don't use `display:none` on the file input — keyboard and AT users cannot trigger the picker *(WCAG 2.1 §2.1.1)*
+- Don't omit the `accept` hint text — users should know allowed types before selecting *(Polaris, Carbon)*
+- Don't show only drag-drop UI with no browse button — drag is inaccessible to keyboard users *(Carbon, Atlassian)*
+- Don't use a generic `aria-label="Remove"` on remove buttons — AT users cannot identify which file *(Carbon)*
+
+---
+
+## Anti-patterns Cross-links
+
+| Anti-pattern | Entry |
+|--------------|-------|
+| BAN-08 | File input hidden with display:none — keyboard inaccessible — `reference/anti-patterns.md#ban-08` |
+| BAN-13 | Icon-only action button without aria-label — `reference/anti-patterns.md#ban-13` |
+
+---
+
+## Benchmark Citations
+
+| Claim | Sources |
+|-------|---------|
+| input type="file" must not be display:none | WCAG 2.1 §2.1.1, Carbon, Polaris accessibility guides |
+| Remove button needs aria-label="Remove [filename]" | Carbon FileUploader, Atlassian, Polaris |
+| Upload errors need aria-live="assertive" | WCAG 2.1 §4.1.3, Material 3 |
+| Progress bar needs aria-valuenow updates | WAI-ARIA progressbar role spec |
+| Drag-over state: background fill + border change | Polaris, Carbon, Atlassian drop zone specs |
+
+Full system URLs: `connections/design-corpora.md`
+
+---
+
+## Grep Signatures
+
+```bash
+# File input hidden with display:none (keyboard inaccessible)
+grep -rn 'type="file"' src/ | grep -v 'opacity\|position.*absolute' | grep 'display.*none\|visibility.*hidden'
+
+# Remove button missing aria-label (icon-only, no accessible name)
+grep -rn 'remove.*button\|btn.*remove\|✕\|×' src/ | grep -v 'aria-label'
+
+# Progress bar missing aria-valuenow
+grep -rn 'role="progressbar"' src/ | grep -v 'aria-valuenow'
+
+# Upload error region without aria-live
+grep -rn 'upload.*error\|file.*error\|error.*upload' src/ | grep -v 'aria-live'
+```
+
+---
+
+## Failing Example
+
+```html
+<!-- BAD: drop zone with display:none on the actual <input> — keyboard and AT users can't trigger file picker -->
+<div class="drop-zone" ondrop="handleDrop(event)" ondragover="handleDragOver(event)">
+  <p>Drag files here</p>
+  <input type="file" id="file-input" style="display:none" onchange="handleFiles(event)">
+  <button onclick="document.getElementById('file-input').click()">Browse</button>
+</div>
+```
+
+**Why it fails**: `display:none` removes the input from accessibility tree and tab order. The JavaScript `.click()` workaround does not work reliably with all AT. Keyboard users pressing Enter/Space on "Browse" may get inconsistent behavior across browsers. Screen reader users cannot discover or activate the file input directly.
+**Grep detection**: `grep -rn 'type="file".*display.*none\|display.*none.*type="file"' src/`
+**Fix**: Use `opacity:0; position:absolute; width:100%; height:100%` on the input (matching the browse button dimensions), or place a visible `<input type="file">` and style the button as a `<label for="file-input">` so clicking the label activates the input natively without JavaScript.

package/reference/components/list.md

@@ -0,0 +1,217 @@
+# List (Interactive & Display) — Benchmark Spec
+
+**Harvested from**: Carbon, Polaris, Material 3, Mantine, WAI-ARIA APG, UUPM (app-interface, MIT)
+**Wave**: 4 · **Category**: Navigation & Data
+
+---
+
+## Purpose
+
+A list component handles two distinct patterns: (1) a display list renders a series of items using semantic `<ul>/<ol>/<li>` HTML — no ARIA needed; (2) an interactive list (listbox) presents selectable options with keyboard navigation and selection state. Use a display list for content; use an interactive listbox when users choose one or more items from a set. *(Carbon, Polaris, Material 3 all define separate display and interactive list patterns)*
+
+---
+
+## Anatomy
+
+```
+Display list:              Interactive listbox:
+<ul>                       <div role="listbox"
+  <li>Item one</li>              aria-multiselectable="false"
+  <li>Item two</li>              aria-label="Assignees">
+  <li>Item three</li>       <div role="option"
+</ul>                              aria-selected="true">Alice</div>
+                             <div role="option"
+                                   aria-selected="false">Bob</div>
+                           </div>
+```
+
+| Part | Required | Notes |
+|------|----------|-------|
+| List container | Yes | `<ul>` / `<ol>` (display) or `role="listbox"` (interactive) |
+| List item | Yes | `<li>` (display) or `role="option"` (interactive) |
+| `aria-selected` | Interactive only | `true`/`false` on each `role="option"` |
+| `aria-multiselectable` | Interactive only | `true` if multi-select; default `false` |
+| `aria-label` / `aria-labelledby` | Interactive only | Describes the listbox purpose |
+| Empty state | No | Min 200px height; illustration + message + optional CTA |
+| Virtual scroll | Conditional | At > 100 items; TanStack Virtual or react-virtual |
+
+---
+
+## Variants
+
+| Variant | Description | Systems |
+|---------|-------------|---------|
+| Unordered display | `<ul>` bullet list; purely semantic | All systems |
+| Ordered display | `<ol>` numbered list; sequential content | All systems |
+| Single-select listbox | One item selectable at a time | Carbon, Polaris, Material 3 |
+| Multi-select listbox | Multiple items selectable (Shift+Click, Ctrl+Click) | Carbon, Material 3, Mantine |
+| List / detail panel | Left-panel list + right detail pane | UUPM app-interface (MIT) |
+| Recent-items list | Time-ordered recent items with timestamps | UUPM app-interface (MIT) |
+| Virtualized | Windowed rendering for large datasets (> 100 items) | Carbon, Mantine |
+
+**Norm** (≥4 systems agree): `role="listbox"` + `role="option"` for interactive; native `<ul>/<li>` for display.
+**Diverge**: Material 3 calls the interactive variant "ListItem with selectable state"; Carbon uses "ContentSwitcher" for small sets and "MultiSelect" for large. Pattern semantics are identical.
+
+---
+
+## States
+
+| State | Trigger | Visual | ARIA |
+|-------|---------|--------|------|
+| default | — | Items visible; none selected | `aria-selected="false"` on all options |
+| option-hover | pointer over | 8% overlay | — |
+| option-focus | keyboard focus | 2px focus-visible ring | managed via `tabindex` |
+| option-selected | click or Enter/Space | Filled highlight; checkmark for multi-select | `aria-selected="true"` |
+| option-disabled | disabled prop | 38% opacity; cursor: default | `aria-disabled="true"` |
+| empty | no items | Empty state (illustration + text + CTA) | `aria-label` on empty container |
+| loading | data fetch | Skeleton items | `aria-busy="true"` on listbox container |
+
+---
+
+## Sizing & Spacing
+
+| Element | Value | Notes |
+|---------|-------|-------|
+| Item height | 40px (default) | 32px compact; 48px comfortable |
+| Item padding H | 12–16px | Icon + 8px gap if icon present |
+| Empty state min-height | 200px | Prevents visually collapsed empty container |
+| Virtual viewport | ~400–600px | Clip height for virtualised scroll |
+| List max-height | 400px default | Scroll within list container |
+
+**Norm**: 40px item height (Carbon, Polaris, Mantine). Max-height + internal scroll for contained lists.
+
+---
+
+## Typography
+
+- Display list: inherits parent body text; `<li>` marker via `list-style-type`
+- Interactive option label: body-sm (13–14px), weight 400; selected weight 500
+- Secondary text / metadata: label-xs (11–12px), `color: --text-subtle`
+- Empty state heading: heading-sm, center-aligned
+- Empty state body: body-sm, `color: --text-subtle`
+
+Cross-link: `reference/typography.md` — body-sm, heading scale
+
+---
+
+## Keyboard & Accessibility
+
+> **WAI-ARIA role**: `listbox` (interactive container), `option` (each item)
+> **Required attributes**: `aria-selected` on each `role="option"`; `aria-label` or `aria-labelledby` on `role="listbox"`; `aria-multiselectable="true"` for multi-select
+
+### Keyboard Contract
+
+*Quoted verbatim from WAI-ARIA APG — https://www.w3.org/WAI/ARIA/apg/patterns/listbox/ — W3C — 2024*
+
+| Key | Action |
+|-----|--------|
+| ArrowDown | Moves focus to next option (wraps to first) |
+| ArrowUp | Moves focus to previous option (wraps to last) |
+| Home | Moves focus to first option |
+| End | Moves focus to last option |
+| Enter / Space | Selects the focused option (single-select) |
+| Shift+ArrowDown | Extends selection downward (multi-select) |
+| Shift+ArrowUp | Extends selection upward (multi-select) |
+| Ctrl+A | Selects all options (multi-select) |
+| A–Z | Moves focus to next option starting with typed character |
+
+### Accessibility Rules
+
+- Display lists use native `<ul>/<li>` — no ARIA roles needed; they are already accessible
+- Interactive lists MUST use `role="listbox"` + `role="option"` — not `<ul>/<li>` with click handlers
+- `aria-selected` MUST be present on every `role="option"` (either `true` or `false`)
+- Multi-select listbox MUST declare `aria-multiselectable="true"` on the container
+- Virtual scroll: all options in the virtualised window must have correct `aria-posinset` and `aria-setsize` attributes
+- Empty state container MUST have `aria-label` or `aria-live` so AT announces the empty state
+
+Cross-link: `reference/accessibility.md` — listbox pattern, virtual list accessibility
+
+---
+
+## Motion
+
+| Transition | Duration | Easing | Notes |
+|------------|----------|--------|-------|
+| Option selection highlight | 100ms | ease-out | Background color only |
+| Skeleton item shimmer | 1500ms | linear loop | Loading placeholder |
+| Empty state entry | 150ms | ease-out | Fade in |
+
+**BAN**: Do not animate item reordering unless using a deliberate drag-and-drop library — unsolicited reordering causes disorientation.
+
+Cross-link: `reference/motion.md` — skeleton shimmer, list animations
+
+---
+
+## Do / Don't
+
+### Do
+- Use native `<ul>/<ol>/<li>` for display-only lists — no ARIA needed *(WAI-ARIA APG)*
+- Use `role="listbox"` + `role="option"` for selectable lists *(WAI-ARIA APG, Carbon, Polaris)*
+- Virtualise at > 100 items to prevent DOM bloat *(Carbon, Mantine)*
+- Provide a meaningful empty state with a CTA when the list can be populated *(Polaris, Material 3)*
+
+### Don't
+- Don't use `<div onClick>` list items without `role="option"` — keyboard-inaccessible *(WCAG 2.1.1)*
+- Don't omit `aria-selected` on options — AT cannot determine what is selected *(WAI-ARIA APG)*
+- Don't use `<ul>/<li>` with `role="option"` — mixing native list semantics and listbox ARIA creates conflicts *(WAI-ARIA)*
+- Don't load all items at once when count > 100 — renders slowly and wastes memory *(Carbon, Mantine)*
+
+---
+
+## Anti-patterns Cross-links
+
+| Anti-pattern | Entry |
+|--------------|-------|
+| BAN-04 | `transition: all` on interactive elements — `reference/anti-patterns.md#ban-04` |
+
+---
+
+## Benchmark Citations
+
+| Claim | Sources |
+|-------|---------|
+| role="listbox" + role="option" for interactive lists | WAI-ARIA APG listbox pattern |
+| aria-selected required on every option | WAI-ARIA APG, Carbon, Polaris |
+| aria-multiselectable="true" for multi-select | WAI-ARIA APG |
+| Virtualise at > 100 items | Carbon, Mantine (TanStack Virtual) |
+| 200px min empty state height | Carbon, Polaris HIG |
+
+Full system URLs: `connections/design-corpora.md`
+
+---
+
+## Grep Signatures
+
+```bash
+# Interactive list items using <div> without role="option"
+grep -rn '<div' src/ | grep -i 'list.*item\|list-item\|listitem' | grep 'onClick\|on:click' | grep -v 'role='
+
+# Missing aria-selected on option elements
+grep -rn 'role="option"' src/ | grep -v 'aria-selected'
+
+# Listbox missing aria-label
+grep -rn 'role="listbox"' src/ | grep -v 'aria-label\|aria-labelledby'
+
+# <ul>/<li> used with role="option" (semantics conflict)
+grep -rn 'role="option"' src/ | grep '<li'
+```
+
+---
+
+## Failing Example
+
+```html
+<!-- BAD: interactive list items using <div onClick> with no keyboard support -->
+<div class="user-list">  <!-- no role="listbox" -->
+  <div class="list-item selected" onclick="selectUser('alice')">
+    Alice Chen
+  </div>
+  <div class="list-item" onclick="selectUser('bob')">
+    Bob Tanaka
+  </div>
+</div>
+```
+
+**Why it fails**: No `role="listbox"` on container; no `role="option"` on items; no `aria-selected`; items not keyboard-focusable (no `tabindex`); arrow-key navigation does nothing; screen readers see two unlabelled `<div>` elements.
+**Grep detection**: `grep -rn '<div.*onClick\|<div.*on:click' src/ | grep -i 'list.*item\|listitem'`
+**Fix**: Use `<div role="listbox" aria-label="Users">` with `<div role="option" tabindex="-1" aria-selected="false">` items; implement roving `tabindex` and arrow-key handlers.