@hegemonart/get-design-done 1.16.0 → 1.18.0

package/reference/components/rich-text-editor.md

@@ -0,0 +1,226 @@
+# Rich-Text Editor — Benchmark Spec
+
+**Harvested from**: Tiptap/ProseMirror, Lexical (Meta), Slate.js, Atlassian Fabric Editor
+**Wave**: 5 · **Category**: Advanced
+**Spec file**: `reference/components/rich-text-editor.md`
+
+---
+
+## Purpose
+
+A Rich-Text Editor (RTE) provides WYSIWYG content authoring with inline formatting (bold, italic, links), block-level elements (headings, lists, blockquotes), and optional advanced features (mentions, embeds, tables). It is appropriate for long-form content where plain `<textarea>` is insufficient and a full CMS-style document editor is overkill. *(Tiptap, Lexical, Atlassian agree: contenteditable + ProseMirror/Lexical model + explicit toolbar is the production-grade RTE pattern.)*
+
+---
+
+## Anatomy
+
+```
+┌── role="toolbar" aria-label="Text formatting" ──────────────────┐
+│ [B] [I] [U] [S] │ [H1][H2] │ [• List][1. List] │ [Link][Image] │
+└──────────────────────────────────────────────────────────────────┘
+┌── role="textbox" aria-multiline="true" aria-label="Post body" ──┐
+│                                                                  │
+│  Start typing here…  (placeholder via CSS ::before)             │
+│                                                                  │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+| Part | Required | Notes |
+|------|----------|-------|
+| Editable area | Yes | `contenteditable="true"` + `role="textbox"` + `aria-multiline="true"` |
+| Toolbar | Yes (for formatting) | `role="toolbar"` + `aria-label`; groups via `role="group"` |
+| Toolbar buttons | Yes | `role="button"`; toggle buttons add `aria-pressed` |
+| Placeholder | No | CSS `[data-placeholder]::before` — NOT HTML attribute |
+| Mention list | No | `role="listbox"` floating suggestion list triggered by `@` |
+| Character count | No | `aria-live="polite"` updated region |
+| Read-only overlay | No | `contenteditable="false"` + `aria-readonly="true"` |
+
+---
+
+## Variants
+
+| Variant | Description | Systems |
+|---------|-------------|---------|
+| Minimal | Bold/italic/underline + link only | Tiptap (StarterKit minimal), Atlassian (inline comment) |
+| Standard | Full paragraph formatting + lists + links | Tiptap, Lexical, Slate |
+| Document | Full editor with headings, tables, embeds, mentions | Atlassian Fabric Editor, Tiptap (full), Lexical (full) |
+| Read-only | Rendered content; no editing | All systems |
+| Bubble toolbar | Formatting toolbar appears on text selection (tooltip style) | Tiptap, Atlassian inline editor |
+
+**Norm** (≥3/4 systems agree): toolbar at top or on selection; contenteditable with explicit role="textbox"; keyboard shortcuts for core formatting.
+**Diverge**: Atlassian uses a floating toolbar on selection; Tiptap supports both fixed and bubble modes; Lexical uses a plugin architecture; Slate treats everything as React tree nodes.
+
+---
+
+## States
+
+| State | Trigger | Visual | ARIA |
+|-------|---------|--------|------|
+| default | — | Cursor; toolbar buttons at rest | — |
+| focused | Click or Tab into editable area | Focus ring on editable container | — |
+| toolbar button active | Text with formatting selected | `aria-pressed="true"` on toggle button | `aria-pressed="true"` |
+| placeholder | No content in editable area | Placeholder text via CSS ::before | — |
+| read-only | `readOnly` prop | No cursor change; grayed toolbar | `aria-readonly="true"`, `contenteditable="false"` |
+| disabled | `disabled` prop | 38% opacity; no interaction | `aria-disabled="true"` |
+| mention-open | `@` typed | Floating listbox appears | `role="listbox"` visible |
+| error | Validation failure | Red border; error message below | `aria-describedby` → error message |
+
+---
+
+## Sizing & Spacing
+
+| Size | Min Height | Toolbar Height | Font |
+|------|-----------|----------------|------|
+| sm | 80px | 32px | 13px |
+| md (default) | 160px | 40px | 14px |
+| lg | 320px | 48px | 16px |
+
+**Norm**: Editor area grows with content (auto-height); enforce max-height with overflow scroll if needed. Toolbar buttons follow button-sm/md sizing with 8px gaps between groups *(Atlassian, Tiptap)*.
+
+Cross-link: `reference/surfaces.md` — toolbar button hit targets.
+
+---
+
+## Typography
+
+- Editor content: body-md, line-height 1.6 for readable long-form text
+- Heading 1: 2em; Heading 2: 1.5em; Heading 3: 1.25em — relative to editor base font
+- Code blocks: monospace, 0.9em, background token surface-code
+- Placeholder text: same size/font as body, secondary color via CSS
+
+Cross-link: `reference/typography.md` — heading scale, code font stack.
+
+---
+
+## Keyboard & Accessibility
+
+> **WAI-ARIA role**: `textbox` (editable area), `toolbar` (toolbar container), `group` (toolbar sections), `button` (toolbar actions), `listbox` (mention suggestions)
+> **Required attributes**: `role="textbox"` + `aria-multiline="true"` + `aria-label` or `aria-labelledby` on editable area; `aria-pressed` on toggle toolbar buttons; `role="toolbar"` + `aria-label` on toolbar
+
+### Keyboard Contract
+
+*Derived from WAI-ARIA APG toolbar pattern — https://www.w3.org/WAI/ARIA/apg/patterns/toolbar/ — W3C — 2024, and standard contenteditable browser behavior*
+
+| Key | Action |
+|-----|--------|
+| Tab | Move focus into the editable area from outside; move out of editor |
+| Ctrl/Cmd + B | Toggle bold on selected text |
+| Ctrl/Cmd + I | Toggle italic on selected text |
+| Ctrl/Cmd + U | Toggle underline on selected text |
+| Ctrl/Cmd + Z | Undo last action |
+| Ctrl/Cmd + Shift + Z | Redo |
+| Ctrl/Cmd + K | Insert or edit link |
+| @ (in editor) | Trigger mention suggestion list |
+| Arrow keys (in listbox) | Navigate mention suggestions |
+| Enter / Space (in listbox) | Select mention suggestion |
+| Escape (in listbox) | Dismiss mention list |
+| F10 or Alt + F10 | Move focus from editable area to toolbar (accessibility shortcut) |
+| Arrow keys (in toolbar) | Move between toolbar buttons (roving tabindex) |
+| Home / End (in toolbar) | First / last toolbar button |
+
+### Accessibility Rules
+
+- Editable area MUST have `role="textbox"` — bare `contenteditable` is announced as a generic region by most AT
+- `aria-multiline="true"` MUST be set — announces correct Enter-key behavior to screen readers
+- Toolbar toggle buttons (bold, italic, lists) MUST use `aria-pressed="true/false"` to reflect current selection state
+- Placeholder MUST use CSS `[data-placeholder]::before` content — not a `placeholder` HTML attribute on contenteditable (screen readers read it incorrectly or not at all)
+- Keyboard shortcuts MUST be documented in a tooltip or help section — not assumed
+- Read-only: set both `contenteditable="false"` AND `aria-readonly="true"` — contenteditable="false" alone is insufficient for AT
+- Mention listbox MUST use `role="listbox"` with `role="option"` items; focused option uses `aria-selected="true"`
+
+Cross-link: `reference/accessibility.md` — contenteditable accessibility, toolbar pattern.
+
+---
+
+## Motion
+
+| Transition | Duration | Easing | Notes |
+|------------|----------|--------|-------|
+| Toolbar button active state | 80ms | ease-out | Background fill on aria-pressed change |
+| Mention list open | 150ms | ease-out | Fade + slide up from caret position |
+| Mention list dismiss | 100ms | ease-in | Fade out |
+| Bubble toolbar appear | 150ms | ease-out | Fade in above selection |
+| Bubble toolbar dismiss | 80ms | ease-in | Fade out on deselect |
+
+**BAN**: Do not animate text reflow on formatting changes — typing performance is critical; any CSS transition on editor content causes visual jitter.
+
+Cross-link: `reference/motion.md` — reduced-motion: remove mention list slide; keep instant formatting toggle.
+
+---
+
+## Do / Don't
+
+### Do
+- Add `role="textbox"` + `aria-multiline="true"` to the contenteditable element *(WAI-ARIA APG)*
+- Use `aria-pressed` on all toggle toolbar buttons (bold, italic, list toggles) *(WAI-ARIA APG toolbar pattern)*
+- Implement placeholder via CSS `::before` pseudo-element, not HTML attribute *(Tiptap, Atlassian)*
+- Document keyboard shortcuts in a tooltip or accessible help dialog *(Atlassian Fabric Editor)*
+
+### Don't
+- Don't use bare `contenteditable` without `role="textbox"` — AT announces it as a generic landmark *(diverges from all 4 systems)*
+- Don't omit `aria-pressed` on toggle buttons — AT users cannot determine current formatting state *(WAI-ARIA APG)*
+- Don't use a `placeholder` HTML attribute on contenteditable — it is not a valid attribute and screen reader behavior is undefined *(MDN, Tiptap docs)*
+- Don't suppress `outline` on the editable area without a custom focus-visible ring *(WCAG 2.4.7)*
+
+---
+
+## Anti-patterns Cross-links
+
+| Anti-pattern | Entry |
+|--------------|-------|
+| BAN-06 | contenteditable without role="textbox" — `reference/anti-patterns.md#ban-06` |
+| BAN-04 | transition: all on editor content causing reflow jank — `reference/anti-patterns.md#ban-04` |
+
+---
+
+## Benchmark Citations
+
+| Claim | Sources |
+|-------|---------|
+| contenteditable needs role="textbox" + aria-multiline="true" | WAI-ARIA spec, Tiptap a11y guide, Atlassian |
+| Toolbar toggle buttons need aria-pressed | WAI-ARIA APG toolbar pattern |
+| Placeholder via CSS ::before, not HTML attribute | Tiptap docs, Atlassian Fabric Editor |
+| Mention list uses role="listbox" + role="option" | Tiptap mention extension, Lexical mention plugin |
+| Ctrl/Cmd+B/I/U keyboard shortcuts are standard | Lexical, Tiptap, Slate — all implement these |
+
+Full system URLs: `connections/design-corpora.md`
+
+---
+
+## Grep Signatures
+
+```bash
+# contenteditable element missing role="textbox" (announced as generic region)
+grep -rn 'contenteditable="true"' src/ | grep -v 'role="textbox"'
+
+# Toolbar toggle buttons missing aria-pressed
+grep -rn 'role="toolbar"' src/ -A 50 | grep 'role="button"' | grep -v 'aria-pressed'
+
+# Placeholder set as HTML attribute on contenteditable (invalid)
+grep -rn 'contenteditable' src/ | grep 'placeholder='
+
+# Mention listbox missing role="listbox"
+grep -rn 'mention\|@mention\|MentionList' src/ | grep -v 'role="listbox"'
+```
+
+---
+
+## Failing Example
+
+```html
+<!-- BAD: rich-text area using only contenteditable without role="textbox" -->
+<div
+  contenteditable="true"
+  class="editor"
+  placeholder="Start writing..."
+>
+</div>
+<div class="toolbar">
+  <button onclick="document.execCommand('bold')">B</button>
+  <button onclick="document.execCommand('italic')">I</button>
+</div>
+```
+
+**Why it fails**: (1) Bare `contenteditable` is announced by most AT as a generic region, not a text input — users do not know they can type. (2) `placeholder` is not a valid HTML attribute on `<div>` — screen readers do not announce it. (3) Toolbar buttons have no `aria-pressed` — AT cannot determine if bold/italic is currently active. (4) `document.execCommand` is deprecated.
+**Grep detection**: `grep -rn 'contenteditable="true"' src/ | grep -v 'role="textbox"'`
+**Fix**: Add `role="textbox"` + `aria-multiline="true"` + `aria-label="Post body"` to the editable div; implement placeholder via CSS `[data-empty]::before { content: attr(data-placeholder) }`; add `aria-pressed="true/false"` to toolbar toggle buttons; use a modern editor library (Tiptap, Lexical) instead of execCommand.

