npm - @hegemonart/get-design-done - Versions diffs - 1.14.8 → 1.16.0 - Mend

@hegemonart/get-design-done 1.14.8 → 1.16.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (58) hide show

package/.claude-plugin/marketplace.json +5 -3
package/.claude-plugin/plugin.json +15 -5
package/CHANGELOG.md +97 -0
package/README.md +30 -0
package/SKILL.md +4 -1
package/agents/a11y-mapper.md +25 -0
package/agents/component-benchmark-harvester.md +112 -0
package/agents/component-benchmark-synthesizer.md +88 -0
package/agents/design-auditor.md +92 -8
package/agents/design-context-builder.md +6 -0
package/agents/design-executor.md +5 -2
package/agents/design-pattern-mapper.md +2 -0
package/agents/design-verifier.md +11 -0
package/agents/motion-mapper.md +45 -0
package/agents/token-mapper.md +36 -0
package/agents/visual-hierarchy-mapper.md +29 -0
package/connections/design-corpora.md +158 -0
package/package.json +16 -2
package/reference/anti-patterns.md +69 -0
package/reference/audit-scoring.md +34 -3
package/reference/brand-voice.md +199 -0
package/reference/checklists.md +30 -3
package/reference/components/README.md +90 -0
package/reference/components/TEMPLATE.md +184 -0
package/reference/components/accordion.md +217 -0
package/reference/components/button.md +195 -0
package/reference/components/card.md +200 -0
package/reference/components/checkbox.md +207 -0
package/reference/components/drawer.md +201 -0
package/reference/components/input.md +208 -0
package/reference/components/label.md +200 -0
package/reference/components/link.md +193 -0
package/reference/components/modal-dialog.md +210 -0
package/reference/components/popover.md +197 -0
package/reference/components/radio.md +203 -0
package/reference/components/select-combobox.md +219 -0
package/reference/components/switch.md +194 -0
package/reference/components/tabs.md +213 -0
package/reference/components/tooltip.md +201 -0
package/reference/data/google-fonts.csv +51 -0
package/reference/data/palettes.csv +41 -0
package/reference/data/styles.csv +39 -0
package/reference/design-system-guidance.md +177 -0
package/reference/design-systems-catalog.md +151 -0
package/reference/framer-motion-patterns.md +411 -0
package/reference/gestalt.md +219 -0
package/reference/iconography.md +231 -0
package/reference/motion.md +102 -0
package/reference/palette-catalog.md +82 -0
package/reference/performance.md +304 -0
package/reference/registry.json +359 -28
package/reference/registry.schema.json +2 -1
package/reference/review-format.md +2 -2
package/reference/style-vocabulary.md +62 -0
package/reference/surfaces.md +114 -0
package/reference/typography.md +80 -0
package/reference/visual-hierarchy-layout.md +306 -0
package/skills/benchmark/SKILL.md +105 -0

package/reference/components/modal-dialog.md ADDED Viewed

