@hegemonart/get-design-done 1.15.0 → 1.18.0

package/reference/components/badge.md

@@ -0,0 +1,202 @@
+# Badge — Benchmark Spec
+
+**Harvested from**: Material 3, Polaris, Carbon, Radix
+**Wave**: 3 · **Category**: Feedback
+
+---
+
+## Purpose
+
+A badge is a compact numeric counter or status indicator overlaid on or beside a parent element (icon, avatar, button) to communicate a count (unread messages, notification count) or status (online, offline, busy). It is purely decorative — the accessible count or status is surfaced through the parent element's `aria-label`. *(Material 3, Polaris, Carbon, Radix agree: badge is decorative; parent carries accessible state)*
+
+---
+
+## Anatomy
+
+**Attached (overlay)**
+```
+┌──────────────────────┐
+│    [icon/avatar]     │
+│                  ┌──┐│
+│                  │ 3││  ← badge, position: absolute top-right
+│                  └──┘│
+└──────────────────────┘
+↑ parent: aria-label="Messages, 3 unread"
+```
+
+**Standalone**
+```
+  ┌──────┐
+  │  99+ │  ← badge standalone (rare; decorative in a list)
+  └──────┘
+```
+
+| Part | Required | Notes |
+|------|----------|-------|
+| Badge element | Yes | Pill or circle shape containing count or dot |
+| Count / label text | Conditional | Present for count/icon variants; absent for dot |
+| Parent element | Yes (for attached) | Carries `aria-label` with accessible count |
+| Dot indicator | No | Status dot variant — no number, pure color/shape |
+
+---
+
+## Variants
+
+| Variant | Description | Systems |
+|---------|-------------|---------|
+| Count | Numeric; shows integer up to 99, then "99+" | Material 3, Polaris, Carbon, Radix |
+| Dot | Status indicator; no number; color/position only | Material 3, Polaris, Radix |
+| Icon overlay | Small icon inside badge shape (rare) | Material 3 |
+
+**Norm** (≥4/18 systems agree): count badges cap display at "99+"; zero count hidden by default; dot variant uses the same position/size slot as count but without text.
+**Diverge**: Material 3 calls the dot variant "small badge" (8px, no content) vs. "large badge" (16px+, with number); Polaris uses "badge" exclusively for text status labels (not overlaid); Carbon uses "tag" for text labels, "notification badge" for counts. Radix provides a headless primitive suitable for all variants.
+
+---
+
+## States
+
+| State | Trigger | Visual | ARIA |
+|-------|---------|--------|------|
+| default | count > 0 | Badge visible, pill shape | Parent `aria-label` updated |
+| zero | count = 0 | Badge hidden (default); visible if `showZero` prop | Parent `aria-label` reflects 0 or omits count |
+| max overflow | count > 99 | Renders "99+" | Parent `aria-label` says "99 or more unread" |
+| dot status | status active | Dot visible; colored by status | Parent `aria-label` includes status text |
+
+---
+
+## Sizing & Spacing
+
+| Variant | Min height | Min width | Font size | Notes |
+|---------|-----------|-----------|-----------|-------|
+| Count (sm) | 16px | 16px (= height) | 10px/500 | Single digit fills circle |
+| Count (md) | 20px | 20px (= height) | 12px/500 | Two-digit + "99+" |
+| Dot | 8px | 8px | — | No text; absolute top-right |
+
+- **Shape**: pill when width > height; circle when width = height (single digit)
+- **Position** (attached): `position: absolute; top: -4px; right: -4px` relative to parent
+- **Min-width = height** (pill rule): ensures pill does not compress on 2-digit counts
+
+**Norm**: 16–20px height; 10–12px font-size; min-width equals height *(Material 3, Polaris, Carbon)*.
+
+---
+
+## Typography
+
+- Count text: 10–12px / 500 (medium weight) — legible at small scale
+- No wrapping; never truncate count text; use "99+" cap instead
+- Letter-spacing: 0 — tight spacing at 10–12px scale
+
+Cross-link: `reference/typography.md` — small label scale (10–12px)
+
+---
+
+## Keyboard & Accessibility
+
+> **WAI-ARIA role**: none (decorative); parent element carries accessible count via `aria-label`
+> **Required attributes**: none on badge itself; `aria-label` on parent with count embedded
+
+### Keyboard Contract
+
+*Quoted verbatim from WAI-ARIA APG — https://www.w3.org/WAI/ARIA/apg/ — W3C — 2024*
+
+| Key | Action |
+|-----|--------|
+| (none) | Badge is non-interactive; no keyboard behavior |
+
+Badge never receives focus. It is a purely visual overlay. All keyboard interaction is on the parent element.
+
+### Accessibility Rules
+
+- Badge element itself MUST have `aria-hidden="true"` — screen readers should not announce the badge number separately; they read it as part of the parent's `aria-label`
+- Parent element MUST have an `aria-label` that includes the count: `aria-label="Messages, 3 unread"` *(WAI-ARIA APG, Material 3)*
+- Parent `aria-label` MUST be updated dynamically when count changes — use `aria-live` on the parent if the count changes while the page is rendered *(WCAG 4.1.3)*
+- Zero badge: if badge is hidden at zero, remove it from DOM (or `display: none`) — do NOT leave it with empty text in the DOM *(Polaris)*
+- Dot variant: parent `aria-label` MUST include the status: `aria-label="User profile, status: online"` *(Radix)*
+- Never rely on badge color alone to communicate status — include text in parent `aria-label` *(WCAG 1.4.1)*
+
+Cross-link: `reference/accessibility.md` — dynamic label updates, aria-live
+
+---
+
+## Motion
+
+| Transition | Duration | Easing | Notes |
+|------------|----------|--------|-------|
+| Count increment (scale pulse) | 150ms | ease-out | Brief scale 1.2 → 1.0 on value change |
+| Badge appear | 100ms | ease-out | Fade + scale from 0.5 |
+| Badge disappear (at zero) | 80ms | ease-in | Fade + scale to 0 |
+
+**BAN**: Continuous bounce animation on badge — implies urgency and is distracting; one-shot pulse on value change is acceptable.
+
+Cross-link: `reference/motion.md` — scale-in/scale-out; `prefers-reduced-motion`: skip all badge animation
+
+---
+
+## Do / Don't
+
+### Do
+- Include count in parent `aria-label`: `aria-label="Inbox, 5 unread messages"` *(WAI-ARIA APG)*
+- Add `aria-hidden="true"` to the badge element itself *(WAI-ARIA APG)*
+- Cap numeric display at "99+" and update parent label to "99 or more" *(Material 3, Carbon)*
+- Hide badge when count is 0 by default; offer `showZero` prop for product preference *(Polaris, Radix)*
+
+### Don't
+- Don't surface badge count only through color (dot badge without parent label) *(WCAG 1.4.1)*
+- Don't put interactive content in a badge — it is always decorative *(Material 3, Carbon)*
+- Don't animate badge continuously — one-shot pulse on value change only *(Polaris)*
+- Don't use badge text as the only accessible notification — always update parent `aria-label` *(WAI-ARIA APG)*
+
+---
+
+## Anti-patterns Cross-links
+
+| Anti-pattern | Entry |
+|--------------|-------|
+| Color as sole status differentiator | `reference/anti-patterns.md#ban-color-only` |
+| Missing aria-label on parent with count | `reference/anti-patterns.md#ban-aria-label` |
+
+---
+
+## Benchmark Citations
+
+| Claim | Sources |
+|-------|---------|
+| Badge is decorative; parent carries aria-label | Material 3, Polaris, Carbon, Radix |
+| Count capped at "99+" | Material 3, Carbon, Radix |
+| 16–20px height; min-width = height | Material 3, Polaris, Carbon |
+| Zero badge hidden by default | Polaris, Radix |
+| aria-hidden="true" on badge element | WAI-ARIA APG |
+| Parent aria-label updated on count change | WCAG 4.1.3 |
+
+Full system URLs: `connections/design-corpora.md`
+
+---
+
+## Grep Signatures
+
+```bash
+# Badge count not surfaced in parent aria-label
+grep -rn 'badge\|Badge' src/ | grep -v 'aria-label' | grep -v 'aria-hidden'
+
+# Badge element missing aria-hidden
+grep -rn 'class.*badge\|className.*badge' src/ | grep -v 'aria-hidden="true"'
+
+# Parent with badge but no aria-label
+grep -rn 'badge\|Badge' src/ -l | xargs grep -l 'button\|icon\|avatar' | xargs grep -L 'aria-label'
+```
+
+---
+
+## Failing Example
+
+```html
+<!-- BAD: badge count visible but parent has no aria-label for screen readers -->
+<button class="icon-btn">
+  <svg aria-hidden="true"><!-- bell icon --></svg>
+  <span class="badge">3</span>
+</button>
+```
+
+**Why it fails**: Screen readers announce "button" with no mention of the count. The `<span class="badge">3</span>` may be announced as isolated "3" out of context, or the badge text is read before the button label, producing confusing output. The button has no accessible name describing its purpose or the notification count.
+**Grep detection**: `grep -rn 'class.*badge' src/ | xargs grep -B2 -A2 'button\|icon' | grep -v 'aria-label'`
+**Fix**: `<button class="icon-btn" aria-label="Notifications, 3 unread"><svg aria-hidden="true">…</svg><span class="badge" aria-hidden="true">3</span></button>`

