SKILL.md
Motion Choreography
Motion is communication. Every animation answers a question the user didn't know they had. If it doesn't answer one, cut it.
The Three Questions
Before adding any animation:
- What changed? — the animation makes it visible
- What should I look at next? — directs attention
- How are these related? — shows spatial/hierarchical relationship
Can't answer at least one? The animation is decoration. Cut it.
Duration Guide
| Context | Duration |
|---|---|
| Micro-interaction (button, toggle) | 100-200ms |
| State change (card expand, tab) | 200-300ms |
| Screen transition | 250-400ms |
| Complex choreography | 400-700ms total |
Nothing over 1 second unless it's a loading indicator.
Easing Reference
| Context | Easing |
|---|---|
| Entering | ease-out (decelerate) |
| Leaving | ease-in (accelerate) |
| State change | ease-in-out |
| Micro-interaction | spring (stiffness 300-500) |
Stagger Patterns
- 50-80ms delay between items
- Maximum 5 items staggered, rest appear instantly
- Follow reading order
- Reveal hierarchy — important items first
Reduced Motion
prefers-reduced-motion: reduce means reduce, not remove.
| Standard | Reduced alternative |
|---|---|
| Slide in | Fade in |
| Scale with bounce | Instant appearance |
| Parallax scroll | Static |
| Staggered reveal | Simultaneous fade |
| Continuous pulse | Static state |
Every animation must have a reduced-motion alternative. No exceptions.
What NOT to Animate
- Text colour changes (photosensitive risk)
- Layout properties in performance paths (use transform)
- Anything that delays task completion
- Decorative loops without user control
Performance
Only animate: transform, opacity, filter. These are GPU-composited.
What You Deliver
- Animation specs with durations, easings, triggers
- Reduced-motion alternatives for every animation
- Performance annotations
- Sequence diagrams for complex choreography
Integration
- Informed by:
design-lead,interaction-design - Feeds into:
motion-designeragent,accessibility-reviewer,design-builder