animation-principles

README.md

references/easing-curves.md

# Easing curves, springs, and durations

A reference library of exact values. Copy directly.

## Named cubic-bezier library

These are battle-tested curves. The four numbers are `(x1, y1, x2, y2)` control points.

### Ease-out family (use for ENTER / appear / settle)

| Name | cubic-bezier | Feel |
|---|---|---|
| easeOutQuad | `0.5, 1, 0.89, 1` | gentle, subtle |
| easeOutCubic | `0.33, 1, 0.68, 1` | balanced, safe default |
| easeOutQuart | `0.25, 1, 0.5, 1` | snappy |
| easeOutQuint | `0.22, 1, 0.36, 1` | very snappy, decisive |
| easeOutExpo | `0.16, 1, 0.3, 1` | dramatic, "premium" arrival |
| easeOutCirc | `0, 0.55, 0.45, 1` | strong late deceleration |

### Ease-in family (use for EXIT / disappear / accelerate away)

| Name | cubic-bezier | Feel |
|---|---|---|
| easeInQuad | `0.11, 0, 0.5, 0` | gentle pull-away |
| easeInCubic | `0.32, 0, 0.67, 0` | balanced exit |
| easeInQuart | `0.5, 0, 0.75, 0` | sharp exit |
| easeInExpo | `0.7, 0, 0.84, 0` | dramatic, fast vanish |

### Ease-in-out family (use for MOVE / reposition while on screen)

| Name | cubic-bezier | Feel |
|---|---|---|
| easeInOutQuad | `0.45, 0, 0.55, 1` | smooth, neutral |
| easeInOutCubic | `0.65, 0, 0.35, 1` | balanced default |
| easeInOutQuart | `0.76, 0, 0.24, 1` | punchy in and out |
| easeInOutExpo | `0.87, 0, 0.13, 1` | very dramatic, long hold mid |

### Overshoot / back family (use for PLAYFUL / branded / "weighty")

| Name | cubic-bezier | Notes |
|---|---|---|
| easeOutBack | `0.34, 1.56, 0.64, 1` | overshoots past target then settles |
| easeInBack | `0.36, 0, 0.66, -0.56` | dips below before launching (anticipation) |
| easeInOutBack | `0.68, -0.6, 0.32, 1.6` | anticipate + overshoot |

The `y` value above 1 (e.g. `1.56`) or below 0 (e.g. `-0.56`) is what creates overshoot/anticipation. Bigger excursion = more bounce.

## Material Design standard curves (good for product UI)

| Token | cubic-bezier | Use |
|---|---|---|
| Standard | `0.2, 0, 0, 1` | most transitions |
| Decelerate (enter) | `0, 0, 0, 1` | elements entering screen |
| Accelerate (exit) | `0.3, 0, 1, 1` | elements leaving screen |
| Emphasized | `0.2, 0, 0, 1` (300-500ms) | hero moments |

## iOS / Apple feel

Apple favors springs, but the closest bezier is `0.25, 0.1, 0.25, 1` (the legacy `ease`) sharpened toward `0.33, 1, 0.68, 1`. For modal presentation Apple uses a spring close to `stiffness 280, damping 28`.

## Spring configurations

Springs are defined by stiffness (tension), damping (friction), and mass. Higher stiffness = faster; higher damping = less bounce; higher mass = more sluggish/heavy.

### Framer Motion (`type: "spring"`)

```js
// Snappy default — interactive UI
{ type: "spring", stiffness: 300, damping: 30, mass: 1 }

// Bouncy — playful, branded
{ type: "spring", stiffness: 400, damping: 17, mass: 1 }

// Gentle — large/heavy elements, modals
{ type: "spring", stiffness: 120, damping: 20, mass: 1 }

// Stiff/no bounce — precise, critically damped
{ type: "spring", stiffness: 500, damping: 50, mass: 1 }

// Alternative API: duration-based spring (Framer Motion v10+)
{ type: "spring", duration: 0.5, bounce: 0.25 } // bounce 0 = no overshoot, 0.5 = lively
```