@@ -0,0 +1,210 @@
+# Modal / Dialog — Benchmark Spec
+**Harvested from**: Radix UI Dialog, WAI-ARIA APG, Material 3, Atlassian, Carbon, Mantine, shadcn/ui, Fluent 2
+**Wave**: 2 · **Category**: Containers
+---
+## Purpose
+A modal dialog is a blocking overlay that requires user interaction before returning to the main content. It is rendered in a portal above the page, traps keyboard focus within itself, prevents interaction with the background, and closes on Escape. Use modals sparingly — they interrupt flow. Prefer inline feedback or slide-out drawers for non-critical workflows. *(Material 3, Atlassian, Polaris all advise modal restraint)*
+---
+## Anatomy
+```
+┌─ Backdrop (aria-hidden) ──────────────────────────────────┐
+│                                                            │
+│  ┌─ Dialog (role="dialog") ───────────────────────────┐   │
+│  │  Title (aria-labelledby)           [✕ Close]        │   │
+│  │─────────────────────────────────────────────────────│   │
+│  │  Content / Body                                     │   │
+│  │─────────────────────────────────────────────────────│   │
+│  │  [Cancel]  [Confirm action]  ← action footer        │   │
+│  └─────────────────────────────────────────────────────┘   │
+└────────────────────────────────────────────────────────────┘
+```
+| Part | Required | Notes |
+|------|----------|-------|
+| Backdrop | Yes | `aria-hidden="true"` overlay; blocks pointer |
+| Dialog container | Yes | `role="dialog"` + `aria-modal="true"` |
+| Title / heading | Yes | `id` referenced by `aria-labelledby` on dialog |
+| Close button | Yes | Keyboard accessible; returns focus to trigger |
+| Body content | Yes | Scrollable if content exceeds viewport |
+| Action footer | Conditional | Confirm + cancel pattern |
+| Portal | Yes | Rendered outside normal DOM flow; `document.body` target |
+---
+## Variants
+| Variant | Description | Systems |
+|---------|-------------|---------|
+| Default | Centered, backdrop, standard size | All |
+| Alert dialog | Blocking confirmation; `role="alertdialog"` | WAI-ARIA APG, Material 3, Carbon |
+| Full-page | Mobile-first; occupies full viewport | Material 3, Atlassian |
+| Small / confirm | Narrow; 2-button pattern | Material 3, Carbon, shadcn |
+| Large / content | Wide; for complex forms or media | Atlassian, Fluent |
+| Scrollable content | Body scrolls; header/footer sticky | All |
+**Norm** (≥6/18): Escape closes; backdrop click may close (configurable); focus trapped inside.
+**Diverge**: backdrop-click-to-close — Material 3 and shadcn default to close; Atlassian and Carbon recommend NOT closing on backdrop click to prevent accidental dismissal of forms.
+---
+## States
+| State | ARIA |
+|-------|------|
+| Open | `aria-modal="true"` on dialog; `inert` on `<body>` content (or equivalent) |
+| Closed | Dialog removed from DOM or `display:none`; focus returned to trigger |
+| Loading content | `aria-busy="true"` on dialog body |
+---
+## Sizing & Spacing
+| Size | Width | Max height | Notes |
+|------|-------|------------|-------|
+| sm | 400px | 80vh | Confirm dialogs |
+| md (default) | 560px | 80vh | Standard |
+| lg | 720px | 90vh | Complex forms |
+| full | 100vw/100vh | — | Mobile sheet pattern |
+Padding: 24px (header/footer), 24px (body horizontal), 20px (body vertical).
+Body scroll: `overflow-y: auto` with `overscroll-behavior: contain`.
+Cross-link: `reference/surfaces.md` — concentric radius, elevation (shadow-as-border)
+---
+## Typography
+- Title: 18–20px/600; `id` attribute set for `aria-labelledby`
+- Body: 14–16px/400
+- Description (if separate from body): 14px/400 muted; linked via `aria-describedby` on dialog
+---
+## Keyboard & Accessibility
+> **WAI-ARIA role**: `dialog` (or `alertdialog` for blocking confirmations)
+> **Required attributes**: `aria-modal="true"`, `aria-labelledby` (dialog title id), optionally `aria-describedby`
+### Keyboard Contract
+*Quoted verbatim from WAI-ARIA APG — https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/ — W3C — 2024*
+| Key | Action |
+|-----|--------|
+| Tab | Moves focus to next focusable element inside dialog (wraps from last to first) |
+| Shift+Tab | Moves focus to previous focusable element inside dialog (wraps from first to last) |
+| Escape | Closes the dialog and returns focus to the element that opened it |
+### Focus Management
+1. **On open**: focus moves to the first focusable element inside the dialog (or to the dialog itself if no focusable children)
+2. **While open**: Tab/Shift+Tab cycle only within the dialog — focus MUST NOT leave the dialog
+3. **On close**: focus MUST return to the element that triggered the dialog open
+### Accessibility Rules
+- `aria-modal="true"` MUST be set — tells AT to ignore background content (supplement with `inert` attribute on background for browsers without full `aria-modal` support)
+- Dialog title MUST have an `id` referenced by `aria-labelledby` — screen reader announces "Dialog: [title]" on open
+- `role="alertdialog"` for confirmation dialogs where the user must respond (delete confirmations, logout confirmation)
+- Scroll-lock: prevent `<body>` scroll when dialog is open (`overflow: hidden` on `<body>`)
+- Portal: render dialog in `document.body` to escape stacking context issues (z-index isolation)
+---
+## Motion
+| Transition | Duration | Easing | Notes |
+|------------|----------|--------|-------|
+| Backdrop fade in | 200ms | ease-out | opacity 0→0.5 |
+| Dialog enter | 200ms | ease-out | scale 0.95→1 + fade |
+| Dialog exit | 150ms | ease-in | scale 1→0.95 + fade |
+| Backdrop fade out | 150ms | ease-in | — |
+Use `AnimatePresence` (Framer Motion) or `data-state` + CSS for mount/unmount animation.
+Cross-link: `reference/motion.md` — `AnimatePresence initial={false}`, `prefers-reduced-motion`
+---
+## Do / Don't
+### Do
+- Return focus to the triggering element on close *(WAI-ARIA APG, all systems)*
+- Trap focus inside the dialog while open *(WAI-ARIA APG)*
+- Render in a portal at `document.body` *(Radix, Mantine, shadcn)*
+- Set `overflow:hidden` on `<body>` to prevent background scroll *(Material 3, Carbon)*
+### Don't
+- Don't close on backdrop click for dialogs with form input — data loss risk *(Atlassian, Carbon)*
+- Don't use `role="dialog"` without `aria-labelledby` — dialog is announced without a name *(WAI-ARIA APG)*
+- Don't use `display:none` to hide a dialog — use DOM removal or `hidden` attribute for correct AT behavior *(WAI-ARIA APG)*
+- Don't stack more than 2 dialogs — use a single dialog with internal step navigation *(Material 3, Atlassian)*
+---
+## Anti-patterns Cross-links
+| Anti-pattern | Entry |
+|--------------|-------|
+| Focus not trapped in modal | `reference/anti-patterns.md` |
+| No focus return on close | `reference/anti-patterns.md` |
+---
+## Benchmark Citations
+| Claim | Sources |
+|-------|---------|
+| Escape closes dialog | WAI-ARIA APG §4.1, all 8 systems |
+| Focus trap (Tab wraps inside) | WAI-ARIA APG §4.1 |
+| aria-modal="true" required | WAI-ARIA APG |
+| Portal at document.body | Radix, Mantine, shadcn |
+| role="alertdialog" for confirmations | WAI-ARIA APG, Material 3 |
+| backdrop-click: configurable | Material 3, shadcn (default: close); Atlassian, Carbon (default: stay) |
+Full system URLs: `connections/design-corpora.md`
+---
+## Grep Signatures
+```bash
+# Dialog without aria-labelledby
+grep -rn 'role="dialog"\|role="alertdialog"' src/ | grep -v 'aria-labelledby'
+# Dialog missing aria-modal
+grep -rn 'role="dialog"' src/ | grep -v 'aria-modal'
+# Modal without focus trap
+grep -rn 'modal\|dialog' src/ | grep -L 'FocusTrap\|useFocusTrap\|focus-trap\|inert'
+# Body scroll not locked on modal open
+grep -rn 'modal.*open\|isOpen.*modal' src/ | grep -v 'overflow\|scroll-lock\|body\.'
+```
+---
+## Failing Example
+```html
+<!-- BAD: dialog with no focus trap, no aria-modal, no aria-labelledby -->
+<div class="modal" style="display:block">
+  <div class="modal-content">
+    <h2>Confirm deletion</h2>
+    <p>This action cannot be undone.</p>
+    <button onclick="close()">Cancel</button>
+    <button onclick="confirm()">Delete</button>
+  </div>
+</div>
+```
+**Why it fails**: No `role="dialog"`, no `aria-modal`, no `aria-labelledby` — screen readers cannot announce the dialog name or suppress background content. Tab escapes the modal. Escape does nothing.
+**Grep detection**: `grep -rn 'class.*modal\|class.*dialog' src/ | grep -v 'role=\|aria-'`
+**Fix**: Use Radix `<Dialog>` or implement WAI-ARIA dialog pattern with `role="dialog"`, `aria-modal="true"`, `aria-labelledby`, focus trap, Escape handler, and portal rendering.

