tailwind-a11y 0.14.0 → 0.15.0

package/README.md

@@ -53,11 +53,11 @@ Exits `1` on violations — safe to use as a CI gate.
 
 | Check | WCAG | Detects |
 |---|---|---|
-| Contrast | 1.4.3 (AA) | `text-*`/`bg-*` pairs below 4.5:1, same-element or direct-parent, including a text-side opacity modifier (`text-gray-400/50`) composited against the background; suggests the nearest passing shade |
+| Contrast | 1.4.3 (AA) | `text-*`/`bg-*` pairs below 4.5:1, same-element or direct-parent, including a text-side opacity modifier (`text-gray-400/50`) composited against the background; also checks `placeholder:text-*` on `<input>`/`<textarea>`; suggests the nearest passing shade |
 | 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`, or an `animate-spin`/`-ping`/`-bounce` under the same variants, with 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/parser/extractClasses.js

@@ -23,6 +23,16 @@ export const COLOR_TOKEN = /^\[(#[0-9a-fA-F]{3,8})\](\/\d{1,3})?$|^[a-z]+-\d{2,3
 // the same failure mode: bg-linear-45 shares the word-number shape with
 // bg-red-500 and would otherwise mask it via last-token-wins.
 const NON_COLOR_SCALE_NAMES = new Set(["opacity", "linear", "conic"]);
+// One definition, not two hand-mirrored copies (lastColorToken and
+// lastPlaceholderColorToken both need this exact test) -- the same "one
+// definition, not a second copy that could drift" reasoning already applied
+// to COLOR_TOKEN itself.
+function isColorScaleToken(rest) {
+    if (!COLOR_TOKEN.test(rest))
+        return false;
+    const scaleName = /^([a-z]+)-\d/.exec(rest)?.[1];
+    return !(scaleName && NON_COLOR_SCALE_NAMES.has(scaleName));
+}
 export function lastColorToken(className, prefix) {
     let found = null;
     for (const raw of className.split(/\s+/).filter(Boolean)) {
@@ -42,15 +52,72 @@ export function lastColorToken(className, prefix) {
         if (!raw.startsWith(`${prefix}-`))
             continue;
         const rest = raw.slice(prefix.length + 1);
-        if (!COLOR_TOKEN.test(rest))
+        if (!isColorScaleToken(rest))
+            continue;
+        found = raw;
+    }
+    return found;
+}
+// placeholder:text-* targets the ::placeholder pseudo-element -- a
+// genuinely different rendered text than the element's own resting text
+// color, so it's checked as an independent candidate, not folded into
+// lastColorToken. Deliberately the exact two-segment shape only
+// (raw.split(":") === ["placeholder", "text-..."]) -- a nested shape like
+// dark:placeholder:text-gray-500 is NOT recognized. This isn't a narrower-
+// for-now cut, it's the only choice consistent with how lastColorToken
+// already treats every other variant-scoped color candidate in this same
+// file: skip outright rather than guess which persistent condition is
+// active. Returns the full raw string including the "placeholder:" prefix
+// -- checkContrast.ts's resolveColorValue/suggestContrastFix tolerate the
+// prefix directly, so every downstream message/skip-reason/suggestion
+// already reads correctly with zero further changes.
+function lastPlaceholderColorToken(className) {
+    let found = null;
+    for (const raw of className.split(/\s+/).filter(Boolean)) {
+        const segments = raw.split(":");
+        if (segments.length !== 2 || segments[0] !== "placeholder")
             continue;
-        const scaleName = /^([a-z]+)-\d/.exec(rest)?.[1];
-        if (scaleName && NON_COLOR_SCALE_NAMES.has(scaleName))
+        const base = segments[1];
+        if (!base.startsWith("text-"))
+            continue;
+        const rest = base.slice("text-".length);
+        if (!isColorScaleToken(rest))
             continue;
         found = raw;
     }
     return found;
 }
+// ::placeholder only exists on <input>/<textarea> in any browser -- a
+// placeholder:text-* class on any other tag is not "maybe irrelevant," it
+// is dead CSS, guaranteed never to render. Unlike reduced-motion's
+// deliberate "not scoped to isInteractiveElement()" choice (a hover-
+// animated <div> genuinely animates), tag-scoping here prevents a
+// guaranteed false positive rather than narrowing a genuine one. A small
+// local set, not a reuse of isInteractiveElement() -- that helper also
+// matches button/a/select and any onClick-bearing element, none of which
+// can render a placeholder.
+const PLACEHOLDER_CAPABLE_TAGS = new Set(["input", "textarea"]);
+function isPlaceholderCapable(openingElement) {
+    return (t.isJSXIdentifier(openingElement.name) && PLACEHOLDER_CAPABLE_TAGS.has(openingElement.name.name));
+}
+// Resolves an element's background exactly once (self, else immediate JSX
+// parent — see extractChecks' own scope note) so both the resting-text and
+// placeholder candidates share one bg/bgSource pair rather than each
+// re-walking the parent chain independently.
+function resolveBg(path) {
+    const className = getStaticClassName(path.node.openingElement.attributes);
+    const ownBg = className ? lastColorToken(className, "bg") : null;
+    if (ownBg)
+        return { bg: ownBg, source: "self" };
+    const parentNode = path.parentPath?.node;
+    if (parentNode && t.isJSXElement(parentNode)) {
+        const parentClassName = getStaticClassName(parentNode.openingElement.attributes);
+        const parentBg = parentClassName ? lastColorToken(parentClassName, "bg") : null;
+        if (parentBg)
+            return { bg: parentBg, source: "parent" };
+    }
+    return null;
+}
 export function extractChecks(code, filePath) {
     const ast = parseJSX(code, filePath);
     if (!ast)
@@ -62,23 +129,22 @@ export function extractChecks(code, filePath) {
             if (!className)
                 return;
             const textClass = lastColorToken(className, "text");
-            if (!textClass)
+            const placeholderClass = isPlaceholderCapable(path.node.openingElement)
+                ? lastPlaceholderColorToken(className)
+                : null;
+            if (!textClass && !placeholderClass)
                 return;
             const line = path.node.openingElement.loc?.start.line ?? 0;
-            const ownBg = lastColorToken(className, "bg");
-            if (ownBg) {
-                checks.push({ file: filePath, line, textColorClass: textClass, bgColorClass: ownBg, bgSource: "self" });
-                return;
-            }
             // Only the immediate JSX parent is considered — no deeper ancestor
             // walk and no cross-component resolution (see CLAUDE.md scope).
-            const parentNode = path.parentPath?.node;
-            if (parentNode && t.isJSXElement(parentNode)) {
-                const parentClassName = getStaticClassName(parentNode.openingElement.attributes);
-                const parentBg = parentClassName ? lastColorToken(parentClassName, "bg") : null;
-                if (parentBg) {
-                    checks.push({ file: filePath, line, textColorClass: textClass, bgColorClass: parentBg, bgSource: "parent" });
-                }
+            const bg = resolveBg(path);
+            if (!bg)
+                return;
+            if (textClass) {
+                checks.push({ file: filePath, line, textColorClass: textClass, bgColorClass: bg.bg, bgSource: bg.source });
+            }
+            if (placeholderClass) {
+                checks.push({ file: filePath, line, textColorClass: placeholderClass, bgColorClass: bg.bg, bgSource: bg.source });
             }
         },
     });
@@ -101,35 +167,37 @@ export function extractContrastSkips(code, filePath) {
             if (!className)
                 return;
             const textClass = lastColorToken(className, "text");
-            if (!textClass)
+            const placeholderClass = isPlaceholderCapable(path.node.openingElement)
+                ? lastPlaceholderColorToken(className)
+                : null;
+            if (!textClass && !placeholderClass)
                 return;
-            const ownBg = lastColorToken(className, "bg");
-            if (ownBg)
-                return; // extractChecks already covers this case
+            if (resolveBg(path))
+                return; // extractChecks already covers this case, for either candidate
             const line = path.node.openingElement.loc?.start.line ?? 0;
             const parentNode = path.parentPath?.node;
-            if (parentNode && t.isJSXElement(parentNode)) {
-                const parentClassName = getStaticClassName(parentNode.openingElement.attributes);
-                const parentBg = parentClassName ? lastColorToken(parentClassName, "bg") : null;
-                if (parentBg)
-                    return; // extractChecks already covers this case
-                const parentTag = t.isJSXIdentifier(parentNode.openingElement.name)
-                    ? parentNode.openingElement.name.name
-                    : null;
+            const parentTag = parentNode && t.isJSXElement(parentNode) && t.isJSXIdentifier(parentNode.openingElement.name)
+                ? parentNode.openingElement.name.name
+                : null;
+            const reportSkip = (candidateClass) => {
                 if (parentTag && /^[A-Z]/.test(parentTag)) {
                     skips.push({
                         file: filePath,
                         line,
-                        reason: `${textClass} — background may be set inside <${parentTag}>, which this tool doesn't inspect across component boundaries`,
+                        reason: `${candidateClass} — background may be set inside <${parentTag}>, which this tool doesn't inspect across component boundaries`,
                     });
                     return;
                 }
