How to Get Motion Specs for Developer Handoff Right

Interface motion is one of the few parts of a product design that cannot be read off a static mockup. A button press, a sheet sliding up from the bottom of the screen, a toast that fades in and politely leaves: each of these has a duration, an easing curve, a delay and a trigger, and if none of those values are written down, the developer building the screen has to guess them. Getting motion specs for developer handoff right means documenting those values so precisely that two engineers working on different platforms, months apart, would build the same movement the designer intended.

This matters to more people than motion designers. Product managers see it as polish that never quite lands. Engineers see it as a stream of vague feedback ("make it snappier") that costs sprint time. Brand and marketing teams see an app that feels subtly different from one screen to the next, because every component was animated by whoever happened to build it. Without specs, developers guess timing and easing, and interface motion drifts from what designers intended, one small approximation at a time.

This playbook walks through the handoff as a sequence of phases you follow in order. Each phase has a goal, the actions that achieve it, the outputs you should have in hand when it is done, and the checks that tell you it is safe to move on. It is written for design leads and in-house teams preparing a handoff, and for the developers on the receiving end who want to know what a good spec should contain.

The Motion Handoff Playbook at a Glance

Before getting into the detail, here is the whole procedure. The order matters: tokens come before per-transition specs because the specs reference the tokens, and reduced-motion alternatives come before packaging because the reference material must show both versions.

Teams that already have a mature design system can move quickly through phases one and two, but they should not skip them. Even a well-established token set tends to acquire orphan values over time, and the inventory is where those get caught. If your team is starting from zero, it is worth reading our overview of how to build motion systems and guidelines properly alongside this guide, since the handoff is only as good as the system it draws on.

Phase 1: Inventory Every Transition and Its Trigger

Goal: produce a complete list of the motion in the feature being handed off, so nothing is animated by accident or left for a developer to invent.

Most handoff problems begin here, not in the easing curves. A designer prototypes the three or four transitions they care about, and the dozen smaller ones (a disabled button becoming enabled, a validation message appearing, a list item being removed) are never discussed. Developers then either leave those instant, which can feel abrupt next to the carefully animated parts, or animate them with whatever default their framework provides, which introduces timing that nobody chose.

Actions

• Walk every screen and state in the feature, including error, empty, loading and success states, and list anything that changes visually.
• For each change, name the trigger precisely: a tap, a hover, focus arriving via keyboard, a scroll position, a network response, a timer, or another animation finishing.
• Record which properties change: opacity, position, scale, rotation, color, size, or layout. Note when layout changes, because animating layout is usually more expensive to build and to render than animating transform and opacity.
• Decide, explicitly, which changes should not animate at all. "Instant" is a valid spec value and saves arguments later.
• Flag any motion that carries meaning, such as a card flying into a cart icon to confirm an add, separately from purely decorative motion. Meaningful motion needs a reduced-motion equivalent that preserves the meaning.

Outputs

A transition inventory, usually a spreadsheet or a table in your design file, with one row per transition: an ID, the component, the trigger, the properties, and whether it is functional or decorative. Give each transition a stable ID such as sheet.open or toast.dismiss. Those IDs will travel into tickets, code comments and QA notes, and they make conversations far more precise than "the bit where it slides."

Triggers deserve special care, because specs without trigger conditions are one of the most common handoff failures. "Fades in over 200 ms" is incomplete. Fades in when? On page load, when the element scrolls into view, after the data request resolves, or after the previous element finishes? What happens if the trigger fires again while the animation is running: does it restart, reverse from its current position, or ignore the second trigger? Interrupt behavior is where most real-world motion bugs live, and designers rarely think about it unless the inventory forces the question.

Phase 2: Define Motion Tokens Before Writing Any Values

Goal: replace one-off timing decisions with a small, named vocabulary of durations and easing curves that the whole product shares.

Unique timing for every component is the second classic mistake. When each transition gets bespoke values, such as 230 ms here, 275 ms there, and a hand-tuned curve on the modal, the product feels inconsistent in a way users notice even if they cannot name it, and developers end up maintaining dozens of magic numbers. Named motion tokens solve both problems. Material Design is a good public reference here: its motion guidance defines duration and easing tokens so that components across a product draw from one shared set rather than inventing their own.

