tailwind-a11y 0.3.1 → 0.4.0

package/README.md

@@ -22,13 +22,19 @@ npm install --save-dev tailwind-a11y
 ## Usage
 
 ```bash
-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
+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 --config ./tw.config.cjs     # use a specific tailwind.config instead of auto-detecting
+npx tailwind-a11y --version                    # print the installed version
+npx tailwind-a11y --help                       # usage and all options
 ```
 
+Custom `theme.extend.colors`/`theme.extend.spacing` in a `tailwind.config.js`/`.cjs`
+found in the current directory (or passed via `--config`) are read automatically, so
+colors and spacing outside Tailwind's defaults resolve too — not just the built-in
+palette.
+
 ```
 src/components/Card.tsx
   3: text-gray-400 on bg-white — ratio 2.54, needs 4.5 (AA); try text-gray-500 (4.83)
@@ -54,7 +60,9 @@ 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
+- A full `theme.colors`/`theme.spacing` replacement, `.mjs`/`.ts` configs, or
+  Tailwind v4's CSS-based `@theme` config (only `theme.extend` in a `.js`/`.cjs`
+  config is read — see [CLAUDE.md](./CLAUDE.md))
 - Color + opacity shorthand (`bg-white/50`)
 - Frameworks other than React/JSX
 

package/dist/cli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { readFileSync } from "node:fs";
-import { relative, sep } from "node:path";
+import { relative, resolve, sep } from "node:path";
 import { createRequire } from "node:module";
 import fg from "fast-glob";
 import { extractChecks, extractContrastSkips } from "./parser/extractClasses.js";
@@ -10,6 +10,7 @@ import { checkTouchTargets } from "./rules/checkTouchTarget.js";
 import { extractFocusIndicatorChecks } from "./parser/extractFocusIndicators.js";
 import { 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).
 const require = createRequire(import.meta.url);
 const { version: packageVersion } = require("../package.json");
@@ -39,7 +40,7 @@ function groupByFile(items) {
     return byFile;
 }
 async function main() {
-    const { help, version, verbose, patterns } = parseArgs(process.argv.slice(2));
+    const { help, version, verbose, config, configError: usageError, patterns } = parseArgs(process.argv.slice(2));
     if (help) {
         console.log(getHelpText());
         return;
@@ -48,6 +49,18 @@ async function main() {
         console.log(packageVersion);
         return;
     }
+    if (usageError) {
+        console.error(`tailwind-a11y: ${usageError}`);
+        process.exitCode = 1;
+        return;
+    }
+    const { palette, spacing, configError } = resolveTheme({
+        rootDir: process.cwd(),
+        configPath: config ? resolve(process.cwd(), config) : null,
+    });
+    if (configError) {
+        console.warn(`tailwind-a11y: ${configError}`);
+    }
     const globPatterns = patterns.length > 0 ? patterns : ["**/*.{jsx,tsx}"];
     const files = await fg(globPatterns, {
         cwd: process.cwd(),
@@ -64,9 +77,9 @@ async function main() {
         try {
             const code = readFileSync(absPath, "utf8");
             const contrastChecks = extractChecks(code, file);
-            violations.push(...checkContrast(contrastChecks), ...checkTouchTargets(extractTouchTargetChecks(code, file)), ...checkFocusIndicators(extractFocusIndicatorChecks(code, file)));
+            violations.push(...checkContrast(contrastChecks, palette), ...checkTouchTargets(extractTouchTargetChecks(code, file, spacing)), ...checkFocusIndicators(extractFocusIndicatorChecks(code, file)));
             if (verbose) {
-                skips.push(...extractContrastSkips(code, file), ...checkContrastValueSkips(contrastChecks), ...extractTouchTargetSkips(code, file));
+                skips.push(...extractContrastSkips(code, file), ...checkContrastValueSkips(contrastChecks, palette), ...extractTouchTargetSkips(code, file, spacing));
             }
         }
         catch (err) {

package/dist/cliArgs.d.ts

@@ -2,6 +2,8 @@ export interface ParsedArgs {
     help: boolean;
     version: boolean;
     verbose: boolean;
+    config: string | null;
+    configError: string | null;
     patterns: string[];
 }
 export declare function getHelpText(): string;

package/dist/cliArgs.js

@@ -6,14 +6,18 @@ 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
+  -v, --verbose      Also report what couldn't be checked, and why
+  -V, --version      Print the version number
+  -h, --help         Print this help message
+      --config <path>  Path to a tailwind.config.js/.cjs to read custom
+                        theme colors/spacing from (default: auto-detected
+                        in the current directory)
 
 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 --config ./tailwind.config.cjs
 `;
 export function getHelpText() {
     return HELP_TEXT;
@@ -22,10 +26,34 @@ export function getHelpText() {
 // avoids colliding with it, matching a common CLI convention.
 const FLAGS = new Set(["--verbose", "-v", "--version", "-V", "--help", "-h"]);
 export function parseArgs(argv) {
+    let config = null;
+    let configError = null;
+    const patterns = [];
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg !== "--config") {
+            if (!FLAGS.has(arg))
+                patterns.push(arg);
+            continue;
+        }
+        const value = argv[i + 1];
+        // A missing value or one that looks like another flag (starts with "-")
+        // must not be silently swallowed as a bogus path -- report a usage error
+        // instead of guessing.
+        if (value === undefined || value.startsWith("-")) {
+            configError = "--config requires a path argument";
+        }
+        else {
+            config = value;
+            i++; // consume the value too, so it isn't also treated as a glob pattern
+        }
+    }
     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)),
