@hegemonart/get-design-done 1.16.0 → 1.18.0

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

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