@hegemonart/get-design-done 1.15.0 → 1.18.0

package/reference/components/rich-text-editor.md

@@ -0,0 +1,226 @@
+# Rich-Text Editor — Benchmark Spec
+
+**Harvested from**: Tiptap/ProseMirror, Lexical (Meta), Slate.js, Atlassian Fabric Editor
+**Wave**: 5 · **Category**: Advanced
+**Spec file**: `reference/components/rich-text-editor.md`
+
+---
+
+## Purpose
+
+A Rich-Text Editor (RTE) provides WYSIWYG content authoring with inline formatting (bold, italic, links), block-level elements (headings, lists, blockquotes), and optional advanced features (mentions, embeds, tables). It is appropriate for long-form content where plain `<textarea>` is insufficient and a full CMS-style document editor is overkill. *(Tiptap, Lexical, Atlassian agree: contenteditable + ProseMirror/Lexical model + explicit toolbar is the production-grade RTE pattern.)*
+
+---
+
+## Anatomy
+
+```
+┌── role="toolbar" aria-label="Text formatting" ──────────────────┐
+│ [B] [I] [U] [S] │ [H1][H2] │ [• List][1. List] │ [Link][Image] │
+└──────────────────────────────────────────────────────────────────┘
+┌── role="textbox" aria-multiline="true" aria-label="Post body" ──┐
+│                                                                  │
+│  Start typing here…  (placeholder via CSS ::before)             │
+│                                                                  │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+| Part | Required | Notes |
+|------|----------|-------|
+| Editable area | Yes | `contenteditable="true"` + `role="textbox"` + `aria-multiline="true"` |
+| Toolbar | Yes (for formatting) | `role="toolbar"` + `aria-label`; groups via `role="group"` |
+| Toolbar buttons | Yes | `role="button"`; toggle buttons add `aria-pressed` |
+| Placeholder | No | CSS `[data-placeholder]::before` — NOT HTML attribute |
+| Mention list | No | `role="listbox"` floating suggestion list triggered by `@` |
+| Character count | No | `aria-live="polite"` updated region |
+| Read-only overlay | No | `contenteditable="false"` + `aria-readonly="true"` |
+
+---
+
+## Variants
+
+| Variant | Description | Systems |
+|---------|-------------|---------|
+| Minimal | Bold/italic/underline + link only | Tiptap (StarterKit minimal), Atlassian (inline comment) |
+| Standard | Full paragraph formatting + lists + links | Tiptap, Lexical, Slate |
+| Document | Full editor with headings, tables, embeds, mentions | Atlassian Fabric Editor, Tiptap (full), Lexical (full) |
+| Read-only | Rendered content; no editing | All systems |
+| Bubble toolbar | Formatting toolbar appears on text selection (tooltip style) | Tiptap, Atlassian inline editor |
+
+**Norm** (≥3/4 systems agree): toolbar at top or on selection; contenteditable with explicit role="textbox"; keyboard shortcuts for core formatting.
+**Diverge**: Atlassian uses a floating toolbar on selection; Tiptap supports both fixed and bubble modes; Lexical uses a plugin architecture; Slate treats everything as React tree nodes.
+
+---
+
+## States
+
+| State | Trigger | Visual | ARIA |
+|-------|---------|--------|------|
+| default | — | Cursor; toolbar buttons at rest | — |
+| focused | Click or Tab into editable area | Focus ring on editable container | — |
+| toolbar button active | Text with formatting selected | `aria-pressed="true"` on toggle button | `aria-pressed="true"` |
+| placeholder | No content in editable area | Placeholder text via CSS ::before | — |
+| read-only | `readOnly` prop | No cursor change; grayed toolbar | `aria-readonly="true"`, `contenteditable="false"` |
+| disabled | `disabled` prop | 38% opacity; no interaction | `aria-disabled="true"` |
+| mention-open | `@` typed | Floating listbox appears | `role="listbox"` visible |
+| error | Validation failure | Red border; error message below | `aria-describedby` → error message |
+
+---
+
+## Sizing & Spacing
+
+| Size | Min Height | Toolbar Height | Font |
+|------|-----------|----------------|------|
+| sm | 80px | 32px | 13px |
+| md (default) | 160px | 40px | 14px |
+| lg | 320px | 48px | 16px |
+
+**Norm**: Editor area grows with content (auto-height); enforce max-height with overflow scroll if needed. Toolbar buttons follow button-sm/md sizing with 8px gaps between groups *(Atlassian, Tiptap)*.
+
+Cross-link: `reference/surfaces.md` — toolbar button hit targets.
+
+---
+
+## Typography
+
+- Editor content: body-md, line-height 1.6 for readable long-form text
+- Heading 1: 2em; Heading 2: 1.5em; Heading 3: 1.25em — relative to editor base font
+- Code blocks: monospace, 0.9em, background token surface-code
+- Placeholder text: same size/font as body, secondary color via CSS
+
+Cross-link: `reference/typography.md` — heading scale, code font stack.
+
+---
+
+## Keyboard & Accessibility
+
+> **WAI-ARIA role**: `textbox` (editable area), `toolbar` (toolbar container), `group` (toolbar sections), `button` (toolbar actions), `listbox` (mention suggestions)
+> **Required attributes**: `role="textbox"` + `aria-multiline="true"` + `aria-label` or `aria-labelledby` on editable area; `aria-pressed` on toggle toolbar buttons; `role="toolbar"` + `aria-label` on toolbar
+
+### Keyboard Contract
+
+*Derived from WAI-ARIA APG toolbar pattern — https://www.w3.org/WAI/ARIA/apg/patterns/toolbar/ — W3C — 2024, and standard contenteditable browser behavior*
+
+| Key | Action |
+|-----|--------|
+| Tab | Move focus into the editable area from outside; move out of editor |
+| Ctrl/Cmd + B | Toggle bold on selected text |
+| Ctrl/Cmd + I | Toggle italic on selected text |
+| Ctrl/Cmd + U | Toggle underline on selected text |
+| Ctrl/Cmd + Z | Undo last action |
+| Ctrl/Cmd + Shift + Z | Redo |
+| Ctrl/Cmd + K | Insert or edit link |
+| @ (in editor) | Trigger mention suggestion list |
+| Arrow keys (in listbox) | Navigate mention suggestions |
+| Enter / Space (in listbox) | Select mention suggestion |
+| Escape (in listbox) | Dismiss mention list |
+| F10 or Alt + F10 | Move focus from editable area to toolbar (accessibility shortcut) |
+| Arrow keys (in toolbar) | Move between toolbar buttons (roving tabindex) |
+| Home / End (in toolbar) | First / last toolbar button |
+
+### Accessibility Rules
+
+- Editable area MUST have `role="textbox"` — bare `contenteditable` is announced as a generic region by most AT
+- `aria-multiline="true"` MUST be set — announces correct Enter-key behavior to screen readers
+- Toolbar toggle buttons (bold, italic, lists) MUST use `aria-pressed="true/false"` to reflect current selection state
+- Placeholder MUST use CSS `[data-placeholder]::before` content — not a `placeholder` HTML attribute on contenteditable (screen readers read it incorrectly or not at all)
+- Keyboard shortcuts MUST be documented in a tooltip or help section — not assumed
+- Read-only: set both `contenteditable="false"` AND `aria-readonly="true"` — contenteditable="false" alone is insufficient for AT
+- Mention listbox MUST use `role="listbox"` with `role="option"` items; focused option uses `aria-selected="true"`
+
+Cross-link: `reference/accessibility.md` — contenteditable accessibility, toolbar pattern.
+
+---
+
+## Motion
+
+| Transition | Duration | Easing | Notes |
+|------------|----------|--------|-------|
+| Toolbar button active state | 80ms | ease-out | Background fill on aria-pressed change |
+| Mention list open | 150ms | ease-out | Fade + slide up from caret position |
+| Mention list dismiss | 100ms | ease-in | Fade out |
+| Bubble toolbar appear | 150ms | ease-out | Fade in above selection |
+| Bubble toolbar dismiss | 80ms | ease-in | Fade out on deselect |
+
+**BAN**: Do not animate text reflow on formatting changes — typing performance is critical; any CSS transition on editor content causes visual jitter.
+
+Cross-link: `reference/motion.md` — reduced-motion: remove mention list slide; keep instant formatting toggle.
+
+---
+
+## Do / Don't
+
+### Do
+- Add `role="textbox"` + `aria-multiline="true"` to the contenteditable element *(WAI-ARIA APG)*
+- Use `aria-pressed` on all toggle toolbar buttons (bold, italic, list toggles) *(WAI-ARIA APG toolbar pattern)*
+- Implement placeholder via CSS `::before` pseudo-element, not HTML attribute *(Tiptap, Atlassian)*
+- Document keyboard shortcuts in a tooltip or accessible help dialog *(Atlassian Fabric Editor)*
+
+### Don't
+- Don't use bare `contenteditable` without `role="textbox"` — AT announces it as a generic landmark *(diverges from all 4 systems)*
+- Don't omit `aria-pressed` on toggle buttons — AT users cannot determine current formatting state *(WAI-ARIA APG)*
+- Don't use a `placeholder` HTML attribute on contenteditable — it is not a valid attribute and screen reader behavior is undefined *(MDN, Tiptap docs)*
+- Don't suppress `outline` on the editable area without a custom focus-visible ring *(WCAG 2.4.7)*
+
+---
+
+## Anti-patterns Cross-links
+
+| Anti-pattern | Entry |
+|--------------|-------|
+| BAN-06 | contenteditable without role="textbox" — `reference/anti-patterns.md#ban-06` |
+| BAN-04 | transition: all on editor content causing reflow jank — `reference/anti-patterns.md#ban-04` |
+
+---
+
+## Benchmark Citations
+
+| Claim | Sources |
+|-------|---------|
+| contenteditable needs role="textbox" + aria-multiline="true" | WAI-ARIA spec, Tiptap a11y guide, Atlassian |
+| Toolbar toggle buttons need aria-pressed | WAI-ARIA APG toolbar pattern |
+| Placeholder via CSS ::before, not HTML attribute | Tiptap docs, Atlassian Fabric Editor |
+| Mention list uses role="listbox" + role="option" | Tiptap mention extension, Lexical mention plugin |
+| Ctrl/Cmd+B/I/U keyboard shortcuts are standard | Lexical, Tiptap, Slate — all implement these |
+
+Full system URLs: `connections/design-corpora.md`
+
+---
+
+## Grep Signatures
+
+```bash
+# contenteditable element missing role="textbox" (announced as generic region)
+grep -rn 'contenteditable="true"' src/ | grep -v 'role="textbox"'
+
+# Toolbar toggle buttons missing aria-pressed
+grep -rn 'role="toolbar"' src/ -A 50 | grep 'role="button"' | grep -v 'aria-pressed'
+
+# Placeholder set as HTML attribute on contenteditable (invalid)
+grep -rn 'contenteditable' src/ | grep 'placeholder='
+
+# Mention listbox missing role="listbox"
+grep -rn 'mention\|@mention\|MentionList' src/ | grep -v 'role="listbox"'
+```
+
+---
+
+## Failing Example
+
+```html
+<!-- BAD: rich-text area using only contenteditable without role="textbox" -->
+<div
+  contenteditable="true"
+  class="editor"
+  placeholder="Start writing..."
+>
+</div>
+<div class="toolbar">
+  <button onclick="document.execCommand('bold')">B</button>
+  <button onclick="document.execCommand('italic')">I</button>
+</div>
+```
+
+**Why it fails**: (1) Bare `contenteditable` is announced by most AT as a generic region, not a text input — users do not know they can type. (2) `placeholder` is not a valid HTML attribute on `<div>` — screen readers do not announce it. (3) Toolbar buttons have no `aria-pressed` — AT cannot determine if bold/italic is currently active. (4) `document.execCommand` is deprecated.
+**Grep detection**: `grep -rn 'contenteditable="true"' src/ | grep -v 'role="textbox"'`
+**Fix**: Add `role="textbox"` + `aria-multiline="true"` + `aria-label="Post body"` to the editable div; implement placeholder via CSS `[data-empty]::before { content: attr(data-placeholder) }`; add `aria-pressed="true/false"` to toolbar toggle buttons; use a modern editor library (Tiptap, Lexical) instead of execCommand.

