@hegemonart/get-design-done 1.15.0 → 1.18.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/alert.md

@@ -0,0 +1,198 @@
+# Alert / Banner — Benchmark Spec
+
+**Harvested from**: Material 3 (Banner), Carbon (InlineNotification), Polaris (Banner), Atlassian (SectionMessage)
+**Wave**: 3 · **Category**: Feedback
+
+---
+
+## Purpose
+
+An alert (inline notification or banner) is a persistent in-page message that communicates status, warnings, or errors relevant to the current context. Unlike Toast, it does not auto-dismiss — it remains visible until the user dismisses it or the underlying condition resolves. Use alert for messages that require acknowledgement or that must remain visible for reference. *(Material 3, Carbon, Polaris, Atlassian agree: alert = persistent inline feedback)*
+
+---
+
+## Anatomy
+
+```
+┌─────────────────────────────────────────────────────────┐
+│ [icon]  [Title (optional)]                   [✕ dismiss?]│
+│         Message text                                     │
+│         [Primary action?]  [Secondary action?]           │
+└─────────────────────────────────────────────────────────┘
+      ↑ role="alert" (error/warning) or role="status" (info/success)
+```
+
+| Part | Required | Notes |
+|------|----------|-------|
+| Container | Yes | `role="alert"` or `role="status"` per severity |
+| Severity icon | Yes | Visual + semantic variant indicator; never color alone |
+| Message text | Yes | Concise description of status or error |
+| Title | No | Recommended for error/warning; provides quick scanning |
+| Primary action | No | One CTA linking to resolution (e.g. "Retry", "Review") |
+| Secondary action | No | Supplemental link; lower emphasis |
+| Dismiss button | No | Required when alert can be resolved by user |
+
+---
+
+## Variants
+
+| Variant | Description | Systems |
+|---------|-------------|---------|
+| Info | Blue; neutral informational message; `role="status"` polite | All |
+| Success | Green; completed action confirmation; `role="status"` polite | All |
+| Warning | Amber; potentially harmful condition; `role="alert"` assertive | All |
+| Error | Red; failure or blocking condition; `role="alert"` assertive | All |
+
+**Norm** (≥4/18 systems agree): four-variant semantic model (info/success/warning/error) with matching color, icon, and role. Icon is REQUIRED — color alone violates WCAG 1.4.1.
+**Diverge**: Atlassian names this "SectionMessage" and omits dismiss; Carbon always includes an X; Polaris supports titled and untitled variants; Material 3 "Banner" supports one CTA only.
+
+---
+
+## States
+
+| State | Trigger | Visual | ARIA |
+|-------|---------|--------|------|
+| visible | render | Full opacity, inline position | `role="alert"` or `role="status"` |
+| hover | pointer over action | Action underline / background change | — |
+| focus | keyboard on action/dismiss | focus-visible ring on button | — |
+| dismissed | click dismiss button | Collapsed / removed | Removed from DOM |
+
+---
+
+## Sizing & Spacing
+
+| Placement | Width | Radius | Padding |
+|-----------|-------|--------|---------|
+| Full-width (page/section) | 100% of container | 0px | 16px 20px |
+| Inline / card-contained | fit-to-container | 6–8px | 12px 16px |
+
+| Property | Value | Notes |
+|----------|-------|-------|
+| Icon size | 20px | Aligned to first line of text |
+| Gap (icon → text) | 12px | |
+| Min height | 48px single-line | Grows with content |
+
+**Norm**: Full-width placement in page-level contexts; rounded corners for component-level inline placement *(Material 3, Carbon, Atlassian)*.
+
+---
+
+## Typography
+
+- Title: label-md (14px/600) — gives quick scannable context for complex errors
+- Message: body-sm (14px/400) — readable at inline scale
+- Action: label-sm (13px/500) — matches action button label weight
+
+Cross-link: `reference/typography.md` — body-sm, label-md definitions
+
+---
+
+## Keyboard & Accessibility
+
+> **WAI-ARIA role**: `alert` (error/warning) or `status` (info/success)
+> **Required attributes**: `role` on container; icon must have `aria-hidden="true"` + text-based variant reinforcement
+
+### 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 buttons or dismiss button in document order |
+| Enter / Space | Activates focused action or dismiss button |
+| Escape | No special behavior (unlike modal); alert stays visible |
+
+The alert container itself is not focusable. Child buttons follow standard button keyboard contract.
+
+### Accessibility Rules
+
+- Icon MUST be `aria-hidden="true"` — the icon is decorative reinforcement; the `role` and text carry the semantic meaning *(WCAG 1.4.1)*
+- Color MUST NOT be the sole differentiator between variants — icon shape and text label must also differ *(WCAG 1.4.1)*
+- `role="alert"` causes immediate assertion by screen readers — only use for error and warning severity
+- `role="status"` uses a polite live region — appropriate for info and success
+- Dismiss button MUST have `aria-label` (e.g. `aria-label="Dismiss warning"`) *(WAI-ARIA APG)*
+- Do NOT auto-dismiss alerts — that is Toast's job; alert stays until explicitly dismissed *(Carbon, Polaris)*
+
+Cross-link: `reference/accessibility.md` — live-regions, color-contrast sections
+
+---
+
+## Motion
+
+| Transition | Duration | Easing | Notes |
+|------------|----------|--------|-------|
+| Enter (height expand + fade) | 200ms | ease-out | Pushes content down; avoids position:fixed |
+| Exit (height collapse + fade) | 150ms | ease-in | Content reflows up as alert closes |
+| Icon entrance | 0ms | — | No animation on icon; immediate |
+
+**BAN**: Slide-in from edge (reserve for Toast). Alert is inline — it should feel like content appearing, not a notification arriving.
+
+Cross-link: `reference/motion.md` — `prefers-reduced-motion`: skip height animation, instant show/hide
+
+---
+
+## Do / Don't
+
+### Do
+- Always include an icon matching the semantic variant *(WCAG 1.4.1 — color not sole differentiator)*
+- Use `role="alert"` for warning/error (assertive) and `role="status"` for info/success (polite) *(WAI-ARIA APG)*
+- Keep alert visible until the condition is resolved or user dismisses *(Carbon, Polaris)*
+- Use full-width for page-level alerts; rounded inline for component-level *(Material 3, Carbon)*
+
+### Don't
+- Don't auto-dismiss alerts — use Toast for transient messages *(Material 3, Carbon)*
+- Don't use color alone to distinguish severity — always include an icon and text label *(WCAG 1.4.1)*
+- Don't stack more than 2 alerts in the same section — consolidate into a single summary *(Polaris)*
+- Don't use `role="alert"` for info/success — overly assertive announcements desensitize users *(WAI-ARIA APG)*
+
+---
+
+## Anti-patterns Cross-links
+
+| Anti-pattern | Entry |
+|--------------|-------|
+| Color as sole variant differentiator | `reference/anti-patterns.md#ban-color-only` |
+| role="alert" on info/success (over-announcing) | `reference/anti-patterns.md#ban-live-region` |
+
+---
+
+## Benchmark Citations
+
+| Claim | Sources |
+|-------|---------|
+| Icon required; color not sole differentiator | WCAG 1.4.1; Material 3, Carbon, Polaris, Atlassian |
+| role="alert" for error/warning; role="status" for info/success | WAI-ARIA APG, Carbon, Polaris |
+| No auto-dismiss | Material 3, Carbon, Polaris, Atlassian |
+| Full-width vs. rounded inline placement | Material 3, Carbon, Atlassian |
+| Dismiss button requires aria-label | WAI-ARIA APG |
+
+Full system URLs: `connections/design-corpora.md`
+
+---
+
+## Grep Signatures
+
+```bash
+# Alert missing role attribute entirely
+grep -rn 'alert\|Alert\|banner\|Banner\|notification' src/ | grep 'class=\|className=' | grep -v 'role='
+
+# Error/warning alert using role="status" instead of role="alert"
+grep -rn 'role="status"' src/ | grep -i 'error\|warning\|danger'
+
+# Color-only differentiation — severity class with no icon reference
+grep -rn 'alert--error\|alert--warning\|alert-error\|alert-warning' src/ | grep -v 'icon\|Icon\|svg\|SVG'
+```
+
+---
+
+## Failing Example
+
+```html
+<!-- BAD: alert using only color class — no icon, no role, no text variant label -->
+<div class="alert alert--error">
+  Your session has expired. Please log in again.
+</div>
+```
+
+**Why it fails**: No `role="alert"` so screen readers do not announce the error message. Color class alone distinguishes severity — users with color blindness or high-contrast themes cannot distinguish this from a neutral message. No icon provides a shape-based cue.
+**Grep detection**: `grep -rn 'class.*alert--error\|class.*alert-error' src/ | grep -v 'role='`
+**Fix**: Add `role="alert"`, include an error icon with `aria-hidden="true"`, and ensure the variant is communicated through text or visually-hidden label in addition to color.