whale-igniter 1.3.0 → 1.3.1

package/dist/version.js

@@ -1 +1 @@
-export const PACKAGE_VERSION = "1.3.0";
+export const PACKAGE_VERSION = "1.3.1";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "whale-igniter",
-  "version": "1.3.0",
+  "version": "1.3.1",
   "description": "CLI-first operational intelligence. Bootstraps and adopts AI-readable project context so agents like Claude Code, Codex and Cursor understand your design system from the first commit. Includes an MCP server, a file watcher, deterministic insights, and an opt-in AI bridge (Selene).",
   "type": "module",
   "main": "./dist/index.js",
@@ -10,6 +10,8 @@
   "files": [
     "dist",
     "brand",
+    "packs",
+    "ui-references",
     "README.md",
     "LICENSE",
     "docs/ROADMAP.md"

package/packs/atlas/instructions.md

@@ -0,0 +1,3 @@
+# Atlas Instructions
+
+Product strategy, decision logs and roadmaps.

package/packs/atlas/manifest.json

@@ -0,0 +1,8 @@
+{
+  "name": "atlas",
+  "version": "0.1.0",
+  "description": "Product strategy, decision logs and roadmaps.",
+  "status": "stub",
+  "requiresAI": false,
+  "auditNote": "No generator or validator commands implemented. Decision logging is handled by whale decision (core), not this pack."
+}

package/packs/atlas/rules.md

@@ -0,0 +1,4 @@
+# Atlas Rules
+
+- Keep workflows local-first.
+- Prefer deterministic checks before AI enhancement.

package/packs/forge/instructions.md

@@ -0,0 +1,3 @@
+# Forge Instructions
+
+Implementation specs, dev contracts and handoff.

package/packs/forge/manifest.json

@@ -0,0 +1,8 @@
+{
+  "name": "forge",
+  "version": "0.1.0",
+  "description": "Implementation specs, dev contracts and handoff.",
+  "status": "stub",
+  "requiresAI": false,
+  "auditNote": "Templates directory exists but no generator commands are wired. Stub only in v1.3."
+}

package/packs/forge/rules.md

@@ -0,0 +1,4 @@
+# Forge Rules
+
+- Keep workflows local-first.
+- Prefer deterministic checks before AI enhancement.

package/packs/lighthouse/instructions.md

@@ -0,0 +1,3 @@
+# Lighthouse Instructions
+
+Accessibility audits, contrast and semantic validation.

package/packs/lighthouse/manifest.json

@@ -0,0 +1,8 @@
+{
+  "name": "lighthouse",
+  "version": "0.1.0",
+  "description": "Accessibility audits, contrast and semantic validation.",
+  "status": "stub",
+  "requiresAI": false,
+  "auditNote": "Validators directory is empty. No runtime rules implemented in v1.3. Roadmapped for v1.4."
+}

package/packs/lighthouse/rules.md

@@ -0,0 +1,4 @@
+# Lighthouse Rules
+
+- Keep workflows local-first.
+- Prefer deterministic checks before AI enhancement.

package/packs/scribe/instructions.md

@@ -0,0 +1,3 @@
+# Scribe Instructions
+
+Generated docs, recipes and READMEs.

package/packs/scribe/manifest.json

@@ -0,0 +1,8 @@
+{
+  "name": "scribe",
+  "version": "0.1.0",
+  "description": "Generated docs, recipes and READMEs.",
+  "status": "stub",
+  "requiresAI": false,
+  "auditNote": "Planned for enrichWithAi flow in whale sync. Not functional in v1.3 — infrastructure only."
+}

package/packs/scribe/rules.md

@@ -0,0 +1,4 @@
+# Scribe Rules
+
+- Keep workflows local-first.
+- Prefer deterministic checks before AI enhancement.

package/packs/selene/instructions.md

@@ -0,0 +1,3 @@
+# Selene Instructions
+
+AI-assisted UX intelligence and refinement memory.

package/packs/selene/manifest.json

@@ -0,0 +1,7 @@
+{
+  "name": "selene",
+  "version": "0.1.0",
+  "description": "AI-assisted UX intelligence and refinement memory.",
+  "status": "starter",
+  "requiresAI": false
+}

package/packs/selene/rules.md

@@ -0,0 +1,4 @@
+# Selene Rules
+
+- Keep workflows local-first.
+- Prefer deterministic checks before AI enhancement.

package/ui-references/INDEX.md

@@ -0,0 +1,51 @@
+# UI References — Index
+
+This library is a curated set of component quality benchmarks drawn from the best production design systems. Consult it when building any UI component: before writing code to understand the quality bar, and when reviewing code to catch common mistakes.
+
+AI agents: read this file first to locate the right category, then read that category file for component-specific guidance.
+
+## Categories
+
+| File | Covers | When to consult |
+|---|---|---|
+| [forms.md](forms.md) | Button, Input, Select, Checkbox, Radio, Toggle, Textarea | Any user input element |
+| [navigation.md](navigation.md) | Nav bar, Tabs, Sidebar, Breadcrumb, Dropdown menu, Pagination, Command palette | Any wayfinding or navigation element |
+| [feedback.md](feedback.md) | Toast, Modal, Alert, Progress, Loading states, Skeleton, Empty state | Any element that communicates system status |
+| [surface.md](surface.md) | Card, Popover, Tooltip, Sheet, Avatar, Separator, Badge | Any container or overlay surface |
+| [layout.md](layout.md) | Container, Stack, Grid, Responsive patterns, Sidebar layout | Any structural layout element |
+| [data-display.md](data-display.md) | Table, List, Code block, Stats, Timeline | Any element that presents data |
+
+## Minimum design system
+
+A project is considered to have a design system when it has all of the following components implemented to the quality bar described in their respective files:
+
+- **Button** — with default, hover, focus-visible, active, disabled, loading states and icon variant
+- **Input** — with label, placeholder, error, disabled states and accessible labeling
+- **Select** — keyboard-navigable, with accessible option list
+- **Checkbox** and **Radio** — with indeterminate state for checkbox
+- **Card** — as a reusable surface with consistent padding and radius
+- **Modal / Dialog** — with focus trap, Escape to close, and accessible title
+- **Toast / Notification** — dismissible, accessible, with distinct severity levels
+
+These seven families are the minimum. Everything else is project-specific.
+
+## How this library is structured
+
+Each category file follows the same format per component:
+
+1. One paragraph on what the component is and why it matters.
+2. **Reference implementations** — two to four links to high-quality real-world implementations with one sentence on what each gets right.
+3. **Minimum quality bar** — a checklist of states and behaviors the component must have to ship.
+4. **Common mistakes** — a short list of patterns to avoid.
+
+## Reference source tiers
+
+When citing implementations, this library prioritizes:
+
+- **Tier 1** (cited frequently): Linear, Vercel/Geist, Radix UI, shadcn/ui, Sonner, Headless UI, Park UI
+- **Tier 2** (cited when category-appropriate): Material Design 3, Apple HIG, Carbon (IBM), Polaris (Shopify), Fluent (Microsoft), Atlassian, GitHub Primer
+- **Tier 3** (cited for niche or emerging needs): Mantine, Ark UI, Origin UI, Animata
+
+## Contributing
+
+To add a component or update a reference link, edit the relevant category file directly. The format per component is fixed — add new components at the end of the file or insert them in frequency order. Do not use AI generation to create entries; references must point to real, stable implementations you have verified.

package/ui-references/data-display.md

@@ -0,0 +1,160 @@
+# Data Display — UI References
+
+Data display components present information that the user reads but does not directly edit. The quality bar is high: data must be scannable, sortable when appropriate, and never overflow or truncate silently. Accessibility concerns shift from interaction to comprehension: screen readers must be able to navigate tables and lists in a meaningful order.
+
+---
+
+## Table
+
+A structured grid of rows and columns. Tables are for relational data where both the row and column identity matter. Do not use tables for layout.
+
+### Reference implementations
+
+- **[shadcn/ui Table](https://ui.shadcn.com/docs/components/table)** — semantic HTML (`<table>`, `<thead>`, `<tbody>`, `<th scope="col">`) with Tailwind styling; the correct baseline.
+- **[Radix UI Table](https://www.radix-ui.com/themes/docs/components/table)** — themed table with built-in row hover, column alignment helpers, and condensed/standard density variants.
+- **[TanStack Table](https://tanstack.com/table/latest)** — the leading headless table library; handles sorting, filtering, pagination, and virtual scrolling for large datasets. Consult for any table with more than a few dozen rows.
+- **[Linear's issue list](https://linear.app)** — observe: not a `<table>` but a virtual list; shows how sorting, filtering, and row selection are handled in a list-as-table pattern common in modern apps.
+
+### Minimum quality bar
+
+- [ ] Semantic HTML: `<table>`, `<thead>`, `<tbody>`, `<tfoot>` (if total row), `<tr>`, `<th>`, `<td>`
+- [ ] Column headers: `<th scope="col">` with a text description; not just icons
+- [ ] Row headers (if applicable): `<th scope="row">` on the first cell of each row
+- [ ] `<caption>` element or `aria-label` on the table describing what it contains
+- [ ] Sortable columns: `aria-sort="ascending"` / `"descending"` / `"none"` on the column header
+- [ ] Horizontal scroll on small viewports: wrap in `overflow-x: auto` container — do not collapse columns silently
+- [ ] Row selection: checkbox in first column; `aria-checked` on the row (or the checkbox); keyboard: Space to toggle row
+- [ ] Sticky header: `position: sticky; top: 0` — works with `overflow-x: auto` using the right scroll container
+- [ ] Empty state: a single full-width `<td colspan="N">` with an empty state component, not a blank table
+
+### Common mistakes
+
+- Using `<div>` grid for tabular data — loses semantic meaning; screen readers cannot navigate by row/column
+- Sortable columns with only visual state and no `aria-sort` — screen reader users can't tell the current sort
+- Truncating cell content silently with `overflow: hidden` — use `text-overflow: ellipsis` and a tooltip for the full value
+- No mobile strategy — either allow horizontal scroll, stack into a card per row, or use a different component for small viewports
+
+---
+
+## List
+
+An ordered or unordered sequence of items. Lists are the most common data structure in UI: navigation items, search results, notifications, file trees. Quality lists are scannable and navigable.
+
+### Reference implementations
+
+- **[Radix UI List](https://www.radix-ui.com/themes/docs/components/data-list)** — key-value data list pattern; good for detail views and settings pages.
+- **[GitHub Primer ActionList](https://primer.style/components/action-list/react/alpha)** — the most complete reference for a list of interactive items (like a menu, but also used for navigation and selection): dividers, header groups, leading/trailing visuals, single/multi-select.
+- **[TanStack Virtual](https://tanstack.com/virtual/latest)** — for lists with >100 items; virtual scrolling renders only visible items.
+
+### Minimum quality bar
+
+- [ ] Semantic HTML: `<ul>` for unordered, `<ol>` for ordered — not `<div>` + `<div>`
+- [ ] Each item is `<li>`; interactive items inside `<li>` use `<a>` or `<button>`, not the `<li>` itself
+- [ ] List roles override when semantics matter: `role="listbox"` + `role="option"` for a selectable list
+- [ ] Keyboard navigation for interactive lists: arrow keys navigate items (roving tabindex or `aria-activedescendant`)
+- [ ] Selected item: `aria-selected="true"` and a visual highlight
+- [ ] Long lists: virtual scrolling or pagination — do not render 1000+ DOM nodes
+- [ ] Grouped lists: each group has a visible heading and `role="group"` with `aria-label` pointing to that heading
+
+### Common mistakes
+
+- `<ul>` with `list-style: none` without `role="list"` — some screen readers strip list semantics when list style is removed (add `role="list"` to restore)
+- Interactive items as `<li>` with `onClick` — the `<li>` is not an interactive role; use `<button>` or `<a>` inside
+
+---
+
+## Code Block
+
+A formatted display of code, command output, or configuration. Must preserve whitespace, be readable at any content length, and allow copying.
+
+### Reference implementations
+
+- **[shadcn/ui](https://ui.shadcn.com)** — observe the code blocks throughout the documentation: copy button in the top-right corner, syntax highlighting, scrollable horizontally, no word wrap.
+- **[Vercel/Geist Code](https://vercel.com/geist/code)** — inline code and block code variants; the inline variant for single-line snippets within prose.
+- **[Shiki](https://shiki.matsu.io/)** — the leading syntax highlighter for static output (no runtime needed); generates semantic token HTML. Use for server-rendered or build-time highlighted code.
+
+### Minimum quality bar
+
+- [ ] `<pre><code>` elements — `<pre>` preserves whitespace; `<code>` signals that the content is code
+- [ ] `tabindex="0"` on `<pre>` so keyboard users can scroll the code block
+- [ ] Horizontal scroll on overflow — never wrap code unless the language is prose-like
+- [ ] Copy button in the top-right corner with visual confirmation ("Copied!")
+- [ ] Language label visible (e.g. "TypeScript", "bash") for multi-snippet docs
+- [ ] Dark mode: code blocks often look better with a dark background in both light and dark themes
+- [ ] `aria-label` on the `<pre>` if the language label is not a `<caption>` equivalent
+
+### Common mistakes
+
+- `white-space: pre-wrap` on code — wraps long lines in a way that breaks indentation context
+- No horizontal scroll (`overflow-x: hidden`) on code blocks — silently truncates code
+- Copy button that disappears after animation — show "Copied!" for at least 1.5 seconds
+
+---
+
+## Stats / Metrics
+
+A display of key numbers or metrics with labels and optional context (trend, change, unit). Common in dashboards, reports, and analytics views.
+
+### Reference implementations
+
+- **[shadcn/ui example: Dashboard](https://ui.shadcn.com/examples/dashboard)** — the stat card pattern: large number, label below, trend indicator (up/down arrow + percentage).
+- **[Vercel/Geist](https://vercel.com/geist/components)** — observe the analytics pages: stat value, label, optional sparkline in the card.
+- **[Polaris KPICard](https://polaris.shopify.com)** — handles trend indicators, unit suffixes, comparison to previous period.
+
+### Minimum quality bar
+
+- [ ] Number has sufficient contrast and type scale — stat values should be the largest text element in the card
+- [ ] Unit is part of the label or the value (`12.4k`, `$1,234`, `94%`), not ambiguous
+- [ ] Trend indicator (if present): arrow + percentage; green/red with a text label ("Up 12%") — never color-only
+- [ ] Large numbers are formatted with locale-appropriate separators (`toLocaleString()` or `Intl.NumberFormat`)
+- [ ] Loading state is a skeleton with the same dimensions as the loaded state
+
+### Common mistakes
+
+- Trend indicator that uses color alone (just a green or red number) — inaccessible; add an up/down arrow or "▲ 12%" text
+- Stats that don't communicate the time period — `$12,400` means nothing without "last 30 days" or similar context
+- Numbers that reflow unpredictably on value change — use `tabular-nums` font feature to prevent layout shift when digits change
+
+---
+
+## Timeline
+
+A chronological sequence of events, displayed as a vertical list with connecting lines and time markers. Used in audit logs, activity feeds, version histories.
+
+### Reference implementations
+
+- **[GitHub's commit history](https://github.com)** — observe: timestamp, author, branch indicator; condensed view with expand; the connecting line between events.
+- **[Linear activity log](https://linear.app)** — observe in issue detail: avatar + action description + relative time; grouped by day; expandable for details.
+- **[Atlassian Activity Streams](https://atlassian.design)** — enterprise-quality timeline with status changes, user attribution, and grouping.
+
+### Minimum quality bar
+
+- [ ] Semantic: use `<ol>` (ordered list) — timeline events are ordered
+- [ ] Each event: timestamp, actor (if applicable), event description
+- [ ] Time shown as relative ("3 minutes ago") with absolute time in a tooltip (`title` attribute or `aria-label`)
+- [ ] Connecting line is decorative (`aria-hidden`); the list semantic conveys the sequence
+- [ ] Long timelines: load more on scroll or paginate — do not render hundreds of events on mount
+- [ ] Events grouped by day: group heading is a visible date, `role="separator"` divider
+
+### Common mistakes
+
+- Connecting line as part of the layout that breaks when the viewport narrows
+- Relative timestamps that never update — "5 minutes ago" should update as the user stays on the page
+- No empty state for timelines with no history — "No activity yet" prevents confusion
+
+---
+
+## Badge / Tag (Data Context)
+
+A small label attached to data items to communicate category, status, or type. See [surface.md](surface.md) for the component itself; this section covers data-display-specific usage patterns.
+
+### Usage patterns in data display
+
+- **Status badges in tables**: align all status badges in the same column; use a fixed-width column so the rest of the row doesn't shift when status changes.
+- **Category tags in lists**: tags that filter the list when clicked become `<button>` elements, not `<span>` — clicking must have a visible effect.
+- **Priority indicators**: if using colored dots or badges for priority (urgent/high/medium/low), always accompany color with a text label or icon — do not rely on color alone.
+
+### Reference implementations
+
+- **[Linear's priority + status labels](https://linear.app)** — observe in issue list: priority dot + label, status as a colored chip with text; keyboard accessible in filter panels.
+- **[GitHub labels](https://github.com)** — colored label with text; filter behavior when clicked in issues list; editable in label management UI.

package/ui-references/feedback.md

@@ -0,0 +1,190 @@
+# Feedback — UI References
+
+Feedback components communicate system status. They answer the user's question "did that work?" They must be timely (not delayed), clear (no ambiguous language), and unobtrusive (not blocking work the user is trying to do). A toast that the user misses, a modal that takes five clicks to dismiss, or an error message with jargon all represent feedback component failures.
+
+---
+
+## Toast / Notification
+
+A brief, auto-dismissing message that confirms an action or communicates a system event. Appears without interrupting the user's current task.
+
+### Reference implementations
+
+- **[Sonner](https://sonner.emilkowal.ski/)** — the current best-in-class toast library: smooth enter/exit animations, stacking with expansion on hover, rich content with actions, correct `role="status"` for non-urgent messages and `role="alert"` for errors. Study the source for the animation and stacking patterns.
+- **[shadcn/ui Toast (Sonner)](https://ui.shadcn.com/docs/components/sonner)** — Sonner integration with the shadcn/ui theming system.
+- **[Radix UI Toast](https://www.radix-ui.com/primitives/docs/components/toast)** — alternative implementation; observe how it handles `swipeDirection` and the viewport positioning.
+- **[Linear's toasts](https://linear.app)** — observe in the app: appear bottom-left, short duration, action button inline, stack without expanding (up to ~3 visible), oldest auto-dismisses when stack is full.
+
+### Minimum quality bar
+
+- [ ] Non-critical toasts: `role="status"`, `aria-live="polite"` — screen reader announces after current speech finishes
+- [ ] Error/warning toasts: `role="alert"`, `aria-live="assertive"` — screen reader announces immediately
+- [ ] Auto-dismiss after 4–6 seconds; longer for messages with actions
+- [ ] Dismiss button always present; hover pauses auto-dismiss timer
+- [ ] Stacking: at most 3–5 toasts visible; oldest dismiss when stack is full
+- [ ] Positioned away from interactive elements (bottom corner, not covering nav)
+- [ ] Keyboard: Tab reaches the toast's action/dismiss button while it is visible
+- [ ] Mobile: full-width at bottom, swipe-to-dismiss gesture
+
+### Common mistakes
+
+- Using `alert` role for success messages — causes screen readers to interrupt unnecessarily
+- Auto-dismissing error messages — errors must persist until acknowledged
+- Toasts covering important page content (especially modals or forms mid-submission)
+- No action button for "undo" actions — missed opportunity to recover from mistakes
+
+---
+
+## Modal / Dialog
+
+A focused overlay that interrupts the user's workflow to demand attention or a decision. Use sparingly: modals block the background and demand immediate resolution.
+
+### Reference implementations
+
+- **[Radix UI Dialog](https://www.radix-ui.com/primitives/docs/components/dialog)** — the reference implementation: focus trap, `role="dialog"`, `aria-modal="true"`, Escape to close, scroll lock on body, correct overlay with `aria-hidden` on background content.
+- **[shadcn/ui Dialog](https://ui.shadcn.com/docs/components/dialog)** — Radix Dialog with Tailwind; includes `DialogHeader`, `DialogTitle` (required), `DialogDescription` (recommended), `DialogFooter` pattern.
+- **[Headless UI Dialog](https://headlessui.com/react/dialog)** — alternative, with the `initialFocus` ref pattern for controlling which element receives focus when the modal opens.
+
+### Minimum quality bar
+
+- [ ] `role="dialog"` and `aria-modal="true"` on the dialog container
+- [ ] `aria-labelledby` pointing to the dialog title; `aria-describedby` pointing to the description
+- [ ] Focus trap: Tab and Shift+Tab cycle only within the modal while open
+- [ ] First focusable element receives focus on open (or explicitly set with `autoFocus`)
+- [ ] Escape closes the modal; clicking the overlay closes it; focus returns to the trigger
+- [ ] Body scroll is locked while modal is open; background content is `aria-hidden="true"`
+- [ ] Destructive modal: the destructive action is not the default focused button
+- [ ] Animation: fade + scale in, fade + scale out; respects `prefers-reduced-motion`
+
+### Common mistakes
+
+- Modal without a visible title — `DialogTitle` is required even if visually hidden; without it screen readers have no context
+- Focus returning to page top (not the trigger) after modal closes
+- Modals that cannot be dismissed without taking an action — always provide a way out
+- Nested modals — almost always a design problem that should be solved differently
+
+---
+
+## Alert / Banner
+
+An inline message that communicates status, warnings, or errors within the page content. Unlike toasts, alerts do not auto-dismiss and are integrated into the layout.
+
+### Reference implementations
+
+- **[shadcn/ui Alert](https://ui.shadcn.com/docs/components/alert)** — clean implementation with icon + title + description pattern; default and destructive variants.
+- **[Radix UI Callout](https://www.radix-ui.com/themes/docs/components/callout)** — four severity levels (info, success, warning, error) with icon and text.
+- **[Polaris Banner](https://polaris.shopify.com/components/feedback-indicators/banner)** — good reference for how to handle actionable alerts (with dismiss, with action button, with expansion for details).
+- **[GitHub Primer Flash](https://primer.style/components/flash/react/alpha)** — persistent alerts with full-width option for page-level messages.
+
+### Minimum quality bar
+
+- [ ] Four severity levels: info, success, warning, error — visually distinct beyond color (icon, border, label)
+- [ ] `role="alert"` only for genuinely urgent messages that need immediate announcement; `role="status"` for success and info
+- [ ] Dismissible alerts have a close button with `aria-label="Dismiss"`
+- [ ] Actionable alerts: action button is secondary style (not primary — the alert should not compete with the page's primary action)
+- [ ] Error alerts that accompany form validation: positioned near (or above) the form, not at page top
+
+### Common mistakes
+
+- `role="alert"` on every informational message — causes constant interruptions for screen reader users
+- Color alone to convey severity — red text, yellow text without icon or label are inaccessible
+- Alerts that appear and disappear too quickly — users miss them or can't read the message
+
+---
+
+## Progress Indicator
+
+Communicates how far along a process is. Two types: determinate (known progress) and indeterminate (working but no ETA).
+
+### Reference implementations
+
+- **[Radix UI Progress](https://www.radix-ui.com/primitives/docs/components/progress)** — `role="progressbar"`, `aria-valuenow`, `aria-valuemin`, `aria-valuemax` correctly implemented; smooth transition on value change.
+- **[shadcn/ui Progress](https://ui.shadcn.com/docs/components/progress)** — clean linear progress bar; the animated indeterminate variant shows the pattern.
+
+### Minimum quality bar
+
+- [ ] Determinate: `role="progressbar"` with `aria-valuenow`, `aria-valuemin="0"`, `aria-valuemax="100"`, `aria-valuetext` for human-readable labels ("Step 2 of 5")
+- [ ] Indeterminate: `aria-valuenow` omitted; CSS animation for visual motion; respects `prefers-reduced-motion` (reduce animation, don't remove it)
+- [ ] Multi-step progress: step labels visible at all steps; completed steps visually distinct from future steps
+- [ ] Color: progress fill must pass 3:1 contrast against the track
+
+### Common mistakes
+
+- Indeterminate progress bar staying for too long — show estimated time after 3+ seconds or switch to a spinner with a status message
+- Progress that jumps backwards (data re-loading or error recovery) — disorienting; hold the last value if you can't go backwards meaningfully
+
+---
+
+## Loading State
+
+Communicates that the system is working. Must be immediate (appear within 100ms of an action) and honest (not appear when there is nothing to load).
+
+### Reference implementations
+
+- **[Vercel/Geist Spinner](https://vercel.com/geist/spinner)** — minimal spinner; used inline and as a page-level overlay; the spinning animation is smooth.
+- **[Radix UI Spinner (Themes)](https://www.radix-ui.com/themes/docs/components/spinner)** — several sizes, accessible.
+- **[Linear loading](https://linear.app)** — observe: spinner appears within 100ms, replaces content (not overlays it in most cases), disappears immediately when content is ready.
+
+### Minimum quality bar
+
+- [ ] Appears within 100ms of triggering the async operation
+- [ ] `role="status"` and `aria-label="Loading"` so screen readers announce it
+- [ ] Replaces or overlays only the content being loaded — not the entire page for partial updates
+- [ ] `prefers-reduced-motion`: reduce animation speed or show a static icon instead of spinning
+- [ ] Spinner disappears immediately when load completes — no artificial minimum duration
+
+### Common mistakes
+
+- Loading overlay covering the full viewport for a small update in one section
+- Minimum loading time ("show spinner for at least 500ms") — adds latency without benefit
+- No loading state at all for operations that take >300ms — users think nothing happened and click again
+
+---
+
+## Skeleton
+
+A placeholder that previews the shape of content while it loads. More useful than a generic spinner for content-heavy layouts.
+
+### Reference implementations
+
+- **[shadcn/ui Skeleton](https://ui.shadcn.com/docs/components/skeleton)** — minimal base implementation: pulse animation, neutral background, matches the shape of the content it replaces.
+- **[Polaris SkeletonPage](https://polaris.shopify.com/components/feedback-indicators/skeleton-page)** — full-page skeleton with SkeletonBodyText, SkeletonDisplayText, SkeletonThumbnail; good reference for compositional approach.
+
+### Minimum quality bar
+
+- [ ] Matches the approximate layout and shape of the real content
+- [ ] Pulse animation (opacity oscillation) is gentler than shimmer (left-to-right gradient) for users with motion sensitivity
+- [ ] `aria-hidden="true"` on skeleton elements — they are decorative; screen readers should not read them
+- [ ] Use `aria-busy="true"` on the container while loading; `aria-busy="false"` when content is ready
+- [ ] Skeleton does not shift layout when content loads — reserve space accurately
+
+### Common mistakes
+
+- Skeleton that looks nothing like the real content — causes layout shift and disorientation when content appears
+- Skeleton persisting after content has loaded — even briefly, confusing to users
+
+---
+
+## Empty State
+
+The state of a view when there is no data to display. One of the most neglected components, and one of the most important for user retention.
+
+### Reference implementations
+
+- **[Linear's empty states](https://linear.app)** — observe in fresh workspace: illustration or icon, clear heading, specific explanation of why it's empty, one actionable next step. Never just "No items found."
+- **[Polaris EmptyState](https://polaris.shopify.com/components/layout-and-structure/empty-state)** — image + heading + description + primary action + (optional) secondary action; the structure to follow.
+- **[GitHub empty states](https://github.com)** — observe in repositories, issues, projects: different copy for "nothing exists yet" vs "nothing matches your filter" — those are two different problems.
+
+### Minimum quality bar
+
+- [ ] Distinct copy for "nothing exists yet" vs "nothing matches current filters" — different user problems
+- [ ] At least one call to action ("Create your first X", "Clear filters")
+- [ ] Visual treatment: icon or illustration (not a blank white box)
+- [ ] When filtered and empty: show what filter is active; offer "Clear all filters"
+- [ ] Error state (couldn't load) is distinct from empty state (loaded but empty) — error needs a retry
+
+### Common mistakes
+
+- Generic "No results" with no context or action — leaves users stranded
+- Empty state that looks like a bug — provide enough context that users trust the app is working correctly
+- Same empty state for all situations — loading error, empty dataset, and filter-with-no-results are three different states

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)

package/ui-references/surface.md

@@ -0,0 +1,188 @@
+# Surface — UI References
+
+Surface components are containers and overlays: they frame content, present it in context, and layer it above other content. The quality of a surface shows in its edge cases — what happens when content overflows, when it's positioned near a viewport edge, or when a screen reader announces it.
+
+---
+
+## Card
+
+A bounded content container that groups related information. Cards are surfaces, not actions: they can be clickable (linking to detail views) but clicking a card is navigation, not a form submission.
+
+### Reference implementations
+
+- **[shadcn/ui Card](https://ui.shadcn.com/docs/components/card)** — `CardHeader`, `CardTitle`, `CardDescription`, `CardContent`, `CardFooter` composition pattern; clear separation of structural slots.
+- **[Radix UI Card](https://www.radix-ui.com/themes/docs/components/card)** — minimal themed card with consistent shadow and radius; good baseline for a design system.
+- **[Linear's cards](https://linear.app)** — observe in issues and project views: no excessive shadow, border defines the edge, hover state is a background tint (not elevation change), active selection uses a strong left border.
+- **[Vercel/Geist Card](https://vercel.com/geist/components)** — flat cards with border; the standard for enterprise/dashboard contexts.
+
+### Minimum quality bar
+
+- [ ] Consistent internal padding (match the project's grid unit)
+- [ ] Container border-radius matches the project's `container` radius value — not the `control` radius
+- [ ] If the whole card is clickable: `<a>` wrapping the card (not an `onClick` on a `<div>`)
+- [ ] If part of the card is clickable (e.g. title link + action button): use `::after` pseudo-element on the title link to expand its hit area to the card; action button has its own event without conflict
+- [ ] Hover state is visible; active/pressed state is visible
+- [ ] Card body does not use `overflow: hidden` aggressively — truncation should be controlled and indicated
+
+### Common mistakes
+
+- Wrapping an entire card in `<a>` when it also contains buttons — creates nested interactive elements and confuses screen readers
+- Elevation (box-shadow) as the primary border — elevation should supplement, not replace, a visible edge
+- Fixed height cards that hide overflow without indication — use truncation with ellipsis and tooltip, not silent clipping
+
+---
+
+## Popover
+
+A floating overlay anchored to a trigger element. Used for secondary actions, rich tooltips, or inline editing. Differs from a tooltip: popovers can contain interactive elements.
+
+### Reference implementations
+
+- **[Radix UI Popover](https://www.radix-ui.com/primitives/docs/components/popover)** — the reference: `role="dialog"` when interactive, focus moves into the popover on open, Escape closes and returns focus. `side`, `align`, and `avoidCollisions` handle positioning near viewport edges.
+- **[shadcn/ui Popover](https://ui.shadcn.com/docs/components/popover)** — Radix Popover with Tailwind; shows the trigger + content pattern cleanly.
+- **[Floating UI](https://floating-ui.com/)** — the positioning library underlying Radix, Headless UI, and others; consult for edge cases in custom positioning logic.
+
+### Minimum quality bar
+
+- [ ] `role="dialog"` with `aria-label` or `aria-labelledby` when the popover contains interactive content
+- [ ] Focus moves into the popover when it opens (for interactive popovers)
+- [ ] Escape closes the popover; click outside closes; focus returns to trigger
+- [ ] Stays within viewport: flips side and/or shifts along axis when near an edge
+- [ ] Arrow indicator (optional but helpful) points to the anchor and repositions when the popover flips
+- [ ] Does not scroll the page body when scrolling inside the popover
+
+### Common mistakes
+
+- Non-interactive popovers that receive focus — only interactive popovers should trap/move focus
+- Popover that overflows the viewport on small screens — always test positioning at mobile widths
+- Opening a popover on hover without a click fallback — hover-only is inaccessible
+
+---
+
+## Tooltip
+
+A small informational overlay that appears on hover (and focus). Tooltips explain UI elements; they do not contain interactive elements. If you need interactive content in the overlay, use a Popover.
+
+### Reference implementations
+
+- **[Radix UI Tooltip](https://www.radix-ui.com/primitives/docs/components/tooltip)** — `role="tooltip"` on the content, `aria-describedby` linking the trigger to the tooltip. Delay before showing (300ms default), immediate hide on mouse leave.
+- **[shadcn/ui Tooltip](https://ui.shadcn.com/docs/components/tooltip)** — clean implementation; the `TooltipProvider` wrapping pattern for shared delay configuration.
+- **[Floating UI Tooltip tutorial](https://floating-ui.com/docs/tooltip)** — explains hover + focus event handling without ARIA mistakes.
+
+### Minimum quality bar
+
+- [ ] `role="tooltip"` on the content element
+- [ ] Trigger has `aria-describedby` pointing to the tooltip id
+- [ ] Shows on hover AND on keyboard focus (not hover only)
+- [ ] Delay before showing (200–300ms) prevents tooltip flicker on cursor pass-through
+- [ ] Tooltip is dismissible via Escape key while visible
+- [ ] Does not obscure the element being described
+- [ ] Text content only — if you need a button inside, it's a Popover
+- [ ] Respects `prefers-reduced-motion` for entry animation
+
+### Common mistakes
+
+- Tooltip on a disabled element — disabled elements don't receive focus events; wrap the disabled element in a `<span>` for the tooltip
+- Tooltip that duplicates the visible label exactly — adds no value; tooltip text should supplement, not repeat
+- Interactive content (links, buttons) inside a tooltip — use Popover instead
+
+---
+
+## Sheet / Drawer
+
+A panel that slides in from an edge of the screen (most commonly the right). Used for secondary task panels, filter drawers, detail views, or mobile navigation.
+
+### Reference implementations
+
+- **[shadcn/ui Sheet](https://ui.shadcn.com/docs/components/sheet)** — four opening directions (top, right, bottom, left); `role="dialog"`, focus trap, Escape to close; uses the Radix UI Dialog primitive underneath.
+- **[Radix UI Dialog as Sheet](https://www.radix-ui.com/primitives/docs/components/dialog)** — sheets are typically implemented on top of a dialog primitive with CSS positioning.
+- **[Linear's right panel](https://linear.app)** — observe the issue detail panel: slides in from the right, does not cover the main content at wider viewports (side-by-side layout), full-screen on mobile.
+
+### Minimum quality bar
+
+- [ ] `role="dialog"`, `aria-modal="true"`, `aria-label` or `aria-labelledby`
+- [ ] Focus trap: Tab/Shift+Tab cycle inside the sheet while open
+- [ ] Opens with slide animation; closes with slide animation; `prefers-reduced-motion` respects instant open/close
+- [ ] Escape closes; clicking the scrim closes; close button always visible
+- [ ] On mobile: always full-screen or nearly full-screen — partial drawers cause content-below-fold confusion
+- [ ] Handles soft keyboard on mobile (input fields inside the sheet must be visible when keyboard opens)
+
+### Common mistakes
+
+- Sheet that cannot be closed without completing a form — always allow escape/scrim close
+- Sheet that scrolls the background page — lock body scroll while sheet is open
+- Nested sheets — avoid; create a single sheet that can change its contents instead
+
+---
+
+## Avatar
+
+Represents a user or entity with an image, initials, or icon. Appears in lists, comments, headers, and presence indicators.
+
+### Reference implementations
+
+- **[Radix UI Avatar](https://www.radix-ui.com/primitives/docs/components/avatar)** — image with `AvatarFallback` that shows while image loads or on error. The fallback timing (delay before fallback renders) avoids flash-of-initials before the image loads.
+- **[shadcn/ui Avatar](https://ui.shadcn.com/docs/components/avatar)** — clean implementation; the image + fallback pattern with consistent sizing.
+
+### Minimum quality bar
+
+- [ ] Image has `alt` text describing who it represents (not `alt=""` — that's for decorative images)
+- [ ] Fallback (initials or generic icon) when image fails to load or is not provided
+- [ ] Fallback renders deterministically — same initials/color every time for the same user
+- [ ] Consistent sizes across the product — define a size scale (sm/md/lg) and stick to it
+- [ ] Avatar groups (stacked avatars): `z-index` and margin-left negative offset done with CSS, not absolute positioning
+
+### Common mistakes
+
+- `alt=""` on user avatar images — these are meaningful, not decorative; describe who the image shows
+- Avatar that shows a broken image icon instead of fallback — always handle image load failure
+- Fallback background color that is too light against a white background — ensure sufficient contrast
+
+---
+
+## Separator / Divider
+
+A visual line that separates groups of content. Structural, not decorative — it communicates that what's above and below belong to different groups.
+
+### Reference implementations
+
+- **[Radix UI Separator](https://www.radix-ui.com/primitives/docs/components/separator)** — `role="separator"` (structural) or `role="none"` (decorative), horizontal and vertical orientation.
+- **[shadcn/ui Separator](https://ui.shadcn.com/docs/components/separator)** — thin horizontal/vertical rule.
+
+### Minimum quality bar
+
+- [ ] `role="separator"` when the line communicates structure (between sections); `role="none"` or `aria-hidden="true"` when purely decorative
+- [ ] Color passes 3:1 contrast against its background
+- [ ] Does not carry margin by default — let the container control spacing
+- [ ] Horizontal separators extend to the full width of their container unless explicitly inset
+
+### Common mistakes
+
+- Using `<hr>` inside inline contexts — `<hr>` has block display; use `role="separator"` on a `<span>` for inline separators
+- Separator with too much vertical margin — creates too much visual space between related groups
+
+---
+
+## Badge
+
+A small label applied to an element to communicate status, count, or category. Appears inline next to text or as an overlay on an icon.
+
+### Reference implementations
+
+- **[shadcn/ui Badge](https://ui.shadcn.com/docs/components/badge)** — variant system (default, secondary, destructive, outline); small, not button-like.
+- **[Radix UI Badge](https://www.radix-ui.com/themes/docs/components/badge)** — color-coded badges with good contrast defaults across themes.
+- **[Linear's labels](https://linear.app)** — observe issue labels: colored dot + text, keyboard accessible in filter panels, consistent small size.
+- **[GitHub Primer Label](https://primer.style/components/label/react/alpha)** — handles "filled" and "outline" variants with color theming.
+
+### Minimum quality bar
+
+- [ ] Not a button — badges are not interactive; if clicking a badge does something, it should be a `<button>` or `<a>` visually styled as a badge
+- [ ] Text must pass 4.5:1 contrast against its background color
+- [ ] Numeric badges (notification counts): `aria-label="N notifications"` on the parent container; the badge itself is `aria-hidden`
+- [ ] Never convey information through color alone — include text or icon alongside color coding
+- [ ] Consistent height and padding across all badge uses in the product
+
+### Common mistakes
+
+- Badge that is a `<div>` with `onClick` — should be `<button>` for interactivity or `<span>` for decoration
+- Too many badge variants — three variants (default, success, danger) cover most cases; more adds cognitive load