UI Motion Guide

Unified reference for UI motion/animation principles and implementation patterns. Based on Disney's 12 Principles adapted for digital interfaces, spring/easing physics, and Motion (Framer Motion) library patterns.

12 Principles of Animation (UI Adaptation)

| # | Principle | UI Takeaway | |---|-----------|-------------| | 1 | Squash & Stretch | Subtle scale deformation (0.95-1.05). Too much = cartoon. | | 2 | Anticipation | Prepare user for next action (button compress before send, pull-to-refresh). | | 3 | Staging | One focal point at a time. Dim backgrounds for modals. Sequence reveals. | | 4 | Straight Ahead / Pose to Pose | Web = pose to pose (keyframes, browser interpolates). Context menus: animate exit only, never entrance. | | 5 | Follow Through / Overlapping | Nothing moves as single rigid unit. Springs add organic overshoot. Stagger ≤50ms/item. | | 6 | Slow In & Slow Out | ease-out for entrances, ease-in for exits, ease-in-out for deliberate moves. | | 7 | Arcs | Curved paths feel organic (Dynamic Island). Reserve for hero moments. | | 8 | Secondary Action | Flourishes supporting main action (sparkle on checkmark). Sound can qualify. | | 9 | Timing | Keep interactions ≤300ms. Be consistent. Define timing scale early. | | 10 | Exaggeration | Amplify for emphasis. Good for onboarding, empty states, errors. Sparingly. | | 11 | Solid Drawing | Shadows = depth, layering = hierarchy. CSS perspective for 3D transforms. | | 12 | Appeal | Sum of all techniques applied with care. |

Spring vs Easing Decision Framework

This is the core decision model. Ask: "Is this motion reacting to the user, or is the system speaking?"

┌─────────────────────────┬───────────────┬──────────────────────────────────┐
│ Scenario                │ Use           │ Why                              │
├─────────────────────────┼───────────────┼──────────────────────────────────┤
│ Gesture-driven motion   │ Spring        │ Survives interruption,           │
│ (drag, flick, swipe)    │               │ preserves velocity               │
├─────────────────────────┼───────────────┼──────────────────────────────────┤
│ System state change     │ Easing curve  │ Clear start/end, predictable     │
│ (toggle, page swap)     │               │                                  │
├─────────────────────────┼───────────────┼──────────────────────────────────┤
│ Time representation     │ Linear        │ 1:1 time-progress relationship   │
│ (progress, loading bar) │               │                                  │
├─────────────────────────┼───────────────┼──────────────────────────────────┤
│ High-frequency input    │ None          │ Animation adds noise             │
│ (typing, fast toggles)  │               │                                  │
└─────────────────────────┴───────────────┴──────────────────────────────────┘

Easing Curves

Format: cubic-bezier(x1, y1, x2, y2) — x1,y1 control responsiveness (how motion begins), x2,y2 control how motion ends.

Common patterns:

Entrance (ease-out): cubic-bezier(0, 0, 0.2, 1) — snappy arrival
Exit (ease-in): cubic-bezier(0.4, 0, 1, 1) — builds momentum leaving
In-view transition (ease-in-out): cubic-bezier(0.4, 0, 0.2, 1) — deliberate move
Linear: Only for progress indicators, never for motion

Spring Parameters

| Parameter | What it controls | Effect | |-----------|-----------------|--------| | stiffness | How strongly spring pulls toward target | Higher = snappier | | damping | How quickly energy is removed | Higher = less bounce | | mass | How heavy the object feels | Higher = more sluggish |

Key difference: springs have no predefined end time (they settle naturally), easing curves do.

Rule: Shorten duration first before adjusting the curve. If a curve feels wrong, it's usually too long.

Timing & Duration Rules

| Context | Duration | Rule ID | |---------|----------|---------| | Press / hover feedback | 120-180ms | duration-press-hover | | Small state change (toggle, chip) | 180-260ms | duration-small-state | | User-initiated max | 300ms | duration-max-300ms | | Context menu entrance | 0ms (instant) | none-context-menu-entrance | | Keyboard navigation | 0ms (instant) | none-keyboard-navigation |

Rules with Examples

Easing Direction

easing-entrance-ease-out — Entrances use ease-out (fast start, gentle stop).

// FAIL: Linear entrance feels robotic
<motion.div
  initial={{ opacity: 0, y: 20 }}
  animate={{ opacity: 1, y: 0 }}
  transition={{ duration: 0.2, ease: "linear" }}
/>

// PASS: ease-out entrance feels snappy
<motion.div
  initial={{ opacity: 0, y: 20 }}
  animate={{ opacity: 1, y: 0 }}
  transition={{ duration: 0.2, ease: [0, 0, 0.2, 1] }}
/>

easing-exit-ease-in — Exits use ease-in (slow start, fast departure).

// FAIL: ease-out on exit feels like it's hesitating to leave
<motion.div
  exit={{ opacity: 0, y: -20 }}
  transition={{ duration: 0.15, ease: "easeOut" }}
/>

