Decision Respect prefers-reduced-motion for all animations and transitions

proposed

Users with vestibular disorders rely on the prefers-reduced-motion media query to disable or reduce motion that can cause discomfort.

Decision

We will respect prefers-reduced-motion: reduce for all animations, transitions, smooth scrolling, and motion-driven UI. This applies to custom code as well as third-party plugins and legacy code, which must be overridden when they do not honor the preference natively.

Implementation

Custom CSS animations and transitions must be scoped inside a prefers-reduced-motion: no-preference media query, so motion only runs when the user has not expressed a preference for reduced motion:

@media (prefers-reduced-motion: no-preference) {
  .card {
    transition: transform 0.3s ease;
  }
}

JavaScript-driven animations must check the same media query before running, per WCAG SCR40:

const animationOkay = window.matchMedia("(prefers-reduced-motion: no-preference)").matches;

if (animationOkay) {
  /* The user has not expressed a preference for reduced motion — run JavaScript-based animation */
}

For third-party plugins or legacy code that does not honor the preference natively (for example, carousels and sliders with auto-play), enforce reduced motion by overriding the offending CSS or by using the plugin's JavaScript API to disable motion when prefers-reduced-motion: reduce is active.

Exceptions

  • Animation is allowed when the activity can't be accomplished without the motion, such as map panning where the animation conveys spatial context.
  • Motion animation does not include changes of color, blurring, or opacity which do not change the perceived size, shape, or position of the element.
  • Animations and transitions with inperceptibly short durations may be used globally if transitionEnd or animationEnd events are used for asynchronous functionality.

Consequences

  • All CSS transitions and animations are disabled or instant for users who prefer reduced motion
  • Sliders and carousels stop auto-advancing
  • Video and other media doesn't auto play.
  • Third-party plugins, legacy code, and JS-driven motion must also respect the preference where possible.

Additional Resources