package/reference/components/sidebar.md

@@ -0,0 +1,211 @@
+# Sidebar (Collapsible Side Navigation Panel) — Benchmark Spec
+
+**Harvested from**: Material 3, Carbon, Polaris, Atlassian, UUPM (app-interface, MIT)
+**Wave**: 4 · **Category**: Navigation
+
+---
+
+## Purpose
+
+A sidebar provides persistent or collapsible secondary navigation along the vertical axis of an application. In expanded state it shows icon + label; in collapsed state it shows icon only (with a tooltip). It is distinct from a Drawer (which is a modal overlay — see `drawer.md`) and from a Navbar (primary horizontal navigation). Use a sidebar for application-level section switching and hierarchical settings navigation. *(Material 3 Navigation Drawer, Carbon UI Shell Left Nav, Atlassian SideNavigation, Polaris Navigation agree)*
+
+---
+
+## Anatomy
+
+```
+┌─────────────────┐         ┌────┐
+│ [≡] App Name    │  ◄──►   │[≡] │  collapsed (icon-only)
+│─────────────────│         │────│
+│ 🏠 Dashboard    │         │[🏠]│  tooltip: "Dashboard"
+│ 📊 Analytics    │         │[📊]│
+│ ▾ Settings      │         │[⚙] │
+│   Account       │         └────┘
+│   Privacy       │
+│   Security      │
+└─────────────────┘
+```
+
+| Part | Required | Notes |
+|------|----------|-------|
+| `<nav>` wrapper | Yes | `role="navigation"` + `aria-label="Secondary"` |
+| Toggle button | Yes | `aria-expanded` + `aria-controls` pointing to nav |
+| Nav item | Yes | `<a>` for routing; `<button>` for non-routing actions |
+| Sub-section toggle | No | `<button>` with `aria-expanded`; chevron icon rotates |
+| Sub-section items | No | Indented child items; hidden when parent collapsed |
+| Tooltip | Conditional | On icon-only items in collapsed state; `role="tooltip"` |
+| Active indicator | Yes | `aria-current="page"` on active item |
+
+---
+
+## Variants
+
+| Variant | Description | Systems |
+|---------|-------------|---------|
+| Expanded | Icon + label visible; full width (240–280px) | All systems |
+| Collapsed / mini | Icon only; 48–64px wide; tooltips on hover/focus | Material 3, Carbon, Atlassian |
+| Floating / overlay | Overlay on top of content (mobile drawer pattern) | Material 3, Polaris |
+| Settings nav | Category tree: Settings › Account › Privacy › Security | UUPM app-interface (MIT) |
+| Dashboard nav | Section switcher: Dashboard / Analytics / Users / Settings | UUPM app-interface (MIT) |
+
+**Norm** (≥4 systems agree): expanded width 240–280px; collapsed width 48–64px; toggle button at top or bottom.
+**Diverge**: Carbon collapses to a rail (16px) with hover-expand; Material 3 differentiates between NavigationDrawer (permanent) and ModalNavigationDrawer (mobile).
+
+---
+
+## States
+
+| State | Trigger | Visual | ARIA |
+|-------|---------|--------|------|
+| expanded | default or toggle | Full width, labels visible | `aria-expanded="true"` on toggle |
+| collapsed | toggle click | Icon-only, labels hidden | `aria-expanded="false"` on toggle |
+| item-default | — | Resting fill | — |
+| item-hover | pointer over | 8% overlay | — |
+| item-focus | keyboard focus | 2px focus-visible ring | — |
+| item-active | current route | Filled pill or left indicator bar | `aria-current="page"` |
+| subsection-open | button click | Children visible; chevron rotated 180° | `aria-expanded="true"` on section button |
+| subsection-closed | button click | Children hidden | `aria-expanded="false"` on section button |
+
+---
+
+## Sizing & Spacing
+
+| State | Width | Item height | Item padding H |
+|-------|-------|-------------|----------------|
+| Expanded | 240–280px | 40px | 16px |
+| Collapsed | 48–64px | 40px | 12px (centered icon) |
+| Sub-item indent | — | 36px | 32px (16px base + 16px indent) |
+
+**Norm**: 240px expanded width (Carbon, Atlassian, Polaris). 40px item height matches button defaults.
+
+---
+
+## Typography
+
+- Nav item label: body-sm (13–14px), weight 400; active item weight 500 or 600
+- Sub-section heading (if present): label-xs (11–12px), uppercase, weight 600, `color: --text-subtle`
+- Tooltip: body-xs (11–12px) — concise, matches item label exactly in collapsed state
+- Never truncate nav item labels — resize the sidebar or abbreviate the label intentionally
+
+Cross-link: `reference/typography.md` — label scale, body-sm
+
+---
+
+## Keyboard & Accessibility
+
+> **WAI-ARIA role**: `navigation` (wrapper)
+> **Required attributes**: `aria-label="Secondary"` on `<nav>`; `aria-expanded` on toggle button and collapsible section buttons; `aria-current="page"` on active item
+
+### Keyboard Contract
+
+*Quoted verbatim from WAI-ARIA APG — https://www.w3.org/WAI/ARIA/apg/patterns/disclosure/ — W3C — 2024*
+
+| Key | Action |
+|-----|--------|
+| Tab / Shift+Tab | Moves focus through focusable items in DOM order |
+| Enter / Space | Activates focused link (navigates) or button (toggles section/sidebar) |
+| ArrowDown | Moves focus to next visible nav item (optional enhancement) |
+| ArrowUp | Moves focus to previous visible nav item (optional enhancement) |
+| Escape | Closes mobile overlay sidebar; returns focus to toggle |
+
+### Accessibility Rules
+
+- `<nav>` MUST have `aria-label="Secondary"` to distinguish from the primary navbar landmark
+- Every collapsible sub-section MUST have `aria-expanded` on its toggle button
+- Items that navigate (routing) MUST be `<a href>` links; items that only toggle state MUST be `<button>` (not `<a href="#">`)
+- In collapsed state, each icon-only item MUST have a tooltip AND `aria-label` (tooltip is not a substitute for accessible name)
+- `aria-current="page"` MUST be present on the currently active item
+
+Cross-link: `reference/accessibility.md` — landmark labelling, disclosure pattern
+
+---
+
+## Motion
+
+| Transition | Duration | Easing | Notes |
+|------------|----------|--------|-------|
+| Expand / collapse sidebar | 200ms | ease-in-out | Width transition; respect `prefers-reduced-motion` |
+| Sub-section open | 150ms | ease-out | Height expand; `overflow: hidden` clip |
+| Sub-section close | 120ms | ease-in | Height collapse |
+| Chevron rotate | 150ms | ease-in-out | 0° → 180° on open |
+| Label fade in | 100ms | ease-out | Delay until width ≥ 140px to prevent overlap |
+
+**BAN**: Animating sidebar width using `transition: all` — catches unrelated property changes and causes jank.
+
+Cross-link: `reference/motion.md` — layout transitions, BAN-04
+
+---
+
+## Do / Don't
+
+### Do
+- Use `<a href>` for routing nav items and `<button>` for non-routing actions *(Carbon, WAI-ARIA APG)*
+- Label the `<nav>` with `aria-label="Secondary"` *(WAI-ARIA APG landmark regions)*
+- Show tooltips on icon-only items in collapsed state *(Material 3, Carbon, Atlassian)*
+- Use `aria-expanded` on sub-section toggles *(WAI-ARIA APG disclosure pattern)*
+
+### Don't
+- Don't use `<a href="#">` for items that don't navigate — breaks bookmark/open-in-new-tab expectations *(Carbon, WAI-ARIA)*
+- Don't hide sub-items with `display: none` without also removing them from tab order *(WCAG 2.1.1)*
+- Don't use the same `aria-label` on both sidebar nav and top navbar *(WAI-ARIA landmark uniqueness)*
+- Don't collapse the sidebar below 44px touch target width on mobile *(WCAG 2.5.5)*
+
+---
+
+## Anti-patterns Cross-links
+
+| Anti-pattern | Entry |
+|--------------|-------|
+| BAN-04 | `transition: all` on interactive elements — `reference/anti-patterns.md#ban-04` |
+
+---
+
+## Benchmark Citations
+
+| Claim | Sources |
+|-------|---------|
+| aria-label="Secondary" distinct from Primary | WAI-ARIA APG landmark regions, WCAG 4.1.2 |
+| `<button>` for non-routing, `<a>` for routing | Carbon, WAI-ARIA APG, Primer |
+| aria-expanded on collapsible sections | WAI-ARIA APG disclosure pattern |
+| 240px expanded / 48–64px collapsed widths | Carbon, Atlassian, Polaris |
+| Tooltip on icon-only collapsed items | Material 3, Carbon, Atlassian |
+
+Full system URLs: `connections/design-corpora.md`
+
+---
+
+## Grep Signatures
+
+```bash
+# nav element missing aria-label
+grep -rn '<nav' src/ | grep -v 'aria-label\|aria-labelledby'
+
+# Collapsible section missing aria-expanded
+grep -rn 'sidebar\|sidenav\|side-nav' src/ | grep 'collapsible\|expandable\|toggle' | grep -v 'aria-expanded'
+
+# href="#" on nav items (non-routing anchor misuse)
+grep -rn 'href="#"' src/ | grep -i 'nav\|sidebar\|menu'
+
+# Active item missing aria-current
+grep -rn 'class.*active\|isActive\|is-active' src/ | grep -i 'nav.*item\|sidebar.*item' | grep -v 'aria-current'
+```
+
+---
+
+## Failing Example
+
+```html
+<!-- BAD: sidebar items using <a href="#"> for non-routing actions -->
+<nav>  <!-- missing aria-label -->
+  <a href="#">Dashboard</a>
+  <a href="#">Analytics</a>
+  <a href="#" class="active">Settings</a>  <!-- no aria-current -->
+  <a href="#">
+    Account  <!-- subsection, but no aria-expanded -->
+  </a>
+</nav>
+```
+
+**Why it fails**: `<nav>` has no label (ambiguous landmark); `<a href="#">` creates false navigation expectations and adds to browser history; active state uses CSS class only; no `aria-current="page"`; no `aria-expanded` for the sub-section.
+**Grep detection**: `grep -rn 'href="#"' src/ | grep -i 'nav\|sidebar'`
+**Fix**: Replace `<a href="#">` with `<button>` for non-routing items; add `aria-label="Secondary"` to `<nav>`; add `aria-current="page"` to active item; add `aria-expanded` to sub-section toggles.

