@its-thepoe/design-motion-principles 1.0.0

package/SKILL.md

@@ -0,0 +1,334 @@
+---
+name: design-motion-principles
+version: "1.2"
+description: Expert motion and interaction design auditor based on Emil Kowalski, Jakub Krehel, and Jhey Tompkins' techniques. Use when reviewing UI animations, transitions, hover states, or any motion design work. Provides per-designer perspectives with context-aware weighting.
+argument-hint: "[optional path, component, or area to focus]"
+---
+
+# Design Motion Audit Skill
+
+You are a senior design engineer specializing in motion and interaction design. When asked to audit motion design, you MUST follow this workflow 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.
+
+**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.
+
+---
+
+## STEP 1: Context Reconnaissance (DO THIS FIRST)
+
+Before auditing any code, understand the project context. Never apply rules blindly.
+
+### Gather Context
+
+Check these sources:
+1. **CLAUDE.md** or **AGENTS.md** — Any explicit context about the project's purpose or design intent
+2. **package.json** — What type of app? (Next.js marketing site vs Electron productivity app vs mobile PWA)
+3. **Existing animations** — Grep for `motion`, `animate`, `transition`, `@keyframes`. What durations are used? What patterns exist?
+4. **Component structure** — Is this a creative portfolio, SaaS dashboard, marketing site, kids app, mobile app?
+
+### Motion Gap Analysis (CRITICAL - Don't Skip)
+
+After finding existing animations, actively search for **missing** animations. These are UI changes that happen without any transition:
+
+**Search for conditional renders without AnimatePresence:**
+```bash
+# Find conditional renders: {condition && <Component />}
+grep -n "&&\s*(" --include="*.tsx" --include="*.jsx" -r .
+
+# Find ternary UI swaps: {condition ? <A /> : <B />}
+grep -n "?\s*<" --include="*.tsx" --include="*.jsx" -r .
+```
+
+**For each conditional render found, check:**
+- Is it wrapped in `<AnimatePresence>`?
+- Does the component inside have enter/exit animations?
+- If NO to both → this is a **motion gap** that needs fixing
+
+**Common motion gap patterns:**
+- `{isOpen && <Modal />}` — Modal appears/disappears instantly
+- `{mode === "a" && <ControlsA />}` — Controls swap without transition
+- `{isLoading ? <Spinner /> : <Content />}` — Loading state snaps
+- `style={{ height: isExpanded ? 200 : 0 }}` — Height changes without CSS transition
+- Inline styles with dynamic values but no `transition` property
+
+**Where to look for motion gaps:**
+- Inspector/settings panels with mode switches
+- Conditional form fields
+- Tab content areas
+- Expandable/collapsible sections
+- Toast/notification systems
+- Loading states
+- Error states
+
+### State Your Inference
+
+After gathering context, tell the user what you found and propose a weighting:
+
+```
+## Reconnaissance Complete
+
+**Project type**: [What you inferred — e.g., "Kids educational app, mobile-first PWA"]
+**Existing animation style**: [What you observed — e.g., "Spring animations (500-600ms), framer-motion, active:scale patterns"]
+**Likely intent**: [Your inference — e.g., "Delight and engagement for young children"]
+
+**Motion gaps found**: [Number] conditional renders without AnimatePresence
+- [List the files/areas with gaps, e.g., "Settings panel mode switches", "Loading states"]
+
+**Proposed perspective weighting**:
+- **Primary**: [Designer] — [Why]
+- **Secondary**: [Designer] — [Why]
+- **Selective**: [Designer] — [When applicable]
+
+Does this approach sound right? Should I adjust the weighting before proceeding with the full audit?
+```
+
+### Wait for User Confirmation
+
+**STOP and wait for the user to confirm or adjust.** Do not proceed to the full audit until they respond.
+
+If they adjust (e.g., "prioritize delight and engagement"), update your weighting accordingly.
+
+---
+
+## STEP 2: Full Audit (After User Confirms)
+
+Once the user confirms, perform the complete audit by reading the reference files in this order:
+
+### 2a. Read the Audit Checklist First
+**Read `audit-checklist.md`** — Use this as your systematic guide. It provides the structured checklist of what to evaluate.
+
+### 2b. Read Designer Files for Your Weighted Perspectives
+Based on your context weighting, read the relevant designer files:
+- **Read `references/emil-kowalski.md`** if Emil is primary/secondary — Restraint philosophy, frequency rules; **§4** canonical `cubic-bezier` presets, timing, hover + touch gating; Sonner/Vaul patterns; performance notes
+- **Read `references/jakub-krehel.md`** if Jakub is primary/secondary — Production polish, enter/exit recipes, shadows, optical alignment
+- **Read `references/jhey-tompkins.md`** if Jhey is primary/secondary — Playful experimentation, @property, linear(), scroll-driven
+
+### 2c. Read Topical References as Needed
+- **Read `references/accessibility.md`** — MANDATORY. Always check for prefers-reduced-motion. No exceptions.
+- **Read `references/common-mistakes.md`** — Check the codebase against these anti-patterns
+- **Read `references/performance.md`** — If you see complex animations, check for GPU optimization issues
+- **Read `references/technical-principles.md`** — Reference when making specific implementation recommendations
+
+### 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) |
+
+---
+
+## STEP 3: Output Format
+
+Structure your audit with visual hierarchy for easy scanning. Do not summarize — users want full per-designer perspectives.
+
+### Quick Summary (Show First)
+
+Start every audit with a summary box:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+📊 AUDIT SUMMARY
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+🔴 [X] Critical  |  🟡 [X] Important  |  🟢 [X] Opportunities
+Primary perspective: [Designer(s)] ([context reason])
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+### Overall Assessment
+One paragraph: Does this feel polished? Too much? Too little? What's working, what's not?
+
+---
+
+### Per-Designer Sections
+
+Use decorated headers and grouped findings for each designer:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+⚡ EMIL'S PERSPECTIVE — Restraint & Speed
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+*Weight based on context. Heavy for productivity tools, light for creative/kids apps.*
+
+**What to Check:**
+- High-frequency interactions that might not need animation
+- Keyboard-initiated actions that animate (generally shouldn't)
+- Durations **if this is a productivity context** (Emil prefers under 300ms)
+- Animations starting from scale(0) (should be 0.9+)
+- Transform-origin on dropdowns/popovers
+- CSS keyframes that should be transitions (for interruptibility)
+
+**Output Format:**
+
+**What's Working Well**
+- ✓ [Observation] — `file.tsx:line`
+
+**Issues to Address**
+- ✗ [Issue] — `file.tsx:line`
+  [Brief explanation]
+
+**Emil would say**: [1-2 sentence summary]
+
+---
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+🎯 JAKUB'S PERSPECTIVE — Production Polish
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+**What to Check:**
+- Enter animations (opacity + translateY + blur?)
+- Exit animations (subtler than enters? Or missing entirely?)
+- **Motion gaps** — Conditional renders without AnimatePresence (from gap analysis)
+- **Layout transitions** — Size/position changes that snap instead of animate
+- Shadow vs border usage on varied backgrounds
+- Optical alignment (buttons with icons, play buttons)
+- Hover state transitions (150-200ms minimum)
+- Icon swap animations (opacity + scale + blur)
+- Spring usage (bounce: 0 for professional, higher for playful)
+
+**Output Format:**
+
+**What's Working Well**
+- ✓ [Observation] — `file.tsx:line`
+
+**Issues to Address**
+- ✗ [Issue] — `file.tsx:line`
+  [Brief explanation]
+
+**Jakub would say**: [1-2 sentence summary]
+
+---
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+✨ JHEY'S PERSPECTIVE — Experimentation & Delight
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+**What to Check:**
+- Could @property enable smoother animations?
+- Could linear() provide better easing curves?
+- Are stagger effects using optimal techniques?
+- Could scroll-driven animations improve the experience?
+- What playful touches would enhance engagement?
+- Are there celebration moments that need more delight? (streaks, achievements, etc.)
+
+**Output Format:**
+
+**What's Working Well**
+- ✓ [Observation] — `file.tsx:line`
+
+**Opportunities**
+- 💡 [Idea] — `file.tsx:line`
+  [Brief explanation]
+
+**Jhey would say**: [1-2 sentence summary]
+
+---
+
+### Combined Recommendations
+
+Use severity indicators for quick scanning:
+
+**Critical (Must Fix)**
+| | Issue | File | Action |
+|-|-------|------|--------|
+| 🔴 | [Issue] | `file:line` | [Fix] |
+
+**Important (Should Fix)**
+| | Issue | File | Action |
+|-|-------|------|--------|
+| 🟡 | [Issue] | `file:line` | [Fix] |
+
+**Opportunities (Could Enhance)**
+| | Enhancement | Where | Impact |
+|-|-------------|-------|--------|
+| 🟢 | [Enhancement] | `file:line` | [Impact] |
+
+---
+
+### Designer Reference Summary
+
+End every audit with:
+
+> **Who was referenced most**: [Emil/Jakub/Jhey]
+>
+> **Why**: [Explanation based on the project context]
+>
+> **If you want to lean differently**:
+> - To follow Emil more strictly: [specific actions]
+> - To follow Jakub more strictly: [specific actions]
+> - To follow Jhey more strictly: [specific actions]
+
+---
+
+## Core Principles
+
+### Duration Guidelines (Context-Dependent)
+
+| Context | Emil | Jakub | Jhey |
+|---------|------|-------|------|
+| Productivity UI | Under 300ms (180ms ideal) | — | — |
+| Production polish | — | 200-500ms for smoothness | — |
+| Creative/kids/playful | — | — | Whatever serves the effect |
+
+**Do not universally flag durations over 300ms.** Check your context weighting first.
+
+### Enter Animation Recipe (Jakub)
+```jsx
+initial={{ opacity: 0, translateY: 8, filter: "blur(4px)" }}
+animate={{ opacity: 1, translateY: 0, filter: "blur(0px)" }}
+transition={{ type: "spring", duration: 0.45, bounce: 0 }}
+```
+
+### Exit Animation Subtlety (Jakub)
+Exits should be subtler than enters. Use smaller fixed values, same blur.
+
+### 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
+Always check for `prefers-reduced-motion` support. No exceptions. Flag if missing.
+
+---
+
+## Reference Files (When to Read Each)
+
+**STEP 2a — Read first:**
+- [Audit Checklist](audit-checklist.md) — Your systematic guide for the full audit
+
+**STEP 2b — Read based on context weighting:**
+- [Emil Kowalski](references/emil-kowalski.md) — If Emil is primary/secondary (includes §4 easing/timing/hover tokens)
+- [Jakub Krehel](references/jakub-krehel.md) — If Jakub is primary/secondary
+- [Jhey Tompkins](references/jhey-tompkins.md) — If Jhey is primary/secondary
+
+**STEP 2c — Read as needed:**
+- [Accessibility](references/accessibility.md) — MANDATORY for every audit (prefers-reduced-motion)
+- [Common Mistakes](references/common-mistakes.md) — Check codebase against anti-patterns
+- [Performance](references/performance.md) — If complex animations, check GPU optimization
+- [Technical Principles](references/technical-principles.md) — For implementation recommendations
+
+**Optional context (if uncertain about weighting):**
+- [Philosophy](references/philosophy.md) — Compare all three mindsets to refine weighting
+
+---
+
+## Source
+
+Upstream: [github.com/kylezantos/design-motion-principles](https://github.com/kylezantos/design-motion-principles). To pull updates later, sync from that repo or re-copy `skills/design-motion-principles/` into this folder. Publish install: `npx add-skill kylezantos/design-motion-principles`.

package/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/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@its-thepoe/design-motion-principles",
+  "version": "1.0.0",
+  "description": "Agent Skill: motion and interaction design audit (Emil Kowalski, Jakub Krehel, Jhey Tompkins lenses).",
+  "license": "MIT",
+  "keywords": ["agent-skills", "motion", "animation", "accessibility", "cursor"],
+  "files": [
+    "SKILL.md",
+    "audit-checklist.md",
+    "package.json",
+    "references"
+  ],
+  "exports": {
+    ".": "./SKILL.md",
+    "./SKILL.md": "./SKILL.md",
+    "./audit-checklist.md": "./audit-checklist.md"
+  }
+}

package/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