tailwind-a11y 0.3.1 → 0.5.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)
@@ -44,7 +50,7 @@ Exits `1` on violations — safe to use as a CI gate.
 
 | Check | WCAG | Detects |
 |---|---|---|
-| Contrast | 1.4.3 (AA) | `text-*`/`bg-*` pairs below 4.5:1, same-element or direct-parent; suggests the nearest passing shade |
+| Contrast | 1.4.3 (AA) | `text-*`/`bg-*` pairs below 4.5:1, same-element or direct-parent, including a text-side opacity modifier (`text-gray-400/50`) composited against the background; suggests the nearest passing shade |
 | Touch target | 2.5.8 (AA) | Interactive elements under 24×24px |
 | Focus indicator | 2.4.7 (AA) | `focus:outline-none` with no visible replacement |
 
@@ -54,8 +60,13 @@ When a case can't be resolved with confidence, it's skipped rather than guessed:
 
 - Ancestors beyond the immediate parent, or backgrounds set inside a separate component
 - Dynamic or computed `className` (ternaries, `clsx()`, template literals)
-- Custom theme colors/spacing not in Tailwind's default scales
-- Color + opacity shorthand (`bg-white/50`)
+- 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))
+- Opacity shorthand on the **background** side (`bg-white/50` as the actual
+  background) — the rendered backdrop is layout-dependent and out of scope,
+  same reasoning as the ancestor-parent limit above. **Text-side** opacity
+  (`text-gray-400/50`) *is* resolved, composited against the (opaque) background.
 - Frameworks other than React/JSX
 
 `--verbose` reports what was skipped and why — a skip is not a pass. Full rationale in

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/contrast/luminance.d.ts

@@ -4,6 +4,7 @@ export interface RGB {
     b: number;
 }
 export declare function hexToRgb(hex: string): RGB | null;
+export declare function applyAlpha(fg: RGB, alpha: number, bg: RGB): RGB;
 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;

package/dist/contrast/luminance.js

@@ -16,6 +16,17 @@ export function hexToRgb(hex) {
         b: parseInt(digits.slice(4, 6), 16),
     };
 }
