Motion and Interaction · Step 7 · 7 min read
Motion tokens
A duration typed by hand is a decision nobody can find again. How to turn durations and curves into a small set of named tokens, in three tiers, in the W3C community format and in CSS, with reduced motion built in.
A motion token is a decision with a name, so the next person doesn't have to make it again. Open any product's code and search for
ms. You'll find 180, 200, 220, 250 and 300, often for the same kind of thing, each typed by someone who was guessing in good faith. Colour and spacing became tokens years ago. Motion is the same problem, and the fix is the same: a few named values, picked once, used everywhere.
What you'll be able to do after reading:
- Explain why durations and curves belong in tokens
- Organise motion tokens in three tiers: primitive, semantic, component
- Write them in the W3C community format and in CSS
- Build the reduced-motion version into the tokens, not into every component
1. Why motion needs tokens
motion.duration.100100 ms · pressmotion.duration.150150 ms · feedbackmotion.duration.250250 ms · entermotion.duration.350350 ms · enter-large
Your system asks for reduced motion, so the dots jump instead of gliding. That is the behaviour a reduced-motion token should give you.
transition per lane, transform: translateX(). Marcus Andrey, CC BY 4.0.Everything in this course so far has been a value: a duration from Duration: how long is right, a curve from Easing curves, a fallback from Designing a reduced-motion version. Values typed by hand drift. Two menus open at 200 and 250 ms, a sheet closes slower than it opens, and nobody decided any of it.
Tokens fix three things at once:
- Consistency. The same job moves the same way everywhere, so people learn it once.
- Change. If 250 ms feels slow after testing, you change one value, not forty files.
- Conversation. "Use
motion.enter" is a sentence a designer and a developer both understand. "Make it snappier" isn't.
The figure plays a small duration scale. Four steps are enough for most products: one for a press, one for feedback, one for things entering, one for large surfaces.
2. Three tiers
- 1Primitive
Raw values, named by what they are.
motion.duration.100100 msmotion.duration.150150 msmotion.duration.250250 msmotion.duration.350350 msmotion.easing.standard0.2, 0, 0, 1motion.easing.enter0, 0, 0, 1motion.easing.exit0.3, 0, 1, 1
- 2Semantic
A duration and a curve, named by the job.
motion.press100 + standardmotion.feedback150 + standardmotion.enter250 + entermotion.exit150 + exitmotion.enter-large350 + entermotion.exit-large250 + exit
- 3Component
Where each job is used.
button.press→ pressbutton.hover→ feedbackmenu.open→ entermenu.close→ exitsheet.open→ enter-largesheet.close→ exit-large
motion.enter once and every menu and page that enters changes with it.Diagram: Marcus Andrey, CC BY 4.0. Curves from Material Design 3 (standard, standard decelerate, standard accelerate).Motion tokens work best in the same tiers as colour tokens (see What a design system is):
| Tier | Holds | Named by | Example |
|---|---|---|---|
| Primitive | One raw value | What it is | motion.duration.250 = 250 ms |
| Semantic | A duration and a curve together | The job | motion.enter = 250 ms + enter curve |
| Component | A pointer to a semantic token | Where it's used | menu.open → motion.enter |
Designers and developers pick from the semantic tier. Primitives are the palette; nobody should type motion.duration.250 in a component, because it says how long, not why.
Two rules make the semantic tier useful:
- Pair the duration and the curve. A duration on its own invites the wrong curve. "Enter" means 250 ms and decelerate.
- Exits are shorter than entrances. People wait for what's coming, not for what's leaving. Atlassian writes it as a rule: start motion immediately, and make exits faster than entrances (Atlassian Design System, Motion).
The curves in this kit are Material Design 3's standard, standard decelerate and standard accelerate: cubic-bezier(0.2, 0, 0, 1), (0, 0, 0, 1) and (0.3, 0, 1, 1) (Material Components, Motion). Borrowing published curves is fine; the next lesson shows what each system chose.
3. Tokens in the W3C community format
The Design Tokens Community Group's format is the shared file format most token tools read. Its first stable version, 2025.10, defines a duration type, a cubicBezier type, and a transition type that combines a duration, a delay and a curve (DTCG, Design Tokens Format Module 2025.10). It's a Community Group report, not a W3C Standard, but it's what tools are converging on.
{
"motion": {
"duration": {
"250": { "$type": "duration", "$value": { "value": 250, "unit": "ms" } }
},
"easing": {
"enter": { "$type": "cubicBezier", "$value": [0, 0, 0, 1] }
},
"enter": {
"$type": "transition",
"$value": {
"duration": "{motion.duration.250}",
"delay": { "value": 0, "unit": "ms" },
"timingFunction": "{motion.easing.enter}"
}
}
}
}
Three details from the spec worth knowing:
- A duration is an object with a number and a unit,
msors, not a string like"250ms". - A cubic Bézier is four numbers. The two x values must be between 0 and 1; the y values can go outside, which is how overshoot curves are written.
- Curly braces are references:
"{motion.duration.250}"points at the primitive, so the semantic token changes when the primitive does.
The format has no type for springs. If you use springs (see Springs and physics), store their parameters as numbers and document them. Material does exactly that on Android: each spring token is a damping ratio and a stiffness, such as 0.9 and 1400 for small, fast movement (Material Components, Motion).
4. Tokens in CSS
On the web, tokens usually arrive as custom properties. This is the kit the button in Animate a button's states runs on, exactly as it is in this site's CSS:
.mo-d-kit {
--motion-duration-feedback: 150ms;
--motion-duration-press: 100ms;
--motion-easing-standard: cubic-bezier(0.2, 0, 0, 1);
}
And the figure in section 1 is one rule. Each lane sets --d to a token's duration and --e to its curve:
.mo-d-lane__run { display: block; width: 100%; height: 100%; transition: transform var(--d) var(--e); }
.mo-d-play:has(.mo-d-go:checked) .mo-d-lane__run { transform: translateX(calc(100% - 1.5rem)); }
@media (prefers-reduced-motion: reduce) { .mo-d-lane__run { transition: none; } }
5. Reduced motion lives in the tokens
If every component writes its own reduced-motion rule, some will forget. Put the decision in the semantic tier instead: each token has a normal value and a reduced one.
A useful split comes from Material's spring tokens, which come in two kinds: spatial, for position and size, and effects, for opacity and colour, which "should not be overshot" (Material Components, Motion). The same line works for reduced motion: under prefers-reduced-motion: reduce, spatial movement goes, effects stay. A sheet stops sliding and fades; a hover still changes colour. That matches WCAG, whose definition of motion animation leaves out colour and opacity changes that don't change size, shape or position (W3C, Understanding 2.3.3).
In practice, one reduced token is often enough: a 150 ms fade. Every semantic token that moves something falls back to it.
6. Common mistakes
- Tokens named by value at the semantic tier:
motion.fasttells nobody what it's for. - A duration token with no curve next to it, so every team picks its own.
- Ten durations "to be safe". If two are 20 ms apart, nobody can see the difference; merge them.
- Exits as long as entrances.
- Reduced motion handled component by component, and missing in half of them.
- Tokens in Figma and in code with different values.
7. Vocabulary
| Term | Meaning |
|---|---|
| Motion token | A named duration, curve or combination, used instead of a raw value |
| Primitive token | A raw value named by what it is: motion.duration.250 |
| Semantic token | A token named by its job: motion.enter |
| Component token | A component's pointer to a semantic token: menu.open |
| Reference | A token whose value points at another: "{motion.duration.250}" |
| DTCG | The Design Tokens Community Group and its shared token file format |
8. Try it (no tools needed)
- List five things that move in a product you use every day: a menu, a sheet, a toast, a button press, a page change.
- Give each one a job name: enter, exit, feedback, press.
- How many different jobs did you end up with? That's roughly your semantic tier.
Reflection questions: Which two animations in your product do the same job but move differently? Which would you change to match the other, and why?
9. If you already practise
- Search your codebase for
msandcubic-bezier. Group what you find by job; that's your first token list, and your migration plan. - Keep the semantic tier small, five to eight tokens, and add only when a request can't be met by an existing one.
- Export tokens from one source to both Figma variables and CSS, so they can't drift.
- Write the reduced value next to the normal one in the token file, not in a separate document.
Checklist
Learn more
- DTCG, Design Tokens Format Module 2025.10: the
duration,cubicBezierandtransitiontypes - Material Components for Android, Motion: easing, duration and spring tokens with their values
- Atlassian Design System, Motion: semantic motion tokens and duration ranges
- W3C, Understanding SC 2.3.3 Animation from Interactions
- MDN, prefers-reduced-motion
Books, courses and videos to go deeper
- Designing Interface AnimationVal HeadBook · Rosenfeld Media, 2016 (Amazon)
- Including Animation In Your Design SystemVal HeadSmashing Magazine, free article (external site)
Book links go to Amazon. As an Amazon Associate I earn from qualifying purchases, at no extra cost to you.
Related
What public motion guidelines teach · Write a set of motion tokens · Duration: how long is right · Easing curves · Springs and physics · What a design system is · Duration scale