design-motion-principles

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). TRIGGER 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.
origin	kylezantos/design-motion-principles
owner	surfingalien
license	MIT

You're a pragmatic executor focused on shipping results and measuring impact. You use AI to amplify your effect and automation to eliminate busywork.

FinSurfing Context

When applying this skill to FinSurfing (React + Vite + Express + PostgreSQL + Anthropic API):

Register: product — FinSurfing is a productivity/trading tool, not a kids app or portfolio.

Default weighting: Emil primary (restraint — traders repeat actions hundreds of times per session), Jakub secondary (production polish for a consumer-facing app), Jhey selective (empty states, onboarding, achievement moments only).

Key motion decisions for FinSurfing:

• Stock watchlist interactions → Emil rules: fast (<180ms), no decorative animation on repeated row interactions
• AI analysis panel entrance → Jakub recipe: opacity + translateY(8px) + blur(4px), spring bounce: 0, 300ms
• P&L number updates → no animation on values that update frequently (Emil frequency gate)
• Portfolio chart reveals → clip-path reveal (Emil), hardware-accelerated, no layout shift
• Empty states (no watchlist items, no analysis yet) → Jhey delight: more expressive entrance is welcome
• Railway deploy status toasts → Jakub: subtle opacity + translateY(-4px) exit, subtler than enter

Audit command for FinSurfing: Run /design-motion-principles in audit mode before each Railway deploy. Check for: pulsing status indicators on live price feeds, hover-scale on stock rows (should be background only), stagger-spam on watchlist items.

Related Skills

• impeccable → /impeccable animate for broader UI animation within a full design workflow
• design-taste-frontend → motion dial settings (MOTION_INTENSITY 1-10) for greenfield builds
• full-output-enforcement → pair to ensure complete motion code is output, not truncated

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	All motion recipes — enter/exit, easing, springs, clip-path, @property, FLIP, scroll-driven	Create mode (always); Audit mode for implementation recommendations
Creation Gotchas	Claude's failure modes when writing motion	Create mode (always)
Audit Checklist	Systematic audit checklist	Audit mode (always)
Anti-Checklist	Quality gate — AI-slop motion categories + anti-patterns to flag	Audit mode (always)
Emil Kowalski	Restraint philosophy, frequency rule, decision frameworks	Either mode, if Emil is weighted
Jakub Krehel	Production polish philosophy and decision frameworks	Either mode, if Jakub is weighted
Jhey Tompkins	Playful experimentation philosophy and frameworks	Either mode, if Jhey is weighted
Accessibility	prefers-reduced-motion, vestibular safety	Both modes (mandatory)
Performance	GPU optimization, will-change, layout thrash	Either mode, for complex animations
Output Format	Audit report template — HTML mode (default) + terminal mode (flag)	Audit mode only
Demo Shell	Visual container template for per-finding demo cards in the HTML report	Audit mode, HTML output

Workflow Index

Workflow	Purpose
Create	Build interactive components with purposeful motion
Audit	Review existing motion design, produce a per-designer report