tailwind-a11y 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 chamroro
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,139 @@
+# 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.
+
+> 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:
+
+```jsx
+<div className="bg-white">
+  <p className="text-gray-400">the background is on the parent, not this element</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
+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 --verbose          # also reports what couldn't be checked, and why
+```
+
+`--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)
+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)
+```
+
+Exits with code `1` when issues are found, `0` otherwise — drop it into CI:
+
+```yaml
+# .github/workflows/a11y.yml
+- run: npx tailwind-a11y
+```
+
+## 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
+
+```bash
+npm install
+npm run dev -- "src/**/*.tsx"   # run the CLI against a project without building
+npm test                        # vitest
+npm run build                   # tsc -> dist/
+```
+
+## License
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import fg from "fast-glob";
+import { extractChecks, extractContrastSkips } from "./parser/extractClasses.js";
+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";
+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 "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":
+            return `${v.line}: <${v.tagName}> removes the focus outline (${v.removalClass}) with no visible replacement (focus:ring-*/border-*/shadow-*/bg-*/outline-*)`;
+    }
+}
+function groupByFile(items) {
+    const byFile = new Map();
+    for (const item of items) {
+        const existing = byFile.get(item.file);
+        if (existing) {
+            existing.push(item);
+        }
+        else {
+            byFile.set(item.file, [item]);
+        }
+    }
+    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 globPatterns = patterns.length > 0 ? patterns : ["**/*.{jsx,tsx}"];
+    const files = await fg(globPatterns, {
+        cwd: process.cwd(),
+        absolute: true,
+        ignore: ["**/node_modules/**", "**/dist/**", "**/.git/**", "**/build/**"],
+    });
+    const violations = [];
+    const skips = [];
+    for (const file of files) {
+        try {
+            const code = readFileSync(file, "utf8");
+            const contrastChecks = extractChecks(code, file);
+            violations.push(...checkContrast(contrastChecks), ...checkTouchTargets(extractTouchTargetChecks(code, file)), ...checkFocusIndicators(extractFocusIndicatorChecks(code, file)));
+            if (verbose) {
+                skips.push(...extractContrastSkips(code, file), ...checkContrastValueSkips(contrastChecks), ...extractTouchTargetSkips(code, file));
+            }
+        }
+        catch (err) {
+            // Consistent with the parser's own skip-on-unparsable-file behavior:
+            // one unreadable file (permissions, deleted between glob and read)
+            // shouldn't abort the whole scan.
+            console.warn(`tailwind-a11y: skipping unreadable file ${file}: ${err.message}`);
+        }
+    }
+    if (violations.length === 0) {
+        console.log("No accessibility issues found.");
+    }
+    else {
+        const byFile = groupByFile(violations);
+        for (const [file, fileViolations] of byFile) {
+            console.log(file);
+            for (const v of fileViolations) {
+                console.log(`  ${formatViolation(v)}`);
+            }
+        }
+        console.log(`\n${violations.length} issue(s) in ${byFile.size} file(s)`);
+    }
+    if (verbose && skips.length > 0) {
+        console.log(`\n--- Skipped (${skips.length}) — not checked, not a pass ---`);
+        const byFile = groupByFile(skips);
+        for (const [file, fileSkips] of byFile) {
+            console.log(file);
+            for (const s of fileSkips) {
+                console.log(`  ${s.line}: ${s.reason}`);
+            }
+        }
+    }
+    if (violations.length > 0) {
+        process.exitCode = 1;
+    }
+}
+main();

package/dist/contrast/luminance.d.ts

@@ -0,0 +1,10 @@
+export interface RGB {
+    r: number;
+    g: number;
+    b: number;
+}
+export declare function hexToRgb(hex: string): RGB | null;
+export declare function relativeLuminance(rgb: RGB): number;
+export declare function contrastRatio(rgb1: RGB, rgb2: RGB): number;
+export declare function requiredRatio(level: "AA" | "AAA", isLargeText: boolean): number;
+export declare function meetsWCAG(ratio: number, level: "AA" | "AAA", isLargeText: boolean): boolean;

package/dist/contrast/luminance.js

