Motion tokens

Motion Tokens

Instructions

Motion belongs in the token system. A component should no more embed 250ms than it should embed #4F46E5.

1. DTCG Types for Motion

DTCG ships duration and cubicBezier. Compose motion via transition groups.

{
  "motion": {
    "duration": {
      "$type": "duration",
      "xs": { "$value": "80ms" },
      "sm": { "$value": "150ms" },
      "md": { "$value": "250ms" },
      "lg": { "$value": "400ms" }
    },
    "easing": {
      "$type": "cubicBezier",
      "standard":    { "$value": [0.2, 0.0, 0.0, 1.0] },
      "accelerate":  { "$value": [0.3, 0.0, 1.0, 1.0] },
      "decelerate":  { "$value": [0.0, 0.0, 0.0, 1.0] },
      "emphasized":  { "$value": [0.2, 0.0, 0.0, 1.0] }
    }
  }
}

2. Semantic Motion Aliases

Components consume intent-bearing aliases, not raw motion.duration.md.

{
  "motion": {
    "transition": {
      "stateChange": {
        "$type": "transition",
        "$value": {
          "duration": "{motion.duration.sm}",
          "timingFunction": "{motion.easing.standard}",
          "delay": "0ms"
        }
      },
      "surfaceEnter": {
        "$type": "transition",
        "$value": {
          "duration": "{motion.duration.md}",
          "timingFunction": "{motion.easing.decelerate}",
          "delay": "0ms"
        }
      },
      "surfaceExit": {
        "$type": "transition",
        "$value": {
          "duration": "{motion.duration.sm}",
          "timingFunction": "{motion.easing.accelerate}",
          "delay": "0ms"
        }
      },
      "stagger": {
        "$type": "duration",
        "$value": "30ms"
      }
    }
  }
}

3. Style Dictionary Transforms

Style Dictionary does not ship duration / cubicBezier transforms out of the box for native platforms. Add small custom transforms.

// style-dictionary.config.js
const StyleDictionary = require('style-dictionary');

StyleDictionary.registerTransform({
  name: 'duration/ms-to-number',
  type: 'value',
  matcher: t => t.$type === 'duration',
  transformer: t => parseInt(String(t.$value).replace('ms', ''), 10),
});

StyleDictionary.registerTransform({
  name: 'cubicBezier/array',
  type: 'value',
  matcher: t => t.$type === 'cubicBezier',
  transformer: t => t.$value, // [x1,y1,x2,y2]
});

StyleDictionary.registerTransformGroup({
  name: 'compose-motion',
  transforms: ['attribute/cti', 'name/cti/pascal', 'duration/ms-to-number', 'cubicBezier/array'],
});

4. Compose Delivery

object Motion {
    object Duration {
        const val Xs = 80
        const val Sm = 150
        const val Md = 250
        const val Lg = 400
    }
    val EasingStandard    = CubicBezierEasing(0.2f, 0.0f, 0.0f, 1.0f)
    val EasingDecelerate  = CubicBezierEasing(0.0f, 0.0f, 0.0f, 1.0f)
    val EasingAccelerate  = CubicBezierEasing(0.3f, 0.0f, 1.0f, 1.0f)
}

val SurfaceEnter = tween<Float>(Motion.Duration.Md, easing = Motion.EasingDecelerate)

5. SwiftUI Delivery

public enum DSMotionDuration { public static let xs = 0.08, sm = 0.15, md = 0.25, lg = 0.4 }
public enum DSMotionEasing {
    public static let standard   = Animation.timingCurve(0.2, 0.0, 0.0, 1.0, duration: DSMotionDuration.md)
    public static let decelerate = Animation.timingCurve(0.0, 0.0, 0.0, 1.0, duration: DSMotionDuration.md)
    public static let accelerate = Animation.timingCurve(0.3, 0.0, 1.0, 1.0, duration: DSMotionDuration.sm)
}

6. Flutter Delivery

class AppMotion extends ThemeExtension<AppMotion> {
  final Duration surfaceEnter;
  final Duration surfaceExit;
  final Curve    standard;
  final Curve    decelerate;
  const AppMotion({
    required this.surfaceEnter, required this.surfaceExit,
    required this.standard,     required this.decelerate,
  });
  static const standard = AppMotion(
    surfaceEnter: Duration(milliseconds: 250),
    surfaceExit:  Duration(milliseconds: 150),
    standard:    Cubic(0.2, 0.0, 0.0, 1.0),
    decelerate:  Cubic(0.0, 0.0, 0.0, 1.0),
  );
  @override AppMotion copyWith(...) => ...;
  @override AppMotion lerp(ThemeExtension<AppMotion>? other, double t) => this;
}

7. React Native Delivery

export const motion = {
  duration: { xs: 80, sm: 150, md: 250, lg: 400 },
  easing: {
    standard:   Easing.bezier(0.2, 0.0, 0.0, 1.0),
    decelerate: Easing.bezier(0.0, 0.0, 0.0, 1.0),
    accelerate: Easing.bezier(0.3, 0.0, 1.0, 1.0),
  },
} as const;

8. Reduced-Motion Variant

Ship a second token file motion.reduced.json where every duration resolves to 0ms. The platform provider picks the right file at runtime based on the accessibility flag.

9. Anti-Patterns

• tween(300) inline in a component.
• Using CSS-string easings on native platforms instead of cubic-bezier arrays.
• Exposing reference durations (motion.duration.md) as the component-facing API.
• Hardcoding stagger in component source — tokenize it.

Checklist

• Duration and easing are DTCG duration / cubicBezier tokens with semantic transition aliases.
• Style Dictionary has explicit transforms for duration and cubic-bezier output per platform.
• Every target platform has a generated motion artifact (Compose Motion, SwiftUI DSMotion…, Flutter ThemeExtension, RN const).
• Components consume semantic motion tokens (transition.stateChange) only.
• A reduced-motion token file is delivered and selected at runtime.
• No raw millisecond or cubic-bezier literals exist in component source.