exonous 0.0.0-stage → 2.10.4

package/assets/skills/ui-motion/reference/prototype.md

@@ -0,0 +1,238 @@
+# UI prototypes with variant picker
+
+Build **genuinely different** implementations of one UI piece behind fixed harness chrome so the user compares live and promotes a winner. Not for reviewing shipping code (`reference/review.md`) or dependency choice (`reference/ui-libraries.md`).
+
+## Posture
+
+Divergence is the product — three accent tweaks teach nothing. Each variant must be shippable-quality motion: ease-out entrances, sub-300ms UI, correct origins, transform/opacity, reduced motion. Sloppy variants waste the picker.
+
+## Hard rules
+
+1. **No production edits** until user picks winner (Phase 6).
+2. Variants differ on a **named axis** (layout, density, personality, motion model) — shared tokens OK.
+3. Each variant **works** — real interactions, plausible copy, no lorem/dead controls.
+4. Picker chrome is **spec-fixed** below — not themed to the product.
+5. After promote, remove prototype surface unless user keeps it.
+
+## Workflow
+
+### 1 — Scope
+
+One component per run. Multi-piece briefs → pick highest leverage, offer follow-ups. Restate brief in one sentence.
+
+### 2 — Recon
+
+Stack, styling, motion libs, design tokens, personality, surrounding context. No project → neutral standalone defaults.
+
+### 3 — Directions
+
+Default **3** variants (max **5**). Name + axis before code; no "Option A". Replace duplicates that differ only in color.
+
+### 4 — Harness
+
+- **With dev server:** isolated route `/prototypes/<slug>`, one file per variant + harness — no imports into production.
+- **Static:** single HTML file, inline assets.
+
+Embed picker spec from **Picker spec** section. Show **one variant full-size** in realistic context (toast needs page behind it). **Variant switch is instant** — high-frequency action, no transition.
+
+### 5 — Verify & hand off
+
+Run all variants; clean console; screenshot if possible. Present table and **stop for user choice**:
+
+| # | Variant | Axis | When to pick it | Cost |
+| --- | --- | --- | --- | --- |
+
+Share URL/path and keyboard hints.
+
+### 6 — Promote
+
+Integrate winner into production conventions; delete prototype dir unless `keep … leave the picker`.
+
+### Invocation
+
+| Input | Behavior |
+| --- | --- |
+| description | Full flow, 3 variants |
+| description xN | N variants (≤5) |
+| riff &lt;name&gt; | New set around that direction |
+| keep &lt;name&gt; | Promote + cleanup |
+| keep &lt;name&gt;, leave the picker | Promote, keep harness |
+
+---
+
+## Picker spec (harness chrome — fixed)
+
+Dark glass pill, bottom-center (or `data-position="top"` if variant occupies bottom-center). Not brand-themed.
+
+### Markup
+
+```html
+<nav class="variant-rail" aria-label="Prototype variants">
+  <span class="variant-rail-thumb" aria-hidden="true"></span>
+  <button class="variant-rail-btn" data-active aria-current="true">Quiet</button>
+  <button class="variant-rail-btn">Bold</button>
+  <button class="variant-rail-btn">Playful</button>
+  <span class="variant-rail-sep" aria-hidden="true"></span>
+  <button class="variant-rail-btn variant-rail-replay" aria-label="Replay animation (R)">↻</button>
+</nav>
+```
+
+Framework: keep class names and structure.
+
+### Styles
+
+```css
+.variant-rail {
+  position: fixed;
+  bottom: 24px;
+  left: 50%;
+  transform: translateX(-50%);
+  z-index: 2147483647;
+  display: flex;
+  align-items: center;
+  gap: 2px;
+  padding: 4px;
+  border-radius: 999px;
+  background: rgba(10, 10, 10, 0.82);
+  -webkit-backdrop-filter: blur(12px) saturate(1.4);
+  backdrop-filter: blur(12px) saturate(1.4);
+  box-shadow:
+    0 0 0 1px rgba(255, 255, 255, 0.08) inset,
+    0 8px 24px rgba(0, 0, 0, 0.24),
+    0 2px 6px rgba(0, 0, 0, 0.12);
+  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+  font-size: 13px;
+  line-height: 1;
+  -webkit-font-smoothing: antialiased;
+  user-select: none;
+}
+
+.variant-rail-thumb {
+  position: absolute;
+  top: 4px;
+  left: 0;
+  height: 28px;
+  border-radius: 999px;
+  background: rgba(255, 255, 255, 0.12);
+  will-change: transform;
+}
+
+.variant-rail[data-ready] .variant-rail-thumb {
+  transition:
+    transform 250ms cubic-bezier(0.23, 1, 0.32, 1),
+    width 250ms cubic-bezier(0.23, 1, 0.32, 1);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .variant-rail[data-ready] .variant-rail-thumb { transition: none; }
+}
+
+.variant-rail-btn {
+  position: relative;
+  display: flex;
+  align-items: center;
+  height: 28px;
+  padding: 0 12px;
+  border: 0;
+  border-radius: 999px;
+  background: transparent;
+  color: rgba(255, 255, 255, 0.55);
+  font: inherit;
+  cursor: pointer;
+  transition: color 150ms ease-out;
+}
+
+.variant-rail-btn:hover { color: rgba(255, 255, 255, 0.85); }
+.variant-rail-btn:active { transform: scale(0.97); }
+.variant-rail-btn:focus-visible {
+  outline: 2px solid rgba(255, 255, 255, 0.4);
+  outline-offset: 2px;
+}
+.variant-rail-btn[data-active] { color: #fff; }
+
+.variant-rail-sep {
+  width: 1px;
+  height: 16px;
+  margin: 0 4px;
+  background: rgba(255, 255, 255, 0.12);
+}
+
+.variant-rail-replay { padding: 0 10px; font-size: 14px; }
+
+.variant-rail[data-position="top"] {
+  bottom: auto;
+  top: 24px;
+}
+```
+
+Thumb slides (250ms strong ease-out); **preview swap stays instant**. Width transition on thumb is allowed — no layout dependents.
+
+Replay control only if a variant has replay-worthy entrance motion.
+
+### Behavior
+
+- Keys `1–N`, arrows, `R` replay; ignore when focus in input/textarea/select/contenteditable or modifiers held.
+- Click sets `data-active` + `aria-current="true"`; thumb follows.
+- Persist `?v=` in URL; `data-ready` after first paint so load does not animate thumb.
+- Switch remounts variant (entrances replay); `R` remounts current.
+
+### Reference wiring (vanilla)
+
+```js
+const canvas = document.getElementById('stage');
+const rail = document.querySelector('.variant-rail');
+const thumb = rail.querySelector('.variant-rail-thumb');
+const tabs = [...rail.querySelectorAll('.variant-rail-btn:not(.variant-rail-replay)')];
+const replayBtn = rail.querySelector('.variant-rail-replay');
+let idx = 0;
+
+function syncThumb() {
+  const tab = tabs[idx];
+  thumb.style.width = `${tab.offsetWidth}px`;
+  thumb.style.transform = `translateX(${tab.offsetLeft}px)`;
+}
+
+function renderVariant(i) {
+  canvas.replaceChildren();
+  requestAnimationFrame(() => {
+    const root = renderers[i]();
+    canvas.append(root);
+  });
+}
+
+function selectVariant(i) {
+  if (i < 0 || i >= renderers.length) return;
+  idx = i;
+  tabs.forEach((el, j) => {
+    const on = j === i;
+    el.toggleAttribute('data-active', on);
+    el.setAttribute('aria-current', on ? 'true' : 'false');
+  });
+  syncThumb();
+  const loc = new URL(location.href);
+  loc.searchParams.set('v', String(i + 1));
+  history.replaceState(null, '', loc);
+  renderVariant(i);
+}
+
+tabs.forEach((el, i) => el.addEventListener('click', () => selectVariant(i)));
+replayBtn?.addEventListener('click', () => renderVariant(idx));
+window.addEventListener('resize', syncThumb);
+
+document.addEventListener('keydown', (ev) => {
+  const tag = ev.target.tagName;
+  if (/^(INPUT|TEXTAREA|SELECT)$/.test(tag) || ev.target.isContentEditable) return;
+  if (ev.metaKey || ev.ctrlKey || ev.altKey) return;
+  const n = parseInt(ev.key, 10);
+  if (n >= 1 && n <= renderers.length) selectVariant(n - 1);
+  else if (ev.key === 'ArrowRight') selectVariant((idx + 1) % renderers.length);
+  else if (ev.key === 'ArrowLeft') selectVariant((idx - 1 + renderers.length) % renderers.length);
+  else if (ev.key === 'r' || ev.key === 'R') renderVariant(idx);
+});
+
+const fromUrl = parseInt(new URLSearchParams(location.search).get('v'), 10) || 1;
+selectVariant(fromUrl - 1);
+requestAnimationFrame(() => requestAnimationFrame(() => rail.setAttribute('data-ready', '')));
+```
+
+`renderers` = array of functions returning DOM nodes for each variant.

