tailwind-a11y 0.9.0 → 0.10.0

package/README.md

@@ -25,7 +25,7 @@ npm install --save-dev tailwind-a11y
 npx tailwind-a11y                              # scans **/*.{jsx,tsx}
 npx tailwind-a11y "src/**/*.tsx"               # custom glob
 npx tailwind-a11y --verbose                    # also reports what couldn't be checked, and why
-npx tailwind-a11y --strict                     # touch targets must meet WCAG 2.5.5 (AAA, 44x44px), not just 2.5.8 (AA, 24x24px)
+npx tailwind-a11y --strict                     # touch targets: WCAG 2.5.5 (AAA, 44x44px); focus indicators: also WCAG 2.4.13 (AAA, min thickness)
 npx tailwind-a11y --config ./tw.config.cjs     # use a specific config instead of auto-detecting
 npx tailwind-a11y --version                    # print the installed version
 npx tailwind-a11y --help                       # usage and all options
@@ -56,6 +56,7 @@ Exits `1` on violations — safe to use as a CI gate.
 | 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 |
 | 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) |
 
 ## Scope
 

package/dist/cli.js

@@ -8,7 +8,7 @@ import { checkContrast, checkContrastValueSkips } from "./rules/checkContrast.js
 import { extractTouchTargetChecks, extractTouchTargetSkips } from "./parser/extractTouchTargets.js";
 import { checkTouchTargets } from "./rules/checkTouchTarget.js";
 import { extractFocusIndicatorChecks } from "./parser/extractFocusIndicators.js";
-import { checkFocusIndicators } from "./rules/checkFocusIndicator.js";
+import { checkFocusContrast, checkFocusIndicators, } from "./rules/checkFocusIndicator.js";
 import { parseArgs, getHelpText } from "./cliArgs.js";
 import { resolveTheme } from "./theme/loadCustomTheme.js";
 // ../package.json resolves correctly from both src/ (dev) and dist/ (published).
@@ -26,6 +26,13 @@ function formatViolation(v) {
         }
         case "focus-indicator":
             return `${v.line}: <${v.tagName}> removes the focus outline (${v.removalClass}) with no visible replacement (focus:ring-*/border-*/shadow-*/bg-*/outline-*)`;
