A government benefits application ships on the web and two native platforms, and its motion feels inconsistent across them. How do you define duration and easing tokens that hold across all three?

## Diagnose where the inconsistency comes from Motion that feels different across platforms rarely has one cause. The usual suspects: - **Hard-coded values.** Each team typed its own durations: 200 milliseconds on the web, 350 on one native app, the platform default on the other. - **Different default curves.** Each platform's animation system has its own default easing, and teams that never chose one inherited three different feels. - **Mixed families.** One platform uses springs for everything, another uses curves, so the same interaction feels bouncy in one place and crisp in another. - **Overridden system motion.** A team replaced its platform's standard navigation transition with a custom one to match the web, and now the app feels foreign on that platform. An inventory — recording the same flows on all three platforms side by side — shows which of these apply. ## Define one motion vocabulary A shared vocabulary is small: 1. **Duration scale** — short, medium, long (and perhaps extra long), with values chosen as common practice and tested at full speed. 2. **Easing roles** — standard for moves within the screen, decelerate for entering, accelerate for leaving, plus emphasized variants if the product needs them. 3. **Springs, if used** — a small set of named springs, usually critically damped, for gesture-driven motion. 4. **Purpose tokens** — motion for specific jobs, such as “expand section” or “panel enter”, that reference the scale and roles. Components use these, never raw values. ## Store it in a tool-agnostic format The Design Tokens Community Group format draft covers most of this: | Need | Draft type | Value shape | |---|---|---| | A duration | `duration` | An object with a numeric `value` and a `unit` of “ms” or “s” | | An easing curve | `cubicBezier` | Four numbers: two control points, x values between 0 and 1 | | A complete transition | `transition` | A composite of duration, delay and timing function, each a value or a reference | | A spring | none | Model as a group of number tokens, such as damping ratio and response | References use curly braces, so a purpose token points at `{motion.duration.medium}` rather than repeating a number. The draft's `$extensions` field is meant for optional metadata, not for values the token cannot be understood without, which is why spring parameters belong in ordinary number tokens instead. ## Generate each platform's output A token pipeline converts the shared source into what each platform consumes: milliseconds or seconds as that platform expects, curve objects, and spring objects assembled from the grouped numbers. Where a platform cannot express something natively — for example a spring on a surface that only accepts curves — the pipeline documents the approximation it uses, so nobody is surprised by a difference. ## Respect platform differences on purpose Consistency does not mean identical numbers everywhere: - **Native navigation and system transitions stay native.** Pushing a new screen, presenting a sheet, going back — users know how these feel on their platform, and replacing them makes the app feel foreign. Tokens govern the product's own custom motion. - **Screen size.** Many systems use slightly longer durations on large screens, where elements travel further, as a documented adjustment per size class. - **User settings.** Platforms let users reduce motion or change animation speed system-wide; the token layer is the natural place to apply those preferences centrally. What a reduced alternative looks like is a separate accessibility decision. The standard for success is **the same intent**: a section expanding feels equally quick and calm on every platform, even if one platform's value is a few milliseconds different. ## Verify and keep it true - Record the same flows on every platform and compare them frame by frame after each release. - Add a lint rule or review check that flags raw duration numbers and curve values in component code. - Document each purpose token with a short clip, so designers and engineers share one reference for what “panel enter” should look like. ## Pitfalls during the rollout - **Migrating numbers instead of intent.** Mapping every old value to its nearest scale step keeps inconsistent choices; map each animation to its purpose first, then to a step. - **Too many steps.** A scale of twelve durations recreates per-component values under new names; three or four steps cover most interfaces. - **Forgetting delay.** Hard-coded delays drift just like durations; the transition composite's delay should reference the scale too.