package/assets/skills/ui-motion/reference/review.md

@@ -0,0 +1,163 @@
+# Review, audit & improve motion
+
+Single procedure for: **diff review** (block/approve), **codebase audit** (read-only findings), and **planning fixes** (self-contained plans for executors). Does not apply patches — executors use `exo-frontend` / `exo-mobile` or user-directed agents.
+
+---
+
+## Part A — Review a diff
+
+Specialized motion review only. Default **flag**; approval is earned.
+
+### Ten standards (violations = findings)
+
+1. **Justified motion** — purpose from allowed set; not "looks cool" on frequent UI.
+2. **Frequency fit** — 100+/day and keyboard → no animation; tiers per `SKILL.md`.
+3. **Responsive easing** — enter/exit ease-out or strong custom; **no ease-in** on UI.
+4. **Sub-300ms UI** — unless justified (drawer/marketing tiers).
+5. **Origin & physicality** — trigger-anchored origin; no `scale(0)`; modals centered OK.
+6. **Interruptibility** — transitions/springs for rapid/gesture UI; not keyframes that restart.
+7. **GPU props** — transform/opacity; no layout props; Motion shorthands under load → full transform string.
+8. **Accessibility** — reduced motion (gentler, not zero); hover behind `(hover: hover) and (pointer: fine)`.
+9. **Asymmetric timing** — slow deliberate user phase, fast system response.
+10. **Cohesion** — motion matches product personality; blur(2px) seam optional on bad crossfades.
+
+### Escalate immediately
+
+`transition: all`; `scale(0)`; ease-in on UI; animation on keyboard/high-frequency; UI >300ms unjustified; center origin on anchored popover; keyframes on toasts/toggles; layout animation; Motion x/y on busy pages; parent CSS var driving child transform; missing reduced-motion or hover gate; symmetric press/release on hold flows; group entrance without 30–80ms stagger.
+
+### Fix preference order
+
+1. Delete animation → 2. Reduce → 3. Fix easing → 4. Fix origin/physicality → 5. Interruptible mechanism → 6. GPU path → 7. Asymmetric timing → 8. Polish (stagger, blur, `@starting-style`, spring) → 9. A11y & cohesion.
+
+### Required output
+
+**Table** (not Before/After lists):
+
+| Before | After | Why |
+| --- | --- | --- |
+
+**Verdict tiers:** feel-breaking → simplifications → performance → interruptibility → origin/cohesion → a11y.
+
+Close with **Block** (any feel-breaking, keyboard motion, scale(0), ease-in, easy GPU fix missed) or **Approve**.
+
+Cite `file:line`. Values from reference tables below — never approximate.
+
+---
+
+## Part B — Audit playbook (eight categories)
+
+Use for full-repo or focused audits. Same value tables as review.
+
+### 1. Purpose & frequency
+
+Hunt keyboard/palette animation, decorative list/hover on constant paths. Strongest fix: delete.
+
+### 2. Easing & duration
+
+Decision order: enter/exit → ease-out; on-screen move → ease-in-out; hover/color → ease; constant → linear.
+
+Tokens:
+
+```css
+--ease-out: cubic-bezier(0.23, 1, 0.32, 1);
+--ease-in-out: cubic-bezier(0.77, 0, 0.175, 1);
+--ease-drawer: cubic-bezier(0.32, 0.72, 0, 1);
+```
+
+Duration budgets: press 100–160; tooltip 125–200; dropdown 150–250; modal/drawer 200–500; marketing longer. UI <300ms. Toolbar tooltips after first should skip delay/animation.
+
+### 3. Physicality & origin
+
+No `scale(0)` — use 0.9–0.97 + opacity. Popovers: `transform-origin: var(--transform-origin)`. Press: scale(0.97), 160ms ease-out.
+
+### 4. Interruptibility
+
+Transitions vs keyframes; `@starting-style` or mount flag; springs for gestures `{ type: "spring", duration: 0.5, bounce: 0.2 }` bounce 0.1–0.3; velocity dismiss > ~0.11; rubber-band not wall; asymmetric hold/release.
+
+### 5. Performance
+
+transform/opacity; no `transition: all`; no parent `--var` driving child transform; Motion → transform string; CSS/WAAPI for predetermined under load; blur <20px.
+
+### 6. Accessibility
+
+Reduced motion + hover gating (snippets in `SKILL.md`).
+
+### 7. Cohesion & tokens
+
+Personality match; consolidate duplicate beziers; stagger 30–80ms; crossfade blur mask.
+
+### 8. Missed opportunities
+
+Teleport states, missing trigger spatial story, rare delight flat — handful only, evidence-based.
+
+---
+
+## Part C — Improve workflow (audit → plans)
+
+Read-only on product source. Output lives under `plans/` or `animation-plans/`.
+
+### Phase 1 — Recon
+
+Stack, motion libs, token locations, personality, frequency map. Grep: `transition`, `@keyframes`, `motion.`, `ease-in`, `transition: all`, `scale(0)`, `prefers-reduced-motion`, `transform-origin`.
+
+### Phase 2 — Audit
+
+Run Part B categories. Large repos: parallel read-only passes per category with recon facts embedded. Effort levels:
+
+| Mode | Scope | Findings |
+| --- | --- | --- |
+| quick | Hot paths | ~5 HIGH only |
+| standard | All interactive UI | Full table |
+| deep | Whole repo + marketing | Full + LOW polish |
+
+### Phase 3 — Vet & prioritize
+
+Confirm every finding at `file:line`. Drop by-design (modal center origin, marketing duration). Table:
+
+| # | Impact | Theme | Where | Issue | Remedy (one line) |
+
+Impact: **HIGH** breaks feel; **MEDIUM** users notice; **LOW** polish. List 2–4 additive opportunity rows apart from fixes. **Wait for user** to pick plan targets unless batch mode → top 3–5 by leverage.
+
+### Phase 4 — Plans
+
+One markdown plan per selected finding in `plans/NNN-slug.md`. Plans must be executor-proof:
+
+- Full paths and current code excerpt
+- Exact target bezier, ms, spring config inline
+- Ordered steps, scope boundaries
+- Verification + feel-check (slow motion, frame step, real device for gestures)
+- Stamp `git rev-parse --short HEAD` when writing
+
+Update `plans/README.md` with order, dependencies, status.
+
+### Invocation variants
+
+| Call | Behavior |
+| --- | --- |
+| default | Full recon → audit → vet → wait → plans |
+| quick / deep | Adjust coverage |
+| category focus | Single category audit |
+| plan <description> | Skip audit; one plan after minimal recon |
+| execute <plan> | Executor implements; re-review diff at Part A bar |
+| reconcile | Refresh plan status vs current code |
+
+Respect documented intentional tradeoffs in code/docs — note, do not reopen.
+
+---
+
+## Reference values (cite in findings)
+
+**Springs (web Motion):**
+
+```js
+{ type: "spring", duration: 0.5, bounce: 0.2 }
+{ type: "spring", mass: 1, stiffness: 100, damping: 10 }
+```
+
+**Gesture dismiss:** `velocity = Math.abs(distance) / elapsedMs`; dismiss if > ~0.11 or past distance threshold.
+
+**Stagger:** 30–80ms; decorative only.
+
+**Debugging when uncertain:** 2–5× duration, DevTools animation panel, physical device for gestures, revisit next day.
+
+**Cohesion note:** Component personality sets curve choice — crisp dashboard vs playful consumer; toast libraries may use slightly slower `ease` for elegance if whole system matches.