Durations

Interface animations are usually specified in milliseconds, and the token set should be expressed that way too. Most teams need somewhere between four and eight duration tokens. A typical structure groups them by the size and distance of the change: very small state changes (a checkbox tick, a color shift on hover) sit at the short end, component-level movements (a menu opening, a card expanding) in the middle, and full-screen or large-distance transitions at the long end. The principle behind this is physical: larger objects moving farther take longer to feel natural, and tiny feedback that lingers makes an interface feel sluggish.

Name tokens by role or by scale, not by value. duration.short or duration.medium-2 can be retuned later without renaming anything; a token named duration-250 becomes a lie the moment someone changes it to 220.

Easing curves

Easing curves can be expressed as CSS cubic-bezier() values, which is the most portable way to hand them off. A cubic Bezier curve is defined by four numbers, the x and y coordinates of two control points, and nearly every platform can consume those four numbers directly or convert them. The MDN Web Docs reference on easing functions documents the syntax and the named keywords, which are themselves shorthands for specific curves: ease is cubic-bezier(0.25, 0.1, 0.25, 1), ease-in is cubic-bezier(0.42, 0, 1, 1), ease-out is cubic-bezier(0, 0, 0.58, 1), and ease-in-out is cubic-bezier(0.42, 0, 0.58, 1).

Most products need three to five easing tokens, organized by purpose:

• Standard for elements that move from one on-screen position to another, typically an ease-in-out shape.
• Enter or decelerate for elements arriving on screen, which should start fast and settle gently, an ease-out shape.
• Exit or accelerate for elements leaving, which start gently and speed away, an ease-in shape. Exits are often slightly shorter than entrances, because users care less about watching something leave.
• Emphasized (optional) for a small number of hero moments where a more expressive curve is justified.
• Linear reserved for continuous motion such as progress indicators and spinners, where easing would look like stuttering.

If your team is still debating why these shapes feel right, our piece on getting motion design principles right covers the reasoning behind acceleration, deceleration and hierarchy in more depth.

Outputs

A token table like the one below, published somewhere both designers and developers can see it, ideally in the same source as your color and spacing tokens. The values in this table are an illustrative starting point, not a standard; tune them against your own product.

Phase 3: Write the Per-Transition Spec

Goal: give developers, for every transition in the inventory, the exact values they need to build it without guessing.

This is the core of motion specs for developer handoff, and the rule is simple: specify duration, easing and delay for every transition, and express each one as a token. A complete spec entry answers seven questions.

Trigger

The event that starts the animation, and the interrupt rule if it fires again mid-animation.

Target

The element or elements that move, named as components or layers the developer will recognize.

Properties

What changes: opacity, translate, scale, rotation, color, size.

From and to values

Start and end states in real units: opacity 0 to 1, translateY 16 px to 0, scale 0.95 to 1.

Duration

A duration token, with the resolved millisecond value in brackets for convenience.

Easing

An easing token, with its cubic-bezier value in brackets.

Delay

Zero, a fixed delay, or a stagger rule for groups.

Choreography and staggers

Single transitions are easy to spec. Choreographed ones, where several elements move in sequence, are where written specs earn their keep. Rather than listing an absolute start time for every element, describe the rule: "list items enter with easing.enter over duration.medium, each item delayed 30 ms after the previous, capped at the first eight items; items beyond eight appear with the eighth." That cap matters. Without it, a list of fifty items staggers for a second and a half, and a developer building from a video of six items would never know the problem exists.

When a transition involves properties moving on different timings, such as a dialog whose scrim fades while the panel scales, spec each property separately and state how they relate: "scrim opacity starts at 0 ms; panel scale and opacity start at 0 ms; panel shadow starts at 100 ms." A small timing diagram, a horizontal bar per property on a millisecond axis, communicates this far better than prose and is quick to draw in any design tool.

Units, platforms and the details that bite