@@ -0,0 +1,42 @@
+const HEX_RE = /^#?([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/;
+export function hexToRgb(hex) {
+    const match = HEX_RE.exec(hex);
+    if (!match)
+        return null;
+    let digits = match[1];
+    if (digits.length === 3) {
+        digits = digits
+            .split("")
+            .map((c) => c + c)
+            .join("");
+    }
+    return {
+        r: parseInt(digits.slice(0, 2), 16),
+        g: parseInt(digits.slice(2, 4), 16),
+        b: parseInt(digits.slice(4, 6), 16),
+    };
+}
+function channelLuminance(channel) {
+    const c = channel / 255;
+    return c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+}
+export function relativeLuminance(rgb) {
+    return (0.2126 * channelLuminance(rgb.r) +
+        0.7152 * channelLuminance(rgb.g) +
+        0.0722 * channelLuminance(rgb.b));
+}
+export function contrastRatio(rgb1, rgb2) {
+    const l1 = relativeLuminance(rgb1);
+    const l2 = relativeLuminance(rgb2);
+    const lighter = Math.max(l1, l2);
+    const darker = Math.min(l1, l2);
+    return (lighter + 0.05) / (darker + 0.05);
+}
+export function requiredRatio(level, isLargeText) {
+    if (level === "AAA")
+        return isLargeText ? 4.5 : 7.0;
+    return isLargeText ? 3.0 : 4.5;
+}
+export function meetsWCAG(ratio, level, isLargeText) {
+    return ratio >= requiredRatio(level, isLargeText);
+}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { extractChecks, extractContrastSkips, type ContrastCheck, type ContrastSkip } from "./parser/extractClasses.js";
+export { checkContrast, checkContrastValueSkips, type ContrastViolation, type ContrastValueSkip } 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";
+export { checkFocusIndicators, type FocusIndicatorViolation } from "./rules/checkFocusIndicator.js";
+export { hexToRgb, contrastRatio, meetsWCAG, requiredRatio, type RGB } from "./contrast/luminance.js";

package/dist/index.js

@@ -0,0 +1,7 @@
+export { extractChecks, extractContrastSkips } from "./parser/extractClasses.js";
+export { checkContrast, checkContrastValueSkips } from "./rules/checkContrast.js";
+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 { hexToRgb, contrastRatio, meetsWCAG, requiredRatio } from "./contrast/luminance.js";

package/dist/parser/babelInterop.d.ts

@@ -0,0 +1,9 @@
+import type { NodePath } from "@babel/traverse";
+import * as t from "@babel/types";
+type TraverseFn = (ast: t.File, visitor: {
+    JSXElement?: (path: NodePath<t.JSXElement>) => void;
+}) => void;
+export declare const traverse: TraverseFn;
+export declare function parseJSX(code: string, filePath: string): t.File | null;
+export declare function getStaticClassName(attributes: t.JSXOpeningElement["attributes"]): string | null;
+export {};

package/dist/parser/babelInterop.js

@@ -0,0 +1,21 @@
+import { parse } from "@babel/parser";
+import _traverse from "@babel/traverse";
+import * as t from "@babel/types";
+export const traverse = (typeof _traverse === "function" ? _traverse : _traverse.default);
+export function parseJSX(code, filePath) {
+    try {
+        return parse(code, { sourceType: "module", plugins: ["jsx", "typescript"] });
+    }
+    catch {
+        console.warn(`tailwind-a11y: skipping unparsable file ${filePath}`);
+        return null;
+    }
+}
+export function getStaticClassName(attributes) {
+    const attr = attributes.find((a) => t.isJSXAttribute(a) && a.name.name === "className");
+    if (!attr || !attr.value)
+        return null;
+    if (t.isStringLiteral(attr.value))
+        return attr.value.value;
+    return null; // JSXExpressionContainer (ternary, template literal, clsx()...) — skip silently
+}

package/dist/parser/extractClasses.d.ts

@@ -0,0 +1,15 @@
+export interface ContrastCheck {
+    file: string;
+    line: number;
+    textColorClass: string;
+    bgColorClass: string;
+    bgSource: "self" | "parent";
+}
+export declare function lastColorToken(className: string, prefix: "text" | "bg"): string | null;
+export declare function extractChecks(code: string, filePath: string): ContrastCheck[];
+export interface ContrastSkip {
+    file: string;
+    line: number;
+    reason: string;
+}
+export declare function extractContrastSkips(code: string, filePath: string): ContrastSkip[];

package/dist/parser/extractClasses.js

