whale-igniter 1.3.0 → 1.3.2

package/ui-references/forms.md

@@ -0,0 +1,192 @@
+# Forms — UI References
+
+Form elements are the primary way users take action in an application. Poor form components are the leading cause of accessibility failures and the most common source of user frustration. Every form element must work without a mouse, communicate its state clearly, and never lose the user's input silently.
+
+---
+
+## Button
+
+The most-pressed element in any UI. A button communicates that something will happen immediately when activated. It is not a link (links navigate). It is not a div with an onClick.
+
+### Reference implementations
+
+- **[shadcn/ui Button](https://ui.shadcn.com/docs/components/button)** — clean variant system (default, destructive, outline, ghost, link), loading state pattern with spinner-in-place, correct use of `asChild` for polymorphic rendering without breaking semantics.
+- **[Radix UI Button primitive](https://www.radix-ui.com/themes/docs/components/button)** — shows how to handle the icon variant with `gap` and `size` scaling; the size scale is worth copying verbatim.
+- **[Vercel/Geist Button](https://vercel.com/geist/button)** — minimal, high-contrast, used in production at scale; the loading spinner that replaces label text (not appended to it) is the right pattern.
+- **[Linear buttons](https://linear.app)** — observe in the app: focus-visible rings that match brand accent, 36px height control, icon-only buttons with tooltip, destructive confirmation pattern.
+
+### Minimum quality bar
+
+- [ ] Default, hover, focus-visible, active, disabled states are all visually distinct
+- [ ] Loading state: spinner replaces or overlays label; button is `disabled` during load
+- [ ] With-icon variant: icon + label with consistent gap (4–6px); icon-only variant with tooltip
+- [ ] Destructive variant: red/danger color, distinct from default primary
+- [ ] Touch target minimum 44×44px on mobile (use padding, not just height)
+- [ ] `type="button"` is explicit; never rely on browser default type in a form context
+- [ ] Keyboard: Enter and Space both activate; Tab reaches the button
+- [ ] Disabled state uses the `disabled` attribute, not just visual styling
+
+### Common mistakes
+
+- Using `<div>` or `<a>` for buttons that trigger actions — breaks keyboard and screen reader access
+- Removing the focus ring with `outline: none` without a replacement — kills keyboard navigation
+- Disabling buttons without explaining why — trap users who don't understand the state
+- Using color alone to distinguish destructive from default — fails color-blind users
+
+---
+
+## Input
+
+A single-line text field. The workhorse of data entry. Quality inputs reduce errors by making their state unambiguous at a glance.
+
+### Reference implementations
+
+- **[shadcn/ui Input](https://ui.shadcn.com/docs/components/input)** — clean baseline with label separation, consistent height, and error state color; pairs well with the Form component for validation messaging.
+- **[Radix UI Form](https://www.radix-ui.com/primitives/docs/components/form)** — the best reference for the full label + input + error message pattern with accessible ARIA wiring.
+- **[Vercel/Geist Input](https://vercel.com/geist/input)** — prefix/suffix slot pattern (icon or text before/after the field) handled without hacks.
+- **[Polaris TextField](https://polaris.shopify.com/components/selection-and-input/text-field)** — character count, multiline behavior, inline error, and help text all handled consistently.
+
+### Minimum quality bar
+
+- [ ] Label is a real `<label>` with `for` pointing to the input's `id` — not a placeholder
+- [ ] Placeholder text is supplementary, not a label replacement; it disappears on type
+- [ ] Error state: red border + error message below the field (not inside it); `aria-describedby` links them
+- [ ] Disabled state: grayed, non-interactive; communicates not the same as read-only
+- [ ] Read-only state: selectable text, different visual treatment from disabled
+- [ ] Focus state: visible ring on `focus-visible`, not on `focus` (avoids focus ring on click)
+- [ ] Prefix/suffix slots for icons or units (e.g. "$", "px") without breaking layout
+- [ ] Mobile: correct `inputmode` and `type` attributes to trigger the right keyboard
+
+### Common mistakes
+
+- Using placeholder as label — fails when the field has a value; inaccessible to screen readers
+- `outline: none` on focus without replacement — invisible focus indicator
+- Showing error messages before the user has interacted — don't validate on mount
+- Input width set to 100% everywhere — inputs should have a width appropriate to their expected content
+
+---
+
+## Select
+
+A dropdown for choosing one option from a set. Native `<select>` is accessible but unstyled; custom selects require careful ARIA construction to match native behavior.
+
+### Reference implementations
+
+- **[Radix UI Select](https://www.radix-ui.com/primitives/docs/components/select)** — the canonical reference for building an accessible custom select: `combobox` role, `listbox` for options, arrow key navigation, type-to-filter. Copy the ARIA pattern, not just the visuals.
+- **[shadcn/ui Select](https://ui.shadcn.com/docs/components/select)** — Radix Select with Tailwind styling; the search-within-select is in Combobox (different component).
+- **[Headless UI Listbox](https://headlessui.com/react/listbox)** — alternative implementation with slightly different API; good for comparing two approaches to the same problem.
+
+### Minimum quality bar
+
+- [ ] Keyboard: Up/Down arrows navigate options; Enter/Space selects; Escape closes; Home/End jump to first/last
+- [ ] When closed, shows selected value (not placeholder unless nothing is selected)
+- [ ] Supports option groups (`optgroup` semantics in custom select)
+- [ ] Long option lists: the dropdown scrolls; first visible option after typing matches
+- [ ] Touch: tap opens overlay positioned relative to viewport, not overflowing
+- [ ] `aria-required` and `aria-invalid` passed through when applicable
+
+### Common mistakes
+
+- Building a custom select with `<div>` and `onClick` only — breaks keyboard and screen reader
+- Opening the dropdown on hover — wrong interaction model; selects open on click/keypress
+- Closing the dropdown on scroll of the parent page — confuses users mid-selection
+
+---
+
+## Checkbox
+
+A toggle for boolean state or for selecting items from a list. Use checkbox (not radio) when multiple selections are valid.
+
+### Reference implementations
+
+- **[Radix UI Checkbox](https://www.radix-ui.com/primitives/docs/components/checkbox)** — correct ARIA role, indeterminate state exposed as `data-state="indeterminate"`, animated check mark with CSS transition.
+- **[shadcn/ui Checkbox](https://ui.shadcn.com/docs/components/checkbox)** — minimal, paired with label using the `FormControl` + `FormLabel` pattern worth copying.
+- **[Headless UI Checkbox](https://headlessui.com/react/checkbox)** — headless approach showing all the keyboard event handling necessary.
+
+### Minimum quality bar
+
+- [ ] Three states: unchecked, checked, indeterminate (for select-all patterns)
+- [ ] Label is clickable and associated with `<label>` or `aria-label`
+- [ ] Focus ring visible on keyboard focus; not on click
+- [ ] Space bar toggles in all browsers
+- [ ] In a group: each checkbox is independently labeled
+- [ ] Indeterminate state is set via JS (not HTML attribute) and communicated via `aria-checked="mixed"`
+
+### Common mistakes
+
+- Using indeterminate as a third state (it is not — it means "some children are checked")
+- Making the hit area the checkbox icon only — label must be part of the hit area
+
+---
+
+## Radio
+
+A single-selection control. When the user must choose exactly one option from a visible, bounded list. Use a Select for long lists (7+ options).
+
+### Reference implementations
+
+- **[Radix UI Radio Group](https://www.radix-ui.com/primitives/docs/components/radio-group)** — `role="radiogroup"` on the container, `role="radio"` on each item, arrow key navigation between options in the group (not Tab).
+- **[shadcn/ui Radio Group](https://ui.shadcn.com/docs/components/radio-group)** — clean implementation with `RadioGroupItem` + `Label` pairing.
+
+### Minimum quality bar
+
+- [ ] Arrow keys navigate within the group; Tab moves past the group to the next focusable element
+- [ ] Only one radio in the group receives Tab focus at a time (roving tabindex)
+- [ ] All radios share the same `name` attribute (native) or group context
+- [ ] Pre-selected option: one option should have a default unless the absence of a choice is meaningful
+- [ ] Label is always to the right of the radio circle (left-to-right layouts)
+
+### Common mistakes
+
+- Replacing a radio group with separate checkboxes — removes the mutually-exclusive semantic
+- Making all radios Tab-focusable independently — breaks keyboard navigation model
+
+---
+
+## Toggle / Switch
+
+A binary control that takes effect immediately, without a submit action. Distinct from a checkbox: checkboxes submit a form, toggles apply instantly.
+
+### Reference implementations
+
+- **[Radix UI Switch](https://www.radix-ui.com/primitives/docs/components/switch)** — `role="switch"`, `aria-checked` updates immediately, smooth sliding animation that communicates the state transition.
+- **[shadcn/ui Switch](https://ui.shadcn.com/docs/components/switch)** — good example of label-on-right with description below.
+- **[Headless UI Switch](https://headlessui.com/react/switch)** — headless; useful for understanding what keyboard events need handling.
+
+### Minimum quality bar
+
+- [ ] `role="switch"` with `aria-checked`
+- [ ] Space and Enter both toggle
+- [ ] Visual change is animated (helps users understand the state change happened)
+- [ ] Label clearly names what is being toggled (not just "On/Off")
+- [ ] State change triggers immediately — no submit required
+- [ ] Disabled state with explanation (tooltip or nearby text) when toggle is locked
+
+### Common mistakes
+
+- Using a checkbox styled as a toggle — breaks ARIA semantics; `role="switch"` is different
+- Toggle that requires a Save button — breaks the convention; if it needs confirmation, use a modal
+
+---
+
+## Textarea
+
+Multi-line text input. Same principles as Input but with a resizing dimension to manage.
+
+### Reference implementations
+
+- **[shadcn/ui Textarea](https://ui.shadcn.com/docs/components/textarea)** — `resize-y` allowed, correct row default, auto-grow variant.
+- **[Polaris TextField (multiline)](https://polaris.shopify.com/components/selection-and-input/text-field)** — character count below the field with warning at 80% capacity.
+
+### Minimum quality bar
+
+- [ ] User can resize vertically (allow `resize-y`); horizontal resize is usually disruptive
+- [ ] `rows` attribute sets a sensible default height (not 2 — at least 4)
+- [ ] Character count visible when there is a limit
+- [ ] Same error, disabled, read-only, focus states as Input
+- [ ] Auto-growing textarea (optional but high quality): height expands with content up to a max
+
+### Common mistakes
+
+- Preventing all resize — users have different viewport and font sizes
+- Setting `height: auto` without `min-height` — collapses to zero on empty value

package/ui-references/layout.md

@@ -0,0 +1,155 @@
+# Layout — UI References
+
+Layout components and patterns define how content is positioned, sized, and reflowed across viewports. They are the invisible scaffolding of every screen. Good layout is invisible — content feels natural and reachable. Bad layout manifests as content that overflows on mobile, pages that don't scale, or sidebar panels that get in the way.
+
+---
+
+## Container
+
+A centered, width-constrained wrapper that gives content a comfortable reading width and consistent horizontal margins. The outermost structural element on most pages.
+
+### Reference implementations
+
+- **[Vercel/Geist Container](https://vercel.com/geist/container)** — `max-width` variants (sm, md, lg, xl), centered with `margin: 0 auto`, horizontal padding that scales with viewport width. The pattern to copy for most web apps.
+- **[Tailwind CSS Container](https://tailwindcss.com/docs/container)** — `container` class with `mx-auto` and responsive padding; a widely-used baseline.
+
+### Minimum quality bar
+
+- [ ] Maximum width is appropriate for the content type (prose: 65–75ch; app UI: 1280px)
+- [ ] Horizontal padding on both sides that scales with viewport — at minimum 16px on mobile, 24–32px on desktop
+- [ ] Centers with `margin: 0 auto` — never with absolute positioning
+- [ ] Does not constrain child elements from filling their parent width
+- [ ] Nested containers: inner containers should not re-apply the outer max-width
+
+### Common mistakes
+
+- Using 100vw for the container width — includes scrollbar width and causes horizontal overflow on Windows
+- Container with no horizontal padding on mobile — content touches viewport edges
+- Nesting full-width sections inside a container that then applies max-width to everything
+
+---
+
+## Stack
+
+A one-dimensional layout that distributes children along a single axis (vertical or horizontal) with consistent spacing. The most frequent layout primitive.
+
+### Reference implementations
+
+- **[Every Layout — Stack](https://every-layout.dev/layouts/stack/)** — the canonical primitive: each child separated by a consistent gap, no global margin reset needed.
+- **[Radix UI Flex](https://www.radix-ui.com/themes/docs/layout/flex)** — flex-based stack with `gap`, `direction`, `align`, `justify` props; useful as a design system primitive.
+- **[Tailwind's flex/gap utilities](https://tailwindcss.com/docs/display#flex)** — `flex flex-col gap-4` is the practical implementation of a vertical stack in Tailwind.
+
+### Minimum quality bar
+
+- [ ] Spacing between children uses `gap`, not margin on individual children — `gap` does not collapse and doesn't affect the outermost children
+- [ ] Direction is explicit: vertical stack uses `flex-col`; horizontal uses `flex-row`
+- [ ] Wrapping behavior is explicit: decide whether children wrap to the next row or clip
+- [ ] Alignment: cross-axis alignment (`align-items`) defaults to `stretch` — be intentional about changing it
+- [ ] Nested stacks use their own `gap` — do not inherit from a parent
+
+### Common mistakes
+
+- Using margin-bottom on children for spacing — breaks the last-child, creates double margins when nesting
+- Gap on a non-flex/non-grid element — `gap` only works on flex and grid containers
+- Using negative margin to "fix" unwanted spacing from margins — indicates a structural problem, not a spacing one
+
+---
+
+## Grid
+
+A two-dimensional layout for aligning content in rows and columns. Use for card grids, form field layouts, and any content that requires both row and column alignment.
+
+### Reference implementations
+
+- **[Every Layout — Grid](https://every-layout.dev/layouts/grid/)** — the auto-fill/minmax pattern for responsive grids that reflow without breakpoints; the right default for card grids.
+- **[CSS Grid by Example](https://gridbyexample.com/)** — Rachel Andrew's reference; authoritative for advanced grid patterns.
+- **[Radix UI Grid](https://www.radix-ui.com/themes/docs/layout/grid)** — a grid primitive with explicit `columns` prop for column count control.
+
+### Minimum quality bar
+
+- [ ] Responsive: use `auto-fill` or `auto-fit` with `minmax()` for self-reflowing grids; explicit breakpoints for controlled column counts
+- [ ] Gutters use `gap`, not margin — ensures equal spacing horizontally and vertically
+- [ ] Items in the same row are the same height by default (CSS Grid stretches to match the tallest item)
+- [ ] Named grid areas for complex layouts: makes the layout intent readable in code
+
+### Common mistakes
+
+- Using `float` or `inline-block` for grid layouts — no longer appropriate; use Grid or Flexbox
+- Fixed-width columns that don't reflow — always pair fixed-width grids with `overflow-x: auto` or responsive breakpoints
+- `auto-fit` vs `auto-fill` confusion: `auto-fit` collapses empty tracks (items stretch); `auto-fill` preserves empty column tracks
+
+---
+
+## Responsive Patterns
+
+Strategies for adapting layout to different viewport widths. Not a component, but a set of decisions that every component must make.
+
+### Reference implementations
+
+- **[Every Layout](https://every-layout.dev/)** — the complete reference for responsive layout primitives (Stack, Box, Center, Cluster, Sidebar, Switcher, Cover, Grid, Frame, Reel, Imposter, Icon). These patterns cover 95% of layout needs without breakpoints.
+- **[Tailwind responsive prefixes](https://tailwindcss.com/docs/responsive-design)** — `sm:`, `md:`, `lg:`, `xl:` breakpoints for when intrinsic layouts are insufficient.
+
+### Minimum quality bar
+
+- [ ] Mobile-first: default styles are for small viewports; larger-viewport styles override with `@media (min-width: ...)`
+- [ ] No horizontal scroll on any viewport wider than 320px
+- [ ] Touch targets minimum 44×44px on all interactive elements
+- [ ] Text never smaller than 16px on mobile (prevents browser auto-zoom on iOS)
+- [ ] Images and media use `max-width: 100%` and `height: auto` — never overflow their container
+- [ ] Test at: 320px (smallest iPhone SE), 390px (iPhone 14), 768px (tablet), 1440px (desktop)
+
+### Common mistakes
+
+- Desktop-first design that patches mobile with `max-width` overrides — creates specificity battles
+- Layout that assumes a specific viewport height — mobile browsers have variable chrome heights
+- `vw` units for font size — creates tiny text on narrow viewports and huge text on wide ones; use `clamp()` for fluid typography
+
+---
+
+## Sidebar Layout
+
+A two-column layout with a persistent sidebar (navigation or contextual content) and a main content area. The most common structure for application dashboards.
+
+### Reference implementations
+
+- **[shadcn/ui Sidebar](https://ui.shadcn.com/docs/components/sidebar)** — comprehensive implementation: collapsible, icon-only mode, mobile sheet overlay, keyboard navigation, persistent open/closed state.
+- **[Linear's layout](https://linear.app)** — observe: resizable sidebar, persistent state across reloads, collapses to icon-only at narrower widths, slides away on mobile.
+- **[Radix UI layout primitives](https://www.radix-ui.com/themes/docs/layout/box)** — Box and Flex for building custom sidebar layouts.
+
+### Minimum quality bar
+
+- [ ] Sidebar width is either fixed or resizable within a min/max range
+- [ ] Sidebar open/closed state persists across navigation (local storage or cookie)
+- [ ] Mobile: sidebar slides off-screen; toggle button always visible; opens as overlay, not by pushing content
+- [ ] Main content area uses `min-width: 0` to allow flex children to shrink below content size
+- [ ] Keyboard: pressing a sidebar nav item moves focus into the main content area
+- [ ] Skip-to-content link at page top jumps past the sidebar for keyboard users
+
+### Common mistakes
+
+- Sidebar with `overflow: hidden` — clips content and breaks dropdown menus that extend beyond the sidebar
+- Sidebar that pushes content off-screen on resize — use CSS variables for width so transitions stay smooth
+- Mobile sidebar that requires a hard page navigation to close — use an overlay and an `×` button
+
+---
+
+## Cluster / Inline Group
+
+A horizontal group of items that wraps to the next line when the container is too narrow. Common for button groups, tag collections, filter chips, and navigation items.
+
+### Reference implementations
+
+- **[Every Layout — Cluster](https://every-layout.dev/layouts/cluster/)** — `flex-wrap: wrap` with `gap` is the complete pattern; no media queries needed.
+- **[Tailwind flex-wrap](https://tailwindcss.com/docs/flex-wrap)** — `flex flex-wrap gap-2` covers most cluster needs.
+
+### Minimum quality bar
+
+- [ ] `flex-wrap: wrap` so items reflow naturally rather than overflowing
+- [ ] `gap` (not margin) between items so wrapping rows also have vertical spacing
+- [ ] Alignment: `align-items: center` for mixed-height items (icon + text, badges + text)
+- [ ] When items must not wrap: `overflow-x: auto` with `-webkit-overflow-scrolling: touch` for mobile swipe
+
+### Common mistakes
+
+- Cluster with margin-right on children but no margin on the last item — creates right overhang
+- Mixing margin and gap for spacing in the same container — pick one

package/ui-references/navigation.md

@@ -0,0 +1,188 @@
+# Navigation — UI References
+
+Navigation elements help users understand where they are and move confidently through an application. Poor navigation is one of the top reasons users abandon software. Good navigation is invisible: users find what they need without thinking about the mechanism.
+
+---
+
+## Navigation Bar
+
+The persistent top bar that identifies the application and provides access to primary destinations. It must be consistent across all screens and never disappear unexpectedly.
+
+### Reference implementations
+
+- **[Linear's top nav](https://linear.app)** — observe in the app: no wordmark at scale (icon only), workspace switcher, command bar in center, user avatar at far right. Extremely low visual weight — chrome stays out of the way of content.
+- **[Vercel/Geist Header](https://vercel.com/geist/components)** — persistent nav with responsive collapse to hamburger on mobile; good reference for how a complex nav simplifies at small breakpoints.
+- **[GitHub Primer Global Nav](https://primer.style/components/nav-list/react/alpha)** — handles authenticated vs. unauthenticated states, notification badge, and global search without cluttering the bar.
+- **[Atlassian Navigation](https://atlassian.design/components/atlassian-navigation/examples)** — horizontal nav for complex products with overflow handling when items don't fit.
+
+### Minimum quality bar
+
+- [ ] `<nav>` element with `aria-label="Main"` (distinguish from secondary navs on the page)
+- [ ] Current page/section has `aria-current="page"` on its link
+- [ ] Keyboard: all links reachable by Tab; no keyboard traps
+- [ ] Mobile: all destinations accessible (not hidden behind a broken hamburger)
+- [ ] Logo links to home; clicking it from home does not reload the page in a disorienting way
+- [ ] Skip navigation link is the first focusable element on the page
+
+### Common mistakes
+
+- Multiple `<nav role="navigation">` without distinct `aria-label` — screen readers can't distinguish them
+- Hiding the hamburger menu without a visible open state indicator
+- Nav items that look like buttons but navigate — use `<a>`, not `<button>`
+
+---
+
+## Tabs
+
+Tabs switch between views of the same conceptual space. The content area changes; the URL may or may not change depending on whether tabs represent distinct routes.
+
+### Reference implementations
+
+- **[Radix UI Tabs](https://www.radix-ui.com/primitives/docs/components/tabs)** — the correct `tablist`/`tab`/`tabpanel` ARIA pattern. Arrow key navigation within the tab list, Tab to move focus into the panel. This is the keyboard interaction model to copy.
+- **[shadcn/ui Tabs](https://ui.shadcn.com/docs/components/tabs)** — clean Radix implementation showing horizontal and vertical orientations.
+- **[Linear's sidebar tabs](https://linear.app)** — vertical tabs in a sidebar context; icon+label on wider widths, icon-only on narrower widths with tooltip.
+
+### Minimum quality bar
+
+- [ ] `role="tablist"` on container, `role="tab"` on each trigger, `role="tabpanel"` on each panel
+- [ ] `aria-selected="true"` on the active tab, `aria-controls` pointing to its panel
+- [ ] Arrow keys (Left/Right for horizontal, Up/Down for vertical) navigate between tabs
+- [ ] Tab key moves focus into the active panel, not to the next tab
+- [ ] Active tab is visually distinct from inactive — not just a color change (underline or elevated background)
+- [ ] If tabs can have counts or badges, they don't overflow the tab trigger width
+
+### Common mistakes
+
+- Building tabs with buttons and state — without the ARIA roles, screen readers can't identify the pattern
+- Tab key navigating between tabs — breaks the WAI-ARIA tabs keyboard spec
+- Tabs that look like navigation links but don't change the URL — confuse back button behavior
+
+---
+
+## Sidebar Navigation
+
+A persistent vertical list of destinations, usually for primary navigation in dense applications. The sidebar is either always visible (persistent) or toggled (collapsible).
+
+### Reference implementations
+
+- **[Linear's sidebar](https://linear.app)** — collapsible sections with disclosure triangles, drag-to-reorder items, keyboard-accessible, active item highlighted with subtle background. The state of each section persists across sessions.
+- **[shadcn/ui Sidebar](https://ui.shadcn.com/docs/components/sidebar)** — comprehensive implementation with collapsible, icon-only mode, groups, and responsive mobile sheet behavior.
+- **[Radix UI Navigation Menu](https://www.radix-ui.com/primitives/docs/components/navigation-menu)** — for nested navigation with flyout submenus.
+
+### Minimum quality bar
+
+- [ ] `<nav>` element with `aria-label` distinct from any other nav
+- [ ] Active item has `aria-current="page"` and a visual highlight (not just color)
+- [ ] Collapsible sections use `<button>` with `aria-expanded`; the trigger is not the section heading itself
+- [ ] Keyboard: arrow keys navigate the tree; Enter expands/collapses; Escape collapses
+- [ ] Mobile: either always visible (if space allows) or a toggleable sheet/drawer — not a hamburger that hides destinations
+
+### Common mistakes
+
+- Using `<ul>` and `<li>` without navigation semantics — consider `role="navigation"` and `aria-label`
+- Active state using only color — inaccessible; add icon, weight, or background differentiation
+- Sidebar that hides off-screen on mobile but is still Tab-focusable — focus trap for keyboard users
+
+---
+
+## Breadcrumb
+
+Shows the user's location in a hierarchy and lets them jump to any ancestor level. Useful in deeply nested navigation trees; not needed for flat applications.
+
+### Reference implementations
+
+- **[Radix UI Breadcrumbs](https://www.radix-ui.com/themes/docs/components/breadcrumbs)** — correct `<nav aria-label="Breadcrumb">` wrapper with `<ol>` and `aria-current="page"` on the last item.
+- **[GitHub Primer Breadcrumb](https://primer.style/react/storybook/?path=/story/components-breadcrumbs--default)** — good handling of overflow: ellipsis in the middle, not at the start or end.
+
+### Minimum quality bar
+
+- [ ] `<nav aria-label="Breadcrumb">` wrapper around an `<ol>`
+- [ ] Last item has `aria-current="page"` and is not a link (it's the current page)
+- [ ] Separator (/) between items is decorative — `aria-hidden="true"` or CSS-generated
+- [ ] On mobile/constrained width: truncate middle items, always show root and current
+- [ ] Schema.org `BreadcrumbList` structured data for SEO when breadcrumbs appear in public pages
+
+### Common mistakes
+
+- Making the current page item a link — it should not be; it is the current location
+- Separators that are part of the link's tab stop — separators are decorative
+
+---
+
+## Dropdown Menu
+
+A contextual list of actions, exposed from a trigger element. Not a select (select chooses a value); a menu triggers actions.
+
+### Reference implementations
+
+- **[Radix UI Dropdown Menu](https://www.radix-ui.com/primitives/docs/components/dropdown-menu)** — the complete reference: `menu`, `menuitem`, `menuitemcheckbox`, `menuitemradio` roles, keyboard navigation (arrow keys, Home/End, typeahead), sub-menus, separators.
+- **[shadcn/ui Dropdown Menu](https://ui.shadcn.com/docs/components/dropdown-menu)** — clean implementation with icons, keyboard shortcuts displayed inline, destructive item styling.
+- **[Linear's context menus](https://linear.app)** — observe: keyboard shortcuts shown in the menu (⌘D), dividers grouping related actions, destructive actions at the bottom, subtle hover highlight.
+
+### Minimum quality bar
+
+- [ ] `role="menu"` on the list, `role="menuitem"` (or `menuitemcheckbox`/`menuitemradio`) on items
+- [ ] Arrow keys navigate; Enter/Space activates; Escape closes and returns focus to trigger
+- [ ] Typeahead: pressing a letter jumps to first item starting with that letter
+- [ ] Nested submenus open on arrow-right; close on arrow-left or Escape
+- [ ] Destructive items visually distinct (red label); positioned last in the group
+- [ ] Menu closes when user clicks outside or navigates away; focus returns to trigger
+
+### Common mistakes
+
+- Using a dropdown menu for a select — `role="menu"` does not communicate value selection to screen readers
+- Not returning focus to the trigger when the menu closes
+- Sub-menus that open on hover (not arrow key) — inaccessible keyboard pattern
+
+---
+
+## Pagination
+
+Controls for navigating through paged data. Users need to know their current position, total pages (if known), and where to go next.
+
+### Reference implementations
+
+- **[shadcn/ui Pagination](https://ui.shadcn.com/docs/components/pagination)** — previous/next arrows with page number range in between; ellipsis for large ranges.
+- **[GitHub Primer Pagination](https://primer.style/components/pagination)** — handles `aria-label` per page link ("Page 2"), `aria-current="page"` on the active page, previous/next with icon + text.
+
+### Minimum quality bar
+
+- [ ] `<nav aria-label="Pagination">` wrapping the controls
+- [ ] Each page link has a unique, descriptive `aria-label` ("Page 3")
+- [ ] Current page has `aria-current="page"` and is not a link
+- [ ] Previous/Next buttons are disabled (not hidden) on the first/last page; `aria-disabled="true"` and `disabled`
+- [ ] Ellipsis items are not interactive and are `aria-hidden="true"`
+- [ ] Keyboard: Tab reaches each page link; Enter activates
+
+### Common mistakes
+
+- Hiding previous on page 1 and next on last page — users lose spatial context about the range
+- Ellipsis items that are also links — they should not be clickable
+
+---
+
+## Command Palette
+
+A keyboard-first search interface for navigating and acting across the entire application. Found in Linear, VSCode, GitHub, Vercel. The power-user's primary navigation.
+
+### Reference implementations
+
+- **[cmdk](https://cmdk.paco.me/)** — the canonical open-source command palette component; accessible, keyboard-driven, fuzzy search, used by shadcn/ui and Linear.
+- **[Linear's command palette](https://linear.app)** — press `⌘K`; observe: fuzzy search, grouping, keyboard shortcuts shown, recent items at top, no mouse required after open.
+- **[shadcn/ui Command](https://ui.shadcn.com/docs/components/command)** — cmdk with Tailwind styling; includes the modal wrapper pattern.
+
+### Minimum quality bar
+
+- [ ] Opens with `⌘K` (Mac) / `Ctrl+K` (Windows/Linux); closes with Escape
+- [ ] Focus is trapped inside while open; returns to previous element on close
+- [ ] Search input is focused immediately on open
+- [ ] Keyboard: arrow keys navigate items; Enter activates; Tab should also navigate
+- [ ] Items are grouped (e.g. "Navigation", "Actions", "Recent")
+- [ ] Empty state is shown when no matches (not a blank list)
+- [ ] `role="combobox"` on the input, `role="listbox"` on the list, `role="option"` on items
+
+### Common mistakes
+
+- Requiring mouse to open — defeats the purpose of a keyboard-first tool
+- No empty state — users don't know if the search is broken or there are no results
+- Slow filtering — command palettes must filter on every keystroke instantly (<16ms)