+        config,
+        configError,
+        patterns,
     };
 }

package/dist/index.d.ts

@@ -5,3 +5,5 @@ export { checkTouchTargets, type TouchTargetViolation } from "./rules/checkTouch
 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";
+export { resolveTheme, findTailwindConfig, loadCustomTheme, mergePalette, mergeSpacing, type ResolvedTheme, type RawCustomTheme, } from "./theme/loadCustomTheme.js";
+export type { Palette, ColorScale } from "./theme/defaultPalette.js";

package/dist/index.js

@@ -5,3 +5,4 @@ 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";
+export { resolveTheme, findTailwindConfig, loadCustomTheme, mergePalette, mergeSpacing, } from "./theme/loadCustomTheme.js";

package/dist/parser/extractTouchTargets.d.ts

@@ -7,10 +7,10 @@ export interface TouchTargetCheck {
     widthPx: number;
     heightPx: number;
 }
-export declare function extractTouchTargetChecks(code: string, filePath: string): TouchTargetCheck[];
+export declare function extractTouchTargetChecks(code: string, filePath: string, spacing?: Record<string, number>): TouchTargetCheck[];
 export interface TouchTargetSkip {
     file: string;
     line: number;
     reason: string;
 }
-export declare function extractTouchTargetSkips(code: string, filePath: string): TouchTargetSkip[];
+export declare function extractTouchTargetSkips(code: string, filePath: string, spacing?: Record<string, number>): TouchTargetSkip[];

package/dist/parser/extractTouchTargets.js

@@ -42,7 +42,7 @@ function isInlineInText(path) {
         return false;
     return isMeaningfulText(siblings[index - 1]) || isMeaningfulText(siblings[index + 1]);
 }
