@hegemonart/get-design-done 1.16.0 → 1.18.0

package/reference/components/navbar.md

@@ -0,0 +1,211 @@
+# Navbar (Top Navigation Bar) — Benchmark Spec
+
+**Harvested from**: Material 3, Carbon, Polaris, Atlassian, Primer, UUPM (app-interface, MIT)
+**Wave**: 4 · **Category**: Navigation
+
+---
+
+## Purpose
+
+A navbar is the primary horizontal navigation surface at the top of an application. It houses the logo/home link, primary navigation destinations, and secondary actions (search, notifications, profile). It communicates the application's identity and provides always-visible wayfinding. Differs from a Sidebar (vertical, secondary nav) and Breadcrumb (trail-based context). *(Material 3, Carbon, Polaris, Atlassian agree: top navbar = primary navigation + brand identity)*
+
+---
+
+## Anatomy
+
+```
+┌──────────────────────────────────────────────────────┐  role="banner"
+│ [Skip to main]  (visually hidden, focus-visible)     │
+│ [Logo/Home] | Nav Item · Nav Item · Nav Item | [🔍][👤]│  role="navigation" aria-label="Primary"
+└──────────────────────────────────────────────────────┘
+```
+
+| Part | Required | Notes |
+|------|----------|-------|
+| `<header>` wrapper | Yes | `role="banner"` — one per page |
+| `<nav>` | Yes | `role="navigation"` + `aria-label="Primary"` |
+| Skip-to-main link | Yes | First focusable element; `href="#main-content"`; visible on focus |
+| Logo / home link | Yes | `<a href="/">` with `aria-label="[App name] home"` |
+| Nav items | Yes | `<a>` for routing; `aria-current="page"` on active item |
+| Secondary actions | No | Icon buttons (search, notifications, profile) |
+| Hamburger button | Conditional | Mobile only; `aria-expanded` + `aria-controls` |
+| Scroll shadow | No | `box-shadow` appears on scroll > 0px |
+
+---
+
+## Variants
+
+| Variant | Description | Systems |
+|---------|-------------|---------|
+| Default / static | Fixed in document flow; scrolls with page | Carbon, Polaris |
+| Sticky / fixed | `position: sticky` or `fixed`; stays at top on scroll | Material 3, Atlassian, Primer |
+| Transparent hero | Transparent over hero image; becomes opaque on scroll | Material 3, Polaris |
+| Compact / dense | Reduced height (48px) for data-heavy apps | Carbon, UUPM app-interface |
+| Dashboard navbar | App-switcher + user avatar + notifications | UUPM app-interface (MIT) |
+| Settings navbar | Breadcrumb-style subtitle below app name | UUPM app-interface (MIT) |
+
+**Norm** (≥4 systems agree): 56–64px height; logo left-aligned; secondary actions right-aligned.
+**Diverge**: Material 3 distinguishes "Top app bar" (mobile) from "Navigation bar" (desktop) as separate components; other systems use a single responsive navbar.
+
+---
+
+## States
+
+| State | Trigger | Visual | ARIA |
+|-------|---------|--------|------|
+| default | — | Full nav visible, no shadow | — |
+| scrolled | scroll > 0 | `box-shadow` bottom border appears | — |
+| nav-item-hover | pointer over item | underline or bg highlight | — |
+| nav-item-focus | keyboard focus | 2px focus-visible ring | — |
+| nav-item-active | current route | `font-weight: 600` + indicator underline or pill | `aria-current="page"` |
+| mobile-collapsed | viewport < breakpoint | Nav items hidden; hamburger visible | `aria-expanded="false"` on hamburger |
+| mobile-expanded | hamburger activated | Nav items shown as vertical list | `aria-expanded="true"` on hamburger |
+
+---
+
+## Sizing & Spacing
+
+| Size | Height | Logo H | Item padding H | Font |
+|------|--------|--------|----------------|------|
+| compact | 48px | 24px | 12px | 13px/500 |
+| default | 56px | 28px | 16px | 14px/500 |
+| comfortable | 64px | 32px | 20px | 15px/500 |
+
+**Norm**: 56px default height (Material 3, Carbon, Polaris, Atlassian all converge here).
+Mobile breakpoint: collapse at ≤768px (Carbon, Polaris); ≤960px for complex navbars (Atlassian).
+
+---
+
+## Typography
+
+- Nav item labels: body-sm to body-md (13–15px), weight 500 for active, 400 for inactive
+- Active item visual distinction must not rely on color alone (add font-weight or underline indicator)
+- Secondary action icons: 20px, with `aria-label` on each button
+- Skip link text: `body-sm`, matches surrounding text — it only needs to be visible on focus
+
+Cross-link: `reference/typography.md` — body scale, weight tokens
+
+---
+
+## Keyboard & Accessibility
+
+> **WAI-ARIA role**: `banner` (header), `navigation` (nav)
+> **Required attributes**: `aria-label="Primary"` on `<nav>`; `aria-current="page"` on active item; `aria-expanded` + `aria-controls` on hamburger
+
+### Keyboard Contract
+
+*Quoted verbatim from WAI-ARIA APG — https://www.w3.org/WAI/ARIA/apg/patterns/landmark-regions/ — W3C — 2024*
+
+| Key | Action |
+|-----|--------|
+| Tab | Moves focus through focusable nav elements in DOM order |
+| Shift+Tab | Moves focus backwards |
+| Enter / Space | Activates focused link or button |
+| Escape | Closes mobile expanded menu; returns focus to hamburger |
+
+### Accessibility Rules
+
+- `<nav>` MUST have `aria-label="Primary"` — multiple `<nav>` landmarks on a page must all be distinctly labelled
+- Skip-to-main link MUST be the first focusable element on the page — keyboard users need to bypass repetitive nav
+- Active nav item MUST use `aria-current="page"` — color alone is insufficient for AT users
+- Hamburger button MUST have `aria-expanded` and `aria-controls` — AT users need to know the nav state
+- `role="banner"` MUST appear only once per page (one `<header>` at page level)
+
+Cross-link: `reference/accessibility.md` — landmark regions, skip navigation
+
+---
+
+## Motion
+
+| Transition | Duration | Easing | Notes |
+|------------|----------|--------|-------|
+| Scroll shadow appear | 150ms | ease-out | `box-shadow` opacity only |
+| Mobile menu open | 200ms | ease-out | Height expand or slide-down |
+| Mobile menu close | 150ms | ease-in | Collapse |
+| Transparent → opaque on scroll | 200ms | ease-out | Background-color transition |
+
+**BAN**: Animating navbar height on scroll — causes layout reflow and jank on every scroll event.
+
+Cross-link: `reference/motion.md` — layout-affecting transitions
+
+---
+
+## Do / Don't
+
+### Do
+- Include a visible skip-to-main link as the first focusable element *(WCAG 2.4.1, Carbon, Polaris)*
+- Label `<nav>` with `aria-label="Primary"` *(WAI-ARIA APG landmark regions)*
+- Use `aria-current="page"` on the active nav item *(WAI-ARIA, Atlassian)*
+- Manage z-index explicitly on sticky navbars to prevent overlap issues *(Material 3, Carbon)*
+
+### Don't
+- Don't use multiple unlabelled `<nav>` landmarks — screen reader users can't distinguish them *(WCAG 4.1.2)*
+- Don't rely on color alone to indicate the active nav item *(WCAG 1.4.1)*
+- Don't put more than 7 primary nav items — overwhelming and hard to scan *(Carbon, Polaris HIG)*
+- Don't use `position: fixed` on mobile without accounting for virtual keyboard displacement
+
+---
+
+## Anti-patterns Cross-links
+
+| Anti-pattern | Entry |
+|--------------|-------|
+| BAN-04 | `transition: all` on interactive elements — `reference/anti-patterns.md#ban-04` |
+
+---
+
+## Benchmark Citations
+
+| Claim | Sources |
+|-------|---------|
+| role="banner" on outer header | WAI-ARIA APG landmark regions |
+| aria-label="Primary" required on nav | WAI-ARIA APG, WCAG 4.1.2 |
+| Skip-to-main as first focusable element | WCAG 2.4.1, Carbon, Polaris |
+| aria-current="page" on active item | WAI-ARIA APG, Atlassian, Primer |
+| 56px default navbar height | Material 3, Carbon, Polaris, Atlassian |
+
+Full system URLs: `connections/design-corpora.md`
+
+---
+
+## Grep Signatures
+
+```bash
+# nav element missing aria-label
+grep -rn '<nav' src/ | grep -v 'aria-label\|aria-labelledby'
+
+# Active nav item missing aria-current
+grep -rn 'active\|current\|selected' src/ | grep -i 'nav.*item\|navitem\|nav-link' | grep -v 'aria-current'
+
+# Missing skip link
+grep -rn 'skip.*main\|skip.*content\|skipnav' src/ | grep -v 'href'
+# If the above returns nothing, no skip link exists
+grep -rn 'id="main\|id="main-content"' src/ | head -5
+
+# Multiple unlabelled nav landmarks
+grep -rn '<nav' src/ | grep -v 'aria-label\|aria-labelledby'
+```
+
+---
+
+## Failing Example
+
+```html
+<!-- BAD: multiple <nav> elements without aria-label -->
+<header>
+  <nav>
+    <a href="/">Home</a>
+    <a href="/about">About</a>
+    <a href="/contact" class="active">Contact</a>  <!-- no aria-current -->
+  </nav>
+</header>
+<aside>
+  <nav>  <!-- second nav, also unlabelled — ambiguous for AT users -->
+    <a href="/settings">Settings</a>
+  </nav>
+</aside>
+```
+
+**Why it fails**: Screen readers announce "navigation" twice with no way to distinguish them; active state relies on CSS class only (not `aria-current="page"`); no skip link; `<header>` lacks landmark context.
+**Grep detection**: `grep -rn '<nav' src/ | grep -v 'aria-label'`
+**Fix**: Add `aria-label="Primary"` and `aria-label="Secondary"` to each `<nav>`; add `aria-current="page"` to active link; add skip link as first child of `<header>`.