+// Standard "src-over" compositing of a foreground at `alpha` opacity over an
+// opaque background, in gamma-encoded sRGB space (0-255 channels) -- matches
+// how browsers actually composite CSS opacity, no linear-light conversion
+// needed for a simple two-layer blend.
+export function applyAlpha(fg, alpha, bg) {
+    return {
+        r: Math.round(alpha * fg.r + (1 - alpha) * bg.r),
+        g: Math.round(alpha * fg.g + (1 - alpha) * bg.g),
+        b: Math.round(alpha * fg.b + (1 - alpha) * bg.b),
+    };
+}
 function channelLuminance(channel) {
     const c = channel / 255;
     return c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;

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/extractClasses.js

@@ -3,8 +3,13 @@ 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)$/;
+// across versions. Every alternative allows an optional trailing opacity
+// modifier (/NN) so text-white/40, text-[#eee]/40, and text-gray-400/40 are
+// all extracted with the suffix intact -- text-white/black-with-opacity is
+// an extremely common real idiom, more so than the named-scale case, and
+// dropping it here would make the contrast checker's opacity support (see
+// rules/checkContrast.ts) silently inapplicable to the most common case.
+const COLOR_TOKEN = /^\[(#[0-9a-fA-F]{3,8})\](\/\d{1,3})?$|^[a-z]+-\d{2,3}(\/\d{1,3})?$|^(white|black|transparent|current|inherit)(\/\d{1,3})?$/;
 // opacity-{N} (e.g. bg-opacity-50, text-opacity-50) matches the same
 // "word-number" shape as a color token but isn't one — without this
 // exclusion it can silently overwrite a real color match via the

package/dist/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 { applyAlpha, 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,23 +17,57 @@ 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) {
+// Splits a trailing Tailwind opacity modifier off a color utility class
+// (e.g. "text-gray-400/50" -> { base: "text-gray-400", alpha: 0.5 }). No
+// modifier -> alpha 1. Out-of-range (>100) is clamped rather than rejected --
+// real browsers clamp out-of-range CSS alpha to the nearest valid bound, so
+// "/150" genuinely renders identically to "/100"; silently skipping it
+// instead would hide a real violation behind what's essentially a typo. A
+// non-digit or malformed suffix falls through as { base: <the whole original
+// string>, alpha: 1 } -- base still contains the "/", so resolveColorValue's
+// existing guard rejects it downstream; this never needs to return null.
+function splitOpacityModifier(utilityClass) {
+    const match = /^(.+)\/(\d{1,3})$/.exec(utilityClass);
+    if (!match)
+        return { base: utilityClass, alpha: 1 };
+    const pct = Math.min(100, Math.max(0, Number(match[2])));
+    return { base: match[1], alpha: pct / 100 };
+}
+// Resolves a text-* class (with or without an opacity modifier) to the
+// effective color it actually renders as, composited against the already-
+// resolved (fully opaque) background. Only the text side supports opacity --
+// see resolveColorValue's own unconditional "/" rejection for why the
+// background side doesn't: compositing a semi-transparent background
+// correctly requires knowing what's rendered *behind* it, which is out of
+// scope the same way walking further up the ancestor chain is.
+function resolveTextColorWithOpacity(utilityClass, bgRgb, palette) {
+    const { base, alpha } = splitOpacityModifier(utilityClass);
+    if (alpha === 0)
+        return null; // fully transparent -- equivalent to text-transparent, nothing to check
+    const hex = resolveColorValue(base, palette);
+    const rgb = hex ? hexToRgb(hex) : null;
+    if (!rgb)
+        return null;
+    return alpha < 1 ? applyAlpha(rgb, alpha, bgRgb) : rgb;
+}
+export function checkContrast(checks, palette = defaultPalette) {
     const violations = [];
     for (const check of checks) {
-        const textHex = resolveColorValue(check.textColorClass);
-        const bgHex = resolveColorValue(check.bgColorClass);
-        if (!textHex || !bgHex)
+        const bgHex = resolveColorValue(check.bgColorClass, palette);
+        if (!bgHex)
             continue;
-        const textRgb = hexToRgb(textHex);
         const bgRgb = hexToRgb(bgHex);
-        if (!textRgb || !bgRgb)
+        if (!bgRgb)
+            continue;
+        const textRgb = resolveTextColorWithOpacity(check.textColorClass, bgRgb, palette);
+        if (!textRgb)
             continue;
         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,
@@ -50,23 +84,27 @@ export function checkContrast(checks) {
     return violations;
 }
 const TEXT_SCALE_SHADE_RE = /^text-([a-z]+)-(\d+)$/;
-// Only the text shade moves — bg stays fixed, since text color is the more
-// commonly adjustable side in practice. Candidates come from the palette's
-// actual keys (not an assumed 50..950 enumeration), sorted nearest-first by
-// numeric distance from the original shade; ties favor the higher/darker
-// shade, since real failures here are overwhelmingly light-on-light and
-// darker is the fix a human reaches for. The original shade can never win:
-// it's in this same candidate list at distance 0, and this recomputes the
-// identical unrounded ratio comparison that just failed.
-export function suggestContrastFix(textClass, bgClass, required) {
-    const match = TEXT_SCALE_SHADE_RE.exec(textClass);
+// Only the text shade moves — bg and any opacity modifier on the text class
+// stay fixed, since text color is the more commonly adjustable side in
+// practice. Candidates come from the palette's actual keys (not an assumed
+// 50..950 enumeration), sorted nearest-first by numeric distance from the
+// original shade; ties favor the higher/darker shade, since real failures
+// here are overwhelmingly light-on-light and darker is the fix a human
+// reaches for. The original shade can never win: it's in this same
+// candidate list at distance 0, and this recomputes the identical unrounded
+// ratio comparison that just failed.
+export function suggestContrastFix(textClass, bgClass, required, palette = defaultPalette) {
+    const { base, alpha } = splitOpacityModifier(textClass);
+    if (alpha === 0)
+        return null; // no shade change fixes total transparency
+    const match = TEXT_SCALE_SHADE_RE.exec(base);
     if (!match)
-        return null; // text-white, text-[#eee], text-gray-400/50 — no suggestion
+        return null; // text-white, text-[#eee] — 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;
@@ -75,34 +113,64 @@ export function suggestContrastFix(textClass, bgClass, required) {
         .filter((s) => /^\d+$/.test(s))
         .map(Number)
         .sort((a, b) => Math.abs(a - original) - Math.abs(b - original) || b - a);
+    // Only the shade searches candidates -- the original opacity is held
+    // fixed, exactly like bg is already held fixed.
     for (const candidate of candidates) {
         const rgb = hexToRgb(shades[String(candidate)]);
         if (!rgb)
             continue;
-        const ratio = contrastRatio(rgb, bgRgb);
-        if (ratio >= required)
-            return { textClass: `text-${scale}-${candidate}`, ratio };
+        const effectiveRgb = alpha < 1 ? applyAlpha(rgb, alpha, bgRgb) : rgb;
+        const ratio = contrastRatio(effectiveRgb, bgRgb);
+        if (ratio >= required) {
+            const suggestedClass = alpha < 1 ? `text-${scale}-${candidate}/${Math.round(alpha * 100)}` : `text-${scale}-${candidate}`;
+            return { textClass: suggestedClass, ratio };
+        }
     }
     return null;
 }
 // A candidate that extractChecks *did* find a background for, but whose
 // text or bg utility didn't resolve to a known value (custom theme color,
-// non-hex arbitrary value, opacity shorthand) — surfaced separately from
-// extractContrastSkips' component-boundary case, since this one already has
-// a full text/bg pair and only failed at value resolution.
-export function checkContrastValueSkips(checks) {
+// non-hex arbitrary value, background-side 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.
+//
+// Resolves bg first, same order as checkContrast, so a bg-side failure and a
+// text-side failure are attributed to the correct class -- since text
+// resolution now depends on a known bg to composite against, resolving both
+// independently (as before) would make every bg failure also look like a
+// text failure. This does mean that when *both* sides are unresolvable for
+// unrelated reasons, bg is now named first (previously text always was) --
+// a deliberate, tested change, not an accidental side effect of reordering.
+export function checkContrastValueSkips(checks, palette = defaultPalette) {
     const skips = [];
     for (const check of checks) {
-        const textHex = resolveColorValue(check.textColorClass);
-        const bgHex = resolveColorValue(check.bgColorClass);
-        if (textHex && bgHex)
+        const bgHex = resolveColorValue(check.bgColorClass, palette);
+        const bgRgb = bgHex ? hexToRgb(bgHex) : null;
+        if (!bgRgb) {
+            skips.push({
+                file: check.file,
+                line: check.line,
+                reason: `${check.bgColorClass} is not a recognized color (custom theme color or unsupported arbitrary value) — skipped`,
+            });
             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`,
-        });
+        }
+        const { alpha } = splitOpacityModifier(check.textColorClass);
+        if (alpha === 0) {
+            skips.push({
+                file: check.file,
+                line: check.line,
+                reason: `${check.textColorClass} is fully transparent (opacity 0) — nothing rendered to check`,
+            });
+            continue;
+        }
+        const textRgb = resolveTextColorWithOpacity(check.textColorClass, bgRgb, palette);
+        if (!textRgb) {
+            skips.push({
+                file: check.file,
+                line: check.line,
+                reason: `${check.textColorClass} is not a recognized color (custom theme color or unsupported arbitrary value) — skipped`,
+            });
+        }
     }
     return skips;
 }

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.5.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": {