@hegemonart/get-design-done 1.16.0 → 1.19.0

package/reference/components/progress.md

@@ -0,0 +1,210 @@
+# Progress — Benchmark Spec
+
+**Harvested from**: Material 3, Carbon (ProgressIndicator), Polaris, Mantine
+**Wave**: 3 · **Category**: Feedback
+
+---
+
+## Purpose
+
+A progress indicator communicates the status of an ongoing operation. Determinate variants show a known percentage of completion (0–100%); indeterminate variants signal ongoing work when duration is unknown. Linear bars are suited to step-based or file-based progress; circular (spinner-ring) variants are suited to inline or compact contexts. *(Material 3, Carbon, Polaris, Mantine agree: separate determinate vs. indeterminate; linear vs. circular)*
+
+---
+
+## Anatomy
+
+**Linear**
+```
+[track ──────────────────────────────────]
+[fill ◼◼◼◼◼◼◼◼◼◼◼◼◼◼·····················]
+      ↑ role="progressbar" aria-valuenow="45"
+```
+
+**Circular**
+```
+    ╭──╮
+   ╭    ╮
+   ╰    ╯ ← SVG stroke-dashoffset ring
+    ╰──╯
+  role="progressbar"
+```
+
+| Part | Required | Notes |
+|------|----------|-------|
+| Track | Yes | Background rail (linear) or ring background (circular) |
+| Fill / indicator | Yes | Foreground showing progress amount |
+| Label (visually hidden ok) | Yes | `aria-label` or `aria-labelledby` — describes what is loading |
+| Value text | No | Rendered percentage (e.g. "45%") — supplement to ARIA value |
+
+---
+
+## Variants
+
+| Variant | Description | Systems |
+|---------|-------------|---------|
+| Linear determinate | Bar fills left-to-right proportionally | Material 3, Carbon, Polaris, Mantine |
+| Linear indeterminate | Bar animates in loop (shimmer or sweep) | Material 3, Carbon, Polaris, Mantine |
+| Circular determinate | SVG ring fills by stroke-dashoffset | Material 3, Carbon, Mantine |
+| Circular indeterminate | SVG ring rotates in loop | Material 3, Carbon, Mantine |
+
+**Norm** (≥4/18 systems agree): `role="progressbar"` on all variants; `aria-valuenow` only on determinate; `aria-valuemin=0` + `aria-valuemax=100` always.
+**Diverge**: Polaris calls the circular variant "Spinner" (single indeterminate state only); Material 3 distinguishes "linear progress indicator" and "circular progress indicator" as separate component families; Carbon offers multi-step linear progress ("ProgressStep") as a distinct component.
+
+---
+
+## States
+
+| State | Trigger | Visual | ARIA |
+|-------|---------|--------|------|
+| determinate (0–100%) | known progress value | Fill width/stroke = percentage | `aria-valuenow={n}` |
+| indeterminate | unknown duration | Looping animation | `aria-valuetext="Loading"` |
+| complete | value reaches 100% | Full fill; brief hold before removal | `aria-valuenow="100"` |
+| paused | operation suspended | Static fill; muted color | `aria-valuetext="Paused"` |
+
+---
+
+## Sizing & Spacing
+
+**Linear**
+
+| Size | Height | Notes |
+|------|--------|-------|
+| sm | 4px (default) | Decorative; thin above content |
+| md | 8px | Accessible minimum — recommended when bar is the primary indicator |
+| lg | 12px | High-emphasis; file upload, step progress |
+
+**Circular**
+
+| Size | Diameter | Stroke width | Notes |
+|------|----------|-------------|-------|
+| sm | 20px | 2px | Inline within text/button |
+| md | 32px | 3px | Component-level loading |
+| lg | 48px | 4px | Page/section loading |
+
+**Norm**: 4px linear height default (Material 3); 8px recommended for standalone accessibility *(Carbon)*; circular diameter 20–48px *(Material 3, Mantine)*.
+
+---
+
+## Typography
+
+- Value label (if shown): numeric-sm (12px/tabular-nums) — percentage readability
+- Associated label (if visible): body-sm (14px/400) — describes what is loading
+- Do not truncate the associated label; use a visually-hidden version if space is constrained
+
+Cross-link: `reference/typography.md` — tabular-nums for percentage values
+
+---
+
+## Keyboard & Accessibility
+
+> **WAI-ARIA role**: `progressbar`
+> **Required attributes**: `aria-valuemin="0"`, `aria-valuemax="100"`, `aria-label` or `aria-labelledby`; `aria-valuenow` on determinate only
+
+### Keyboard Contract
+
+*Quoted verbatim from WAI-ARIA APG — https://www.w3.org/WAI/ARIA/apg/patterns/meter/ — W3C — 2024*
+
+| Key | Action |
+|-----|--------|
+| (none) | Progress bar is not interactive; no keyboard interaction required |
+
+Progress indicators are read-only status elements. They receive no keyboard focus unless embedded in a larger focusable region.
+
+### Accessibility Rules
+
+- `aria-label` or `aria-labelledby` MUST describe what is loading (e.g. "Uploading file", "Loading results") — a bare `role="progressbar"` with no label is announced as empty *(WAI-ARIA APG)*
+- Determinate bars MUST include `aria-valuenow` matching the current integer percentage *(WAI-ARIA APG)*
+- Indeterminate bars MUST omit `aria-valuenow` and instead set `aria-valuetext="Loading"` or similar *(WAI-ARIA APG)*
+- `aria-valuemin` and `aria-valuemax` MUST be present on all progress bars (default 0 and 100)
+- Indeterminate animation MUST respect `prefers-reduced-motion` — reduce to opacity pulse or static indicator *(WCAG 2.3.3)*
+- Color contrast of fill vs. track MUST meet 3:1 minimum for non-text UI components *(WCAG 1.4.11)*
+
+Cross-link: `reference/accessibility.md` — `prefers-reduced-motion`, WCAG 1.4.11
+
+---
+
+## Motion
+
+| Transition | Duration | Easing | Notes |
+|------------|----------|--------|-------|
+| Determinate fill advance | 300ms | ease-out | Smooth value update on change |
+| Indeterminate linear sweep | 1.2s | ease-in-out | Infinite loop; reverse direction at 50% |
+| Circular spin | 1.2s | linear | Single full rotation per cycle |
+| Complete → remove | 400ms | ease-in | Brief hold at 100% then fade/collapse |
+
+**BAN**: Bouncing or elasticity on indeterminate loop — communicates false progress rhythm. Do not use `transition: all` (catches color changes during theme swap).
+
+Cross-link: `reference/motion.md` — `prefers-reduced-motion`: replace sweep with opacity 0.5→1 pulse
+
+---
+
+## Do / Don't
+
+### Do
+- Always provide `aria-label` describing what is loading *(WAI-ARIA APG)*
+- Use `aria-valuenow` on determinate variants and omit on indeterminate *(WAI-ARIA APG)*
+- Use 8px+ height for standalone linear bars — 4px bars lack sufficient touch and visual target *(Carbon)*
+- Transition fill smoothly (300ms ease-out) when value updates *(Material 3, Mantine)*
+
+### Don't
+- Don't use `aria-valuenow` on indeterminate bars — it implies a known value *(WAI-ARIA APG)*
+- Don't show a spinner (circular indeterminate) when content shape is known — use Skeleton instead *(Carbon, Polaris)*
+- Don't remove the progress bar the instant it hits 100% — hold briefly so the completion is registered *(Material 3)*
+- Don't animate with infinite bounce — implies bouncing progress rhythm *(Carbon, Mantine)*
+
+---
+
+## Anti-patterns Cross-links
+
+| Anti-pattern | Entry |
+|--------------|-------|
+| Indeterminate bar with aria-valuenow | `reference/anti-patterns.md#ban-aria-value` |
+| Spinner used when content shape is known | `reference/anti-patterns.md#ban-spinner-overuse` |
+
+---
+
+## Benchmark Citations
+
+| Claim | Sources |
+|-------|---------|
+| role="progressbar" on all variants | WAI-ARIA APG |
+| aria-valuenow only on determinate | WAI-ARIA APG, Material 3, Carbon |
+| aria-label required (what is loading) | WAI-ARIA APG |
+| 8px accessible minimum height | Carbon |
+| 1.2s animation loop duration | Material 3, Mantine |
+| Respect prefers-reduced-motion | WCAG 2.3.3 |
+
+Full system URLs: `connections/design-corpora.md`
+
+---
+
+## Grep Signatures
+
+```bash
+# Progress bar missing aria-label or aria-labelledby
+grep -rn 'role="progressbar"' src/ | grep -v 'aria-label\|aria-labelledby'
+
+# Determinate progress missing aria-valuenow
+grep -rn 'role="progressbar"' src/ | grep -v 'aria-valuenow\|indeterminate'
+
+# Progress missing valuemin/valuemax
+grep -rn 'role="progressbar"' src/ | grep -v 'aria-valuemin\|aria-valuemax'
+
+# Indeterminate with aria-valuenow (invalid pattern)
+grep -rn 'indeterminate' src/ | grep 'aria-valuenow'
+```
+
+---
+
+## Failing Example
+
+```html
+<!-- BAD: progress bar with no accessible label and no value attributes -->
+<div class="progress-bar">
+  <div class="progress-bar__fill" style="width: 45%"></div>
+</div>
+```
+
+**Why it fails**: No `role="progressbar"` so screen readers do not recognize this as a progress indicator. No `aria-label` so there is no description of what is loading. No `aria-valuenow`, `aria-valuemin`, or `aria-valuemax` so screen readers cannot read the percentage even if the role were present.
+**Grep detection**: `grep -rn 'progress-bar\|progressBar\|progress__fill' src/ | grep -v 'role="progressbar"'`
+**Fix**: `<div role="progressbar" aria-valuenow="45" aria-valuemin="0" aria-valuemax="100" aria-label="Uploading file"><div style="width:45%"></div></div>`

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/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.