Motion

Motion provides shared duration tokens for transitions and defines how motion responds to user preferences.

The duration scale provides several timing options for interface changes. Components determine which properties and easing values use those durations according to their behaviour.

Reduced-motion preferences are handled where motion is introduced.

Transition durations

:root {
  --transition-duration-turbo: 0.1458980338s;
  --transition-duration-fast: 0.382s;
  --transition-duration: 0.618s;
  --transition-duration-slow: 1.618s;
}

The tokens progress from shortest to longest:

Use the shortest duration that makes a change understandable without making the interface feel delayed.

Turbo

Use --transition-duration-turbo for immediate state feedback where the change should remain perceptible.

.button {
  transition-duration: var(--transition-duration-turbo);
}

Fast

Use --transition-duration-fast for short interface transitions that need slightly more time to register.

.control {
  transition-duration: var(--transition-duration-fast);
}

Default

Use --transition-duration when a transition needs more time than the faster interaction states.

.panel {
  transition-duration: var(--transition-duration);
}

Slow

--transition-duration-slow is the longest duration in the scale.

.panel {
  transition-duration: var(--transition-duration-slow);
}

Transition properties

Specify which properties should transition:

.link {
  transition-property: color;
  transition-duration: var(--transition-duration-turbo);
}

Multiple properties can share the same duration:

.button {
  transition-property: color, background-color, border-color, box-shadow;
  transition-duration: var(--transition-duration-turbo);
}

Avoid transitioning every changed property with all. Explicit properties make the intended motion clear and prevent unrelated property changes from being animated.

The duration tokens define timing only. Transition properties and easing remain part of the implementation using them. The system does not currently define shared easing tokens.

Smooth scrolling

The base styles enable smooth scrolling:

html {
  scroll-behavior: smooth;
}

This affects scrolling performed through navigation or the CSSOM scrolling APIs. It does not change scrolling performed directly by the user.

Reduced motion

Disable smooth scrolling when the user requests reduced motion:

@media (prefers-reduced-motion: reduce) {
  html {
    scroll-behavior: auto;
  }
}

The prefers-reduced-motion media feature detects when a user has requested that non-essential motion be minimized.

Components that introduce other motion must handle the preference where that motion is defined:

.element {
  transition-property: transform;
  transition-duration: var(--transition-duration);
}

@media (prefers-reduced-motion: reduce) {
  .element {
    transition: none;
  }
}

Do not automatically remove every transition. Color, border, and other non-moving state changes may remain useful when they do not create problematic motion.

Motion triggered by interaction should be removable when it is not essential to the functionality or information being communicated.

Changing the duration scale

Change a duration when its timing is consistently unsuitable across the implementations using it.

Add another duration only when a recurring timing requirement cannot be represented by the existing scale.

When changing a duration, check:

• hover, focus, active, and expanded states
• repeated interactions
• transitions between significantly different element sizes or positions
• whether the interface responds immediately enough
• reduced-motion behaviour
• whether the duration still fits its name relative to the other tokens