-export function extractTouchTargetChecks(code, filePath) {
+export function extractTouchTargetChecks(code, filePath, spacing = spacingScale) {
     const ast = parseJSX(code, filePath);
     if (!ast)
         return [];
@@ -60,8 +60,8 @@ export function extractTouchTargetChecks(code, filePath) {
             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];
+            const widthPx = spacing[width.value];
+            const heightPx = spacing[height.value];
             if (widthPx === undefined || heightPx === undefined)
                 return; // arbitrary/keyword/fraction — skip
             if (isInlineInText(path))
@@ -85,7 +85,7 @@ export function extractTouchTargetChecks(code, filePath) {
 // 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) {
+export function extractTouchTargetSkips(code, filePath, spacing = spacingScale) {
     const ast = parseJSX(code, filePath);
     if (!ast)
         return [];
@@ -110,11 +110,11 @@ export function extractTouchTargetSkips(code, filePath) {
                 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];
+            const widthPx = spacing[width.value];
+            const heightPx = spacing[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` });
+                skips.push({ file: filePath, line, reason: `${bad} is not in the resolved spacing scale (arbitrary, keyword, or fraction value) — skipped` });
             }
         },
     });

package/dist/rules/checkContrast.d.ts

@@ -1,3 +1,4 @@
+import type { Palette } from "../theme/defaultPalette.js";
 import type { ContrastCheck } from "../parser/extractClasses.js";
 export interface ContrastViolation {
     type: "contrast";
@@ -11,16 +12,16 @@ export interface ContrastViolation {
     suggestion?: string;
     suggestedRatio?: number;
 }
-export declare function resolveColorValue(utilityClass: string): string | null;
-export declare function checkContrast(checks: ContrastCheck[]): ContrastViolation[];
+export declare function resolveColorValue(utilityClass: string, palette?: Palette): string | null;
+export declare function checkContrast(checks: ContrastCheck[], palette?: Palette): ContrastViolation[];
 export interface ContrastFix {
     textClass: string;
     ratio: number;
 }
-export declare function suggestContrastFix(textClass: string, bgClass: string, required: number): ContrastFix | null;
+export declare function suggestContrastFix(textClass: string, bgClass: string, required: number, palette?: Palette): ContrastFix | null;
 export interface ContrastValueSkip {
     file: string;
     line: number;
     reason: string;
 }
-export declare function checkContrastValueSkips(checks: ContrastCheck[]): ContrastValueSkip[];
+export declare function checkContrastValueSkips(checks: ContrastCheck[], palette?: Palette): ContrastValueSkip[];

package/dist/rules/checkContrast.js

@@ -1,6 +1,6 @@
 import { contrastRatio, hexToRgb, meetsWCAG, requiredRatio } from "../contrast/luminance.js";
 import { defaultPalette, semanticColors } from "../theme/defaultPalette.js";
-export function resolveColorValue(utilityClass) {
+export function resolveColorValue(utilityClass, palette = defaultPalette) {
     const match = /^(?:text|bg)-(.+)$/.exec(utilityClass);
     if (!match)
         return null;
@@ -17,13 +17,13 @@ export function resolveColorValue(utilityClass) {
     const [scale, shade] = token.split("-");
     if (!scale || !shade)
         return null;
-    return defaultPalette[scale]?.[shade] ?? null; // unknown/custom color — skip
+    return palette[scale]?.[shade] ?? null; // unknown/custom color — skip
 }
-export function checkContrast(checks) {
+export function checkContrast(checks, palette = defaultPalette) {
     const violations = [];
     for (const check of checks) {
-        const textHex = resolveColorValue(check.textColorClass);
-        const bgHex = resolveColorValue(check.bgColorClass);
+        const textHex = resolveColorValue(check.textColorClass, palette);
+        const bgHex = resolveColorValue(check.bgColorClass, palette);
         if (!textHex || !bgHex)
             continue;
         const textRgb = hexToRgb(textHex);
@@ -33,7 +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);
+            const fix = suggestContrastFix(check.textColorClass, check.bgColorClass, required, palette);
             violations.push({
                 type: "contrast",
                 file: check.file,
@@ -58,15 +58,15 @@ const TEXT_SCALE_SHADE_RE = /^text-([a-z]+)-(\d+)$/;
 // 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) {
+export function suggestContrastFix(textClass, bgClass, required, palette = defaultPalette) {
     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];
+    const shades = palette[scale];
     if (!shades?.[shade])
         return null; // custom scale, or a decoy like text-opacity-50
-    const bgHex = resolveColorValue(bgClass);
+    const bgHex = resolveColorValue(bgClass, palette);
     const bgRgb = bgHex ? hexToRgb(bgHex) : null;
     if (!bgRgb)
         return null;
@@ -90,11 +90,11 @@ export function suggestContrastFix(textClass, bgClass, required) {
 // 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) {
+export function checkContrastValueSkips(checks, palette = defaultPalette) {
     const skips = [];
     for (const check of checks) {
-        const textHex = resolveColorValue(check.textColorClass);
-        const bgHex = resolveColorValue(check.bgColorClass);
+        const textHex = resolveColorValue(check.textColorClass, palette);
+        const bgHex = resolveColorValue(check.bgColorClass, palette);
         if (textHex && bgHex)
             continue;
         const unresolved = !textHex ? check.textColorClass : check.bgColorClass;

package/dist/theme/loadCustomTheme.d.ts

@@ -0,0 +1,18 @@
+import type { Palette } from "./defaultPalette.js";
+export declare function findTailwindConfig(rootDir: string): string | null;
+export interface RawCustomTheme {
+    colors?: Palette;
+    spacing?: Record<string, number>;
+}
+export declare function loadCustomTheme(configPath: string): RawCustomTheme | null;
+export declare function mergePalette(base: Palette, extend?: Palette): Palette;
+export declare function mergeSpacing(base: Record<string, number>, extend?: Record<string, number>): Record<string, number>;
+export interface ResolvedTheme {
+    palette: Palette;
+    spacing: Record<string, number>;
+    configError?: string;
+}
+export declare function resolveTheme(opts: {
+    rootDir: string | null;
+    configPath?: string | null;
+}): ResolvedTheme;

package/dist/theme/loadCustomTheme.js

@@ -0,0 +1,149 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { createRequire } from "node:module";
+import { hexToRgb } from "../contrast/luminance.js";
+import { defaultPalette } from "./defaultPalette.js";
+import { spacingScale } from "./spacingScale.js";
+const CONFIG_FILENAMES = ["tailwind.config.js", "tailwind.config.cjs"];
+// v1 only looks in the given directory itself -- no ancestor-directory search.
+// --config (CLI) / settings["tailwind-a11y"].configPath (ESLint) exist as
+// explicit escape hatches for projects where this isn't enough. `rootDir` must
+// be an absolute path.
+export function findTailwindConfig(rootDir) {
+    for (const filename of CONFIG_FILENAMES) {
+        const candidate = join(rootDir, filename);
+        if (existsSync(candidate))
+            return candidate;
+    }
+    return null;
+}
+const SPACING_RE = /^-?[\d.]+(rem|px)$/;
+function parseSpacingValue(value) {
+    if (typeof value !== "string")
+        return null;
+    const match = SPACING_RE.exec(value);
+    if (!match)
+        return null; // em/%/vw/bare number/function -- skip, don't guess
+    const num = parseFloat(value);
+    return match[1] === "rem" ? num * 16 : num; // matches spacingScale.ts's 16px-root assumption
+}
+// Only plain hex-shade objects are accepted (e.g. `brand: { 500: '#3490dc' }`).
+// A flat string color (`brand: '#3490dc'`) or a `DEFAULT` key is skipped
+// entirely -- there's no class syntax ("bg-brand-DEFAULT" isn't real Tailwind)
+// that would ever resolve to it, so partially supporting it would be dead code.
+function parseColorScale(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return null;
+    const shades = {};
+    for (const [shade, shadeValue] of Object.entries(value)) {
+        if (shade === "DEFAULT")
+            continue; // no "bg-brand-DEFAULT" class syntax exists to resolve it
+        if (typeof shadeValue !== "string")
+            continue;
+        if (hexToRgb(shadeValue) === null)
+            continue; // not a hex value -- skip, don't guess
+        shades[shade] = shadeValue;
+    }
+    return Object.keys(shades).length > 0 ? shades : null;
+}
+// Loads a tailwind.config.js/.cjs and extracts only `theme.extend.colors` /
+// `theme.extend.spacing` -- v1 does not read a full `theme.colors`/`theme.spacing`
+// replacement, Tailwind v4's CSS-based `@theme` config, or .mjs/.ts configs (no
+// config-transpiling dependency exists in this package). `configPath` must be
+// an absolute path (require() resolves relative paths against this module's
+// own location, not the caller's cwd).
+//
+// Node's require() cache is busted before loading -- recursively, for the
+// config file *and* everything it required (e.g. a config that factors
+// tokens into a separate `require('./colors.js')`) -- without this, a
+// long-lived process (the VS Code extension host, an editor-integrated
+// ESLint server) would keep serving a stale value forever after the user
+// edits any file the config depends on, not just the config file itself.
+function bustRequireCache(require, mod, seen) {
+    if (seen.has(mod.id))
+        return;
+    seen.add(mod.id);
+    for (const child of mod.children)
+        bustRequireCache(require, child, seen);
+    delete require.cache[mod.id];
+}
+// Returns null only when the file itself couldn't be loaded (missing,
+// syntax error, ERR_REQUIRE_ESM for a "type": "module" project, or a config
+// that throws) -- a config that loads fine but has no theme.extend colors or
+// spacing returns {}, which callers must not treat as an error.
+export function loadCustomTheme(configPath) {
+    try {
+        const require = createRequire(import.meta.url);
+        const resolved = require.resolve(configPath);
+        const cached = require.cache[resolved];
+        if (cached)
+            bustRequireCache(require, cached, new Set());
+        const config = require(resolved);
+        const extend = config?.theme?.extend ?? {};
+        const result = {};
+        if (extend.colors && typeof extend.colors === "object") {
+            const colors = {};
+            for (const [scale, value] of Object.entries(extend.colors)) {
+                const shades = parseColorScale(value);
+                if (shades)
+                    colors[scale] = shades;
+            }
+            if (Object.keys(colors).length > 0)
+                result.colors = colors;
+        }
+        if (extend.spacing && typeof extend.spacing === "object") {
+            const spacing = {};
+            for (const [token, value] of Object.entries(extend.spacing)) {
+                const px = parseSpacingValue(value);
+                if (px !== null)
+                    spacing[token] = px;
+            }
+            if (Object.keys(spacing).length > 0)
+                result.spacing = spacing;
+        }
+        return result;
+    }
+    catch {
+        return null;
+    }
+}
+// New scale names are added wholesale; extending an existing scale merges
+// shade keys in without dropping the scale's other (default) shades.
+export function mergePalette(base, extend) {
+    if (!extend)
+        return base;
+    const merged = { ...base };
+    for (const [scale, shades] of Object.entries(extend)) {
+        merged[scale] = { ...merged[scale], ...shades };
+    }
+    return merged;
+}
+export function mergeSpacing(base, extend) {
+    return extend ? { ...base, ...extend } : base;
+}
+// configError is only ever set when a path was *explicitly* provided (CLI
+// --config flag or ESLint settings) and failed to load -- auto-detected
+// absence stays silent, matching the "avoid confusing noise in an unrelated
+// linter run" precedent already in the ESLint plugin's index.ts. `rootDir`
+// and `configPath` (if given) must be absolute paths.
+export function resolveTheme(opts) {
+    const explicitPath = opts.configPath ?? null;
+    const configPath = explicitPath ?? (opts.rootDir ? findTailwindConfig(opts.rootDir) : null);
+    if (!configPath) {
+        return { palette: defaultPalette, spacing: spacingScale };
+    }
+    const custom = loadCustomTheme(configPath);
+    if (custom === null) {
+        return explicitPath
+            ? {
+                palette: defaultPalette,
+                spacing: spacingScale,
+                configError: `could not load Tailwind config at ${explicitPath}`,
+            }
+            : { palette: defaultPalette, spacing: spacingScale };
+    }
+    return {
+        palette: mergePalette(defaultPalette, custom.colors),
+        spacing: mergeSpacing(spacingScale, custom.spacing),
+    };
+}

package/package.json

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