Animation & Motion

Animation is where design engineers add unique value. A prototype has no motion curves, no hover states, no gesture feedback — but a shipped product needs all of them. Motion communicates hierarchy, confirms actions, and makes the interface feel physical rather than mechanical.

CSS Transitions vs Keyframes

The two CSS animation mechanisms serve different purposes and behave differently when interrupted:

.element {
  transition: transform 200ms ease, opacity 200ms ease;
}

@keyframes fade-in {
  from { opacity: 0; transform: translateY(8px); }
  to   { opacity: 1; transform: translateY(0); }
}
.element {
  animation: fade-in 400ms ease-out;
}

Users change their intent mid-interaction — menus open then close, dropdowns toggle then toggle back. Non-interruptible animations make the interface feel sluggish. Use transitions for anything the user interacts with.

Timing & Easing Tokens

Define motion durations and easing curves as design tokens:

@theme inline {
  --duration-instant:  50ms;
  --duration-fast:     100ms;
  --duration-moderate: 200ms;
  --duration-slow:     400ms;
  --ease-out:   cubic-bezier(0.0, 0.0, 0.2, 1);
  --ease-in:    cubic-bezier(0.4, 0.0, 1, 1);
  --ease-inout: cubic-bezier(0.4, 0.0, 0.2, 1);
}

Framer Motion

When CSS transitions are not expressive enough — gesture-driven animations, shared layout animations, or orchestrated sequences — use Framer Motion.

Key Framer Motion patterns for design engineers:

Gesture Handling

Touch and pointer gestures need libraries — do not hand-roll drag detection:

Page Transitions

View Transitions API enables smooth page transitions without losing scroll position. Supported in Chromium and Safari.

For crossfade transitions, apply CSS:

::view-transition-old(root) {
  animation: fade-out 200ms ease;
}
::view-transition-new(root) {
  animation: fade-in 200ms ease;
}

Reduced Motion

Always respect the user's motion preference. This is not optional:

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

In Tailwind v4, use the motion-safe: and motion-reduce: variants:

<div
  className="motion-safe:animate-fade-in motion-reduce:opacity-100"
>
  {children}
</div>

Optical Alignment

Geometric centering is not always visually correct. Icons with pointed shapes (triangles, chevrons, arrows) often need a slight offset to look centred next to text or inside a button.

<button className="inline-flex items-center gap-2 px-4 py-2">
  <PlayIcon className="size-4 mr-[1px]" aria-hidden="true" />
  Play
</button>

The same principle applies to button padding: the side with the icon needs slightly less padding than the text-only side because the icon's visual weight sits differently from text. When in doubt, adjust by 1-2px and check with your eyes rather than trusting the math.