@hegemonart/get-design-done 1.16.0 → 1.19.0

package/reference/components/menu.md

@@ -0,0 +1,212 @@
+# Menu (Dropdown / Context Menu) — Benchmark Spec
+
+**Harvested from**: Radix UI, WAI-ARIA APG, Carbon, Atlassian, Material 3, Polaris
+**Wave**: 4 · **Category**: Navigation
+
+---
+
+## Purpose
+
+A menu presents a list of actions or options in a temporary overlay anchored to a trigger element. It differs from a Select/Combobox (which chooses a value) — a menu executes commands or navigates. Use a Dropdown Menu for trigger-button scenarios; use a Context Menu for right-click/long-press on an element. *(Radix DropdownMenu, Carbon OverflowMenu, Atlassian DropdownMenu, WAI-ARIA APG Menu agree: menus are action lists, not value selectors)*
+
+---
+
+## Anatomy
+
+```
+[ Trigger Button ▾ ]
+┌─────────────────────┐
+│  ✓ Menu Item        │  role="menuitemcheckbox"
+│  ── Separator ──    │  role="separator"
+│  › Sub-menu Item    │  role="menuitem" aria-haspopup="menu"
+│    Edit             │  role="menuitem"
+│    Delete           │  role="menuitem"
+└─────────────────────┘
+```
+
+| Part | Required | Notes |
+|------|----------|-------|
+| Trigger | Yes | `<button>` with `aria-haspopup="menu"` + `aria-expanded` |
+| Menu container | Yes | `role="menu"` + `aria-labelledby` pointing to trigger |
+| Menu item | Yes | `role="menuitem"` on each action |
+| Separator | No | `role="separator"` — groups related items |
+| Checkbox item | No | `role="menuitemcheckbox"` + `aria-checked` |
+| Radio item | No | `role="menuitemradio"` + `aria-checked`; group in `role="group"` |
+| Sub-menu trigger | No | `role="menuitem"` + `aria-haspopup="menu"` + `aria-expanded` |
+| Focus indicator | Yes | 2px focus-visible ring on keyboard-active item |
+
+---
+
+## Variants
+
+| Variant | Description | Systems |
+|---------|-------------|---------|
+| Dropdown menu | Opens from a button trigger; anchored below/above | Radix, Carbon, Atlassian, Polaris |
+| Context menu | Opens at pointer position on right-click or long-press | Radix, Material 3, Carbon |
+| Overflow menu | Icon-only trigger (⋯ or ⋮); common in dense UIs | Carbon OverflowMenu, Atlassian |
+| Sub-menu | Cascading child menu opening on ArrowRight | Radix, Atlassian, Carbon |
+| Checkbox/radio menu | Items with persistent checked state | Radix, Carbon, Material 3 |
+
+**Norm** (≥4 systems agree): flat action list with separator groups; avoid > 2 nesting levels.
+**Diverge**: Polaris uses ActionList as a shared primitive for both menus and select options; Carbon splits OverflowMenu from ContextMenu as separate components.
+
+---
+
+## States
+
+| State | Trigger | Visual | ARIA |
+|-------|---------|--------|------|
+| closed | — | Trigger visible; overlay hidden | `aria-expanded="false"` on trigger |
+| open | Click trigger | Overlay visible; first item focused | `aria-expanded="true"` on trigger |
+| item-hover / focus | Arrow keys or pointer | Item highlight (8% overlay) | `tabindex="-1"` managed via roving tabindex |
+| item-disabled | `disabled` prop | 38% opacity, cursor: default | `aria-disabled="true"` on item |
+| checked | Toggle menuitemcheckbox | Checkmark icon visible | `aria-checked="true"` |
+| submenu-open | ArrowRight on parent | Child menu visible | `aria-expanded="true"` on parent item |
+
+---
+
+## Sizing & Spacing
+
+| Element | Value | Notes |
+|---------|-------|-------|
+| Min menu width | 160px | Prevents awkward narrow menus |
+| Max menu width | 320px | Truncate labels with ellipsis beyond |
+| Item height | 36px (md) | 32px compact, 40px comfortable |
+| Item padding H | 12px | Icon if present: 16px left + 8px gap |
+| Separator height | 1px + 4px V margin | Divider line |
+| Icon size | 16px | Left-aligned, consistent with label baseline |
+
+**Norm**: 36px item height (Radix default, Carbon, Atlassian). Min-width 160px prevents single-word menus.
+
+---
+
+## Typography
+
+- Item label: body-sm (13–14px), weight 400 — not bold; action labels read as text, not controls
+- Destructive items: same weight, color token `--color-text-danger`
+- Keyboard shortcut hints: body-xs (11–12px), muted color, right-aligned, `aria-hidden="true"`
+- Truncate item labels with `text-overflow: ellipsis`; never wrap item text
+
+Cross-link: `reference/typography.md` — body-sm scale
+
+---
+
+## Keyboard & Accessibility
+
+> **WAI-ARIA role**: `menu` (container), `menuitem` / `menuitemcheckbox` / `menuitemradio` (items)
+> **Required attributes**: `aria-haspopup="menu"` + `aria-expanded` on trigger; `aria-labelledby` on `role="menu"`
+
+### Keyboard Contract
+
+*Quoted verbatim from WAI-ARIA APG — https://www.w3.org/WAI/ARIA/apg/patterns/menu-button/ — W3C — 2024*
+
+| Key | Action |
+|-----|--------|
+| Enter / Space | Opens menu from trigger; activates focused item |
+| ArrowDown | Moves focus to next item (wraps to first) |
+| ArrowUp | Moves focus to previous item (wraps to last) |
+| Escape | Closes menu; returns focus to trigger |
+| Tab | Closes menu; moves focus to next focusable element (does not cycle through items) |
+| Home | Moves focus to first item |
+| End | Moves focus to last item |
+| A–Z / a–z | Moves focus to next item starting with that character |
+| ArrowRight | Opens sub-menu; moves focus to first item of sub-menu |
+| ArrowLeft | Closes sub-menu; returns focus to parent item |
+
+### Accessibility Rules
+
+- Menu MUST open on click only — never on hover for primary open (hover may preview sub-menus)
+- All items MUST be reachable by keyboard; no mouse-only items
+- Focus returns to the trigger element when the menu closes
+- Keyboard shortcut labels (e.g. "⌘K") are `aria-hidden="true"` — the shortcut must be registered separately
+- `role="separator"` dividers are not focusable
+- Disabled items use `aria-disabled="true"` (keep focusable so AT users know the option exists)
+
+Cross-link: `reference/accessibility.md` — focus management, roving tabindex
+
+---
+
+## Motion
+
+| Transition | Duration | Easing | Notes |
+|------------|----------|--------|-------|
+| Menu enter | 120ms | ease-out | Scale 0.95→1 + opacity 0→1 from anchor point |
+| Menu exit | 80ms | ease-in | Opacity 1→0; skip scale-down for speed |
+| Item highlight | 80ms | ease-out | Background color transition only |
+| Sub-menu enter | 120ms | ease-out | Same as menu enter |
+
+**BAN**: `transition: all` on menu items — triggers layout thrash on width changes.
+
+Cross-link: `reference/motion.md` — overlay entry pattern, BAN-04
+
+---
+
+## Do / Don't
+
+### Do
+- Use `role="menu"` + `role="menuitem"` for all action menus *(WAI-ARIA APG)*
+- Group related items with `role="separator"` — keep groups ≤ 7 items *(Carbon, Atlassian)*
+- Return focus to the trigger on close *(WAI-ARIA APG)*
+- Use `role="menuitemcheckbox"` for persistent toggle states *(Radix, Material 3)*
+
+### Don't
+- Don't open the menu on hover as the primary interaction — keyboard users can't discover hover *(WCAG 1.3.3)*
+- Don't exceed 2 levels of sub-menus — deeply nested menus are cognitively expensive *(Atlassian, Carbon)*
+- Don't put form controls (inputs, sliders) inside a menu — use a Popover instead *(WAI-ARIA APG)*
+- Don't use `<div>` items without `role="menuitem"` — invisible to screen readers *(WAI-ARIA)*
+
+---
+
+## 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="menu" + role="menuitem" contract | WAI-ARIA APG Menu Button pattern |
+| Click-only open (not hover) | WAI-ARIA APG, WCAG 1.3.3, Carbon |
+| ArrowRight/Left for sub-menu navigation | WAI-ARIA APG, Radix DropdownMenu |
+| Focus returns to trigger on close | WAI-ARIA APG, Radix |
+| 36px item height | Radix default, Carbon OverflowMenu, Atlassian |
+
+Full system URLs: `connections/design-corpora.md`
+
+---
+
+## Grep Signatures
+
+```bash
+# Menu container missing role="menu"
+grep -rn 'dropdown\|context-menu\|overflow-menu' src/ | grep -v 'role="menu"'
+
+# Items using <div> without role="menuitem"
+grep -rn '<div' src/ | grep -i 'menu-item\|menuitem\|menu__item' | grep -v 'role='
+
+# Trigger missing aria-haspopup
+grep -rn 'aria-expanded' src/ | grep -i 'menu\|dropdown' | grep -v 'aria-haspopup'
+
+# Missing aria-labelledby on menu container
+grep -rn 'role="menu"' src/ | grep -v 'aria-labelledby\|aria-label'
+```
+
+---
+
+## Failing Example
+
+```html
+<!-- BAD: div list with click handlers but no ARIA roles -->
+<div class="dropdown-menu">
+  <div class="dropdown-item" onclick="handleEdit()">Edit</div>
+  <div class="dropdown-item" onclick="handleDelete()">Delete</div>
+</div>
+```
+
+**Why it fails**: No `role="menu"` or `role="menuitem"` — screen readers cannot announce this as a menu; items are not keyboard-navigable; no arrow-key navigation; trigger lacks `aria-haspopup` and `aria-expanded`.
+**Grep detection**: `grep -rn '<div.*onclick\|<div.*onClick' src/ | grep -i 'menu\|dropdown'`
+**Fix**: Use `<ul role="menu">` with `<li role="menuitem" tabindex="-1">` items, or a headless menu primitive (Radix DropdownMenu, Downshift).

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.