Ui Animation

Reference files

| File | Read when | | -------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | | [references/decision-framework.md](references/decision-framework.md) | Default: animation decisions, easing, and duration | | [references/spring-animations.md](references/spring-animations.md) | Using spring physics, framer-motion useSpring, configuring spring params | | [references/component-patterns.md](references/component-patterns.md) | Building buttons, popovers, tooltips, drawers, modals, toasts with animation | | [references/clip-path-techniques.md](references/clip-path-techniques.md) | Using clip-path for reveals, tabs, hold-to-delete, comparison sliders | | [references/gesture-drag.md](references/gesture-drag.md) | Implementing drag, swipe-to-dismiss, momentum, pointer capture | | [references/performance-deep-dive.md](references/performance-deep-dive.md) | Debugging jank, CSS vs JS, WAAPI, CSS variables trap, Framer Motion caveats | | [references/review-format.md](references/review-format.md) | Reviewing animation code — Before/After/Why table and issue checklist |

Core rules

1. Animate for feedback, orientation, continuity, or deliberate delight.
2. Never animate keyboard-initiated actions (shortcuts, arrow navigation, tab/focus).
3. Prefer CSS transitions for interruptible UI; use keyframes only for predetermined sequences.
4. CSS transitions > WAAPI > CSS keyframes > JS (requestAnimationFrame).
5. Make animations interruptible and input-driven.
6. Asymmetric timing: enter can be slightly slower; exit should be fast.
7. Use @starting-style for DOM entry animations; fall back to data-mounted.
8. A small filter: blur(2px) can hide rough crossfades.

Motion design principles

1. Continuity over teleportation. Elements visible in both states transition in place. Never duplicate a persistent element or hard-cut between views that share components.
2. Directional motion matches position. Tab and carousel transitions animate in the direction matching spatial layout (left-to-right for forward, right-to-left for back).
3. Emerge from the trigger. Overlays, trays, and panels animate outward from the element that opened them. Generic centre-screen entrances break spatial orientation.
4. Consistent polish everywhere. Under-animated areas make the entire product feel unpolished. Motion quality must be uniform across all surfaces.
5. Delight scales inversely with frequency. Rarer interactions have more room for personality and surprise. High-frequency actions must be invisible.
6. Motion enhances perceived speed. Smooth transitions between states feel faster than hard cuts, even at identical load times.

What to animate

1. Movement: transform and opacity only.
2. State feedback: color, background-color, and opacity are acceptable.
3. Never animate layout properties (width, height, top, left); never use transition: all.
4. Avoid filter animation for core interactions; keep blur <= 20px if unavoidable.
5. SVG: apply transforms on a <g> wrapper with transform-box: fill-box; transform-origin: center.
6. Disable transitions during theme switches ([data-theme-switching] * { transition: none !important }).

Easing defaults

| Element | Duration | Easing | | ----------------------------- | ------------ | -------------------------------- | | Button press feedback | 100–160ms | cubic-bezier(0.22, 1, 0.36, 1) | | Tooltips, small popovers | 125–200ms | ease-out or enter curve | | Dropdowns, selects | 150–250ms | cubic-bezier(0.22, 1, 0.36, 1) | | Modals, drawers | 200–350ms | cubic-bezier(0.22, 1, 0.36, 1) | | Move/slide on screen | 200–300ms | cubic-bezier(0.25, 1, 0.5, 1) | | Simple hover (colour/opacity) | 200ms | ease | | Illustrative/marketing | Up to 1000ms | Spring or custom |

Named curves

1. Enter: cubic-bezier(0.22, 1, 0.36, 1) — entrances and transform-based hover
2. Move: cubic-bezier(0.25, 1, 0.5, 1) — slides, drawers, panels
3. Drawer (iOS-like): cubic-bezier(0.32, 0.72, 0, 1)

Avoid ease-in for UI. Prefer custom curves from [easing.dev](https://easing.dev/).

Spatial and sequencing

1. Set transform-origin at the trigger point for popovers; keep center for modals.
2. For dialogs/menus, start around scale(0.85–0.9). Never scale(0).
3. Stagger reveals at 30–50ms per item; total stagger under 300ms.

Accessibility

1. Gate hover animations behind @media (hover: hover) and (pointer: fine) to avoid false positives on touch.
2. During direct manipulation, keep the element locked to the pointer. Add easing only after release.

Performance

1. Only animate transform and opacity — these skip layout and paint.
2. Pause looping animations off-screen with IntersectionObserver.
3. Toggle will-change only during heavy motion and only for transform/opacity — remove after.
4. Do not animate drag gestures using CSS variables (triggers recalc on all children).
5. Motion x/y values are the normal choice for axis-based movement and drag. Use full transform strings when you need one transform owner for combined transforms or interop.
6. See [references/performance-deep-dive.md](references/performance-deep-dive.md) for WAAPI, compositing layers, and CSS vs JS comparison.

Anti-patterns

1. transition: all — triggers layout recalc and animates unintended properties.
2. Animating layout properties (width, height, top, left) for interactive feedback.
3. Using ease-in for UI entrances — feels sluggish.
4. Animating from scale(0) — nothing in the real world appears from nothing. Use scale(0.85–0.95).
5. Animating on mount without user trigger — unexpected motion is disorienting.
6. Permanent will-change — toggle it only during heavy motion.
7. CSS variables for drag gesture animation — repaints every frame.
8. Symmetric enter/exit timing — exit should be faster (user expects instant response).
9. Hard stops on drag boundaries — use friction/damping instead.
10. Mixing Motion x/y props with a handwritten transform string on the same element.
11. Keyframes on rapidly-triggered elements — use CSS transitions for interruptibility.
12. Static cuts between related views — if views share elements, hard cuts lose spatial context. Transition shared elements in place.
13. Duplicating persistent elements across states — animate the same element from its current position to its next, rather than hiding one and showing another.
14. Generic centre-screen entrance for contextual content — overlays and trays should emerge from their trigger, not fade in from nowhere.

Workflow

Copy and track this checklist:

Animation progress:
[ ] Step 1: Decide whether the interaction should animate
[ ] Step 2: Choose purpose, easing, and duration
[ ] Step 3: Pick the implementation style
[ ] Step 4: Load the relevant component or technique reference
[ ] Step 5: Validate timing, interruption, and device behavior

1. Answer the four questions from [references/decision-framework.md](references/decision-framework.md): should it animate? What purpose? What easing? What speed?
2. Pick duration from the easing defaults table above.
3. Choose implementation: CSS transition > WAAPI > spring > keyframe > JS.
4. Load the relevant reference for your component type or technique.
5. When reviewing, use the Before/After/Why table format from [references/review-format.md](references/review-format.md).

Validation

1. Verify no layout property animations (width, height, top, left).
2. Check that looping animations pause off-screen.
3. Confirm will-change is toggled only during animation, not permanently set.
4. Retoggle components quickly to confirm transitions retarget cleanly instead of restarting from zero.
5. Slow animations to 0.1x in DevTools to catch timing issues invisible at full speed.
6. Record and play back frame-by-frame for coordinated property timing.
7. Test touch interactions on real devices (not just simulators).