wizz-method 1.3.2 → 1.4.1

package/src/skills-lib/design-motion-principles/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: design-motion-principles
+description: "Motion and interaction design expert based on Emil Kowalski, Jakub Krehel, and Jhey Tompkins' techniques. Two modes — build interactive components with purposeful motion, or audit existing animations to catch AI-slop motion patterns (audit emits a branded HTML report with looping demos). Use when creating, adding, animating, or reviewing UI motion: transitions, hover states, micro-interactions, enter/exit animations, or any motion design work in React, Framer Motion, CSS, or HTML. Provides per-designer perspectives with context-aware weighting."
+---
+
+# Design Motion Principles
+
+You are a senior design engineer specializing in motion and interaction design. This skill operates in two modes:
+
+- **Create** — Build interactive components with purposeful motion → `workflows/create.md`
+- **Audit** — Review existing motion design and report findings → `workflows/audit.md`
+
+**Scope**: Web and app UI motion — HTML/CSS, React, Framer Motion / Motion, iOS/Android transitions, design system animations. The frequency framework still applies to other motion work (game engines, Lottie, Rive, video), but designer-specific techniques may not translate.
+
+---
+
+## STEP 0: Detect Mode (DO THIS FIRST)
+
+| Signal in the request | Mode |
+|-----------------------|------|
+| "build", "create", "add animation", "animate this", "implement", "make it feel…" | **Create** |
+| "audit", "review", "evaluate", "check", "feedback on", "is this motion good" | **Audit** |
+| Ambiguous (e.g. "look at this modal animation") | Ask the user |
+
+For ambiguous requests, if `AskUserQuestion` is available, present:
+- **Create** — Build or improve the component's motion
+- **Audit** — Review existing motion and report findings
+
+Otherwise ask in plain text: "Should I build/improve the motion (Create mode), or review existing motion and report findings (Audit mode)?"
+
+**Once the mode is known, read the matching workflow file and follow it exactly.**
+
+---
+
+## The Three Designers
+
+- **Emil Kowalski** (Linear, ex-Vercel) — Restraint, speed, purposeful motion. Best for productivity tools.
+- **Jakub Krehel** (jakub.kr) — Subtle production polish, professional refinement. Best for shipped consumer apps.
+- **Jhey Tompkins** (@jh3yy) — Playful experimentation, CSS innovation. Best for creative sites, kids apps, portfolios.
+
+> These three lenses distill each designer's *publicly published* work — courses, articles, talks, and open-source projects. The weighting framework and the "lens" framing are this skill's interpretation of their principles, named in tribute; they are not authored or endorsed by the designers themselves.
+
+Each designer answers a different question:
+- **Emil** — *"Should this animate at all?"*
+- **Jakub** — *"Is this subtle and polished enough for production?"*
+- **Jhey** — *"What could this become?"*
+
+**Critical insight**: These perspectives are context-dependent, not universal rules. A kids' app should prioritize Jakub + Jhey (polish + delight), not Emil's productivity-focused speed rules. Both modes weight the designers by project context before doing anything.
+
+---
+
+## Context-to-Perspective Mapping
+
+| Project Type | Primary | Secondary | Selective |
+|--------------|---------|-----------|-----------|
+| Productivity tool (Linear, Raycast) | Emil | Jakub | Jhey (onboarding only) |
+| Kids app / Educational | Jakub | Jhey | Emil (high-freq game interactions) |
+| Creative portfolio | Jakub | Jhey | Emil (high-freq interactions) |
+| Marketing/landing page | Jakub | Jhey | Emil (forms, nav) |
+| SaaS dashboard | Emil | Jakub | Jhey (empty states) |
+| Mobile app | Jakub | Emil | Jhey (delighters) |
+| E-commerce | Jakub | Emil | Jhey (product showcase) |
+
+---
+
+## Core Principles (Both Modes)
+
+### The Frequency Gate
+
+Before adding or approving any animation, ask how often the user triggers it:
+
+| Frequency | Recommendation |
+|-----------|----------------|
+| Rare (monthly) | Delightful, expressive motion welcome |
+| Occasional (daily) | Subtle, fast motion |
+| Frequent (100s/day) | No animation or instant transition |
+| Keyboard-initiated | Never animate |
+
+### Duration Guidelines (Context-Dependent)
+
+| Context | Guideline |
+|---------|-----------|
+| Productivity UI (Emil) | Under 300ms — 180ms ideal |
+| Production polish (Jakub) | 200-500ms for smoothness |
+| Creative/kids/playful (Jhey) | Whatever serves the effect |
+
+**Do not universally flag or cap durations.** Check the context weighting first.
+
+### The Golden Rule
+
+> "The best animation is that which goes unnoticed."
+
+If users comment "nice animation!" on every interaction, it's probably too prominent for production. (Exception: kids apps and playful contexts where delight IS the goal.)
+
+### Accessibility is NOT Optional
+
+Every animation — generated in Create mode or reviewed in Audit mode — must handle `prefers-reduced-motion`. No exceptions. See `references/accessibility.md`.
+
+---
+
+## Reference Index
+
+| File | Contents | Load When |
+|------|----------|-----------|
+| [Motion Cookbook](references/motion-cookbook.md) | All motion recipes — enter/exit, easing, springs, clip-path, @property, FLIP, scroll-driven | Create mode (always); Audit mode for implementation recommendations |
+| [Creation Gotchas](references/creation-gotchas.md) | Claude's failure modes when writing motion | Create mode (always) |
+| [Audit Checklist](references/audit-checklist.md) | Systematic audit checklist | Audit mode (always) |
+| [Anti-Checklist](references/anti-checklist.md) | Quality gate — AI-slop motion categories + anti-patterns to flag | Audit mode (always) |
+| [Emil Kowalski](references/emil-kowalski.md) | Restraint philosophy, frequency rule, decision frameworks | Either mode, if Emil is weighted |
+| [Jakub Krehel](references/jakub-krehel.md) | Production polish philosophy and decision frameworks | Either mode, if Jakub is weighted |
+| [Jhey Tompkins](references/jhey-tompkins.md) | Playful experimentation philosophy and frameworks | Either mode, if Jhey is weighted |
+| [Accessibility](references/accessibility.md) | prefers-reduced-motion, vestibular safety | Both modes (mandatory) |
+| [Performance](references/performance.md) | GPU optimization, will-change, layout thrash | Either mode, for complex animations |
+| [Output Format](references/output-format.md) | Audit report template — HTML mode (default) + terminal mode (flag) | Audit mode only |
+| [Demo Shell](references/demo-shell.html) | Visual container template for per-finding demo cards in the HTML report | Audit mode, HTML output |
+
+## Workflow Index
+
+| Workflow | Purpose |
+|----------|---------|
+| [Create](workflows/create.md) | Build interactive components with purposeful motion |
+| [Audit](workflows/audit.md) | Review existing motion design, produce a per-designer report |