+        case "focus-contrast": {
+            const sc = v.level === "AAA" ? "2.4.13" : "1.4.11";
+            const base = `${v.line}: <${v.tagName}> focus indicator ${v.indicatorClass} on ${v.bgClass} — ratio ${v.ratio.toFixed(2)}, needs ${v.required} (WCAG ${sc})`;
+            return v.thicknessPx !== undefined
+                ? `${base}; also only ${v.thicknessPx}px thick, needs >= ${v.requiredThicknessPx}px`
+                : base;
+        }
     }
 }
 function groupByFile(items) {
@@ -79,7 +86,8 @@ async function main() {
         try {
             const code = readFileSync(absPath, "utf8");
             const contrastChecks = extractChecks(code, file);
-            violations.push(...checkContrast(contrastChecks, palette), ...checkTouchTargets(extractTouchTargetChecks(code, file, spacing), strict), ...checkFocusIndicators(extractFocusIndicatorChecks(code, file)));
+            const focusChecks = extractFocusIndicatorChecks(code, file);
+            violations.push(...checkContrast(contrastChecks, palette), ...checkTouchTargets(extractTouchTargetChecks(code, file, spacing), strict), ...checkFocusIndicators(focusChecks), ...checkFocusContrast(focusChecks, strict, palette));
             if (verbose) {
                 skips.push(...extractContrastSkips(code, file), ...checkContrastValueSkips(contrastChecks, palette), ...extractTouchTargetSkips(code, file, spacing));
             }

package/dist/cliArgs.js

@@ -3,14 +3,16 @@
 const HELP_TEXT = `Usage: tailwind-a11y [options] [<glob>...]
 
 Static analysis for Tailwind CSS accessibility violations -- color contrast,
-touch target size, and focus indicator removal.
+touch target size, and focus indicator removal/contrast.
 
 Options:
   -v, --verbose      Also report what couldn't be checked, and why
   -V, --version      Print the version number
   -h, --help         Print this help message
       --strict       Touch targets must meet WCAG 2.5.5 (AAA, 44x44px)
-                      instead of the default 2.5.8 (AA, 24x24px)
+                      instead of the default 2.5.8 (AA, 24x24px); focus
+                      indicators are also held to 2.4.13 (AAA, minimum
+                      thickness) alongside the default 1.4.11 (AA, contrast)
       --config <path>  Path to a tailwind.config.js/.cjs (v3) or a CSS
                         @theme file like app/globals.css (v4) to read
                         custom theme colors/spacing from (default:

package/dist/index.d.ts

@@ -3,7 +3,7 @@ export { checkContrast, checkContrastValueSkips, suggestContrastFix, type Contra
 export { extractTouchTargetChecks, extractTouchTargetSkips, type TouchTargetCheck, type TouchTargetSkip } from "./parser/extractTouchTargets.js";
 export { checkTouchTargets, type TouchTargetViolation } from "./rules/checkTouchTarget.js";
 export { extractFocusIndicatorChecks, type FocusIndicatorCheck } from "./parser/extractFocusIndicators.js";
-export { checkFocusIndicators, type FocusIndicatorViolation } from "./rules/checkFocusIndicator.js";
+export { checkFocusIndicators, checkFocusContrast, type FocusIndicatorViolation, type FocusContrastViolation, } from "./rules/checkFocusIndicator.js";
 export { hexToRgb, contrastRatio, meetsWCAG, requiredRatio, type RGB } from "./contrast/luminance.js";
 export { resolveTheme, findTailwindConfig, loadCustomTheme, findTailwindThemeCss, loadThemeFromCssFile, mergePalette, mergeSpacing, type ResolvedTheme, type RawCustomTheme, } from "./theme/loadCustomTheme.js";
 export { parseThemeCss } from "./theme/parseThemeCss.js";

package/dist/index.js

@@ -3,7 +3,7 @@ export { checkContrast, checkContrastValueSkips, suggestContrastFix } from "./ru
 export { extractTouchTargetChecks, extractTouchTargetSkips } from "./parser/extractTouchTargets.js";
 export { checkTouchTargets } from "./rules/checkTouchTarget.js";
 export { extractFocusIndicatorChecks } from "./parser/extractFocusIndicators.js";
-export { checkFocusIndicators } from "./rules/checkFocusIndicator.js";
+export { checkFocusIndicators, checkFocusContrast, } from "./rules/checkFocusIndicator.js";
 export { hexToRgb, contrastRatio, meetsWCAG, requiredRatio } from "./contrast/luminance.js";
 export { resolveTheme, findTailwindConfig, loadCustomTheme, findTailwindThemeCss, loadThemeFromCssFile, mergePalette, mergeSpacing, } from "./theme/loadCustomTheme.js";
 export { parseThemeCss } from "./theme/parseThemeCss.js";

package/dist/parser/extractFocusIndicators.d.ts

@@ -3,5 +3,7 @@ export interface FocusIndicatorCheck {
     line: number;
     tagName: string;
     focusClasses: string[];
+    bgClass?: string | null;
+    bgSource?: "self" | "parent" | null;
 }
 export declare function extractFocusIndicatorChecks(code: string, filePath: string): FocusIndicatorCheck[];

package/dist/parser/extractFocusIndicators.js

@@ -1,6 +1,7 @@
 import * as t from "@babel/types";
 import { getStaticClassName, parseJSX, traverse } from "./babelInterop.js";
 import { isInteractiveElement } from "./isInteractiveElement.js";
+import { lastColorToken } from "./extractClasses.js";
 function focusScopedClasses(className) {
     return className
         .split(/\s+/)
@@ -27,11 +28,30 @@ export function extractFocusIndicatorChecks(code, filePath) {
             const focusClasses = focusScopedClasses(className);
             if (focusClasses.length === 0)
                 return; // nothing under focus:/focus-visible: — not a candidate
+            const ownBg = lastColorToken(className, "bg");
+            let bgClass = ownBg;
+            let bgSource = ownBg ? "self" : null;
+            if (!bgClass) {
+                // Only the immediate JSX parent, same limit as extractClasses.ts's
+                // own contrast resolution — no deeper ancestor walk, no
+                // cross-component resolution.
+                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) {
+                        bgClass = parentBg;
+                        bgSource = "parent";
+                    }
+                }
+            }
             checks.push({
                 file: filePath,
                 line: opening.loc?.start.line ?? 0,
                 tagName: t.isJSXIdentifier(opening.name) ? opening.name.name : "onClick-element",
                 focusClasses,
+                bgClass,
+                bgSource,
             });
         },
     });

package/dist/rules/checkContrast.js

@@ -1,7 +1,10 @@
 import { applyAlpha, contrastRatio, hexToRgb, meetsWCAG, requiredRatio } from "../contrast/luminance.js";
 import { defaultPalette, semanticColors } from "../theme/defaultPalette.js";
 export function resolveColorValue(utilityClass, palette = defaultPalette) {
-    const match = /^(?:text|bg)-(.+)$/.exec(utilityClass);
+    // 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);
     if (!match)
         return null;
     const token = match[1];

package/dist/rules/checkFocusIndicator.d.ts

@@ -1,4 +1,5 @@
 import type { FocusIndicatorCheck } from "../parser/extractFocusIndicators.js";
+import type { Palette } from "../theme/defaultPalette.js";
 export interface FocusIndicatorViolation {
     type: "focus-indicator";
     file: string;
@@ -7,3 +8,17 @@ export interface FocusIndicatorViolation {
     removalClass: string;
 }
 export declare function checkFocusIndicators(checks: FocusIndicatorCheck[]): FocusIndicatorViolation[];
+export interface FocusContrastViolation {
+    type: "focus-contrast";
+    file: string;
+    line: number;
+    tagName: string;
+    indicatorClass: string;
+    bgClass: string;
+    ratio: number;
+    required: number;
+    level: "AA" | "AAA";
+    thicknessPx?: number;
+    requiredThicknessPx?: number;
+}
+export declare function checkFocusContrast(checks: FocusIndicatorCheck[], strict?: boolean, palette?: Palette): FocusContrastViolation[];

package/dist/rules/checkFocusIndicator.js

@@ -1,4 +1,7 @@
 import { COLOR_TOKEN } from "../parser/extractClasses.js";
+import { resolveColorValue } from "./checkContrast.js";
+import { contrastRatio, hexToRgb } from "../contrast/luminance.js";
+import { defaultPalette } from "../theme/defaultPalette.js";
 const REMOVAL_BASE = "outline-none";
 // Utilities that match the "replacement" shape but are semantically no-ops —
 // the same failure mode as bg-opacity-50 masking a real color match: a
@@ -97,3 +100,109 @@ export function checkFocusIndicators(checks) {
     }
     return violations;
 }
+// Flat non-text threshold -- not luminance.ts's requiredRatio()/meetsWCAG(),
+// which model the text-specific large-text/small-text AA/AAA table that
+// doesn't apply to UI-component contrast.
+const NON_TEXT_MIN_RATIO = 3;
+// WCAG 2.4.13's "2 CSS pixel thick perimeter" -- verified against a real
+// tailwindcss@4.3.3 compile (see CLAUDE.md) rather than assumed.
+const FOCUS_INDICATOR_MIN_THICKNESS_PX = 2;
+// outline-{0,1,2,4,8} / ring-{0,1,2,4,8} -- Tailwind's fixed width scale for
+// both utilities, verified against a real build. Bare `ring`/`outline` (no
+// digit) is deliberately NOT in this map: verified via that same build that
+// it resolves to 1px in Tailwind v4, but v3's bare `ring` default is
+// documented elsewhere as 3px -- a real cross-version difference this tool
+// 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) {
+    let found = null;
+    for (const raw of focusClasses) {
+        const base = raw.slice(raw.lastIndexOf(":") + 1);
+        const match = /^(?:outline|ring)-(.+)$/.exec(base);
+        if (!match)
+            continue;
+        const rest = match[1];
+        if (!COLOR_TOKEN.test(rest))
+            continue;
+        const scaleName = /^([a-z]+)-\d/.exec(rest)?.[1];
+        if (scaleName === "opacity")
+            continue;
+        found = base;
+    }
+    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) {
+    let found = null;
+    for (const raw of focusClasses) {
+        const base = raw.slice(raw.lastIndexOf(":") + 1);
+        const match = /^(?:outline|ring)-(.+)$/.exec(base);
+        if (!match)
+            continue;
+        const token = match[1];
+        if (token in WIDTH_SCALE) {
+            found = WIDTH_SCALE[token];
+            continue;
+        }
+        const arbitrary = /^\[(\d+(?:\.\d+)?)px\]$/.exec(token);
+        if (arbitrary)
+            found = Number(arbitrary[1]);
+    }
+    return found;
+}
+export function checkFocusContrast(checks, strict = false, palette = defaultPalette) {
+    const violations = [];
+    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)
+            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)
+            continue;
+        const rawIndicatorClass = check.focusClasses.find((raw) => raw.slice(raw.lastIndexOf(":") + 1) === indicatorBase);
+        violations.push({
+            type: "focus-contrast",
+            file: check.file,
+            line: check.line,
+            tagName: check.tagName,
+            indicatorClass: rawIndicatorClass,
+            bgClass: check.bgClass,
+            ratio,
+            required: NON_TEXT_MIN_RATIO,
+            level: thicknessFails ? "AAA" : "AA",
+            ...(thicknessFails && thicknessPx !== null
+                ? { thicknessPx, requiredThicknessPx: FOCUS_INDICATOR_MIN_THICKNESS_PX }
+                : {}),
+        });
+    }
+    return violations;
+}

package/package.json

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