Skip to main content
Any new JS-driven animation MUST respect the user’s prefers-reduced-motion: reduce setting. CSS animations and transitions are already neutralized globally by the @media (prefers-reduced-motion: reduce) rule in src/index.css, but JavaScript-driven motion bypasses that rule and must opt in explicitly.

​
When this applies

  • Chart/graph libraries with internal requestAnimationFrame interpolation (Recharts, D3, Chart.js, etc.)
  • element.scrollIntoView / scrollTo / scrollBy calls with behavior: 'smooth'
  • Carousels and sliders (Embla, Swiper, keen-slider)
  • Web Animations API (element.animate(...)) and manual requestAnimationFrame loops
  • Spring/physics libraries (Framer Motion, react-spring) — gate animation props on the hook
  • Auto-scrolling tickers, marquees, parallax, and confetti effects

​
How to comply

Use the existing helpers — do not re-implement the matchMedia check inline.

​
Rules

  1. Never hardcode a non-zero animation duration without checking the preference first when the motion is JS-driven.
  2. Never write behavior: 'smooth' directly — use the safeScroll* helpers. The only allowed exception is when the call site has already early-returned for reduced-motion users (see ScrollableTabsList.tsx for the pattern).
  3. The reduced-motion path must be functionally equivalent — instant, but the same end state. Do not skip the action, only its animation.
  4. Both branches must be reactive: if you read usePrefersReducedMotion(), the component will re-render when the OS toggle changes — make sure your animation re-initializes (e.g., Embla reInit, Framer key change) so the new duration takes effect without a reload.
  5. Tests for new motion code should cover both branches (matchMedia mock returns matches: true and matches: false).

​
Reference

  • Helpers: src/shared/lib/a11y/scroll.ts, src/platform/a11y/usePrefersReducedMotion.ts
  • Recharts patch: src/shared/lib/a11y/recharts-motion.ts (installed in src/main.tsx)
  • Global CSS rule: src/index.css (@media (prefers-reduced-motion: reduce))
  • WCAG: 2.3.3 Animation from Interactions (AAA)