tailwind-a11y 0.13.0 → 0.13.5

package/dist/parser/extractClasses.js

@@ -26,16 +26,28 @@ const NON_COLOR_SCALE_NAMES = new Set(["opacity", "linear", "conic"]);
 export function lastColorToken(className, prefix) {
     let found = null;
     for (const raw of className.split(/\s+/).filter(Boolean)) {
-        const base = raw.slice(raw.lastIndexOf(":") + 1); // strip hover:/dark:/md: variants
-        if (!base.startsWith(`${prefix}-`))
+        // Variant-scoped classes (hover:/dark:/md:/...) are skipped entirely,
+        // not stripped down to their base utility -- fixed after independent
+        // testing found a real false negative: `bg-white dark:bg-gray-900`
+        // with `text-gray-300` silently passed, because stripping the `dark:`
+        // prefix let it participate in last-token-wins as if it were the real,
+        // always-rendered resting-state background, when `dark:bg-gray-900`
+        // only ever applies under a completely different condition. Mirrors
+        // `extractTouchTargets.ts`'s `lastSizeToken`, which already excludes
+        // any variant-scoped size token from resting-state resolution the same
+        // way (`if (raw.includes(":")) continue;`) -- this had no equivalent
+        // guard for colors.
+        if (raw.includes(":"))
             continue;
-        const rest = base.slice(prefix.length + 1);
+        if (!raw.startsWith(`${prefix}-`))
+            continue;
+        const rest = raw.slice(prefix.length + 1);
         if (!COLOR_TOKEN.test(rest))
             continue;
         const scaleName = /^([a-z]+)-\d/.exec(rest)?.[1];
         if (scaleName && NON_COLOR_SCALE_NAMES.has(scaleName))
             continue;
-        found = base;
+        found = raw;
     }
     return found;
 }

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 = [];
@@ -115,23 +149,30 @@ const FOCUS_INDICATOR_MIN_THICKNESS_PX = 2;
 // can't currently distinguish, so bare ring/outline contributes color (if
 // paired with an explicit color utility) but never a thickness value.
 const WIDTH_SCALE = { "0": 0, "1": 1, "2": 2, "4": 4, "8": 8 };