• State distances in the units your platforms use (CSS pixels, points on iOS, density-independent pixels on Android) or in a unit your design system maps to all three.
• Prefer transform and opacity changes over layout changes where the design allows. Say so in the spec when a layout animation is genuinely required, so engineering can plan for it.
• Specify the transform origin for scale and rotation. A menu scaling from its top-left corner and one scaling from its center look like two different designs.
• For spring-based motion, give the spring parameters your target frameworks accept, and a cubic-bezier approximation for platforms that do not support springs.
• Note text behavior. Animated text needs to remain readable while it moves; if a heading slides in, it should settle quickly. Our guide to text legibility in motion covers the thresholds worth respecting.

Outputs

One spec entry per inventory row, stored with the design file or in the component documentation, not buried in a chat thread. A simple, consistent format beats a clever one. Many teams use a table per component with a row per transition; others annotate frames directly in the design tool with a spec panel. Either works if every entry has all seven fields.

Phase 4: Specify Reduced-Motion Alternatives

Goal: make sure every transition has a defined behavior for users who have asked their operating system to reduce motion.

Ignoring reduced-motion needs is a mistake that is both common and consequential. Large movements, parallax, zooms and spinning elements can cause discomfort, dizziness or nausea for people with vestibular disorders, and every major operating system offers a setting to reduce motion. On the web, that preference is exposed to CSS through the prefers-reduced-motion media feature, documented on MDN; native platforms expose equivalent accessibility flags. Specs should include alternatives for prefers-reduced-motion, and they should be designed rather than improvised by the developer on the night before release.

Deciding what each transition becomes

Reduced motion does not mean no motion. It means removing or replacing movement that could trigger symptoms while preserving the information the motion carried. For each spec entry, choose one of these patterns:

1. Keep as is. Small opacity and color changes rarely cause problems and often help comprehension. A 100 ms fade on a button state change can usually stay.
2. Replace movement with a fade. A sheet that slides up 600 px can instead cross-fade into place over a short duration. The user still sees that something new arrived.
3. Shorten and flatten. A scale-and-translate entrance becomes a shorter opacity change with no position change.
4. Remove entirely. Decorative parallax, background loops and autoplaying flourishes should simply stop.
5. Replace with a static indicator. A spinning loader might become a pulsing opacity change or a static progress message.

The functional-versus-decorative flag from Phase 1 pays off here. Decorative motion is usually removed; functional motion is usually translated into a gentler form that keeps the meaning. For a more complete treatment of the risks, including flashing content and photosensitivity thresholds, see our practical guide to motion accessibility and photosensitivity.

Outputs

A reduced-motion column added to every spec entry, and reduced-motion variants in the token set if you use them (for example, a rule that all translate distances become zero and all durations above duration.medium fall back to duration.short). Encoding the rule at token level means developers implement it once, globally, rather than remembering it component by component.

Phase 5: Package Prototypes and Reference Videos

Goal: give developers a clear picture of how the motion should feel, without letting the picture replace the numbers.

Handing off only a video is the mistake that sits behind many failed motion handoffs. A screen recording of a prototype looks complete, and it is genuinely useful for conveying feel, but it hides almost everything a developer needs. Frame rates round timings. Compression smears easing. Triggers, interrupts and edge cases do not appear at all. An engineer scrubbing through a video frame by frame to estimate a duration is doing reverse engineering that the designer could have avoided by writing down one number.

Reference material still has a job, and it is an important one. Provide reference videos or prototypes, but treat them as illustrations of the written spec, never as the spec itself.

What to include

• An interactive prototype for flows where interaction matters, so developers can trigger transitions themselves and feel the timing.
• Short reference clips, one per transition or choreographed sequence, named with the transition ID so they can be matched to the spec.
• A slowed-down version of complex sequences, at a stated fraction of real speed, so overlapping movements can be seen clearly.
• A reduced-motion clip for each transition where the alternative is not trivially obvious.
• Edge-case demonstrations for interrupt behavior: what happens if the user taps close while the sheet is still opening.

Label every clip with the frame rate it was exported at, and state in the handoff notes that where the video and the written spec disagree, the written spec wins. If your team exports reference clips from a motion tool rather than a prototyping tool, the export settings matter; our article on rendering and output for motion covers frame rate and codec choices that keep reference material honest.

