@hegemonart/get-design-done 1.16.0 → 1.19.0

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

@@ -0,0 +1,200 @@
+# Toast / Snackbar — Benchmark Spec
+
+**Harvested from**: Radix UI Toast, Material 3 (Snackbar), Polaris (Toast), Carbon (Notification Toast)
+**Wave**: 3 · **Category**: Feedback
+
+---
+
+## Purpose
+
+A toast (snackbar) is a transient, non-blocking notification that appears briefly to confirm a completed action or communicate a system status. It auto-dismisses after 4–8 seconds (configurable) and does not require user acknowledgement for info/success variants. Use toast for low-urgency, time-sensitive feedback (save-confirmation, settings-saved). For persistent in-page messaging that demands attention, use Alert. *(Radix, Material 3, Polaris, Carbon agree: toast = ephemeral, non-blocking)*
+
+---
+
+## Anatomy
+
+```
+┌──────────────────────────────────────────────┐
+│ [icon?]  Message text              [Action?] [✕?] │
+└──────────────────────────────────────────────┘
+         ↑ role="status" or role="alert"
+         ↑ positioned: bottom-right (default)
+```
+
+| Part | Required | Notes |
+|------|----------|-------|
+| Container | Yes | Positioned overlay; `role="status"` or `role="alert"` |
+| Message text | Yes | Concise (≤80 chars); describes what happened |
+| Severity icon | No | Reinforces variant; never sole differentiator |
+| Action button | No | Single CTA, max 2 words (e.g. "Undo", "View") |
+| Dismiss button | No | Required when auto-dismiss is disabled or severity is error |
+| Progress indicator | No | Optional strip showing remaining display time |
+
+---
+
+## Variants
+
+| Variant | Description | Systems |
+|---------|-------------|---------|
+| Info | Neutral status update; `role="status"` polite | Radix, Material 3, Polaris, Carbon |
+| Success | Confirmed completion; `role="status"` polite | All |
+| Warning | Action may have side effects; `role="alert"` assertive | Material 3, Carbon, Polaris |
+| Error | Failure requiring attention; `role="alert"` assertive; persistent | All |
+
+**Norm** (≥4/18 systems agree): info/success use polite live region; warning/error use assertive; error variant is persistent (no auto-dismiss) or has explicit dismiss.
+**Diverge**: Material 3 calls this "Snackbar" (single action, no icon); Carbon calls it "Toast notification" (icon required). Polaris uses icon + title for structured variant. All converge on the transient + positioned pattern.
+
+---
+
+## States
+
+| State | Trigger | Visual | ARIA |
+|-------|---------|--------|------|
+| entering | mount | Slide-in from bottom-right + fade-in, 200ms ease-out | Live region populated |
+| visible | auto | Full opacity, static position | `role="status"` or `role="alert"` |
+| hover / focus | pointer/keyboard | Auto-dismiss timer paused | — |
+| exiting | dismiss / timeout | Slide-out + fade-out, 150ms ease-in | Removed from DOM |
+| queued | >3 toasts active | Off-screen; waits for visible slot | Not yet in DOM |
+
+---
+
+## Sizing & Spacing
+
+| Property | Value | Notes |
+|----------|-------|-------|
+| Min width | 288px | Prevents squished single-word toasts |
+| Max width | 400px | *(Material 3: 344px, Carbon: 480px)* |
+| Padding | 12px 16px | |
+| Gap between stacked | 8px | Toasts stack vertically; max 3 visible |
+| Border radius | 8px | *(Material 3: 4px, Polaris: 8px, Carbon: 0px)* |
+| Position (default) | bottom-right | 16–24px from viewport edge |
+
+**Norm**: Stack vertically with 8px gap; max 3 visible, queue the rest *(Radix, Polaris, Carbon)*.
+
+---
+
+## Typography
+
+- Message: body-sm (14px/400) — same as body to ensure readability at a glance
+- Action label: label-sm (13px/500) — slightly heavier to signal interactivity
+- No wrapping beyond 2 lines — if message exceeds 2 lines, use Alert instead
+
+Cross-link: `reference/typography.md` — body-sm, label-sm definitions
+
+---
+
+## Keyboard & Accessibility
+
+> **WAI-ARIA role**: `status` (info/success) or `alert` (warning/error)
+> **Required attributes**: `role` on container; `aria-label` on dismiss button; `aria-live` region must be pre-mounted in DOM
+
+### Keyboard Contract
+
+*Quoted verbatim from WAI-ARIA APG — https://www.w3.org/WAI/ARIA/apg/patterns/alert/ — W3C — 2024*
+
+| Key | Action |
+|-----|--------|
+| Tab | Moves focus to action button or dismiss button if present |
+| Enter / Space | Activates focused action or dismiss button |
+| Escape | Dismisses the toast (pauses timer first if hovering) |
+
+Toast container itself is not focusable. Only interactive children (action, dismiss) receive focus.
+
+### Accessibility Rules
+
+- `role="alert"` on warning/error toasts causes immediate announcement by screen readers — do NOT use for info/success (too noisy)
+- `role="status"` on info/success uses a polite live region — announced at next opportunity
+- The live region container MUST be present in the DOM before the toast text is injected — injecting `role="alert"` dynamically may not announce *(WCAG 4.1.3)*
+- Dismiss button MUST have `aria-label="Dismiss notification"` or similar — the ✕ icon alone is not an accessible name
+- Auto-dismiss timer MUST pause when the toast is hovered or focused *(WCAG 2.2.1 — Timing Adjustable)*
+- Error toasts MUST either be persistent or have an explicit dismiss mechanism *(Polaris, Carbon)*
+
+Cross-link: `reference/accessibility.md` — live-regions section
+
+---
+
+## Motion
+
+| Transition | Duration | Easing | Notes |
+|------------|----------|--------|-------|
+| Enter (slide-in + fade) | 200ms | ease-out | Slides from bottom-right edge inward |
+| Exit (slide-out + fade) | 150ms | ease-in | Reverse direction on dismiss |
+| Stack reflow | 150ms | ease-out | Other toasts shift position when one exits |
+
+**BAN**: Bouncing or spring physics on enter — toast is informational, not celebratory. Avoid `transition: all` (catches layout shifts during stack reflow).
+
+Cross-link: `reference/motion.md` — `prefers-reduced-motion`: skip slide, use fade-only at 100ms
+
+---
+
+## Do / Don't
+
+### Do
+- Use `role="status"` for info/success and `role="alert"` for warning/error *(WAI-ARIA APG)*
+- Pre-mount the live region container in the DOM before injecting toast content *(WCAG 4.1.3)*
+- Pause auto-dismiss timer on hover and focus *(WCAG 2.2.1)*
+- Keep message text ≤80 characters; use action button for follow-up *(Material 3, Polaris)*
+
+### Don't
+- Don't use toast for errors that require user action — use a modal or alert *(Material 3, Carbon)*
+- Don't stack more than 3 toasts — queue the rest *(Radix, Polaris)*
+- Don't put more than one action in a toast — use a modal for complex decisions *(Material 3)*
+- Don't rely on toast alone for critical status — supplement with in-page feedback *(Carbon)*
+
+---
+
+## Anti-patterns Cross-links
+
+| Anti-pattern | Entry |
+|--------------|-------|
+| Missing live region role | `reference/anti-patterns.md#ban-live-region` |
+| Auto-dismiss without pause on hover | `reference/anti-patterns.md#ban-timing` |
+
+---
+
+## Benchmark Citations
+
+| Claim | Sources |
+|-------|---------|
+| role="alert" for error/warning; role="status" for info/success | WAI-ARIA APG, Material 3, Carbon, Polaris |
+| Auto-dismiss 4–8s; error toasts persistent | Radix, Material 3, Polaris, Carbon |
+| Max 3 visible toasts, queue rest | Radix, Polaris |
+| Pause timer on hover/focus (WCAG 2.2.1) | WAI-ARIA APG |
+| Pre-mount live region before injecting text | WCAG 4.1.3 |
+| UUPM save-confirmation / settings-saved patterns | UUPM app-interface (MIT) |
+
+Full system URLs: `connections/design-corpora.md`
+
+---
+
+## Grep Signatures
+
+```bash
+# Error toast missing role="alert" — uses role="status" instead
+grep -rn 'toast\|Toast\|snackbar' src/ | grep 'error\|Error\|danger' | grep -v 'role="alert"'
+
+# Toast missing any role attribute
+grep -rn 'toast\|Toast\|snackbar' src/ | grep -v 'role='
+
+# Missing aria-live region (live region not pre-mounted)
+grep -rn 'toast\|Toast' src/ | grep -v 'aria-live\|role="status"\|role="alert"'
+
+# Dismiss button missing aria-label
+grep -rn 'toast.*close\|toast.*dismiss\|close.*toast' src/ | grep -v 'aria-label'
+```
+
+---
+
+## Failing Example
+
+```html
+<!-- BAD: toast with no role — screen readers receive no announcement -->
+<div class="toast toast--error">
+  Settings failed to save.
+  <button class="toast__close">✕</button>
+</div>
+```
+
+**Why it fails**: No `role="alert"` so screen readers do not announce the error. The ✕ dismiss button has no `aria-label`. There is no live region for the text injection.
+**Grep detection**: `grep -rn 'class.*toast' src/ | grep -v 'role='`
+**Fix**: Add `role="alert"` for error severity; add `aria-label="Dismiss notification"` to the close button; pre-mount `<div role="alert" aria-live="assertive">` in the document and inject content into it.