package/reference/components/skeleton.md

@@ -0,0 +1,197 @@
+# Skeleton — Benchmark Spec
+
+**Harvested from**: Polaris, Carbon, Atlassian, Mantine
+**Wave**: 3 · **Category**: Feedback
+
+---
+
+## Purpose
+
+A skeleton screen is a loading placeholder that mirrors the shape of the content it will replace — text lines, images, cards, avatars. It reduces perceived wait time by showing the structural layout before real data arrives, preventing the jarring reflow that occurs when content suddenly appears. Use skeleton when the content shape is known; use an indeterminate spinner or progress bar when shape is unknown. *(Polaris, Carbon, Atlassian, Mantine agree: skeleton = shape-matched placeholder, not generic spinner)*
+
+---
+
+## Anatomy
+
+```
+┌──────────────────────────────────┐
+│  ████ (avatar-circle, 40px)      │  ← aria-hidden="true"
+│  ██████████████████ (text-line)  │
+│  █████████████ (text-line 75%)   │
+│  ████████████████████ (text-line)│
+└──────────────────────────────────┘
+↑ container: aria-busy="true" aria-label="Loading…"
+```
+
+| Part | Required | Notes |
+|------|----------|-------|
+| Container | Yes | `aria-busy="true"` + `aria-label="Loading…"` or `aria-labelledby` |
+| Skeleton elements | Yes | `aria-hidden="true"` on each shape element |
+| Text-line shape | No | Width 60–90% (varied) to mimic text flow |
+| Image/card block | No | Fixed aspect-ratio; fills the same space as the loaded image |
+| Avatar circle | No | Circular shape; diameter matches the final avatar size |
+
+---
+
+## Variants
+
+| Variant | Description | Systems |
+|---------|-------------|---------|
+| Text lines | One or more lines at varying widths (60–90%) | All |
+| Image block | Rectangular/aspect-ratio shape for images | Polaris, Carbon, Mantine |
+| Avatar | Circular placeholder at avatar diameter | Polaris, Atlassian, Mantine |
+| Card | Full card-sized block with text-line children | All |
+| Table row | Row-shaped block with column-width children | Carbon, Mantine |
+
+**Norm** (≥4/18 systems agree): shimmer animation (left-to-right gradient sweep); vary text-line widths 60–90%; `aria-hidden` on skeleton elements; `aria-busy` on container.
+**Diverge**: Polaris renders skeleton as named sub-components (`SkeletonBodyText`, `SkeletonDisplayText`); Carbon uses CSS class modifiers; Mantine uses a generic `Skeleton` with width/height props; Atlassian uses a shape prop.
+
+---
+
+## States
+
+| State | Trigger | Visual | ARIA |
+|-------|---------|--------|------|
+| loading | data fetch in progress | Shimmer animation looping | `aria-busy="true"` on container |
+| loaded | data resolves | Skeleton removed, real content appears | `aria-busy="false"` or remove attr |
+
+---
+
+## Sizing & Spacing
+
+| Shape | Default sizing | Notes |
+|-------|----------------|-------|
+| Text-line | 16px height | Matches body line-height slot |
+| Text-line (heading) | 24–28px height | Matches h2/h3 slot |
+| Avatar | Match target avatar diameter | 32px, 40px, 48px common |
+| Image block | Match target image aspect ratio | 16:9, 1:1, 4:3 common |
+| Gap between text lines | 8px | Matches body line-height rhythm |
+
+**Norm**: Match exact pixel dimensions of the content being replaced — layout shift score is zero when skeleton matches final content size *(Polaris, Mantine)*.
+
+---
+
+## Typography
+
+Skeleton shapes are purely visual — no typography content. However:
+- Text-line height should match the `line-height` of the real text it replaces
+- Heading skeleton height should match the heading's `font-size` + leading
+- Do NOT use placeholder text ("Loading…") inside skeleton shapes — use `aria-label` on the container instead
+
+Cross-link: `reference/typography.md` — line-height scale for matching skeleton dimensions
+
+---
+
+## Keyboard & Accessibility
+
+> **WAI-ARIA role**: no role on skeleton shapes; container uses `aria-busy`
+> **Required attributes**: `aria-hidden="true"` on each skeleton element; `aria-busy="true"` + `aria-label="Loading…"` on container
+
+### Keyboard Contract
+
+*Quoted verbatim from WAI-ARIA APG — https://www.w3.org/WAI/ARIA/apg/ — W3C — 2024*
+
+| Key | Action |
+|-----|--------|
+| (none) | Skeleton shapes are not interactive; no keyboard interaction |
+
+Skeleton elements must not receive focus. The container is not focusable unless it wraps focusable content that appears after loading.
+
+### Accessibility Rules
+
+- Every skeleton shape element MUST have `aria-hidden="true"` — blank shapes announced by screen readers ("image", "text") confuse users *(Polaris, Carbon)*
+- The container MUST have `aria-busy="true"` while loading, set to `false` (or removed) when content appears *(WAI-ARIA APG)*
+- The container MUST have `aria-label="Loading…"` or equivalent — this is what screen readers announce while `aria-busy="true"` *(WAI-ARIA APG)*
+- Do NOT use skeleton as the only loading indicator for screen reader users — announce loading state via live region if the transition is programmatic *(Carbon)*
+- Shimmer animation MUST be suppressed under `prefers-reduced-motion` — use static fill instead *(WCAG 2.3.3)*
+
+Cross-link: `reference/accessibility.md` — `aria-busy`, `prefers-reduced-motion`
+
+---
+
+## Motion
+
+| Transition | Duration | Easing | Notes |
+|------------|----------|--------|-------|
+| Shimmer sweep | 1.5s | ease-in-out | 130° gradient: transparent → surface-highlight → transparent |
+| Loop delay | 0.5s | — | Pause between sweeps to avoid strobing |
+| Skeleton → content | 200ms | ease-out | Fade-in real content over skeleton |
+
+Shimmer gradient direction: 130 degrees (roughly top-left to bottom-right) — matches natural reading direction.
+Background: `surface-variant` token (slightly darker than background surface, lighter than border).
+
+**BAN**: High-contrast shimmer (e.g. white → gray on dark) — too visually noisy. Do NOT use spinner animation inside a skeleton shape. Under `prefers-reduced-motion`, remove the sweep entirely and use static fill.
+
+Cross-link: `reference/motion.md` — `prefers-reduced-motion`: static fill, no gradient sweep
+
+---
+
+## Do / Don't
+
+### Do
+- Match skeleton dimensions exactly to target content to avoid layout shift *(Polaris, Mantine)*
+- Vary text-line widths 60–90% to simulate natural text flow *(Carbon, Atlassian)*
+- Set `aria-hidden="true"` on every skeleton shape element *(WAI-ARIA APG, Polaris)*
+- Set `aria-busy="true"` + `aria-label="Loading…"` on the container *(WAI-ARIA APG)*
+
+### Don't
+- Don't use a spinner when content shape is known — skeleton is always preferred for layout-bearing slots *(Carbon, Polaris)*
+- Don't use strong contrast for shimmer — use `surface-variant` (low contrast) *(Atlassian, Mantine)*
+- Don't animate shimmer under `prefers-reduced-motion` — use static fill *(WCAG 2.3.3)*
+- Don't add visible "Loading…" text inside skeleton shapes — put it on the container via `aria-label` *(Carbon)*
+
+---
+
+## Anti-patterns Cross-links
+
+| Anti-pattern | Entry |
+|--------------|-------|
+| Spinner used when content shape is known | `reference/anti-patterns.md#ban-spinner-overuse` |
+| Missing aria-hidden on visual-only elements | `reference/anti-patterns.md#ban-aria-hidden` |
+
+---
+
+## Benchmark Citations
+
+| Claim | Sources |
+|-------|---------|
+| aria-hidden="true" on skeleton shapes | WAI-ARIA APG, Polaris, Carbon |
+| aria-busy="true" on container | WAI-ARIA APG |
+| Text-line widths 60–90% varied | Carbon, Atlassian, Mantine |
+| Shimmer 130° gradient sweep 1.5s | Polaris, Mantine |
+| Suppress shimmer under prefers-reduced-motion | WCAG 2.3.3 |
+| Match exact target dimensions to prevent layout shift | Polaris, Mantine |
+
+Full system URLs: `connections/design-corpora.md`
+
+---
+
+## Grep Signatures
+
+```bash
+# Skeleton shapes missing aria-hidden
+grep -rn 'skeleton\|Skeleton' src/ | grep -v 'aria-hidden="true"' | grep -v 'aria-busy\|container'
+
+# Skeleton container missing aria-busy
+grep -rn 'skeleton\|Skeleton' src/ | grep 'container\|wrapper\|section' | grep -v 'aria-busy'
+
+# Shimmer animation without prefers-reduced-motion guard
+grep -rn 'shimmer\|skeleton.*animation\|@keyframes.*skeleton' src/ | grep -v 'prefers-reduced-motion'
+```
+
+---
+
+## Failing Example
+
+```html
+<!-- BAD: skeleton shapes with no aria-hidden, container with no aria-busy -->
+<div class="card-skeleton">
+  <div class="skeleton-avatar"></div>
+  <div class="skeleton-line skeleton-line--80"></div>
+  <div class="skeleton-line skeleton-line--60"></div>
+</div>
+```
+
+**Why it fails**: Screen readers traverse the skeleton shapes and announce them as empty elements ("image", unlabeled regions). There is no `aria-busy="true"` to signal a loading state. No `aria-label` tells the user what is loading. When content loads, no `aria-busy="false"` transition signals completion.
+**Grep detection**: `grep -rn 'skeleton' src/ | grep -v 'aria-hidden\|aria-busy'`
+**Fix**: Add `aria-busy="true" aria-label="Loading card content"` to the container; add `aria-hidden="true"` to every skeleton child shape.