UI Animation

Reference files

Core rules

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

Motion design principles

• Continuity over teleportation. Elements visible in both states transition in place. Use shared element transitions — expand from where elements sit rather than fading in a new instance. Never duplicate a persistent element or hard-cut between views that share components.
• 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).
• Emerge from the trigger. Overlays, trays, and panels animate outward from the element that opened them. Generic centre-screen entrances break spatial orientation.
• Consistent polish everywhere. Under-animated areas make the entire product feel unpolished. Motion quality must be uniform across all surfaces.
• Delight scales inversely with frequency. Rarer interactions have more room for personality and surprise. High-frequency actions must be invisible.
• Motion enhances perceived speed. Smooth transitions between states feel faster than hard cuts, even at identical load times.

What to animate

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

Easing defaults

Named curves

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

Avoid ease-in for UI. Prefer custom curves from easing.dev.

Spatial and sequencing

• Set transform-origin at the trigger point for popovers; keep center for modals.
• For dialogs/menus, start around scale(0.85–0.9). Never scale(0).
• Stagger reveals at 30–50ms per item; total stagger under 300ms. Vary timing by visual importance — the most important element should lead. Uniform stagger (identical delays between all items) removes hierarchy and feels mechanical.
• Paired elements rule: Elements that animate together (modal + overlay, tooltip + arrow, FAB + label) must share the same easing curve and duration. Mismatched timing between paired elements is a common source of "something feels off" bugs.

Accessibility

• Gate hover animations behind @media (hover: hover) and (pointer: fine) to avoid false positives on touch. Tailwind v4 hover: utilities apply this guard automatically — skip the manual media query in Tailwind v4 projects.
• During direct manipulation, keep the element locked to the pointer. Add easing only after release.
• Respect prefers-reduced-motion: reduce. Replace spatial movement (translateY, scale) with opacity crossfades — reduced motion means less spatial movement, not zero feedback. Keep color and background-color transitions.

@media (prefers-reduced-motion: reduce) {
  *, *::before, *::after {
    transition-duration: 0.01ms !important;
    animation-duration: 0.01ms !important;
    animation-iteration-count: 1 !important;
  }
}

• In Framer Motion, use the useReducedMotion hook to skip spatial initial values:

const shouldReduceMotion = useReducedMotion();
<motion.div
  initial={shouldReduceMotion ? false : { opacity: 0, y: 20 }}
  animate={{ opacity: 1, y: 0 }}
/>

Performance

• Only animate transform and opacity — these skip layout and paint.
• Pause looping animations off-screen with IntersectionObserver.
• Toggle will-change only during heavy motion and only for transform/opacity — remove after.
• Do not animate drag gestures using CSS variables (triggers recalc on all children).
• 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.
• See references/performance-deep-dive.md for WAAPI, compositing layers, and CSS vs JS comparison.

Anti-patterns

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

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: 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.

Validation

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