Accessible Animation

Accessible Animation (Reduced Motion, Tiered)

Honor prefers-reduced-motion: reduce as a graceful degradation, not a kill switch. The OS-level setting (macOS: Settings > Accessibility > Display > Reduce motion; Windows: Settings > Accessibility > Visual effects > Animation effects; iOS/Android equivalents) signals that vestibular-triggering motion causes nausea, dizziness, or migraines. The correct response is to remove the dangerous motion while keeping orientation cues.

When to use

Use when adding or auditing animation in a web UI, when a user reports motion sickness or WCAG findings, or when integrating animation libraries (GSAP, Framer Motion, Lenis smooth scroll, Anime.js, CSS keyframes) into an accessible product.

The core principle: tier motion, do not nuke it

Removing all animation is a common over-correction. An instant state change with no transition can be more disorienting (elements teleport) and removes useful affordances (focus rings, loading spinners that communicate progress). Sort every animation into three tiers:

• Tier 1 — Remove entirely (vestibular triggers). Parallax; large-area slides/translates across the viewport; scale/zoom of large elements; 3D rotation and spin; continuous auto-playing carousels and marquees; smooth-scroll hijacking (Lenis/Locomotive); scroll-jacked pinned scenes; motion-path animation; anything that moves a large portion of the screen or implies depth/self-motion.
• Tier 2 — Soften / shorten. Replace movement with a short opacity fade (≤200ms). Reduce distance and duration. Keep the fact of a transition (so elements don't teleport) but strip the displacement. Replace a 600ms slide-in-from-left with a 150ms cross-fade.
• Tier 3 — Always keep. Opacity fades, color/background transitions, focus-ring transitions, loading indicators, and motion that is essential to meaning (WCAG allows essential animation). These rarely trigger vestibular responses because they imply no self-motion.

CSS layer: media-query gating

Write motion as the default, then override under the reduce query. Prefer a global safety net plus targeted overrides.

/* Global safety net: neutralize runaway motion but DO NOT set 0s blindly,
   which can break JS that waits for transitionend/animationend. Use 0.01ms. */
@media (prefers-reduced-motion: reduce) {
  *,
  *::before,
  *::after {
    animation-duration: 0.01ms !important;
    animation-iteration-count: 1 !important;   /* stop infinite spins/marquees */
    transition-duration: 0.01ms !important;
    scroll-behavior: auto !important;          /* kill smooth scroll */
  }
}

The global net is a backstop. Layer intentional, tiered overrides on top so Tier 3 motion survives:

.card {
  transition: transform 400ms ease, opacity 400ms ease, background-color 200ms ease;
}

@media (prefers-reduced-motion: reduce) {
  .card {
    /* Tier 2: drop the transform (movement), keep opacity + color (Tier 3) */
    transition: opacity 150ms ease, background-color 150ms ease;
  }
  .parallax-layer { transform: none !important; }        /* Tier 1: remove */
  .hero-zoom      { animation: none !important; }        /* Tier 1: remove */
}

Use the positive query (prefers-reduced-motion: no-preference) to opt motion IN, which is the safest pattern for elaborate effects:

.hero { opacity: 1; } /* visible, static by default */
@media (prefers-reduced-motion: no-preference) {
  .hero { animation: zoom-in 1.2s ease both; } /* only animate when allowed */
}

JS layer: matchMedia gating

CSS cannot gate JS-driven animation (GSAP timelines, Framer's animate, canvas/WebGL, Lenis). Read the same signal via matchMedia and react to live changes (users toggle the OS setting without reloading).

const REDUCE_QUERY = '(prefers-reduced-motion: reduce)';

export function prefersReducedMotion() {
  return typeof window !== 'undefined'
    && window.matchMedia
    && window.matchMedia(REDUCE_QUERY).matches;
}

// Live updates: listen so toggling the OS setting takes effect immediately.
export function onReducedMotionChange(cb) {
  const mq = window.matchMedia(REDUCE_QUERY);
  const handler = (e) => cb(e.matches);
  mq.addEventListener('change', handler);          // modern API
  return () => mq.removeEventListener('change', handler);
}

Library gating, applied as one reusable layer

// GSAP — use matchMedia(): GSAP reverts conditional setups on change.
import gsap from 'gsap';
const mm = gsap.matchMedia();
mm.add({
  motionOK: '(prefers-reduced-motion: no-preference)',
  motionReduce: '(prefers-reduced-motion: reduce)',
}, (ctx) => {
  const { motionOK } = ctx.conditions;
  if (motionOK) {
    gsap.from('.hero', { y: 80, opacity: 0, duration: 1 });   // Tier 1 move
  } else {
    gsap.from('.hero', { opacity: 0, duration: 0.15 });        // Tier 2 fade
  }
});

// Lenis smooth scroll — do not instantiate at all when reduced.
import Lenis from 'lenis';
let lenis = null;
if (!prefersReducedMotion()) {
  lenis = new Lenis();
  const raf = (t) => { lenis.raf(t); requestAnimationFrame(raf); };
  requestAnimationFrame(raf);
}

React: a useReducedMotion hook

import { useState, useEffect } from 'react';

export function useReducedMotion() {
  const query = '(prefers-reduced-motion: reduce)';
  const get = () =>
    typeof window !== 'undefined' && window.matchMedia
      ? window.matchMedia(query).matches
      : false;
  const [reduced, setReduced] = useState(get);

  useEffect(() => {
    const mq = window.matchMedia(query);
    const onChange = () => setReduced(mq.matches);
    onChange();                                   // sync after hydration
    mq.addEventListener('change', onChange);
    return () => mq.removeEventListener('change', onChange);
  }, []);

  return reduced;
}

// Framer Motion has its own useReducedMotion(); the hook above also works.
import { motion } from 'framer-motion';
function Card() {
  const reduced = useReducedMotion();
  return (
    <motion.div
      initial={reduced ? { opacity: 0 } : { opacity: 0, y: 40 }}
      animate={{ opacity: 1, y: 0 }}
      transition={{ duration: reduced ? 0.15 : 0.5 }}
    />
  );
}

Initialize SSR-rendered state to false (motion) and re-sync in useEffect to avoid a hydration mismatch; the OS value is only known client-side.

WCAG mapping

• 2.3.3 Animation from Interactions (AAA). Motion triggered by interaction (scroll, hover) must be disable-able unless essential. Honoring prefers-reduced-motion is the standard technique.
• C39 (CSS technique). Use the prefers-reduced-motion query to prevent motion. This is the named sufficient technique.
• 2.2.2 Pause, Stop, Hide (A). Any auto-playing motion lasting >5s must offer pause/stop. Auto-carousels and marquees fail this regardless of the media query — give a control too.

Deliver & verify (standalone HTML)

Packaged helper (scripts/): scripts/seek-shot.sh anim.html 0 1.5 3 freezes the ?t=N harness and screenshots each moment; scripts/contact-sheet.sh sheet.png frame-*.png tiles them for one-glance review. See scripts/README.md.

For a self-contained demo the deliverable is one HTML file that opens directly in a browser — markup, CSS, and any JS (GSAP/matchMedia from CDN) inline, no build step. For this skill the verification is the point: you must screenshot both the normal and the reduced-motion path and confirm the tiering is correct.

Output contract:

• One .html file with the full motion AND its tiered reduced-motion overrides (CSS query + matchMedia/gsap.matchMedia() for JS-driven motion).
• A seek harness to freeze a frame, plus a way to force the reduced-motion code path for screenshots.