@hegemonart/get-design-done 1.16.0 → 1.19.0

package/agents/motion-mapper.md

@@ -25,6 +25,10 @@ You inventory motion and animation patterns. Zero session memory. You do not mod
 
 - `.design/STATE.md`
 - `reference/motion.md` (if present)
+- `reference/motion-advanced.md` (if present) — advanced patterns: spring physics, scroll-driven, FLIP, View Transitions API, gesture/drag mechanics, clip-path patterns, blur crossfades, Framer Motion hardware-accel gotcha
+- `reference/motion-easings.md` (if present) — 12 canonical easing presets; classify each detected easing against this catalog
+- `reference/motion-transition-taxonomy.md` (if present) — 8 transition families; classify page/route transitions against this taxonomy
+- `reference/motion-spring.md` (if present) — spring presets; classify spring configs against gentle/wobbly/stiff/slow
 - Any files supplied by the orchestrator
 
 ## Scan Strategy
@@ -61,8 +65,37 @@ From the collected values, bucket by:
 - Normal: 200–400ms
 - Slow: >400ms
 
+## Advanced Scan Patterns (Phase 18+)
+
+When `reference/motion-advanced.md` is present, additionally scan for:
+
+```bash
+# Gesture / drag patterns
+grep -rEn "setPointerCapture|onPointerDown.*drag|dragConstraints|useDragControls" src/ | head -40
+grep -rEn "velocity|flick|swipe.*dismiss|drag.*dismiss" src/ | head -40
+
+# Clip-path animations
+grep -rEn "clip-path|clipPath|inset\(" src/ | head -40
+
+# FLIP / View Transitions
+grep -rEn "layoutId|startViewTransition|view-transition-name" src/ | head -30
+
+# Scroll-driven
+grep -rEn "animation-timeline|ScrollTimeline|useScroll\b" src/ | head -30
+
+# WAAPI
+grep -rEn "\.animate\(\[|WebAnimation|getAnimations" src/ | head -20
+```
+
+Classify gesture patterns against `reference/motion-advanced.md` (velocity formula, pointer capture, multi-touch protection).
+Classify easing values against the 12 canonical presets in `reference/motion-easings.md`; output `"custom"` with justification for anything that doesn't match.
+Classify page/route transitions against the 8 families in `reference/motion-transition-taxonomy.md`.
+Classify spring configs against the 4 presets in `reference/motion-spring.md`.
+
 ## Output Format — `.design/map/motion.md`
 
