@hegemonart/get-design-done 1.15.0 → 1.18.0

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

@@ -0,0 +1,201 @@
+# Tooltip — Benchmark Spec
+
+**Harvested from**: WAI-ARIA APG, Radix UI, Material 3, Carbon, Mantine, Fluent 2, Atlassian, Apple HIG
+**Wave**: 2 · **Category**: Containers
+
+---
+
+## Purpose
+
+A tooltip is a small, non-interactive label that appears on hover or keyboard focus to provide supplemental context for an element (typically an icon button or truncated text). It disappears on mouse-out, blur, or Escape. Tooltips MUST NOT contain interactive content (buttons, links, form elements). For interactive overlay content, use Popover. *(WAI-ARIA APG, Radix, Carbon all enforce this boundary)*
+
+---
+
+## Anatomy
+
+```
+[Icon button]  ← hover or focus triggers tooltip
+      │
+      ▼  (after 300ms delay)
+┌────────────┐
+│  Label     │  ← role="tooltip"; 12px; no interactive content
+└────────────┘
+     ▲  (optional 6px arrow caret)
+```
+
+| Part | Required | Notes |
+|------|----------|-------|
+| Trigger | Yes | Usually a button or interactive element |
+| Tooltip container | Yes | `role="tooltip"` + unique `id` |
+| Label text | Yes | Short (≤60 chars), descriptive |
+| Arrow | No | 6–8px caret indicating anchor |
+
+---
+
+## Variants
+
+| Variant | Description | Systems |
+|---------|-------------|---------|
+| Default | Hover + focus triggered | All |
+| Delayed | 300ms show delay; 0ms hide | All (WAI-ARIA APG recommended) |
+| Instant | No delay (icon toolbars, dense UIs) | Material 3, Carbon |
+| Dark | Dark background regardless of theme | Most systems |
+| Light | Light background | Mantine (inverted) |
+
+**Norm** (≥7/18): 300ms show delay, 0ms hide; max-width 240px; never interactive content.
+**Diverge**: delay duration — Carbon recommends 100ms for toolbars; WAI-ARIA APG recommends ≤500ms. 300ms is the safe default.
+
+---
+
+## States
+
+| State | Trigger | ARIA |
+|-------|---------|------|
+| hidden | default | `role="tooltip"` hidden (not in tab order) |
+| visible (hover) | `mouseenter` (after delay) | `aria-describedby` on trigger points to tooltip id |
+| visible (focus) | `focusin` on trigger | same |
+| dismissed | `mouseleave`, `blur`, Escape | Tooltip hidden |
+
+---
+
+## Sizing & Spacing
+
+| Property | Value | Notes |
+|----------|-------|-------|
+| Max width | 240px | *(Material 3: 200px, Carbon: 288px, Fluent: 240px)* |
+| Padding | 6px 12px | |
+| Font size | 12px/400 | Smaller than body to signal supplemental role |
+| Border radius | 4–6px | Tight radius vs. card; feels like label |
+| Offset from trigger | 6–8px | |
+
+---
+
+## Typography
+
+- 12px/400 — tooltip text is supplemental; smaller weight and size distinguish it from primary content
+- No bold, no headings inside tooltip — it is a single line of text (≤60 chars preferred)
+- Multi-line: allowed if content genuinely requires it; still no interactive elements
+
+---
+
+## Keyboard & Accessibility
+
+> **WAI-ARIA role**: `tooltip`
+> **Trigger attributes**: `aria-describedby="tooltip-id"` — links the supplemental label
+
+### Keyboard Contract
+
+*Quoted verbatim from WAI-ARIA APG — https://www.w3.org/WAI/ARIA/apg/patterns/tooltip/ — W3C — 2024*
+
+| Key | Action |
+|-----|--------|
+| Tab | (on trigger) Shows tooltip when trigger receives focus |
+| Escape | Hides the tooltip |
+| Tab / Shift+Tab | Hides tooltip when focus leaves the trigger |
+
+Tooltip does NOT receive focus. It is purely a visual label attached to the trigger.
+
+### Accessibility Rules
+
+- Trigger MUST have `aria-describedby` pointing to the tooltip's `id` — screen readers read tooltip content as supplemental description
+- Tooltip is `role="tooltip"` — NOT `role="dialog"` (no interactivity, no focus trap)
+- Tooltip MUST appear on keyboard focus, not only on hover — keyboard-only users need access too *(WCAG 1.3.3, 2.1.1)*
+- Do NOT put interactive content inside a tooltip — use Popover (`reference/components/popover.md`)
+- Do NOT use tooltip as the only accessible name for a control — use `aria-label` on the trigger instead; tooltip supplements, not replaces, the accessible name
+- Escape MUST dismiss the tooltip without removing focus from the trigger *(WAI-ARIA APG)*
+
+---
+
+## Motion
+
+| Transition | Duration | Easing | Notes |
+|------------|----------|--------|-------|
+| Show | 100ms | ease-out | Fade only; no scale (too flashy for a label) |
+| Hide | 80ms | ease | Fade only; immediate on Escape |
+| Delay | 300ms | — | CSS `transition-delay` or JS timeout |
+
+Cross-link: `reference/motion.md` — `prefers-reduced-motion`: skip fade, instant show/hide
+
+---
+
+## Do / Don't
+
+### Do
+- Show on keyboard focus AND hover — not hover-only *(WAI-ARIA APG, WCAG 2.1.1)*
+- Use `aria-describedby` to link trigger to tooltip *(WAI-ARIA APG)*
+- Limit tooltip content to ≤60 chars — longer content belongs in a popover *(Carbon, Material 3)*
+- Apply 300ms show delay to prevent accidental triggers while cursor passes *(WAI-ARIA APG, Carbon)*
+
+### Don't
+- Don't put interactive elements inside a tooltip *(WAI-ARIA APG — this makes it a popover)*
+- Don't use tooltip as the only accessible name — `aria-describedby` supplements, not replaces, `aria-label` *(WAI-ARIA APG)*
+- Don't trigger tooltip on click — use a popover *(Radix, WAI-ARIA APG)*
+- Don't use tooltip for critical information — it's supplemental; users on touch devices may miss it *(Material 3, Polaris)*
+
+---
+
+## Anti-patterns Cross-links
+
+| Anti-pattern | Entry |
+|--------------|-------|
+| Interactive content inside tooltip | `reference/anti-patterns.md` |
+| Hover-only tooltip (not focus-triggered) | `reference/anti-patterns.md` |
+
+---
+
+## Benchmark Citations
+
+| Claim | Sources |
+|-------|---------|
+| role="tooltip" not role="dialog" | WAI-ARIA APG |
+| Show on focus AND hover | WAI-ARIA APG, WCAG 2.1.1 |
+| Escape dismisses without removing focus | WAI-ARIA APG §3.2 |
+| 300ms delay | WAI-ARIA APG, Carbon |
+| 240px max-width | Material 3, Fluent 2 |
+| No interactive content | WAI-ARIA APG (all systems agree) |
+
+Full system URLs: `connections/design-corpora.md`
+
+---
+
+## Grep Signatures
+
+```bash
+# Tooltip triggered only on hover (not focus) — missing focusin handler
+grep -rn 'tooltip\|Tooltip' src/ | grep 'mouseenter\|onHover' | grep -v 'focus\|onFocus'
+
+# Interactive content inside tooltip
+grep -rn 'role="tooltip"' src/ | xargs grep -l 'button\|<a \|input' 2>/dev/null
+
+# Trigger missing aria-describedby
+grep -rn 'role="tooltip"' src/ | grep -v 'aria-describedby'
+
+# Tooltip without id (aria-describedby target requires id)
+grep -rn 'role="tooltip"' src/ | grep -v ' id='
+```
+
+---
+
+## Failing Example
+
+```html
+<!-- BAD: tooltip shows on hover only, no focus trigger, no ARIA linkage -->
+<button class="icon-btn" onmouseenter="showTooltip()" onmouseleave="hideTooltip()">
+  <svg><!-- settings icon --></svg>
+</button>
+<div class="tooltip">Settings</div>
+```
+
+**Why it fails**: Keyboard users never see the tooltip. Screen readers receive no supplemental description. The `<div>` has no `role="tooltip"` and no `id`, so `aria-describedby` cannot link to it.
+**Grep detection**: `grep -rn 'mouseenter\|onHover' src/ | grep -i 'tooltip' | grep -v 'focus'`
+**Fix**:
+```html
+<button aria-describedby="settings-tip"
+        onmouseenter="show()" onmouseleave="hide()"
+        onfocusin="show()" onfocusout="hide()"
+        onkeydown="e.key==='Escape'&&hide()">
+  <svg aria-hidden="true"><!-- icon --></svg>
+  <span class="sr-only">Settings</span>
+</button>
+<div role="tooltip" id="settings-tip">Manage account settings</div>
+```

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.