tailwind-a11y 0.13.1 → 0.14.0

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 `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

@@ -17,6 +17,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)
@@ -31,12 +34,32 @@ export function extractReducedMotionChecks(code, filePath) {
             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)));
+            // 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((v) => INTERACTION_VARIANTS.has(v));
+            });
             // 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/checkContrast.js

@@ -131,6 +131,24 @@ export function suggestContrastFix(textClass, bgClass, required, palette = defau
     }
     return null;
 }
+// resolveColorValue() bails out on any bg-side opacity modifier before ever
+// checking whether the underlying color is real (background-side opacity
+// compositing is out of scope -- see CLAUDE.md -- since it depends on
+// knowing what's rendered behind an already-semi-transparent background).
+// Caught in independent adversarial testing: this made checkContrastValueSkips
+// report `bg-gray-800/50 is not a recognized color`, even though gray-800
+// is a perfectly recognized default-palette color -- a developer reading
+// that message would reasonably (and pointlessly) try adding a theme entry
+// for it. Distinguishes the two cases by re-resolving the color with the
+// opacity suffix stripped off: if that succeeds, the real reason is the
+// out-of-scope opacity, not an unrecognized color.
+function bgSkipReason(bgColorClass, palette) {
+    const { base, alpha } = splitOpacityModifier(bgColorClass);
+    if (alpha < 1 && resolveColorValue(base, palette) !== null) {
+        return `${bgColorClass} is a recognized color, but background-side opacity isn't resolved (compositing it correctly requires knowing what's rendered behind it) — skipped`;
+    }
+    return `${bgColorClass} is not a recognized color (custom theme color or unsupported arbitrary value) — skipped`;
+}
 // A candidate that extractChecks *did* find a background for, but whose
 // text or bg utility didn't resolve to a known value (custom theme color,
 // non-hex arbitrary value, background-side opacity shorthand) — surfaced
@@ -150,11 +168,7 @@ export function checkContrastValueSkips(checks, palette = defaultPalette) {
         const bgHex = resolveColorValue(check.bgColorClass, palette);
         const bgRgb = bgHex ? hexToRgb(bgHex) : null;
         if (!bgRgb) {
-            skips.push({
-                file: check.file,
-                line: check.line,
-                reason: `${check.bgColorClass} is not a recognized color (custom theme color or unsupported arbitrary value) — skipped`,
-            });
+            skips.push({ file: check.file, line: check.line, reason: bgSkipReason(check.bgColorClass, palette) });
             continue;
         }
         const { alpha } = splitOpacityModifier(check.textColorClass);

package/dist/rules/checkFocusIndicator.js

@@ -11,9 +11,15 @@ const REMOVAL_BASE = "outline-none";
 // resets every element to `border: 0 solid`, so border-width stays 0
 // regardless of style and no border is ever drawn, same failure mode as
 // border-0.
+// inset-shadow-none/inset-ring-0 (Tailwind v4's inset-* box-shadow family,
+// missed by the original one-time audit -- these utilities didn't exist,
+// or weren't considered, at the time) are the exact same failure mode as
+// shadow-none/ring-0: verified against a real build that inset-shadow-none
+// computes to a fully transparent shadow and inset-ring-0 computes to a
+// 0px-wide inset ring, both real but invisible.
 const DEGENERATE_BASES = new Set([
     "outline-none", "ring-0", "border-0", "shadow-none", "bg-transparent",
-    "border-none", "border-hidden",
+    "border-none", "border-hidden", "inset-shadow-none", "inset-ring-0",
 ]);
 // Modifier-only utilities (opacity/offset/inset) don't set a concrete value
 // on their own — e.g. bg-opacity-50 with no bg-* color, or ring-offset-4
@@ -58,16 +64,35 @@ const NON_VISUAL_PATTERN = /^bg-blend-|^border-spacing(-[xy])?-/;
 // offset cases above, but shaped like a color token rather than a fixed
 // suffix, so it reuses COLOR_TOKEN (the exact same "is this a color value"
 // test extractClasses.ts uses) instead of a third, drifting definition of
-// what a color looks like.
+// what a color looks like. inset-shadow-{color}/inset-ring-{color} are the
+// same mechanism one prefix-family over (verified against a real build:
+// inset-shadow-blue-500 alone only sets --tw-inset-shadow-color,
+// inset-ring-blue-500 alone only sets --tw-inset-ring-color -- neither
+// produces a box-shadow without a companion size utility).
 function isColorOnlyShadowOrRing(base) {
-    const shadowMatch = /^shadow-(.+)$/.exec(base);
+    const shadowMatch = /^(?:inset-)?shadow-(.+)$/.exec(base);
     if (shadowMatch && COLOR_TOKEN.test(shadowMatch[1]))
         return true;
-    const ringMatch = /^ring-(.+)$/.exec(base);
+    const ringMatch = /^(?:inset-)?ring-(.+)$/.exec(base);
     if (ringMatch && COLOR_TOKEN.test(ringMatch[1]))
         return true;
     return false;
 }
+// ring-offset-{color} (e.g. ring-offset-blue-500) sets only the
+// --tw-ring-offset-color CSS variable -- the offset ring itself is only
+// ever drawn when a real ring width is *also* present (ring-2, etc.),
+// verified against a real Tailwind v4 build. MODIFIER_ONLY above already
+// excludes the numeric width form (ring-offset-4), but its regex requires
+// digits after "offset-", so it never matched this color-shaped form --
+// caught in independent adversarial testing (a real false negative: this
+// fell through to the generic ring-* prefix match at the bottom of
+// isReplacement and was silently accepted as a real replacement). One
+// level deeper than isColorOnlyShadowOrRing above, so a separate check
+// rather than folding into it.
+function isColorOnlyRingOffset(base) {
+    const match = /^ring-offset-(.+)$/.exec(base);
+    return !!match && COLOR_TOKEN.test(match[1]);
+}
 function baseUtility(raw) {
     return raw.slice(raw.lastIndexOf(":") + 1);
 }
@@ -79,7 +104,16 @@ function isReplacement(raw) {
         return false;
     if (isColorOnlyShadowOrRing(base))
         return false;
-    return /^(ring|border|shadow|bg|outline)(-|$)/.test(base);
+    if (isColorOnlyRingOffset(base))
+        return false;
+    // inset-shadow-*/inset-ring-* (Tailwind v4) are their own prefix
+    // families, not `ring`/`shadow` with a suffix -- a string starting with
+    // "inset-" doesn't match the "shadow"/"ring" alternatives below at all,
+    // so a real inset-shadow-sm/inset-ring-2 replacement was previously
+    // rejected outright (a false positive on the overall check: it reported
+    // the outline as removed with nothing put back, when something real
+    // was). Caught in independent adversarial testing.
+    return /^(ring|border|shadow|bg|outline|inset-shadow|inset-ring)(-|$)/.test(base);
 }
 export function checkFocusIndicators(checks) {
     const violations = [];

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

@@ -44,6 +44,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
@@ -60,22 +71,93 @@ export function checkReducedMotion(checks, strict = false) {
         return [];
     const violations = [];
     for (const check of checks) {
-        let unscopedTransition = null;
+        let realTransition = null;
         let hasMotionReduceGuard = false;
         for (const raw of check.classes) {
             const base = baseUtility(raw);
             const segments = variantSegments(raw);
-            if (segments.length === 0 && TRANSITION_BASES.has(base))
-                unscopedTransition = raw;
-            if (segments.includes("motion-reduce") && (base === "transition-none" || base === "transform-none")) {
+            // A transition counts as "real" (needs checking) unless its variant
+            // stack makes it not actually apply at the moment the interaction
+            // begins:
+            //  - an interaction pseudo-class (hover:/focus:/focus-within:/
+            //    active:) anywhere in the stack means the transition-property
+            //    only exists *during* that momentary state, not before it -- CSS
+            //    has nothing to transition *from* right as the interaction
+            //    starts, so `hover:transition-transform hover:scale-110` still
+            //    snaps instantly, same as before this fix (this is the one case
+            //    the original `segments.length === 0` check happened to get
+            //    right, so it's preserved here under its real reason instead).
+            //  - motion-safe: anywhere in the stack means the transition simply
+            //    doesn't exist unless motion is already safe -- a complete,
+            //    persistent exemption, unrelated to interaction timing.
+            // Any *other* scoping (dark:, sm:, lg:, ...) is a persistent
+            // precondition, not a momentary one -- the transition genuinely is
+            // present in the resting state whenever that condition holds, with
+            // zero relationship to prefers-reduced-motion. Caught in independent
+            // adversarial testing: the previous version required
+            // `segments.length === 0` (no variant at all), so
+            // `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 isMotionSafeGated = segments.includes("motion-safe");
+            if (TRANSITION_BASES.has(base) && !isInteractionGated && !isMotionSafeGated)
+                realTransition = raw;
+            // Only a *bare* motion-reduce:transition-none/transform-none (no
+            // other variant stacked with it) is trusted as a full guard --
+            // caught in independent adversarial testing: `sm:motion-reduce:
+            // transition-none` was being accepted as fully protective even
+            // though it only suppresses the transition at/above the `sm`
+            // breakpoint, leaving it completely unguarded below that width.
+            // Correctly modeling arbitrary variant-subset relationships (does
+            // this guard's other conditions always hold whenever the real
+            // trigger's conditions hold?) is out of scope -- requiring the
+            // guard to be unconditional is the same "skip/flag rather than
+            // guess" posture used everywhere else in this project, erring
+            // toward a false positive over the worse failure mode, a false
+            // negative.
+            if (segments.length === 1 && segments[0] === "motion-reduce" && (base === "transition-none" || base === "transform-none")) {
                 hasMotionReduceGuard = true;
             }
         }
-        // A transition scoped only under motion-safe: (never unscoped) means it
-        // simply doesn't exist unless motion is already safe -- a complete
+        // 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((v) => INTERACTION_VARIANTS.has(v)))
+                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
         // correctly falls through as a pass, not a skip-because-unresolvable.
-        if (!unscopedTransition)
+        if (!realTransition)
             continue;
         if (hasMotionReduceGuard)
             continue;
@@ -97,10 +179,11 @@ 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,
-            transitionClass: unscopedTransition,
+            transitionClass: realTransition,
             motionClass,
             level: "AAA",
         });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tailwind-a11y",
-  "version": "0.13.1",
+  "version": "0.14.0",
   "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": {