@hegemonart/get-design-done 1.15.0 → 1.16.0

package/reference/components/TEMPLATE.md

@@ -0,0 +1,184 @@
+# [Component Name] — Benchmark Spec
+
+> **Template version**: 1.0 (Phase 16)
+> Replace every placeholder in `[brackets]`. Delete this block before committing.
+> Max 350 lines. Every section must be present even if brief.
+> See `agents/component-benchmark-synthesizer.md` for authoring rules.
+
+---
+
+**Harvested from**: [N] design systems · [date]
+**Wave**: [1 | 2 | 3 | 4 | 5] · **Category**: [Inputs | Containers | Feedback | Navigation | Advanced]
+**Spec file**: `reference/components/[name].md`
+
+---
+
+## Purpose
+
+[One paragraph: what this component is, its core job, and when to use it vs. alternatives.
+Cite convergence: "(Material 3, Carbon, Polaris agree: …)"]
+
+---
+
+## Anatomy
+
+[Describe the structural parts. Use a numbered or bulleted list of named elements.
+Mark each as optional or required.]
+
+```
+[ASCII diagram or bulleted tree showing component structure]
+```
+
+| Part | Required | Notes |
+|------|----------|-------|
+| [part] | Yes/No | [brief description] |
+
+---
+
+## Variants
+
+[List the canonical variant set. For each, note which systems define it and what
+distinguishes it visually/behaviorally.]
+
+| Variant | Description | Systems |
+|---------|-------------|---------|
+| [variant] | [what it is] | [Material 3, Carbon, …] |
+
+**Norm** (≥4/18 systems agree): [what the majority agrees on for variant naming/behavior]
+**Diverge**: [where systems meaningfully differ and why]
+
+---
+
+## States
+
+[All interaction states the component must handle. Include visual and semantic description.]
+
+| State | Trigger | Visual | ARIA |
+|-------|---------|--------|------|
+| default | — | [description] | — |
+| hover | pointer over | [description] | — |
+| focus | keyboard focus | focus-visible ring | — |
+| active / pressed | mousedown / Space/Enter | [description] | — |
+| disabled | `disabled` attr | [description] | `aria-disabled="true"` |
+| loading | [if applicable] | [description] | `aria-busy="true"` |
+| error | [if applicable] | [description] | `aria-invalid="true"` |
+
+---
+
+## Sizing & Spacing
+
+[Token-based sizing guidance. Reference `reference/typography.md` and `reference/surfaces.md`
+for typographic and radius rules.]
+
+| Size | Height | Padding H | Font | Notes |
+|------|--------|-----------|------|-------|
+| sm | [value] | [value] | [value] | |
+| md (default) | [value] | [value] | [value] | |
+| lg | [value] | [value] | [value] | |
+
+**Norm**: [what most systems agree on for sizing ratios]
+
+---
+
+## Typography
+
+[Any typographic constraints: weight, size relative to body, line-height cap, truncation rules.]
+
+Cross-link: `reference/typography.md` — [relevant section]
+
+---
+
+## Keyboard & Accessibility
+
+> **WAI-ARIA role**: `[role]`
+> **Required attributes**: `[aria-* attrs]`
+
+### Keyboard Contract
+
+*Quoted verbatim from WAI-ARIA APG — [pattern URL] — W3C — [access date]*
+
+| Key | Action |
+|-----|--------|
+| [key] | [action] |
+
+### Accessibility Rules
+
+- [Rule 1 — e.g., must have visible label or `aria-label`]
+- [Rule 2 — e.g., focus-visible ring must not be suppressed]
+- [Rule 3 — e.g., disabled state uses `aria-disabled`, not `disabled` attr, if interactive]
+
+Cross-link: `reference/accessibility.md` — [relevant section]
+
+---
+
+## Motion
+
+[Animation guidance for entry, exit, state transitions. Reference `reference/motion.md`.]
+
+| Transition | Duration | Easing | Notes |
+|------------|----------|--------|-------|
+| [transition] | [ms] | [easing] | |
+
+**BAN**: [any motion anti-patterns specific to this component]
+
+Cross-link: `reference/motion.md` — [relevant section]
+
+---
+
+## Do / Don't
+
+### Do
+- [Positive practice 1] *([System])*
+- [Positive practice 2] *([System])*
+- [Positive practice 3] *([System])*
+
+### Don't
+- [Anti-practice 1] *(diverges from [N] systems)*
+- [Anti-practice 2]
+- [Anti-practice 3]
+
+---
+
+## Anti-patterns Cross-links
+
+| Anti-pattern | Entry |
+|--------------|-------|
+| [BAN-XX] | [brief name] — `reference/anti-patterns.md#ban-xx` |
+
+---
+
+## Benchmark Citations
+
+| Claim | Sources |
+|-------|---------|
+| [claim] | [System1, System2, System3] |
+
+Full system URLs: `connections/design-corpora.md`
+
+---
+
+## Grep Signatures
+
+Patterns to detect common implementation failures (used by `design-auditor`):
+
+```bash
+# Missing accessible label on icon-only variant
+grep -rn 'aria-label\|aria-labelledby' src/ | grep -v '[Component]'
+
+# [Additional grep pattern with comment explaining what it detects]
+```
+
+---
+
+## Failing Example
+
+What a broken implementation of this component looks like, and how to detect it:
+
+```[html|jsx|tsx]
+<!-- BAD: [describe the failure] -->
+[broken code snippet]
+```
+
+**Why it fails**: [explanation]
+**Grep detection**: `grep -rn '[pattern]' src/`
+**Fix**: [one-line fix or cross-link to reference]

