Marcus Andrey Study
Ler em português Library

Motion and Interaction · Labs · 3 min read

Write a set of motion tokens

A guided lab: collect every duration and curve a product uses, group them by job, reduce them to a small scale, name semantic tokens, add reduced-motion values, and write the set in the DTCG format and in CSS. About two hours, with a codebase or a set of screens and a spreadsheet.

Most products already have motion tokens. They're just hidden in forty files, with forty slightly different values. You'll find them, group them by what they do, and reduce them to a set small enough to remember. The result is one table and one file that a designer and a developer can both use tomorrow.

What you'll do:

  • Collect the durations and curves a product uses today
  • Group them by job and pick a small scale
  • Name semantic tokens and give each a reduced-motion value
  • Write the set in the DTCG format and as CSS custom properties

You'll need: access to a codebase (or, if you don't have one, ten screens of a product you can record), a spreadsheet, a text editor, about two hours.


1. Collect what's there

Search the code for ms, s;, cubic-bezier, ease and transition. No code? Record ten interactions of an app and estimate each one by counting frames in a screen recording.

Put each one in a row: where (component), what moves, duration, curve. Expect surprises: most teams find six to twelve durations for three or four jobs.


2. Group by job

Add a column, job, and use only these words: press, feedback, enter, exit, and enter-large and exit-large for sheets, drawers and dialogs. If something doesn't fit, ask whether it should move at all (see When not to animate).

Then sort by job. Every group with more than one duration is a decision nobody made.


3. Pick the scale

For each group, choose one duration. Use the guidance from What public motion guidelines teach:

  • Frequent feedback stays under 150 ms (Atlassian, Motion).
  • Bigger and farther takes longer, but transitions stay at or under about 400 ms.
  • Exits are shorter than entrances.
  • Merge values less than 50 ms apart. People won't feel the difference; you'll still have to maintain it.

You should end with four to six primitive durations. Pick three curves: standard, enter (decelerate), exit (accelerate). Borrow them from a public system and write down which.


4. Name the semantic tokens

TokenDurationCurveUse it forUnder reduced motion
motion.feedback150 ms standardHover, colour, small fadesSame (no movement)
motion.press100 ms standardPress: a button giving under the fingerNo scale
motion.enter250 ms enterMenus, popovers, a page coming inFade only, 150 ms
motion.exit150 ms exitThe same things leavingFade only, 150 ms
motion.enter-large350 ms enterSheets, drawers, dialogs coming inFade only, 150 ms
motion.exit-large250 ms exitThe same things leavingFade only, 150 ms
A filled-in token sheet: six semantic motion tokens, each with its duration, its curve, its job and its reduced-motion fallback. Entering decelerates, leaving accelerates and is faster, and nothing is longer than 350 ms.Values: Marcus Andrey, CC BY 4.0. Curves from Material Design 3: standard (0.2, 0, 0, 1), standard decelerate (0, 0, 0, 1), standard accelerate (0.3, 0, 1, 1).

Now fill in the sheet: one row per job, with its duration, its curve, what to use it for, and what happens under reduced motion. The figure is a finished sheet, the same set used in Motion tokens and the earlier labs.

The reduced-motion column is the most important one. Use the rule from Designing a reduced-motion version: movement goes, fades and colour stay. A single fallback, a 150 ms fade, covers most rows.


5. Write the file

Write the set in the Design Tokens Community Group format, so any token tool can read it (DTCG, Format Module 2025.10). Primitives first, then semantic tokens that reference them:

{
  "motion": {
    "duration": {
      "100": { "$type": "duration", "$value": { "value": 100, "unit": "ms" } },
      "150": { "$type": "duration", "$value": { "value": 150, "unit": "ms" } },
      "250": { "$type": "duration", "$value": { "value": 250, "unit": "ms" } },
      "350": { "$type": "duration", "$value": { "value": 350, "unit": "ms" } }
    },
    "easing": {
      "standard": { "$type": "cubicBezier", "$value": [0.2, 0, 0, 1] },
      "enter":    { "$type": "cubicBezier", "$value": [0, 0, 0, 1] },
      "exit":     { "$type": "cubicBezier", "$value": [0.3, 0, 1, 1] }
    },
    "enter": {
      "$type": "transition",
      "$description": "Menus, popovers, a page coming in. Reduced motion: fade only, 150 ms.",
      "$value": {
        "duration": "{motion.duration.250}",
        "delay": { "value": 0, "unit": "ms" },
        "timingFunction": "{motion.easing.enter}"
      }
    }
  }
}

Add the other five semantic tokens the same way. Put the job and the reduced-motion rule in $description, which the format allows on every token, so the reason travels with the value.

Then the CSS your components will read:

:root {
  --motion-duration-press: 100ms;
  --motion-duration-feedback: 150ms;
  --motion-duration-enter: 250ms;
  --motion-duration-exit: 150ms;
  --motion-duration-enter-large: 350ms;
  --motion-duration-exit-large: 250ms;
  --motion-easing-standard: cubic-bezier(0.2, 0, 0, 1);
  --motion-easing-enter: cubic-bezier(0, 0, 0, 1);
  --motion-easing-exit: cubic-bezier(0.3, 0, 1, 1);
}

6. Test it on three real animations

Pick three animations from your inventory, one per job, and rebuild them with the tokens only. If any of them looks wrong, decide which is wrong: the token or the animation. Change one, write down why.

Show the result to one designer and one developer. Ask each: "Which token would you use for a tooltip?" If they pick the same one without asking you, the names work.


7. Check your work

Reflection questions: How many durations did you start with, and how many are left? Which merge was hardest to agree on?

Motion tokens · What public motion guidelines teach · Documenting motion in a design system · Duration: how long is right · Easing curves

Saved only on this device.

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