whale-igniter 1.2.3 → 1.3.1

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