package/reference/components/tree.md

@@ -0,0 +1,225 @@
+# Tree View (Hierarchical Navigation) — Benchmark Spec
+
+**Harvested from**: WAI-ARIA APG, Carbon, Atlassian, Radix, Material 3
+**Wave**: 4 · **Category**: Navigation & Data
+
+---
+
+## Purpose
+
+A tree view displays hierarchical data in a collapsible structure of parent and child nodes. It is used for file systems, organisational charts, nested settings, and category navigation. Each node can be expanded (revealing children) or collapsed. Nodes may be selectable, checkable, or action-only. *(WAI-ARIA APG Tree View, Carbon TreeView, Atlassian Tree, Radix all define the tree as a hierarchical, keyboard-navigable disclosure widget)*
+
+---
+
+## Anatomy
+
+```
+<ul role="tree" aria-label="File explorer">
+  <li role="treeitem" aria-expanded="true" aria-level="1">
+    <span>📁 src</span>
+    <ul role="group">
+      <li role="treeitem" aria-level="2" aria-selected="false">
+        <span>📄 index.ts</span>
+      </li>
+      <li role="treeitem" aria-expanded="false" aria-level="2">
+        <span>📁 components</span>
+        <ul role="group">  <!-- hidden when collapsed -->
+          <li role="treeitem" aria-level="3">📄 Button.tsx</li>
+        </ul>
+      </li>
+    </ul>
+  </li>
+</ul>
+```
+
+| Part | Required | Notes |
+|------|----------|-------|
+| `role="tree"` root | Yes | On the outermost list; `aria-label` or `aria-labelledby` |
+| `role="treeitem"` | Yes | On every node `<li>` |
+| `role="group"` | Yes (on child lists) | Child `<ul>` inside an expandable `treeitem` |
+| `aria-expanded` | Required on expandable nodes | `"true"` / `"false"`; omit on leaf nodes |
+| `aria-level` | Yes | Nesting depth; starts at 1 |
+| `aria-selected` | Yes on selectable trees | `"true"` / `"false"` on each treeitem |
+| `aria-multiselectable` | No | `"true"` on `role="tree"` for multi-select |
+| `aria-busy` | Conditional | `"true"` on node while fetching children (lazy load) |
+
+---
+
+## Variants
+
+| Variant | Description | Systems |
+|---------|-------------|---------|
+| Default | Expand/collapse only; no selection | WAI-ARIA APG, Carbon |
+| Single-select | One item selectable; `aria-selected` | WAI-ARIA APG, Carbon, Radix |
+| Multi-select | Multiple items selectable; `aria-multiselectable` | WAI-ARIA APG, Carbon |
+| Checkbox tree | Each node has a checkbox; indeterminate state for partial parent | Carbon, Material 3 |
+| Lazy-loaded | Children fetched on expand; `aria-busy` during fetch | Carbon, Atlassian |
+| File explorer | File/folder icons; drag-to-reorder | Carbon, Radix |
+
+**Norm** (≥4 systems agree): `role="tree"` + `role="treeitem"` + `role="group"` on child lists; `aria-expanded` on parent nodes; keyboard navigation with arrow keys.
+**Diverge**: Carbon renders `aria-level` as a data attribute for CSS depth indentation; Radix computes `aria-level` implicitly from DOM nesting depth.
+
+---
+
+## States
+
+| State | Trigger | Visual | ARIA |
+|-------|---------|--------|------|
+| node-default | — | Icon + label; indented by level | — |
+| node-hover | pointer over | 8% overlay on row | — |
+| node-focus | keyboard focus | 2px focus-visible ring on row | `tabindex="0"` on focused; `-1` on rest |
+| node-selected | click or Enter/Space | Filled row highlight | `aria-selected="true"` |
+| node-expanded | toggle click or ArrowRight | Children visible; icon rotated/open | `aria-expanded="true"` |
+| node-collapsed | toggle click or ArrowLeft | Children hidden; icon closed | `aria-expanded="false"` |
+| node-loading | expand triggers fetch | Spinner icon beside label | `aria-busy="true"` |
+| node-disabled | disabled prop | 38% opacity; cursor: default | `aria-disabled="true"` |
+
+---
+
+## Sizing & Spacing
+
+| Element | Value | Notes |
+|---------|-------|-------|
+| Node height | 32–36px | Compact tree; denser than lists |
+| Level indent | 16–20px per level | CSS left-padding on `role="group"` |
+| Expand icon | 16px | Chevron or ▶ triangle; rotates on expand |
+| Node icon | 16px | File/folder/custom; left of label |
+| Max nesting depth (recommended) | 5–6 levels | Deeper trees become hard to navigate |
+
+**Norm**: 16–20px per level indentation (Carbon, Atlassian, Radix). 32–36px node height for compact data.
+
+---
+
+## Typography
+
+- Node label: body-sm (13–14px), weight 400; selected node weight 500
+- Level depth: visual indentation only — no font-size reduction per level
+- Disabled node: same font size, `color: --text-disabled`
+
+Cross-link: `reference/typography.md` — body-sm
+
+---
+
+## Keyboard & Accessibility
+
+> **WAI-ARIA role**: `tree` (root), `treeitem` (each node), `group` (child list)
+> **Required attributes**: `aria-expanded` on expandable nodes; `aria-level` on each treeitem; `aria-selected` on selectable treeitems; `aria-label` on root `role="tree"`
+
+### Keyboard Contract
+
+*Quoted verbatim from WAI-ARIA APG — https://www.w3.org/WAI/ARIA/apg/patterns/treeview/ — W3C — 2024*
+
+| Key | Action |
+|-----|--------|
+| ArrowDown | Moves focus to next visible treeitem (skips collapsed children) |
+| ArrowUp | Moves focus to previous visible treeitem |
+| ArrowRight | If collapsed: expands node. If expanded: moves focus to first child |
+| ArrowLeft | If expanded: collapses node. If collapsed: moves focus to parent |
+| Home | Moves focus to first treeitem in tree |
+| End | Moves focus to last visible treeitem in tree |
+| Enter / Space | Selects or activates focused treeitem |
+| Asterisk (*) | Expands all siblings at the same level |
+| A–Z / a–z | Jumps to next treeitem matching typed character |
+
+### Accessibility Rules
+
+- ALL expandable nodes MUST have `aria-expanded` — CSS-only expand/collapse is invisible to AT
+- `aria-level` must accurately reflect nesting depth (1-based) on every `role="treeitem"`
+- Child `<ul>` MUST have `role="group"` — without it, AT cannot perceive the parent-child relationship
+- Focus management uses roving `tabindex`: only the active node has `tabindex="0"`; all others `tabindex="-1"`
+- Lazy-loaded nodes MUST set `aria-busy="true"` while fetching; remove when complete
+- Multi-select tree MUST set `aria-multiselectable="true"` on the `role="tree"` element
+
+Cross-link: `reference/accessibility.md` — tree pattern, roving tabindex, aria-busy
+
+---
+
+## Motion
+
+| Transition | Duration | Easing | Notes |
+|------------|----------|--------|-------|
+| Expand children | 150ms | ease-out | Height expand via `overflow: hidden` |
+| Collapse children | 120ms | ease-in | Height collapse |
+| Chevron rotate | 150ms | ease-in-out | 0° → 90° on expand |
+| Node selection highlight | 100ms | ease-out | Background color only |
+| Lazy-load spinner | continuous | linear | Replace with content on load |
+
+**BAN**: Do not use CSS-only `display: none` / `display: block` to toggle children without updating `aria-expanded` — both changes must happen atomically.
+
+Cross-link: `reference/motion.md` — disclosure animations
+
+---
+
+## Do / Don't
+
+### Do
+- Use `role="tree"` + `role="treeitem"` + `role="group"` on every tree *(WAI-ARIA APG)*
+- Update `aria-expanded` in the same event handler that toggles child visibility *(WAI-ARIA APG)*
+- Use `aria-busy="true"` on a node while its children are loading *(WAI-ARIA APG, Carbon)*
+- Limit tree depth to 5–6 levels to prevent cognitive overload *(Carbon, Atlassian HIG)*
+
+### Don't
+- Don't use `<ul>/<li>` tree without `role="tree"` + `role="treeitem"` — semantically invisible to AT *(WCAG 1.3.1)*
+- Don't forget `role="group"` on child `<ul>` — AT cannot infer parent-child structure without it *(WAI-ARIA APG)*
+- Don't manage expand/collapse with CSS only (no `aria-expanded`) — blind users cannot discover collapsed state *(WCAG 4.1.2)*
+- Don't indent via `aria-level` alone — also apply visual CSS indentation for sighted users *(Material 3, Carbon)*
+
+---
+
+## Anti-patterns Cross-links
+
+| Anti-pattern | Entry |
+|--------------|-------|
+| BAN-04 | `transition: all` on tree nodes — `reference/anti-patterns.md#ban-04` |
+
+---
+
+## Benchmark Citations
+
+| Claim | Sources |
+|-------|---------|
+| role="tree" + role="treeitem" + role="group" structure | WAI-ARIA APG tree pattern |
+| aria-expanded required on all expandable nodes | WAI-ARIA APG, Carbon, Atlassian |
+| aria-level for nesting depth | WAI-ARIA APG |
+| Roving tabindex focus management | WAI-ARIA APG |
+| aria-busy="true" during lazy load | WAI-ARIA APG, Carbon |
+
+Full system URLs: `connections/design-corpora.md`
+
+---
+
+## Grep Signatures
+
+```bash
+# <ul>/<li> tree without role="tree" + role="treeitem"
+grep -rn 'tree\|file.*explorer\|folder.*tree' src/ | grep '<ul\|<li' | grep -v 'role="tree"\|role="treeitem"'
+
+# Expandable node missing aria-expanded
+grep -rn 'role="treeitem"' src/ | grep 'expand\|collaps' | grep -v 'aria-expanded'
+
+# Child list missing role="group"
+grep -rn 'role="treeitem"' src/ | grep -A 2 'aria-expanded' | grep '<ul' | grep -v 'role="group"'
+
+# Tree missing aria-label
+grep -rn 'role="tree"' src/ | grep -v 'aria-label\|aria-labelledby'
+```
+
+---
+
+## Failing Example
+
+```html
+<!-- BAD: CSS-only expand/collapse with no aria-expanded updates -->
+<ul class="tree">
+  <li class="tree-node has-children expanded">  <!-- CSS class only; no ARIA -->
+    <span onclick="toggle(this)">📁 src</span>
+    <ul class="children">  <!-- no role="group" -->
+      <li class="tree-node">📄 index.ts</li>
+    </ul>
+  </li>
+</ul>
+```
+
+**Why it fails**: No `role="tree"` or `role="treeitem"`; no `aria-expanded` — screen readers cannot tell if the node is open or closed; `role="group"` missing on child list; no `aria-level`; expand/collapse is click-only (no keyboard).
+**Grep detection**: `grep -rn 'class.*tree\|treeview' src/ | grep '<ul\|<li' | grep -v 'role='`
+**Fix**: Add `role="tree"` to root `<ul>`; `role="treeitem"` + `aria-expanded` + `aria-level` to each node; `role="group"` to child `<ul>`; implement arrow-key navigation with roving tabindex.