@hegemonart/get-design-done 1.16.0 → 1.18.0

package/reference/components/slider.md

@@ -0,0 +1,208 @@
+# Slider — Benchmark Spec
+
+**Harvested from**: WAI-ARIA APG Slider pattern, Material 3, Radix Slider, Carbon Design System
+**Wave**: 5 · **Category**: Advanced
+**Spec file**: `reference/components/slider.md`
+
+---
+
+## Purpose
+
+A Slider lets users select a numeric value (or range of values) by dragging a thumb along a track. It is appropriate when the range of values is meaningful as a continuum — volume, price, opacity, temperature — and the exact numeric value matters less than relative position. For precise numeric entry, pair the slider with a text input. For a range, use two thumbs. *(Material 3, Carbon, Radix agree: slider = continuous or discrete value selection with visual track.)*
+
+---
+
+## Anatomy
+
+```
+Single:
+[ ●────────────────────── ]  ← track
+   thumb
+
+Range:
+[ ──────●────────●──────── ]
+        min      max
+        thumb    thumb
+```
+
+| Part | Required | Notes |
+|------|----------|-------|
+| Track | Yes | Full-width bar; inactive segments use muted color |
+| Active range fill | Yes | Filled portion between min-edge and thumb (single) or between thumbs (range) |
+| Thumb | Yes | Draggable handle; visual ≥12px; touch target ≥44px via ::before padding |
+| Value label (tooltip) | No | Shows current value above/beside thumb on interaction |
+| Tick marks | No | Shown for discrete steps when ≤10 steps |
+| Min/Max labels | No | Static text at track ends |
+| Numeric input | No | Paired `<input type="number">` for precise entry |
+
+---
+
+## Variants
+
+| Variant | Description | Systems |
+|---------|-------------|---------|
+| Single | One thumb; selects a scalar value | WAI-ARIA APG, Material 3, Carbon, Radix |
+| Range | Two thumbs; selects min and max of a range | Material 3 (RangeSlider), Carbon, Radix |
+| Discrete | Step-snapping with tick marks (≤10 steps) | Material 3, Carbon |
+| Continuous | No snapping; free movement | Material 3, Carbon, Radix |
+| Vertical | `aria-orientation="vertical"`; track runs top-to-bottom | WAI-ARIA APG, Carbon |
+
+**Norm** (≥3/4 systems agree): horizontal orientation is default; thumb is a circle on a horizontal track; active range fills in brand color.
+**Diverge**: Carbon shows tick labels below the track; Material 3 shows a floating value tooltip on drag; Radix delegates tooltip entirely to the consumer.
+
+---
+
+## States
+
+| State | Trigger | Visual | ARIA |
+|-------|---------|--------|------|
+| default | — | Track + thumb at resting position | `aria-valuenow` reflects current value |
+| hover | Pointer over thumb | Thumb expands or shows halo | — |
+| focus | Keyboard focus on thumb | Focus-visible ring on thumb | — |
+| dragging / active | Mousedown / touch on thumb | Value tooltip visible; thumb slightly enlarged | — |
+| disabled | `disabled` / `aria-disabled` | 38% opacity; cursor: not-allowed | `aria-disabled="true"` |
+
+---
+
+## Sizing & Spacing
+
+| Size | Track Height | Thumb Visual | Thumb Hit Area | Notes |
+|------|-------------|--------------|----------------|-------|
+| sm | 2px | 12px | 44px (via ::before) | Compact; pair with numeric input |
+| md (default) | 4px | 20px | 44px (via ::before) | Standard; tick labels at 14px |
+| lg | 6px | 24px | 44px | High-emphasis; price/volume controls |
+
+**Norm**: 4px track height (Material 3, Carbon). Thumb visual diameter 20px with ::before/::after expanding the touch target to ≥44px without inflating layout.
+
+Cross-link: `reference/surfaces.md` — 44×44px touch-target minimum; use padding trick, not enlarged visual.
+
+---
+
+## Typography
+
+- Value tooltip: caption-sm, weight 500, centered above thumb
+- Tick labels: caption-xs, secondary color, centered below tick mark
+- Min/Max endpoint labels: caption-sm, secondary color, flush with track ends
+
+Cross-link: `reference/typography.md` — tabular-nums on value tooltip so digits don't shift width during drag.
+
+---
+
+## Keyboard & Accessibility
+
+> **WAI-ARIA role**: `slider`
+> **Required attributes**: `aria-valuenow`, `aria-valuemin`, `aria-valuemax`; `aria-valuetext` for human-readable value (e.g., "$45" or "45%"); `aria-label` or `aria-labelledby`; `aria-orientation="vertical"` when vertical
+
+### Keyboard Contract
+
+*Quoted verbatim from WAI-ARIA APG — https://www.w3.org/WAI/ARIA/apg/patterns/slider/ — W3C — 2024*
+
+| Key | Action |
+|-----|--------|
+| Right Arrow / Up Arrow | Increase value by one step |
+| Left Arrow / Down Arrow | Decrease value by one step |
+| Page Up | Increase value by a larger step (typically 10% of range) |
+| Page Down | Decrease value by a larger step (typically 10% of range) |
+| Home | Set value to minimum |
+| End | Set value to maximum |
+
+*For vertical slider (`aria-orientation="vertical"`), Up Arrow increases and Down Arrow decreases.*
+
+### Accessibility Rules
+
+- Every slider thumb MUST have `aria-valuenow`; update it continuously during drag
+- `aria-valuetext` MUST be provided when raw number is not human-readable (e.g., "Low", "Medium", "High" for a quality setting, or "$45" for a price)
+- Range slider: label each thumb distinctly (e.g., `aria-label="Minimum price"` and `aria-label="Maximum price"`) — identical labels confuse screen readers
+- Thumb touch target MUST be ≥44×44px; use `::before`/`::after` pseudo-element padding if visual thumb is smaller
+- Do not use `<input type="range">` hidden behind a custom div without ARIA — the native element is preferable when no custom styling is required
+- Disabled sliders: use `aria-disabled="true"`; keep thumb in tab order so AT can announce the current value
+
+Cross-link: `reference/accessibility.md` — slider role, aria-valuetext guidance.
+
+---
+
+## Motion
+
+| Transition | Duration | Easing | Notes |
+|------------|----------|--------|-------|
+| Thumb drag | 0ms | — | No easing on drag — follows pointer exactly |
+| Keyboard step | 80ms | ease-out | Smooth snap to new position |
+| Value tooltip appear | 100ms | ease-out | Fade in on focus/drag |
+| Value tooltip dismiss | 150ms | ease-in | Fade out on blur |
+| Tick mark appear | 120ms | ease-out | When switching to discrete mode |
+
+**BAN**: Do not add momentum or inertia easing to thumb drag — feels broken and breaks accessibility (thumb does not match pointer).
+
+Cross-link: `reference/motion.md` — reduced-motion: remove keyboard-step animation; thumb jumps instantly.
+
+---
+
+## Do / Don't
+
+### Do
+- Provide `aria-valuetext` with a human-readable label when the raw number needs context *(WAI-ARIA APG)*
+- Give each range thumb a unique, descriptive `aria-label` *(WAI-ARIA APG, Radix Slider docs)*
+- Expand thumb touch target to ≥44px with pseudo-element padding *(Material 3, Carbon)*
+- Show tick marks only for discrete sliders with ≤10 steps *(Material 3, Carbon)*
+
+### Don't
+- Don't build a slider from `<div>` with mouse events only — no keyboard, no ARIA *(diverges from all 4 systems)*
+- Don't omit `aria-valuenow` updates during drag — AT users hear a stale value *(WAI-ARIA APG)*
+- Don't let the visual thumb area be smaller than 12px with no hit-area expansion — fails WCAG 2.5.8 *(Material 3)*
+- Don't use identical `aria-label` for both range thumbs *(WAI-ARIA APG)*
+
+---
+
+## Anti-patterns Cross-links
+
+| Anti-pattern | Entry |
+|--------------|-------|
+| BAN-09 | Custom interactive widget with mouse events only, no keyboard — `reference/anti-patterns.md#ban-09` |
+| BAN-11 | Touch target below 44px without padding expansion — `reference/anti-patterns.md#ban-11` |
+
+---
+
+## Benchmark Citations
+
+| Claim | Sources |
+|-------|---------|
+| role="slider" + aria-valuenow/min/max required | WAI-ARIA APG Slider pattern |
+| Arrow key step, Page key 10% step, Home/End to extremes | WAI-ARIA APG keyboard contract |
+| 4px track height default | Material 3, Carbon |
+| Thumb touch target ≥44px via pseudo-element | Material 3, Carbon accessibility guidelines |
+| aria-valuetext for non-numeric human-readable values | WAI-ARIA APG, Radix Slider docs |
+
+Full system URLs: `connections/design-corpora.md`
+
+---
+
+## Grep Signatures
+
+```bash
+# Slider thumb missing aria-valuenow (ARIA contract violation)
+grep -rn 'role="slider"' src/ | grep -v 'aria-valuenow'
+
+# Custom slider div with mouse events only — no keyboard handler
+grep -rn 'class.*slider\|\.slider' src/ | grep 'onMouseDown\|mousedown' | grep -v 'onKeyDown\|keydown\|role="slider"'
+
+# Thumb element potentially below 44px with no hit-area expansion
+grep -rn '\.thumb\|slider-thumb' src/ | grep 'width:\s*[0-9]\{1,2\}px\|height:\s*[0-9]\{1,2\}px' | grep -v '::before\|::after\|padding'
+
+# Range slider thumbs with identical aria-label
+grep -rn 'role="slider"' src/ -A2 | grep 'aria-label' | sort | uniq -d
+```
+
+---
+
+## Failing Example
+
+```html
+<!-- BAD: custom slider using <div> with mouse events only — no keyboard, no ARIA -->
+<div class="slider-track" onmousedown="startDrag(event)">
+  <div class="slider-thumb" style="left: 45%"></div>
+</div>
+```
+
+**Why it fails**: Not reachable by keyboard; no `role="slider"`; no `aria-valuenow`, `aria-valuemin`, or `aria-valuemax`; AT cannot read or change the value; touch users cannot interact via assistive touch.
+**Grep detection**: `grep -rn '<div.*slider\|class="slider' src/ | grep -v 'role="slider"'`
+**Fix**: Use native `<input type="range">` or add `role="slider"` + `aria-valuenow` + `aria-valuemin` + `aria-valuemax` + `aria-valuetext` + full keyboard event handlers (Arrow, Page, Home, End) to the thumb element.

