SiteLint documentation and guidelines

Verify animation from interactions

Description

This rule checks that motion animation triggered by user interaction can be disabled, unless the animation is essential to the functionality or the information being conveyed. Interactive animations include parallax scrolling, hover-based transforms, slide-in reveals, pulse effects, and other movement triggered by clicks, taps, scrolls, or pointer focus. The rule maps to WCAG 2.3.3 Animation from Interactions at Level AAA.

Because this is a semi-automated rule, the tool flags the page for manual review. An auditor must verify whether a mechanism exists – such as a prefers-reduced-motion media query or a site-level toggle – that lets users block non-essential motion. Motion that is essential (e.g., a loading spinner, a progress bar, or a functional drag indicator) is exempt.

Disabilities impacted

  • Vision (vestibular disorders) – Motion animations such as parallax scrolling, zoom, pan, and rapid transitions can trigger dizziness, nausea, and vertigo in people with vestibular disorders. Users in this group often need to disable all non-essential motion to browse comfortably.
  • Cognitive disabilities – Moving, pulsing, or sliding content can distract or overwhelm users with ADHD, autism, or other cognitive conditions. Uncontrolled interaction-triggered animation makes it difficult to maintain focus or complete tasks.
  • Motor control disabilities – Users with tremors, parkinsonism, or limited fine motor control may inadvertently trigger hover-based or click-based animations. These accidental triggers can cause disorientation, unintended navigation, or physical discomfort.

Why it matters

Motion is a powerful communication tool, but for many users it is a barrier. WCAG 2.3.3 (Level AAA) requires that motion from interactions be optional unless the movement is essential. Failing this criterion excludes people with vestibular, cognitive, and motor disabilities. Beyond compliance, respecting reduced-motion preferences improves perceived performance, reduces battery drain on mobile devices, and demonstrates inclusive design maturity. Modern operating systems expose a prefers-reduced-motion setting; ignoring it signals that accessibility was not part of the design process.

Coding problems and solutions

Common coding problems

  • No prefers-reduced-motion support – CSS or JavaScript motion effects are written without querying the user’s system-level motion preference. The animations play regardless of the user’s OS setting.
  • Missing animation toggle – The site provides no visible, persistent control (button or switch) to disable motion animations globally. Users who cannot use OS-level settings have no fallback.
  • All-property transitions – Using transition: all or animating expensive properties (width, height, top, left) causes layout thrashing and increases the impact of motion sensitivity.
  • Uncontrolled scroll-triggered reveals – Intersection Observer or scroll listeners trigger CSS keyframes or JS-driven animations without checking for reduced-motion preferences, forcing motion on every visitor.
  • Interactive hover/focus animations without fallback – Buttons, cards, or menus scale, slide, or pulse on hover or focus, but no reduced-motion override removes or simplifies the movement.

How to fix it

Respect the prefers-reduced-motion media query

Use the prefers-reduced-motion media feature to serve reduced or no motion when the user has indicated that preference in their operating system.

Correct example

.card {
  transition: transform 0.3s ease, box-shadow 0.3s ease;
}

.card:hover,
.card:focus-visible {
  transform: scale(1.04);
  box-shadow: 0 8px 24px rgba(0, 0, 0, 0.12);
}

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

  .card:hover,
  .card:focus-visible {
    transform: none;
    box-shadow: 0 2px 8px rgba(0, 0, 0, 0.2);
  }
}
Incorrect example

.card {
  transition: transform 0.3s ease, box-shadow 0.3s ease;
}

.card:hover {
  transform: scale(1.04);
  box-shadow: 0 8px 24px rgba(0, 0, 0, 0.12);
}

Provide an explicit animation toggle

In addition to the media query, offer a visible button that lets users disable animations site-wide. Persist the preference with localStorage or a cookie.

Correct example

<button
  id="motionToggle"
  class="motion-toggle"
  aria-pressed="false"
  type="button"
>
  Disable animations
</button>

const toggle = document.getElementById('motionToggle');

