Designers
Animation handoff: how to give developers a motion spec they can build
Animation handoff for designers: what a motion spec needs, a spec table template, motion tokens as CSS custom properties, and how to review the build against it
A designer finishes a prototype where a panel slides in with a soft overshoot and the content follows a beat later. A developer builds it. It moves, but it feels wrong: too slow, too linear, everything arriving at once. Nobody did a bad job. The numbers simply never made it across.
Good animation handoff fixes that. This guide covers why videos and prototypes lose information, what a motion spec should contain, a table template you can copy, how to name motion tokens, and how to check the shipped build against the spec.
Why videos and prototypes lose the numbers
A screen recording shows the feel of an animation, but a developer cannot read a duration or a curve off it. At 30 or 60 frames per second, a 200 ms transition is six to twelve frames. The difference between ease-out and a sharper custom curve is almost invisible frame by frame, and it is the difference that makes the motion feel right.
Prototypes are better, because the values exist somewhere. But they are spread across interactions and layers, and a developer has to click through each one to find them. Some tools describe easing with names that do not match CSS, or with spring settings that have no direct CSS equivalent. Delays between elements, the part that creates a stagger, are often the first thing to go missing.
The result is that developers fill gaps with defaults. The default in CSS is ease, and most libraries have their own. Defaults are why built animations so often look generic.
What a good motion spec contains
For each animated element, a developer needs seven things:
- Trigger. What starts it: page load, entering the viewport, hover, focus, click, a state change such as "item added". Say what reverses it too, if anything.
- Properties. Which properties change. Prefer
transformandopacity; they animate smoothly. If the design needs height or blur, say so, so it can be discussed early. - From and to values. Exact numbers with units:
translateY(16px) → 0,opacity 0 → 1,scale .96 → 1. Add intermediate keyframes if the motion overshoots. - Duration in milliseconds.
- Delay in milliseconds, measured from the trigger.
- Easing as
cubic-bezier(x1, y1, x2, y2), orlinearfor loops. - Reduced motion behaviour. What happens when the user has asked for less motion: removed, replaced by a fade, or shortened.
For groups, add the stagger: the delay added per item, the order (first to last, from the centre, from the clicked item) and whether there is a cap so that a list of 40 items does not take four seconds to appear.
Give easing as numbers rather than names. "Ease out" means one curve in CSS, a different one in Figma and another in GSAP. cubic-bezier(.2, .8, .2, 1) means the same thing everywhere. The CSS easing functions guide explains how to read the four numbers, and this guide shows how to find the curve of an animation you like.
A spec table template
A table is the most useful format because it maps almost line for line to code. Here is a spec for a modal opening:
| Element | Trigger | Property | From → to | Duration | Delay | Easing | Reduced motion |
|---|---|---|---|---|---|---|---|
| Backdrop | Open | opacity | 0 → 1 | 200 ms | 0 | linear | Keep |
| Dialog | Open | opacity | 0 → 1 | 240 ms | 40 ms | cubic-bezier(.2, .8, .2, 1) | Keep |
| Dialog | Open | transform | translateY(24px) scale(.97) → none | 320 ms | 40 ms | cubic-bezier(.2, .8, .2, 1) | Remove |
| Dialog items | Open | opacity, translateY(8px → 0) | as listed | 200 ms | 120 ms + 40 ms per item, max 5 | cubic-bezier(.2, .8, .2, 1) | Fade only, no stagger |
| Dialog | Close (Esc, backdrop, button) | opacity, transform | reverse of open | 160 ms | 0 | cubic-bezier(.4, 0, 1, 1) | Fade only |
A few habits make this easier to build from:
- One row per property when timings differ. The dialog's fade and movement have different durations, so they get two rows. When they share timing, combine them.
- Write exits separately. Exits are usually shorter and use an accelerating curve. If you do not specify them, they will be the entrance played backwards, which tends to feel slow.
- Attach a slowed-down recording at 25% or 10% speed. It shows the relationship between elements that a table cannot, and the table gives the numbers the video cannot.
Name motion tokens
If your product has more than a handful of animations, the same durations and curves should repeat. Naming them turns a spec row like "320 ms, cubic-bezier(.2, .8, .2, 1)" into "duration-slow, ease-out-standard", which is easier to review and keeps things consistent. A small set is enough:
:root {
/* durations */
--duration-instant: 80ms; /* colour and opacity feedback */
--duration-fast: 150ms; /* hover, press, small toggles */
--duration-base: 240ms; /* dropdowns, tooltips, tabs */
--duration-slow: 320ms; /* modals, drawers, page sections */
/* easing */
--ease-out-standard: cubic-bezier(.2, .8, .2, 1); /* entering */
--ease-in-standard: cubic-bezier(.4, 0, 1, 1); /* leaving */
--ease-in-out-standard: cubic-bezier(.65, 0, .35, 1); /* moving on screen */
/* stagger */
--stagger-step: 40ms;
}
@media (prefers-reduced-motion: reduce) {
:root {
--duration-base: 1ms;
--duration-slow: 1ms;
--stagger-step: 0ms;
}
}
.dialog {
transition:
opacity var(--duration-base) var(--ease-out-standard),
transform var(--duration-slow) var(--ease-out-standard);
}
Name tokens by role, not by value. --duration-fast can change from 150 ms to 120 ms across the whole product in one place; --duration-150 cannot. Keep the same names in your design tool, so the spec and the code use one vocabulary.
Overriding the duration tokens under prefers-reduced-motion is a blunt default, not a full answer. Some motion carries meaning and should become a fade rather than vanish, which is why the spec table has its own column for it. The reduced motion guide covers how to decide.
Review the build against the spec
Handoff does not end when the ticket is closed. Plan a short motion review, the same way you would check spacing and colour.
- Watch it at real speed first. Does it feel right? If yes, the numbers are probably close. If not, keep going.
- Slow it down. Chrome's Animations panel can play CSS animations, transitions and Web Animations API animations at 25% or 10% speed. Order and overlap problems become obvious. The DevTools guide shows where to find it.
- Read the real values. Compare duration, delay and easing for each row of your spec. The most common bugs are a missing delay, a default
easewhere a custom curve was specified, and an exit that is just the entrance reversed. - Turn on reduced motion in the operating system and check the last column of the table.
Reading values by hand gets slow when an interaction animates a dozen properties, or when it is driven by a JavaScript library that DevTools cannot show. This is where Capture Motion helps: open the staging or live page, start the Chrome extension and trigger the interaction. It records the animation while it plays and lists the keyframes, duration, delay and easing of every animated property, including hover states, which it captures by setting a real :hover state. You get a table of what actually shipped to hold up against what you specified.
Bring the shipped motion back into Figma
Motion also needs to travel the other way. When the build has been tuned in code, or when you are redesigning a screen that already animates, the source of truth is the live site, not the old design file.
Capture the animation, copy the JSON export, and paste it into the Capture Motion Figma plugin. It rebuilds the animation as a Figma Motion timeline, with the same timing and easing as the site. Your next iteration then starts from what users see today. The Figma import guide walks through the steps, and this page explains the plugin.
A short checklist
- Every animated element has a trigger, properties, from and to values, duration, delay and easing.
- Easing is written as
cubic-bezier()numbers orlinear, never just a name. - Staggers state the step, the order and a cap.
- Exits are specified separately from entrances.
- Each row says what happens under reduced motion.
- Repeated values use named tokens shared between design and code.
- A slowed-down recording is attached for feel.
- The build is reviewed against the table before release.
None of this takes long once it is a habit, and it saves the rounds of "can you make it a bit snappier" that eat up review time on both sides.
Questions
What should an animation handoff include?
For each animated element: the trigger, the properties that change with their from and to values, duration, delay, easing as a cubic-bezier, any stagger, and what happens when reduced motion is on. A video is useful for feel, but it is not a spec.
Why give easing as cubic-bezier instead of a name?
Names like ease-out mean different curves in different tools. Four cubic-bezier numbers mean the same curve in CSS, the Web Animations API, Figma and most animation libraries, so nothing has to be guessed.
How do I check the built animation matches my design?
Slow the page down in Chrome DevTools to see the motion clearly, then read the real timing values. Capture Motion records the shipped animation and lists the duration, delay and easing of every animated property, so you can compare them row by row with your spec.
Can I bring an animation from a live site back into Figma?
Yes. Capture the animation with the Capture Motion Chrome extension, copy the JSON export, and paste it into the Capture Motion Figma plugin, which rebuilds it as a Figma Motion timeline.