### react-spring presets

```js
import { config } from '@react-spring/web'
config.default   // { tension: 170, friction: 26 }
config.gentle    // { tension: 120, friction: 14 }
config.wobbly    // { tension: 180, friction: 12 }  — visible bounce
config.stiff     // { tension: 210, friction: 20 }
config.slow      // { tension: 280, friction: 60 }  — heavy, no bounce
config.molasses  // { tension: 280, friction: 120 }
```

### SwiftUI / iOS

```swift
.spring(response: 0.4, dampingFraction: 0.8)   // response = approx duration, dampingFraction 1.0 = no bounce
.interactiveSpring()                            // for gesture-driven
```

## Duration guidance per element type

| Element / event | Duration | Easing |
|---|---|---|
| Hover state, tap highlight | 100-150ms | easeOutQuad |
| Toggle, checkbox, switch | 150-200ms | easeOutCubic |
| Tooltip, dropdown open | 150-250ms | easeOutCubic |
| Button press feedback | 80-120ms down / 200ms up | easeOut + back on release |
| Modal / dialog enter | 300-400ms | easeOutExpo or spring(gentle) |
| Modal / dialog exit | 200-250ms | easeInQuart |
| Page / route region transition | 300-500ms | easeInOutCubic |
| Card / list item reveal | 400-500ms each | easeOutExpo |
| Hero headline / full-screen | 500-800ms | easeOutExpo |
| Cinematic camera push/pan | 800-2000ms | easeInOutQuad |
| Loading spinner | continuous | linear |
| Number count-up | 600-1200ms | easeOutExpo |

## Distance-to-duration scaling

To keep perceived velocity natural, scale duration with travel distance:

```
duration_ms ≈ base_ms * (distance_px / base_distance_px) ^ 0.5
```

The `^0.5` (square root) prevents long moves from feeling tediously slow while still granting them more time than short moves. Example: base 300ms at 200px -> a 800px move ≈ 300 * sqrt(4) = 600ms.

## Stagger math

```
total = (count - 1) * offset + per_item_duration
```