package/reference/components/accordion.md

@@ -0,0 +1,217 @@
+# Accordion — Benchmark Spec
+
+**Harvested from**: WAI-ARIA APG, Radix UI, Carbon, Chakra UI, Material 3, Mantine, shadcn/ui, Atlassian
+**Wave**: 2 · **Category**: Containers
+
+---
+
+## Purpose
+
+An accordion is a vertically stacked set of headers that each reveal or conceal an associated section of content when activated. It reduces visual clutter by hiding content that is not immediately relevant. The header MUST be a button (or have `role="button"`) — users must be able to activate sections by keyboard. *(WAI-ARIA APG, Radix, Carbon all agree)*
+
+---
+
+## Anatomy
+
+```
+┌──────────────────────────────┬──┐
+│ Section 1 header (button)    │ ▾│  ← aria-expanded="true"
+└──────────────────────────────┴──┘
+  ┌────────────────────────────┐
+  │ Section 1 content          │  ← aria-hidden="false"
+  └────────────────────────────┘
+┌──────────────────────────────┬──┐
+│ Section 2 header (button)    │ ▾│  ← aria-expanded="false"
+└──────────────────────────────┴──┘
+  (Section 2 content hidden)
+```
+
+| Part | Required | Notes |
+|------|----------|-------|
+| Header (h2–h6) | Yes | Wraps the trigger button; maintains document outline |
+| Trigger button | Yes | `<button>` with `aria-expanded` + `aria-controls` |
+| Panel | Yes | `id` referenced by `aria-controls`; `role="region"` + `aria-labelledby` |
+| Chevron / icon | No | Rotates 180° on open; `aria-hidden="true"` |
+| Divider | No | Border between items |
+
+---
+
+## Variants
+
+| Variant | Description | Systems |
+|---------|-------------|---------|
+| Single-open | Only one panel open at a time | Material 3, Mantine (default) |
+| Multi-open | Multiple panels can be open simultaneously | Radix (default), Carbon, shadcn |
+| Bordered | Each item has a border/card appearance | All |
+| Flush / ghost | No border; full-width dividers only | shadcn, Material 3 |
+| With icon | Leading icon per header | Carbon, Atlassian |
+
+**Norm** (≥5/18): chevron icon rotates on open (180°); panel animates height.
+**Diverge**: single-open vs. multi-open — Radix defaults to multi-open (more flexible); Material 3 defaults to single-open (simpler UX). Multi-open is safer for long FAQ pages where users may want to compare sections.
+
+---
+
+## States
+
+| State | Trigger | Visual | ARIA |
+|-------|---------|--------|------|
+| collapsed | default | Panel hidden | `aria-expanded="false"` on button |
+| expanded | button activated | Panel visible | `aria-expanded="true"` on button |
+| hover | pointer over header | Header background tint | — |
+| focus | keyboard | 2px focus ring on button | — |
+| disabled | programmatic | 38% opacity; non-interactive | `aria-disabled="true"` on button |
+
+---
+
+## Sizing & Spacing
+
+| Property | Value | Notes |
+|----------|-------|-------|
+| Header height | 48px (md default) | Touch-friendly |
+| Padding H (header) | 16px | |
+| Padding (panel) | 16px | |
+| Icon size | 16–20px | Chevron; gap from label: 8px |
+| Item border | 1px `border-bottom` | Flush style |
+
+---
+
+## Typography
+
+- Header: 14–16px/500 — slightly heavier than panel body
+- Panel body: 14px/400
+- Disabled header: same size, 38% opacity
+
+---
+
+## Keyboard & Accessibility
+
+> **WAI-ARIA role**: `button` on header trigger (implicit if `<button>`); `region` on panel
+> **Header trigger attributes**: `aria-expanded`, `aria-controls` (panel id)
+> **Panel attributes**: `id`, `role="region"`, `aria-labelledby` (header button id)
+
+### Keyboard Contract
+
+*Quoted verbatim from WAI-ARIA APG — https://www.w3.org/WAI/ARIA/apg/patterns/accordion/ — W3C — 2024*
+
+| Key | Action |
+|-----|--------|
+| Enter / Space | When focus is on the accordion header, toggles the associated panel |
+| Tab | Moves focus to the next focusable element |
+| Shift+Tab | Moves focus to the previous focusable element |
+| Arrow Down | (Optional) Moves focus to the next accordion header |
+| Arrow Up | (Optional) Moves focus to the previous accordion header |
+| Home | (Optional) Moves focus to the first accordion header |
+| End | (Optional) Moves focus to the last accordion header |
+
+Arrow/Home/End navigation is optional; Tab navigation between headers is always required.
+
+### Accessibility Rules
+
+- Header MUST be wrapped in an `<h2>`–`<h6>` tag to maintain document outline — the heading level should match the surrounding page hierarchy
+- The trigger MUST be a `<button>` (or `role="button"`) — `<div>` headers are inaccessible by keyboard
+- `aria-expanded` MUST be on the trigger button, not the panel
+- Panel SHOULD have `role="region"` + `aria-labelledby` referencing the trigger button id — this creates a named region for landmark navigation
+- `role="region"` should be omitted if there are more than 6 accordions (too many regions = noisy landmark nav)
+- Avoid `display:none` for the panel in open state — use `hidden` or height animation
+
+---
+
+## Motion
+
+| Transition | Duration | Easing | Notes |
+|------------|----------|--------|-------|
+| Panel expand | 200ms | ease-out | Height 0→auto via `grid-template-rows` trick |
+| Panel collapse | 150ms | ease-in | |
+| Chevron rotate | 200ms | ease | 0→180deg |
+
+**Height animation trick** (CSS-only, no JS measurement):
+```css
+.panel { display: grid; grid-template-rows: 0fr; transition: grid-template-rows 200ms ease; }
+.panel.open { grid-template-rows: 1fr; }
+.panel > div { overflow: hidden; }
+```
+
+Cross-link: `reference/motion.md` — `prefers-reduced-motion`: skip height animation, instant toggle
+
+---
+
+## Do / Don't
+
+### Do
+- Wrap header triggers in proper heading tags (`<h2>`–`<h6>`) *(WAI-ARIA APG, Carbon)*
+- Use `aria-expanded` on the trigger button, not on the panel *(WAI-ARIA APG)*
+- Animate height with `grid-template-rows` trick — no JS height measurement needed *(CSS-only pattern)*
+- Support Tab navigation between accordion headers at minimum *(WAI-ARIA APG)*
+
+### Don't
+- Don't use `<div>` as the accordion header without `role="button"` *(WAI-ARIA APG)*
+- Don't use `display:none` to hide the panel in collapsed state if you want animation — use CSS grid trick *(CSS pattern)*
+- Don't use `role="region"` for more than 6 accordions — excessive landmarks harm screen reader navigation *(WAI-ARIA APG note)*
+- Don't auto-close other panels in a "single-open" accordion without announcing the change *(Atlassian)*
+
+---
+
+## Anti-patterns Cross-links
+
+| Anti-pattern | Entry |
+|--------------|-------|
+| div header without role="button" | `reference/anti-patterns.md` |
+| aria-expanded on panel instead of button | `reference/anti-patterns.md` |
+
+---
+
+## Benchmark Citations
+
+| Claim | Sources |
+|-------|---------|
+| Header in h2–h6 required | WAI-ARIA APG, Carbon |
+| aria-expanded on trigger (not panel) | WAI-ARIA APG §3.1 |
+| role="region" + aria-labelledby on panel | WAI-ARIA APG |
+| Enter/Space to toggle | WAI-ARIA APG §3.1 |
+| grid-template-rows for height animation | CSS-only pattern (no system-specific) |
+
+Full system URLs: `connections/design-corpora.md`
+
+---
+
+## Grep Signatures
+
+```bash
+# Accordion header not a button
+grep -rn 'accordion\|Accordion' src/ | grep 'header\|trigger' | grep -v '<button\|role="button"'
+
+# aria-expanded on wrong element (panel instead of trigger)
+grep -rn 'aria-expanded' src/ | grep 'panel\|content\|body'
+
+# display:none used on accordion panel (breaks animation)
+grep -rn 'accordion.*panel\|panel.*accordion' src/ | grep 'display.*none'
+```
+
+---
+
+## Failing Example
+
+```html
+<!-- BAD: div header — no keyboard access, no aria-expanded -->
+<div class="accordion-header" onclick="toggle(1)">
+  What is the return policy?
+</div>
+<div id="panel-1" class="accordion-panel" style="display:none">
+  Our return policy is 30 days…
+</div>
+```
+
+**Why it fails**: `<div>` is not keyboard-operable (no Tab stop). No `aria-expanded`. Screen reader cannot determine expanded state. `display:none` prevents CSS animation.
+**Grep detection**: `grep -rn 'class.*accordion.*header\|accordion-header' src/ | grep -v '<button\|role="button"'`
+**Fix**:
+```html
+<h3>
+  <button aria-expanded="false" aria-controls="panel-1" id="header-1">
+    What is the return policy?
+    <svg aria-hidden="true"><!-- chevron --></svg>
+  </button>
+</h3>
+<div id="panel-1" role="region" aria-labelledby="header-1" class="panel">
+  <div>Our return policy is 30 days…</div>
+</div>
+```