-// Near-duplicate of extractClasses.ts's lastColorToken, not a call to it:
-// that function takes a single prefix ("text" | "bg") and this needs
-// last-token-wins across *two* prefixes (outline-*, ring-*) in one pass, so
-// whichever was actually written last in the class list wins regardless of
-// which utility it is. Reuses COLOR_TOKEN (the one shared "is this
-// color-shaped" test) and only excludes the "opacity" scale name locally --
-// lastColorToken's full NON_COLOR_SCALE_NAMES set also excludes
-// "linear"/"conic", but those are bg-gradient-angle utilities with no
-// outline-*/ring-* equivalent, so they can never appear here.
-function lastIndicatorColorToken(focusClasses) {
+// Last-token-wins WITHIN one prefix only. Fixed after independent testing
+// found a real bug: the original version raced outline-* against ring-*
+// in one shared last-token-wins slot, so an element with BOTH a passing
+// outline-* and a failing ring-* (or vice versa) got a verdict that
+// depended purely on which was written later in the class string -- even
+// though outline-*/ring-* are two independent CSS mechanisms
+// (outline-color/-width vs. box-shadow) that both render simultaneously
+// regardless of order (verified against a real Tailwind v4 build).
+// Last-token-wins is still correct *within* a single prefix (e.g.
+// `outline-red-500 outline-blue-600` really does render as blue-600, the
+// later declaration winning in CSS) -- only racing the two prefixes
+// against each other was wrong. Reuses COLOR_TOKEN (the shared
+// "is this color-shaped" test) and only excludes the "opacity" scale name
+// locally -- extractClasses.ts's lastColorToken's full NON_COLOR_SCALE_NAMES
+// set also excludes "linear"/"conic", but those are bg-gradient-angle
+// utilities with no outline-*/ring-* equivalent, so they can never appear
+// here.
+function lastColorTokenForIndicator(focusClasses, prefix) {
     let found = null;
     for (const raw of focusClasses) {
         const base = raw.slice(raw.lastIndexOf(":") + 1);
-        const match = /^(?:outline|ring)-(.+)$/.exec(base);
-        if (!match)
+        if (!base.startsWith(`${prefix}-`))
             continue;
-        const rest = match[1];
+        const rest = base.slice(prefix.length + 1);
         if (!COLOR_TOKEN.test(rest))
             continue;
         const scaleName = /^([a-z]+)-\d/.exec(rest)?.[1];
@@ -141,19 +182,18 @@ function lastIndicatorColorToken(focusClasses) {
     }
     return found;
 }
-// Same last-token-wins-across-both-prefixes shape as above, but for width:
-// only an enumerated outline-{N}/ring-{N} or an arbitrary [Npx] sets a
-// thickness. A color token (ring-blue-400), ring-offset-*, ring-inset, etc.
-// don't match either shape and are silently ignored here -- they're a
-// different utility's job (color, offset, inset), not this one's.
-function lastIndicatorThicknessPx(focusClasses) {
+// Same per-prefix last-token-wins shape as above, but for width: only an
+// enumerated outline-{N}/ring-{N} or an arbitrary [Npx] sets a thickness.
+// A color token (ring-blue-400), ring-offset-*, ring-inset, etc. don't
+// match either shape and are silently ignored here -- they're a different
+// utility's job (color, offset, inset), not this one's.
+function thicknessTokenForIndicator(focusClasses, prefix) {
     let found = null;
     for (const raw of focusClasses) {
         const base = raw.slice(raw.lastIndexOf(":") + 1);
-        const match = /^(?:outline|ring)-(.+)$/.exec(base);
-        if (!match)
+        if (!base.startsWith(`${prefix}-`))
             continue;
-        const token = match[1];
+        const token = base.slice(prefix.length + 1);
         if (token in WIDTH_SCALE) {
             found = WIDTH_SCALE[token];
             continue;
@@ -169,26 +209,44 @@ export function checkFocusContrast(checks, strict = false, palette = defaultPale
     for (const check of checks) {
         if (!check.bgClass)
             continue; // no resolvable background — skip, not a guess
-        const indicatorBase = lastIndicatorColorToken(check.focusClasses);
-        if (!indicatorBase)
-            continue; // no explicit outline-*/ring-* color — out of scope, see CLAUDE.md
-        const indicatorHex = resolveColorValue(indicatorBase, palette);
         const bgHex = resolveColorValue(check.bgClass, palette);
-        if (!indicatorHex || !bgHex)
+        const bgRgb = bgHex ? hexToRgb(bgHex) : null;
+        if (!bgRgb)
             continue; // custom theme color / unsupported arbitrary value — skip
-        const indicatorRgb = hexToRgb(indicatorHex);
-        const bgRgb = hexToRgb(bgHex);
-        if (!indicatorRgb || !bgRgb)
-            continue;
-        const ratio = contrastRatio(indicatorRgb, bgRgb);
-        const contrastFails = ratio < NON_TEXT_MIN_RATIO;
-        let thicknessPx = null;
-        if (strict)
-            thicknessPx = lastIndicatorThicknessPx(check.focusClasses);
-        const thicknessFails = strict && thicknessPx !== null && thicknessPx < FOCUS_INDICATOR_MIN_THICKNESS_PX;
-        if (!contrastFails && !thicknessFails)
+        // outline-* and ring-* are evaluated as independent candidates, not
+        // raced against each other -- both are real, simultaneously-rendering
+        // mechanisms (see lastColorTokenForIndicator's comment for why), so an
+        // element can have zero, one, or both present at once.
+        const candidates = [];
+        for (const prefix of ["outline", "ring"]) {
+            const indicatorBase = lastColorTokenForIndicator(check.focusClasses, prefix);
+            if (!indicatorBase)
+                continue; // this mechanism isn't in use on this element
+            const indicatorHex = resolveColorValue(indicatorBase, palette);
+            const indicatorRgb = indicatorHex ? hexToRgb(indicatorHex) : null;
+            if (!indicatorRgb)
+                continue; // custom theme color / unsupported arbitrary value — skip this candidate
+            const ratio = contrastRatio(indicatorRgb, bgRgb);
+            const contrastFails = ratio < NON_TEXT_MIN_RATIO;
+            let thicknessPx = null;
+            if (strict)
+                thicknessPx = thicknessTokenForIndicator(check.focusClasses, prefix);
+            const thicknessFails = strict && thicknessPx !== null && thicknessPx < FOCUS_INDICATOR_MIN_THICKNESS_PX;
+            candidates.push({ indicatorBase, ratio, contrastFails, thicknessPx, thicknessFails });
+        }
+        if (candidates.length === 0)
+            continue; // no resolvable outline-*/ring-* color at all
+        // A user only needs ONE sufficiently visible (and, under strict,
+        // sufficiently thick) focus indicator to perceive the focus state --
+        // if any present candidate fully passes, this element is compliant
+        // even if another present indicator independently would have failed.
+        const allFail = candidates.every((c) => c.contrastFails || c.thicknessFails);
+        if (!allFail)
             continue;
-        const rawIndicatorClass = check.focusClasses.find((raw) => raw.slice(raw.lastIndexOf(":") + 1) === indicatorBase);
+        // More than one candidate present and both fail -- report the worst
+        // (lowest-ratio) offender.
+        const worst = candidates.reduce((a, b) => (b.ratio < a.ratio ? b : a));
+        const rawIndicatorClass = check.focusClasses.find((raw) => raw.slice(raw.lastIndexOf(":") + 1) === worst.indicatorBase);
         violations.push({
             type: "focus-contrast",
             file: check.file,
@@ -196,11 +254,11 @@ export function checkFocusContrast(checks, strict = false, palette = defaultPale
             tagName: check.tagName,
             indicatorClass: rawIndicatorClass,
             bgClass: check.bgClass,
-            ratio,
+            ratio: worst.ratio,
             required: NON_TEXT_MIN_RATIO,
-            level: thicknessFails ? "AAA" : "AA",
-            ...(thicknessFails && thicknessPx !== null
-                ? { thicknessPx, requiredThicknessPx: FOCUS_INDICATOR_MIN_THICKNESS_PX }
+            level: worst.thicknessFails ? "AAA" : "AA",
+            ...(worst.thicknessFails && worst.thicknessPx !== null
+                ? { thicknessPx: worst.thicknessPx, requiredThicknessPx: FOCUS_INDICATOR_MIN_THICKNESS_PX }
                 : {}),
         });
     }

package/dist/rules/checkReducedMotion.js

@@ -60,22 +60,60 @@ 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
+        // 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;
@@ -100,7 +138,7 @@ export function checkReducedMotion(checks, strict = false) {
             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.0",
+  "version": "0.13.5",
   "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": {