package/reference/components/select-combobox.md

@@ -0,0 +1,219 @@
+# Select / Combobox — Benchmark Spec
+
+**Harvested from**: Radix UI, WAI-ARIA APG, Carbon, Headless UI, Mantine, Material 3, Ant Design, shadcn/ui
+**Wave**: 1 · **Category**: Inputs
+
+---
+
+## Purpose
+
+A select allows the user to choose one (or multiple) options from a predefined list presented in a dropdown. A combobox extends this with a text filter input. Use native `<select>` when styling flexibility is not required and options are static; use a custom combobox when filtering, grouping, async loading, or complex option rendering is needed. *(Radix, Headless UI, WAI-ARIA APG agree on this decision tree)*
+
+---
+
+## Anatomy
+
+```
+Label *
+┌────────────────────────┬──┐
+│ Selected value         │ ▾│  ← trigger button (role="combobox" + aria-haspopup)
+└────────────────────────┴──┘
+  ┌──────────────────────────┐
+  │ [search input]           │  ← combobox only; role="textbox"
+  │──────────────────────────│
+  │ ○ Option A               │  ← role="option" in role="listbox"
+  │ ○ Option B               │
+  │ ○ Option C               │
+  └──────────────────────────┘
+```
+
+| Part | Required | Notes |
+|------|----------|-------|
+| Label | Yes | `<label>` or `aria-label` on trigger |
+| Trigger button | Yes | Announces selected value; opens dropdown on Enter/Space |
+| Dropdown list | Yes | `role="listbox"` container |
+| Option items | Yes | `role="option"` with `aria-selected` |
+| Filter input | No | Combobox only; `role="combobox"` with `aria-controls` |
+| Group headings | No | `role="group"` with `aria-label` |
+| Empty state | Conditional | Required when async/filter can return zero results |
+| Clear button | No | Clears selection; keyboard accessible |
+
+---
+
+## Variants
+
+| Variant | Description | Systems |
+|---------|-------------|---------|
+| Native select | `<select>` — minimal, accessible, no custom styling | All (as baseline) |
+| Custom select | Styled trigger + listbox; no filter | Radix, Carbon, shadcn |
+| Combobox | Trigger + text filter + listbox | Radix, Mantine, Headless UI, Ant |
+| Multi-select | Multiple `aria-selected="true"` options; tag display | Mantine, Ant, Carbon |
+| Async / searchable | Options loaded on query; loading state in listbox | Mantine, Ant, shadcn |
+
+**Norm** (≥5/18): custom select must replicate native keyboard behavior exactly.
+**Diverge**: tag vs. chip display for multi-select — Mantine uses tags, Ant uses chips, Carbon uses checkboxes in dropdown. Checkbox approach is most accessible (state is visible without removing focus from listbox).
+
+---
+
+## States
+
+| State | Trigger | Visual | ARIA |
+|-------|---------|--------|------|
+| default | — | Resting trigger | `aria-expanded="false"` |
+| open | trigger activated | Dropdown visible | `aria-expanded="true"` |
+| option hovered | pointer | Option highlighted | `aria-activedescendant` updated |
+| option selected | Enter / click | Checkmark or filled circle | `aria-selected="true"` |
+| disabled | `disabled` attr | 38% opacity; pointer-events: none | `aria-disabled="true"` |
+| error | validation | Red border + error message | `aria-invalid="true"` |
+| loading | async fetch | Spinner inside listbox | `aria-busy="true"` on listbox |
+| empty | filter = zero results | "No results" message in listbox | `aria-live="polite"` |
+
+---
+
+## Sizing & Spacing
+
+| Size | Trigger height | Option height | Padding H |
+|------|---------------|---------------|-----------|
+| sm | 32px | 28px | 12px |
+| md (default) | 40px | 36px | 16px |
+| lg | 48px | 44px | 16px |
+
+Max dropdown height: 240px with internal scroll — prevents viewport overflow without pagination.
+Option min-height: 36px (md) for touch targets *(Material 3, Polaris)*
+
+---
+
+## Typography
+
+- Trigger value: same weight/size as input (14px/400)
+- Option text: 14px/400; selected option: 14px/500
+- Group label: 11px/600 uppercase, muted colour — not an option, not focusable
+
+---
+
+## Keyboard & Accessibility
+
+> **WAI-ARIA role**: `combobox` on trigger (select pattern); `listbox` on dropdown; `option` on items
+> **Required attributes**: `aria-expanded`, `aria-haspopup="listbox"`, `aria-controls` (trigger→listbox), `aria-activedescendant` (updated on option focus)
+
+### Keyboard Contract — Select (Listbox Pattern)
+
+*Quoted verbatim from WAI-ARIA APG — https://www.w3.org/WAI/ARIA/apg/patterns/listbox/ — W3C — 2024*
+
+| Key | Action |
+|-----|--------|
+| Enter / Space | Opens listbox when trigger is focused |
+| Escape | Closes listbox; returns focus to trigger |
+| Arrow Down | Opens listbox (if closed) or moves focus to next option |
+| Arrow Up | Opens listbox (if closed) or moves focus to previous option |
+| Home | Moves focus to first option |
+| End | Moves focus to last option |
+| Enter (option focused) | Selects option; closes listbox |
+| Tab | Closes listbox; moves focus to next element |
+| Printable character | (Type-ahead) Moves focus to next option starting with typed character |
+
+### Keyboard Contract — Combobox
+
+*Quoted verbatim from WAI-ARIA APG — https://www.w3.org/WAI/ARIA/apg/patterns/combobox/ — W3C — 2024*
+
+| Key | Action |
+|-----|--------|
+| Any printable character | Filters option list; opens popup |
+| Escape | Clears filter (if any); closes popup |
+| Arrow Down | Moves focus into listbox (first or previously focused option) |
+| Arrow Up | Moves focus to last option |
+| Enter | Selects focused option; closes popup |
+| Alt + Arrow Down | Opens popup without moving focus |
+| Alt + Arrow Up | Closes popup; returns focus to textbox |
+
+### Accessibility Rules
+
+- `aria-activedescendant` on trigger MUST update as options are highlighted — screen readers follow this, not DOM focus
+- Options must have unique `id` attributes (for `aria-activedescendant` reference)
+- Grouping: `role="group"` with `aria-label` wrapping grouped `role="option"` items
+- Empty state: announce via `aria-live="polite"` region when filter returns no results
+- Virtualised lists: keep rendered DOM options in sync with `aria-activedescendant` pointer
+
+---
+
+## Motion
+
+| Transition | Duration | Easing | Notes |
+|------------|----------|--------|-------|
+| Dropdown open | 120ms | ease-out | Scale 0.95→1 + fade; origin at trigger |
+| Dropdown close | 80ms | ease-in | Fade only |
+| Option highlight | 60ms | ease | Background colour only |
+
+Cross-link: `reference/motion.md` — `AnimatePresence` pattern for mount/unmount
+
+---
+
+## Do / Don't
+
+### Do
+- Replicate native `<select>` keyboard behavior exactly in custom implementations *(WAI-ARIA APG, Radix)*
+- Show a "No results" state (not empty dropdown) when filter has no matches *(Mantine, shadcn, Carbon)*
+- Update `aria-activedescendant` on every option focus change *(WAI-ARIA APG)*
+- Limit dropdown height to ~6–8 options; add scroll for more *(Carbon, Material 3)*
+
+### Don't
+- Don't close the dropdown on every keystroke in combobox mode — only on selection or Escape *(WAI-ARIA APG)*
+- Don't use a select for navigation — use a nav + router *(Carbon, Primer)*
+- Don't disable scroll inside the listbox — virtualise instead for large lists *(Mantine, Ant)*
+- Don't place interactive elements (links, buttons) inside `role="option"` *(WAI-ARIA APG)*
+
+---
+
+## Anti-patterns Cross-links
+
+| Anti-pattern | Entry |
+|--------------|-------|
+| Custom select without ARIA | `reference/anti-patterns.md` — ARIA role omission pattern |
+
+---
+
+## Benchmark Citations
+
+| Claim | Sources |
+|-------|---------|
+| aria-activedescendant pattern | WAI-ARIA APG combobox §4.1 |
+| Escape closes + returns focus | WAI-ARIA APG listbox §3.4 |
+| 240px max dropdown height | Carbon, Material 3 |
+| Checkbox approach for multi-select a11y | Carbon, WAI-ARIA APG |
+
+Full system URLs: `connections/design-corpora.md`
+
+---
+
+## Grep Signatures
+
+```bash
+# Custom select/combobox missing aria-expanded
+grep -rn 'role="combobox"\|role="listbox"' src/ | grep -v 'aria-expanded'
+
+# Options missing aria-selected
+grep -rn 'role="option"' src/ | grep -v 'aria-selected'
+
+# Missing aria-activedescendant on trigger
+grep -rn 'role="combobox"' src/ | grep -v 'aria-activedescendant'
+
+# Dropdown closed on every keypress (bad UX in combobox)
+grep -rn 'onKeyDown\|on:keydown' src/ | grep -i 'select\|combobox\|dropdown'
+```
+
+---
+
+## Failing Example
+
+```html
+<!-- BAD: custom dropdown with no ARIA — keyboard users and screen readers are stranded -->
+<div class="select-trigger" onclick="toggleDropdown()">Choose option</div>
+<ul class="dropdown">
+  <li onclick="selectOption('a')">Option A</li>
+  <li onclick="selectOption('b')">Option B</li>
+</ul>
+```
+
+**Why it fails**: No role, no aria-expanded, no keyboard navigation, no focus management.
+**Grep detection**: `grep -rn 'class.*dropdown\|class.*select' src/ | grep -v 'role='`
+**Fix**: Use Radix `<Select>` or implement WAI-ARIA listbox pattern with `role="combobox"`, `role="listbox"`, `role="option"`, `aria-expanded`, and `aria-activedescendant`.