package/reference/components/button.md

@@ -0,0 +1,195 @@
+# Button — Benchmark Spec
+
+**Harvested from**: Material 3, Polaris, Carbon, Fluent 2, Radix, shadcn/ui, Primer, Atlassian
+**Wave**: 1 · **Category**: Inputs
+
+---
+
+## Purpose
+
+A button triggers a discrete action in the current context — submitting a form, opening a dialog, executing a command. It is not a navigation element (use Link for href-based navigation). Buttons have an explicit visual affordance of clickability and must communicate their current state (loading, disabled) clearly. *(Material 3, Carbon, Polaris agree: button = action trigger, not navigation)*
+
+---
+
+## Anatomy
+
+```
+[ icon? ] [ label ] [ trailing-icon? ]
+    └── role="button" or <button>
+        └── focus-visible ring (2px offset)
+```
+
+| Part | Required | Notes |
+|------|----------|-------|
+| Label | Yes (or `aria-label`) | Visible text preferred; `aria-label` for icon-only |
+| Root element | Yes | Must be `<button>` or element with `role="button"` + `tabindex="0"` |
+| Leading icon | No | Left-aligned, 16–20px, optical spacing ~8px |
+| Trailing icon | No | Right-aligned; use sparingly (chevron for split buttons) |
+| Focus ring | Yes | 2px solid, 2px offset from border; never hidden |
+| Loading indicator | No | Spinner replaces or overlays label; `aria-busy="true"` |
+
+---
+
+## Variants
+
+| Variant | Description | Systems |
+|---------|-------------|---------|
+| Primary / Filled | Highest emphasis; one per view section | Material 3, Carbon, Polaris, Fluent, Primer |
+| Secondary / Outlined | Medium emphasis; alternate action | Material 3, Carbon, Polaris, Fluent |
+| Ghost / Text | Low emphasis; tertiary or inline actions | Material 3 (text), Carbon (ghost), Polaris (plain) |
+| Destructive | Irreversible actions (delete, remove) | Polaris (critical), Carbon (danger), shadcn |
+| Icon-only | No visible label; requires `aria-label` | All systems |
+| Link-style | Looks like link, behaves as button | Carbon, Primer |
+
+**Norm** (≥6/18 systems agree): primary/secondary/ghost hierarchy; one primary per viewport section.
+**Diverge**: "tertiary" naming (Material 3) vs. "ghost" (Carbon) vs. "plain" (Polaris) — same visual intent, different labels.
+
+---
+
+## States
+
+| State | Trigger | Visual | ARIA |
+|-------|---------|--------|------|
+| default | — | Resting fill/border | — |
+| hover | pointer over | 8% overlay (light) / 8% overlay (dark) | — |
+| focus | keyboard focus | 2px focus-visible ring, 2px offset | — |
+| active / pressed | mousedown / Space / Enter | 12% overlay; scale 0.96 | — |
+| disabled | `disabled` attr | 38% opacity; cursor: not-allowed | `disabled` attr |
+| loading | async action in flight | Spinner, `aria-busy="true"` | `aria-busy="true"` |
+
+**Norm**: 96% scale on press (Material 3, shadcn, Carbon confirm). 38% opacity for disabled (Material 3 spec).
+**Diverge**: hover overlay vs. background tint — systems use either approach; overlay is more theme-portable.
+
+---
+
+## Sizing & Spacing
+
+| Size | Height | Padding H | Min-width | Font |
+|------|--------|-----------|-----------|------|
+| sm | 32px | 12px | 64px | 13px/500 |
+| md (default) | 40px | 16px | 80px | 14px/500 |
+| lg | 48px | 24px | 96px | 16px/500 |
+
+**Norm**: 40px default height (Carbon, Polaris, Fluent all confirm). Min-width prevents single-character buttons.
+Cross-link: `reference/surfaces.md` — hit-area rule (minimum 44×44px accessible tap target via padding, not height).
+
+---
+
+## Typography
+
+- Weight: 500 (medium) — not bold; distinguishes from body text without being heavy *(Material 3, Carbon)*
+- Letter-spacing: +0.01em for sm/md, 0 for lg
+- No text truncation — resize button or use icon-only variant; truncated button labels break affordance
+
+Cross-link: `reference/typography.md` — tabular-nums rule (use on loading counters, not labels)
+
+---
+
+## Keyboard & Accessibility
+
+> **WAI-ARIA role**: `button`
+> **Required attributes**: none if `<button>`; `role="button"` + `tabindex="0"` if `<div>`/`<span>`
+
+### Keyboard Contract
+
+*Quoted verbatim from WAI-ARIA APG — https://www.w3.org/WAI/ARIA/apg/patterns/button/ — W3C — 2024*
+
+| Key | Action |
+|-----|--------|
+| Enter | Activates the button |
+| Space | Activates the button |
+
+### Accessibility Rules
+
+- Icon-only buttons MUST have `aria-label` or `aria-labelledby` — a tooltip is not a substitute
+- Loading state: set `aria-busy="true"` and disable pointer events; announce completion via `aria-live`
+- Disabled: use native `disabled` attribute (not `aria-disabled`) unless button must remain focusable for tooltip explanation
+- Never use `<div>` or `<a>` as a button trigger without `role="button"` and keyboard handlers
+- Focus ring must never be `outline: none` without a visible CSS custom alternative
+
+Cross-link: `reference/accessibility.md`
+
+---
+
+## Motion
+
+| Transition | Duration | Easing | Notes |
+|------------|----------|--------|-------|
+| hover overlay | 120ms | ease-out | Subtle; background/border only |
+| press scale (0.96) | 80ms | ease-in | Immediate tactile feedback |
+| loading spinner in | 150ms | ease-out | Replaces or overlays label |
+
+**BAN**: `transition: all` — catches width change on loading and causes layout jank.
+
+Cross-link: `reference/motion.md` — canonical scale-on-press 0.96, BAN-04 (`transition: all`)
+
+---
+
+## Do / Don't
+
+### Do
+- Use one primary button per section of a view *(Material 3, Carbon, Polaris)*
+- Write labels as verb phrases: "Save changes", "Delete account" *(Polaris content guidelines)*
+- Provide `aria-label` for icon-only variants *(WAI-ARIA APG)*
+- Maintain 8px minimum spacing between adjacent buttons *(Carbon, Fluent)*
+
+### Don't
+- Don't use a button for navigation to another page — use `<a href>` (Link) *(Carbon, Primer)*
+- Don't disable a button without explaining why — prefer showing error state after submission *(Polaris)*
+- Don't use "Click here" or "Submit" as labels — be specific about the action *(Polaris, Carbon)*
+- Don't truncate button labels — buttons must fit their content *(Fluent, Atlassian)*
+
+---
+
+## Anti-patterns Cross-links
+
+| Anti-pattern | Entry |
+|--------------|-------|
+| BAN-04 | `transition: all` on interactive elements — `reference/anti-patterns.md#ban-04` |
+
+---
+
+## Benchmark Citations
+
+| Claim | Sources |
+|-------|---------|
+| 40px default height | Carbon, Polaris, Fluent 2 |
+| 96% press scale | Material 3, shadcn, Carbon |
+| One primary per section | Material 3, Carbon, Polaris, Fluent |
+| Space/Enter activation | WAI-ARIA APG §4.2 |
+| 38% opacity disabled | Material 3 |
+
+Full system URLs: `connections/design-corpora.md`
+
+---
+
+## Grep Signatures
+
+```bash
+# Icon-only button missing aria-label
+grep -rn '<button' src/ | grep -v 'aria-label\|aria-labelledby' | grep 'icon\|svg'
+
+# div/span used as button without role
+grep -rn '<div\|<span' src/ | grep 'onClick\|on:click' | grep -v 'role="button"'
+
+# transition: all on button (BAN-04)
+grep -rn 'transition:\s*all' src/ | grep -i 'button\|btn'
+
+# Missing focus-visible — outline: none without alternative
+grep -rn 'outline:\s*none\|outline:\s*0' src/ | grep -i 'button\|btn\|focus'
+```
+
+---
+
+## Failing Example
+
+```html
+<!-- BAD: div used as button — no keyboard access, no role, no focus management -->
+<div class="btn" onclick="handleClick()">
+  <svg><!-- icon --></svg>
+</div>
+```
+
+**Why it fails**: Not reachable by keyboard; no ARIA role; Space/Enter do nothing; no accessible name.
+**Grep detection**: `grep -rn '<div.*onClick\|<div.*on:click' src/ | grep -v 'role='`
+**Fix**: Use `<button type="button" aria-label="[action]">` with the icon inside.