Hero image for Motion Tokens: Making Duration and Easing Machine-Readable

Motion Tokens: Making Duration and Easing Machine-Readable

Motion is the last part of a design system an AI agent can read least well. Color and spacing usually live in parseable token files, but durations and easing curves still live in CSS snippets, component code, or a designer’s head. That gap is where machine review breaks down: an agent can check a color token against a palette, but it cannot reliably tell whether a 240ms drawer uses the system’s intended curve. Motion tokens fix that by making duration and easing first-class, typed values. This post explains what the W3C Design Tokens (DTCG) format draft says about motion, compares how Carbon, Material 2, and Spectrum encode it, and turns the result into rules an agent can actually run.

Why Motion Lags Behind Color and Spacing

A design system becomes machine-checkable when its decisions are represented as data rather than prose. Motion has lagged behind color, spacing, and typography because its two core ingredients—time and curve—were treated as implementation details. A token file can say that color.action.primary is #005fcc; it rarely says that a modal enters over 240ms with cubic-bezier(0, 0, 0.3, 1). As a result, motion review is still mostly human judgment: someone opens a component, watches it, and decides whether it feels right.

The DTCG format changes the shape of that problem. It defines typed token values for duration, cubicBezier, and transition, so a motion decision can be stored, referenced, validated, and audited like any other token. The goal is not to replace taste with a number; it is to make the number legible to software, including agents that review pull requests or generate components.

What the DTCG Format Actually Says About Motion

The DTCG format is a draft, and its motion types are small but precise. The relevant facts are best stated as a contract rather than a table.

duration (§8.5): time as a typed value

  • $type MUST be duration.
  • The value MUST be an object with a numeric value and a unit of "ms" or "s".
  • Validation: $value.unit may only be "ms" or "s".

That is the whole contract, and it is enough to stop a common failure mode: a token file that says "duration": "240ms" as a string, or one that uses "frames" as a unit. A machine can now reject the token by shape alone.

cubicBezier (§8.6): a curve as four numbers

  • $type MUST be cubicBezier.
  • The value MUST be an array of four numbers: [P1x, P1y, P2x, P2y].
  • The x coordinates are restricted to [0, 1]; the y coordinates are unbounded.

This is the same mathematical object CSS calls a cubic Bézier easing function, but stored as data. Because x is bounded and y is not, the format can represent overshoot curves without pretending they are invalid. The MDN easing-function documentation corroborates that x coordinates live in [0, 1].

transition (§9.5): the composite type with an open question

  • $type MUST be transition.
  • The keys are duration, delay, and timingFunction.
  • duration and delay must each be a valid duration value or a duration token reference.
  • timingFunction must be a valid cubicBezier value or a reference.

The composite type is convenient, but it has a known limitation. Issue 103 asks whether transition tokens are useful at all, because “they don’t let you specify what aspect of a UI is being transitioned and what the start and end states are.” In other words, a transition token can say how long and how, but not what changed. That limitation is worth keeping in view before adopting the type everywhere.

How Carbon, Material, and Spectrum Encode Motion

The three systems in this comparison do not disagree about physics; they disagree about where motion decisions should live. Carbon leans on a non-linear token scale, Material on area and direction heuristics, and Spectrum on semantic categories. The table below is the post’s only comparison table.

Dimension IBM Carbon Material 2 Adobe Spectrum
Duration scale philosophy Non-linear scale “to achieve better perceived consistency across all distances”; six static tokens, 70→700ms, each with a named use case Duration scales with area and direction—exit faster than entrance (switch 100ms; drawer 250/200ms; card 300/250ms; full-screen 300/250ms) Categorizes motion by meaning (directional / interaction / wayfinding); no duration values published
Easing taxonomy 2 styles (productive, expressive) × 3 roles (standard, entrance, exit); six concrete cubic-bezier values; “Reserve expressive motion for occasional, important moments.” 4 named types (standard, emphasized, accelerated, decelerated); CSS curves published for standard cubic-bezier(0.4, 0.0, 0.2, 1), decelerated cubic-bezier(0.0, 0.0, 0.2, 1) and accelerated cubic-bezier(0.4, 0.0, 1, 1); emphasized is N/A on the cited page Directional sub-categories (linear, diagonal, clockwise); no cubic-bezier values published
Reduced-motion guidance Explicit, under “Adaptive interface motion design”: “Consider simplified or reduced motion designs for mobile and tablet,” with a static alternative always available Not stated on the cited speed page Explicit: large-surface motion must support reduced-motion settings; RTL and cultural-context cautions
What an agent can parse unaided Full name→ms and style→bezier pairs—fully machine-extractable Heuristics, example ms values, and CSS curves for three of four easing types; emphasized has no published value Semantic categories only; numbers must come from your own system

