@hegemonart/get-design-done 1.16.0 → 1.18.0

package/reference/components/chip.md

@@ -0,0 +1,209 @@
+# Chip / Tag — Benchmark Spec
+
+**Harvested from**: Material 3, Carbon, Atlassian, Mantine
+**Wave**: 3 · **Category**: Feedback
+
+---
+
+## Purpose
+
+A chip (or tag) is a compact, interactive label that represents an attribute, filter, or selection. It is commonly used for multi-select filter interfaces, tag-input fields (user-generated labels), one-time suggestion prompts, and static display labels. Each variant has distinct interaction semantics — filter chips toggle on/off, input chips are removable, suggestion chips trigger a one-time action, and display chips are static. *(Material 3, Carbon, Atlassian, Mantine agree on the four-variant taxonomy)*
+
+*UUPM app-interface: filter chips in search/filter UIs and tag input patterns (MIT attribution)*
+
+---
+
+## Anatomy
+
+```
+┌───────────────────────────────┐
+│ [icon?]  Label text  [✕ remove?] │
+└───────────────────────────────┘
+↑ role varies by variant
+↑ touch target ≥ 32px height
+```
+
+| Part | Required | Notes |
+|------|----------|-------|
+| Label text | Yes | Concise (1–3 words typical) |
+| Container | Yes | Interactive element; role/type depends on variant |
+| Leading icon | No | 16px; left-aligned; 8px gap to label |
+| Remove button | Conditional | Required on input/tag chips; independent focusable element |
+| Selected state indicator | Conditional | Checkmark or filled style on toggled filter chips |
+
+---
+
+## Variants
+
+| Variant | Interaction | Role | Systems |
+|---------|-------------|------|---------|
+| Filter | Toggleable; multi-select | `aria-pressed` or `role="option"` in `role="listbox"` | Material 3, Carbon, Atlassian, Mantine |
+| Input / Tag | User-generated; removable via × button | `role="option"` in combobox; or `role="listbox"` child | Material 3, Atlassian, Mantine |
+| Suggestion | One-time select; fires an action then typically disappears | `role="button"` | Material 3, Mantine |
+| Display | Static label; no interaction | No role needed (or `role="listitem"`) | Atlassian (Lozenge), Carbon (Tag), Mantine |
+
+**Norm** (≥4/18 systems agree): filter chip uses `aria-pressed` for standalone toggles; input chip requires independent remove button with its own `aria-label`; display chip is decorative/static.
+**Diverge**: Material 3 calls static chips "Suggestion chips" when one-time-action and "Assist chips" for shortcut actions; Atlassian separates "Tag" (removable) from "Lozenge" (static status label); Carbon calls them "Tag" uniformly with a `filter` prop.
+
+---
+
+## States
+
+| State | Trigger | Visual | ARIA |
+|-------|---------|--------|------|
+| default | — | Rest fill + label | — |
+| hover | pointer over chip | Background tint (+8%) | — |
+| focus | keyboard focus on chip | focus-visible ring (2px) | — |
+| selected (filter) | click / Enter / Space | Filled background; checkmark icon | `aria-pressed="true"` |
+| unselected (filter) | click / Enter / Space | Outline style | `aria-pressed="false"` |
+| disabled | `disabled` / `aria-disabled` | 38% opacity; cursor not-allowed | `aria-disabled="true"` |
+| remove focus | Tab to × button | Focus ring on × | — |
+
+---
+
+## Sizing & Spacing
+
+| Property | Value | Notes |
+|----------|-------|-------|
+| Height | 32px (min touch target) | Do not reduce below 32px |
+| Padding-x | 12px | Each side; 8px when leading icon present |
+| Gap (icon → label) | 8px | |
+| Gap (label → remove ×) | 4px | |
+| Remove button size | 20×20px (visual); 32×32px (touch) | Extend touch area with padding |
+| Border radius | 16–20px (full pill) | *(Material 3: full-radius pill; Carbon: 4px; Atlassian: 2px)* |
+| Font size | 13–14px / 400 | |
+
+**Norm**: pill shape (full-radius) for filter and input chips *(Material 3, Mantine)*; Touch target ≥ 32px height *(WCAG 2.5.5, Material 3)*.
+
+---
+
+## Typography
+
+- Label: body-sm (13–14px/400) — same scale as form labels
+- No bold weight — chip label is a tag, not a heading or CTA
+- Truncate with ellipsis only when chip is in a fixed-width container; prefer wrapping chip set to natural width
+
+Cross-link: `reference/typography.md` — body-sm definition
+
+---
+
+## Keyboard & Accessibility
+
+> **WAI-ARIA role**: `button` (filter standalone, suggestion); `option` inside `listbox` (filter group, input chips)
+> **Required attributes**: `aria-pressed` on standalone filter chip; `aria-label` on remove button; `aria-selected` if `role="option"`
+
+### Keyboard Contract
+
+*Quoted verbatim from WAI-ARIA APG — https://www.w3.org/WAI/ARIA/apg/patterns/listbox/ — W3C — 2024*
+
+| Key | Action |
+|-----|--------|
+| Tab | Moves focus to the chip or to the remove (×) button |
+| Enter / Space | Toggles filter chip (pressed/unpressed); activates suggestion chip |
+| Delete / Backspace | Removes an input/tag chip (when chip or its remove button has focus) |
+| Arrow Left / Right | Navigates between chips when inside a `role="listbox"` group |
+| Escape | Collapses chip group if it was expanded (e.g. overflow +N pattern) |
+
+### Accessibility Rules
+
+- Filter chip used as standalone toggle MUST have `aria-pressed="true|false"` — absence means screen readers cannot report toggle state *(WAI-ARIA APG)*
+- Filter chips inside a multi-select group SHOULD use `role="option"` inside `role="listbox"` with `aria-multiselectable="true"` *(WAI-ARIA APG)*
+- Remove button MUST have an independent `aria-label` describing what it removes: `aria-label="Remove Python tag"` — the × glyph alone is not an accessible name *(WAI-ARIA APG, Material 3)*
+- Remove button MUST be a separate focusable element, NOT a click handler on the chip label *(Carbon, Atlassian)*
+- Touch target for remove button MUST be ≥ 32×32px via padding even if the visual × is 16–20px *(WCAG 2.5.5)*
+- Display chips have no role — they are presentational; if they carry meaningful status, use `role="status"` or integrate into an Alert *(Atlassian Lozenge guidance)*
+
+Cross-link: `reference/accessibility.md` — `aria-pressed`, `listbox`, touch targets
+
+---
+
+## Motion
+
+| Transition | Duration | Easing | Notes |
+|------------|----------|--------|-------|
+| Toggle selected (background fill) | 100ms | ease-out | Background + checkmark appear |
+| Chip remove (collapse width) | 150ms | ease-in | Width collapses to 0, siblings shift |
+| Chip add (expand width) | 150ms | ease-out | Width expands from 0 |
+| Hover background | 80ms | ease-out | Subtle tint only |
+
+**BAN**: Full-page reflow animation when removing a chip — collapse width inline; do not shift unrelated page sections. Do not use `transition: all` (catches unintended border/shadow changes).
+
+Cross-link: `reference/motion.md` — `prefers-reduced-motion`: skip width animation, instant add/remove
+
+---
+
+## Do / Don't
+
+### Do
+- Add `aria-pressed` to standalone filter chips *(WAI-ARIA APG)*
+- Give remove buttons an independent `aria-label`: "Remove [label] tag" *(WAI-ARIA APG, Material 3)*
+- Use `role="listbox"` + `role="option"` for multi-select filter chip groups *(WAI-ARIA APG)*
+- Ensure touch target ≥ 32px height; extend remove button via padding *(WCAG 2.5.5)*
+
+### Don't
+- Don't put filter chips without `aria-pressed` — screen readers cannot report selected state *(WAI-ARIA APG)*
+- Don't use the same click handler for chip label and remove — remove must be independently focusable *(Carbon, Atlassian)*
+- Don't truncate chip label in narrow containers without a tooltip — truncated tags lose meaning *(Polaris, Mantine)*
+- Don't use display chips for dynamic statuses that change — use Alert or Badge instead *(Atlassian)*
+
+---
+
+## Anti-patterns Cross-links
+
+| Anti-pattern | Entry |
+|--------------|-------|
+| Filter chip without aria-pressed | `reference/anti-patterns.md#ban-aria-pressed` |
+| Remove button without aria-label | `reference/anti-patterns.md#ban-aria-label` |
+
+---
+
+## Benchmark Citations
+
+| Claim | Sources |
+|-------|---------|
+| aria-pressed on standalone filter chip | WAI-ARIA APG, Material 3, Carbon |
+| Remove button independent aria-label | WAI-ARIA APG, Material 3, Atlassian |
+| role="option" inside role="listbox" for group | WAI-ARIA APG |
+| Touch target ≥ 32px height | WCAG 2.5.5, Material 3 |
+| Delete/Backspace removes input chip | Material 3, Atlassian, Mantine |
+| UUPM filter/tag-input patterns | UUPM app-interface (MIT) |
+
+Full system URLs: `connections/design-corpora.md`
+
+---
+
+## Grep Signatures
+
+```bash
+# Filter chip missing aria-pressed
+grep -rn 'chip\|Chip\|filter-tag\|filterChip' src/ | grep -i 'filter\|toggle' | grep -v 'aria-pressed'
+
+# Remove button on chip missing aria-label
+grep -rn 'chip.*remove\|tag.*remove\|remove.*chip\|remove.*tag' src/ | grep -v 'aria-label'
+
+# Chip remove button without independent tab stop (not a separate button element)
+grep -rn 'chip\|tag' src/ | grep '×\|&times;\|✕\|close' | grep -v '<button\|role="button"'
+```
+
+---
+
+## Failing Example
+
+```html
+<!-- BAD: filter chip with no aria-pressed — screen readers cannot report toggle state -->
+<div class="chip chip--filter" onclick="toggleFilter(this)">
+  Python
+</div>
+```
+
+**Why it fails**: `<div>` is not keyboard reachable. No `aria-pressed` means screen readers cannot determine if the filter is active or inactive. No `role="button"` or `tabindex` so keyboard users skip it entirely. No focus-visible ring.
+**Grep detection**: `grep -rn 'chip--filter\|filterChip\|chip.*filter' src/ | grep -v 'aria-pressed'`
+**Fix**:
+```html
+<button class="chip chip--filter"
+        aria-pressed="false"
+        onclick="toggleFilter(this)">
+  Python
+</button>
+```
+Update `aria-pressed` to `"true"` when selected.

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.