tailwind-a11y 0.14.1 → 0.15.0

package/README.md

@@ -53,7 +53,7 @@ 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) |

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/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/package.json

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