package/reference/components/popover.md ADDED Viewed

@@ -0,0 +1,197 @@
+# Popover — Benchmark Spec
+**Harvested from**: Radix UI Popover, Floating UI, Mantine, Atlassian, WAI-ARIA APG, shadcn/ui, Carbon, Material 3
+**Wave**: 2 · **Category**: Containers
+---
+## Purpose
+A popover is an anchored overlay that appears beside a trigger element, containing richer content than a tooltip (interactive content, forms, menus). It is dismissed by clicking outside, pressing Escape, or activating a close button. Unlike a modal, it does not trap focus (unless it contains a form that requires isolation). *(Radix, Floating UI, WAI-ARIA APG differentiate popover from both tooltip and modal)*
+---
+## Anatomy
+```
+[Trigger button]
+        │
+        ▼ (arrow / caret — optional)
+┌───────────────────────┐
+│ Title (opt.)  [✕]     │  ← optional close button
+│───────────────────────│
+│ Content / form        │
+│                       │
+│ [Action]              │
+└───────────────────────┘
+```
+| Part | Required | Notes |
+|------|----------|-------|
+| Trigger | Yes | Button or interactive element that opens the popover |
+| Popover container | Yes | `role="dialog"` OR no role for non-modal content |
+| Content | Yes | Can include interactive elements (forms, links, buttons) |
+| Arrow pointer | No | 8–12px; indicates anchor relationship |
+| Close button | No | When popover contains a form (escape is always active) |
+| Backdrop | No | Popovers typically dismiss on outside-click, not backdrop |
+---
+## Variants
+| Variant | Description | Systems |
+|---------|-------------|---------|
+| Default | Anchored to trigger; dismisses on outside-click | All |
+| With title | Title bar + close button for complex content | Radix, shadcn, Atlassian |
+| Form popover | Contains inputs; focus trap optional | Radix, Mantine |
+| Contextual menu | List of actions (see also: Dropdown Menu pattern) | Material 3, Carbon |
+| Inline picker | Date, color, emoji picker | Material 3, Mantine |
+**Norm** (≥5/18): Escape closes; outside-click closes; arrow pointer indicates anchor.
+**Diverge**: focus trap — Radix Popover does NOT trap focus (non-modal); Radix Dialog DOES. Use Dialog-pattern when content isolation is required.
+---
+## States
+| State | ARIA |
+|-------|------|
+| Closed | `aria-expanded="false"` on trigger |
+| Open | `aria-expanded="true"` on trigger; `aria-controls="popover-id"` |
+| Loading | `aria-busy="true"` on popover body |
+---
+## Positioning
+*Per Floating UI — https://floating-ui.com — MIT — 2024*
+| Property | Recommended Value | Notes |
+|----------|-------------------|-------|
+| Placement | `bottom` (default), `top`, `left`, `right` | Auto-flip on viewport edge |
+| Auto-flip | `flip()` middleware | Flips to opposite side when space is insufficient |
+| Auto-shift | `shift()` middleware | Shifts along the axis to stay in viewport |
+| Offset | 8px from trigger | Gap between trigger and popover edge |
+| Arrow | `arrow()` middleware | CSS custom property `--arrow-x`, `--arrow-y` |
+Positioning must update on scroll and resize (`autoUpdate` from Floating UI).
+---
+## Sizing & Spacing
+| Property | Value | Notes |
+|----------|-------|-------|
+| Min width | 200px | Prevents content collapse |
+| Max width | 360px | Wider → use modal instead |
+| Padding | 16px | |
+| Arrow size | 8×8px | |
+| Border radius | Match design token | `reference/surfaces.md` |
+---
+## Keyboard & Accessibility
+> **WAI-ARIA role**: `dialog` (when content requires focus isolation) OR no specific role
+> **Trigger attributes**: `aria-expanded`, `aria-controls` (popover id), `aria-haspopup="dialog"` (when role="dialog")
+### Keyboard Contract
+*Quoted verbatim from WAI-ARIA APG — https://www.w3.org/WAI/ARIA/apg/patterns/dialogmodal/ (non-modal variant) — W3C — 2024*
+| Key | Action |
+|-----|--------|
+| Escape | Closes the popover; returns focus to trigger |
+| Tab (inside popover) | Moves focus through interactive elements inside popover |
+| Tab (last element inside) | Closes popover; moves focus to next element after trigger |
+### Accessibility Rules
+- Trigger MUST have `aria-expanded` toggled on open/close
+- Trigger MUST have `aria-controls` pointing to the popover's `id`
+- When popover is dismissed, focus MUST return to the trigger element
+- Non-modal popover: Tab MAY leave the popover (focus is not trapped)
+- Modal popover (form isolation): add `role="dialog"` + `aria-modal="true"` + focus trap
+- Popover with interactive content: do NOT use `role="tooltip"` — tooltip cannot contain interactive elements
+---
+## Motion
+| Transition | Duration | Easing | Notes |
+|------------|----------|--------|-------|
+| Open | 120ms | ease-out | scale 0.95→1 + fade; origin at trigger |
+| Close | 80ms | ease-in | fade only |
+| Position update | 0ms | — | No animation on reposition (prevents jank on scroll) |
+Cross-link: `reference/motion.md` — `AnimatePresence`, `data-state` trigger for CSS transitions
+---
+## Do / Don't
+### Do
+- Use Floating UI or equivalent for positioning — manual positioning breaks on scroll and viewport edge *(Radix, Mantine, shadcn)*
+- Dismiss on outside-click AND Escape *(WAI-ARIA APG, Radix, all systems)*
+- Return focus to trigger on close *(WAI-ARIA APG)*
+- Auto-flip and auto-shift so popover stays in viewport *(Floating UI)*
+### Don't
+- Don't use `role="tooltip"` for popovers with interactive content — tooltip has a different contract *(WAI-ARIA APG)*
+- Don't position with `position: absolute` without a Floating UI — it will misalign on scroll *(Floating UI docs)*
+- Don't make popovers wider than 360px — use a modal for complex content *(Atlassian, Carbon)*
+- Don't auto-open popovers on hover — use tooltip for hover-triggered content *(Radix, WAI-ARIA APG)*
+---
+## Anti-patterns Cross-links
+| Anti-pattern | Entry |
+|--------------|-------|
+| role="tooltip" on interactive content | `reference/anti-patterns.md` |
+| Manual absolute positioning | `reference/anti-patterns.md` |
+---
+## Benchmark Citations
+| Claim | Sources |
+|-------|---------|
+| Escape closes popover | WAI-ARIA APG, Radix, all systems |
+| aria-expanded on trigger | WAI-ARIA APG |
+| Floating UI for positioning | Radix, Mantine, shadcn |
+| No focus trap (non-modal) | Radix Popover docs |
+| 8px offset from trigger | Floating UI default |
+Full system URLs: `connections/design-corpora.md`
+---
+## Grep Signatures
+```bash
+# Popover trigger missing aria-expanded
+grep -rn 'popover\|Popover' src/ | grep 'trigger\|button' | grep -v 'aria-expanded'
+# role="tooltip" used for interactive popover
+grep -rn 'role="tooltip"' src/ | xargs grep -l 'button\|input\|<a ' 2>/dev/null
+# Manual absolute positioning (no Floating UI)
+grep -rn 'position:\s*absolute' src/ | grep -i 'popover\|dropdown\|overlay'
+```
+---
+## Failing Example
+```html
+<!-- BAD: popover with role="tooltip" containing a button — wrong role, keyboard broken -->
+<div role="tooltip" id="popover" style="position:absolute;top:40px">
+  <p>Quick actions</p>
+  <button onclick="doAction()">Apply</button>
+</div>
+```
+**Why it fails**: `role="tooltip"` cannot contain interactive elements per ARIA spec. The button is announced incorrectly. Escape may not close (tooltip close behavior differs from popover/dialog).
+**Grep detection**: `grep -rn 'role="tooltip"' src/ | xargs grep -l 'button\|<a \|input' 2>/dev/null`
+**Fix**: Use `role="dialog"` with `aria-modal="false"` (non-modal) for interactive popovers, or use Radix `<Popover>` which handles all ARIA and positioning automatically.

