tailwind-a11y 0.13.5 → 0.14.1

package/README.md

@@ -57,7 +57,7 @@ Exits `1` on violations — safe to use as a CI gate.
 | Touch target | 2.5.8 (AA) | Interactive elements under 24×24px — or 44×44px with `--strict` (2.5.5, AAA) |
 | Focus indicator | 2.4.7 (AA) | `focus:outline-none` with no visible replacement |
 | Focus indicator contrast | 1.4.11 (AA) | A present `outline-*`/`ring-*` focus indicator below 3:1 contrast — or also below the 2px minimum thickness with `--strict` (2.4.13, AAA) |
-| Reduced motion | 2.3.3 (AAA, `--strict` only) | A `hover:`/`focus:`/`focus-visible:`/`active:`-scoped `scale-*`/`rotate-*`/`translate-*`/`skew-*` change with an unscoped `transition`/`transition-all`/`transition-transform` and no `motion-reduce:`/`motion-safe:` handling |
+| Reduced motion | 2.3.3 (AAA, `--strict` only) | A `hover:`/`focus:`/`focus-visible:`/`active:`-scoped (or their `group-*`/`peer-*` equivalents) `scale-*`/`rotate-*`/`translate-*`/`skew-*` change with an unscoped `transition`/`transition-all`/`transition-transform`, or an `animate-spin`/`-ping`/`-bounce` under the same variants, with no `motion-reduce:`/`motion-safe:` handling |
 
 ## Scope
 

package/dist/cli.js

@@ -36,7 +36,9 @@ function formatViolation(v) {
                 : base;
         }
         case "reduced-motion":