const applyPreference = (reduce) => {
  document.body.classList.toggle('reduced-motion', reduce);
  toggle.setAttribute('aria-pressed', String(reduce));
  toggle.textContent = reduce
    ? 'Enable animations'
    : 'Disable animations';
  globalThis.localStorage.setItem('reducedMotion', String(reduce));
};

const stored = globalThis.localStorage.getItem('reducedMotion');
if (stored === 'true') {
  applyPreference(true);
}

const mql = globalThis.matchMedia('(prefers-reduced-motion: reduce)');
if (mql.matches && stored === null) {
  applyPreference(true);
}

toggle.addEventListener('click', () => {
  const next = toggle.getAttribute('aria-pressed') !== 'true';
  applyPreference(next);
});
Incorrect example

<button onclick="stopMotion()">Disable</button>

function stopMotion() {
  document.querySelectorAll('*').forEach((el) => {
    el.style.animation = 'none';
    el.style.transition = 'none';
  });
}

Limit animation to compositor-friendly properties

Restrict CSS transitions and animations to transform and opacity. These properties are handled on the compositor thread and avoid layout or paint recalculations, reducing both performance overhead and motion sensitivity.

Correct example

.modal {
  transition: transform 0.25s ease, opacity 0.25s ease;
}

.modal.closed {
  transform: translateY(-20px);
  opacity: 0;
}

@media (prefers-reduced-motion: reduce) {
  .modal {
    transition: opacity 0.15s ease;
  }

  .modal.closed {
    transform: none;
    opacity: 0;
  }
}
Incorrect example

.modal {
  transition: all 0.5s ease-in-out;
}

.modal.closed {
  width: 0;
  height: 0;
  opacity: 0;
  transform: translateY(-40px);
}

Disable scroll-triggered and interaction-driven effects

When using IntersectionObserver or scroll listeners to trigger reveals, wrap the animation logic in a preference check and provide a CSS-only reduced-motion override.

Correct example

.fade-in {
  opacity: 0;
  transform: translateY(24px);
  transition: opacity 0.6s ease, transform 0.6s ease;
}

.fade-in.visible {
  opacity: 1;
  transform: translateY(0);
}

@media (prefers-reduced-motion: reduce) {
  .fade-in {
    opacity: 1;
    transform: none;
    transition: none;
  }
}

const prefersReduced = globalThis.matchMedia(
  '(prefers-reduced-motion: reduce)'
);

if (!prefersReduced.matches) {
  const observer = new globalThis.IntersectionObserver((entries) => {
    entries.forEach((entry) => {
      if (entry.isIntersecting) {
        entry.target.classList.add('visible');
        observer.unobserve(entry.target);
      }
    });
  });

  document.querySelectorAll('.fade-in').forEach((el) => {
    observer.observe(el);
  });
}
Incorrect example

const observer = new IntersectionObserver((entries) => {
  entries.forEach((entry) => {
    if (entry.isIntersecting) {
      entry.target.classList.add('visible');
    }
  });
});

document.querySelectorAll('.fade-in').forEach((el) => {
  observer.observe(el);
});

Known Limitations

  • Single-page applications (SPAs) – Route transitions in client-side frameworks (Angular, React, Vue) often inject animations independently of prefers-reduced-motion. Framework-level wrappers must check the media query or a global state flag on every route change.
  • Shadow DOM – Motion animations defined inside shadow roots are not governed by the host page’s animation toggle. Custom elements must independently query prefers-reduced-motion using globalThis.matchMedia.
  • Third-party embeds and iframes – Embedded widgets (videos, social feeds, maps, ad units) may animate independently. The host page cannot control their motion without postMessage coordination, which is rarely implemented.
  • JavaScript-driven animation libraries – Libraries such as GSAP, Framer Motion, or the Web Animations API do not automatically respect prefers-reduced-motion. Each animation call must be wrapped in a conditional that checks the preference before starting.
  • Essential animation edge cases – Some motion is essential (loading spinners, progress bars, pulsing error indicators). Distinguishing essential from decorative requires manual judgment, which is why this rule is semi-automated and flagged for human review.

Resources

Rule

  • Audit: accessibility
  • Standard: WCAG
  • Level: AAA
  • Success Criteria: 2.3.3
  • Rule ID:animation-interaction