package/reference/components/pagination.md

@@ -0,0 +1,205 @@
+# Pagination — Benchmark Spec
+
+**Harvested from**: Carbon, Polaris, Atlassian, Mantine, Material 3, UUPM (app-interface, MIT)
+**Wave**: 4 · **Category**: Navigation
+
+---
+
+## Purpose
+
+Pagination divides a large dataset into discrete pages and provides controls to navigate between them. It is the preferred pattern for server-rendered or API-paginated datasets where loading all items at once is impractical. Use infinite scroll for feeds/social content; use pagination for tables, search results, and list views where users need to reference or return to a specific page. *(Carbon, Polaris, Atlassian, Mantine all define pagination as discrete page-set navigation)*
+
+---
+
+## Anatomy
+
+```
+<nav aria-label="Pagination">
+  [‹ Previous]  [1]  [2]  [•3•]  [4]  [...]  [24]  [Next ›]
+                                   ↑ aria-current="page"
+  Items per page: [25 ▾]   Showing 51–75 of 587 items
+</nav>
+```
+
+| Part | Required | Notes |
+|------|----------|-------|
+| `<nav>` container | Yes | `aria-label="Pagination"` |
+| Previous button | Yes | `aria-label="Previous page"`; `disabled` on page 1 |
+| Next button | Yes | `aria-label="Next page"`; `disabled` on last page |
+| Page number buttons | Yes | Each button `aria-label="Page N"` |
+| Current page indicator | Yes | `aria-current="page"` on active page button |
+| Ellipsis | Conditional | At > 7 pages; `aria-hidden="true"` or `aria-label="More pages"` |
+| Per-page selector | No | `<select>` with visible `<label>`; options: 10/25/50/100 |
+| Results summary | No | "Showing 51–75 of 587 items"; `aria-live="polite"` on change |
+
+---
+
+## Variants
+
+| Variant | Description | Systems |
+|---------|-------------|---------|
+| Full | Previous + page numbers + Next | Carbon, Polaris, Atlassian, Mantine |
+| Compact | Previous + "Page N of M" label + Next (no individual page buttons) | Carbon, Material 3 |
+| Simple | Previous / Next only (no page numbers) | Polaris, Atlassian mobile |
+| With per-page | Adds items-per-page selector below or beside | Carbon, Polaris, UUPM list-view (MIT) |
+| Borderless | Text-only Previous/Next; no page number buttons | Mantine |
+
+**Norm** (≥4 systems agree): show 5–7 page buttons max when not truncating; always show first, last, ±1 around current when truncating.
+**Diverge**: Carbon combines per-page selector and result count into the pagination bar; Polaris separates them.
+
+---
+
+## States
+
+| State | Trigger | Visual | ARIA |
+|-------|---------|--------|------|
+| default | — | All buttons enabled except current page | — |
+| current-page | — | Filled/highlighted button | `aria-current="page"` |
+| prev-disabled | page = 1 | Previous button dimmed | `disabled` or `aria-disabled="true"` |
+| next-disabled | page = last | Next button dimmed | `disabled` or `aria-disabled="true"` |
+| button-hover | pointer over | 8% overlay | — |
+| button-focus | keyboard focus | 2px focus-visible ring | — |
+| loading | page change in flight | Spinner overlay on content; buttons retain focus | `aria-busy="true"` on results region |
+
+---
+
+## Sizing & Spacing
+
+| Element | Size | Notes |
+|---------|------|-------|
+| Page button | 36×36px (md) | 32×32px compact; min tap target 44px via padding |
+| Prev/Next button | 36px height × auto | Label text + chevron icon |
+| Button gap | 4px | Between adjacent page buttons |
+| Per-page select | 80px width | 4 options: 10/25/50/100 |
+| Container padding | 16px V | Breathing room above/below |
+
+**Norm**: 36px button height (Carbon, Atlassian, Mantine). 4px gap between buttons.
+
+---
+
+## Typography
+
+- Page number buttons: body-sm (13–14px), weight 400; active page weight 600
+- Previous/Next labels: body-sm, weight 400
+- Results summary: body-sm, `color: --text-subtle`
+- Per-page label: label-sm (12px), always visible above or beside the select
+
+Cross-link: `reference/typography.md` — body-sm, label scale
+
+---
+
+## Keyboard & Accessibility
+
+> **WAI-ARIA role**: `navigation` (container)
+> **Required attributes**: `aria-label="Pagination"` on `<nav>`; `aria-current="page"` on active page button; `aria-label="Previous page"` / `"Next page"` on controls; `aria-label="Page N"` on each numbered button
+
+### Keyboard Contract
+
+*Quoted verbatim from WAI-ARIA APG — https://www.w3.org/WAI/ARIA/apg/patterns/landmark-regions/ — W3C — 2024*
+
+| Key | Action |
+|-----|--------|
+| Tab | Moves focus to next button in pagination |
+| Shift+Tab | Moves focus to previous button |
+| Enter / Space | Activates focused button (navigates to page or changes per-page count) |
+
+### Accessibility Rules
+
+- `aria-label="Pagination"` MUST be on the `<nav>` — distinguishes from other navigation landmarks on the page
+- `aria-current="page"` MUST be on the currently active page button — screen readers announce "Page 3, current"
+- Previous button on page 1 and Next button on last page MUST use `disabled` or `aria-disabled="true"` + visually dimmed
+- `aria-label` on each page number button ("Page 1", "Page 2") prevents screen readers from just announcing the number alone
+- Results summary text MUST use `aria-live="polite"` so screen reader users hear the count update after page change
+- Per-page `<select>` MUST have a visible `<label>` — not just a placeholder
+
+Cross-link: `reference/accessibility.md` — aria-current, landmark labelling, live regions
+
+---
+
+## Motion
+
+| Transition | Duration | Easing | Notes |
+|------------|----------|--------|-------|
+| Button hover | 80ms | ease-out | Background color only |
+| Page change content transition | 150ms | ease-out | Fade the results region; managed by page, not pagination |
+| Ellipsis expand (if interactive) | 120ms | ease-out | Reveal hidden page buttons |
+
+**BAN**: Do not animate the pagination bar itself when a page changes — only the content region transitions.
+
+Cross-link: `reference/motion.md` — content region transitions
+
+---
+
+## Do / Don't
+
+### Do
+- Label the `<nav>` with `aria-label="Pagination"` *(WAI-ARIA APG, Carbon, Polaris)*
+- Use `aria-current="page"` on the active page button *(WAI-ARIA APG)*
+- Provide visible per-page selector with a visible label *(Carbon, Polaris, Atlassian)*
+- Show a results summary ("Showing 51–75 of 587") near the pagination controls *(Carbon, Polaris)*
+
+### Don't
+- Don't use `<a href>` with pushState without `aria-current` — screen readers won't know which page is current *(WAI-ARIA)*
+- Don't show more than 7 page buttons without ellipsis truncation — visually overwhelming *(Carbon, Mantine)*
+- Don't disable the Previous/Next buttons with only visual styling — use `disabled` attr or `aria-disabled` *(WCAG 1.4.3)*
+- Don't place pagination at the top only — bottom placement is expected; both positions is acceptable *(Polaris, Carbon)*
+
+---
+
+## 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="Pagination" on nav container | WAI-ARIA APG, Carbon, Polaris |
+| aria-current="page" on active page button | WAI-ARIA APG, Atlassian, Mantine |
+| Ellipsis pattern: first + last + ±1 around current | Carbon, Polaris, Atlassian, Mantine |
+| Per-page selector requires visible label | WCAG 1.3.1, Carbon, Polaris |
+| aria-live="polite" on results summary | WCAG 4.1.3, Carbon |
+
+Full system URLs: `connections/design-corpora.md`
+
+---
+
+## Grep Signatures
+
+```bash
+# Pagination nav missing aria-label
+grep -rn 'pagination\|pager' src/ | grep '<nav' | grep -v 'aria-label'
+
+# Active page button missing aria-current
+grep -rn 'pagination\|pager' src/ | grep 'active\|current\|selected' | grep -v 'aria-current'
+
+# Page buttons using <a> without aria-current
+grep -rn '<a' src/ | grep -i 'page.*[0-9]\|pager' | grep -v 'aria-current'
+
+# Per-page select missing label
+grep -rn 'per.page\|items-per-page\|pageSize' src/ | grep '<select' | grep -v '<label\|aria-label'
+```
+
+---
+
+## Failing Example
+
+```html
+<!-- BAD: page buttons using <a href> with pushState but no aria-current -->
+<nav>  <!-- missing aria-label="Pagination" -->
+  <a href="?page=2" class="prev">Previous</a>  <!-- no aria-label -->
+  <a href="?page=1">1</a>
+  <a href="?page=2">2</a>
+  <a href="?page=3" class="active">3</a>  <!-- class active but no aria-current -->
+  <a href="?page=4">4</a>
+  <a href="?page=4" class="next">Next</a>  <!-- no aria-label -->
+</nav>
+```
+
+**Why it fails**: No `aria-label` on `<nav>`; active page has CSS class but no `aria-current="page"` so AT announces "3" not "Page 3, current"; Previous/Next have no descriptive labels; no `aria-label="Page N"` on individual page links.
+**Grep detection**: `grep -rn 'pagination' src/ | grep -v 'aria-current\|aria-label'`
+**Fix**: Add `aria-label="Pagination"` to `<nav>`; add `aria-current="page"` to the active page button; add `aria-label="Previous page"` and `aria-label="Next page"`; add `aria-label="Page N"` to each numbered button.

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