@hegemonart/get-design-done 1.15.0 → 1.16.0

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