package/reference/components/stepper.md

@@ -0,0 +1,220 @@
+# Stepper / Wizard — Benchmark Spec
+
+**Harvested from**: Carbon (ProgressIndicator + StepNavigation), Material 3 Stepper, Atlassian Design System, Mantine Stepper
+**Wave**: 5 · **Category**: Advanced
+**Spec file**: `reference/components/stepper.md`
+
+---
+
+## Purpose
+
+A Stepper (or Wizard) guides users through a sequential multi-step flow — onboarding, checkout, multi-page forms, settings setup. It communicates how many steps exist, which step is current, which are complete, and which are upcoming. Unlike Tabs (free navigation), a linear Stepper enforces order: the user must complete the current step before advancing. *(Carbon, Material 3, Atlassian, Mantine agree: step indicator list + content area + explicit Next/Back buttons is the canonical wizard pattern.)*
+
+---
+
+## Anatomy
+
+```
+Step indicator (role="list"):
+  ● Step 1: Account    ✓ Step 2: Profile    ○ Step 3: Confirm
+  aria-current="step"  completed             upcoming
+
+Content area:
+  [ Current step form/content ]
+
+Actions:
+  [ Back ]                              [ Next ] / [ Submit ]
+```
+
+| Part | Required | Notes |
+|------|----------|-------|
+| Step indicator list | Yes | `role="list"`; each step is `role="listitem"` |
+| Step labels | Yes | Visible text per step; described state (e.g., "completed") |
+| Current step marker | Yes | `aria-current="step"` on active step |
+| Content area | Yes | Shows current step content (single panel or accordion) |
+| Next button | Yes | Explicit label "Next" or "Continue"; validates current step first |
+| Back button | Yes (if non-first step) | Returns to previous step; "Back" label |
+| Submit button | Yes (final step) | "Submit" or context-specific label; replaces Next on last step |
+| Step connector line | No | Visual line between step dots; decorative, `aria-hidden="true"` |
+
+---
+
+## Variants
+
+| Variant | Description | Systems |
+|---------|-------------|---------|
+| Linear / locked | Must complete steps in order; no jumping ahead | Carbon, Material 3, Atlassian, Mantine |
+| Non-linear | Can jump to any previously completed step | Carbon (StepNavigation), Mantine (allowNextStepsSelect) |
+| Horizontal | Step indicators in a row across the top | All systems (default) |
+| Vertical | Step indicators stacked on the left | Carbon, Material 3 |
+| Accordion stepper | All steps visible; current step expanded | Material 3 (docked), Mantine (vertical) |
+| Simple (no icons) | Text + number only, no check icons | Atlassian (compact) |
+
+**Norm** (≥3/4 systems agree): horizontal orientation is default; completed steps show a checkmark; current step is visually distinct; upcoming steps are muted.
+**Diverge**: Material 3 uses filled circles with numbers; Carbon uses custom step icons; Mantine supports icons per step; Atlassian uses numbered circles.
+
+---
+
+## States
+
+| State | Trigger | Visual | ARIA |
+|-------|---------|--------|------|
+| upcoming | Step not yet reached | Muted circle/number, secondary text color | — |
+| current | Active step | Brand-color filled circle; bold label | `aria-current="step"` |
+| completed | Step passed + valid | Check icon; full-opacity; clickable if non-linear | `aria-label="Step N: [name] - completed"` |
+| error | Step has validation errors | Error color circle; error icon | `aria-label="Step N: [name] - has errors"` |
+| disabled | Future step in linear flow | Muted; not clickable | Implicit (no click handler; cursor: default) |
+
+---
+
+## Sizing & Spacing
+
+| Size | Step Circle | Connector Height | Label Font | Gap Between Steps |
+|------|-------------|-----------------|------------|-------------------|
+| sm | 20px | 1px | 12px | 32px |
+| md (default) | 32px | 2px | 14px | 48px |
+| lg | 40px | 2px | 16px | 64px |
+
+**Norm**: Step circles 32px default *(Carbon, Mantine)*. Horizontal spacing between steps should scale with the available width so the indicator spans the container. Connector line is centered between circles.
+
+Cross-link: `reference/surfaces.md` — minimum 44×44px touch target for clickable step indicators.
+
+---
+
+## Typography
+
+- Step label: body-sm (completed/upcoming) → body-sm weight 600 (current)
+- Step number/icon inside circle: caption-sm, center-aligned
+- Step description (optional sub-label): caption-sm, secondary color
+- Action buttons: body-md, weight 500 — same as standard button spec
+
+Cross-link: `reference/typography.md` — label weight change for current state.
+
+---
+
+## Keyboard & Accessibility
+
+> **WAI-ARIA role**: `list` (step indicator container), `listitem` (each step), `button` (clickable completed steps in non-linear mode)
+> **Required attributes**: `aria-current="step"` on active step; descriptive `aria-label` on completed steps (include state: "Step 2: Profile - completed"); `aria-label` on connector lines if not `aria-hidden`
+
+### Keyboard Contract
+
+*Derived from WAI-ARIA APG list and button patterns — https://www.w3.org/WAI/ARIA/apg/ — W3C — 2024*
+
+| Key | Action |
+|-----|--------|
+| Tab | Move focus through interactive elements: clickable completed steps (non-linear), Back button, Next/Submit button |
+| Enter / Space | Activate focused Back, Next, Submit button; activate clickable completed step (non-linear) |
+| (No arrow-key navigation) | Steps are NOT tabs — do not implement roving tabindex / arrow-key navigation between steps |
+
+Steps are NOT `role="tab"` and do not use the tab keyboard pattern. Upcoming steps are not focusable in linear mode. Only completed steps are interactive (and focusable) in non-linear mode.
+
+### Accessibility Rules
+
+- Step indicators MUST use `role="list"` + `role="listitem"` — not `role="tablist"` + `role="tab"` (tabs allow free navigation; wizard steps do not)
+- Current step MUST have `aria-current="step"` — this is the correct token (not `aria-selected` or `aria-checked`)
+- Completed steps in non-linear mode MUST be `<button>` elements (or have `role="button"` + `tabindex="0"`) with `aria-label` including the step name and "completed" state
+- Step connector lines MUST be `aria-hidden="true"` — they are purely decorative
+- Validate current step before allowing Next; display inline error messages with `aria-describedby` associations
+- "Next", "Back", and "Submit" MUST be explicit text labels — do not use icon-only navigation buttons
+- Announce step transitions via `aria-live="polite"` on the content region header (e.g., "Step 2 of 4: Profile")
+
+Cross-link: `reference/accessibility.md` — aria-current values, list semantics.
+
+---
+
+## Motion
+
+| Transition | Duration | Easing | Notes |
+|------------|----------|--------|-------|
+| Step complete animation | 200ms | ease-out | Circle fill → checkmark draw |
+| Content area transition | 250ms | ease-in-out | Fade or slide left/right between steps |
+| Error state appear | 150ms | ease-out | Circle color change + icon fade in |
+| Back navigation | 200ms | ease-in-out | Slide right (reverse direction) |
+
+**BAN**: Do not use the same slide direction for both forward and backward step navigation — direction must be consistent with the mental model (forward = left, backward = right).
+
+Cross-link: `reference/motion.md` — reduced-motion: skip slide; cross-fade content area only.
+
+---
+
+## Do / Don't
+
+### Do
+- Use `role="list"` for the step indicator — steps are a list, not a tab set *(WAI-ARIA APG, Carbon)*
+- Set `aria-current="step"` on the active step *(WAI-ARIA spec §aria-current)*
+- Validate the current step before advancing and show inline errors *(Carbon, Atlassian)*
+- Label Back/Next/Submit buttons explicitly — not icons or chevrons *(Material 3, Carbon, Mantine)*
+
+### Don't
+- Don't use `role="tablist"` for steps — tabs allow free navigation; wizard steps are ordered and gated *(diverges from all 4 systems)*
+- Don't allow jumping to future unvisited steps in linear mode — breaks the sequential contract *(Carbon, Atlassian)*
+- Don't use `aria-selected` on steps — `aria-current="step"` is the correct token *(WAI-ARIA spec)*
+- Don't omit the Back button — users must be able to correct previous steps *(Material 3, Atlassian)*
+
+---
+
+## Anti-patterns Cross-links
+
+| Anti-pattern | Entry |
+|--------------|-------|
+| BAN-14 | Stepper using role="tablist" — semantically incorrect navigation model — `reference/anti-patterns.md#ban-14` |
+| BAN-07 | Missing aria-current on active step — `reference/anti-patterns.md#ban-07` |
+
+---
+
+## Benchmark Citations
+
+| Claim | Sources |
+|-------|---------|
+| Step indicator is role="list", not role="tablist" | WAI-ARIA APG, Carbon, Atlassian design docs |
+| aria-current="step" on active step | WAI-ARIA spec §aria-current, Carbon a11y guide |
+| Completed steps need aria-label with state | Carbon ProgressIndicator a11y docs, Atlassian |
+| Validate before Next; show inline errors | Carbon, Atlassian wizard pattern guidelines |
+| Explicit Next/Back/Submit text labels required | Material 3, Carbon, Mantine |
+
+Full system URLs: `connections/design-corpora.md`
+
+---
+
+## Grep Signatures
+
+```bash
+# Step indicator using role="tablist" (incorrect — steps are not tabs)
+grep -rn 'stepper\|wizard\|step-indicator\|StepIndicator' src/ | grep 'role="tablist"'
+
+# Missing aria-current on active step
+grep -rn 'stepper\|wizard\|\.step\b\|step--active\|step--current' src/ | grep -v 'aria-current'
+
+# Step connector lines not aria-hidden (extraneous AT noise)
+grep -rn 'step.*connector\|connector.*step\|\.step-line\|StepConnector' src/ | grep -v 'aria-hidden'
+
+# Icon-only Next/Back buttons (no text label)
+grep -rn 'wizard.*next\|stepper.*next\|wizard.*back\|stepper.*back' src/ | grep -v 'Next\|Back\|Continue\|Submit\|aria-label'
+```
+
+---
+
+## Failing Example
+
+```html
+<!-- BAD: stepper using <ul role="tablist"> with <li role="tab"> — semantically wrong -->
+<ul role="tablist" class="stepper">
+  <li role="tab" aria-selected="true" class="step step--active">
+    <span class="step-number">1</span>
+    <span class="step-label">Account</span>
+  </li>
+  <li role="tab" aria-selected="false" class="step step--upcoming">
+    <span class="step-number">2</span>
+    <span class="step-label">Profile</span>
+  </li>
+  <li role="tab" aria-selected="false" class="step step--upcoming">
+    <span class="step-number">3</span>
+    <span class="step-label">Confirm</span>
+  </li>
+</ul>
+```
+
+**Why it fails**: `role="tablist"` implies that all tabs are independently activatable and content switches freely — this is correct for Tabs but wrong for a wizard where steps are gated. AT users expect arrow-key navigation between tabs; in a wizard this would allow jumping to uncompleted future steps. `aria-selected` is the tab token; the correct token for a wizard is `aria-current="step"`.
+**Grep detection**: `grep -rn 'role="tablist"' src/ | grep -i 'step\|wizard'`
+**Fix**: Replace `<ul role="tablist">` with `<ol role="list">` (ordered list signals sequence), each `<li>` with `role="listitem"`, remove `aria-selected`, and add `aria-current="step"` to the current step. Make only completed steps keyboard-focusable (as `<button>`) in non-linear mode; upcoming steps are not interactive.

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.