vibecodeagent 0.0.0-stage → 0.1.64

package/dist/resources/skills/builtin/frontend-design/references/motion.md

@@ -0,0 +1,222 @@
+# Motion Doctrine (Web)
+
+The canonical motion reference for this skill. Every duration, curve, and spring config in the other files traces back to here — when another file and this one disagree, this one wins. It turns a request for motion into an implementation that would survive a strict review, and it exists to produce zero lines of code sometimes: the most common animation defect is animating something that should never animate.
+
+For React Native / Expo, use [expo.md](expo.md) — the doctrine is the same, the runtime rules are not. For gesture physics, velocity handoff, and fluid-interface details, [apple-fluid.md](apple-fluid.md) goes deeper. For ready-made implementations, [recipes-web.md](recipes-web.md). For award-level scroll choreography, [animation-patterns.md](animation-patterns.md).
+
+## Operating Posture
+
+You are a senior design engineer building the animation yourself. Never present motion options as a menu — make the call, state the reasoning in one line, write the code.
+
+Two failure modes, and the first is worse:
+
+1. **Animating something that shouldn't animate.** The gate below exists to produce zero lines of code sometimes. That's a success, not a dodge.
+2. **Animating the right thing with the wrong ingredients** — `ease-in` on an entrance, `scale(0)`, keyframes on a toast, a duration that makes a dropdown feel sluggish.
+
+## Hard Rules
+
+1. **Run the sequence in order.** Steps 1 and 2 gate everything. Don't reach for a curve before you know whether it animates at all.
+2. **No approximated values.** Every curve, duration, and spring config comes from the tables below. Never invent `cubic-bezier(0.4, 0, 0.2, 1)` because it looks familiar.
+3. **Extend the codebase's tokens, don't fork them.** If `--ease-out` or a duration scale already exists, use it. Adding a parallel system is a defect.
+4. **Reduced motion and hover gating ship with the animation**, not as a follow-up.
+5. **Cheapest tool that works.** Don't install a motion library for a fade.
+
+## The Build Sequence
+
+### 1. Should this animate at all?
+
+| Frequency | Decision |
+| --- | --- |
+| 100+ times/day (keyboard shortcuts, command palette toggle) | **No animation. Ever.** Stop here. |
+| Tens of times/day (hover effects, list navigation) | Near-imperceptible only — fast and subtle, or nothing |
+| Occasional (modals, drawers, toasts) | Standard animation |
+| Rare / first-time (onboarding, success, celebration) | The delight budget lives here |
+
+**Keyboard-initiated actions are a disqualifier, not a judgment call.** Raycast has no open/close animation — that is correct for something opened hundreds of times a day.
+
+If the request fails this gate, say so plainly and don't write the animation. Offer the non-motion alternative (instant state change, a static affordance) instead.
+
+### 2. What is the purpose?
+
+Name it in one of these words before continuing:
+
+- **Feedback** — confirming the interface heard the user
+- **Spatial consistency** — showing where something came from or went
+- **State indication** — making a state change legible
+- **Preventing a jarring change** — bridging content that would otherwise teleport
+- **Explanation** — demonstrating how something works (marketing/onboarding only)
+- **Delight** — allowed *only* at the rare/first-time tier
+
+Can't name it? Don't build it. "It looks cool" on a frequently-seen element is a reason to stop.
+
+Also check **function**: data the user is reading or acting on should not move for style. A decorative mouse-tracking effect belongs on a marketing page, not on a graph in a banking app.
+
+### 3. Pick the tool — cheapest that works
+
+Walk down; stop at the first that fits.
+
+| Need | Tool |
+| --- | --- |
+| Hover, press, color, a state toggle you control with a class or attribute | **CSS transition** |
+| Entry animation on mount, no JS state | **CSS `@starting-style`** |
+| Predetermined motion that must stay smooth while the page is busy loading | **CSS animation** (runs off the main thread) |
+| Motion tied to scroll position, no library | **CSS scroll-driven animation** (`animation-timeline: view()` / `scroll()`), with an `IntersectionObserver` fallback |
+| Page navigation, or one element morphing into another across a state change | **View Transitions API** (`document.startViewTransition`, `view-transition-name`) |
+| Programmatic control with CSS performance, no library | **WAAPI** (`element.animate()`) |
+| Springs, layout animations, exit animations, gesture-driven values | **Motion** (`motion.dev`) |
+
+CSS animations beat JS under load — they run off the main thread, while `requestAnimationFrame`-based animation drops frames while the browser loads, scripts, or paints. Use CSS for predetermined motion, JS for dynamic and interruptible motion.
+
+If the task needs a *component* rather than an animation — a toast, a drawer, a command menu, a dropdown — stop and consult [libraries.md](libraries.md). Hand-rolling those is how you end up with a `<div>` dropdown and no focus management.
+
+### 4. Pick the properties
+
+- **`transform` and `opacity` only.** They skip layout and paint and run on the GPU. `width`/`height`/`margin`/`padding`/`top`/`left` trigger all three. (`clip-path` is the sanctioned fourth — see the recipes. `height` is tolerated only for accordions, where there's no transform equivalent.)
+- **Never `scale(0)`.** Start from `scale(0.9–0.97)` + `opacity: 0`. Nothing in the real world appears from nothing.
+- **`transform-origin` at the trigger** for popovers, dropdowns, menus, tooltips — `var(--transform-origin)` in Base UI. **Modals are exempt**; they're not anchored to a trigger, so they stay centered.
+- **Percentages in `translate()`** are relative to the element's own size — `translateY(100%)` moves by its own height whatever the content. Prefer over hardcoded pixels.
+- **`scale()` scales children too** — the label and icons come along, which is what makes press feedback read as physical. That's a feature.
+- **In Motion, use the full transform string.** `x`/`y`/`scale` shorthands are not hardware-accelerated and drop frames under load:
+
+```jsx
+<motion.div animate={{ x: 100 }} />                          // drops frames under load
+<motion.div animate={{ transform: "translateX(100px)" }} />  // hardware accelerated
+```
+
+- **Never drive a child's transform from a CSS variable on the parent** — it recalculates styles for every child. Set `transform` on the element directly.
+- **`will-change` is a scalpel, not a seasoning.** It permanently promotes a layer; applied broadly it exhausts memory and makes things slower.
+
+### 5. Easing and duration — or a spring
+
+**Easing**, in decision order:
+
+| Situation | Easing |
+| --- | --- |
+| Entering or exiting | `ease-out` |
+| Moving / morphing on screen | `ease-in-out` |
+| Hover / color change | `ease` |
+| Constant motion (marquee, progress) | `linear` |
+| Default | `ease-out` |
+
+**Never `ease-in` on UI.** It starts slow, delaying the exact moment the user is watching. `ease-out` at 200ms *feels* faster than `ease-in` at 200ms.
+
+Built-in CSS easings are too weak. Use these:
+
+```css
+--ease-out: cubic-bezier(0.23, 1, 0.32, 1);        /* strong ease-out for UI */
+--ease-in-out: cubic-bezier(0.77, 0, 0.175, 1);    /* strong ease-in-out for on-screen movement */
+--ease-drawer: cubic-bezier(0.32, 0.72, 0, 1);     /* iOS-like drawer curve (Ionic) */
+```
+
+Need a curve that isn't here? Take it from [easing.dev](https://easing.dev/) or [easings.co](https://easings.co/). Don't hand-roll one. (Award-level marketing work uses stronger expo/quart curves — those live in [animation-patterns.md](animation-patterns.md) and are for immersive pages, not everyday UI.)
+
+**Duration:**
+
+| Element | Duration |
+| --- | --- |
+| Button press feedback | 100–160ms |
+| Tooltips, small popovers | 125–200ms |
+| Dropdowns, selects | 150–250ms |
+| Modals, drawers | 200–500ms |
+| Marketing / explanatory | Can be longer |
+
+**UI animations stay under 300ms.** A 180ms dropdown feels more responsive than a 400ms one. Two rules that modulate the table:
+
+- **Exits are faster than entrances**, usually by about a third. The user has already decided to leave; making them watch is holding a door closed.
+- **Distance changes duration.** The same 200ms feels snappy across 20px and sluggish across 600px. Scale duration with travel, not with importance.
+
+**Perceived performance** is part of the craft: a fast-spinning spinner makes loading feel faster at identical load time; instant tooltips after the first one is open (skip delay + skip animation) make a whole toolbar feel faster. The perception of speed matters as much as actual speed, and `ease-out` amplifies it because the user sees immediate movement.
+
+**Reach for a spring instead** when the motion is drag with momentum, an element that should feel alive, a gesture the user can interrupt or reverse, or decorative mouse-tracking:
+
+```js
+{ type: "spring", duration: 0.5, bounce: 0.2 }            // Apple-style — easier to reason about
+{ type: "spring", mass: 1, stiffness: 100, damping: 10 }  // traditional physics — more control
+```
+
+Keep bounce at 0.1–0.3, and avoid bounce in most UI — reserve it for drag-to-dismiss and playful interactions. Overshoot on a menu that faded in feels wrong; overshoot on a card the user flicked feels right. For mouse-tracking, interpolate through `useSpring` rather than tying the value directly to the pointer — direct coupling feels artificial because it has no momentum. Velocity handoff, momentum projection, and rubber-banding live in [apple-fluid.md](apple-fluid.md).
+
+### 6. Interruption and exit
+
+The most common animation bug is not visual — it is that the animation ignores the user.
+
+- **Transitions, not keyframes, for anything triggered rapidly** — toasts, toggles, anything a user can fire twice in a second. Transitions retarget from the current value; keyframes restart from zero.
+- **Springs for gestures**, because they carry velocity through an interruption.
+- **Reversing mid-flight starts from the current position**, never snap-to-end-then-play-backwards. A menu closed halfway through opening closes from where it is.
+- **Never block input while animating.** A 300ms modal transition that swallows clicks makes fast users feel the interface is broken — and fast users are the ones who use it most.
+- **Never queue.** If state changed three times, animate to the third — do not play three animations in sequence.
+- **Exit the way it entered.** A toast that slides in from the bottom leaves through the bottom. Symmetric paths are what make swipe-to-dismiss feel obvious.
+- **Asymmetric timing where the user is deciding.** Slow on the deliberate phase (a hold-to-confirm press: 2s linear), snappy on the system response (release: 200ms ease-out).
+
+### 7. Reduced motion and pointer gating
+
+Ships with the animation, every time.
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  .element { animation: fade 0.2s ease; } /* keep opacity/color, drop transform-based motion */
+}
+
+@media (hover: hover) and (pointer: fine) {
+  .element:hover { transform: scale(1.05); } /* touch fires false hovers on tap */
+}
+```
+
+```jsx
+const reduce = useReducedMotion();
+const closedX = reduce ? 0 : '-100%';
+```
+
+Motion is an accessibility surface, not a style preference:
+
+- **Reduced motion means fewer and gentler animations, not zero.** Replace a slide with a fade; keep transitions that aid comprehension, remove movement and position changes. Removing all feedback makes state changes invisible — that's a different failure, not a fix.
+- **Nothing critical may depend on motion being seen.** If the only signal that a message sent is an animation, it did not communicate to anyone using a screen reader.
+- **Never animate anything that flashes more than three times a second.** That is a seizure risk, not a style choice.
+- Large moving surfaces and parallax are the nausea triggers — for people with vestibular disorders this is a health issue, not a preference.
+
+## Cohesion — motion has a personality
+
+Match the motion to the component's and the product's mood. Sonner reads as elegant partly because its motion is tuned to the component's personality — slightly slower than typical UI, `ease` rather than `ease-out`. A playful consumer app can be bouncier; a professional dashboard stays crisp and fast. One bouncy component in a crisp app is a defect even when its values are individually correct.
+
+Two places where there is no formula and you tune by eye: the opacity/height balance when items enter or leave a list, and any crossfade between two visible states. For the second, a subtle `filter: blur(2px)` during the transition blends two overlapping states into one perceived transformation — keep it under 20px; heavy blur is expensive, especially in Safari.
+
+## Debugging feel
+
+When an animation is mechanically correct but feels wrong:
+
+- **Slow motion.** Play at 2–5× duration or slow playback in the DevTools Animations panel. Look for: two states visibly overlapping in a crossfade, easing that stops abruptly, a wrong `transform-origin`, coordinated properties out of sync.
+- **Frame by frame.** Step through in the Animations panel — timing drift between coordinated properties is invisible at full speed.
+- **Real devices for gestures.** Connect a phone, hit the dev server by IP, use remote devtools. Simulators hide exactly the jank you're looking for.
+- **Fresh eyes the next day.** Imperfections invisible during development surface later. Budget for it.
+
+## Never Ship
+
+Self-check before you finish. Each of these is an automatic block in review mode ([review-audit.md](review-audit.md)):
+
+| Never | Instead |
+| --- | --- |
+| `transition: all` | Name the exact properties |
+| `transform: scale(0)` entrance | `scale(0.95)` + `opacity: 0` |
+| `ease-in` on a UI element | `ease-out` or a strong custom curve |
+| Built-in `ease-out` on a deliberate animation | `cubic-bezier(0.23, 1, 0.32, 1)` |
+| Animation on a keyboard shortcut or 100+/day action | No animation |
+| UI duration over 300ms with no reason | 150–250ms |
+| `transform-origin: center` on a trigger-anchored popover | `var(--transform-origin)` (modals exempt) |
+| Keyframes on toasts, toggles, rapidly-triggered elements | CSS transitions |
+| Animating `width`/`height`/`margin`/`padding`/`top`/`left` | `transform` / `opacity` |
+| Motion `x`/`y`/`scale` props under load | Full `transform` string |
+| Driving a child's transform via a parent CSS variable | `element.style.transform` directly |
+| Ungated `:hover` motion | `@media (hover: hover) and (pointer: fine)` |
+| Missing `prefers-reduced-motion` | Gentler variant, not zero |
+| Everything entering at once | 30–80ms stagger (decorative — never blocks input) |
+| Symmetric timing on press-and-release / hold interactions | Slow the deliberate phase, snap the response |
+
+## Output
+
+Write the code. Then, in at most a few lines:
+
+- **The gate result** — frequency tier and the named purpose. If something in the request was rejected, say which and why.
+- **The ingredients** — tool, properties, curve, duration or spring config, in one line each.
+- **What to feel-check** — if the result depends on feel you can't judge from code (a crossfade, a spring's bounce, the opacity/height balance in an entering list), say so and point at the check from *Debugging feel* above.
+
+Don't pad this into a report. The code is the deliverable. When the honest answer is "this shouldn't animate," give it — that answer is the reason this doctrine exists.

package/dist/resources/skills/builtin/frontend-design/references/picker.md

@@ -0,0 +1,197 @@
+# The Picker
+
+The picker's appearance is **not a design decision** — it is this spec. Copy the markup, CSS, and wiring below verbatim; the only values that change per run are the variant names and count. It stays identical across every project so it always reads as harness chrome, never as part of the design being judged. Do not restyle it with the project's tokens, fonts, or colors.
+
+It is a floating dark pill, bottom-center. Dark glass works on top of any page — light or dark — which is why it is not theme-aware.
+
+## Markup
+
+The sliding highlight span first, one button per variant, a hairline divider, then the replay button (only when at least one variant has motion to re-trigger):
+
+```html
+<nav class="proto-picker" aria-label="Prototype variants">
+  <span class="proto-picker-highlight" aria-hidden="true"></span>
+  <button class="proto-picker-item" data-active aria-current="true">Quiet</button>
+  <button class="proto-picker-item">Editorial</button>
+  <button class="proto-picker-item">Playful</button>
+  <span class="proto-picker-divider" aria-hidden="true"></span>
+  <button class="proto-picker-item proto-picker-replay" aria-label="Replay animation (R)">↻</button>
+</nav>
+```
+
+In a framework, keep the class names and structure; only the rendering syntax changes.
+
+## Styles
+
+```css
+.proto-picker {
+  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;
+  -webkit-user-select: none;
+}
+
+.proto-picker-highlight {
+  position: absolute;
+  top: 4px;
+  left: 0;
+  height: 28px;
+  border-radius: 999px;
+  background: rgba(255, 255, 255, 0.12);
+  will-change: transform;
+}
+
+/* The slide is enabled only after first paint (data-ready), so load doesn't animate. */
+.proto-picker[data-ready] .proto-picker-highlight {
+  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) {
+  .proto-picker[data-ready] .proto-picker-highlight { transition: none; }
+}
+
+.proto-picker-item {
+  position: relative; /* sits above the highlight */
+  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;
+}
+
+.proto-picker-item:hover {
+  color: rgba(255, 255, 255, 0.85);
+}
+
+.proto-picker-item:active {
+  transform: scale(0.97);
+}
+
+.proto-picker-item:focus-visible {
+  outline: 2px solid rgba(255, 255, 255, 0.4);
+  outline-offset: 2px;
+}
+
+.proto-picker-item[data-active] {
+  color: #fff;
+}
+
+.proto-picker-divider {
+  width: 1px;
+  height: 16px;
+  margin: 0 4px;
+  background: rgba(255, 255, 255, 0.12);
+}
+
+.proto-picker-replay {
+  padding: 0 10px;
+  font-size: 14px;
+}
+
+.proto-picker[data-position="top"] {
+  bottom: auto;
+  top: 24px;
+}
+```
+
+## Rules
+
+- **Verbatim.** These values are the spec. No project fonts, no brand colors, no theme switching, no extra shadows or borders.
+- **The highlight slides; the variant swap stays instant.** The active pill animates between buttons (250ms, strong ease-out) as spatial feedback on the picker itself — but the variant being previewed still switches with no transition. The `width` transition is a deliberate exception to the transform/opacity rule: the element is 28px tall, absolutely positioned, and has no layout dependents, so the paint cost is negligible.
+- **One allowed modification:** if a variant occupies the bottom-center of the screen (a toast stack, a bottom sheet, a dock), set `data-position="top"` so the picker never covers the work. Nothing else about it may move or change.
+- **Replay is conditional.** Render the replay button and its divider only when at least one variant has an entrance or state animation worth re-triggering; a static comparison gets a shorter pill.
+
+## Behavior contract
+
+The contract is fixed regardless of how the harness renders:
+
+- Number keys `1–N` and `←`/`→` switch variants; `R` replays. Ignore key events when focus is in an input, textarea, select, or contenteditable, or when a modifier is held.
+- Clicking an item switches to it; exactly one item carries `data-active` and `aria-current="true"` at all times, and the highlight slides to it.
+- Selection persists across reload via a URL param (`?v=2`), falling back to variant 1. The highlight takes its initial position without animating (`data-ready` is added after first paint).
+- Switching re-mounts the variant (so entrance animations re-run); the replay key re-mounts without switching.
+
+## Reference wiring
+
+Verbatim for the standalone-HTML branch; in a framework, keep the same behavior but express it idiomatically (state instead of `innerHTML`, a keyed re-mount instead of `requestAnimationFrame`, refs + a layout effect for the highlight measurement).
+
+```js
+// `variants` is an array of render functions, one per variant, in picker order.
+const stage = document.getElementById('stage');
+const picker = document.querySelector('.proto-picker');
+const highlight = picker.querySelector('.proto-picker-highlight');
+const items = [...picker.querySelectorAll('.proto-picker-item:not(.proto-picker-replay)')];
+const replay = picker.querySelector('.proto-picker-replay');
+let current = 0;
+
+function moveHighlight() {
+  const el = items[current];
+  highlight.style.width = el.offsetWidth + 'px';
+  highlight.style.transform = `translateX(${el.offsetLeft}px)`;
+}
+
+function mount(i) {
+  stage.innerHTML = '';
+  // Clear first, render next frame, so entrance animations re-run.
+  requestAnimationFrame(() => { stage.innerHTML = variants[i](); });
+}
+
+function setActive(i) {
+  if (i < 0 || i >= variants.length) return;
+  current = i;
+  items.forEach((el, j) => {
+    el.toggleAttribute('data-active', j === i);
+    if (j === i) el.setAttribute('aria-current', 'true');
+    else el.removeAttribute('aria-current');
+  });
+  moveHighlight();
+  const url = new URL(location);
+  url.searchParams.set('v', i + 1);
+  history.replaceState(null, '', url);
+  mount(i);
+}
+
+items.forEach((el, i) => el.addEventListener('click', () => setActive(i)));
+replay?.addEventListener('click', () => mount(current));
+window.addEventListener('resize', moveHighlight);
+
+document.addEventListener('keydown', (e) => {
+  if (/^(INPUT|TEXTAREA|SELECT)$/.test(e.target.tagName) || e.target.isContentEditable) return;
+  if (e.metaKey || e.ctrlKey || e.altKey) return;
+  const num = parseInt(e.key, 10);
+  if (num >= 1 && num <= variants.length) setActive(num - 1);
+  else if (e.key === 'ArrowRight') setActive((current + 1) % variants.length);
+  else if (e.key === 'ArrowLeft') setActive((current - 1 + variants.length) % variants.length);
+  else if (e.key === 'r' || e.key === 'R') mount(current);
+});
+
+setActive((parseInt(new URLSearchParams(location.search).get('v'), 10) || 1) - 1);
+// Enable the slide only after first paint, so load doesn't animate.
+requestAnimationFrame(() => requestAnimationFrame(() => picker.setAttribute('data-ready', '')));
+```

package/dist/resources/skills/builtin/frontend-design/references/plan-template.md

@@ -0,0 +1,73 @@
+# Plan Template
+
+Every plan written in audit mode ([review-audit.md](review-audit.md)) follows this structure. The executor may be a less capable model with zero context and zero taste — the plan must contain everything, exactly. No references to "the audit above" or "the easing we discussed."
+
+```markdown
+# NNN — <Short imperative title>
+
+- **Status**: TODO
+- **Commit**: <output of `git rev-parse --short HEAD` when this plan was written>
+- **Severity**: HIGH | MEDIUM | LOW
+- **Category**: <audit category>
+- **Estimated scope**: <n files, rough size>
+
+## Problem
+
+What is wrong, where, and why it matters to how the product feels. Cite every
+location as `path/to/file.tsx:123` and include the current code verbatim:
+
+​```css
+/* src/components/dropdown.css:14 — current */
+.dropdown { transition: all 400ms ease-in; }
+​```
+
+## Target
+
+The exact end state. Every value spelled out — curves, durations, spring
+configs, media queries. Never "use a nicer easing":
+
+​```css
+/* target */
+.dropdown {
+  transition: transform 200ms var(--ease-out), opacity 200ms var(--ease-out);
+  transform-origin: var(--transform-origin);
+}
+​```
+
+## Repo conventions to follow
+
+How this codebase already does it, with one exemplar the executor should
+imitate (token names, file placement, prop patterns):
+
+- Easing tokens live in `src/styles/tokens.css`; add new curves there, e.g. `--ease-out: cubic-bezier(0.23, 1, 0.32, 1);`
+- <exemplar file:line that already does this correctly>
+
+## Steps
+
+1. <One concrete edit per step: file, what changes, resulting code.>
+2. …
+
+## Boundaries
+
+- Do NOT touch <files/components out of scope>.
+- Do NOT change markup/structure — motion properties only (unless a step says otherwise).
+- Do NOT add new dependencies.
+- If a step doesn't match the code you find (drift since the commit stamp), STOP and report instead of improvising.
+
+## Verification
+
+- **Mechanical**: <exact commands — typecheck, lint, build — with expected outcome>.
+- **Feel check**: run the UI, trigger <interaction>, and confirm:
+  - <observable check, e.g. "the dropdown scales from its trigger, not from center">
+  - <e.g. "spamming the toggle never restarts the animation from zero">
+  - In DevTools, set playback to 10% (Animations panel) and confirm <detail>.
+  - Toggle `prefers-reduced-motion` (Rendering panel) and confirm movement is dropped but opacity feedback remains.
+- **Done when**: <machine- or eye-checkable completion criteria>.
+```
+
+## Notes for the plan author
+
+- One plan per finding. If two findings share every file and the same fix pattern (e.g. the same easing token swap across components), they may merge into one plan.
+- Pull every value from [motion.md](motion.md) — never approximate from memory.
+- The feel check is not optional. Motion can be mechanically correct and still feel wrong; give the executor (or the human reviewing the executor's diff) concrete things to watch for in slow motion.
+- After writing plans, create or update `plans/README.md` with: a table of plans (number, title, severity, status), the recommended execution order, and any dependencies between plans.

package/dist/resources/skills/builtin/frontend-design/references/prototype.md

@@ -0,0 +1,85 @@
+
+# Prototyping Variants
+
+A divergence skill. It does ONE thing: take a described piece of UI ("a toast", "the pricing card", "a hold-to-delete button"), build several genuinely different versions of it, and put them behind a visual picker so the user can flip through them live and choose a winner. It does not review existing UI (that is review mode in [review-audit.md](review-audit.md)), plan fixes for it (audit mode, same file), or choose dependencies (that is [libraries.md](libraries.md)).
+
+## Operating Posture
+
+You are a senior design engineer running a design exploration. The entire value of this skill is **divergence**: three tints of the same idea waste the picker — the user learns nothing by flipping between them. Each variant must be a direction you could defend shipping on its own, exploring a genuinely different answer to the same brief.
+
+Divergence is not an excuse to drop the craft bar. Every variant individually meets Emil Kowalski's standards — right easing (`ease-out` on entrances, never `ease-in`), sub-300ms UI motion, correct `transform-origin`, `transform`/`opacity` only, reduced-motion handled. A sloppy variant doesn't widen the exploration; it just loses on execution and teaches nothing about the direction it represents.
+
+## Hard Rules
+
+1. **Never touch production code during exploration.** Everything lives in an isolated prototype surface (see Phase 4). Integration happens only in Phase 6, only for the variant the user picked.
+2. **Variants diverge on a named axis** — layout, density, personality, motion, interaction model. Before building, you must be able to state each variant's axis in a phrase. Sharing the project's tokens is not convergence; variants *should* feel native to the product.
+3. **Every variant fully works.** Real interactions, real motion, realistic content — actual product-shaped copy, plausible names and numbers. No lorem ipsum, no dead buttons, no "imagine this part".
+4. **The picker is chrome, not a contestant.** Its exact markup, styles, and behavior are specified in [picker.md](picker.md) — copy them verbatim. Its look is not a design decision and never adapts to the project.
+5. **Clean up after the choice.** When a winner is promoted, delete the prototype surface unless the user asks to keep it.
+
+## Workflow
+
+### Phase 1 — Scope
+
+One thing per run. If the description spans multiple components ("the dashboard"), narrow it: pick the single highest-leverage piece, say which and why, and offer the rest as follow-up runs. Restate the brief in one sentence — what the thing is, where it will live, what it must do.
+
+### Phase 2 — Recon
+
+Before designing anything, map the ground the variants must stand on:
+
+- **Stack**: framework, styling system (Tailwind, CSS modules, vanilla), motion library if any.
+- **Tokens**: colors, radii, spacing, fonts, easing/duration variables. Variants use these — every variant should look like it could ship in this product tomorrow.
+- **Personality**: playful consumer app or crisp dashboard? This bounds how far the boldest variant may go.
+- **Context**: where the piece renders — against what background, beside what neighbors, at what sizes.
+
+If there is no project (empty directory, or the user is just exploring), skip to the standalone branch in Phase 4 and choose a restrained default look: neutral grays, one accent, system font stack.
+
+### Phase 3 — Choose directions
+
+Default **3 variants**; up to 5 when the user asks or the design space is genuinely wide. More than 5 dilutes the comparison.
+
+Before writing any code, list the set: a name and an axis for each. Names describe the direction — "Quiet", "Editorial", "Playful", "Dense" — never "Option A/B/C". If two proposed directions would differ only in accent color or copy, they are one direction; replace one with a real alternative (different layout, different interaction model, different motion story).
+
+**Completion criterion:** every variant has a name and a stated axis, and no two variants share an axis position.
+
+### Phase 4 — Build the picker harness
+
+Two branches, by what exists:
+
+- **In a project with a dev server** — an isolated route or page (`/prototypes/<slug>`, or the framework's equivalent), one file per variant plus a small harness file. Nothing imports from the prototype surface into production code.
+- **No project / static context** — a single self-contained HTML file (inline CSS/JS) the user can open directly in a browser.
+
+The picker's markup, styles, keyboard wiring, and placement come from [picker.md](picker.md), verbatim — load it now and build exactly that. Beyond the picker itself, the harness must render **one variant at a time, full size, in realistic surrounding context** — a toast needs a page behind it, a card needs siblings, a button needs a form. Side-by-side thumbnails distort spacing and scale; never judge UI at postage-stamp size. Switching is **instant** — flipping is a 100+/session action; by the frequency rule the variant swap gets no animation.
+
+### Phase 5 — Verify and hand off
+
+Run the harness. Confirm every variant renders, every interaction responds, and the console is clean — flip through all of them yourself before showing the user. If browser tooling is available, screenshot each variant.
+
+Then present the set and **stop — the choice belongs to the user**:
+
+| # | Variant | Axis | When it's the right choice | Its cost |
+| --- | --- | --- | --- | --- |
+| 1 | Quiet | Minimal motion, borders over shadows | The product is a daily-use tool | Least memorable |
+| 2 | Editorial | Large type, generous whitespace | The moment deserves weight | Eats vertical space |
+
+Close with where the picker is running (URL or file path) and the keys to flip.
+
+**Completion criterion:** every variant is reachable from the picker and behaves correctly; no console errors; the table names each variant's tradeoff honestly.
+
+### Phase 6 — Promote on selection
+
+When the user picks: integrate that variant where it belongs, following the project's existing conventions (file layout, naming, token usage), then delete the prototype surface per Hard Rule 5. If the user instead wants another round, keep the harness and run Phase 3 again, diverging *around* the direction they gravitated to.
+
+## Invocation Variants
+
+| Invocation | Behavior |
+| --- | --- |
+| `<description>` | Full workflow: scope → recon → 3 variants → picker → wait for choice |
+| `<description> x5` | Same, with that many variants (capped at 5) |
+| `riff <variant>` | New round: keep the harness, generate a fresh set diverging around the named variant's direction |
+| `keep <variant>` | Promote that variant into the codebase and delete the prototype surface |
+| `keep <variant>, leave the picker` | Promote, but keep the prototype surface around |
+
+## Tone
+
+Sell each variant honestly — one line on when it wins, one on what it costs. Never pre-pick a favorite in the table; if the user asks which you'd choose, answer with a reason rooted in the product's personality and frequency of use, not aesthetics alone. If two variants converged while you built them, cut one and say so: a picker with two truly distinct directions beats one padded to three.