Duration Tokens

Duration tokens define animation timing values in a systematic way, enabling consistent motion design across components and platforms. Rather than hard-coding animation durations, components reference named tokens like “duration-moderate” that hold actual millisecond values. This approach ensures animation timing remains coherent throughout a design system.

What Are Duration Tokens

Duration tokens store time values that control how long animations take. Semantic names indicate intended use: “instant” for immediate feedback, “quick” for snappy interactions, “moderate” for standard transitions, “slow” for elaborate entrances. Components reference these names rather than arbitrary numbers.

Token-based duration management enables systematic motion tuning. Changing “duration-moderate” from 200ms to 250ms updates all components using that token. This centralized control prevents the proliferation of slightly different duration values across a design system.

Cross-platform transformation converts token values to platform-appropriate formats. Milliseconds might become seconds for iOS APIs. Token systems handle this transformation, outputting values that work natively on each platform.

How Duration Tokens Work

Duration token definitions use semantic names with time values. Common scales use multiples (100ms, 200ms, 400ms) or mathematical progressions for visual harmony.

Duration Token Structure:

Token Definitions:
{
  "motion": {
    "duration": {
      "instant": {
        "value": 0,
        "description": "No animation, immediate"
      },
      "quick": {
        "value": 100,
        "description": "Fast feedback, micro-interactions"
      },
      "moderate": {
        "value": 200,
        "description": "Standard transitions"
      },
      "slow": {
        "value": 400,
        "description": "Elaborate entrances, page transitions"
      },
      "elaborate": {
        "value": 600,
        "description": "Complex choreographed sequences"
      }
    }
  }
}

Platform Output:

CSS:
--motion-duration-instant: 0ms;
--motion-duration-quick: 100ms;
--motion-duration-moderate: 200ms;
--motion-duration-slow: 400ms;

iOS (Swift):
static let instant: TimeInterval = 0
static let quick: TimeInterval = 0.1
static let moderate: TimeInterval = 0.2
static let slow: TimeInterval = 0.4

Android (Kotlin):
const val DURATION_INSTANT = 0L
const val DURATION_QUICK = 100L
const val DURATION_MODERATE = 200L
const val DURATION_SLOW = 400L

Usage guidelines specify which durations suit which animation types. Feedback animations use quick durations. Page transitions use slow durations. Component documentation references appropriate tokens.

Reduced motion preferences may use alternative duration values. When users prefer reduced motion, duration-moderate might become 0, eliminating the animation. Design systems can define parallel token sets for reduced motion contexts.

Key Considerations

• Semantic naming indicates purpose not value
• Duration scales should have clear progression
• Reduced motion alternatives need specification
• Platform unit conversion happens during transformation
• Usage guidelines prevent incorrect token application
• Testing validates that durations feel appropriate

Common Questions

How do design systems determine duration values?

Material Design research provides starting points. Google’s motion guidelines recommend specific durations for different animation types based on user research.

Content size and distance traveled affect appropriate duration. Longer animations suit larger movements. Brief animations suit small property changes.

User testing validates duration choices. Animations should complete before feeling sluggish but not appear jarringly fast. User feedback refines duration values.

Device performance considerations may influence duration. Slower devices may benefit from shorter durations that complete before performance issues manifest.

How many duration tokens should a design system have?

Most design systems need 4-6 duration levels. Instant (0), quick (~100ms), moderate (~200ms), slow (~400ms), and elaborate (~600ms) cover most use cases.

Too few tokens force inappropriate reuse. If only quick and slow exist, moderate animations must choose between too fast and too slow.

Too many tokens create confusion. If twelve duration levels exist, developers struggle to choose correctly. Simplicity aids adoption.

Specialized tokens may supplement the core scale. A “duration-loading-loop” might have specific value not fitting the standard scale.

How should duration tokens handle responsive animation?

Longer durations may feel appropriate on larger screens. A page transition covering more distance might warrant longer duration on tablet than phone.

Token variants for different size contexts can address this. “duration-moderate-mobile” and “duration-moderate-desktop” provide context-appropriate values.

Alternatively, duration calculation can factor in animation distance. Dynamic duration based on pixel distance traveled maintains consistent perceived speed.

Testing across devices validates responsive duration approaches. Animations should feel equally appropriate on all target device sizes.

Summary

Duration tokens define animation timing systematically through semantic names referencing time values. Token-based management enables centralized motion tuning and consistent duration usage across components. Platform transformation converts values to appropriate formats. Design systems should define clear duration scales with usage guidance, reduced motion alternatives, and consideration for responsive contexts.