whale-igniter 1.3.0 → 1.3.2

package/dist/commands/ignite.js

@@ -46,7 +46,8 @@ export async function igniteCommand(projectName = "whale-project", options = {})
         };
     }
     // ---- Step 1: scaffold workspace -------------------------------------------
-    const target = await initCommand(projectName, { config, silent: true });
+    const resolvedProjectName = config.projectName ?? projectName;
+    const target = await initCommand(resolvedProjectName, { config, silent: true });
     const targetRel = path.relative(process.cwd(), target) || ".";
     console.log(ui.ok(`Workspace created at ${ui.path(targetRel)}`));
     // ---- Step 1b: record free-text project intent as first decision ------------

package/dist/version.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "whale-igniter",
-  "version": "1.3.0",
+  "version": "1.3.2",
   "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