Keep `total` under ~800ms for group reveals. If it exceeds that, reduce `offset` or use distance-based staggering (each item's delay proportional to its distance from a focal origin), which keeps a constant feel regardless of count.

references/easing-graph-editor.md

# Easing in the After Effects Graph Editor

Tool-specific craft for turning the abstract easing principles into hand-shaped After Effects keyframes. The concepts here (slow-in/slow-out, asymmetric easing, overshoot, bounce) apply everywhere; the controls are AE's Graph Editor.

## The principle: slow-in / slow-out

Natural motion accelerates from rest and decelerates to rest — "slow-in, slow-out". Constant-speed (linear) motion reads as robotic because nothing physical starts and stops instantly. Easing means shaping how fast a property changes over time, not just its start and end values.

## Graph Editor basics

Open with the **Graph Editor** button (the curve icon) in the Timeline (or Shift+F3). It replaces the keyframe strip with curves.

Two graph modes, switched via the **graph type menu** at the bottom of the Graph Editor:

- **Value Graph** — plots the property's value over time (e.g., X position in pixels). The line's height = the value; its slope = the speed.
- **Speed Graph** — plots the rate of change (speed) over time. The line's height = speed; a hump = fast, a valley near zero = slow/stopped.

**How to tell which is shown:** Open the graph type menu → "Edit Value Graph" / "Edit Speed Graph" shows the current choice (the active one is checked). Quick tell: for a single moving property, the **Speed Graph** reads as a hill (accelerate up, decelerate down); the **Value Graph** reads as an S-curve climbing from start value to end value. Spatial properties (Position) usually default to the Speed Graph; single-dimension properties to the Value Graph.

For shaping ease feel, the **Speed Graph** is the most intuitive: flatten the ends toward zero (slow start/stop), let the middle rise (fast).

### Display tips
- Enable "Show Reference Graph" to see the other graph faintly behind the editable one.
- "Snap" and "Fit selection to view" make handle work easier.

## Why Easy Ease is rarely enough

`F9` (Easy Ease) applies a symmetric ease with ~33% influence on both sides. It's a starting point, not a finished move. Two reasons it falls flat:

1. **Symmetry.** Most compelling motion is asymmetric — e.g., snappy UI eases *out* hard (fast start, long glide to stop) far more than it eases in.
2. **Low influence.** 33% is gentle. Strong, modern motion-design easing pushes influence to **80–90%** on the deceleration side, producing a sharp launch and a smooth settle.

So: start with `F9`, then open the Graph Editor and **drag the bezier handles** to make it asymmetric and increase influence.

## Handle techniques

In the Graph Editor each keyframe has bezier handles:

- **Pull a handle horizontally (longer)** → more influence → the ease extends further in time → smoother, slower approach.
- **Pull a handle down toward zero speed** → the property comes more fully to rest at that keyframe.
- **Ease out 80–90%:** select the final keyframe, drag its incoming handle nearly flat and long so speed glides to near-zero over most of the move. This is the core "snappy" feel.
- **Overshoot:** let the value go past the target, then settle back. In the Value Graph, push the curve above the end value briefly, then return. Or add a small keyframe past the target and ease back.
- **Bounce:** repeated decaying overshoots — the value hits, overshoots less each time, settling. Build with successive keyframes of decreasing amplitude, each eased.

## Influence and velocity numbers

Right-click a keyframe → **Keyframe Velocity** to set exact values:

- **Incoming/Outgoing Velocity** — the speed at the keyframe (units/sec). Zero = full stop.
- **Influence %** — how far the ease extends toward the neighboring keyframe. Higher = smoother, longer ease.

Targets:
- Snappy UI move: outgoing influence ~15–25% (quick launch), **incoming influence 80–90%** (long settle).
- Smooth symmetric float: both sides ~50–65%.
- Anticipation: a small reverse move before the main action (pull back, then go).

## Recipe table

| Feel | Speed Graph shape | Outgoing inf. | Incoming inf. | Notes |
|---|---|---|---|---|
| Snappy UI | sharp rise, long tail to 0 | 10–25% | 80–90% | The default "good" motion-design ease |
| Smooth float | gentle symmetric hill | 50–65% | 50–65% | Calm, even, no snap |
| Anticipation | dip below 0 then rise | add pre-keyframe | 70–85% | Tiny reverse move first |
| Overshoot | rise, overshoot value, settle | 20–40% | 85–95% | 1 extra keyframe past target |
| Bounce | repeated decaying humps | per-bounce | per-bounce | Decreasing amplitude keyframes |

## Quick reference

| Action | How |
|---|---|
| Open Graph Editor | Curve icon in Timeline (or Shift+F3) |
| Apply Easy Ease | `F9` (Ease In `Shift+F9`, Ease Out `Ctrl/Cmd+Shift+F9`) |
| Switch Value/Speed graph | Graph type menu (bottom of Graph Editor) |
| Set exact velocity | Right-click keyframe → Keyframe Velocity |
| Convert to bezier handles | Easy Ease, then drag handles |
| Strong settle | Incoming influence 80–90% on last keyframe |

## Step-by-step recipes

### Snappy UI ease (the workhorse)
1. Set two Position (or Scale) keyframes for the move.
2. Select both, press `F9` (Easy Ease).
3. Open Graph Editor → Speed Graph.
4. Select the **first** keyframe; shorten its outgoing handle (low influence, ~15–25%) so it launches fast.
5. Select the **last** keyframe; pull its incoming handle long and nearly flat to the time axis — influence **80–90%** — so it glides to a stop.
6. Result: fast start, long smooth settle. This is the standard "premium" motion-design feel.

Exact via Keyframe Velocity (right-click keyframe):
- First keyframe: Outgoing influence 18%, velocity 0.
- Last keyframe: Incoming influence 85%, velocity 0.

### Overshoot
Goal: element flies in, slightly passes its target, settles back.
1. Animate from start to target value (2 keyframes), ease.
2. Add a **third keyframe ~6–10 frames before** the final, set its value **past** the target (e.g., target 100% → set 112%).
3. Final keyframe returns to target (100%).
4. Ease all keyframes; give the settle keyframes high incoming influence (85–95%).
5. Tune overshoot amount (how far past) and settle time for snappiness.

Value Graph view: the curve rises above the target line, then dips back down to it.

### Anticipation
Goal: a small reverse move before the main action (wind-up).
1. Before the main motion's first keyframe, add a keyframe that moves **slightly opposite** the main direction (e.g., a jump-up preceded by a small crouch-down).
2. Ease the wind-up gently, then the main move fast (low outgoing influence).
3. Optionally combine with overshoot on the landing for a full squash-stretch feel.

### Bounce (hand-keyed)
1. First keyframe: rest/start.
2. Impact keyframe: the object hits the floor value.
3. Bounce keyframes: each successive peak is **lower** than the last (decaying amplitude), spaced **closer** in time (decreasing period).
4. At each floor contact, set incoming/outgoing velocity sharp (near-instant direction change); at each peak, ease to near-zero speed (apex).
5. 3–4 decaying bounces usually read as natural.

Amplitude example for a drop settling to 0: 0 → -200 (rise) → 0 → -90 → 0 → -35 → 0 → -12 → 0, with shrinking time gaps.

### Bounce (expression)
Apply to a property (e.g., Position) after a single ease-in keyframe to auto-generate decaying bounce:
```javascript
amp = 0.12;       // bounce strength
freq = 2.5;       // bounces per second
decay = 5.0;      // how fast it settles
n = 0;
if (numKeys > 0) { n = nearestKey(time).index; if (key(n).time > time) n--; }
if (n > 0) {
  t = time - key(n).time;
  v = velocityAtTime(key(n).time - thisComp.frameDuration/10);
  value + v*(amp*Math.sin(freq*t*2*Math.PI)/Math.exp(decay*t));
} else { value; }
```
- `amp` raises the overshoot height; `freq` the number of wobbles; `decay` how quickly it stops.
- Place a single eased keyframe (or two) where the motion arrives; the expression adds the bounce after.

## Velocity / influence cheat sheet

| Feel | Out influence | In influence | Velocity at stops |
|---|---|---|---|
| Snappy UI | 15–25% | 80–90% | 0 |
| Smooth float | 50–65% | 50–65% | 0 |
| Mechanical/linear | 0% | 0% | constant |
| Overshoot settle | 20–40% | 85–95% | 0 at final |
| Bounce apex | high | high | 0 at apex |
| Bounce impact | low | low | sharp/non-zero |

## Gotchas

- **Easy Ease ≠ finished.** It's a 33% symmetric starting point; almost always refine in the Graph Editor.
- **Know your graph.** Editing a Value Graph thinking it's a Speed Graph produces confusing results — confirm in the graph type menu.
- **Influence is per-side.** Asymmetric influence (low out, high in) is what makes UI motion feel snappy.
- **Spatial vs temporal.** Position has both a motion path (spatial bezier in the Composition viewer) and speed easing (Graph Editor). A floaty arc may be a spatial handle issue, not temporal. Right-click a Position keyframe for **Rove Across Time** and spatial interpolation (Linear/Auto/Continuous Bezier).
- **Auto-Bezier roving keyframes** can smooth speed across multiple keyframes but remove precise per-keyframe timing — use deliberately.
- **Overshoot needs room past the target** — clamp/limits or layout edges can hide it.
- **Bounce by hand is tedious;** expression-driven bounce (decaying sine) is common, but hand-keyed gives the most control.

references/twelve-principles.md

# The 12 principles of animation, applied to motion graphics

The Disney principles, translated to UI/motion-graphics with concrete numeric examples. Ordered by how often they matter in screen motion (most-used first).

## 1. Slow in and slow out (easing)

The most important. Objects accelerate and decelerate; they don't snap to constant velocity.

Example: a card sliding in from the right travels 600px over 450ms with `cubic-bezier(0.16, 1, 0.3, 1)` (easeOutExpo) — fast at first, settling gently into place.

## 2. Timing

Number of frames / duration defines weight and mood. Fast = light/urgent, slow = heavy/calm.

Example: a 24px notification badge pops in over 150ms; a full-screen onboarding panel slides over 500ms. Same easing, different timing communicates different mass.

## 3. Follow-through and overlapping action

Parts don't all stop at once; trailing elements continue and settle after the lead.

Example: a hero card lands at 400ms; its drop-shadow finishes settling at 450ms, its title text at 460ms, its subtitle at 500ms — a 40-60ms cascade rather than a synchronized stop.

## 4. Anticipation

A small opposite move telegraphs the main action.

Example: a "send" button scales to `0.95` over 80ms (the dip), then springs to `1.0` and the message launches. Or a modal dips `y: +8px` for 60ms before sliding up — the recoil makes the launch feel powered.

## 5. Staging (focal direction)

Direct attention to one thing at a time; the motion makes the important element unambiguous.

Example: dim background to 40% opacity over 200ms while the target element scales `0.9 -> 1.0` and brightens — the eye has exactly one place to land.

## 6. Arcs

Natural movement follows curved paths, not straight lines.

Example: a floating action button moving from bottom-right to center-screen animates along a quadratic bezier path instead of a diagonal line; the slight arc reads as organic rather than mechanical.

## 7. Squash and stretch

Volume-preserving deformation conveys impact and elasticity.

Example: a bouncing dot stretches `scaleY 1.2 / scaleX 0.85` at the top of its arc and squashes `scaleY 0.8 / scaleX 1.15` on landing impact. Keep the product of scales ≈ 1 to preserve perceived volume. Use sparingly in product UI; common in playful loaders and mascots.

## 8. Exaggeration

Push the key pose beyond literal realism for clarity and appeal.

Example: a success checkmark overshoots to `scale 1.15` before settling to `1.0` (using easeOutBack `0.34, 1.56, 0.64, 1`); the overshoot makes success feel emphatic.

## 9. Secondary action

A subordinate motion supporting the primary one.

Example: while a panel slides up (primary), its icon rotates 90deg and a subtle particle shimmer fades in (secondary) — supporting, never competing for attention.

## 10. Straight-ahead vs. pose-to-pose

Pose-to-pose (define keyframes, interpolate between) is the norm for choreographed motion graphics; straight-ahead (frame-by-frame, momentum-driven) suits chaotic/organic effects like particles, smoke, and procedural noise.

Example: a logo build is pose-to-pose (start pose, end pose, eased between); a confetti burst is straight-ahead/physics-driven.

## 11. Solid drawing (depth and weight)

Maintain consistent perspective, volume, and lighting so motion respects 3D space.

Example: when a 2.5D card tilts on hover (`rotateY 8deg`), its shadow shifts and lengthens consistently and a subtle specular highlight sweeps — selling that it's a solid object catching light, not a flat sticker.

## 12. Appeal

The composite charm — clean silhouettes, confident timing, no jank. Achieved by applying the other 11 with restraint: correct easing, deliberate timing, follow-through, a touch of overshoot, and removing anything that competes.

Example: a polished toggle = 180ms easeOutCubic slide, a 40ms follow-through on the label color, a hairline overshoot on the knob — small, coherent, satisfying.

## Practical priority for screen motion

For most product/web work, nailing **slow-in/slow-out, timing, follow-through, anticipation, staging, and arcs** delivers 90% of the quality. Squash/stretch, exaggeration, and secondary action add personality where the brand calls for it.

---
Apply the twelve principles with restraint and UI motion reads as intentional. Built by **[iart.ai](https://iart.ai/?utm_source=github&utm_medium=readme&utm_campaign=motion-design-skills&utm_content=skill_footer&utm_term=animation-principles)** — the AI motion agent for editable, on-brand motion graphics.

SKILL.md

---
name: animation-principles
description: This skill should be used when the user asks to "make this animation feel natural", "fix motion that feels stiff/floaty/cheap", "my animation looks robotic", "choose an easing curve", "how do I use the Graph Editor", "add overshoot or bounce", "Easy Ease isn't enough", "make snappy motion", "pick a duration for this transition", "stagger a list animation", "sync animation to a beat", or "review motion for good timing". It is the tech-agnostic foundation for deciding how something should move.
version: 0.1.0
---

# Motion Principles

Decide how something should move so it feels right — independent of the tool used to build it. This skill answers timing, easing, spacing, weight, and rhythm. It does not pick a tech stack; it produces concrete numbers (durations, cubic-bezier curves, stagger offsets, spring configs) ready to hand to any implementation.

## When to use

- Motion feels stiff, floaty, mechanical, robotic, or cheap and needs diagnosis.
- Choosing a clip or transition's duration, easing curve, and stagger offset.
- Reviewing whether motion respects physics intuition (weight, follow-through, arcs).
- Synchronizing keyframes to a musical beat or edit accent.

## Three pillars — settle these before any number

Every piece of motion should answer three questions *before* you pick a duration or curve. Skip them and you get technically-correct motion that feels like nothing. These are the shared vocabulary the rest of the collection refers back to.

| Pillar | The question | What it drives |
|---|---|---|
| **Emotional intent** | What should the viewer *feel*? (joy, calm, urgency, trust, elegance) | Easing, duration, amplitude/overshoot |
| **Visual narrative** | What's the micro-story? Setup → action → resolution | Sequencing, staging, what enters when |
| **Motion craft** | How do we make it believable? | Physics, secondary motion, arcs, follow-through |

## Three motion layers — depth, not flatness

Flat motion = only the main thing moves. Believable motion runs three layers at once:

- **Primary** — the main action the eye follows (the hero move).
- **Secondary** — supporting richness reacting to the primary (a shadow shifting, an icon nudging, a label settling late).
- **Ambient** — background life that never demands attention (slow gradient drift, a low-contrast pulse).

> The judgment layer (`motion-art-direction`) calls these **Hero / Support / Texture** — same three layers, ranked for *what earns motion*. Primary≈Hero, Secondary≈Support, Ambient≈Texture.

## Core principles

### Easing is the single biggest lever

Linear motion reads as robotic. Reserve `linear` for continuous loops (spinners, marquees, infinite scroll) only. Everything an eye perceives as a discrete event needs acceleration.

Match the curve to the action:
- **Enter / appear** -> ease-out (fast start, gentle settle). Object arrives with energy and decelerates into place. `cubic-bezier(0.16, 1, 0.3, 1)`.
- **Exit / disappear** -> ease-in (gentle start, fast end). Object accelerates away. `cubic-bezier(0.7, 0, 0.84, 0)`.
- **Move / reposition (stays on screen)** -> ease-in-out (symmetric). `cubic-bezier(0.65, 0, 0.35, 1)`.
- **Playful / branded** -> slight overshoot. `cubic-bezier(0.34, 1.56, 0.64, 1)` (the `1.56` pushes past 1.0, creating an overshoot-and-settle that reads as "weight").

Rule of thumb: the eye forgives a slow start far less than a slow end. When in doubt, decelerate into rest.

**Hand-shaping easing (After Effects).** When keyframing by hand rather than supplying a curve, the same principles map to the Graph Editor: shape the Speed Graph so the ends flatten toward zero, and push deceleration influence to 80–90% for a snappy launch and smooth settle. `F9` (Easy Ease) is only a 33% symmetric starting point — make it asymmetric. See `references/easing-graph-editor.md` for Graph Editor reading, handle/influence techniques, and step-by-step overshoot, anticipation, and bounce recipes (including a decaying-bounce expression).

### Timing communicates weight and importance

| Element | Duration |
|---|---|
| Micro-interaction (hover, toggle, tap feedback) | 100-200ms |
| UI transition (panel, modal, page region) | 200-400ms |
| Hero / large element / full-screen | 400-800ms |
| Cinematic camera move | 800-2000ms |

Distance and size scale duration. A small icon moving 20px and a full-bleed panel moving 800px should NOT share a duration — the panel needs more time or it looks weightless. A practical scaling: keep perceived velocity roughly constant by adding ~30-50% duration when distance or area roughly doubles. Heavy objects start slowly and overshoot less; light objects snap and may bounce.

### Spacing and stagger create rhythm

Never reveal a list, grid, or group all at once — it reads as a single flat event. Stagger each child's start.

- Lists / sequential items: **40-80ms** between items.
- Dense grids: **20-40ms** (more items, less per-item delay, or the tail drags).
- Cap total reveal at roughly **600-800ms** for a group; if `count * offset` exceeds that, shrink the offset or switch to a distance-based stagger (items further from an origin point start later).
- Stagger direction should follow the eye: top-to-bottom, or radiating from a focal point.

**The 1/3 Rule (two forms, both universal):**
- *Distance* — no element travels more than ~1/3 of the screen without an intermediate keyframe or a scale/opacity change. Long unbroken slides read as "the template moved," not "something happened."
- *Simultaneity* — with 3+ elements, keep no more than ~1/3 in active motion at once. The rest hold or move as ambient. Everything moving together = noise with no focal point.

### Anticipation and follow-through sell physical motion

- **Anticipation**: a tiny counter-move before the main action (a button dips `scale 0.95` before popping, a character crouches before jumping). 60-120ms is enough.
- **Follow-through / overlapping action**: trailing parts keep moving after the main body stops (a hero card lands, then its shadow and label settle 40-80ms later). Stagger the settle of attached elements rather than stopping everything on the same frame.
- **Arcs**: natural movement curves; pure straight-line translation of an organic object looks mechanical. Add a slight arc to x/y or animate a path.

### Beat-sync and rhythm

When motion accompanies audio, land impact keyframes (a hit, a cut, a reveal) on the beat, not between beats. At 120 BPM a beat is 500ms; an eighth-note grid is 250ms. Quantize key moments to that grid. For edits without music, establish a visual pulse (e.g. one major event per ~500-800ms) so the piece breathes consistently.

### Spring vs. duration-based motion

Springs (mass / stiffness / damping) self-determine duration and feel more physical for interactive, interruptible motion (drag-release, gestures). Duration+easing is better for choreographed, timeline-locked sequences (video, scroll-tied reveals) where exact sync matters. A snappy default spring: `stiffness 300, damping 30, mass 1`. See `references/easing-curves.md` for a full spring table.

## Diagnosing common failures

- **Feels stiff/robotic** -> using `linear` or symmetric easing on an enter; switch to ease-out.
- **Feels floaty/sluggish** -> duration too long or ease-out too gentle; cut duration 30%, sharpen the curve.
- **Feels cheap/janky** -> everything appears at once (no stagger), or all elements share one duration regardless of size.
- **Feels mechanical despite easing** -> no anticipation, no follow-through, straight-line paths; add arcs and overlap.

## Quick reference

| Need | Use |
|---|---|
| Enter | `cubic-bezier(0.16, 1, 0.3, 1)`, 300-500ms |
| Exit | `cubic-bezier(0.7, 0, 0.84, 0)`, 200-300ms |
| Move | `cubic-bezier(0.65, 0, 0.35, 1)`, 300-400ms |
| Branded pop | `cubic-bezier(0.34, 1.56, 0.64, 1)`, 400-600ms |
| List stagger | 40-80ms per item, cap ~700ms total |
| Loop only | `linear` |

## Reference files

- `references/easing-curves.md` — named cubic-bezier library with exact values, spring configs (Framer/react-spring/iOS), and per-element-type duration guidance.
- `references/easing-graph-editor.md` — After Effects Graph Editor craft: speed graph vs value graph, easing handles and influence/velocity numbers, and step-by-step snappy, overshoot, anticipation, and bounce recipes.
- `references/twelve-principles.md` — all 12 Disney principles, each with a concrete, numeric motion-graphics example.