@hegemonart/get-design-done 1.15.0 → 1.18.0

package/reference/components/popover.md

@@ -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/progress.md

@@ -0,0 +1,210 @@
+# Progress — Benchmark Spec
+
+**Harvested from**: Material 3, Carbon (ProgressIndicator), Polaris, Mantine
+**Wave**: 3 · **Category**: Feedback
+
+---
+
+## Purpose
+
+A progress indicator communicates the status of an ongoing operation. Determinate variants show a known percentage of completion (0–100%); indeterminate variants signal ongoing work when duration is unknown. Linear bars are suited to step-based or file-based progress; circular (spinner-ring) variants are suited to inline or compact contexts. *(Material 3, Carbon, Polaris, Mantine agree: separate determinate vs. indeterminate; linear vs. circular)*
+
+---
+
+## Anatomy
+
+**Linear**
+```
+[track ──────────────────────────────────]
+[fill ◼◼◼◼◼◼◼◼◼◼◼◼◼◼·····················]
+      ↑ role="progressbar" aria-valuenow="45"
+```
+
+**Circular**
+```
+    ╭──╮
+   ╭    ╮
+   ╰    ╯ ← SVG stroke-dashoffset ring
+    ╰──╯
+  role="progressbar"
+```
+
+| Part | Required | Notes |
+|------|----------|-------|
+| Track | Yes | Background rail (linear) or ring background (circular) |
+| Fill / indicator | Yes | Foreground showing progress amount |
+| Label (visually hidden ok) | Yes | `aria-label` or `aria-labelledby` — describes what is loading |
+| Value text | No | Rendered percentage (e.g. "45%") — supplement to ARIA value |
+
+---
+
+## Variants
+
+| Variant | Description | Systems |
+|---------|-------------|---------|
+| Linear determinate | Bar fills left-to-right proportionally | Material 3, Carbon, Polaris, Mantine |
+| Linear indeterminate | Bar animates in loop (shimmer or sweep) | Material 3, Carbon, Polaris, Mantine |
+| Circular determinate | SVG ring fills by stroke-dashoffset | Material 3, Carbon, Mantine |
+| Circular indeterminate | SVG ring rotates in loop | Material 3, Carbon, Mantine |
+
+**Norm** (≥4/18 systems agree): `role="progressbar"` on all variants; `aria-valuenow` only on determinate; `aria-valuemin=0` + `aria-valuemax=100` always.
+**Diverge**: Polaris calls the circular variant "Spinner" (single indeterminate state only); Material 3 distinguishes "linear progress indicator" and "circular progress indicator" as separate component families; Carbon offers multi-step linear progress ("ProgressStep") as a distinct component.
+
+---
+
+## States
+
+| State | Trigger | Visual | ARIA |
+|-------|---------|--------|------|
+| determinate (0–100%) | known progress value | Fill width/stroke = percentage | `aria-valuenow={n}` |
+| indeterminate | unknown duration | Looping animation | `aria-valuetext="Loading"` |
+| complete | value reaches 100% | Full fill; brief hold before removal | `aria-valuenow="100"` |
+| paused | operation suspended | Static fill; muted color | `aria-valuetext="Paused"` |
+
+---
+
+## Sizing & Spacing
+
+**Linear**
+
+| Size | Height | Notes |
+|------|--------|-------|
+| sm | 4px (default) | Decorative; thin above content |
+| md | 8px | Accessible minimum — recommended when bar is the primary indicator |
+| lg | 12px | High-emphasis; file upload, step progress |
+
+**Circular**
+
+| Size | Diameter | Stroke width | Notes |
+|------|----------|-------------|-------|
+| sm | 20px | 2px | Inline within text/button |
+| md | 32px | 3px | Component-level loading |
+| lg | 48px | 4px | Page/section loading |
+
+**Norm**: 4px linear height default (Material 3); 8px recommended for standalone accessibility *(Carbon)*; circular diameter 20–48px *(Material 3, Mantine)*.
+
+---
+
+## Typography
+
+- Value label (if shown): numeric-sm (12px/tabular-nums) — percentage readability
+- Associated label (if visible): body-sm (14px/400) — describes what is loading
+- Do not truncate the associated label; use a visually-hidden version if space is constrained
+
+Cross-link: `reference/typography.md` — tabular-nums for percentage values
+
+---
+
+## Keyboard & Accessibility
+
+> **WAI-ARIA role**: `progressbar`
+> **Required attributes**: `aria-valuemin="0"`, `aria-valuemax="100"`, `aria-label` or `aria-labelledby`; `aria-valuenow` on determinate only
+
+### Keyboard Contract
+
+*Quoted verbatim from WAI-ARIA APG — https://www.w3.org/WAI/ARIA/apg/patterns/meter/ — W3C — 2024*
+
+| Key | Action |
+|-----|--------|
+| (none) | Progress bar is not interactive; no keyboard interaction required |
+
+Progress indicators are read-only status elements. They receive no keyboard focus unless embedded in a larger focusable region.
+
+### Accessibility Rules
+
+- `aria-label` or `aria-labelledby` MUST describe what is loading (e.g. "Uploading file", "Loading results") — a bare `role="progressbar"` with no label is announced as empty *(WAI-ARIA APG)*
+- Determinate bars MUST include `aria-valuenow` matching the current integer percentage *(WAI-ARIA APG)*
+- Indeterminate bars MUST omit `aria-valuenow` and instead set `aria-valuetext="Loading"` or similar *(WAI-ARIA APG)*
+- `aria-valuemin` and `aria-valuemax` MUST be present on all progress bars (default 0 and 100)
+- Indeterminate animation MUST respect `prefers-reduced-motion` — reduce to opacity pulse or static indicator *(WCAG 2.3.3)*
+- Color contrast of fill vs. track MUST meet 3:1 minimum for non-text UI components *(WCAG 1.4.11)*
+
+Cross-link: `reference/accessibility.md` — `prefers-reduced-motion`, WCAG 1.4.11
+
+---
+
+## Motion
+
+| Transition | Duration | Easing | Notes |
+|------------|----------|--------|-------|
+| Determinate fill advance | 300ms | ease-out | Smooth value update on change |
+| Indeterminate linear sweep | 1.2s | ease-in-out | Infinite loop; reverse direction at 50% |
+| Circular spin | 1.2s | linear | Single full rotation per cycle |
+| Complete → remove | 400ms | ease-in | Brief hold at 100% then fade/collapse |
+
+**BAN**: Bouncing or elasticity on indeterminate loop — communicates false progress rhythm. Do not use `transition: all` (catches color changes during theme swap).
+
+Cross-link: `reference/motion.md` — `prefers-reduced-motion`: replace sweep with opacity 0.5→1 pulse
+
+---
+
+## Do / Don't
+
+### Do
+- Always provide `aria-label` describing what is loading *(WAI-ARIA APG)*
+- Use `aria-valuenow` on determinate variants and omit on indeterminate *(WAI-ARIA APG)*
+- Use 8px+ height for standalone linear bars — 4px bars lack sufficient touch and visual target *(Carbon)*
+- Transition fill smoothly (300ms ease-out) when value updates *(Material 3, Mantine)*
+
+### Don't
+- Don't use `aria-valuenow` on indeterminate bars — it implies a known value *(WAI-ARIA APG)*
+- Don't show a spinner (circular indeterminate) when content shape is known — use Skeleton instead *(Carbon, Polaris)*
+- Don't remove the progress bar the instant it hits 100% — hold briefly so the completion is registered *(Material 3)*
+- Don't animate with infinite bounce — implies bouncing progress rhythm *(Carbon, Mantine)*
+
+---
+
+## Anti-patterns Cross-links
+
+| Anti-pattern | Entry |
+|--------------|-------|
+| Indeterminate bar with aria-valuenow | `reference/anti-patterns.md#ban-aria-value` |
+| Spinner used when content shape is known | `reference/anti-patterns.md#ban-spinner-overuse` |
+
+---
+
+## Benchmark Citations
+
+| Claim | Sources |
+|-------|---------|
+| role="progressbar" on all variants | WAI-ARIA APG |
+| aria-valuenow only on determinate | WAI-ARIA APG, Material 3, Carbon |
+| aria-label required (what is loading) | WAI-ARIA APG |
+| 8px accessible minimum height | Carbon |
+| 1.2s animation loop duration | Material 3, Mantine |
+| Respect prefers-reduced-motion | WCAG 2.3.3 |
+
+Full system URLs: `connections/design-corpora.md`
+
+---
+
+## Grep Signatures
+
+```bash
+# Progress bar missing aria-label or aria-labelledby
+grep -rn 'role="progressbar"' src/ | grep -v 'aria-label\|aria-labelledby'
+
+# Determinate progress missing aria-valuenow
+grep -rn 'role="progressbar"' src/ | grep -v 'aria-valuenow\|indeterminate'
+
+# Progress missing valuemin/valuemax
+grep -rn 'role="progressbar"' src/ | grep -v 'aria-valuemin\|aria-valuemax'
+
+# Indeterminate with aria-valuenow (invalid pattern)
+grep -rn 'indeterminate' src/ | grep 'aria-valuenow'
+```
+
+---
+
+## Failing Example
+
+```html
+<!-- BAD: progress bar with no accessible label and no value attributes -->
+<div class="progress-bar">
+  <div class="progress-bar__fill" style="width: 45%"></div>
+</div>
+```
+
+**Why it fails**: No `role="progressbar"` so screen readers do not recognize this as a progress indicator. No `aria-label` so there is no description of what is loading. No `aria-valuenow`, `aria-valuemin`, or `aria-valuemax` so screen readers cannot read the percentage even if the role were present.
+**Grep detection**: `grep -rn 'progress-bar\|progressBar\|progress__fill' src/ | grep -v 'role="progressbar"'`
+**Fix**: `<div role="progressbar" aria-valuenow="45" aria-valuemin="0" aria-valuemax="100" aria-label="Uploading file"><div style="width:45%"></div></div>`

package/reference/components/radio.md

@@ -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>
+```