package/assets/skills/ui-motion/reference/toasts.md

@@ -0,0 +1,144 @@
+# Sonner — React toasts
+
+Guide for [Sonner](https://sonner.emilkowal.ski): mount once, call `toast()` from client code, style and debug. Exact prop tables below; options on `toast()` override Toaster defaults.
+
+## Setup
+
+1. **Single `<Toaster />`** near app root (Next.js `layout.tsx` works in RSC). Never per-page or conditional — duplicates every toast.
+2. **`toast()` from client** — handlers, effects, callbacks. Server actions: return data; call `toast()` where the client handles the response.
+
+```jsx
+import { Toaster } from 'sonner';
+import { toast } from 'sonner';
+```
+
+## Choosing an API
+
+| Goal | API |
+| --- | --- |
+| Simple line | `toast('Title')` + optional `{ description }` |
+| Typed icon | `toast.success` / `.error` / `.info` / `.warning` |
+| Manual loading → done | `toast.loading` then update same `id` |
+| Promise lifecycle | `toast.promise(promise, { loading, success, error })` — success/error may be functions of result |
+| Primary action | `{ action: { label, onClick } }` — closes unless `preventDefault` on click |
+| Secondary | `{ cancel: { label, onClick } }` |
+| JSX in default chrome | `toast(<Node />)` |
+| Full custom shell | `toast.custom((t) => <Node />)` — `t` has id for dismiss |
+
+## Patterns
+
+**Update by id**
+
+```jsx
+const handleUpload = async () => {
+  const id = toast.loading('Sending file…');
+  await upload();
+  toast.success('Sent', { id });
+};
+```
+
+**Persist / dismiss / inspect**
+
+- `{ duration: Infinity }` keeps open
+- `toast.dismiss(id)` or `toast.dismiss()` for all
+- `useSonner()` → `{ toasts }` in React; `toast.getActiveToasts()` outside
+
+**Rich title/description** — function returning JSX: `toast(() => <a href="/item">Open</a>)`
+
+**Multiple toasters** — unique `id` on each `<Toaster />`; target with `toast('…', { toasterId: 'sidebar' })`. Omitting `toasterId` broadcasts to all.
+
+**Close hooks** — `onDismiss` (button/swipe); `onAutoClose` (timeout). No combined callback.
+
+## Styling ladder (climb only as needed)
+
+1. Defaults; `richColors` for vivid success/error; `invert` for contrast flip.
+2. `toastOptions={{ style: { … } }}` global or per-call `style`.
+3. `classNames` on toast parts — injected Sonner CSS wins; Tailwind needs `!` prefix. Many `!important`s → go headless.
+4. **`toast.custom()`** — recommended for design-system toasts; wrap in your own helper. (`unstyled: true` is partial escape hatch.)
+
+**Icons** — Toaster `icons` map or per-toast `icon`; `null` removes default.
+
+**Theme** — default `theme='light'` ignores OS. Use `theme="system"` or `<Toaster theme={resolvedTheme} />` from your theme provider.
+
+## Troubleshooting
+
+| Symptom | Fix |
+| --- | --- |
+| Never shows | No root Toaster, or unmounted. Client-only from server actions. |
+| Duplicate | Two Toasters (layout + page). StrictMode double effect → fire from handler or stable `id`. |
+| Classes ignored | Defaults win — `!important`, `unstyled`, or custom. |
+| Unstyled (Astro, view transitions) | `import 'sonner/dist/styles.css'` in layout. |
+| Shadow DOM | Copy `[data-sonner-toaster]` style tag into shadow root. |
+| Behind modal / clipped | Stacking context (`transform`, `filter`, `overflow`) or z-index — mount Toaster at document root outside dialogs. |
+| Dark mode wrong | Set system or resolved theme prop. |
+| Gray success/error | Enable `richColors`. |
+| Won't close | `duration: Infinity`, `dismissible: false`, or unsettled `toast.promise`. |
+| promise stuck loading | Must pass settling Promise; success/error configs valid. |
+| Swipe wrong axis | Set `swipeDirections` on Toaster; defaults follow `position`. |
+| Every toaster shows toast | Use `toasterId` pairing. |
+| Mobile edge tight | `offset` (default 32px desktop), `mobileOffset` (16px &lt;600px) — number, string, or per-side object. |
+
+---
+
+## API reference
+
+### `<Toaster />`
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `theme` | `string` | `'light'` | `'light'`, `'dark'`, `'system'`. |
+| `richColors` | `boolean` | `false` | Stronger error/success color. |
+| `expand` | `boolean` | `false` | Expanded stack default (else expand on hover). |
+| `visibleToasts` | `number` | `3` | Visible count. |
+| `id` | `string` | – | Matched by `toast({ toasterId })`. |
+| `position` | `string` | `'bottom-right'` | `top-left`, `top-center`, `top-right`, `bottom-left`, `bottom-center`, `bottom-right`. |
+| `closeButton` | `boolean` | `false` | Close on all toasts. |
+| `offset` | `string \| number \| object` | `'32px'` | Edge inset; object per side e.g. `{ bottom: '24px', right: '16px' }`. |
+| `mobileOffset` | `string \| number \| object` | `'16px'` | Inset when width &lt; 600px. |
+| `swipeDirections` | `array` | from position | Allowed dismiss swipe directions. |
+| `dir` | `string` | `'ltr'` | Text direction. |
+| `hotkey` | `string` | `⌥/alt + T` | Focus toaster region. |
+| `invert` | `boolean` | `false` | Invert light/dark toast surface. |
+| `toastOptions` | `object` | – | Defaults for every `toast()` option below. |
+| `gap` | `number` | `14` | Gap when expanded. |
+| `icons` | `object` | – | `{ success, info, warning, error, loading }`; `null` clears one. |
+
+### `toast(message, options?)`
+
+Message: string, JSX, or function → JSX. Returns toast id.
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `description` | `ReactNode` | – | Subtitle; may be function → JSX. |
+| `closeButton` | `boolean` | `false` | Per-toast close. |
+| `invert` | `boolean` | `false` | Per-toast invert. |
+| `duration` | `number` | `4000` | Auto-close ms; `Infinity` persists. |
+| `position` | `string` | `'bottom-right'` | Override placement. |
+| `dismissible` | `boolean` | `true` | `false` blocks user dismiss. |
+| `icon` | `ReactNode` | – | Leading icon; `null` hides default. |
+| `action` | `ReactNode \| { label, onClick }` | – | Primary; closes unless `preventDefault`. |
+| `cancel` | `ReactNode \| { label, onClick }` | – | Secondary; closes on click. |
+| `actionButtonStyle` | `object` | `{}` | Action button inline styles. |
+| `cancelButtonStyle` | `object` | `{}` | Cancel button inline styles. |
+| `id` | `string` | – | Re-call with same id updates in place. |
+| `testId` | `string` | – | `data-testid`. |
+| `toasterId` | `string` | – | Target toaster `id`. |
+| `style` | `object` | – | Inline toast styles. |
+| `classNames` | `object` | – | `{ toast, title, description, actionButton, cancelButton, closeButton }` — needs `!important` unless `unstyled`. |
+| `unstyled` | `boolean` | `false` | Strip default styles. |
+| `onDismiss` | `(toast) => void` | – | Close button or swipe. |
+| `onAutoClose` | `(toast) => void` | – | Timeout close. |
+| `containerAriaLabel` | `string` | `'Notifications'` | Region label. |
+
+### Functions
+
+| API | Role |
+| --- | --- |
+| `toast(msg, opts?)` | Show; returns id. |
+| `toast.success / .error / .info / .warning` | Typed variants. |
+| `toast.loading` | Spinner; update via id. |
+| `toast.promise(promise, { loading, success, error })` | Async lifecycle. |
+| `toast.custom((t) => jsx, opts?)` | Headless content. |
+| `toast.dismiss(id?)` | One or all. |
+| `toast.getActiveToasts()` | Snapshot outside React. |
+| `useSonner()` | `{ toasts }` hook. |

package/assets/skills/ui-motion/reference/ui-libraries.md

@@ -0,0 +1,71 @@
+# Picking UI & motion libraries
+
+Explicit invocation only. Map **task → one recommendation** from the curated list. Check `package.json` first — prefer what is installed; flag churn if a competitor is already entrenched.
+
+## Steps
+
+1. Identify the **task** (dropdown → primitives), not the library user named.
+2. Read existing dependencies.
+3. Recommend **one** library, one-sentence why; wire/install if requested — no option menus when the list is clear.
+4. Uncovered tasks: say you left the list; suggest from general knowledge.
+
+## Curated list
+
+### UI components & primitives
+
+| Task | Library |
+| --- | --- |
+| Accessible unstyled primitives (dialog, popover, menu, select…) | [base-ui](https://base-ui.com) |
+| Command palette (⌘K) | [cmdk](https://cmdk.paco.me) |
+| Toasts | [Sonner](https://sonner.emilkowal.ski) — see [toasts.md](toasts.md) |
+| OTP / verification input | [input-otp](https://input-otp.rodz.dev) |
+| Debug/control GUI | [Leva](https://github.com/pmndrs/leva) — [dialkit](https://joshpuckett.me/dialkit) alternate |
+
+### Motion & visuals
+
+| Task | Library |
+| --- | --- |
+| Springs, layout, enter/exit, gestures | [motion](https://motion.dev) |
+| Animated numbers | [NumberFlow](https://number-flow.barvian.me) |
+| Animated text | [torph](https://torph.lochie.me/) |
+| 3D globe | [Cobe](https://cobe.vercel.app) |
+| Dynamic OG images | [Satori](https://github.com/vercel/satori) |
+| Syntax highlighting | [shiki](https://shiki.style) |
+
+Use Motion when springs/layout/exit/gesture needed — not for a lone CSS hover fade.
+
+### Charts
+
+| Task | Library |
+| --- | --- |
+| Live streaming series | [Liveline](https://github.com/benjitaylor/liveline) |
+| General dashboards | [recharts](https://recharts.org) |
+
+### Lists, drag, throughput
+
+| Task | Library |
+| --- | --- |
+| Reorderable / draggable UI | [dnd kit](https://dndkit.com) |
+| Virtualized long lists or tables | [Virtuoso](https://virtuoso.dev) |
+
+### State & styling
+
+| Task | Library |
+| --- | --- |
+| Client state | [zustand](https://zustand.docs.pmnd.rs) |
+| Conditional class strings | [clsx](https://github.com/lukeed/clsx) |
+| Typed Tailwind variants | [cva](https://cva.style) |
+| Theme without flash | [next-themes](https://github.com/pacocoursey/next-themes) |
+
+clsx for ad-hoc classes; cva when variants deserve a typed API — they compose.
+
+## Common mismatches
+
+- Hand-rolled toasts or modal-as-toast → Sonner
+- Div dropdown without focus trap → base-ui
+- Re-rendered number text → NumberFlow
+- 1000+ DOM rows → Virtuoso
+- Prop-drilled shared state web → zustand
+- Deep ternary class strings → clsx/cva
+
+For animation **implementation** after picking Motion or CSS, use [web.md](web.md) or [expo.md](expo.md).