@@ -0,0 +1,112 @@
+import * as t from "@babel/types";
+import { getStaticClassName, parseJSX, traverse } from "./babelInterop.js";
+// Positive shape filter for "does this look like a color utility", not a
+// blocklist — Tailwind heavily overloads the text-*/bg-* prefix (text-lg,
+// bg-cover, bg-gradient-to-r, ...) and an exclude-list would be fragile
+// across versions.
+const COLOR_TOKEN = /^\[(#[0-9a-fA-F]{3,8})\]$|^[a-z]+-\d{2,3}(\/\d{1,3})?$|^(white|black|transparent|current|inherit)$/;
+// 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
+// last-token-wins rule below, making a real violation vanish (a false
+// negative, the worst failure mode for a linter).
+const NON_COLOR_SCALE_NAMES = new Set(["opacity"]);
+export function lastColorToken(className, prefix) {
+    let found = null;
+    for (const raw of className.split(/\s+/).filter(Boolean)) {
+        const base = raw.slice(raw.lastIndexOf(":") + 1); // strip hover:/dark:/md: variants
+        if (!base.startsWith(`${prefix}-`))
+            continue;
+        const rest = base.slice(prefix.length + 1);
+        if (!COLOR_TOKEN.test(rest))
+            continue;
+        const scaleName = /^([a-z]+)-\d/.exec(rest)?.[1];
+        if (scaleName && NON_COLOR_SCALE_NAMES.has(scaleName))
+            continue;
+        found = base;
+    }
+    return found;
+}
+export function extractChecks(code, filePath) {
+    const ast = parseJSX(code, filePath);
+    if (!ast)
+        return [];
+    const checks = [];
+    traverse(ast, {
+        JSXElement(path) {
+            const className = getStaticClassName(path.node.openingElement.attributes);
+            if (!className)
+                return;
+            const textClass = lastColorToken(className, "text");
+            if (!textClass)
+                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" });
+                }
+            }
+        },
+    });
+    return checks;
+}
+// Independent pass (not merged into extractChecks) purely to surface why a
+// text color candidate produced no check — most usefully, the component-
+// boundary case: <Card><p className="text-gray-400">...</Card> where Card
+// sets its background internally, in a file this tool never opens. This is
+// a real, common miss (see CLAUDE.md's v1 scope), so it's made visible
+// rather than silently invisible, without attempting to actually resolve it.
+export function extractContrastSkips(code, filePath) {
+    const ast = parseJSX(code, filePath);
+    if (!ast)
+        return [];
+    const skips = [];
+    traverse(ast, {
+        JSXElement(path) {
+            const className = getStaticClassName(path.node.openingElement.attributes);
+            if (!className)
+                return;
+            const textClass = lastColorToken(className, "text");
+            if (!textClass)
+                return;
+            const ownBg = lastColorToken(className, "bg");
+            if (ownBg)
+                return; // extractChecks already covers this case
+            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;
+                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`,
+                    });
+                    return;
+                }
+            }
+            skips.push({
+                file: filePath,
+                line,
+                reason: `${textClass} — no background utility found on this element or its immediate parent`,
+            });
+        },
+    });
+    return skips;
+}

package/dist/parser/extractFocusIndicators.d.ts

@@ -0,0 +1,7 @@
+export interface FocusIndicatorCheck {
+    file: string;
+    line: number;
+    tagName: string;
+    focusClasses: string[];
+}
+export declare function extractFocusIndicatorChecks(code: string, filePath: string): FocusIndicatorCheck[];

package/dist/parser/extractFocusIndicators.js

@@ -0,0 +1,39 @@
+import * as t from "@babel/types";
+import { getStaticClassName, parseJSX, traverse } from "./babelInterop.js";
+import { isInteractiveElement } from "./isInteractiveElement.js";
+function focusScopedClasses(className) {
+    return className
+        .split(/\s+/)
+        .filter(Boolean)
+        .filter((raw) => {
+        const segments = raw.split(":");
+        const variant = segments[segments.length - 2]; // the variant immediately before the utility
+        return variant === "focus" || variant === "focus-visible";
+    });
+}
+export function extractFocusIndicatorChecks(code, filePath) {
+    const ast = parseJSX(code, filePath);
+    if (!ast)
+        return [];
+    const checks = [];
+    traverse(ast, {
+        JSXElement(path) {
+            const opening = path.node.openingElement;
+            if (!isInteractiveElement(opening))
+                return;
+            const className = getStaticClassName(opening.attributes);
+            if (!className)
+                return;
+            const focusClasses = focusScopedClasses(className);
+            if (focusClasses.length === 0)
+                return; // nothing under focus:/focus-visible: — not a candidate
+            checks.push({
+                file: filePath,
+                line: opening.loc?.start.line ?? 0,
+                tagName: t.isJSXIdentifier(opening.name) ? opening.name.name : "onClick-element",
+                focusClasses,
+            });
+        },
+    });
+    return checks;
+}

package/dist/parser/extractTouchTargets.d.ts

@@ -0,0 +1,16 @@
+export interface TouchTargetCheck {
+    file: string;
+    line: number;
+    tagName: string;
+    widthClass: string;
+    heightClass: string;
+    widthPx: number;
+    heightPx: number;
+}
+export declare function extractTouchTargetChecks(code: string, filePath: string): TouchTargetCheck[];
+export interface TouchTargetSkip {
+    file: string;
+    line: number;
+    reason: string;
+}
+export declare function extractTouchTargetSkips(code: string, filePath: string): TouchTargetSkip[];

package/dist/parser/extractTouchTargets.js

@@ -0,0 +1,95 @@
+import * as t from "@babel/types";
+import { getStaticClassName, parseJSX, traverse } from "./babelInterop.js";
+import { isInteractiveElement } from "./isInteractiveElement.js";
+import { spacingScale } from "../theme/spacingScale.js";
+// Only unprefixed w-*/h-* tokens count — a variant-scoped size like
+// hover:w-24 does not describe the resting-state box, so it must not be
+// allowed to overwrite a real base match via "last token wins" (the same
+// failure mode as bg-opacity-50 masking bg-white in the contrast checker).
+function lastSizeToken(tokens, prefix) {
+    let found = null;
+    for (const raw of tokens) {
+        if (raw.includes(":"))
+            continue;
+        if (!raw.startsWith(`${prefix}-`))
+            continue;
+        found = { raw, value: raw.slice(prefix.length + 1) };
+    }
+    return found;
+}
+export function extractTouchTargetChecks(code, filePath) {
+    const ast = parseJSX(code, filePath);
+    if (!ast)
+        return [];
+    const checks = [];
+    traverse(ast, {
+        JSXElement(path) {
+            const opening = path.node.openingElement;
+            if (!isInteractiveElement(opening))
+                return;
+            const className = getStaticClassName(opening.attributes);
+            if (!className)
+                return;
+            const tokens = className.split(/\s+/).filter(Boolean);
+            const width = lastSizeToken(tokens, "w");
+            const height = lastSizeToken(tokens, "h");
+            if (!width || !height)
+                return; // either dimension missing/dynamic — skip, don't guess
+            const widthPx = spacingScale[width.value];
+            const heightPx = spacingScale[height.value];
+            if (widthPx === undefined || heightPx === undefined)
+                return; // arbitrary/keyword/fraction — skip
+            checks.push({
+                file: filePath,
+                line: opening.loc?.start.line ?? 0,
+                tagName: t.isJSXIdentifier(opening.name) ? opening.name.name : "onClick-element",
+                widthClass: width.raw,
+                heightClass: height.raw,
+                widthPx,
+                heightPx,
+            });
+        },
+    });
+    return checks;
+}
+// Independent pass surfacing why an interactive element with size-related
+// classes produced no check: either only one of w-*/h-* is present, or a
+// present value isn't in the default spacing scale (arbitrary, keyword, or
+// fraction). Elements with neither w-* nor h-* at all aren't reported —
+// that's the overwhelming majority of interactive elements and would be
+// pure noise, not a meaningful skip.
+export function extractTouchTargetSkips(code, filePath) {
+    const ast = parseJSX(code, filePath);
+    if (!ast)
+        return [];
+    const skips = [];
+    traverse(ast, {
+        JSXElement(path) {
+            const opening = path.node.openingElement;
+            if (!isInteractiveElement(opening))
+                return;
+            const className = getStaticClassName(opening.attributes);
+            if (!className)
+                return;
+            const tokens = className.split(/\s+/).filter(Boolean);
+            const width = lastSizeToken(tokens, "w");
+            const height = lastSizeToken(tokens, "h");
+            if (!width && !height)
+                return; // no size classes at all — not a meaningful skip
+            const line = opening.loc?.start.line ?? 0;
+            if (!width || !height) {
+                const found = width ?? height;
+                const missing = width ? "height" : "width";
+                skips.push({ file: filePath, line, reason: `${found.raw} present but no ${missing} utility set — skipped` });
+                return;
+            }
+            const widthPx = spacingScale[width.value];
+            const heightPx = spacingScale[height.value];
+            if (widthPx === undefined || heightPx === undefined) {
+                const bad = widthPx === undefined ? width.raw : height.raw;
+                skips.push({ file: filePath, line, reason: `${bad} is not in the default spacing scale (arbitrary, keyword, or fraction value) — skipped` });
+            }
+        },
+    });
+    return skips;
+}

package/dist/parser/isInteractiveElement.d.ts

@@ -0,0 +1,2 @@
+import * as t from "@babel/types";
+export declare function isInteractiveElement(opening: t.JSXOpeningElement): boolean;

package/dist/parser/isInteractiveElement.js

@@ -0,0 +1,8 @@
+import * as t from "@babel/types";
+const INTERACTIVE_TAGS = new Set(["button", "a", "input", "select", "textarea"]);
+export function isInteractiveElement(opening) {
+    const tagName = t.isJSXIdentifier(opening.name) ? opening.name.name : null;
+    if (tagName !== null && INTERACTIVE_TAGS.has(tagName))
+        return true;
+    return opening.attributes.some((a) => t.isJSXAttribute(a) && a.name.name === "onClick");
+}

package/dist/rules/checkContrast.d.ts

@@ -0,0 +1,19 @@
+import type { ContrastCheck } from "../parser/extractClasses.js";
+export interface ContrastViolation {
+    type: "contrast";
+    file: string;
+    line: number;
+    textClass: string;
+    bgClass: string;
+    ratio: number;
+    required: number;
+    level: "AA";
+}
+export declare function resolveColorValue(utilityClass: string): string | null;
+export declare function checkContrast(checks: ContrastCheck[]): ContrastViolation[];
+export interface ContrastValueSkip {
+    file: string;
+    line: number;
+    reason: string;
+}
+export declare function checkContrastValueSkips(checks: ContrastCheck[]): ContrastValueSkip[];

package/dist/rules/checkContrast.js

@@ -0,0 +1,70 @@
+import { contrastRatio, hexToRgb, meetsWCAG, requiredRatio } from "../contrast/luminance.js";
+import { defaultPalette, semanticColors } from "../theme/defaultPalette.js";
+export function resolveColorValue(utilityClass) {
+    const match = /^(?:text|bg)-(.+)$/.exec(utilityClass);
+    if (!match)
+        return null;
+    const token = match[1];
+    const arbitrary = /^\[(#[0-9a-fA-F]{3,8})\]$/.exec(token);
+    if (arbitrary)
+        return arbitrary[1];
+    if (token.startsWith("["))
+        return null; // non-hex arbitrary (url()/var()/rgb()) — skip
+    if (token.includes("/"))
+        return null; // opacity shorthand — skip rather than approximate
+    if (token in semanticColors)
+        return semanticColors[token];
+    const [scale, shade] = token.split("-");
+    if (!scale || !shade)
+        return null;
+    return defaultPalette[scale]?.[shade] ?? null; // unknown/custom color — skip
+}
+export function checkContrast(checks) {
+    const violations = [];
+    for (const check of checks) {
+        const textHex = resolveColorValue(check.textColorClass);
+        const bgHex = resolveColorValue(check.bgColorClass);
+        if (!textHex || !bgHex)
+            continue;
+        const textRgb = hexToRgb(textHex);
+        const bgRgb = hexToRgb(bgHex);
+        if (!textRgb || !bgRgb)
+            continue;
+        const ratio = contrastRatio(textRgb, bgRgb);
+        const required = requiredRatio("AA", false); // v1: large-text detection deferred
+        if (!meetsWCAG(ratio, "AA", false)) {
+            violations.push({
+                type: "contrast",
+                file: check.file,
+                line: check.line,
+                textClass: check.textColorClass,
+                bgClass: check.bgColorClass,
+                ratio,
+                required,
+                level: "AA",
+            });
+        }
+    }
+    return violations;
+}
+// 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
+// extractContrastSkips' component-boundary case, since this one already has
+// a full text/bg pair and only failed at value resolution.
+export function checkContrastValueSkips(checks) {
+    const skips = [];
+    for (const check of checks) {
+        const textHex = resolveColorValue(check.textColorClass);
+        const bgHex = resolveColorValue(check.bgColorClass);
+        if (textHex && bgHex)
+            continue;
+        const unresolved = !textHex ? check.textColorClass : check.bgColorClass;
+        skips.push({
+            file: check.file,
+            line: check.line,
+            reason: `${unresolved} is not a recognized color (custom theme color or unsupported arbitrary value) — skipped`,
+        });
+    }
+    return skips;
+}

package/dist/rules/checkFocusIndicator.d.ts

@@ -0,0 +1,9 @@
+import type { FocusIndicatorCheck } from "../parser/extractFocusIndicators.js";
+export interface FocusIndicatorViolation {
+    type: "focus-indicator";
+    file: string;
+    line: number;
+    tagName: string;
+    removalClass: string;
+}
+export declare function checkFocusIndicators(checks: FocusIndicatorCheck[]): FocusIndicatorViolation[];

package/dist/rules/checkFocusIndicator.js

@@ -0,0 +1,41 @@
+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"]);
+// 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
+// mode as DEGENERATE_BASES above, but suffix-shaped rather than a fixed
+// set (opacity/offset take arbitrary numeric values), so matched with a
+// pattern instead of enumerated.
+const MODIFIER_ONLY = /^(bg|border|ring)-opacity-\d{1,3}$|^(ring|outline)-offset-\d{1,3}$|^ring-inset$/;
+function baseUtility(raw) {
+    return raw.slice(raw.lastIndexOf(":") + 1);
+}
+function isReplacement(raw) {
+    const base = baseUtility(raw);
+    if (DEGENERATE_BASES.has(base) || MODIFIER_ONLY.test(base))
+        return false;
+    return /^(ring|border|shadow|bg|outline)(-|$)/.test(base);
+}
+export function checkFocusIndicators(checks) {
+    const violations = [];
+    for (const check of checks) {
+        const removal = check.focusClasses.find((raw) => baseUtility(raw) === REMOVAL_BASE);
+        if (!removal)
+            continue;
+        const hasReplacement = check.focusClasses.some(isReplacement);
+        if (hasReplacement)
+            continue;
+        violations.push({
+            type: "focus-indicator",
+            file: check.file,
+            line: check.line,
+            tagName: check.tagName,
+            removalClass: removal,
+        });
+    }
+    return violations;
+}

package/dist/rules/checkTouchTarget.d.ts

@@ -0,0 +1,12 @@
+import type { TouchTargetCheck } from "../parser/extractTouchTargets.js";
+export interface TouchTargetViolation {
+    type: "touch-target";
+    file: string;
+    line: number;
+    tagName: string;
+    widthClass: string;
+    heightClass: string;
+    widthPx: number;
+    heightPx: number;
+}
+export declare function checkTouchTargets(checks: TouchTargetCheck[]): TouchTargetViolation[];

package/dist/rules/checkTouchTarget.js

@@ -0,0 +1,8 @@
+// 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) {
+    return checks
+        .filter((c) => c.widthPx < MIN_TARGET_PX || c.heightPx < MIN_TARGET_PX)
+        .map((c) => ({ type: "touch-target", ...c }));
+}

package/dist/theme/defaultPalette.d.ts

@@ -0,0 +1,4 @@
+export type ColorScale = Record<string, string>;
+export type Palette = Record<string, ColorScale>;
+export declare const defaultPalette: Palette;
+export declare const semanticColors: Record<string, string | null>;

package/dist/theme/defaultPalette.js

@@ -0,0 +1,300 @@
+// Snapshot of tailwindcss/colors (default palette), generated once at
+// authoring time rather than read from the consumer's project — see
+// CLAUDE.md: v1 does not read a user's tailwind.config.
+export const defaultPalette = {
+    slate: {
+        "50": "#f8fafc",
+        "100": "#f1f5f9",
+        "200": "#e2e8f0",
+        "300": "#cbd5e1",
+        "400": "#94a3b8",
+        "500": "#64748b",
+        "600": "#475569",
+        "700": "#334155",
+        "800": "#1e293b",
+        "900": "#0f172a",
+        "950": "#020617",
+    },
+    gray: {
+        "50": "#f9fafb",
+        "100": "#f3f4f6",
+        "200": "#e5e7eb",
+        "300": "#d1d5db",
+        "400": "#9ca3af",
+        "500": "#6b7280",
+        "600": "#4b5563",
+        "700": "#374151",
+        "800": "#1f2937",
+        "900": "#111827",
+        "950": "#030712",
+    },
+    zinc: {
+        "50": "#fafafa",
+        "100": "#f4f4f5",
+        "200": "#e4e4e7",
+        "300": "#d4d4d8",
+        "400": "#a1a1aa",
+        "500": "#71717a",
+        "600": "#52525b",
+        "700": "#3f3f46",
+        "800": "#27272a",
+        "900": "#18181b",
+        "950": "#09090b",
+    },
+    neutral: {
+        "50": "#fafafa",
+        "100": "#f5f5f5",
+        "200": "#e5e5e5",
+        "300": "#d4d4d4",
+        "400": "#a3a3a3",
+        "500": "#737373",
+        "600": "#525252",
+        "700": "#404040",
+        "800": "#262626",
+        "900": "#171717",
+        "950": "#0a0a0a",
+    },
+    stone: {
+        "50": "#fafaf9",
+        "100": "#f5f5f4",
+        "200": "#e7e5e4",
+        "300": "#d6d3d1",
+        "400": "#a8a29e",
+        "500": "#78716c",
+        "600": "#57534e",
+        "700": "#44403c",
+        "800": "#292524",
+        "900": "#1c1917",
+        "950": "#0c0a09",
+    },
+    red: {
+        "50": "#fef2f2",
+        "100": "#fee2e2",
+        "200": "#fecaca",
+        "300": "#fca5a5",
+        "400": "#f87171",
+        "500": "#ef4444",
+        "600": "#dc2626",
+        "700": "#b91c1c",
+        "800": "#991b1b",
+        "900": "#7f1d1d",
+        "950": "#450a0a",
+    },
+    orange: {
+        "50": "#fff7ed",
+        "100": "#ffedd5",
+        "200": "#fed7aa",
+        "300": "#fdba74",
+        "400": "#fb923c",
+        "500": "#f97316",
+        "600": "#ea580c",
+        "700": "#c2410c",
+        "800": "#9a3412",
+        "900": "#7c2d12",
+        "950": "#431407",
+    },
+    amber: {
+        "50": "#fffbeb",
+        "100": "#fef3c7",
+        "200": "#fde68a",
+        "300": "#fcd34d",
+        "400": "#fbbf24",
+        "500": "#f59e0b",
+        "600": "#d97706",
+        "700": "#b45309",
+        "800": "#92400e",
+        "900": "#78350f",
+        "950": "#451a03",
+    },
+    yellow: {
+        "50": "#fefce8",
+        "100": "#fef9c3",
+        "200": "#fef08a",
+        "300": "#fde047",
+        "400": "#facc15",
+        "500": "#eab308",
+        "600": "#ca8a04",
+        "700": "#a16207",
+        "800": "#854d0e",
+        "900": "#713f12",
+        "950": "#422006",
+    },
+    lime: {
+        "50": "#f7fee7",
+        "100": "#ecfccb",
+        "200": "#d9f99d",
+        "300": "#bef264",
+        "400": "#a3e635",
+        "500": "#84cc16",
+        "600": "#65a30d",
+        "700": "#4d7c0f",
+        "800": "#3f6212",
+        "900": "#365314",
+        "950": "#1a2e05",
+    },
+    green: {
+        "50": "#f0fdf4",
+        "100": "#dcfce7",
+        "200": "#bbf7d0",
+        "300": "#86efac",
+        "400": "#4ade80",
+        "500": "#22c55e",
+        "600": "#16a34a",
+        "700": "#15803d",
+        "800": "#166534",
+        "900": "#14532d",
+        "950": "#052e16",
+    },
+    emerald: {
+        "50": "#ecfdf5",
+        "100": "#d1fae5",
+        "200": "#a7f3d0",
+        "300": "#6ee7b7",
+        "400": "#34d399",
+        "500": "#10b981",
+        "600": "#059669",
+        "700": "#047857",
+        "800": "#065f46",
+        "900": "#064e3b",
+        "950": "#022c22",
+    },
+    teal: {
+        "50": "#f0fdfa",
+        "100": "#ccfbf1",
+        "200": "#99f6e4",
+        "300": "#5eead4",
+        "400": "#2dd4bf",
+        "500": "#14b8a6",
+        "600": "#0d9488",
+        "700": "#0f766e",
+        "800": "#115e59",
+        "900": "#134e4a",
+        "950": "#042f2e",
+    },
+    cyan: {
+        "50": "#ecfeff",
+        "100": "#cffafe",
+        "200": "#a5f3fc",
+        "300": "#67e8f9",
+        "400": "#22d3ee",
+        "500": "#06b6d4",
+        "600": "#0891b2",
+        "700": "#0e7490",
+        "800": "#155e75",
+        "900": "#164e63",
+        "950": "#083344",
+    },
+    sky: {
+        "50": "#f0f9ff",
+        "100": "#e0f2fe",
+        "200": "#bae6fd",
+        "300": "#7dd3fc",
+        "400": "#38bdf8",
+        "500": "#0ea5e9",
+        "600": "#0284c7",
+        "700": "#0369a1",
+        "800": "#075985",
+        "900": "#0c4a6e",
+        "950": "#082f49",
+    },
+    blue: {
+        "50": "#eff6ff",
+        "100": "#dbeafe",
+        "200": "#bfdbfe",
+        "300": "#93c5fd",
+        "400": "#60a5fa",
+        "500": "#3b82f6",
+        "600": "#2563eb",
+        "700": "#1d4ed8",
+        "800": "#1e40af",
+        "900": "#1e3a8a",
+        "950": "#172554",
+    },
+    indigo: {
+        "50": "#eef2ff",
+        "100": "#e0e7ff",
+        "200": "#c7d2fe",
+        "300": "#a5b4fc",
+        "400": "#818cf8",
+        "500": "#6366f1",
+        "600": "#4f46e5",
+        "700": "#4338ca",
+        "800": "#3730a3",
+        "900": "#312e81",
+        "950": "#1e1b4b",
+    },
+    violet: {
+        "50": "#f5f3ff",
+        "100": "#ede9fe",
+        "200": "#ddd6fe",
+        "300": "#c4b5fd",
+        "400": "#a78bfa",
+        "500": "#8b5cf6",
+        "600": "#7c3aed",
+        "700": "#6d28d9",
+        "800": "#5b21b6",
+        "900": "#4c1d95",
+        "950": "#2e1065",
+    },
+    purple: {
+        "50": "#faf5ff",
+        "100": "#f3e8ff",
+        "200": "#e9d5ff",
+        "300": "#d8b4fe",
+        "400": "#c084fc",
+        "500": "#a855f7",
+        "600": "#9333ea",
+        "700": "#7e22ce",
+        "800": "#6b21a8",
+        "900": "#581c87",
+        "950": "#3b0764",
+    },
+    fuchsia: {
+        "50": "#fdf4ff",
+        "100": "#fae8ff",
+        "200": "#f5d0fe",
+        "300": "#f0abfc",
+        "400": "#e879f9",
+        "500": "#d946ef",
+        "600": "#c026d3",
+        "700": "#a21caf",
+        "800": "#86198f",
+        "900": "#701a75",
+        "950": "#4a044e",
+    },
+    pink: {
+        "50": "#fdf2f8",
+        "100": "#fce7f3",
+        "200": "#fbcfe8",
+        "300": "#f9a8d4",
+        "400": "#f472b6",
+        "500": "#ec4899",
+        "600": "#db2777",
+        "700": "#be185d",
+        "800": "#9d174d",
+        "900": "#831843",
+        "950": "#500724",
+    },
+    rose: {
+        "50": "#fff1f2",
+        "100": "#ffe4e6",
+        "200": "#fecdd3",
+        "300": "#fda4af",
+        "400": "#fb7185",
+        "500": "#f43f5e",
+        "600": "#e11d48",
+        "700": "#be123c",
+        "800": "#9f1239",
+        "900": "#881337",
+        "950": "#4c0519",
+    },
+};
+// null entries are intentionally unresolvable: 'transparent' and 'current'
+// have no fixed luminance to compute a ratio against.
+export const semanticColors = {
+    white: "#ffffff",
+    black: "#000000",
+    transparent: null,
+    current: null,
+    inherit: null,
+};

package/dist/theme/spacingScale.d.ts

@@ -0,0 +1 @@
+export declare const spacingScale: Record<string, number>;

package/dist/theme/spacingScale.js

@@ -0,0 +1,47 @@
+// Snapshot of tailwindcss/defaultTheme's `spacing` scale, converted to px at
+// the standard 16px root (rem values × 16), generated the same way
+// defaultPalette.ts was — verified against the real installed `tailwindcss`
+// package's `require('tailwindcss/defaultTheme').spacing` rather than
+// hand-transcribed. See CLAUDE.md: v1 does not read a user's tailwind.config.
+//
+// No `/`-fraction keys exist in this base scale (fractions like `w-1/2` are
+// merged in separately by Tailwind's width/height theme functions), so a
+// fraction class naturally fails this lookup and is skipped as unresolvable
+// — the desired behavior, since a fraction is relative, not a fixed px value.
+export const spacingScale = {
+    "0": 0,
+    "px": 1,
+    "0.5": 2,
+    "1": 4,
+    "1.5": 6,
+    "2": 8,
+    "2.5": 10,
+    "3": 12,
+    "3.5": 14,
+    "4": 16,
+    "5": 20,
+    "6": 24,
+    "7": 28,
+    "8": 32,
+    "9": 36,
+    "10": 40,
+    "11": 44,
+    "12": 48,
+    "14": 56,
+    "16": 64,
+    "20": 80,
+    "24": 96,
+    "28": 112,
+    "32": 128,
+    "36": 144,
+    "40": 160,
+    "44": 176,
+    "48": 192,
+    "52": 208,
+    "56": 224,
+    "60": 240,
+    "64": 256,
+    "72": 288,
+    "80": 320,
+    "96": 384,
+};

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "tailwind-a11y",
+  "version": "0.1.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": {
+    "tailwind-a11y": "./dist/cli.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": ["dist"],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsx src/cli.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "keywords": ["tailwindcss", "accessibility", "a11y", "wcag", "wcag22", "contrast", "touch-target", "focus-visible", "lint"],
+  "author": "chamroro",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/chamroro/tailwind-a11y.git",
+    "directory": "packages/tailwind-a11y"
+  },
+  "bugs": {
+    "url": "https://github.com/chamroro/tailwind-a11y/issues"
+  },
+  "homepage": "https://github.com/chamroro/tailwind-a11y/tree/main/packages/tailwind-a11y#readme",
+  "dependencies": {
+    "@babel/parser": "^7.25.0",
+    "@babel/traverse": "^7.25.0",
+    "@babel/types": "^7.25.0",
+    "fast-glob": "^3.3.2"
+  },
+  "devDependencies": {
+    "@types/babel__traverse": "^7.20.6",
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.5.0",
+    "vitest": "^2.1.0"
+  }
+}