// PASS: ease-in exit builds momentum
<motion.div
  exit={{ opacity: 0, y: -20 }}
  transition={{ duration: 0.15, ease: [0.4, 0, 1, 1] }}
/>

Physics & Active States

physics-active-state — Interactive elements need :active / whileTap with scale.

// FAIL: Button with no press feedback
<motion.button onClick={handleSubmit}>
  Submit
</motion.button>

// PASS: Button with tactile scale response
<motion.button
  onClick={handleSubmit}
  whileTap={{ scale: 0.97 }}
  transition={{ type: "spring", stiffness: 500, damping: 30 }}
>
  Submit
</motion.button>

physics-subtle-deformation — Scale values in 0.95-1.05 range.

// FAIL: Exaggerated scale feels cartoonish
whileTap={{ scale: 0.8 }}

// PASS: Subtle deformation
whileTap={{ scale: 0.97 }}
whileHover={{ scale: 1.02 }}

physics-no-excessive-stagger — Stagger delay ≤50ms per item.

// FAIL: 200ms stagger makes list feel sluggish
const variants = {
  visible: { transition: { staggerChildren: 0.2 } },
};

// PASS: 30ms stagger feels brisk
const variants = {
  visible: { transition: { staggerChildren: 0.03 } },
};

Spring Usage

spring-for-gestures — Gesture-driven motion must use springs.

// FAIL: Easing for drag (can't preserve velocity on release)
<motion.div
  drag="x"
  animate={{ x: 0 }}
  transition={{ duration: 0.3, ease: "easeOut" }}
/>

// PASS: Spring survives interruption and preserves velocity
<motion.div
  drag="x"
  animate={{ x: 0 }}
  transition={{ type: "spring", stiffness: 300, damping: 25 }}
/>

spring-params-balanced — Avoid excessive oscillation (high stiffness + low damping).

// FAIL: Bounces forever
transition={{ type: "spring", stiffness: 800, damping: 5 }}

// PASS: Controlled overshoot-and-settle
transition={{ type: "spring", stiffness: 300, damping: 25 }}

Staging

staging-one-focal-point — One prominent animation at a time.

// FAIL: Multiple competing animations
<motion.div animate={{ scale: 1.1, rotate: 10 }} />
<motion.div animate={{ x: 100 }} />
<motion.div animate={{ opacity: [0, 1, 0] }} />

// PASS: Single focal animation, others static or subtle
<motion.div animate={{ scale: 1.1 }} />  {/* Hero action */}
<div className="opacity-50" />             {/* Dimmed background */}

staging-dim-background — Dim overlay for modals/dialogs.

// PASS: Overlay dims background to direct focus
<motion.div
  className="fixed inset-0 bg-black/40"
  initial={{ opacity: 0 }}
  animate={{ opacity: 1 }}
  exit={{ opacity: 0 }}
/>

No-Animation Cases

none-high-frequency — No animation for high-frequency interactions.

// FAIL: Animating every keystroke
<motion.span animate={{ opacity: 1 }} key={inputValue}>
  {inputValue}
</motion.span>

// PASS: Instant update
<span>{inputValue}</span>

Accessibility

Always respect prefers-reduced-motion:

// Global: disable all motion
const MotionConfig = ({ children }) => (
  <LazyMotion features={domAnimation}>
    <MotionConfig reducedMotion="user">{children}</MotionConfig>
  </LazyMotion>
);

// Per-element: provide fallback
const prefersReduced = useReducedMotion();
<motion.div
  animate={{ x: prefersReduced ? 0 : 100, opacity: 1 }}
/>

Reference Documents

For detailed implementation patterns, load the relevant reference:

| Reference | Content | When to Load | |-----------|---------|--------------| | references/animate-presence.md | AnimatePresence exit animations, modes, usePresence, nested exits | Implementing enter/exit transitions, list animations, route transitions | | references/morphing-icons.md | SVG line-based morphing icon system with spring physics | Building animated icon sets, hamburger-to-X transitions | | references/container-animation.md | Animating auto width/height, useMeasure, fluid text | Expanding panels, accordions, dynamic-width buttons, text transitions |

Output Format

When reviewing motion code, report issues as:

[RULE_ID] file:line — description

Example:
[easing-entrance-ease-out] components/Modal.tsx:42 — Entrance uses linear easing; should use ease-out
[duration-max-300ms] components/Drawer.tsx:18 — Transition duration is 500ms; reduce to ≤300ms
[spring-for-gestures] components/SwipeCard.tsx:31 — Drag interaction uses easing; switch to spring

Quick Reference

ENTRANCES:  ease-out    [0, 0, 0.2, 1]        120-300ms
EXITS:      ease-in     [0.4, 0, 1, 1]        120-200ms
IN-VIEW:    ease-in-out [0.4, 0, 0.2, 1]      180-300ms
PROGRESS:   linear      —                      matches real time
GESTURES:   spring      stiffness/damping/mass no fixed duration
PRESS:      spring      stiffness:500 damp:30  whileTap scale:0.97
HIGH-FREQ:  none        —                      instant
STAGGER:    ≤50ms/item  —                      30ms typical