package/reference/components/radio.md ADDED Viewed

@@ -0,0 +1,203 @@
+# Radio — Benchmark Spec
+**Harvested from**: Material 3, Carbon, Fluent 2, Mantine, WAI-ARIA APG, Polaris, Ant Design, Chakra UI
+**Wave**: 1 · **Category**: Inputs
+---
+## Purpose
+A radio button represents one option within a mutually exclusive group. Selecting one radio button deselects all others in the same group. Always wrap radio buttons in a `<fieldset>` + `<legend>` and group them with the same `name` attribute. Never use a single radio button — it creates an unresettable state. Use a checkbox for binary choices.
+---
+## Anatomy
+```
+<fieldset>
+  <legend>Shipping method</legend>
+  ( ) Standard shipping  ← <input type="radio" name="shipping" id="standard">
+  (●) Express shipping   ← <input type="radio" name="shipping" id="express" checked>
+  ( ) Overnight          ← <input type="radio" name="shipping" id="overnight">
+</fieldset>
+```
+| Part | Required | Notes |
+|------|----------|-------|
+| `<fieldset>` | Yes | Groups the radio set |
+| `<legend>` | Yes | Names the group; read by screen readers before each option |
+| `<input type="radio">` | Yes | Native element; same `name` within group |
+| `<label for="id">` | Yes | Click zone extends to label text |
+| Helper text | No | Below individual item or below legend |
+| Error message | Conditional | Group-level error via `aria-describedby` on `<fieldset>` |
+---
+## Variants
+| Variant | Description | Systems |
+|---------|-------------|---------|
+| Default (stacked) | Vertical list of options | All |
+| Horizontal | Side-by-side for short labels (2–3 options) | Material 3, Carbon, Mantine |
+| Radio card | Clickable card with radio indicator | Polaris, Mantine, shadcn |
+| Button group | Segmented-control appearance | Material 3, Fluent 2, Carbon |
+**Norm** (≥6/18): vertical stacking default; horizontal allowed for ≤3 short labels.
+**Diverge**: button-group vs. radio-card — visual styling differs but keyboard contract is identical.
+---
+## States
+| State | Trigger | Visual | ARIA |
+|-------|---------|--------|------|
+| unselected | default | Empty circle | — |
+| selected | user interaction / programmatic | Filled dot | `checked` attr |
+| hover | pointer over | Circle border darkens | — |
+| focus | keyboard (Tab into group) | 2px focus ring on currently selected / first | — |
+| disabled | `disabled` attr | 38% opacity | `aria-disabled="true"` |
+| error | group-level | Red border on legend/container | `aria-describedby` on `<fieldset>` |
+---
+## Sizing & Spacing
+| Property | Value | Notes |
+|----------|-------|-------|
+| Control diameter | 16–20px | *(Material 3: 20px, Carbon: 16px, Polaris: 16px)* |
+| Dot diameter | 8–10px (center of control) | |
+| Gap: control → label | 8px | |
+| Item spacing (vertical) | 8–12px | *(Carbon: 8px, Material 3: 8px)* |
+| Touch target | 44×44px via pseudo-element | `reference/surfaces.md` |
+Cross-link: `reference/surfaces.md` — hit-area pseudo-element pattern
+---
+## Typography
+- Label: 14px/400 — same as body; option is a choice, not a heading
+- Legend: 14px/500 or 12px/600 uppercase — distinct from option labels
+- Helper/error: 12px/400
+---
+## Keyboard & Accessibility
+> **WAI-ARIA role**: `radio` (implicit on `<input type="radio">`)
+> **Group role**: `radiogroup` (via `<fieldset>` + ARIA, or `role="radiogroup"` explicitly)
+> **Required attributes**: `name` (groups radios), `id` + `<label for>` per item
+### Keyboard Contract
+*Quoted verbatim from WAI-ARIA APG — https://www.w3.org/WAI/ARIA/apg/patterns/radio/ — W3C — 2024*
+| Key | Action |
+|-----|--------|
+| Tab | Moves focus into group (to the checked radio, or first if none checked) |
+| Tab (from within group) | Moves focus out of group to next focusable element |
+| Arrow Right / Arrow Down | Moves focus to next radio AND selects it |
+| Arrow Left / Arrow Up | Moves focus to previous radio AND selects it |
+| Space | If the focused radio is not selected, selects it |
+**Key insight**: Arrow keys move AND select simultaneously (auto-advance). This differs from checkboxes (Space toggles, Tab moves). Tab navigates in/out of the whole group as one focusable unit.
+### Accessibility Rules
+- `<fieldset>` + `<legend>` MUST wrap the entire group — legend text is prepended to each option announcement
+- All radios in a group MUST share the same `name` attribute
+- Tab focuses the selected radio (or first, if none selected) — arrow keys navigate within the group
+- Never use a single radio button — it creates a state the user cannot unset; use a checkbox
+- Error state applies to the group: `aria-describedby` on the `<fieldset>` or `role="radiogroup"` container
+- `required`: apply to all radios in the group or use `aria-required` on the group container
+---
+## Motion
+| Transition | Duration | Easing | Notes |
+|------------|----------|--------|-------|
+| Dot fill | 120ms | ease-out | Scale 0→1 from center |
+| Deselect | 80ms | ease | Dot scale 1→0 |
+| Hover border | 80ms | ease | Border colour only |
+Cross-link: `reference/motion.md` — `prefers-reduced-motion`: skip dot animation, show fill instantly
+---
+## Do / Don't
+### Do
+- Always use `<fieldset>` + `<legend>` for the group *(WAI-ARIA APG, Carbon, Polaris)*
+- Use the same `name` attribute for all radios in a group *(HTML spec, all systems)*
+- Pre-select a default option where appropriate to reduce cognitive load *(Material 3, Polaris)*
+- Use arrow keys to navigate within a group — Tab moves to the group, not each item *(WAI-ARIA APG)*
+### Don't
+- Don't use a single radio button — use a checkbox instead *(Material 3, Carbon, WAI-ARIA APG)*
+- Don't use radio buttons for mutually exclusive options that require confirmation — use a select *(Polaris)*
+- Don't mix radio and checkbox styles in the same group *(Carbon, Polaris)*
+- Don't require the user to make a selection before seeing other page content (premature required state) *(Polaris)*
+---
+## Anti-patterns Cross-links
+| Anti-pattern | Entry |
+|--------------|-------|
+| Lone radio button | `reference/anti-patterns.md` |
+---
+## Benchmark Citations
+| Claim | Sources |
+|-------|---------|
+| Arrow keys move + select simultaneously | WAI-ARIA APG §3.6 |
+| Tab focuses whole group as one unit | WAI-ARIA APG |
+| fieldset+legend required | WAI-ARIA APG, Carbon, Polaris |
+| Single radio = anti-pattern | Material 3, Carbon, WAI-ARIA APG |
+Full system URLs: `connections/design-corpora.md`
+---
+## Grep Signatures
+```bash
+# Single radio button (no group = unresettable state)
+grep -rn 'type="radio"' src/ | sort | uniq -c | sort -n | head
+# Radio group missing name attribute
+grep -rn 'type="radio"' src/ | grep -v 'name='
+# Radio group without fieldset or role="radiogroup"
+grep -rn 'type="radio"' src/ | grep -v 'fieldset\|role="radiogroup"'
+# Arrow key handler missing in custom radio implementation
+grep -rn 'role="radio"' src/ | grep -v 'ArrowDown\|ArrowUp\|onKeyDown'
+```
+---
+## Failing Example
+```html
+<!-- BAD: radio group without fieldset/legend and with keyboard nav broken -->
+<div>
+  <input type="radio" id="a" name="plan"> <label for="a">Starter</label>
+  <input type="radio" id="b" name="plan"> <label for="b">Pro</label>
+</div>
+```
+**Why it fails**: Screen reader announces each option without the group question. The `<div>` provides no semantic grouping; `<legend>` is not present, so users don't know what "Starter" and "Pro" refer to.
+**Grep detection**: `grep -B3 'type="radio"' src/ | grep '<div' | grep -v 'fieldset'`
+**Fix**:
+```html
+<fieldset>
+  <legend>Select your plan</legend>
+  <input type="radio" id="a" name="plan"> <label for="a">Starter</label>
+  <input type="radio" id="b" name="plan"> <label for="b">Pro</label>
+</fieldset>
+```