package/reference/components/breadcrumbs.md

@@ -0,0 +1,198 @@
+# Breadcrumbs — Benchmark Spec
+
+**Harvested from**: WAI-ARIA APG, Carbon, Polaris, Material 3, Atlassian
+**Wave**: 4 · **Category**: Navigation
+
+---
+
+## Purpose
+
+A breadcrumb trail shows a user's location within a hierarchical navigation structure, providing a supplemental path back to any ancestor page. It is not primary navigation — the current page is always the last item and is never a link. Breadcrumbs are most valuable in deep hierarchies (> 2 levels) and information-dense applications. *(WAI-ARIA APG breadcrumb pattern, Carbon, Polaris, Material 3, Atlassian all define breadcrumb as a supplemental location indicator)*
+
+---
+
+## Anatomy
+
+```
+<nav aria-label="Breadcrumb">
+  <ol role="list">
+    <li><a href="/">Home</a></li>
+    <li><span aria-hidden="true">›</span><a href="/products">Products</a></li>
+    <li><span aria-hidden="true">›</span><span aria-current="page">Widget Pro</span></li>
+  </ol>
+</nav>
+```
+
+| Part | Required | Notes |
+|------|----------|-------|
+| `<nav>` container | Yes | `role="navigation"` + `aria-label="Breadcrumb"` |
+| `<ol>` list | Yes | Ordered list — sequence matters |
+| `<li>` items | Yes | One per level in the path |
+| Ancestor links | Yes | `<a href>` pointing to each ancestor URL |
+| Current page | Yes | Plain text `<span>` (not a link) + `aria-current="page"` |
+| Separator | Yes | `aria-hidden="true"` character or SVG icon; never in link text |
+| Ellipsis (deep paths) | No | Truncate middle items at > 4 levels; always keep first + last 2 |
+
+---
+
+## Variants
+
+| Variant | Description | Systems |
+|---------|-------------|---------|
+| Default | Inline trail, all items visible | All systems |
+| Collapsed / truncated | Middle items replaced by "…" at > 4 levels | Carbon, Polaris, Atlassian |
+| With icons | Leading icon per item (folder/page icon) | Material 3, Atlassian |
+| Large / heading-inline | Larger type, sits beside or below a page title | Polaris, Atlassian |
+
+**Norm** (≥4 systems agree): separator is `aria-hidden`; current page uses `aria-current="page"`; last item is never a link.
+**Diverge**: Polaris uses `>` as separator; Carbon uses `/`; Material 3 uses `›` (chevron). All are acceptable — choose to match your product's visual language.
+
+---
+
+## States
+
+| State | Trigger | Visual | ARIA |
+|-------|---------|--------|------|
+| default | — | Ancestor links + muted separator + current page text | — |
+| link-hover | pointer over ancestor | Underline or color shift | — |
+| link-focus | keyboard focus on ancestor | 2px focus-visible ring | — |
+| current | — | No underline; muted or bold treatment; not clickable | `aria-current="page"` |
+| truncated | path > 4 levels | Middle items hidden; "…" button shown | `aria-label="Show full path"` on ellipsis button |
+
+---
+
+## Sizing & Spacing
+
+| Element | Value | Notes |
+|---------|-------|-------|
+| Item font size | 13–14px (body-sm) | Smaller than page headings; supplemental context |
+| Item height | 24–32px | Allow for comfortable touch targets on mobile |
+| Separator spacing | 4–8px H padding each side | Optical breathing room |
+| Max visible levels | 4 | Truncate middle items beyond 4 levels |
+| Truncation rule | Keep: first + last 2 items | Never truncate the current page or the root |
+
+**Norm**: 13–14px font size (Carbon, Polaris, Atlassian); items on a single line; no wrapping.
+
+---
+
+## Typography
+
+- Ancestor links: body-sm, weight 400, `color: --text-link`; underline on hover
+- Current page: body-sm, weight 500 or 600 (bold for emphasis), `color: --text-primary`; no underline
+- Separator: body-sm, `color: --text-subtle`, `aria-hidden="true"`
+- Do not use uppercase or letter-spacing on breadcrumb items — they should read as natural path segments
+
+Cross-link: `reference/typography.md` — body-sm, link color tokens
+
+---
+
+## Keyboard & Accessibility
+
+> **WAI-ARIA role**: `navigation` (container)
+> **Required attributes**: `aria-label="Breadcrumb"` on `<nav>`; `aria-current="page"` on last item; `aria-hidden="true"` on separators
+
+### Keyboard Contract
+
+*Quoted verbatim from WAI-ARIA APG — https://www.w3.org/WAI/ARIA/apg/patterns/breadcrumb/ — W3C — 2024*
+
+| Key | Action |
+|-----|--------|
+| Tab | Moves focus to next focusable link in the breadcrumb trail |
+| Shift+Tab | Moves focus to previous link |
+| Enter | Activates the focused link (navigates to ancestor) |
+
+### Accessibility Rules
+
+- `aria-current="page"` MUST be on the last item (current page) — this is the primary AT signal
+- Separators MUST be `aria-hidden="true"` — screen readers should announce "Home, Products, Widget Pro" not "Home › Products › Widget Pro"
+- The current page item MUST NOT be a link — it is the user's current location
+- `<ol>` conveys that order matters; do not use `<ul>` or a `<div>` list
+- `aria-label="Breadcrumb"` distinguishes this nav from primary/secondary navigation landmarks
+
+Cross-link: `reference/accessibility.md` — aria-current, landmark labelling
+
+---
+
+## Motion
+
+| Transition | Duration | Easing | Notes |
+|------------|----------|--------|-------|
+| Ellipsis expand | 150ms | ease-out | Reveal hidden items inline |
+| Ellipsis collapse | 120ms | ease-in | Hide middle items |
+
+**BAN**: Do not animate the breadcrumb trail on route change — route transitions are the page's responsibility, not the breadcrumb's.
+
+Cross-link: `reference/motion.md` — layout transitions
+
+---
+
+## Do / Don't
+
+### Do
+- Use `<ol>` for the list — order is meaningful in a hierarchical path *(WAI-ARIA APG)*
+- Mark the current page with `aria-current="page"` — not just a CSS class *(WAI-ARIA APG, Atlassian)*
+- Hide separators with `aria-hidden="true"` *(WAI-ARIA APG, Carbon, Polaris)*
+- Truncate middle items (not first/last) when path exceeds 4 levels *(Carbon, Polaris, Atlassian)*
+
+### Don't
+- Don't make the current page item a link — it creates a circular self-referential link *(WAI-ARIA APG)*
+- Don't include separator text inside link labels — `aria-hidden` the separator element, not the link *(WAI-ARIA APG)*
+- Don't use breadcrumbs as the only navigation method — they supplement; primary nav is required *(Material 3, Polaris)*
+- Don't truncate the root or current page items — users need anchoring context at both ends *(Carbon, Atlassian)*
+
+---
+
+## Anti-patterns Cross-links
+
+| Anti-pattern | Entry |
+|--------------|-------|
+| BAN-07 | Missing `aria-current` on active navigation items — `reference/anti-patterns.md#ban-07` |
+
+---
+
+## Benchmark Citations
+
+| Claim | Sources |
+|-------|---------|
+| aria-label="Breadcrumb" on nav container | WAI-ARIA APG breadcrumb pattern |
+| Separator must be aria-hidden | WAI-ARIA APG, Carbon, Polaris, Atlassian |
+| Last item not a link + aria-current="page" | WAI-ARIA APG, Carbon, Polaris, Material 3 |
+| Ordered list (`<ol>`) for hierarchy | WAI-ARIA APG |
+| Truncate middle at > 4 levels | Carbon, Polaris, Atlassian |
+
+Full system URLs: `connections/design-corpora.md`
+
+---
+
+## Grep Signatures
+
+```bash
+# Last breadcrumb item is a link (should be plain text with aria-current)
+grep -rn 'breadcrumb\|bread-crumb' src/ | grep -v 'aria-current="page"'
+
+# Separator not aria-hidden
+grep -rn 'breadcrumb' src/ | grep '›\|/\|>\|chevron' | grep -v 'aria-hidden'
+
+# Using <ul> instead of <ol> for breadcrumb
+grep -rn 'breadcrumb' src/ | grep '<ul'
+
+# nav container missing aria-label
+grep -rn 'breadcrumb' src/ | grep '<nav' | grep -v 'aria-label'
+```
+
+---
+
+## Failing Example
+
+```html
+<!-- BAD: all items are links including the current page, separators not hidden -->
+<nav>  <!-- missing aria-label="Breadcrumb" -->
+  <a href="/">Home</a> /
+  <a href="/products">Products</a> /
+  <a href="/products/widget-pro">Widget Pro</a>  <!-- should NOT be a link; no aria-current -->
+</nav>
+```
+
+**Why it fails**: Current page is a link (circular/confusing); separators `/` are announced by screen readers; `<nav>` has no label; no `aria-current="page"` to signal location to AT users; no `<ol>/<li>` structure loses hierarchy semantics.
+**Grep detection**: `grep -rn 'breadcrumb' src/ | grep -v 'aria-current'`
+**Fix**: Replace last `<a>` with `<span aria-current="page">Widget Pro</span>`; wrap separators in `<span aria-hidden="true">/</span>`; add `aria-label="Breadcrumb"` to `<nav>`; wrap items in `<ol><li>`.

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.