Imported from g8d3/p4 (e034-motion-design-skill/upstream/skills/motion-design/SKILL.md). Install upstream with npx skills add g8d3/p4 --skill motion-design. Copyright stays with the author (MIT).

Motion Design Skill

When to Apply

Use this skill when:

• Creating UI animations (buttons, cards, modals, page transitions)
• Designing micro-interactions and feedback animations
• Building loading, success, or error states
• Animating illustrations or decorative elements
• Planning scroll-triggered or progress-based animations
• Establishing brand motion identity
• Choreographing multi-element sequences

Decision tree:

1. Does it serve a functional purpose (feedback, guidance)? → Timing rules for responsiveness
2. Does it express brand personality? → Motion Personality archetypes
3. Does it tell a story or guide attention? → Disney principles + choreography
4. Is this a complex multi-element scene? → 1/3 Rule + stagger patterns

Quick Reference: 8-Step Checklist

Before creating any animation:

1. Emotional target? — joy, calm, urgency, elegance
2. Motion Personality? — Playful, Premium, Corporate, Energetic
3. Primary property? — position, scale, rotation, opacity
4. Duration? — see duration table below
5. Easing family? — entrance=decelerate, exit=accelerate
6. Hero element? — apply staging principles
7. Secondary + ambient layers? — add richness
8. 1/3 rules? — motion distance, simultaneous elements

Three Pillars (CRITICAL)

Every animation must satisfy three pillars before any technical decisions:

Three motion layers (flat animation = missing layers):

• Primary: Main action the viewer follows
• Secondary: Supporting richness (shadows, icons shifting)
• Ambient: Background life (gradients, subtle pulses)

Deep dive: director/core-philosophy.md

Motion Personality

Select ONE archetype per project. Apply consistently.

Default: Corporate for UI, Playful for illustrations.

Brand Motion Identity — define three constants:

1. Signature easing: One curve for 80% of animations
2. Duration palette: 3 durations (quick / standard / slow)
3. Entrance pattern: One consistent entry style

Deep dive: director/motion-personality.md

Property Selection

Simplicity threshold: Use the minimum properties needed. One = direct. Two = polished. Three+ = potentially overwhelming.

Deep dive: reference/property-selection.md

Duration Table

Distance scales duration: 100px = base. 200px = 1.3x. 400px = 1.6x.

Enter > Exit: Entrances 30-50% longer than exits. Users care about what appears.

Interactive feedback:

• Hover: <100ms
• Press: <150ms
• Release/settle: 200-300ms
• Error shake: 300-400ms (2-3 oscillations)

Deep dive: reference/timing-easing-tables.md

Easing Selection

Directional rules:

• Entrance → decelerate (fast start, gentle landing): ease-out family
• Exit → accelerate (gentle start, fast departure): ease-in family
• On-screen → smooth both ends: ease-in-out family
• Looping ambient → seamless: sine-based ease-in-out

Industry standards:

Material-based easing:

Deep dive: reference/timing-easing-tables.md

Common Patterns

Button Press (Playful)

1. Anticipation: Scale to 0.97 (50ms, ease-out)
2. Squash: Scale to [1.04, 0.96] (100ms, ease-in)
3. Follow through: Overshoots to 1.02, settles to 1.0 (spring, 200ms)
4. Secondary: Shadow shrinks during press, icon shifts down 2px
5. Total: ~150ms press + 200ms settle

Card Entrance (Premium)

1. Start: 20px below target, opacity 0
2. Path: Slight curve (10px X offset at midpoint)
3. Easing: ease-out-cubic deceleration
4. Follow through: Shadow arrives 50ms after card
5. Secondary: Content fades in 100ms after card lands
6. Staging: Other cards dim to 80%

Success State (Playful)

1. Primary: Scale pop with ease-out-back
2. Secondary: Checkmark draws in
3. Ambient: Subtle particle burst
4. Color: Green fill
5. Total: 300-400ms

Error Shake (Corporate)

1. Primary: Position oscillates 2-3 times, ±10-15px horizontal
2. Easing: ease-in-out for sharp stops
3. Color: Red tint
4. Total: 300-400ms
5. No overshoot: Errors feel firm

More patterns: patterns/entrance-exit.md | patterns/state-feedback.md

Choreography Essentials

Coordinated entry:

• Lead with the hero — primary element enters first or most prominently
• Spatial consistency — all elements enter from same direction
• Counter-motion — hero moves right → ambient moves left at 20-30% speed

1/3 Rule (distance): No motion travels more than 1/3 of screen without a keyframe change.

1/3 Rule (elements): With 3+ elements, no more than 1/3 in active motion simultaneously.

Stagger budgets:

Critical: Total stagger must stay under 500ms.

Deep dive: director/choreography.md

Emotion-to-Motion Map

Path as language: Angular = tense. Curved = friendly. Spiral = whimsical. Diagonal = purposeful. Vertical = growth/weight. Horizontal = progress.

Deep dive: director/emotion-mapping.md

Weight Classification

Quality Rules

CRITICAL — never break

1. Never linear for spatial movement — always use easing curves (linear only for spinners, progress bars)
2. Never opacity-only for important state changes — combine with position or scale
3. Never exceed 1/3 screen without intermediate keyframe
4. Always three motion layers — primary + secondary + ambient

HIGH — strongly follow

1. Match duration to element type (see tables)
2. Use directional easing (ease-out entrance, ease-in exit)
3. Apply Disney principles (especially anticipation, follow-through)
4. Maintain consistent personality across scene

Full checklist: reference/quality-checklist.md

Troubleshooting Quick Reference

Deep dive: reference/troubleshooting.md

File Reference

Philosophy (director/):

• core-philosophy.md — Three Pillars deep dive
• decision-framework.md — Full decision pipeline
• disney-principles.md — 12 principles, UI-adapted
• motion-personality.md — 4 archetypes + brand identity
• emotion-mapping.md — Emotion → motion + color psychology
• choreography.md — Multi-element coordination
• narrative-structure.md — Micro-story framework
• context-adaptation.md — Platform, a11y, performance

Reference (reference/):

• timing-easing-tables.md — Duration + easing lookups
• property-selection.md — Property communication guide
• troubleshooting.md — Animation smells + fixes
• quality-checklist.md — Evaluation criteria

Patterns (patterns/):

• entrance-exit.md — Entrance/exit recipes
• state-feedback.md — Success, error, loading, hover
• ambient-continuous.md — Looping, breathing, parallax
• multi-element.md — Stagger + choreography recipes