package/reference/components/sidebar.md

@@ -0,0 +1,211 @@
+# Sidebar (Collapsible Side Navigation Panel) — Benchmark Spec
+
+**Harvested from**: Material 3, Carbon, Polaris, Atlassian, UUPM (app-interface, MIT)
+**Wave**: 4 · **Category**: Navigation
+
+---
+
+## Purpose
+
+A sidebar provides persistent or collapsible secondary navigation along the vertical axis of an application. In expanded state it shows icon + label; in collapsed state it shows icon only (with a tooltip). It is distinct from a Drawer (which is a modal overlay — see `drawer.md`) and from a Navbar (primary horizontal navigation). Use a sidebar for application-level section switching and hierarchical settings navigation. *(Material 3 Navigation Drawer, Carbon UI Shell Left Nav, Atlassian SideNavigation, Polaris Navigation agree)*
+
+---
+
+## Anatomy
+
+```
+┌─────────────────┐         ┌────┐
+│ [≡] App Name    │  ◄──►   │[≡] │  collapsed (icon-only)
+│─────────────────│         │────│
+│ 🏠 Dashboard    │         │[🏠]│  tooltip: "Dashboard"
+│ 📊 Analytics    │         │[📊]│
+│ ▾ Settings      │         │[⚙] │
+│   Account       │         └────┘
+│   Privacy       │
+│   Security      │
+└─────────────────┘
+```
+
+| Part | Required | Notes |
+|------|----------|-------|
+| `<nav>` wrapper | Yes | `role="navigation"` + `aria-label="Secondary"` |
+| Toggle button | Yes | `aria-expanded` + `aria-controls` pointing to nav |
+| Nav item | Yes | `<a>` for routing; `<button>` for non-routing actions |
+| Sub-section toggle | No | `<button>` with `aria-expanded`; chevron icon rotates |
+| Sub-section items | No | Indented child items; hidden when parent collapsed |
+| Tooltip | Conditional | On icon-only items in collapsed state; `role="tooltip"` |
+| Active indicator | Yes | `aria-current="page"` on active item |
+
+---
+
+## Variants
+
+| Variant | Description | Systems |
+|---------|-------------|---------|
+| Expanded | Icon + label visible; full width (240–280px) | All systems |
+| Collapsed / mini | Icon only; 48–64px wide; tooltips on hover/focus | Material 3, Carbon, Atlassian |
+| Floating / overlay | Overlay on top of content (mobile drawer pattern) | Material 3, Polaris |
+| Settings nav | Category tree: Settings › Account › Privacy › Security | UUPM app-interface (MIT) |
+| Dashboard nav | Section switcher: Dashboard / Analytics / Users / Settings | UUPM app-interface (MIT) |
+
+**Norm** (≥4 systems agree): expanded width 240–280px; collapsed width 48–64px; toggle button at top or bottom.
+**Diverge**: Carbon collapses to a rail (16px) with hover-expand; Material 3 differentiates between NavigationDrawer (permanent) and ModalNavigationDrawer (mobile).
+
+---
+
+## States
+
+| State | Trigger | Visual | ARIA |
+|-------|---------|--------|------|
+| expanded | default or toggle | Full width, labels visible | `aria-expanded="true"` on toggle |
+| collapsed | toggle click | Icon-only, labels hidden | `aria-expanded="false"` on toggle |
+| item-default | — | Resting fill | — |
+| item-hover | pointer over | 8% overlay | — |
+| item-focus | keyboard focus | 2px focus-visible ring | — |
+| item-active | current route | Filled pill or left indicator bar | `aria-current="page"` |
+| subsection-open | button click | Children visible; chevron rotated 180° | `aria-expanded="true"` on section button |
+| subsection-closed | button click | Children hidden | `aria-expanded="false"` on section button |
+
+---
+
+## Sizing & Spacing
+
+| State | Width | Item height | Item padding H |
+|-------|-------|-------------|----------------|
+| Expanded | 240–280px | 40px | 16px |
+| Collapsed | 48–64px | 40px | 12px (centered icon) |
+| Sub-item indent | — | 36px | 32px (16px base + 16px indent) |
+
+**Norm**: 240px expanded width (Carbon, Atlassian, Polaris). 40px item height matches button defaults.
+
+---
+
+## Typography
+
+- Nav item label: body-sm (13–14px), weight 400; active item weight 500 or 600
+- Sub-section heading (if present): label-xs (11–12px), uppercase, weight 600, `color: --text-subtle`
+- Tooltip: body-xs (11–12px) — concise, matches item label exactly in collapsed state
+- Never truncate nav item labels — resize the sidebar or abbreviate the label intentionally
+
+Cross-link: `reference/typography.md` — label scale, body-sm
+
+---
+
+## Keyboard & Accessibility
+
+> **WAI-ARIA role**: `navigation` (wrapper)
+> **Required attributes**: `aria-label="Secondary"` on `<nav>`; `aria-expanded` on toggle button and collapsible section buttons; `aria-current="page"` on active item
+
+### Keyboard Contract
+
+*Quoted verbatim from WAI-ARIA APG — https://www.w3.org/WAI/ARIA/apg/patterns/disclosure/ — W3C — 2024*
+
+| Key | Action |
+|-----|--------|
+| Tab / Shift+Tab | Moves focus through focusable items in DOM order |
+| Enter / Space | Activates focused link (navigates) or button (toggles section/sidebar) |
+| ArrowDown | Moves focus to next visible nav item (optional enhancement) |
+| ArrowUp | Moves focus to previous visible nav item (optional enhancement) |
+| Escape | Closes mobile overlay sidebar; returns focus to toggle |
+
+### Accessibility Rules
+
+- `<nav>` MUST have `aria-label="Secondary"` to distinguish from the primary navbar landmark
+- Every collapsible sub-section MUST have `aria-expanded` on its toggle button
+- Items that navigate (routing) MUST be `<a href>` links; items that only toggle state MUST be `<button>` (not `<a href="#">`)
+- In collapsed state, each icon-only item MUST have a tooltip AND `aria-label` (tooltip is not a substitute for accessible name)
+- `aria-current="page"` MUST be present on the currently active item
+
+Cross-link: `reference/accessibility.md` — landmark labelling, disclosure pattern
+
+---
+
+## Motion
+
+| Transition | Duration | Easing | Notes |
+|------------|----------|--------|-------|
+| Expand / collapse sidebar | 200ms | ease-in-out | Width transition; respect `prefers-reduced-motion` |
+| Sub-section open | 150ms | ease-out | Height expand; `overflow: hidden` clip |
+| Sub-section close | 120ms | ease-in | Height collapse |
+| Chevron rotate | 150ms | ease-in-out | 0° → 180° on open |
+| Label fade in | 100ms | ease-out | Delay until width ≥ 140px to prevent overlap |
+
+**BAN**: Animating sidebar width using `transition: all` — catches unrelated property changes and causes jank.
+
+Cross-link: `reference/motion.md` — layout transitions, BAN-04
+
+---
+
+## Do / Don't
+
+### Do
+- Use `<a href>` for routing nav items and `<button>` for non-routing actions *(Carbon, WAI-ARIA APG)*
+- Label the `<nav>` with `aria-label="Secondary"` *(WAI-ARIA APG landmark regions)*
+- Show tooltips on icon-only items in collapsed state *(Material 3, Carbon, Atlassian)*
+- Use `aria-expanded` on sub-section toggles *(WAI-ARIA APG disclosure pattern)*
+
+### Don't
+- Don't use `<a href="#">` for items that don't navigate — breaks bookmark/open-in-new-tab expectations *(Carbon, WAI-ARIA)*
+- Don't hide sub-items with `display: none` without also removing them from tab order *(WCAG 2.1.1)*
+- Don't use the same `aria-label` on both sidebar nav and top navbar *(WAI-ARIA landmark uniqueness)*
+- Don't collapse the sidebar below 44px touch target width on mobile *(WCAG 2.5.5)*
+
+---
+
+## Anti-patterns Cross-links
+
+| Anti-pattern | Entry |
+|--------------|-------|
+| BAN-04 | `transition: all` on interactive elements — `reference/anti-patterns.md#ban-04` |
+
+---
+
+## Benchmark Citations
+
+| Claim | Sources |
+|-------|---------|
+| aria-label="Secondary" distinct from Primary | WAI-ARIA APG landmark regions, WCAG 4.1.2 |
+| `<button>` for non-routing, `<a>` for routing | Carbon, WAI-ARIA APG, Primer |
+| aria-expanded on collapsible sections | WAI-ARIA APG disclosure pattern |
+| 240px expanded / 48–64px collapsed widths | Carbon, Atlassian, Polaris |
+| Tooltip on icon-only collapsed items | Material 3, Carbon, Atlassian |
+
+Full system URLs: `connections/design-corpora.md`
+
+---
+
+## Grep Signatures
+
+```bash
+# nav element missing aria-label
+grep -rn '<nav' src/ | grep -v 'aria-label\|aria-labelledby'
+
+# Collapsible section missing aria-expanded
+grep -rn 'sidebar\|sidenav\|side-nav' src/ | grep 'collapsible\|expandable\|toggle' | grep -v 'aria-expanded'
+
+# href="#" on nav items (non-routing anchor misuse)
+grep -rn 'href="#"' src/ | grep -i 'nav\|sidebar\|menu'
+
+# Active item missing aria-current
+grep -rn 'class.*active\|isActive\|is-active' src/ | grep -i 'nav.*item\|sidebar.*item' | grep -v 'aria-current'
+```
+
+---
+
+## Failing Example
+
+```html
+<!-- BAD: sidebar items using <a href="#"> for non-routing actions -->
+<nav>  <!-- missing aria-label -->
+  <a href="#">Dashboard</a>
+  <a href="#">Analytics</a>
+  <a href="#" class="active">Settings</a>  <!-- no aria-current -->
+  <a href="#">
+    Account  <!-- subsection, but no aria-expanded -->
+  </a>
+</nav>
+```
+
+**Why it fails**: `<nav>` has no label (ambiguous landmark); `<a href="#">` creates false navigation expectations and adds to browser history; active state uses CSS class only; no `aria-current="page"`; no `aria-expanded` for the sub-section.
+**Grep detection**: `grep -rn 'href="#"' src/ | grep -i 'nav\|sidebar'`
+**Fix**: Replace `<a href="#">` with `<button>` for non-routing items; add `aria-label="Secondary"` to `<nav>`; add `aria-current="page"` to active item; add `aria-expanded` to sub-section toggles.