@hegemonart/get-design-done 1.16.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/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.