+**The output MUST begin with a structured JSON block** enclosed in ` ```json ``` ` fences, followed by the prose sections. The JSON block must conform to `reference/output-contracts/motion-map.schema.json`. Malformed or missing blocks are validation failures.
+
 ```markdown
 ---
 generated: [ISO 8601]
@@ -70,22 +103,54 @@ generated: [ISO 8601]
 
 # Motion Map
 
+```json
+{
+  "schema_version": "1.0.0",
+  "generated_at": "[ISO 8601]",
+  "summary": {
+    "total_animations": 0,
+    "custom_easings": 0,
+    "reduced_motion_compliant": false,
+    "libraries": []
+  },
+  "animations": [
+    {
+      "id": "example-toast-enter",
+      "location": { "file": "src/components/Toast.tsx", "line": 12 },
+      "description": "Toast enter animation — opacity + translateY",
+      "easing": "cubic-out",
+      "duration_class": "quick",
+      "duration_ms": 180,
+      "trigger": "state-change",
+      "library": "framer-motion",
+      "reduced_motion_handled": true
+    }
+  ]
+}
+```
+
 ## CSS transitions
-| File | Property | Duration | Easing |
-|------|----------|----------|--------|
+| File | Property | Duration | Easing | Canonical Easing |
+|------|----------|----------|--------|-----------------|
 
 ## Library usage
 | Library | Files | Notes |
 |---------|-------|-------|
 
 ## Duration distribution
-- Fast (<200ms): [N]
-- Normal (200–400ms): [N]
-- Slow (>400ms): [N]
-
-## Easing functions
-| Easing | Count |
-|--------|-------|
+- Instant (<100ms): [N]
+- Quick (100–200ms): [N]
+- Standard (200–400ms): [N]
+- Slow (400–800ms): [N]
+- Narrative (>800ms): [N]
+
+## Easing classification
+| Detected Easing | Canonical Name | Count | Notes |
+|----------------|---------------|-------|-------|
+
+## Advanced patterns detected
+| Pattern | Files | Notes |
+|---------|-------|-------|
 
 ## Reduced-motion compliance
 - `prefers-reduced-motion` queries present: [N]

package/agents/token-mapper.md

@@ -119,6 +119,14 @@ After the standard token inventory, scan and report:
    - Check if they have `font-variant-numeric: tabular-nums` or Tailwind `tabular-nums` class
    - Report missing instances
 
+5. **Easing token consolidation** (when `reference/motion-easings.md` is present)
+   - Grep: `cubic-bezier\(` in CSS/SCSS/styled-components/Tailwind config
+   - Grep: `ease:` or `easing:` in Framer Motion / GSAP configs
+   - For each raw easing value found, check if a canonical `--ease-*` token from `reference/motion-easings.md` would serve the same purpose
+   - Report raw values that map to a canonical preset (recommend the `--ease-*` token)
+   - Report raw values with no canonical match as informational (may warrant a custom token)
+   - Do NOT flag values that are already using `--ease-*` tokens
+
 ### Output format:
 ```
 ## Micro-polish token findings

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hegemonart/get-design-done",
-  "version": "1.16.0",
+  "version": "1.19.0",
   "description": "A Claude Code plugin for systematic design improvement",
   "author": "Hegemon",
   "homepage": "https://github.com/hegemonart/get-design-done",
@@ -67,8 +67,22 @@
     "style-vocabulary",
     "industry-palettes",
     "ui-style-vocabulary",
+    "variable-fonts",
+    "container-queries",
+    "view-transitions",
+    "motion-vocabulary",
+    "motion-easings",
+    "transition-taxonomy",
+    "gesture-mechanics",
+    "clip-path-animation",
     "component-specs",
-    "design-system-benchmarks"
+    "design-system-benchmarks",
+    "i18n",
+    "user-research",
+    "information-architecture",
+    "form-patterns",
+    "data-viz",
+    "platforms"
   ],
   "skills": [
     "SKILL.md"

package/reference/components/README.md

@@ -41,40 +41,44 @@ Typography · Keyboard/a11y · Motion · Do/Don't · Anti-patterns · Citations
 
 ---
 
-## Wave 3 — Feedback *(Phase 17)*
+## Wave 3 — Feedback
 
 | Component | Spec | Purpose |
 |-----------|------|---------|
-| Toast / Snackbar | — | Ephemeral status notification |
-| Alert / Banner | — | Persistent inline status message |
-| Progress | — | Linear and circular completion indicator |
-| Skeleton | — | Loading placeholder matching content shape |
-| Badge | — | Numeric or status indicator overlaid on another element |
-| Chip / Tag | — | Compact, dismissible label |
+| Toast / Snackbar | [toast.md](toast.md) | Ephemeral status notification; auto-dismisses 4–8s |
+| Alert / Banner | [alert.md](alert.md) | Persistent inline status message; four severity variants |
+| Progress | [progress.md](progress.md) | Linear and circular completion indicator; determinate + indeterminate |
+| Skeleton | [skeleton.md](skeleton.md) | Loading placeholder matching content shape |
+| Badge | [badge.md](badge.md) | Numeric or status indicator overlaid on another element |
+| Chip / Tag | [chip.md](chip.md) | Compact toggleable/removable label; filter, input, suggestion, display |
 
 ---
 
-## Wave 4 — Navigation *(Phase 17)*
+## Wave 4 — Navigation & Data *(v1.17.0 · plan 17-02)*
 
 | Component | Spec | Purpose |
 |-----------|------|---------|
-| Breadcrumb | — | Hierarchical location trail |
-| Pagination | — | Page-set navigation |
-| Stepper | — | Sequential multi-step progress indicator |
-| Navigation Menu | — | Top-level or sidebar navigation |
-| Command Menu | — | Keyboard-first search + action launcher |
+| Menu | [menu.md](menu.md) | Dropdown and context menu; action list with ARIA menu roles |
+| Navbar | [navbar.md](navbar.md) | Top navigation bar; primary nav + skip link + mobile hamburger |
+| Sidebar | [sidebar.md](sidebar.md) | Collapsible side navigation panel; icon+label / icon-only states |
+| Breadcrumbs | [breadcrumbs.md](breadcrumbs.md) | Hierarchical location trail; aria-current + hidden separators |
+| Pagination | [pagination.md](pagination.md) | Page-set navigation; previous/next + page buttons + per-page |
+| Table | [table.md](table.md) | Data table with sorting, selection, sticky header, virtualisation |
+| List | [list.md](list.md) | Display list (`<ul>/<ol>`) and interactive listbox (`role="listbox"`) |
+| Tree | [tree.md](tree.md) | Hierarchical tree view; expand/collapse with full ARIA tree roles |
+| Command Palette | [command-palette.md](command-palette.md) | Global Cmd/Ctrl+K launcher; dialog + combobox + listbox pattern |
 
 ---
 
-## Wave 5 — Data & Advanced *(Phase 17)*
+## Wave 5 — Data & Advanced
 
 | Component | Spec | Purpose |
 |-----------|------|---------|
-| Table / Data Grid | — | Tabular data with sorting, filtering, selection |
-| Date Picker | — | Calendar-based date/range selection |
-| File Upload | — | Drag-drop or browse file input |
-| Rich Text Editor | — | WYSIWYG content authoring |
-| Virtualized List | — | Windowed rendering for large datasets |
+| Date Picker | [date-picker.md](date-picker.md) | Calendar-based date/range selection; input + popover variants |
+| Slider | [slider.md](slider.md) | Single-value and range thumb on a track; full keyboard contract |
+| File Upload | [file-upload.md](file-upload.md) | Drag-drop zone + accessible file input; per-file progress list |
+| Rich-Text Editor | [rich-text-editor.md](rich-text-editor.md) | WYSIWYG authoring with contenteditable + toolbar + mentions |
+| Stepper / Wizard | [stepper.md](stepper.md) | Sequential multi-step flow; role="list" (not tablist) |
 
 ---
 
@@ -84,7 +88,7 @@ Typography · Keyboard/a11y · Motion · Do/Don't · Anti-patterns · Citations
 |------|-------|--------|
 | Wave 1 — Inputs | 8 | v1.16.0 |
 | Wave 2 — Containers | 7 | v1.16.0 |
-| Wave 3 — Feedback | 6 | Phase 17 |
-| Wave 4 — Navigation | 5 | Phase 17 |
-| Wave 5 — Data & Advanced | 5 | Phase 17 |
-| **Total** | **31** | — |
+| Wave 3 — Feedback | 6 | v1.17.0 |
+| Wave 4 — Navigation & Data | 9 | v1.17.0 |
+| Wave 5 — Data & Advanced | 5 | v1.17.0 |
+| **Total** | **35** | — |

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.

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