tailwind-a11y 0.7.0 → 0.9.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 must meet WCAG 2.5.5 (AAA, 44x44px), not just 2.5.8 (AA, 24x24px)
 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,7 +54,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 |
-| 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 |
 
 ## Scope
@@ -78,6 +79,7 @@ When a case can't be resolved with confidence, it's skipped rather than guessed:
 
 - [`eslint-plugin-tailwind-a11y`](https://github.com/chamroro/tailwind-a11y/tree/main/packages/eslint-plugin-tailwind-a11y) — same checks as ESLint rules
 - [`vscode-tailwind-a11y`](https://github.com/chamroro/tailwind-a11y/tree/main/packages/vscode-tailwind-a11y) — same checks as live editor diagnostics
+- [`github-action-tailwind-a11y`](https://github.com/chamroro/tailwind-a11y/tree/main/packages/github-action-tailwind-a11y) — same checks as inline PR annotations
 
 ## License
 

package/dist/cli.js

@@ -20,8 +20,10 @@ 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-*)`;
     }
@@ -40,7 +42,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 +79,7 @@ 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)));
+            violations.push(...checkContrast(contrastChecks, palette), ...checkTouchTargets(extractTouchTargetChecks(code, file, spacing), strict), ...checkFocusIndicators(extractFocusIndicatorChecks(code, file)));
             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

@@ -9,6 +9,8 @@ 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)
       --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 +20,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 +28,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 +56,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/parser/extractClasses.d.ts

@@ -5,6 +5,7 @@ export interface ContrastCheck {
     bgColorClass: string;
     bgSource: "self" | "parent";
 }
+export declare const COLOR_TOKEN: RegExp;
 export declare function lastColorToken(className: string, prefix: "text" | "bg"): string | null;
 export declare function extractChecks(code: string, filePath: string): ContrastCheck[];
 export interface ContrastSkip {

package/dist/parser/extractClasses.js

@@ -9,7 +9,11 @@ import { getStaticClassName, parseJSX, traverse } from "./babelInterop.js";
 // an extremely common real idiom, more so than the named-scale case, and
 // dropping it here would make the contrast checker's opacity support (see
 // rules/checkContrast.ts) silently inapplicable to the most common case.
-const COLOR_TOKEN = /^\[(#[0-9a-fA-F]{3,8})\](\/\d{1,3})?$|^[a-z]+-\d{2,3}(\/\d{1,3})?$|^(white|black|transparent|current|inherit)(\/\d{1,3})?$/;
+// Exported for reuse in checkFocusIndicator.ts, which needs the exact same
+// "does this suffix look like a color value" test to detect shadow-{color}/
+// ring-{color} decoys (see that file for why) -- one definition, not a
+// second copy that could silently drift out of sync.
+export const COLOR_TOKEN = /^\[(#[0-9a-fA-F]{3,8})\](\/\d{1,3})?$|^[a-z]+-\d{2,3}(\/\d{1,3})?$|^(white|black|transparent|current|inherit)(\/\d{1,3})?$/;
 // opacity-{N} (e.g. bg-opacity-50, text-opacity-50) matches the same
 // "word-number" shape as a color token but isn't one — without this
 // exclusion it can silently overwrite a real color match via the

package/dist/rules/checkFocusIndicator.js

@@ -1,9 +1,17 @@
+import { COLOR_TOKEN } from "../parser/extractClasses.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
 // same-prefix decoy that would silently hide a real violation if we only
-// checked the prefix.
-const DEGENERATE_BASES = new Set(["outline-none", "ring-0", "border-0", "shadow-none", "bg-transparent"]);
+// checked the prefix. border-none/border-hidden only set border-style, not
+// border-width -- verified against a real Tailwind v4 build that preflight
+// 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.
+const DEGENERATE_BASES = new Set([
+    "outline-none", "ring-0", "border-0", "shadow-none", "bg-transparent",
+    "border-none", "border-hidden",
+]);
 // 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
 // with no ring-* width, renders nothing visible by itself. Same failure
@@ -31,8 +39,32 @@ const NON_VISUAL_BASES = new Set([
 ]);
 // bg-blend-{mode} (e.g. bg-blend-multiply) sets a blend mode, not a color --
 // suffix-varying like MODIFIER_ONLY above, so pattern-matched instead of
-// enumerated.
-const NON_VISUAL_PATTERN = /^bg-blend-/;
+// enumerated. border-spacing-*/-x-*/-y-* sets the CSS border-spacing
+// property, which only affects the gap between <table> cells -- verified
+// against a real Tailwind v4 build that it has zero visual effect on any
+// non-table element (the only elements this check ever fires on), even
+// with a real numeric value applied.
+const NON_VISUAL_PATTERN = /^bg-blend-|^border-spacing(-[xy])?-/;
+// shadow-{color}/ring-{color} alone (e.g. shadow-red-500, ring-blue-400/50,
+// an arbitrary hex) only sets the --tw-shadow-color/--tw-ring-color CSS
+// variable -- the actual box-shadow property is set by a separate *size*
+// utility (shadow-lg, ring-2, etc.) that references that variable. Verified
+// against a real Tailwind v4 build: shadow-red-500 alone computes to
+// `box-shadow: none`; shadow-lg shadow-red-500 together produce a real,
+// colored shadow. Same underlying mechanism as MODIFIER_ONLY's opacity/
+// 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.
+function isColorOnlyShadowOrRing(base) {
+    const shadowMatch = /^shadow-(.+)$/.exec(base);
+    if (shadowMatch && COLOR_TOKEN.test(shadowMatch[1]))
+        return true;
+    const ringMatch = /^ring-(.+)$/.exec(base);
+    if (ringMatch && COLOR_TOKEN.test(ringMatch[1]))
+        return true;
+    return false;
+}
 function baseUtility(raw) {
     return raw.slice(raw.lastIndexOf(":") + 1);
 }
@@ -42,6 +74,8 @@ function isReplacement(raw) {
         return false;
     if (NON_VISUAL_BASES.has(base) || NON_VISUAL_PATTERN.test(base))
         return false;
+    if (isColorOnlyShadowOrRing(base))
+        return false;
     return /^(ring|border|shadow|bg|outline)(-|$)/.test(base);
 }
 export function checkFocusIndicators(checks) {

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.7.0",
+  "version": "0.9.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": {