tailwind-a11y 0.8.0 → 0.10.0

package/README.md

@@ -25,6 +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: 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
@@ -53,8 +54,9 @@ 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 |
-| Touch target | 2.5.8 (AA) | Interactive elements under 24×24px |
+| 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).
@@ -20,10 +20,19 @@ function formatViolation(v) {
             const base = `${v.line}: ${v.textClass} on ${v.bgClass} — ratio ${v.ratio.toFixed(2)}, needs ${v.required} (${v.level})`;
             return v.suggestion ? `${base}; try ${v.suggestion} (${v.suggestedRatio.toFixed(2)})` : base;
         }
-        case "touch-target":
-            return `${v.line}: <${v.tagName}> is ${v.widthPx}×${v.heightPx}px (${v.widthClass} ${v.heightClass}) — WCAG 2.5.8 requires >= 24×24px`;
+        case "touch-target": {
+            const sc = v.level === "AAA" ? "2.5.5" : "2.5.8";
+            return `${v.line}: <${v.tagName}> is ${v.widthPx}×${v.heightPx}px (${v.widthClass} ${v.heightClass}) — WCAG ${sc} requires >= ${v.required}×${v.required}px`;
+        }
         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) {
@@ -40,7 +49,7 @@ function groupByFile(items) {
     return byFile;
 }
 async function main() {
-    const { help, version, verbose, config, configError: usageError, patterns } = parseArgs(process.argv.slice(2));
+    const { help, version, verbose, strict, config, configError: usageError, patterns } = parseArgs(process.argv.slice(2));
     if (help) {
         console.log(getHelpText());
         return;
@@ -77,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)), ...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.d.ts

@@ -2,6 +2,7 @@ export interface ParsedArgs {
     help: boolean;
     version: boolean;
     verbose: boolean;
+    strict: boolean;
     config: string | null;
     configError: string | null;
     patterns: string[];

package/dist/cliArgs.js

@@ -3,12 +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); 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:
@@ -18,6 +22,7 @@ Examples:
   tailwind-a11y                    Scan **/*.{jsx,tsx} from the current directory
   tailwind-a11y "src/**/*.tsx"     Scan a custom glob pattern
   tailwind-a11y --verbose          Also report skipped/unresolvable cases
+  tailwind-a11y --strict           Enforce the stricter 44x44px touch target minimum
   tailwind-a11y --config ./tailwind.config.cjs
 `;
 export function getHelpText() {
@@ -25,7 +30,7 @@ export function getHelpText() {
 }
 // -v/--verbose already existed before --version was added; -V (uppercase)
 // avoids colliding with it, matching a common CLI convention.
-const FLAGS = new Set(["--verbose", "-v", "--version", "-V", "--help", "-h"]);
+const FLAGS = new Set(["--verbose", "-v", "--version", "-V", "--help", "-h", "--strict"]);
 export function parseArgs(argv) {
     let config = null;
     let configError = null;
@@ -53,6 +58,7 @@ export function parseArgs(argv) {
         help: argv.includes("--help") || argv.includes("-h"),
         version: argv.includes("--version") || argv.includes("-V"),
         verbose: argv.includes("--verbose") || argv.includes("-v"),
+        strict: argv.includes("--strict"),
         config,
         configError,
         patterns,

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/dist/rules/checkTouchTarget.d.ts

@@ -8,5 +8,7 @@ export interface TouchTargetViolation {
     heightClass: string;
     widthPx: number;
     heightPx: number;
+    required: number;
+    level: "AA" | "AAA";
 }
-export declare function checkTouchTargets(checks: TouchTargetCheck[]): TouchTargetViolation[];
+export declare function checkTouchTargets(checks: TouchTargetCheck[], strict?: boolean): TouchTargetViolation[];

package/dist/rules/checkTouchTarget.js

@@ -1,8 +1,17 @@
 // WCAG 2.5.8 Target Size (Minimum), Level AA: interactive targets must be
 // at least 24x24 CSS pixels. "Minimum" is inclusive, so exactly 24x24 passes.
 const MIN_TARGET_PX = 24;
-export function checkTouchTargets(checks) {
+// WCAG 2.5.5 Target Size (Enhanced), Level AAA: 44x44 CSS pixels -- opt-in
+// via `strict`, not the default. Same "target in a sentence/text block"
+// exemption as 2.5.8 (verified against the W3C Understanding doc), so
+// extractTouchTargets.ts's isInlineInText() exemption logic applies
+// unchanged to both thresholds -- this file only changes which number is
+// compared against, not how targets are found or exempted.
+const MIN_TARGET_PX_STRICT = 44;
+export function checkTouchTargets(checks, strict = false) {
+    const required = strict ? MIN_TARGET_PX_STRICT : MIN_TARGET_PX;
+    const level = strict ? "AAA" : "AA";
     return checks
-        .filter((c) => c.widthPx < MIN_TARGET_PX || c.heightPx < MIN_TARGET_PX)
-        .map((c) => ({ type: "touch-target", ...c }));
+        .filter((c) => c.widthPx < required || c.heightPx < required)
+        .map((c) => ({ type: "touch-target", ...c, required, level }));
 }

package/package.json

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