package/src/skills-lib/design-motion-principles/references/accessibility.md

@@ -0,0 +1,52 @@
+# Accessibility
+
+**This is not optional.** Motion can cause discomfort, nausea, or distraction for many users.
+
+---
+
+## Respect User Preferences
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  *,
+  *::before,
+  *::after {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+    scroll-behavior: auto !important;
+  }
+}
+```
+
+**What this does**: Effectively disables animations while preserving final states (so layouts don't break).
+
+---
+
+## Functional vs. Decorative Motion
+
+| Type | Purpose | Reduced Motion Behavior |
+|------|---------|------------------------|
+| **Functional** | Indicates state changes, spatial relationships, orientation | May need alternative (instant state change, no transition) |
+| **Decorative** | Pure delight, visual interest | Can be fully removed |
+
+**The test**: Does removing this animation break the user's ability to understand what happened? If yes, it's functional.
+
+---
+
+## Motion Sensitivity Considerations
+
+- Avoid large-scale motion (full-screen transitions, parallax)
+- Avoid continuous or looping animations that can't be paused
+- Provide pause controls for any ambient animation
+- Be especially careful with vestibular triggers: zooming, spinning, parallax
+
+---
+
+## Implementation Checklist
+
+- [ ] Tested with `prefers-reduced-motion: reduce` enabled
+- [ ] No vestibular triggers (excessive zoom, spin, parallax)
+- [ ] Looping animations can be paused
+- [ ] Functional animations have non-motion alternatives
+- [ ] Users can complete all tasks with animations disabled

package/src/skills-lib/design-motion-principles/references/anti-checklist.md

@@ -0,0 +1,274 @@
+# Anti-Checklist
+
+This file is the audit's quality gate. The categories below describe motion patterns to **flag** in audited code — AI-slop tells at the top (where most 2026 motion problems live), followed by perspective-specific anti-patterns from Emil, Jakub, and Jhey, then general motion mistakes and code-shaped red flags. When audited code matches a pattern here, the audit surfaces a finding and the agent generates a per-finding motion suggestion by reading the relevant philosophy reference (`emil-kowalski.md`, `jakub-krehel.md`, `jhey-tompkins.md`).
+
+The file frames patterns as "things to flag," not "mistakes to avoid" — language that makes the audit's adversarial posture explicit.
+
+---
+
+## AI-Slop Motion Patterns
+
+These are the recognizable motion fingerprints of AI-generated UIs in 2026. They're not always wrong in isolation — what makes them slop is *frequency* and *uniformity*. Finding one instance is normal polish; finding the same pattern slapped across the codebase is the tell. Each category includes a flagging heuristic below the definition so the audit isn't tripped by single intentional uses.
+
+---
+
+### Pulsing indicators
+
+Glowing dots, breathing CTAs, throbbing rings, "live"/"online"/"recording"/"AI active" pulse animations, dark-mode pulse glows — any looped scale/opacity pulse used to draw attention to a status element.
+
+**Flag when you see:**
+- `@keyframes` rules with names containing `pulse`, `glow`, `breathe`, `throb`
+- `animation: ... infinite` on small UI elements (dots, badges, status indicators)
+- `box-shadow` or `opacity` loops on status icons
+- Tailwind `animate-pulse` on indicator dots or active-state elements
+
+**Heuristic:** Flag *any* instance. Pulsing indicators are almost always slop — the only exception is a single brand element with explicit design rationale stated in code comments or design docs.
+
+**Fix lens:** Emil — purposeful restraint. See `references/emil-kowalski.md`.
+
+---
+
+### Blur-everywhere entrances
+
+`filter: blur(Npx)` applied to every entering element on mount — sections, cards, images, paragraphs. Jakub's enter recipe (`opacity + translateY + blur`) is excellent in moderation; AI-slop versions apply it uniformly across the page.
+
+**Flag when you see:**
+- `initial={{ filter: 'blur(Npx)' }}` or `from { filter: blur(Npx); }` on multiple distinct components in the same view
+- Identical blur values (e.g., `blur(4px)`) repeated across components without context distinction
+- Blur on text-bearing entrances (headings, paragraphs) where it impairs first-paint readability
+
+**Heuristic:** Flag when ≥3 distinct components in the same view share the same `filter: blur()` enter pattern. Single uses with intent (a hero element, a modal) are fine.
+
+**Fix lens:** Jakub — production polish, but selective. See `references/jakub-krehel.md`.
+
+---
+
+### Hover-scale-on-everything
+
+`transform: scale(1.0X)` on `:hover` applied to every card, button, and image without intent. The micro-bounce-on-hover feels polished in moderation; AI-slop versions slap it on indiscriminately.
+
+**Flag when you see:**
+- `transition` rules with `transform: scale(1.0X)` on `:hover` across multiple card/button/image components
+- Identical scale values (e.g., `scale(1.05)`) repeated across selectors with no discriminating context
+- Tailwind `hover:scale-105` applied to grids of repeated items
+
+**Heuristic:** Flag when ≥3 distinct components share the same `transform: scale(1.0X)` on `:hover` with no other discriminating selector context. Single intentional uses (e.g., a primary CTA) are fine.
+
+**Fix lens:** Emil for utility-shaped elements (none); Jakub for product-shaped elements (selective). See `references/emil-kowalski.md` and `references/jakub-krehel.md`.
+
+---
+
+### Stagger-spam-on-every-list
+
+`stagger`, `staggerChildren`, or hand-rolled `animation-delay: calc(var(--i) * 50ms)` patterns applied to every list, grid, or repeated-element block. Jhey-style stagger on a deliberate moment is delightful; AI-slop spreads it across every list as default polish.
+
+**Flag when you see:**
+- `staggerChildren` in framer-motion `variants` across multiple list components
+- `animation-delay: calc(...)` with item-index multipliers across multiple components
+- Sequential delays applied to lists that don't read as a moment (search results, settings options, table rows)
+
+**Heuristic:** Flag when ≥2 lists in the same view use stagger entrance. One intentional moment is fine; two or more is the tell.
+
+**Fix lens:** Emil for utility lists (no stagger); Jhey for delight moments (selective). See `references/emil-kowalski.md` and `references/jhey-tompkins.md`.
+
+---
+
+### Bouncy-springs-on-utility-actions
+
+`type: 'spring'` with bounce on dropdown opens, toggle switches, menu reveals, modal entrances — utility actions where bounce reads as "playful" but the action itself is productivity-oriented.
+
+**Flag when you see:**
+- `transition={{ type: 'spring', bounce: > 0 }}` on dropdowns, popovers, menus, toggles, modal opens, settings panels
+- CSS `cubic-bezier(...)` with overshoot values on utility elements
+- Identical spring configs across utility components
+
+**Heuristic:** Flag *any* spring with bounce > 0 on a utility action (dropdown, menu, toggle, modal, settings panel). Bounce belongs on playful elements — celebration moments, kids apps, intentional delight — not productivity UI.
+
+**Fix lens:** Emil — speed and purpose. See `references/emil-kowalski.md`.
+
+---
+
+### Uniform-fade-in-on-every-element
+
+Identical `opacity + translateY` (with or without blur) enter animations applied to every section, card, paragraph, and heading. The "polished entrance" treatment from Jakub used uniformly across the page, regardless of element type or context.
+
+**Flag when you see:**
+- Multiple components sharing identical `initial`/`animate` opacity+translateY values
+- `whileInView` with identical viewport options applied to every block on a page
+- CSS keyframes with generic names (`fadeInUp`, `enter`, `reveal`) attached to many selectors
+
+**Heuristic:** Flag when ≥4 distinct components share identical enter animations (same opacity, same translateY, same duration, same easing). Three is acceptable polish baseline; four is uniformity slop.
+
+**Fix lens:** Jakub — selective polish with hierarchy. See `references/jakub-krehel.md`.
+
+---
+
+### Motion-on-mount-for-static-content
+
+Entrance animations on headings, body paragraphs, navigation links, and other content that should appear instantly. The "fade in everything" pattern that delays reading and makes the page feel sluggish.
+
+**Flag when you see:**
+- `initial`/`animate` on `<h1>`, `<h2>`, `<p>`, `<nav>` elements
+- `whileInView` on body copy (paragraphs, articles, prose)
+- `animation` rules on text-only components without functional reason
+
+**Heuristic:** Flag any motion on a text-only or navigation element when the motion's only purpose is the entrance itself. Carousels, sliders, and hero animations are fine when the motion serves a function (orientation, narrative pacing, attention direction).
+
+**Fix lens:** Emil — animations should serve a purpose, not announce themselves. See `references/emil-kowalski.md`.
+
+---
+
+## From Emil's Perspective (Purposeful Restraint)
+
+- **Animating high-frequency interactions** — If users trigger this 100s of times daily, remove the animation
+- **Animating keyboard-initiated actions** — Keyboard shortcuts should NEVER animate
+- **Animations over 300ms** — UI animations should be under 300ms; 180ms feels more responsive than 400ms
+- **Animating from scale(0)** — Start from `scale(0.9)` or higher for natural motion
+- **Same tooltip behavior everywhere** — First tooltip: delayed + animated. Subsequent: instant
+- **Using default CSS easing** — Built-in `ease` and `ease-in-out` lack strength; use custom curves
+- **Ignoring transform-origin** — Dropdowns should expand from their trigger, not center
+- **Expecting delight in productivity tools** — Users of high-frequency tools prioritize speed over delight
+- **Using keyframes for interruptible animations** — Keyframes can't retarget mid-flight; use CSS transitions with state
+- **CSS variables for frequent updates** — Causes expensive style recalculation; update styles directly on element
+- **Distance thresholds for dismissal** — Use velocity (distance/time) instead; fast short gestures should work
+- **Abrupt boundary stops** — Use damping; things slow down before stopping in real life
+
+---
+
+## From Jakub's Perspective (Production Polish)
+
+- **Making enter and exit animations equally prominent** — Exits should be subtler
+- **Using solid borders when shadows would adapt better** — Especially on varied backgrounds
+- **Forgetting optical alignment** — Buttons with icons, play buttons, asymmetric shapes
+- **Over-animating** — If users notice the animation itself, it's too much
+- **Using the same animation everywhere** — Context should drive timing and easing choices
+- **Ignoring hover state transitions** — Even small transitions (150-200ms) feel more polished than instant changes
+
+---
+
+## From Jhey's Perspective (Creative Learning)
+
+- **Filtering ideas based on "usefulness" too early** — Make first, judge later
+- **Not documenting random creative sparks** — Keep notebooks everywhere, including by your bed
+- **Thinking CSS art is useless** — It teaches real skills (clip-path, layering, complex shapes)
+- **Focusing on "How do I learn X?" instead of "How do I make Y?"** — Let ideas drive learning
+- **Following tutorials without experimenting** — Tutorials teach techniques; experimentation teaches problem-solving
+- **Giving up when something doesn't work** — The struggle is where learning happens
+
+---
+
+## General Motion Design Mistakes
+
+- **Animating layout-triggering properties** (width, height, top, left) — Use transform instead
+- **No animation at all** — Instant state changes feel broken to modern users
+- **Same duration for all animations** — Smaller elements should animate faster
+- **Forgetting `prefers-reduced-motion`** — Not optional
+
+*Note: Duration is designer-dependent. Emil prefers under 300ms for productivity tools. Jakub and Jhey may use longer durations when polish or effect warrants it.*
+
+---
+
+## Red Flags in Code Review
+
+Watch for these patterns:
+
+```jsx
+// BAD: Animating layout properties
+animate={{ width: 200, height: 100 }}
+
+// GOOD: Use transform
+animate={{ scale: 1.2 }}
+```
+
+```jsx
+// BAD: Same animation for enter and exit
+initial={{ opacity: 0, y: 20 }}
+exit={{ opacity: 0, y: 20 }}
+
+// GOOD: Subtler exit
+initial={{ opacity: 0, y: 20 }}
+exit={{ opacity: 0, y: -8 }}
+```
+
+```css
+/* BAD: No reduced motion support */
+.animated { animation: bounce 1s infinite; }
+
+/* GOOD: Respects user preference */
+@media (prefers-reduced-motion: no-preference) {
+  .animated { animation: bounce 1s infinite; }
+}
+```
+
+```css
+/* BAD: will-change everywhere */
+* { will-change: transform; }
+
+/* GOOD: Targeted will-change */
+.animated-button { will-change: transform, opacity; }
+```
+
+```jsx
+// BAD: Animating from scale(0) (Emil)
+initial={{ scale: 0 }}
+animate={{ scale: 1 }}
+
+// GOOD: Start from higher scale
+initial={{ scale: 0.9, opacity: 0 }}
+animate={{ scale: 1, opacity: 1 }}
+```
+
+```jsx
+// Per Emil: Too slow for productivity UI
+transition={{ duration: 0.4 }}
+
+// Per Emil: Fast, snappy (but Jakub/Jhey might use 0.4 for polish)
+transition={{ duration: 0.18 }}
+```
+
+```css
+/* BAD: Dropdown expanding from center (Emil) */
+.dropdown {
+  transform-origin: center;
+}
+
+/* GOOD: Origin-aware animation */
+.dropdown {
+  transform-origin: top center;
+}
+```
+
+```css
+/* BAD: Keyframes can't be interrupted (Emil) */
+@keyframes slideIn {
+  from { transform: translateY(100%); }
+  to { transform: translateY(0); }
+}
+.toast { animation: slideIn 400ms ease; }
+
+/* GOOD: Transitions can retarget mid-flight */
+.toast {
+  transform: translateY(100%);
+  transition: transform 400ms ease;
+}
+.toast.mounted {
+  transform: translateY(0);
+}
+```
+
+```javascript
+// BAD: CSS variables cause cascade recalc (Emil)
+element.style.setProperty('--drag-y', `${y}px`);
+
+// GOOD: Direct style update
+element.style.transform = `translateY(${y}px)`;
+```
+
+```javascript
+// BAD: Distance threshold for dismissal (Emil)
+if (dragDistance > 100) dismiss();
+
+// GOOD: Velocity-based (fast short gestures work)
+const velocity = dragDistance / elapsedTime;
+if (velocity > 0.11) dismiss();
+```

package/src/skills-lib/design-motion-principles/references/audit-checklist.md

@@ -0,0 +1,137 @@
+# Audit Checklist
+
+Use this checklist when reviewing motion design in any UI code.
+
+---
+
+## Philosophy Check (Do First)
+
+- [ ] **How often will users trigger this?** (Frequent = less/no animation — Emil's rule)
+- [ ] **Is this keyboard-initiated?** (If yes, don't animate — Emil's rule)
+- [ ] **Does this animation serve a purpose?** (orientation, feedback, continuity—not just decoration)
+- [ ] **Will users notice this animation consciously?** (If yes for production UI, probably too much)
+- [ ] **Have I tested this with `prefers-reduced-motion: reduce`?**
+- [ ] **Does this feel natural after the 10th interaction?** (Test repeatedly, not just once)
+- [ ] **Is the easing appropriate for my brand/context?**
+- [ ] **Is the duration appropriate for context?** (Emil prefers under 300ms; Jakub/Jhey may use longer for polish or effect)
+
+---
+
+## Motion Gap Analysis (Check BEFORE Reviewing Existing Animations)
+
+Conditional UI changes that **lack** animation are often worse than poorly-tuned animations:
+
+- [ ] **Searched for conditional renders** — `{condition && <Component />}` patterns
+- [ ] **Searched for ternary swaps** — `{condition ? <A /> : <B />}` patterns
+- [ ] **Searched for dynamic inline styles** — `style={{ prop: dynamicValue }}` without transition
+- [ ] **Each conditional render** either has AnimatePresence wrapper OR doesn't need animation (static content)
+- [ ] **Mode switches** (tabs, toggles) animate their content changes, not just the switch itself
+- [ ] **Settings panels** with conditional controls have enter/exit animations
+- [ ] **Expandable sections** animate height, not just show/hide
+- [ ] **Loading → Content** transitions are smooth, not instant swaps
+
+---
+
+## Enter/Exit States
+
+- [ ] Enter animations combine opacity + translateY + blur
+- [ ] Exit animations are subtler than enters (smaller translateY, same blur/opacity)
+- [ ] `animation-fill-mode: backwards` used for delayed sequences
+- [ ] Elements don't flash before their delayed animation starts
+
+---
+
+## Easing & Timing
+
+- [ ] Appropriate easing for context (not default `ease` everywhere)
+- [ ] Custom Bézier curves used instead of built-in easing (Emil's rule)
+- [ ] Spring animations for interactive elements
+- [ ] Durations appropriate for context (Emil: under 300ms; others: whatever serves the design)
+- [ ] Consistent timing values across related animations
+- [ ] Transform-origin matches interaction source (dropdowns from trigger)
+
+---
+
+## Visual Polish
+
+- [ ] Shadows instead of borders where background varies
+- [ ] Gradients using oklch color space for smooth blending
+- [ ] Blur used intentionally as a state signal
+
+---
+
+## Optical Alignment
+
+- [ ] Buttons with icons have adjusted padding
+- [ ] Asymmetric icons (play, arrows) are visually centered
+- [ ] Text and icons feel balanced
+
+---
+
+## State Transitions
+
+- [ ] Icon swaps are animated (opacity, scale, blur)
+- [ ] Loading states have smooth transitions
+- [ ] Hover states have transitions (150-200ms minimum)
+- [ ] Button press has scale feedback (`scale(0.97)` on `:active`)
+- [ ] Elements don't animate from `scale(0)` (use `0.9+` instead)
+
+---
+
+## Interaction Patterns (Emil's Rules)
+
+- [ ] Tooltips: first delayed + animated, subsequent instant
+- [ ] Animations are interruptible (can change mid-animation)
+- [ ] Clip-path used for reveals instead of width/height
+- [ ] High-frequency actions have minimal or no animation
+- [ ] Keyboard shortcuts don't animate
+
+---
+
+## Performance
+
+- [ ] `will-change` used sparingly and specifically
+- [ ] Animations use transform/opacity (not layout properties)
+- [ ] Tested on low-end devices
+- [ ] No continuous animations without purpose
+- [ ] CSS transitions (not keyframes) for interruptible animations (Emil)
+- [ ] Direct style updates for drag operations (not CSS variables) (Emil)
+- [ ] Velocity-based thresholds (not distance) for swipe dismiss (Emil)
+
+---
+
+## Accessibility
+
+- [ ] Respects `prefers-reduced-motion`
+- [ ] No vestibular triggers (excessive zoom, spin, parallax)
+- [ ] Looping animations can be paused
+- [ ] Functional animations have non-motion alternatives
+
+---
+
+## Quick Reference: Severity Levels
+
+**Critical (Must Fix)**:
+- Missing `prefers-reduced-motion` support
+- Animating layout properties (width, height, top, left)
+- No exit animations (elements just disappear)
+- **Motion gaps in primary UI** — Conditional controls/panels that snap in/out without animation
+- Animating keyboard-initiated actions (Emil)
+- Animations on high-frequency actions (100s/day)
+
+**Important (Should Fix)**:
+- Exit animations as prominent as enter animations
+- Missing blur in enter animations
+- Animating from `scale(0)` instead of `0.9+` (Emil)
+- Default CSS easing instead of custom curves (Emil)
+- Wrong transform-origin on dropdowns/popovers (Emil)
+
+**Context-Dependent (Check Against Designer Perspective)**:
+- Durations over 300ms (Emil flags this; Jakub/Jhey may approve for polish)
+
+**Nice to Have**:
+- Optical alignment refinements
+- oklch color space for gradients
+- Spring animations instead of ease
+- Button scale feedback on press
+- Tooltip delay pattern (first delayed, subsequent instant)

package/src/skills-lib/design-motion-principles/references/creation-gotchas.md

@@ -0,0 +1,36 @@
+# Creation Gotchas
+
+Where Claude typically fails when **writing** motion (as opposed to auditing it). Self-check generated code against every item before presenting.
+
+---
+
+## Motion that shouldn't exist
+
+- **Don't animate just because you can.** Decorative motion added "for polish" is the default failure mode. Every animation needs a purpose — feedback, orientation, or continuity. If you can't name the purpose, remove it.
+- **Don't animate high-frequency interactions.** If the user triggers it dozens of times a session, motion becomes friction. Instant is correct.
+- **Don't animate keyboard-initiated actions.** Keyboard shortcuts should never animate — the user wants speed, not a show.
+- **Don't add looping attention-seeking motion.** No pulsing dots, glowing status rings, breathing CTAs, throbbing indicators, or any looped scale/opacity pulse to draw the eye. They age badly, harm accessibility, and rarely serve the user. Use a static treatment unless the user explicitly asks for a pulse.
+
+## Wrong defaults
+
+- **Don't start from `scale(0)`.** It produces unnatural motion. Start from `scale(0.9)` or higher.
+- **Don't use bare `ease` or `ease-in-out`.** Built-in curves lack strength. Use a custom `cubic-bezier` or a spring.
+- **Don't give enter and exit equal weight.** Exits should be subtler — smaller translate, the user's attention is already moving on.
+- **Don't use one duration for everything.** Smaller elements animate faster. Match duration to element size and context.
+- **Don't ignore `transform-origin`.** Dropdowns, popovers, and tooltips should expand from their trigger, not from center.
+
+## Performance failures
+
+- **Don't animate layout properties.** `width`, `height`, `top`, `left`, `margin`, `padding` trigger reflow. Use `transform` and `opacity`.
+- **Don't sprinkle `will-change` everywhere.** It's a targeted hint for elements about to animate, not a global fix.
+- **Don't use keyframes for interruptible animations.** Keyframes can't retarget mid-flight. Use state-driven CSS transitions for anything the user can re-trigger rapidly.
+
+## Accessibility omissions
+
+- **Don't ship motion without `prefers-reduced-motion`.** Every animation you generate needs a reduced-motion path. This is not optional and not a follow-up — include it in the same code.
+- **Don't use vestibular triggers casually.** Large-scale zoom, spin, and parallax can cause genuine discomfort. Avoid unless the design explicitly calls for it, and gate them behind reduced-motion.
+
+## Context blindness
+
+- **Don't apply one designer's rules universally.** Emil's sub-300ms restraint is wrong for a kids' app; Jhey's elastic playfulness is wrong for a banking dashboard. Confirm the weighting before generating.
+- **Don't ignore the existing codebase.** If the project already animates with 500ms springs, a new 150ms ease-out component will feel foreign. Match established conventions unless they are the thing being fixed.