Tailwind animations and WCAG 2.2.2: the motion-safe: trap

Kevin Fröba · 2026-08-29 · MotionSpec

Prefixing a Tailwind animation with motion-safe: closes the WCAG 2.3.3 gap, not the WCAG 2.2.2 one. Those are two different rails. motion-safe: honours an operating-system preference — it does nothing for the far larger group of users who have never opened that setting. And all four of Tailwind's built-in animation utilities are declared infinite, which is exactly the pattern WCAG 2.2.2 Pause, Stop, Hide (Level A) is written about. This guide shows where the line falls, what we measured on Tailwind's own documentation page, and the two fixes that actually move a loop out of 2.2.2's scope.

What do motion-safe: and motion-reduce: actually do?

motion-safe: and motion-reduce: are variants that wrap a utility in a prefers-reduced-motion media query. The Tailwind documentation introduces them in one sentence:

"For situations where the user has specified that they prefer reduced motion, you can conditionally apply animations and transitions using the motion-safe and motion-reduce variants."

— Tailwind CSS docs, Animation

That is a good default and you should use it. motion-safe:animate-spin compiles to a rule inside @media (prefers-reduced-motion: no-preference), so a visitor who has switched on Reduce Motion in macOS, Windows, iOS or Android gets a still spinner instead of a rotating one. If the media feature itself is new to you, our prefers-reduced-motion guide covers the vocabulary and the four ways to test it.

Why doesn't motion-safe: satisfy WCAG 2.2.2?

Because 2.2.2 is not about a preference — it is about a control. The criterion asks that any moving content which starts automatically, runs longer than five seconds and sits alongside other content offers the user a mechanism to pause, stop or hide it. A media query is not a mechanism the user can operate; it is a branch the developer took on their behalf, and only for the subset of people who found the OS setting.

The practical consequence is easy to state. Take a badge with motion-safe:animate-pulse next to a headline. For a visitor with Reduce Motion on, it is still. For everyone else — the overwhelming majority — it pulses for as long as the page is open, with no way to stop it. That is the 2.2.2 pattern, unchanged by the variant. Conversely, a page with a working pause button and no motion-safe: anywhere satisfies 2.2.2 and still ignores the OS preference. The two rails do not substitute for each other, and robust motion ships both.

Which Tailwind utilities loop forever?

All four built-ins. In Tailwind v4 the animation utilities resolve through theme variables rather than carrying the animation shorthand directly, and every one of the four ends in the infinite keyword. These are the values as published in Tailwind's theme.css (v4.1.11):

Values read from tailwindcss@4.1.11/theme.css on 2026-08-29. Tailwind ships these as sensible defaults; the point here is not that they are wrong, but that the infinite keyword decides which WCAG lane you are in.

There is a second-order effect worth knowing if you run any static tooling over your CSS. Because the utility compiles to .animate-pulse { animation: var(--animate-pulse) }, the literal word infinite is not in the utility rule — it is one indirection away, in the variable. A scanner that reads declarations without resolving custom properties can see the animation and miss that it never ends. Ours is one of them; more on that below.

What we measured on Tailwind's own documentation page

On 2026-08-29 we ran the free motion check against https://tailwindcss.com/docs/animation. The result: score 55/100, 18 distinct motion root causes across 32 occurrences. All four built-in utilities were reported individually — .animate-spin, .animate-ping, .animate-pulse, .animate-bounce — each under the rule "Motion without prefers-reduced-motion guard", in the WCAG 2.3.3 lane.

Read that finding correctly, because it is not a criticism of Tailwind. A framework's job is to define the utility; deciding whether a given animation should be guarded is the application's job, and the variant Tailwind ships for exactly that purpose is documented on that very page. What the scan measures is the compiled stylesheet: in it, the four utility rules genuinely carry no guard, because the guard is opt-in per usage. That is the design, and it is also precisely why the trap exists — the default is unguarded, and the guarded form takes eleven extra characters that nothing enforces.

The same scan reported zero findings under the WCAG 2.2.2 rule on that page, even though all four utilities are infinite. That is the custom-property indirection described above, and it is the honest limit of the tool, not a clean bill of health.

How do you move a Tailwind loop out of 2.2.2's scope?

Two options: bound the loop, or wire a real control. Ship the motion-safe: guard alongside either one — it is still the right default for the 2.3.3 rail.

Option A — bound it. If the motion is decorative, give it a finite iteration count so it ends inside five seconds and leaves the criterion entirely. Tailwind's arbitrary-value syntax takes the whole shorthand:

<!-- Before: pulses forever -->
<span class="motion-safe:animate-pulse">New</span>

<!-- After: two iterations, 4s total, then it stops -->
<span class="motion-safe:animate-[pulse_2s_cubic-bezier(0.4,0,0.6,1)_2]">New</span>

Option B — wire a control. If the motion must keep running — a genuine activity indicator, a ticker, a logo strip — give the page one keyboard-operable button that halts it. A single data attribute on the root plus one CSS rule covers every animation on the page at once:

/* One rule pauses every CSS animation under the flag. */
html[data-motion-paused] *,
html[data-motion-paused] *::before,
html[data-motion-paused] *::after {
  animation-play-state: paused !important;
}

/* The OS-preference rail, unchanged and still worth shipping. */
@media (prefers-reduced-motion: reduce) {
  .animate-spin, .animate-ping, .animate-pulse, .animate-bounce {
    animation: none;
  }
}

<button type="button" id="motion-toggle" aria-pressed="false">Pause animation</button>

<script>
  const btn = document.getElementById('motion-toggle');
  btn.addEventListener('click', () => {
    const paused = document.documentElement.toggleAttribute('data-motion-paused');
    btn.setAttribute('aria-pressed', String(paused));
    btn.textContent = paused ? 'Resume animation' : 'Pause animation';
  });
</script>

The control has to be visible, reachable by keyboard, and it has to actually stop the movement. A hover-pause does not qualify: it ends the moment the pointer leaves, and a keyboard user never triggers it at all. For the most common case on an agency site — the scrolling client-logo strip — the complete build is in the infinite logo marquee that passes WCAG 2.2.2.

What this does not cover

• Whether your spinner was ever in scope. 2.2.2 needs all three conditions — automatic start, more than five seconds, presented in parallel with other content. A spinner that resolves in two seconds, or one that is the only thing on a blocking load screen, is a different case. Nothing automated can make that call for you.
• Whether a control qualifies. A scan can prove a pause path is absent. It cannot judge whether the button you added is findable, operable and genuinely halts the motion. That stays a human review.
• Motion your CSS never sees. Anything animated from JavaScript — Motion for React, GSAP, the Web Animations API, scroll libraries — is invisible to a static CSS scan. See GSAP and prefers-reduced-motion for that half of the problem.
• The custom-property indirection above. On a Tailwind v4 build our scan reports the four built-ins as unguarded but not as infinite. Treat a quiet 2.2.2 result on a Tailwind page as "not yet checked", and grep your own markup for animate-spin, animate-ping, animate-pulse and animate-bounce.

FAQ

Does motion-safe: make a Tailwind animation pass WCAG?

No. motion-safe: applies the animation only when the user has not asked for reduced motion, which addresses WCAG 2.3.3 (Animation from Interactions, Level AAA). WCAG 2.2.2 (Pause, Stop, Hide, Level A) asks for a mechanism any user can operate on the page, whatever their OS settings. A motion-safe: prefixed infinite animation still runs forever for every user who never set the preference.

Do animate-spin, animate-ping, animate-pulse and animate-bounce loop forever?

Yes. In Tailwind v4 the four built-in utilities resolve through theme variables that all end in the infinite keyword: --animate-spin is spin 1s linear infinite, --animate-ping is ping 1s cubic-bezier(0, 0, 0.2, 1) infinite, --animate-pulse is pulse 2s cubic-bezier(0.4, 0, 0.6, 1) infinite and --animate-bounce is bounce 1s infinite.

Is a loading spinner a WCAG 2.2.2 failure?

It depends on what surrounds it. 2.2.2 applies to motion that starts automatically, lasts more than five seconds and is presented in parallel with other content. A spinner on a blocking load screen with nothing else on it is commonly treated as out of scope; the same spinner inside a page full of content, spinning indefinitely, is in scope. Duration matters too: a spinner that resolves in two seconds never crosses the five-second line.

How do you add a pause path to a Tailwind animation?

Bound the loop or wire a control. Bounding is an arbitrary-value utility such as animate-[pulse_2s_cubic-bezier(0.4,0,0.6,1)_2] so the animation ends on its own. A control is a keyboard-operable button that toggles a data attribute on the root, with a CSS rule that sets animation-play-state: paused under that attribute. Both patterns are above.

Shipping Tailwind sites for clients? The agency motion handoff, and what we found on 22 agency home pages →

MotionSpec checks and compiles UI animation for AI-generated web apps — it does not generate AI video.