The lesson is not that one system is correct. It is that the three philosophies yield three different levels of machine-extractable detail. IBM Carbon publishes name-to-millisecond and style-to-bezier pairs, so an agent can check against it directly. Material 2 publishes heuristics, example durations, and CSS curves for three of its four easing types, so most of its taxonomy is extractable — the emphasized curve is the gap. Adobe Spectrum publishes categories and safety guidance; no duration values or easing curves appear on the cited page, and Spectrum motion guidance is still in development. Spectrum cells in the table therefore carry that caveat explicitly, and no Spectrum durations should be inferred.

Carbon’s own documentation contains an internal tension worth surfacing rather than smoothing over. Its token table spans micro-interactions from 70ms to 150ms, while its review checklist asks, “Do micro-interactions fall within a static duration ranging from 90–120 ms?” Both bands are Carbon’s own guidance; this post presents both and does not reconcile them.

Easing Keywords Are a Migration Problem

Legacy CSS buries motion in keywords. A stylesheet can say transition: opacity 150ms ease-out, and the easing is real but not portable: ease-out is a name, not a token. The MDN easing-function reference gives a deterministic canonicalization path from five common keywords to cubicBezier tokens:

  • ease → cubic-bezier(0.25, 0.1, 0.25, 1)
  • ease-in → cubic-bezier(0.42, 0, 1, 1)
  • ease-out → cubic-bezier(0, 0, 0.58, 1)
  • ease-in-out → cubic-bezier(0.42, 0, 0.58, 1)
  • linear → cubic-bezier(0, 0, 1, 1)

That equivalence is the migration bridge: every keyword in an existing CSS file can be replaced by a named token whose value is one of those four-number arrays. The same reference documents that steps() variants include jump-start, jump-end, jump-none, and jump-both, and that linear() defines multi-point progress. Neither has a corresponding token type in the DTCG draft cited here, so both remain outside the token contract for now. The easing-function reference is also where the July 2015 baseline for these functions is documented.

The Rules: What an Agent Can Actually Check

A computable contract is a set of predicates, each returning pass or fail plus the offending token path. These ten rules are phrased that way. Rules 1–3 follow the DTCG constraints directly; rule 4 follows the MDN keyword equivalences; rules 5–7 are derived from the cited system guidance; rules 8–9 are derived conventions, not spec mandates; rule 10 is derived from Spectrum’s directional categories.

  1. Duration shape. For every token with $type == "duration", $value.value is a number and $value.unit ∈ {"ms", "s"}. Fail on anything else, such as unit: "frames".
  2. Bezier shape and x-range. For every token with $type == "cubicBezier", $value is an array of length 4, $value[0] ∈ [0, 1], and $value[2] ∈ [0, 1]. The y values are unbounded.
  3. Transition completeness. For every token with $type == "transition", the keys {duration, delay, timingFunction} are all present; duration and delay each resolve to a valid duration value or duration token reference; timingFunction resolves to a valid cubicBezier value or reference.
  4. Keyword canonicalization. Any easing stored as a keyword must equal its canonical bezier from the list above, or be flagged non-portable.
  5. Exit ≤ entrance. For every component class declaring both, exit duration ≤ entrance duration. The Material examples demonstrate the pattern: drawer 250/200ms, card 300/250ms.
  6. Micro-interaction band. Every token tagged micro-interaction satisfies 70 ≤ ms ≤ 150, Carbon’s token span, with an additional warning outside 90–120ms, Carbon’s checklist band. Both bands are surfaced; neither is privileged.
  7. Duration ceiling. No duration token exceeds 700ms without a justification note in its $description.
  8. Reduced-motion counterpart (derived, not spec-mandated). Every animated token has a paired reduced variant resolving to 0ms or a shortened duration, and the system exposes a prefers-reduced-motion: reduce branch.
  9. Auto-motion audit. Any animation flagged auto-starting or looping and running more than 5 seconds must carry a pausable: true attribute or fail.
  10. Directional semantics. Tokens naming directional motion use one of {linear, diagonal, clockwise}, and any diagonal token carries an RTL-flip rule.

The Motion Token Generator

The motion token generator we built alongside this post implements the contract above. It checks your scale against the spec; it does not impose one.

Inputs

The input set is deliberately small: a starting preset (Carbon productive or expressive, or a custom curve), a base duration step, a scale ratio, an exit-to-entrance ratio, and the four control points of the standard curve. Nothing in that set requires Carbon’s numbers, Material’s heuristics, or Spectrum’s categories — the presets are a starting point you can overwrite. You bring the scale; the tool checks its shape.

Outputs: DTCG JSON and CSS

The dual output is spec-shaped DTCG tokens plus CSS custom properties or plain JSON. One source then feeds both agents, which read the token file, and stylesheets, which consume the CSS. That is the practical point of the contract: a single authored source that is simultaneously human-editable, machine-validatable, and browser-usable.

What it validates