Phase 6: Run the Handoff Session and Map Tokens to Code

Goal: make sure developers understand the spec, can implement the tokens on every platform, and have raised their questions before building rather than after.

A written spec does not remove the need for a conversation; it makes the conversation short and productive. Schedule a session of thirty to sixty minutes with the designer who owns the motion and the engineers who will build it. Walk the inventory, play the reference clips, and let engineers challenge anything that looks expensive or ambiguous.

Actions

• Confirm where the tokens will live in code. On the web, CSS custom properties are the natural home: one variable per duration and easing token, consumed by every transition and animation declaration. Native platforms usually get a constants file or theme object generated from the same source.
• Agree whether tokens will be generated automatically from the design token source or maintained by hand. Automatic generation prevents drift; hand maintenance is acceptable for small teams if one person owns it.
• Identify platform gaps. If one platform cannot do spring physics, or a framework handles interrupts differently, agree the fallback now and record it in the spec.
• Flag performance risks. Animating layout, large blurs or shadows on low-end devices may not hit a smooth frame rate. Engineering should say which transitions they are worried about so the designer can offer a cheaper alternative.
• Assign each transition to a ticket, using the transition ID, and link the spec entry and reference clip from the ticket.

Outputs

Token definitions in the codebase, a short list of agreed platform exceptions appended to the spec, and tickets that link back to specific spec entries. The spec is now a living document shared by both disciplines, not a one-way deliverable.

A useful shortcut: ask one engineer to build a single representative transition, typically the most complex one, during the week of the handoff session. Reviewing that one build together surfaces almost every misunderstanding in the spec while it is still cheap to fix.

Phase 7: Review the Built Animation Against the Spec

Goal: confirm that what shipped matches what was specified, and catch drift before users see it.

Review built animations against the spec as a formal step, not as an afterthought during general design QA. Motion is easy to miss in a quick click-through, and subtle problems (a wrong easing curve, a missing delay, a transition that restarts instead of reversing when interrupted) only show up when someone checks deliberately.

How to review

1. Check the code first. Confirm transitions reference tokens rather than raw values. A quick search for hard-coded millisecond values in style files finds most deviations in minutes.
2. Inspect in the browser or on device. Browser developer tools can slow animations down and show easing curves for CSS transitions, which makes it easy to confirm the curve and duration match the spec.
3. Test triggers and interrupts. Trigger each transition, then re-trigger it mid-animation, and compare the behavior with the spec's interrupt rule.
4. Test reduced motion. Turn on the operating system's reduce-motion setting and walk every transition again.
5. Test on a slower device. Motion that is smooth on a developer laptop can stutter on an older phone. Note dropped frames against the transition ID.
6. Log deviations by ID. Record each issue with the transition ID, the expected value from the spec and the observed behavior, so fixes are unambiguous.

Be disciplined about the difference between a deviation and a design change. If the built animation matches the spec but the designer now thinks it should be different, that is a spec change: update the spec and the tokens first, then the code. Fixing it only in code reintroduces exactly the drift the process was meant to prevent.

If a motion change is made only in code, the spec stops describing the product, and the next developer is back to guessing.

Phase 8: Keep the Motion System Maintained

Goal: ensure the next feature extends the motion system rather than forking it.

A handoff is not a one-time event. Every new feature brings new transitions, and each is an opportunity either to reuse tokens or to invent new values. Keep the token table versioned alongside the rest of the design system, and require that any new token be proposed and justified rather than simply added. When a new pattern appears in two or more features, promote it to a documented pattern with its own spec template: "bottom sheet," "inline expansion," "toast." Future handoffs for those patterns then shrink to a reference and a list of any differences.

Motion specs also travel beyond the product. Brand teams often want interface transitions echoed in marketing videos, presentations and social assets. If you share the token table with those teams, the timing of an explainer video can feel related to the app it demonstrates. Our guides to localizing motion graphics and to real-time work such as motion graphics in game engines show how the same discipline of named, documented values carries over to other contexts, from longer translated text to engine-driven animation.

Outputs and checks

A versioned token source, a changelog of motion decisions, a small library of documented patterns, and an agreed owner. The key check is simple: when you search the codebase for raw durations and easing values, the number should be falling over time, not rising.