-            }
-            skips.push({
-                file: filePath,
-                line,
-                reason: `${textClass} — no background utility found on this element or its immediate parent`,
-            });
+                skips.push({
+                    file: filePath,
+                    line,
+                    reason: `${candidateClass} — no background utility found on this element or its immediate parent`,
+                });
+            };
+            if (textClass)
+                reportSkip(textClass);
+            if (placeholderClass)
+                reportSkip(placeholderClass);
         },
     });
     return skips;

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);
 }
@@ -33,7 +60,7 @@ 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
@@ -51,7 +78,7 @@ export function extractReducedMotionChecks(code, filePath) {
             // 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));
+                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, OR an

package/dist/rules/checkContrast.js

@@ -3,8 +3,14 @@ import { defaultPalette, semanticColors } from "../theme/defaultPalette.js";
 export function resolveColorValue(utilityClass, palette = defaultPalette) {
     // outline/ring are here for checkFocusIndicator.ts's non-text-contrast
     // check (WCAG 1.4.11/2.4.13) -- same palette/arbitrary-hex/semantic-color
-    // resolution as text/bg, just a different utility prefix.
-    const match = /^(?:text|bg|outline|ring)-(.+)$/.exec(utilityClass);
+    // resolution as text/bg, just a different utility prefix. The optional
+    // leading "placeholder:" tolerates extractClasses.ts's
+    // lastPlaceholderColorToken, which deliberately keeps that prefix on the
+    // class string it returns -- harmless to accept on all four prefixes
+    // here since extraction only ever produces "placeholder:text-*", never
+    // "placeholder:bg-*"/etc., and checkFocusIndicator.ts's own call sites
+    // can never pass a placeholder:-prefixed string into this function.
+    const match = /^(?:placeholder:)?(?:text|bg|outline|ring)-(.+)$/.exec(utilityClass);
     if (!match)
         return null;
     const token = match[1];
@@ -86,7 +92,10 @@ export function checkContrast(checks, palette = defaultPalette) {
     }
     return violations;
 }
-const TEXT_SCALE_SHADE_RE = /^text-([a-z]+)-(\d+)$/;
+// Optional leading "placeholder:" tolerated for the same reason as
+// resolveColorValue's regex above -- suggestContrastFix re-prepends it to
+// the suggested class below so the suggestion stays copy-pasteable.
+const TEXT_SCALE_SHADE_RE = /^(?:placeholder:)?text-([a-z]+)-(\d+)$/;
 // Only the text shade moves — bg and any opacity modifier on the text class
 // stay fixed, since text color is the more commonly adjustable side in
 // practice. Candidates come from the palette's actual keys (not an assumed
@@ -104,6 +113,7 @@ export function suggestContrastFix(textClass, bgClass, required, palette = defau
     if (!match)
         return null; // text-white, text-[#eee] — no suggestion
     const [, scale, shade] = match;
+    const isPlaceholder = base.startsWith("placeholder:");
     const shades = palette[scale];
     if (!shades?.[shade])
         return null; // custom scale, or a decoy like text-opacity-50
@@ -125,7 +135,8 @@ export function suggestContrastFix(textClass, bgClass, required, palette = defau
         const effectiveRgb = alpha < 1 ? applyAlpha(rgb, alpha, bgRgb) : rgb;
         const ratio = contrastRatio(effectiveRgb, bgRgb);
         if (ratio >= required) {
-            const suggestedClass = alpha < 1 ? `text-${scale}-${candidate}/${Math.round(alpha * 100)}` : `text-${scale}-${candidate}`;
+            const suggestedBase = alpha < 1 ? `text-${scale}-${candidate}/${Math.round(alpha * 100)}` : `text-${scale}-${candidate}`;
+            const suggestedClass = isPlaceholder ? `placeholder:${suggestedBase}` : suggestedBase;
             return { textClass: suggestedClass, ratio };
         }
     }

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);
 }
@@ -99,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;
@@ -138,7 +156,7 @@ export function checkReducedMotion(checks, strict = false) {
             // 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)))
+            if (!segments.some(isInteractionVariant))
                 return false;
             return ANIMATE_MOTION_BASES.has(baseUtility(raw));
         });
@@ -171,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));
         });

package/package.json

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