Marcus Andrey Study
Ler em português Library

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 tray of motion tokens: three durations laid out as bars whose length is their time, and one easing tile with its curve raised on top. Point at a token and it lifts out of the tray, ready to use; its neighbours lift a little. That's this step: in a motion system, teams pick from a small set of named values instead of inventing a new number on every screen. This step has three lessons: motion tokens, what public motion guidelines teach, and documenting motion in a design system.Illustration: Marcus Andrey, drawn with Hairline (MIT, Lucas Marques).

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

Same distance, same curve (standard), four durations
  • motion.duration.100100 ms · press
  • motion.duration.150150 ms · feedback
  • motion.duration.250250 ms · enter
  • motion.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.

The duration scale, played. Same distance and curve, so the only difference is time: 100 ms feels instant, 350 ms feels like travel. Small changes take the short end, big surfaces the long end. Tick the box again to send them back.Live CSS: one 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

  1. 1Primitive

    Raw values, named by what they are.

    • motion.duration.100 100 ms
    • motion.duration.150 150 ms
    • motion.duration.250 250 ms
    • motion.duration.350 350 ms
    • motion.easing.standard 0.2, 0, 0, 1
    • motion.easing.enter 0, 0, 0, 1
    • motion.easing.exit 0.3, 0, 1, 1
  2. 2Semantic

    A duration and a curve, named by the job.

    • motion.press 100 + standard
    • motion.feedback 150 + standard
    • motion.enter 250 + enter
    • motion.exit 150 + exit
    • motion.enter-large 350 + enter
    • motion.exit-large 250 + exit
  3. 3Component

    Where each job is used.

    • button.press → press
    • button.hover → feedback
    • menu.open → enter
    • menu.close → exit
    • sheet.open → enter-large
    • sheet.close → exit-large
Three tiers of motion tokens: designers pick from the middle one. Primitives hold the numbers, semantic tokens pair a duration with a curve for a job, components point at the job. Change 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, ms or s, 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.fast tells 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)

  1. List five things that move in a product you use every day: a menu, a sheet, a toast, a button press, a page change.
  2. Give each one a job name: enter, exit, feedback, press.
  3. 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 ms and cubic-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

Books, courses and videos to go deeper

Book links go to Amazon. As an Amazon Associate I earn from qualifying purchases, at no extra cost to you.

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

Saved only on this device.

↑ ↓ to move · Enter to open · Esc to close