A Realistic Schedule for a Motion Spec Handoff

How long this takes depends mostly on whether tokens already exist and how many transitions the feature contains. The schedule below assumes a mid-sized feature, roughly fifteen to twenty-five transitions, on a team that is defining its motion tokens for the first time. Teams with an existing token set can usually compress the first week considerably.

The spec-writing phase is the one most often squeezed, and squeezing it is a false economy. Every hour saved there tends to return as several hours of back-and-forth during implementation, spread across more people.

Worked Example: Specifying a Checkout Bottom Sheet

To make the playbook concrete, here is an illustrative example, not a client project: a mobile web checkout where tapping "Choose delivery" opens a bottom sheet listing delivery options. The sheet contains a heading, five option rows and a confirm button. The team uses the token table from Phase 2.

Inventory

The designer walks the flow and finds seven transitions, not the two that appeared in the original prototype: sheet.open, sheet.close, scrim.show, scrim.hide, options.enter (the staggered rows), option.select (a row's checkmark and highlight) and confirm.enable (the button changing from disabled to enabled once an option is chosen). The last two would almost certainly have been left to developer judgment without the inventory.

The spec

The numbers that matter

Adding up the choreography: the sheet takes 300 ms to open. Rows begin entering when the sheet is half open, at 150 ms. With five rows at a 30 ms stagger, the last row starts at 150 + 4 x 30 = 270 ms and finishes 200 ms later, at 470 ms. The whole entrance is therefore complete in under half a second, which keeps the sheet feeling responsive, and the stagger cap means that if the business later adds three more delivery options, the entrance does not grow to 560 ms. The closing transition deliberately uses the shorter duration.medium with the exit curve, so the sheet leaves in 200 ms, faster than it arrived.

With reduced motion on, the same sheet appears as a 100 ms fade with every row present immediately. The user still gets a clear signal that a new panel has opened, but nothing slides or staggers.

What review found

In this illustrative review, the designer checks the build and logs two deviations: sheet.close used easing.enter instead of easing.exit, making the dismissal feel sticky, and tapping the scrim during sheet.open restarted the close from the fully open position instead of reversing from the current one, producing a visible jump. Both were fixed in minutes because the log named the transition ID, the expected value and the observed behavior.

Diagnosing the Handoff Failures This Example Avoids

When motion in a shipped product feels wrong, the cause usually traces back to one of a handful of gaps. The table below maps the symptoms people report to the likely cause and the phase of this playbook that fixes it.

Notice that none of these failures are really about talent. Skilled designers and skilled engineers produce all of them when the process between them is missing a step. That is why a written, phase-by-phase approach tends to outperform heroic individual effort.

When to Bring In a Motion Specialist

Many teams can run this playbook themselves for a single feature. The point where outside help pays off is when you are building a motion system for a product team: defining the token set, the patterns and the reduced-motion rules that dozens of engineers and several designers will rely on for years. Getting those foundations right is a specialized job, and mistakes compound, because every feature built on a weak token set inherits its problems.

Signs that it is time to bring in help include a codebase full of hard-coded animation values that nobody wants to touch, a brand refresh that needs interface motion to match new marketing animation, a multi-platform product where web, iOS and Android have visibly drifted apart, and accessibility reviews that keep flagging motion. A studio with both motion design and production experience can audit the current state, propose a token set, write the first round of specs as templates, and train the in-house team to keep going. Our animation and motion graphics services cover this kind of engagement alongside brand and marketing motion, and our wider library of motion graphics and animation articles goes deeper into the related craft decisions.

Whichever route you take, the principle stays the same: motion is a design decision with specific values, and those values belong in a document both disciplines trust, not in a video that one side has to decode.

Where this comes from

• Material Design — Motion
• MDN Web Docs — easing-function

The figures and practices above come from the sources listed.

Working on something like this?

We take on Motion Graphics & Animation work for teams who want it done once, properly. Tell us what you are building and we will tell you honestly whether we are the right studio for it. Start a project.

Where to go next

• How to Get HTML5 Animated Banner Ads Right
• Texture and Grain in Animation: What Actually Works