-            return `${v.line}: <${v.tagName}> animates ${v.motionClass} via ${v.transitionClass} with no motion-reduce:transition-none/transform-none guard — WCAG 2.3.3 requires motion animation triggered by interaction to be disableable`;
+            return v.mechanism === "animate"
+                ? `${v.line}: <${v.tagName}> animates ${v.motionClass} via a CSS animation with no motion-reduce:animate-none guard — WCAG 2.3.3 requires motion animation triggered by interaction to be disableable`
+                : `${v.line}: <${v.tagName}> animates ${v.motionClass} via ${v.transitionClass} with no motion-reduce:transition-none/transform-none guard — WCAG 2.3.3 requires motion animation triggered by interaction to be disableable`;
     }
 }
 function groupByFile(items) {

package/dist/parser/extractReducedMotion.js

@@ -1,7 +1,34 @@
 import * as t from "@babel/types";
 import { getStaticClassName, parseJSX, traverse } from "./babelInterop.js";
 const TRANSITION_BASES = new Set(["transition", "transition-all", "transition-transform"]);
-const INTERACTION_VARIANTS = new Set(["hover", "focus", "focus-visible", "focus-within", "active"]);
+// group-hover:/peer-hover:/etc. compile to the identical momentary-pseudo-
+// class shape as bare hover:, just evaluated against an ancestor/sibling
+// (.group/.peer marker) instead of the element itself -- verified against a
+// real Tailwind v4 build (`.group-hover\:scale-110:is(:where(.group):hover *)`).
+// Deliberately NOT extended to has-*:/arbitrary variants ([&:hover]:, already
+// an established out-of-scope precedent for this file -- unbounded selector
+// text, not a closed enumerable set) or in-*: (a real v4.1+ ancestor-state
+// variant with the identical shape, but a legitimate separate follow-up, not
+// folded into this set).
+const INTERACTION_VARIANTS = new Set([
+    "hover", "focus", "focus-visible", "focus-within", "active",
+    "group-hover", "group-focus", "group-focus-visible", "group-focus-within", "group-active",
+    "peer-hover", "peer-focus", "peer-focus-visible", "peer-focus-within", "peer-active",
+]);
+// Named groups/peers (`group-hover/sidebar:scale-110`) compile the group
+// name into the variant token itself via a slash
+// (`.group-hover\/sidebar\:scale-110:is(:where(.group\/sidebar):hover *)`),
+// so variantSegments() returns "group-hover/sidebar" verbatim -- a plain
+// Set.has() would miss it. Safe to slice on the first "/" and re-check:
+// Tailwind's opacity-modifier slash (`text-black/50`) lives inside the base
+// utility segment (after the last ":"), never inside a variant segment, so
+// there's no collision to worry about here.
+function isInteractionVariant(v) {
+    if (INTERACTION_VARIANTS.has(v))
+        return true;
+    const slash = v.indexOf("/");
+    return slash !== -1 && INTERACTION_VARIANTS.has(v.slice(0, slash));
+}
 function baseUtility(raw) {
     return raw.slice(raw.lastIndexOf(":") + 1);
 }
@@ -17,6 +44,9 @@ function baseUtility(raw) {
 function variantSegments(raw) {
     return raw.split(":").slice(0, -1);
 }
+function isAnimateBase(base) {
+    return base.startsWith("animate-");
+}
 export function extractReducedMotionChecks(code, filePath) {
     const ast = parseJSX(code, filePath);
     if (!ast)
@@ -30,13 +60,33 @@ export function extractReducedMotionChecks(code, filePath) {
                 return;
             const classes = className.split(/\s+/).filter(Boolean);
             const hasTransitionBase = classes.some((raw) => TRANSITION_BASES.has(baseUtility(raw)));
-            const hasInteractionClass = classes.some((raw) => variantSegments(raw).some((v) => INTERACTION_VARIANTS.has(v)));
+            const hasInteractionClass = classes.some((raw) => variantSegments(raw).some(isInteractionVariant));
+            // A second, independent candidacy path for animate-* utilities, which
+            // carry their own `animation` property and need no transition-*  base
+            // at all -- `hover:animate-bounce` alone must be a candidate even
+            // though `hasTransitionBase` is false. Deliberately a SINGLE-class
+            // condition (one class must be both an animate-* base AND
+            // interaction-scoped in its own variant stack), not two independent
+            // whole-element flags like hasTransitionBase/hasInteractionClass
+            // above: unlike transition-transform (never itself interaction-scoped)
+            // paired with a separate hover:scale-110, an animate-* class is
+            // simultaneously its own trigger and its own animator. Two independent
+            // flags would wrongly treat `animate-spin hover:text-red-500` (an
+            // unscoped, continuously-running animation next to an unrelated hover
+            // class) as a candidate -- that's 2.2.2 (Pause/Stop/Hide) territory,
+            // not 2.3.3, per the same reasoning checkReducedMotion.ts already
+            // documents for why unscoped animate-* is out of scope here.
+            const hasInteractionScopedAnimate = classes.some((raw) => {
+                const base = baseUtility(raw);
+                return isAnimateBase(base) && variantSegments(raw).some(isInteractionVariant);
+            });
             // Not a candidate at all unless there's some transition utility
-            // (scoped or not) *and* some interaction-scoped class -- narrows the
-            // set of elements checkReducedMotion.ts has to reason about, without
-            // pre-deciding any of the nuance (unscoped vs motion-safe:, identity
-            // values, motion-reduce: guards) that belongs in the rule.
-            if (!hasTransitionBase || !hasInteractionClass)
+            // (scoped or not) *and* some interaction-scoped class, OR an
+            // interaction-scoped animate-* class -- narrows the set of elements
+            // checkReducedMotion.ts has to reason about, without pre-deciding any
+            // of the nuance (unscoped vs motion-safe:, identity/non-motion
+            // animate-* names, motion-reduce: guards) that belongs in the rule.
+            if ((!hasTransitionBase || !hasInteractionClass) && !hasInteractionScopedAnimate)
                 return;
             checks.push({
                 file: filePath,

package/dist/rules/checkReducedMotion.d.ts

@@ -1,11 +1,20 @@
 import type { ReducedMotionCheck } from "../parser/extractReducedMotion.js";
-export interface ReducedMotionViolation {
+export type ReducedMotionViolation = {
     type: "reduced-motion";
+    mechanism: "transition";
     file: string;
     line: number;
     tagName: string;
     transitionClass: string;
     motionClass: string;
     level: "AAA";
-}
+} | {
+    type: "reduced-motion";
+    mechanism: "animate";
+    file: string;
+    line: number;
+    tagName: string;
+    motionClass: string;
+    level: "AAA";
+};
 export declare function checkReducedMotion(checks: ReducedMotionCheck[], strict?: boolean): ReducedMotionViolation[];

package/dist/rules/checkReducedMotion.js

@@ -5,7 +5,25 @@
 // animates (the browser has nothing telling it to transition that
 // property), and correctly isn't flagged.
 const TRANSITION_BASES = new Set(["transition", "transition-all", "transition-transform"]);
-const INTERACTION_VARIANTS = new Set(["hover", "focus", "focus-visible", "focus-within", "active"]);
+// group-hover:/peer-hover:/etc. compile to the identical momentary-pseudo-
+// class shape as bare hover:, just evaluated against an ancestor/sibling
+// (.group/.peer marker) instead of the element itself -- see the identical
+// set (and full explanation) in extractReducedMotion.ts. Deliberately NOT
+// extended to has-*:/arbitrary variants or in-*: -- see that file's comment.
+const INTERACTION_VARIANTS = new Set([
+    "hover", "focus", "focus-visible", "focus-within", "active",
+    "group-hover", "group-focus", "group-focus-visible", "group-focus-within", "group-active",
+    "peer-hover", "peer-focus", "peer-focus-visible", "peer-focus-within", "peer-active",
+]);
+// Named groups/peers (`group-hover/sidebar:...`) put the group name in the
+// variant token itself via a slash -- see extractReducedMotion.ts for the
+// full explanation of why slicing on the first "/" is safe here.
+function isInteractionVariant(v) {
+    if (INTERACTION_VARIANTS.has(v))
+        return true;
+    const slash = v.indexOf("/");
+    return slash !== -1 && INTERACTION_VARIANTS.has(v.slice(0, slash));
+}
 function baseUtility(raw) {
     return raw.slice(raw.lastIndexOf(":") + 1);
 }
@@ -44,6 +62,17 @@ function isNonIdentityMotionUtility(base) {
         return Number(skew[2]) !== 0;
     return false;
 }
+// Verified against a real Tailwind v4 build's compiled keyframes:
+// animate-spin -> rotate(360deg) (orientation/shape change), animate-ping ->
+// scale(2)+opacity:0 (includes a size change), animate-bounce ->
+// translateY(-25%) (position change) -- all three qualify as "motion
+// animation" per this project's own WCAG 2.3.3 boundary (size/shape/
+// position, not color/opacity/blur). animate-pulse is opacity-only (excluded,
+// same reason color/opacity transitions don't count above) and animate-none
+// is the off/identity value (excluded, same treatment as scale-100/rotate-0).
+// A fully enumerated set, not a regex -- unlike scale/rotate/translate/skew,
+// none of these utilities take an arbitrary numeric value to range-check.
+const ANIMATE_MOTION_BASES = new Set(["animate-spin", "animate-ping", "animate-bounce"]);
 // `strict` gates the whole check for the scan-everything-by-default
 // adapters (CLI/VS Code/GitHub Action) -- WCAG 2.3.3 is AAA-only, and
 // unconditionally enabling a brand-new AAA check would silently start
@@ -88,7 +117,7 @@ export function checkReducedMotion(checks, strict = false) {
             // `dark:transition hover:scale-110` was silently treated as
             // compliant even though it animates on hover in dark mode
             // regardless of the user's motion preference.
-            const isInteractionGated = segments.some((v) => INTERACTION_VARIANTS.has(v));
+            const isInteractionGated = segments.some(isInteractionVariant);
             const isMotionSafeGated = segments.includes("motion-safe");
             if (TRANSITION_BASES.has(base) && !isInteractionGated && !isMotionSafeGated)
                 realTransition = raw;
@@ -109,6 +138,39 @@ export function checkReducedMotion(checks, strict = false) {
                 hasMotionReduceGuard = true;
             }
         }
+        // Independent detection path for the animate-* mechanism -- deliberately
+        // NOT nested after the transition path's `continue`s below, since
+        // `hover:animate-bounce` alone has no transition base at all
+        // (realTransition stays null), which would skip past this block entirely
+        // if it were placed after the `if (!realTransition) continue;` line. A
+        // single element can have a real violation on both mechanisms at once
+        // (independently pushed), or on just one -- they don't race for one slot.
+        const hasMotionReduceAnimateGuard = check.classes.some((raw) => {
+            const segments = variantSegments(raw);
+            return segments.length === 1 && segments[0] === "motion-reduce" && baseUtility(raw) === "animate-none";
+        });
+        const animateMotionClass = check.classes.find((raw) => {
+            const segments = variantSegments(raw);
+            // Same self-guard and interaction-scoping reasoning as the transition
+            // side's motionClass find below -- see its comment for the full
+            // explanation of why both checks are per-candidate, not per-element.
+            if (segments.includes("motion-safe"))
+                return false;
+            if (!segments.some(isInteractionVariant))
+                return false;
+            return ANIMATE_MOTION_BASES.has(baseUtility(raw));
+        });
+        if (animateMotionClass && !hasMotionReduceAnimateGuard) {
+            violations.push({
+                type: "reduced-motion",
+                mechanism: "animate",
+                file: check.file,
+                line: check.line,
+                tagName: check.tagName,
+                motionClass: animateMotionClass,
+                level: "AAA",
+            });
+        }
         // No real (non-motion-safe-guarded) transition at all means it simply
         // doesn't exist unless motion is already safe -- a complete
         // alternative way of satisfying 2.3.3, not a partial one -- so this
@@ -127,7 +189,7 @@ export function checkReducedMotion(checks, strict = false) {
             // self-guarded at the same time, e.g. `hover:motion-safe:scale-110`).
             if (segments.includes("motion-safe"))
                 return false;
-            if (!segments.some((v) => INTERACTION_VARIANTS.has(v)))
+            if (!segments.some(isInteractionVariant))
                 return false;
             return isNonIdentityMotionUtility(baseUtility(raw));
         });
@@ -135,6 +197,7 @@ export function checkReducedMotion(checks, strict = false) {
             continue; // no real, un-self-guarded motion actually triggered by interaction
         violations.push({
             type: "reduced-motion",
+            mechanism: "transition",
             file: check.file,
             line: check.line,
             tagName: check.tagName,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tailwind-a11y",
-  "version": "0.13.5",
+  "version": "0.14.1",
   "description": "Static analysis CLI that catches WCAG accessibility violations — color contrast, touch target size, and focus indicator removal/contrast — in Tailwind CSS class combinations before they ship.",
   "type": "module",
   "bin": {