The tool’s checks map onto the predicates in the previous section: shape, ranges, completeness, and canonicalization. It checks shape against the spec, not taste. Your numbers, not Carbon’s or Material’s, are what it tests.

The Safety Layer: Reduced Motion Is Not Optional

Motion is an accessibility issue before it is a design issue. The MDN prefers-reduced-motion reference documents that the media feature detects a device setting to minimize non-essential motion. Its values are no-preference (false) and reduce (true), and @media (prefers-reduced-motion) is equivalent to @media (prefers-reduced-motion: reduce). The feature has been baseline since January 2020. Scaling or panning large objects can be vestibular triggers.

The medical stakes are spelled out by web.dev: some users experience motion sickness, so reducing animation is “a medical necessity.” Vestibular reactions include dizziness, nausea, and migraine headaches, sometimes requiring bed rest. Parallax is a common trigger because background elements move at a different rate than foreground elements.

Two WCAG 2.2 criteria frame the compliance side. SC 2.3.3 (AAA) says motion animation triggered by interaction can be disabled unless essential, with suggested solutions including avoiding unnecessary animation, providing a control, and using the OS reduce-motion feature. SC 2.2.2 (Level A) requires a mechanism to pause, stop, or hide moving, blinking, or scrolling information that starts automatically, lasts more than five seconds, and is presented in parallel with other content, unless it is essential.

Spectrum adds the system-level guidance that motion over large surface areas needs to support browser and system settings for reduced motion, and that custom animation should consider RTL languages and cultural context. Tokens make the reduced branch checkable through rules 8 and 9: every animated token carries a reduced variant, and any auto-motion over five seconds must be pausable.

What Motion Tokens Can’t Say Yet

The claim should be bounded honestly. Transition tokens do not capture what changed, per Issue 103. Spectrum publishes no duration values and no easing curves, only categories and safety guidance, and its motion guidance is still in development. Material’s four named easing types are not equally documented: emphasized easing publishes no CSS value on the cited page, while standard, decelerated and accelerated each publish a cubic-bezier. The DTCG draft has no token type for springs, physics, or linear() multi-point progress. No public tooling support matrix for DTCG motion types was found in the cited documentation, and the format itself is a draft. Carbon’s 90–120ms checklist band and 70–150ms token span remain unresolved in its own documentation. None of these gaps invalidates the approach; they define its current edge.

FAQ

What is a motion token, exactly?

A motion token is a typed token whose value is a duration, a cubic Bézier curve, or a transition. In the DTCG draft, that means $type of duration, cubicBezier, or transition, with the keys and constraints described above. It turns a motion decision into data that can be referenced and validated.

Is transition stable, or should I skip it?

Treat it as optional. The composite type is convenient, but Issue 103 questions its usefulness because transition tokens do not say what aspect of a UI is being transitioned or what the start and end states are. Adopt duration and cubicBezier now; add transition where the composite genuinely helps.

Do I have to use Carbon’s or Material’s numbers?

No. The token format is vendor-neutral. Carbon, Material 2, and Spectrum are three different philosophies, and the generator validates your scale against the spec rather than imposing any vendor’s scale. Your numbers are the ones that matter to your system.

How do I migrate ease-out-style keywords in existing CSS?

Replace each keyword with its canonical bezier from the MDN equivalences: ease-out becomes [0, 0, 0.58, 1], and similarly for the other four. Keywords like steps() and linear() have no token equivalent in the cited draft, so they remain CSS-level concerns for now.

Does honoring prefers-reduced-motion make me WCAG-compliant?

Not by itself. SC 2.3.3 (AAA) and SC 2.2.2 (Level A) set conditions around disabling interaction-triggered motion and pausing auto-starting motion over five seconds. Honoring the OS setting is a strong, recommended step, but the criteria also depend on whether the motion is essential and whether pausing controls exist.

What about springs, physics, and linear()?

The cited DTCG draft has no token type for spring or physics parameters, and no token type for linear() multi-point progress. Those remain outside the current token contract. The MDN reference documents linear() and steps() variants, but not as DTCG types.

Which tools support DTCG motion tokens today?

No public support matrix was found in the cited documentation, and the format is a draft. The practical answer is to validate your own files against the spec and treat tooling support as something to verify per tool rather than assume.

The Bottom Line

Motion tokens turn the least-checkable part of a design system into a computable contract. Adopt duration and cubicBezier now, treat transition as optional pending Issue 103, and ship the reduced-motion branch alongside the primary one. Use the generator because hand-writing these files is where spec violations creep in. The result is not a replacement for design judgment; it is a machine-readable record of the judgment you already made.

How This Guide Was Built

This guide was built from public documentation only. Research drew on the nine inline-linked sources above, all accessed on 2026-11-19, and no hands-on testing was performed. Every number in the post is taken from those sources or from the DTCG draft’s stated constraints; where a source is silent—on Spectrum durations, on Material control points, on tooling support—the post says so rather than filling the gap.