@hegemonart/get-design-done 1.15.0 → 1.18.0

package/reference/components/switch.md

@@ -0,0 +1,194 @@
+# Switch — Benchmark Spec
+
+**Harvested from**: Apple HIG, Material 3, Radix UI, Spectrum (Adobe), Polaris, Fluent 2, Mantine, shadcn/ui
+**Wave**: 1 · **Category**: Inputs
+
+---
+
+## Purpose
+
+A switch (toggle) represents an immediate binary action — changes take effect without a confirm step, like enabling dark mode or activating a feature. It differs from a checkbox in this immediacy: a checkbox is a form option submitted later; a switch acts now. Do not use a switch inside a form that requires a submit button to apply changes. *(Apple HIG, Material 3, Polaris all distinguish switch from checkbox this way)*
+
+---
+
+## Anatomy
+
+```
+Label                     ← visible text describing the setting
+ ◉───────  ON             ← track + thumb; thumb slides right on ON
+ ○───────  OFF            ← thumb left on OFF
+ Helper text (opt.)
+```
+
+| Part | Required | Notes |
+|------|----------|-------|
+| Track | Yes | Background bar; 28–52px wide, 14–32px tall |
+| Thumb | Yes | Circular indicator that slides |
+| Label | Yes (or `aria-label`) | Describes what the switch controls |
+| State text (ON/OFF) | No | Optional inside or beside track; not required by a11y |
+| Helper text | No | Clarifies effect of the switch |
+
+---
+
+## Variants
+
+| Variant | Description | Systems |
+|---------|-------------|---------|
+| Default | Label left/right, switch right/left | All |
+| With icon | Icon inside thumb (check/x) | Material 3, Fluent 2 |
+| With state text | ON/OFF inside track | Apple HIG (iOS), Fluent 2 |
+| Small | Compact size (24px height) | Mantine, shadcn |
+| Large | 32px height | Material 3, Apple HIG |
+
+**Norm** (≥5/18): label appears to the left of the switch (LTR); toggle is right-aligned.
+**Diverge**: thumb icon vs. bare thumb — Material 3 adds check icon on ON, x on OFF; most others use bare thumb. Bare is simpler and more portable across themes.
+
+---
+
+## States
+
+| State | Visual | ARIA |
+|-------|--------|------|
+| OFF (unchecked) | Thumb left, track muted | `aria-checked="false"` |
+| ON (checked) | Thumb right, track colored | `aria-checked="true"` |
+| hover | Thumb scale up slightly (1.1×) | — |
+| focus | 2px focus ring around track | — |
+| disabled OFF | 38% opacity, thumb left | `aria-disabled="true"` |
+| disabled ON | 38% opacity, thumb right | `aria-disabled="true"` |
+
+---
+
+## Sizing & Spacing
+
+| Size | Track W×H | Thumb diameter | Touch target |
+|------|-----------|----------------|--------------|
+| sm | 36×20px | 16px | 44×44px via pseudo-element |
+| md (default) | 44×24px | 20px | 44×44px |
+| lg | 52×28px | 24px | 48×48px |
+
+Track radius: `border-radius: 9999px` (pill shape — all 8 systems agree).
+Thumb travel: track width − thumb diameter − (2 × inset padding ≈ 2px).
+
+Cross-link: `reference/surfaces.md` — concentric radius rule does NOT apply here (pill shape is intentional, not nested radius)
+
+---
+
+## Typography
+
+- Label: 14px/400 body weight; not distinguished from surrounding text
+- State text (optional): 10–11px/600 uppercase inside track — ensure ≥4.5:1 contrast against track colour
+
+---
+
+## Keyboard & Accessibility
+
+> **WAI-ARIA role**: `switch`
+> **Required attributes**: `aria-checked` ("true" / "false"); `aria-label` or visible associated label
+
+### Keyboard Contract
+
+*Quoted verbatim from WAI-ARIA APG — https://www.w3.org/WAI/ARIA/apg/patterns/switch/ — W3C — 2024*
+
+| Key | Action |
+|-----|--------|
+| Space | Toggles the switch state |
+| Enter | (Optional) Toggles the switch state |
+
+### Accessibility Rules
+
+- `role="switch"` with `aria-checked="true/false"` — not `role="checkbox"` (different semantic contract; switch implies immediate action)
+- Label MUST be associated: `<label>` with `for` on the switch element, or `aria-label`/`aria-labelledby`
+- State text ("ON"/"OFF") inside the track is a visual enhancement only — it MUST NOT be the sole accessible name
+- Disabled: use `aria-disabled="true"` (not native `disabled` attr) if keyboard focus should remain (e.g. to explain why it's disabled via tooltip)
+- Announce state change via `aria-live="polite"` if switching triggers a significant UI change distant from the control
+
+---
+
+## Motion
+
+| Transition | Duration | Easing | Notes |
+|------------|----------|--------|-------|
+| Thumb slide | 150ms | spring (bounce: 0) | Smooth, satisfying; canonical spring values |
+| Track colour | 150ms | ease | Simultaneous with thumb |
+| Thumb scale on hover | 80ms | ease | 1→1.1× scale |
+| Press scale | 80ms | ease | 1→0.96× (canonical press scale) |
+
+Cross-link: `reference/motion.md` — spring bounce=0 canonical values, canonical scale-on-press 0.96
+
+---
+
+## Do / Don't
+
+### Do
+- Use `role="switch"` not `role="checkbox"` for toggle-with-immediate-effect *(WAI-ARIA APG, Radix)*
+- Animate the thumb sliding — static snap removes the "toggle" affordance *(Apple HIG, Material 3)*
+- Place label to the left of the switch in LTR layouts *(Apple HIG, Material 3, Polaris)*
+- Apply changes immediately on toggle — no submit button required *(Apple HIG, Polaris)*
+
+### Don't
+- Don't use a switch inside a form where the user must click "Save" — use a checkbox *(Apple HIG, Polaris)*
+- Don't rely on track colour alone to communicate state (colour blind users) — add icon or label *(Spectrum, Material 3)*
+- Don't use the same `aria-label` for ON and OFF states — screen readers read the current state via `aria-checked` *(WAI-ARIA APG)*
+- Don't animate thumb with `transition: all` — it catches border-radius changes and causes thumb deformation *(BAN-04)*
+
+---
+
+## Anti-patterns Cross-links
+
+| Anti-pattern | Entry |
+|--------------|-------|
+| BAN-04 | `transition: all` — `reference/anti-patterns.md#ban-04` |
+| Checkbox semantics for immediate-action toggle | `reference/anti-patterns.md` |
+
+---
+
+## Benchmark Citations
+
+| Claim | Sources |
+|-------|---------|
+| Switch = immediate action; checkbox = form submit | Apple HIG, Material 3, Polaris |
+| role="switch" not role="checkbox" | WAI-ARIA APG, Radix |
+| Pill track (border-radius: 9999px) | Apple HIG, Material 3, Fluent 2 (all 8) |
+| Spring motion for thumb | Material 3, Apple HIG |
+
+Full system URLs: `connections/design-corpora.md`
+
+---
+
+## Grep Signatures
+
+```bash
+# Switch using role="checkbox" instead of role="switch"
+grep -rn 'role="checkbox"' src/ | grep -i 'switch\|toggle'
+
+# Missing aria-checked on switch
+grep -rn 'role="switch"' src/ | grep -v 'aria-checked'
+
+# transition: all on switch thumb (BAN-04)
+grep -rn 'transition:\s*all' src/ | grep -i 'switch\|thumb\|toggle'
+
+# Switch inside <form> with submit (should be checkbox)
+grep -rn 'role="switch"\|type.*switch' src/ | grep -i 'form\|submit'
+```
+
+---
+
+## Failing Example
+
+```html
+<!-- BAD: input[type="checkbox"] used as a switch — wrong semantic contract -->
+<label>
+  <input type="checkbox" class="switch-toggle" />
+  Enable notifications
+</label>
+```
+
+**Why it fails**: `type="checkbox"` implies form-submit semantics. Screen reader announces "checkbox" not "switch". Users with mental model of "toggle = immediate effect" are confused.
+**Grep detection**: `grep -rn 'class.*switch\|class.*toggle' src/ | grep 'type="checkbox"'`
+**Fix**:
+```html
+<button role="switch" aria-checked="false" id="notif-switch">
+  <span class="thumb" aria-hidden="true"></span>
+</button>
+<label for="notif-switch">Enable notifications</label>
+```

package/reference/components/table.md

@@ -0,0 +1,229 @@
+# Table (Data Table / Data Grid) — Benchmark Spec
+
+**Harvested from**: Carbon DataTable, Polaris DataTable, Atlassian DynamicTable, Ant Design Table, UUPM (app-interface, MIT)
+**Wave**: 4 · **Category**: Navigation & Data
+
+---
+
+## Purpose
+
+A data table presents structured, comparable information in rows and columns. It supports sorting, filtering, row selection, and pagination. Use `role="table"` for static display; use `role="grid"` for interactive tables where keyboard navigation between cells is needed (e.g., spreadsheet-like editing). Tables are distinct from Lists (unstructured items) and Cards (single-entity display). *(Carbon DataTable, Polaris DataTable, Atlassian DynamicTable, Ant Table all define table as the canonical multi-column data display)*
+
+---
+
+## Anatomy
+
+```
+┌─────────────────────────────────────────────────────┐
+│ [☐] Name ↑      Status       Amount       Actions   │  <thead>
+│─────────────────────────────────────────────────────│
+│ [☐] Alice Chen  Active       $1,200.00    [···]     │  <tbody>
+│ [☑] Bob Tanaka  Inactive     $850.00      [···]     │  aria-selected="true"
+│ [☐] Carol Wu    Active       $2,400.00    [···]     │
+│─────────────────────────────────────────────────────│
+│ Showing 1–3 of 247    [‹ Prev]  1  2  3  [Next ›]  │  <tfoot>
+└─────────────────────────────────────────────────────┘
+```
+
+| Part | Required | Notes |
+|------|----------|-------|
+| `<table>` | Yes | Semantic table element; `role="grid"` if interactive |
+| `<caption>` | Yes (or `aria-label`) | Describes the table's purpose; `<caption>` preferred |
+| `<thead>` | Yes | Column header row(s) |
+| `<th scope="col">` | Yes | `scope="col"` on every column header |
+| `<tbody>` | Yes | Data rows |
+| `<th scope="row">` | No | Row header for the first cell if rows have identity |
+| `<tfoot>` | No | Summary row, pagination, totals |
+| Sortable header | No | `aria-sort="ascending|descending|none"` on `<th>` |
+| Select-all checkbox | No | `<th scope="col">` with select-all; `aria-label="Select all rows"` |
+| Row checkbox | No | `<td>` with checkbox; selected row has `aria-selected="true"` on `<tr>` |
+| Scroll wrapper | Conditional | `overflow-x: auto` + `tabindex="0"` on wrapper for keyboard scroll |
+
+---
+
+## Variants
+
+| Variant | Description | Systems |
+|---------|-------------|---------|
+| Static / display | Read-only; `role="table"` | All systems |
+| Sortable | Clickable column headers; `aria-sort` | Carbon, Polaris, Atlassian, Ant |
+| Selectable | Row checkboxes; batch actions toolbar | Carbon, Polaris, Atlassian |
+| Expandable rows | Toggle row detail panel | Carbon, Ant, Atlassian |
+| Interactive / grid | Cell-level focus; `role="grid"` | Carbon, Ant |
+| Sticky header | `position: sticky` on `<thead>` | Carbon, Ant, Polaris |
+| Master-detail | Table + side detail pane | UUPM app-interface (MIT) |
+| Dashboard data grid | Dense, compact variant for analytics dashboards | UUPM app-interface (MIT) |
+
+**Norm** (≥4 systems agree): `<table>` with `<thead>`/`<tbody>`; `scope="col"` on all `<th>`; `aria-sort` on sortable columns.
+**Diverge**: Carbon uses `role="grid"` by default for keyboard cell navigation; Polaris uses `role="table"` for read-only display.
+
+---
+
+## States
+
+| State | Trigger | Visual | ARIA |
+|-------|---------|--------|------|
+| default | — | Alternating row colors or border separators | — |
+| row-hover | pointer over row | Subtle row highlight (4% overlay) | — |
+| row-selected | checkbox checked | Row highlight; checkbox filled | `aria-selected="true"` on `<tr>` |
+| header-sort-asc | sort click | Arrow indicator up; column highlight | `aria-sort="ascending"` on `<th>` |
+| header-sort-desc | sort click again | Arrow indicator down | `aria-sort="descending"` on `<th>` |
+| header-sort-none | default or reset | No indicator | `aria-sort="none"` on sortable `<th>` |
+| header-focus | keyboard focus on sortable `<th>` | 2px focus-visible ring | — |
+| loading | data fetch | Skeleton rows or spinner overlay | `aria-busy="true"` on table or container |
+| empty | no results | Empty state illustration + message | — |
+
+---
+
+## Sizing & Spacing
+
+| Density | Row height | Cell padding H | Cell padding V | Font |
+|---------|------------|----------------|----------------|------|
+| compact | 32px | 12px | 4px | 13px |
+| default | 48px | 16px | 12px | 14px |
+| comfortable | 56px | 20px | 16px | 14px |
+
+**Norm**: 48px default row height (Carbon, Atlassian, Ant). Column min-width 80px; text columns flexible.
+Virtualise rows when `rowCount > 200`; use TanStack Virtual or react-virtual.
+
+---
+
+## Typography
+
+- Column header: body-sm or label-sm (12–13px), weight 600, `color: --text-secondary`
+- Cell text: body-sm (13–14px), weight 400
+- Numeric cells: `font-variant-numeric: tabular-nums` — column values align on decimal point
+- Truncation: `text-overflow: ellipsis` on cells with `max-width`; tooltip reveals full value on hover
+
+Cross-link: `reference/typography.md` — tabular-nums, body-sm
+
+---
+
+## Keyboard & Accessibility
+
+> **WAI-ARIA role**: `table` (static) or `grid` (interactive)
+> **Required attributes**: `scope="col"` on all `<th>` headers; `aria-sort` on sortable columns; `aria-selected="true"` on selected `<tr>`; `<caption>` or `aria-label` on `<table>`
+
+### Keyboard Contract
+
+*Quoted verbatim from WAI-ARIA APG — https://www.w3.org/WAI/ARIA/apg/patterns/grid/ — W3C — 2024*
+
+| Key | Action (role="grid") |
+|-----|---------------------|
+| ArrowRight | Moves focus to next cell in row |
+| ArrowLeft | Moves focus to previous cell in row |
+| ArrowDown | Moves focus to same cell in next row |
+| ArrowUp | Moves focus to same cell in previous row |
+| Home | Moves focus to first cell in row |
+| End | Moves focus to last cell in row |
+| Ctrl+Home | Moves focus to first cell in grid |
+| Ctrl+End | Moves focus to last cell in grid |
+| Enter / Space | Activates cell widget (checkbox, link, button) |
+| Tab | Moves focus out of grid to next component |
+
+### Accessibility Rules
+
+- ALL `<th>` column headers MUST have `scope="col"` — missing scope breaks AT table navigation
+- Sortable `<th>` elements MUST have `aria-sort` with value `ascending`, `descending`, or `none`
+- Selected rows MUST use `aria-selected="true"` on `<tr>` — CSS class alone is invisible to AT
+- `<table>` MUST have a `<caption>` or `aria-label` to announce the table's purpose
+- The responsive scroll wrapper MUST have `tabindex="0"` so keyboard users can scroll horizontally
+- `role="grid"` enables cell-level arrow-key navigation; use only when cells contain interactive controls
+
+Cross-link: `reference/accessibility.md` — table semantics, grid pattern
+
+---
+
+## Motion
+
+| Transition | Duration | Easing | Notes |
+|------------|----------|--------|-------|
+| Row hover highlight | 80ms | ease-out | Background color only |
+| Row select | 100ms | ease-out | Checkbox + row color |
+| Sort indicator change | 120ms | ease-out | Arrow direction transition |
+| Expandable row open | 150ms | ease-out | Height expand |
+| Skeleton shimmer | 1500ms | linear loop | Loading placeholder |
+
+**BAN**: Do not animate `width` on table columns — causes full table relayout on every frame.
+
+Cross-link: `reference/motion.md` — layout-affecting transitions, skeleton shimmer
+
+---
+
+## Do / Don't
+
+### Do
+- Add `scope="col"` to every `<th>` — screen readers use this to announce column context *(WAI-ARIA, Carbon)*
+- Use `aria-sort` on sortable headers — not just a visual arrow icon *(Carbon, Polaris, Atlassian)*
+- Use `tabindex="0"` on horizontal scroll wrapper for keyboard accessibility *(WCAG 2.1.1)*
+- Virtualise rows at > 200 items — prevents browser paint lag *(Carbon, Ant)*
+
+### Don't
+- Don't build a "table" with `<div>` elements and no ARIA grid roles — invisible to AT *(WCAG 1.3.1)*
+- Don't use `aria-sort` on non-sortable columns — misleads users into clicking non-interactive headers *(WAI-ARIA)*
+- Don't place `overflow-x: auto` on `<table>` directly — wrap in a `<div>` with `tabindex="0"` *(WCAG 2.1.1)*
+- Don't use `display: contents` on `<thead>/<tbody>/<tr>` — breaks AT table parsing *(WCAG 1.3.1)*
+
+---
+
+## Anti-patterns Cross-links
+
+| Anti-pattern | Entry |
+|--------------|-------|
+| BAN-04 | `transition: all` on table cells — `reference/anti-patterns.md#ban-04` |
+
+---
+
+## Benchmark Citations
+
+| Claim | Sources |
+|-------|---------|
+| scope="col" on all th headers | WAI-ARIA, Carbon DataTable, Polaris |
+| aria-sort on sortable columns | WAI-ARIA APG grid pattern, Carbon, Atlassian |
+| aria-selected="true" on selected rows | WAI-ARIA APG, Carbon, Ant |
+| role="grid" for interactive cell navigation | WAI-ARIA APG, Carbon |
+| Virtualise at > 200 rows | Carbon, Ant (TanStack Virtual recommendation) |
+
+Full system URLs: `connections/design-corpora.md`
+
+---
+
+## Grep Signatures
+
+```bash
+# <th> missing scope attribute
+grep -rn '<th' src/ | grep -v 'scope='
+
+# Sortable column missing aria-sort
+grep -rn 'sortable\|sort-header\|on.*sort' src/ | grep '<th' | grep -v 'aria-sort'
+
+# Selected row missing aria-selected
+grep -rn 'row.*selected\|selected.*row\|isSelected' src/ | grep '<tr' | grep -v 'aria-selected'
+
+# Table built with divs (no semantic markup)
+grep -rn 'class.*table\|data-table' src/ | grep '<div' | grep -v 'role="table"\|role="grid"'
+```
+
+---
+
+## Failing Example
+
+```html
+<!-- BAD: <div> table with no semantic markup and no ARIA grid roles -->
+<div class="data-table">
+  <div class="table-header">
+    <div class="col-header" onclick="sortByName()">Name</div>  <!-- no aria-sort -->
+    <div class="col-header">Status</div>
+    <div class="col-header">Amount</div>
+  </div>
+  <div class="table-row selected">  <!-- no aria-selected -->
+    <div class="cell">Alice Chen</div>
+    <div class="cell">Active</div>
+    <div class="cell">$1,200.00</div>
+  </div>
+</div>
+```
+
+**Why it fails**: No `<table>/<thead>/<tbody>/<th>/<td>` semantics; no `scope="col"` on headers; no `aria-sort` on sortable column; `selected` row uses CSS class without `aria-selected="true"`; screen readers cannot navigate by row/column; no caption/label.
+**Grep detection**: `grep -rn 'data-table\|table.*container' src/ | grep '<div' | grep -v 'role='`
+**Fix**: Replace with semantic `<table>` and `<th scope="col">` headers; add `aria-sort` to sortable headers; add `aria-selected="true"` to selected `<tr>`; add `<caption>` describing the table.

package/reference/components/tabs.md

@@ -0,0 +1,213 @@
+# Tabs — Benchmark Spec
+
+**Harvested from**: WAI-ARIA APG, Radix UI, Carbon, Mantine, Material 3, Chakra UI, Atlassian, Fluent 2
+**Wave**: 2 · **Category**: Containers
+
+---
+
+## Purpose
+
+Tabs organize content into parallel sections where only one section is visible at a time. Users navigate between tab panels without a page reload. Tabs differ from accordion (tabs are horizontal, panels mutually exclusive) and navigation (tabs do not change the URL in most implementations). The tab strip uses arrow-key navigation within the tablist, not Tab key. *(WAI-ARIA APG, Radix, Carbon all define this contract)*
+
+---
+
+## Anatomy
+
+```
+┌──────┬──────────┬──────┐
+│ Tab1 │  Tab 2   │ Tab3 │  ← role="tablist"
+└──────┴──────────┴──────┘    Each tab: role="tab" + aria-selected + aria-controls
+────────────────────────────  Panel separator (visual only)
+  Panel content               ← role="tabpanel" + aria-labelledby
+
+Vertical tabs (sidebar):
+┌──────────┬──────────────────┐
+│ Tab 1    │                  │
+│ Tab 2    │  Panel content   │
+│ Tab 3    │                  │
+└──────────┴──────────────────┘
+```
+
+| Part | Required | Notes |
+|------|----------|-------|
+| `role="tablist"` container | Yes | Wraps all tabs; `aria-label` or `aria-labelledby` |
+| Tab triggers | Yes | `role="tab"`, `aria-selected`, `aria-controls` |
+| Tab panels | Yes | `role="tabpanel"`, `aria-labelledby` (matching tab id) |
+| Tab strip indicator | No | Underline or filled; shows selected tab |
+| Overflow handling | Conditional | Scroll or dropdown when tabs overflow container |
+
+---
+
+## Variants
+
+| Variant | Description | Systems |
+|---------|-------------|---------|
+| Default (horizontal) | Tab strip above panel | All |
+| Vertical | Tab strip left of panel | Carbon, Material 3, Fluent |
+| Underline | Underline indicator below selected tab | Material 3, shadcn, Atlassian |
+| Filled / boxed | Selected tab has filled background | Carbon, Mantine, Fluent |
+| Pill | Rounded tab shape | Mantine, Chakra |
+| Scrollable | Horizontal scroll when tabs overflow | Material 3, Carbon |
+| Icon + label | Icon above or beside label | Material 3, Carbon |
+
+**Norm** (≥6/18): arrow keys navigate between tabs; Tab key moves to active panel content.
+**Diverge**: automatic vs. manual activation — automatic (arrow key selects immediately) vs. manual (arrow key moves focus, Enter selects). WAI-ARIA APG recommends manual for complex panels; Radix defaults to automatic.
+
+---
+
+## States
+
+| State | ARIA |
+|-------|------|
+| Selected tab | `aria-selected="true"`, `tabindex="0"` |
+| Unselected tab | `aria-selected="false"`, `tabindex="-1"` |
+| Focused tab | 2px focus ring; `tabindex="0"` moves to tab |
+| Disabled tab | `aria-disabled="true"`, `tabindex="-1"` |
+| Active panel | `role="tabpanel"`, visible, focusable |
+| Inactive panel | `hidden` or `display:none` (removed from AT) |
+
+---
+
+## Sizing & Spacing
+
+| Property | Value | Notes |
+|----------|-------|-------|
+| Tab height | 40–48px | Touch target compliance |
+| Tab padding H | 16px | Minimum; increase for wider labels |
+| Min tab width | 80px | Prevent cramped labels |
+| Indicator thickness | 2–3px (underline) | On bottom edge of selected tab |
+| Panel padding | 16–24px | |
+
+---
+
+## Typography
+
+- Tab label: 14px/500 (selected), 14px/400 (unselected)
+- Vertical tab label: 14px/400; left-aligned
+- Tab count badge: 12px/600 in a pill; `aria-label` on tab includes count
+
+---
+
+## Keyboard & Accessibility
+
+> **WAI-ARIA role**: `tablist` (container), `tab` (each trigger), `tabpanel` (each content panel)
+> **Tab attributes**: `aria-selected`, `aria-controls` (panel id), `tabindex` (0 if selected, -1 if not)
+> **Panel attributes**: `role="tabpanel"`, `aria-labelledby` (tab id), `tabindex="0"` (makes panel focusable)
+
+### Keyboard Contract
+
+*Quoted verbatim from WAI-ARIA APG — https://www.w3.org/WAI/ARIA/apg/patterns/tabs/ — W3C — 2024*
+
+| Key | Action |
+|-----|--------|
+| Tab | When focus moves into the tab list, sets focus on the active tab. When the tab list has focus, Tab moves focus to the next element in the page tab sequence (the tabpanel or element after tablist). |
+| Arrow Right | Moves focus to the next tab. If focus is on the last tab, moves to the first tab. |
+| Arrow Left | Moves focus to the previous tab. If focus is on the first tab, moves to the last tab. |
+| Arrow Down | (Vertical tabs) Moves focus to the next tab |
+| Arrow Up | (Vertical tabs) Moves focus to the previous tab |
+| Space / Enter | (Manual activation only) Activates the focused tab |
+| Home | Moves focus to the first tab |
+| End | Moves focus to the last tab |
+
+### Activation Modes
+
+- **Automatic**: arrow key moves focus AND activates the tab/panel simultaneously
+- **Manual**: arrow key moves focus only; Enter/Space activates. Preferred for panels that have expensive load operations
+
+### Accessibility Rules
+
+- Only the selected tab has `tabindex="0"` — all other tabs have `tabindex="-1"` (roving tabindex pattern)
+- `tablist` MUST have a label: `aria-label="[Section name]"` or `aria-labelledby`
+- Inactive panels MUST be hidden with `hidden` attribute (not just CSS) so AT skips them
+- Panel SHOULD have `tabindex="0"` to allow focusing the panel after Tab from the tablist
+- Icon-only tabs MUST have `aria-label` on the tab element
+- Linked tabs (tabs that change URL): use `role="link"` semantics or native `<a>` within tab — but note this changes the keyboard contract
+
+---
+
+## Motion
+
+| Transition | Duration | Easing | Notes |
+|------------|----------|--------|-------|
+| Indicator slide | 200ms | ease-out | Underline slides between tabs |
+| Panel fade | 150ms | ease | Crossfade between panels |
+| Scroll reveal | 200ms | ease | When scrolling to new active tab in overflow |
+
+Cross-link: `reference/motion.md` — `prefers-reduced-motion`: disable indicator slide + panel fade
+
+---
+
+## Do / Don't
+
+### Do
+- Use roving tabindex — `tabindex="0"` on selected, `tabindex="-1"` on all others *(WAI-ARIA APG)*
+- Navigate with arrow keys between tabs, not Tab key *(WAI-ARIA APG)*
+- Label the tablist with `aria-label` or `aria-labelledby` *(WAI-ARIA APG)*
+- Hide inactive panels with `hidden` attribute so AT skips them *(WAI-ARIA APG)*
+
+### Don't
+- Don't use Tab key to navigate between tabs — Tab moves in/out of the tablist *(WAI-ARIA APG)*
+- Don't show all tab panel content simultaneously — defeats the purpose of tabs *(all systems)*
+- Don't use more than 7 tabs in a horizontal tab strip — prefer a select or dropdown for overflow *(Carbon, Atlassian)*
+- Don't use tabs for steps that must be completed in order — use a stepper *(Material 3, Atlassian)*
+
+---
+
+## Anti-patterns Cross-links
+
+| Anti-pattern | Entry |
+|--------------|-------|
+| Tab navigation with Tab key (not arrow keys) | `reference/anti-patterns.md` |
+| All panels visible simultaneously | `reference/anti-patterns.md` |
+
+---
+
+## Benchmark Citations
+
+| Claim | Sources |
+|-------|---------|
+| Arrow keys navigate tablist | WAI-ARIA APG §3.2 |
+| Tab moves in/out of tablist | WAI-ARIA APG §3.2 |
+| Roving tabindex pattern | WAI-ARIA APG |
+| hidden attr on inactive panels | WAI-ARIA APG |
+| aria-selected="true" on active tab | WAI-ARIA APG, all systems |
+
+Full system URLs: `connections/design-corpora.md`
+
+---
+
+## Grep Signatures
+
+```bash
+# Tabs using Tab key navigation instead of arrow keys
+grep -rn 'role="tab"' src/ | xargs grep -l 'onKeyDown.*Tab\|key.*Tab' 2>/dev/null | grep -v 'ArrowLeft\|ArrowRight'
+
+# Tab missing aria-selected
+grep -rn 'role="tab"' src/ | grep -v 'aria-selected'
+
+# Inactive panel not hidden (just CSS)
+grep -rn 'role="tabpanel"' src/ | grep -v 'hidden\|aria-hidden'
+
+# tablist missing accessible label
+grep -rn 'role="tablist"' src/ | grep -v 'aria-label\|aria-labelledby'
+```
+
+---
+
+## Failing Example
+
+```html
+<!-- BAD: tabs using Tab key for navigation + no aria attributes -->
+<div class="tab-list">
+  <button class="tab active">Overview</button>
+  <button class="tab">Details</button>
+  <button class="tab">Reviews</button>
+</div>
+<div class="tab-panel active">Overview content</div>
+<div class="tab-panel">Details content</div>
+<div class="tab-panel">Reviews content</div>
+```
+
+**Why it fails**: No `role="tablist"`, `role="tab"`, `role="tabpanel"`. No `aria-selected`. No `aria-controls`/`aria-labelledby`. Tab key moves between buttons instead of arrow keys. Inactive panels are not hidden from AT.
+**Grep detection**: `grep -rn 'class.*tab\b' src/ | grep -v 'role='`
+**Fix**: Use Radix `<Tabs>` or implement WAI-ARIA tabs pattern with `role="tablist"`, `role="tab"` (with `aria-selected`, `aria-controls`, roving tabindex), `role="tabpanel"` (with `aria-labelledby`), and arrow-key handlers.