tailwind-a11y 0.1.1 → 0.3.0

package/README.md

@@ -1,54 +1,18 @@
 # tailwind-a11y
 
-A static analysis engine that resolves Tailwind CSS utility classes back into their real
-computed values (colors, sizes, focus behavior) via AST parsing — so accessibility bugs
-can be caught **before rendering**, in CI, instead of at a Lighthouse audit or QA pass
-after the fact. Three [WCAG](https://www.w3.org/WAI/WCAG21/quickref/) checks ship on top
-of that engine today: color contrast, touch target size, and focus indicator removal.
+CLI that catches WCAG accessibility violations in Tailwind CSS class combinations
+before they ship.
 
-> Renamed from `tailwind-contrast-guard` once these three checks landed. This package now
-> lives in the [`tailwind-a11y` monorepo](https://github.com/chamroro/tailwind-a11y)
-> alongside its [ESLint plugin](https://github.com/chamroro/tailwind-a11y/tree/main/packages/eslint-plugin-tailwind-a11y).
-
-## The actual problem this solves
-
-The pain isn't "checking contrast" — plenty of tools do that. The pain is finding out
-about an accessibility bug **late**: at a design review, an axe/Lighthouse audit, or a
-QA pass, days or weeks after the code that caused it was written and merged. By the time
-that class combination surfaces as one of forty findings on a spreadsheet, nobody
-remembers why `text-gray-400` ended up on that element.
-
-`tailwind-a11y` moves that feedback to write-time by actually understanding what a
-Tailwind class *renders as* — not just matching class names, but resolving `text-gray-400`
-to `#9ca3af`, `w-4` to `16px`, and evaluating those against the real WCAG formulas. That's
-what makes it different from a linter that only knows class *names* exist:
+Resolves Tailwind utility classes into their real computed values via AST analysis,
+rather than matching class names. This catches a pattern most contrast checkers miss —
+background color on a parent element, text color on a child:
 
 ```jsx
 <div className="bg-white">
-  <p className="text-gray-400">the background is on the parent, not this element</p>
+  <p className="text-gray-400">not caught by most tools — but fails WCAG AA</p>
 </div>
 ```
 
-Most existing Tailwind contrast checkers only catch `text-*`/`bg-*` on the **same**
-element and miss this — extremely common — direct-parent pattern entirely, because they
-never resolve the parent's class at all.
-
-## What's built on the engine today
-
-```jsx
-<button className="w-4 h-4" onClick={...}>×</button>          {/* 16×16px, fails WCAG 2.5.8 */}
-<button className="focus:outline-none">Save</button>          {/* no visible focus indicator */}
-```
-
-- **Contrast** (WCAG 1.4.3) — same-element and direct-parent `text-*`/`bg-*` combinations
-- **Touch target size** (WCAG 2.5.8) — interactive elements under 24×24px
-- **Focus indicator removal** (WCAG 2.4.7) — `focus:outline-none` with no visible replacement
-
-These three exist because they're the checks a Tailwind-aware engine can answer with high
-confidence today. The engine itself — turning a utility class into a real value — isn't
-specific to accessibility; it's the reusable part, and more checks can sit on top of it
-without becoming a different tool.
-
 ## Install
 
 ```bash
@@ -58,81 +22,49 @@ npm install --save-dev tailwind-a11y
 ## Usage
 
 ```bash
-npx tailwind-a11y                    # scans **/*.{jsx,tsx} from the current directory
-npx tailwind-a11y "src/**/*.tsx"     # or pass your own glob pattern(s)
+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 --version          # print the installed version
+npx tailwind-a11y --help             # usage and all options
 ```
 
-`--verbose` surfaces the coverage gap explicitly instead of leaving it invisible — e.g. a
-custom theme color that can't be resolved, or a background set inside a wrapping
-component this tool can't see into. A skip is not a pass; it means "not checked."
-
-Example output:
-
 ```
 src/components/Card.tsx
-  3: text-gray-400 on bg-white — ratio 2.54, needs 4.5 (AA)
+  3: text-gray-400 on bg-white — ratio 2.54, needs 4.5 (AA); try text-gray-500 (4.83)
 src/components/IconButton.tsx
   5: <button> is 16×16px (w-4 h-4) — WCAG 2.5.8 requires >= 24×24px
-  12: <button> removes the focus outline (focus:outline-none) with no visible replacement
 
-3 issue(s) in 2 file(s)
+2 issue(s) in 2 file(s)
 ```
 
-Exits with code `1` when issues are found, `0` otherwise — drop it into CI:
+Exits `1` on violations — safe to use as a CI gate.
 
-```yaml
-# .github/workflows/a11y.yml
-- run: npx tailwind-a11y
-```
+## Checks
 
-## What it catches
-
-- **Contrast** (WCAG 1.4.3): `text-*`/`bg-*` on the **same element**, or `text-*` on a
-  child with `bg-*` on its **immediate JSX parent** (one level up, exactly). Tailwind's
-  default color palette, plus arbitrary hex values (`text-[#123456]`).
-- **Touch target size** (WCAG 2.5.8): interactive elements (`button`, `a`, `input`,
-  `select`, `textarea`, or any element with an `onClick` handler) sized below 24×24px via
-  explicit `w-*`/`h-*` utilities.
-- **Focus indicator removal** (WCAG 2.4.7): `focus:outline-none`/`focus-visible:outline-none`
-  with no other `focus:`/`focus-visible:` utility (`ring-*`, `border-*`, `shadow-*`, `bg-*`,
-  non-`none` `outline-*`) providing a visible replacement.
-- All checks: static `className="..."` string literals only.
-
-## What it deliberately doesn't catch (v1 scope)
-
-These are intentional limitations, not bugs — each would require a fundamentally heavier
-tool (whole-program or runtime analysis) for a comparatively rare payoff. When a check can't
-be resolved with confidence, it is **skipped, not guessed** — a wrong "pass" is worse than
-no answer:
-
-- **Ancestors beyond the immediate parent**, or backgrounds set inside a separately-defined
-  wrapping component (e.g. `<Card><Text/></Card>` where `Card` sets `bg-white` internally).
-  This is the most common source of missed violations in real component-library-heavy
-  codebases (MUI, Chakra, shadcn/ui, Radix) — resolving it would require whole-program,
-  type-aware analysis across file boundaries, a different tool than this.
-- **Dynamic or computed `className`** — ternaries, template literals, `clsx()`/`cva()`
-  composition. These are silently skipped, never guessed at.
-- **Custom theme colors/spacing** not in Tailwind's default scales (e.g. `text-brand-500`)
-- **Color + opacity shorthand** (`bg-white/50`) — skipped rather than alpha-composited,
-  since a wrong guess is worse than no answer
-- **Large-text contrast thresholds** (3.0:1 instead of 4.5:1) — every check currently uses
-  the normal-text AA threshold
-- **`min-w-*`/`min-h-*` sizing**, and WCAG 2.5.8's inline-text-link exception — touch target
-  checks require explicit `w-*`+`h-*`, no fallback/exception heuristics in v1
-- Frameworks other than React/JSX (Vue, Svelte, Blade, …)
-- Editor/LSP integration — this is a CLI/CI tool, not a VS Code extension (yet)
-
-See [CLAUDE.md](./CLAUDE.md) for the full rationale behind these boundaries.
-
-## Development
+| Check | WCAG | Detects |
+|---|---|---|
+| Contrast | 1.4.3 (AA) | `text-*`/`bg-*` pairs below 4.5:1, same-element or direct-parent; suggests the nearest passing shade |
+| Touch target | 2.5.8 (AA) | Interactive elements under 24×24px |
+| Focus indicator | 2.4.7 (AA) | `focus:outline-none` with no visible replacement |
 
-```bash
-npm install
-npm run dev -- "src/**/*.tsx"   # run the CLI against a project without building
-npm test                        # vitest
-npm run build                   # tsc -> dist/
-```
+## Scope
+
+When a case can't be resolved with confidence, it's skipped rather than guessed:
+
+- Ancestors beyond the immediate parent, or backgrounds set inside a separate component
+- Dynamic or computed `className` (ternaries, `clsx()`, template literals)
+- Custom theme colors/spacing not in Tailwind's default scales
+- Color + opacity shorthand (`bg-white/50`)
+- Frameworks other than React/JSX
+
+`--verbose` reports what was skipped and why — a skip is not a pass. Full rationale in
+[CLAUDE.md](./CLAUDE.md).
+
+## Related
+
+- [`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
 
 ## License
 

package/dist/cli.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { readFileSync } from "node:fs";
 import { relative, sep } from "node:path";
+import { createRequire } from "node:module";
 import fg from "fast-glob";
 import { extractChecks, extractContrastSkips } from "./parser/extractClasses.js";
 import { checkContrast, checkContrastValueSkips } from "./rules/checkContrast.js";
@@ -8,10 +9,16 @@ import { extractTouchTargetChecks, extractTouchTargetSkips } from "./parser/extr
 import { checkTouchTargets } from "./rules/checkTouchTarget.js";
 import { extractFocusIndicatorChecks } from "./parser/extractFocusIndicators.js";
 import { checkFocusIndicators } from "./rules/checkFocusIndicator.js";
+import { parseArgs, getHelpText } from "./cliArgs.js";
+// ../package.json resolves correctly from both src/ (dev) and dist/ (published).
+const require = createRequire(import.meta.url);
+const { version: packageVersion } = require("../package.json");
 function formatViolation(v) {
     switch (v.type) {
-        case "contrast":
-            return `${v.line}: ${v.textClass} on ${v.bgClass} — ratio ${v.ratio.toFixed(2)}, needs ${v.required} (${v.level})`;
+        case "contrast": {
+            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 "focus-indicator":
@@ -32,9 +39,15 @@ function groupByFile(items) {
     return byFile;
 }
 async function main() {
-    const args = process.argv.slice(2);
-    const verbose = args.includes("--verbose") || args.includes("-v");
-    const patterns = args.filter((a) => a !== "--verbose" && a !== "-v");
+    const { help, version, verbose, patterns } = parseArgs(process.argv.slice(2));
+    if (help) {
+        console.log(getHelpText());
+        return;
+    }
+    if (version) {
+        console.log(packageVersion);
+        return;
+    }
     const globPatterns = patterns.length > 0 ? patterns : ["**/*.{jsx,tsx}"];
     const files = await fg(globPatterns, {
         cwd: process.cwd(),

package/dist/cliArgs.d.ts

@@ -0,0 +1,8 @@
+export interface ParsedArgs {
+    help: boolean;
+    version: boolean;
+    verbose: boolean;
+    patterns: string[];
+}
+export declare function getHelpText(): string;
+export declare function parseArgs(argv: string[]): ParsedArgs;

package/dist/cliArgs.js

@@ -0,0 +1,31 @@
+// Split out from cli.ts so it's importable in tests without triggering
+// cli.ts's top-level main() call (which does real file I/O on import).
+const HELP_TEXT = `Usage: tailwind-a11y [options] [<glob>...]
+
+Static analysis for Tailwind CSS accessibility violations -- color contrast,
+touch target size, and focus indicator removal.
+
+Options:
+  -v, --verbose   Also report what couldn't be checked, and why
+  -V, --version   Print the version number
+  -h, --help      Print this help message
+
+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
+`;
+export function getHelpText() {
+    return HELP_TEXT;
+}
+// -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"]);
+export function parseArgs(argv) {
+    return {
+        help: argv.includes("--help") || argv.includes("-h"),
+        version: argv.includes("--version") || argv.includes("-V"),
+        verbose: argv.includes("--verbose") || argv.includes("-v"),
+        patterns: argv.filter((a) => !FLAGS.has(a)),
+    };
+}

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { extractChecks, extractContrastSkips, type ContrastCheck, type ContrastSkip } from "./parser/extractClasses.js";
-export { checkContrast, checkContrastValueSkips, type ContrastViolation, type ContrastValueSkip } from "./rules/checkContrast.js";
+export { checkContrast, checkContrastValueSkips, suggestContrastFix, type ContrastViolation, type ContrastValueSkip, type ContrastFix } from "./rules/checkContrast.js";
 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";

package/dist/index.js

@@ -1,5 +1,5 @@
 export { extractChecks, extractContrastSkips } from "./parser/extractClasses.js";
-export { checkContrast, checkContrastValueSkips } from "./rules/checkContrast.js";
+export { checkContrast, checkContrastValueSkips, suggestContrastFix } from "./rules/checkContrast.js";
 export { extractTouchTargetChecks, extractTouchTargetSkips } from "./parser/extractTouchTargets.js";
 export { checkTouchTargets } from "./rules/checkTouchTarget.js";
 export { extractFocusIndicatorChecks } from "./parser/extractFocusIndicators.js";

package/dist/rules/checkContrast.d.ts

@@ -8,9 +8,16 @@ export interface ContrastViolation {
     ratio: number;
     required: number;
     level: "AA";
+    suggestion?: string;
+    suggestedRatio?: number;
 }
 export declare function resolveColorValue(utilityClass: string): string | null;
 export declare function checkContrast(checks: ContrastCheck[]): ContrastViolation[];
+export interface ContrastFix {
+    textClass: string;
+    ratio: number;
+}
+export declare function suggestContrastFix(textClass: string, bgClass: string, required: number): ContrastFix | null;
 export interface ContrastValueSkip {
     file: string;
     line: number;

package/dist/rules/checkContrast.js

@@ -33,6 +33,7 @@ export function checkContrast(checks) {
         const ratio = contrastRatio(textRgb, bgRgb);
         const required = requiredRatio("AA", false); // v1: large-text detection deferred
         if (!meetsWCAG(ratio, "AA", false)) {
+            const fix = suggestContrastFix(check.textColorClass, check.bgColorClass, required);
             violations.push({
                 type: "contrast",
                 file: check.file,
@@ -42,11 +43,48 @@ export function checkContrast(checks) {
                 ratio,
                 required,
                 level: "AA",
+                ...(fix && { suggestion: fix.textClass, suggestedRatio: fix.ratio }),
             });
         }
     }
     return violations;
 }
+const TEXT_SCALE_SHADE_RE = /^text-([a-z]+)-(\d+)$/;
+// Only the text shade moves — bg stays fixed, since text color is the more
+// commonly adjustable side in practice. Candidates come from the palette's
+// actual keys (not an assumed 50..950 enumeration), sorted nearest-first by
+// numeric distance from the original shade; ties favor the higher/darker
+// shade, since real failures here are overwhelmingly light-on-light and
+// darker is the fix a human reaches for. The original shade can never win:
+// it's in this same candidate list at distance 0, and this recomputes the
+// identical unrounded ratio comparison that just failed.
+export function suggestContrastFix(textClass, bgClass, required) {
+    const match = TEXT_SCALE_SHADE_RE.exec(textClass);
+    if (!match)
+        return null; // text-white, text-[#eee], text-gray-400/50 — no suggestion
+    const [, scale, shade] = match;
+    const shades = defaultPalette[scale];
+    if (!shades?.[shade])
+        return null; // custom scale, or a decoy like text-opacity-50
+    const bgHex = resolveColorValue(bgClass);
+    const bgRgb = bgHex ? hexToRgb(bgHex) : null;
+    if (!bgRgb)
+        return null;
+    const original = Number(shade);
+    const candidates = Object.keys(shades)
+        .filter((s) => /^\d+$/.test(s))
+        .map(Number)
+        .sort((a, b) => Math.abs(a - original) - Math.abs(b - original) || b - a);
+    for (const candidate of candidates) {
+        const rgb = hexToRgb(shades[String(candidate)]);
+        if (!rgb)
+            continue;
+        const ratio = contrastRatio(rgb, bgRgb);
+        if (ratio >= required)
+            return { textClass: `text-${scale}-${candidate}`, ratio };
+    }
+    return null;
+}
 // A candidate that extractChecks *did* find a background for, but whose
 // text or bg utility didn't resolve to a known value (custom theme color,
 // non-hex arbitrary value, opacity shorthand) — surfaced separately from

package/package.json

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