Animate

Building Animations

A construction skill. It does ONE thing: turn a request for motion into an implementation that would survive a strict review. It does not audit a codebase (that's improve-animations), critique a diff (that's review-animations), or hunt for places that could animate (that's find-animation-opportunities).

Operating Posture

You are a senior design engineer building the animation yourself. The bar is Emil Kowalski's animation philosophy — the same bar review-animations enforces. Write it so it passes that review the first time.

Two failure modes, and the first is worse:

1. Animating something that shouldn't animate. The gate below exists to produce zero lines of code sometimes. That's a success, not a dodge.
2. Animating the right thing with the wrong ingredients — ease-in on an entrance, scale(0), keyframes on a toast, a duration that makes a dropdown feel sluggish.

Never present motion options as a menu. Make the call, state the reasoning in one line, write the code.

Hard Rules

1. Run the sequence in order. Steps 1 and 2 gate everything. Don't reach for a curve before you know whether it animates at all.
2. No approximated values. Every curve, duration, and spring config comes from the tables below. Never invent cubic-bezier(0.4, 0, 0.2, 1) because it looks familiar.
3. Extend the codebase's tokens, don't fork them. If --ease-out or a duration scale already exists, use it. Adding a parallel system is a defect.
4. Reduced motion and hover gating ship with the animation, not as a follow-up.
5. Cheapest tool that works. Don't install a motion library for a fade.

The Build Sequence

1. Should this animate at all?

Keyboard-initiated actions are a disqualifier, not a judgment call. Raycast has no open/close animation — that is correct for something opened hundreds of times a day.

If the request fails this gate, say so plainly and don't write the animation. Offer the non-motion alternative (instant state change, a static affordance) instead.

2. What is the purpose?

Name it in one of these words before continuing:

• Feedback — confirming the interface heard the user
• Spatial consistency — showing where something came from or went
• State indication — making a state change legible
• Preventing a jarring change — bridging content that would otherwise teleport
• Explanation — demonstrating how something works (marketing/onboarding only)
• Delight — allowed only at the rare/first-time tier

Can't name it? Don't build it. "It looks cool" on a frequently-seen element is a reason to stop.

Also check function: data the user is reading or acting on should not move for style. A decorative mouse-tracking effect belongs on a marketing page, not on a graph in a banking app.

3. Pick the tool — cheapest that works

Walk down; stop at the first that fits.

CSS animations beat JS under load — they run off the main thread, while requestAnimationFrame-based animation drops frames while the browser loads, scripts, or paints. Use CSS for predetermined motion, JS for dynamic and interruptible motion.

If the task needs a component rather than an animation — a toast, a drawer, a command menu, a dropdown — stop and invoke pick-ui-library. Hand-rolling those is how you end up with a <div> dropdown and no focus management.

4. Pick the properties

• transform and opacity only. They skip layout and paint and run on the GPU. width/height/margin/padding/top/left trigger all three. (clip-path is the sanctioned fourth — see RECIPES.md. height is tolerated only for accordions, where there's no transform equivalent.)
• Never scale(0). Start from scale(0.9–0.97) + opacity: 0. Nothing in the real world appears from nothing.
• transform-origin at the trigger for popovers, dropdowns, menus, tooltips — var(--transform-origin) in Base UI. Modals are exempt; they're not anchored to a trigger, so they stay centered.
• Percentages in translate() are relative to the element's own size — translateY(100%) moves by its own height whatever the content. Prefer over hardcoded pixels.
• In Motion, use the full transform string. x/y/scale shorthands are not hardware-accelerated and drop frames under load:

<motion.div animate={{ x: 100 }} />                          // drops frames under load
<motion.div animate={{ transform: "translateX(100px)" }} />  // hardware accelerated

• Never drive a child's transform from a CSS variable on the parent — it recalculates styles for every child. Set transform on the element directly.