tailwind-a11y 0.6.0 → 0.7.0

package/README.md

@@ -25,15 +25,17 @@ 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 --config ./tw.config.cjs     # use a specific tailwind.config instead of auto-detecting
+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
 ```
 
-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.
+Custom theme colors/spacing are read automatically, so colors and spacing outside
+Tailwind's defaults resolve too — not just the built-in palette. Both config formats
+are supported: `theme.extend.colors`/`theme.extend.spacing` in a Tailwind v3
+`tailwind.config.js`/`.cjs`, and `--color-*`/`--spacing-*` custom properties in a
+Tailwind v4 CSS `@theme { ... }` block (auto-detected from common paths like
+`app/globals.css`, or passed via `--config`).
 
 ```
 src/components/Card.tsx

package/dist/cliArgs.js

@@ -9,9 +9,10 @@ Options:
   -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)
+      --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:
+                        auto-detected in the current directory)
 
 Examples:
   tailwind-a11y                    Scan **/*.{jsx,tsx} from the current directory

package/dist/index.d.ts

@@ -5,5 +5,6 @@ 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 { resolveTheme, findTailwindConfig, loadCustomTheme, findTailwindThemeCss, loadThemeFromCssFile, mergePalette, mergeSpacing, type ResolvedTheme, type RawCustomTheme, } from "./theme/loadCustomTheme.js";
+export { parseThemeCss } from "./theme/parseThemeCss.js";
 export type { Palette, ColorScale } from "./theme/defaultPalette.js";

package/dist/index.js

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

package/dist/theme/loadCustomTheme.d.ts

@@ -1,10 +1,12 @@
 import type { Palette } from "./defaultPalette.js";
 export declare function findTailwindConfig(rootDir: string): string | null;
+export declare function findTailwindThemeCss(rootDir: string): string | null;
 export interface RawCustomTheme {
     colors?: Palette;
     spacing?: Record<string, number>;
 }
 export declare function loadCustomTheme(configPath: string): RawCustomTheme | null;
+export declare function loadThemeFromCssFile(cssPath: 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 {

package/dist/theme/loadCustomTheme.js

@@ -1,9 +1,10 @@
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync } 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";
+import { parseColorScale, parseSpacingValue } from "./themeValueParsers.js";
+import { parseThemeCss } from "./parseThemeCss.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
@@ -17,41 +18,38 @@ export function findTailwindConfig(rootDir) {
     }
     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;
+// Checked in priority order, in rootDir only (no recursive walk) -- v4 has no
+// single conventional filename the way v3 has tailwind.config.js, so this is
+// a heuristic covering common Next.js App Router / Pages Router / Vite React
+// conventions, most-specific first. `globals.css` is checked last since it's
+// the most generic name and the most likely to false-positive-match a file
+// that isn't actually the Tailwind entry point. --config (CLI) /
+// settings["tailwind-a11y"].configPath (ESLint) / INPUT_CONFIG (Action)
+// remain the escape hatch for anything else.
+const CSS_THEME_CANDIDATES = [
+    "app/globals.css",
+    "src/app/globals.css",
+    "styles/globals.css",
+    "src/styles/globals.css",
+    "src/index.css",
+    "globals.css",
+];
+export function findTailwindThemeCss(rootDir) {
+    for (const rel of CSS_THEME_CANDIDATES) {
+        const candidate = join(rootDir, rel);
+        if (existsSync(candidate))
+            return candidate;
     }
-    return Object.keys(shades).length > 0 ? shades : null;
+    return 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).
+// Loads a Tailwind v3-style tailwind.config.js/.cjs and extracts only
+// `theme.extend.colors`/`theme.extend.spacing` -- v1 does not read a full
+// `theme.colors`/`theme.spacing` replacement, or .mjs/.ts configs (no
+// config-transpiling dependency exists in this package). Tailwind v4's
+// CSS-based `@theme` config is a separate format entirely, handled by
+// loadThemeFromCssFile()/parseThemeCss() below, not by this function.
+// `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
@@ -114,6 +112,19 @@ export function loadCustomTheme(configPath) {
         return null;
     }
 }
+// Loads a Tailwind v4 CSS file and extracts @theme colors/spacing via
+// parseThemeCss(). Returns null only when the file itself couldn't be read
+// (missing, permission error) -- a file that reads fine but has no @theme
+// block (or nothing recognized inside one) returns {}, same contract as
+// loadCustomTheme. `cssPath` must be an absolute path.
+export function loadThemeFromCssFile(cssPath) {
+    try {
+        return parseThemeCss(readFileSync(cssPath, "utf8"));
+    }
+    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) {
@@ -132,14 +143,23 @@ export function mergeSpacing(base, extend) {
 // --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.
+// and `configPath` (if given) must be absolute paths. `configPath` may point
+// at either a .js/.cjs config or a .css file with an @theme block --
+// dispatched by extension below.
+//
+// Auto-detection tries the JS config first, CSS second: an existing project
+// with a tailwind.config.js gets zero change in resolved output even if it
+// also happens to have an unrelated @theme block (e.g. mid v3-to-v4
+// migration, or a leftover v3 config alongside a partially-adopted v4 CSS
+// file).
 export function resolveTheme(opts) {
     const explicitPath = opts.configPath ?? null;
-    const configPath = explicitPath ?? (opts.rootDir ? findTailwindConfig(opts.rootDir) : null);
+    const configPath = explicitPath ??
+        (opts.rootDir ? (findTailwindConfig(opts.rootDir) ?? findTailwindThemeCss(opts.rootDir)) : null);
     if (!configPath) {
         return { palette: defaultPalette, spacing: spacingScale };
     }
-    const custom = loadCustomTheme(configPath);
+    const custom = configPath.endsWith(".css") ? loadThemeFromCssFile(configPath) : loadCustomTheme(configPath);
     if (custom === null) {
         return explicitPath
             ? {

package/dist/theme/parseThemeCss.d.ts

@@ -0,0 +1,2 @@
+import type { RawCustomTheme } from "./loadCustomTheme.js";
+export declare function parseThemeCss(cssText: string): RawCustomTheme;

package/dist/theme/parseThemeCss.js

@@ -0,0 +1,133 @@
+import { parseColorScale, parseSpacingValue } from "./themeValueParsers.js";
+// Run BEFORE comment-stripping/block-extraction so quoted string content
+// (e.g. a `content: "@theme { --color-brand-500: #3490dc; }"` value) can
+// never be mistaken for a real @theme block or accidentally throw off brace
+// counting -- without this, any valid CSS file containing that substring
+// for unrelated reasons (docs/marketing copy showcasing Tailwind v4 syntax,
+// for instance) would silently inject spurious palette/spacing entries.
+// Replaces each matched string (quotes included) with same-length spaces,
+// so it can't itself contain unmasked quotes/braces/`@theme` text, while
+// keeping offsets stable. An unterminated string (malformed CSS) just
+// doesn't match and is left as-is -- fail safe, don't guess.
+function maskStringLiterals(css) {
+    return css.replace(/"(?:[^"\\]|\\.)*"|'(?:[^'\\]|\\.)*'/g, (m) => " ".repeat(m.length));
+}
+function stripComments(css) {
+    return css.replace(/\/\*[\s\S]*?\*\//g, "");
+}
+// Matches `@theme {`, `@theme inline {`, `@theme static {`, and any other
+// modifier keyword Tailwind might add between `@theme` and the opening
+// brace -- the declaration syntax inside is identical regardless of
+// modifier, so no need to enumerate them. Brace-depth-counted (not a naive
+// first-`}` match) so an accidental nested `{` in a value can't truncate the
+// block early.
+//
+// An unclosed `@theme{` (malformed CSS -- missing a `}` somewhere) aborts
+// extraction for the rest of the file, not just that one block: brace
+// counting has no way to tell "a later, well-formed @theme block" apart
+// from "more content nested inside the still-open first block," so any
+// `{`/`}` pairs after the missing close (including a second, otherwise-valid
+// @theme block) get consumed as if they belonged to the first. The safe,
+// honest result is {} for the whole file rather than a guess at which
+// blocks were "real" -- same "skip, don't guess" precedent as everywhere
+// else in this parser, just at file granularity instead of block
+// granularity when recovery isn't possible.
+function extractThemeBlocks(css) {
+    const blocks = [];
+    const OPEN_RE = /@theme\b[^{]*\{/g;
+    let match;
+    while ((match = OPEN_RE.exec(css))) {
+        const start = match.index + match[0].length;
+        let depth = 1;
+        let i = start;
+        for (; i < css.length && depth > 0; i++) {
+            if (css[i] === "{")
+                depth++;
+            else if (css[i] === "}")
+                depth--;
+        }
+        if (depth !== 0)
+            break;
+        blocks.push(css.slice(start, i - 1));
+        OPEN_RE.lastIndex = i;
+    }
+    return blocks;
+}
+// Split on `;` rather than a single greedy declaration regex, so a missing
+// trailing semicolon before `}` (valid CSS) doesn't drop the last
+// declaration.
+function extractDeclarations(block) {
+    const decls = [];
+    for (const raw of block.split(";")) {
+        const trimmed = raw.trim();
+        if (!trimmed)
+            continue;
+        const colon = trimmed.indexOf(":");
+        if (colon === -1)
+            continue;
+        const prop = trimmed.slice(0, colon).trim();
+        if (!prop.startsWith("--"))
+            continue;
+        decls.push([prop, trimmed.slice(colon + 1).trim()]);
+    }
+    return decls;
+}
+// Greedy .+ anchored on the *last* -\d+, so multi-hyphen scale names
+// (--color-hot-pink-500) resolve to scale "hot-pink", shade "500".
+const COLOR_PROP_RE = /^--color-(.+)-(\d+)$/;
+const SPACING_PROP_RE = /^--spacing-([\w-]+)$/;
+// Reads Tailwind v4's CSS-first `@theme { ... }` config -- extracts only
+// --color-{name}-{shade} and --spacing-{token} custom properties, running
+// each value through the exact same hex/rem-px acceptance rules as the JS
+// tailwind.config.js path (parseColorScale/parseSpacingValue from
+// themeValueParsers.ts), so no validation logic is duplicated between the
+// two config formats. A bare `--color-brand: #3490dc` (no shade suffix) is
+// skipped -- same "no class syntax to resolve it to" reasoning as the JS
+// path's flat-string-color skip. A bare `--spacing: 0.25rem` (Tailwind v4's
+// global spacing *multiplier*, which scales all arbitrary spacing
+// utilities) is also skipped -- spacingScale.ts is a static named-token to
+// px map, not a multiplier system; supporting the multiplier correctly
+// would mean reimplementing derived-value math, a different feature.
+// `@import`ed files are never followed -- only @theme blocks physically
+// present in the given CSS text are read.
+//
+// Never throws and never returns null -- unlike loadCustomTheme's
+// require()-based loading, this is tolerant scanning, not execution, so
+// there's no "syntax error" concept here. Worst case (no @theme block, or
+// nothing recognized inside one) returns {}, the same "loaded fine but
+// nothing to extend" contract loadCustomTheme uses.
+export function parseThemeCss(cssText) {
+    const colorBuckets = {};
+    const spacingRaw = {};
+    for (const block of extractThemeBlocks(stripComments(maskStringLiterals(cssText)))) {
+        for (const [prop, value] of extractDeclarations(block)) {
+            const colorMatch = COLOR_PROP_RE.exec(prop);
+            if (colorMatch) {
+                const [, scale, shade] = colorMatch;
+                (colorBuckets[scale] ??= {})[shade] = value;
+                continue;
+            }
+            const spacingMatch = SPACING_PROP_RE.exec(prop);
+            if (spacingMatch)
+                spacingRaw[spacingMatch[1]] = value;
+        }
+    }
+    const result = {};
+    const colors = {};
+    for (const [scale, shades] of Object.entries(colorBuckets)) {
+        const parsed = parseColorScale(shades);
+        if (parsed)
+            colors[scale] = parsed;
+    }
+    if (Object.keys(colors).length > 0)
+        result.colors = colors;
+    const spacing = {};
+    for (const [token, value] of Object.entries(spacingRaw)) {
+        const px = parseSpacingValue(value);
+        if (px !== null)
+            spacing[token] = px;
+    }
+    if (Object.keys(spacing).length > 0)
+        result.spacing = spacing;
+    return result;
+}

package/dist/theme/themeValueParsers.d.ts

@@ -0,0 +1,2 @@
+export declare function parseSpacingValue(value: unknown): number | null;
+export declare function parseColorScale(value: unknown): Record<string, string> | null;

package/dist/theme/themeValueParsers.js

@@ -0,0 +1,30 @@
+import { hexToRgb } from "../contrast/luminance.js";
+const SPACING_RE = /^-?[\d.]+(rem|px)$/;
+export 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.
+export 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;
+}

package/package.json

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