tailwind-a11y 0.10.0 → 0.13.0

package/README.md

@@ -25,7 +25,7 @@ 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 --strict                     # touch targets: WCAG 2.5.5 (AAA, 44x44px); focus indicators: also WCAG 2.4.13 (AAA, min thickness)
+npx tailwind-a11y --strict                     # AAA tier: touch targets 2.5.5, focus indicators also 2.4.13, and enables the reduced-motion check (2.3.3)
 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
@@ -34,7 +34,7 @@ npx tailwind-a11y --help                       # usage and all options
 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.config.js`/`.cjs`/`.mjs`, 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`).
 
@@ -57,6 +57,7 @@ Exits `1` on violations — safe to use as a CI gate.
 | Touch target | 2.5.8 (AA) | Interactive elements under 24×24px — or 44×44px with `--strict` (2.5.5, AAA) |
 | Focus indicator | 2.4.7 (AA) | `focus:outline-none` with no visible replacement |
 | Focus indicator contrast | 1.4.11 (AA) | A present `outline-*`/`ring-*` focus indicator below 3:1 contrast — or also below the 2px minimum thickness with `--strict` (2.4.13, AAA) |
+| Reduced motion | 2.3.3 (AAA, `--strict` only) | A `hover:`/`focus:`/`focus-visible:`/`active:`-scoped `scale-*`/`rotate-*`/`translate-*`/`skew-*` change with an unscoped `transition`/`transition-all`/`transition-transform` and no `motion-reduce:`/`motion-safe:` handling |
 
 ## Scope
 

package/dist/cli.js

@@ -9,6 +9,8 @@ import { extractTouchTargetChecks, extractTouchTargetSkips } from "./parser/extr
 import { checkTouchTargets } from "./rules/checkTouchTarget.js";
 import { extractFocusIndicatorChecks } from "./parser/extractFocusIndicators.js";
 import { checkFocusContrast, checkFocusIndicators, } from "./rules/checkFocusIndicator.js";
+import { extractReducedMotionChecks } from "./parser/extractReducedMotion.js";
+import { checkReducedMotion } from "./rules/checkReducedMotion.js";
 import { parseArgs, getHelpText } from "./cliArgs.js";
 import { resolveTheme } from "./theme/loadCustomTheme.js";
 // ../package.json resolves correctly from both src/ (dev) and dist/ (published).
@@ -33,6 +35,8 @@ function formatViolation(v) {
                 ? `${base}; also only ${v.thicknessPx}px thick, needs >= ${v.requiredThicknessPx}px`
                 : base;
         }
+        case "reduced-motion":
+            return `${v.line}: <${v.tagName}> animates ${v.motionClass} via ${v.transitionClass} with no motion-reduce:transition-none/transform-none guard — WCAG 2.3.3 requires motion animation triggered by interaction to be disableable`;
     }
 }
 function groupByFile(items) {
@@ -87,7 +91,7 @@ async function main() {
             const code = readFileSync(absPath, "utf8");
             const contrastChecks = extractChecks(code, file);
             const focusChecks = extractFocusIndicatorChecks(code, file);
-            violations.push(...checkContrast(contrastChecks, palette), ...checkTouchTargets(extractTouchTargetChecks(code, file, spacing), strict), ...checkFocusIndicators(focusChecks), ...checkFocusContrast(focusChecks, strict, palette));
+            violations.push(...checkContrast(contrastChecks, palette), ...checkTouchTargets(extractTouchTargetChecks(code, file, spacing), strict), ...checkFocusIndicators(focusChecks), ...checkFocusContrast(focusChecks, strict, palette), ...checkReducedMotion(extractReducedMotionChecks(code, file), strict));
             if (verbose) {
                 skips.push(...extractContrastSkips(code, file), ...checkContrastValueSkips(contrastChecks, palette), ...extractTouchTargetSkips(code, file, spacing));
             }

package/dist/cliArgs.js

@@ -3,7 +3,8 @@
 const HELP_TEXT = `Usage: tailwind-a11y [options] [<glob>...]
 
 Static analysis for Tailwind CSS accessibility violations -- color contrast,
-touch target size, and focus indicator removal/contrast.
+touch target size, focus indicator removal/contrast, and reduced-motion
+support for interaction-triggered animation.
 
 Options:
   -v, --verbose      Also report what couldn't be checked, and why
@@ -12,7 +13,10 @@ Options:
       --strict       Touch targets must meet WCAG 2.5.5 (AAA, 44x44px)
                       instead of the default 2.5.8 (AA, 24x24px); focus
                       indicators are also held to 2.4.13 (AAA, minimum
-                      thickness) alongside the default 1.4.11 (AA, contrast)
+                      thickness) alongside the default 1.4.11 (AA, contrast);
+                      also enables the reduced-motion check (WCAG 2.3.3,
+                      AAA-only, off by default -- has no AA tier to fall
+                      back to)
       --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:

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 rgbToHex(rgb: RGB): string;
 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;

package/dist/contrast/luminance.js

@@ -16,6 +16,15 @@ export function hexToRgb(hex) {
         b: parseInt(digits.slice(4, 6), 16),
     };
 }
+// Inverse of hexToRgb -- used once, by themeValueParsers.ts's
+// parseColorScale(), to turn an accepted oklch() value back into the plain
+// hex string every downstream consumer already expects a palette shade to
+// be. Channels are clamped and rounded rather than assumed already valid,
+// since a caller could in principle pass an out-of-range value.
+export function rgbToHex(rgb) {
+    const channel = (c) => Math.round(Math.min(255, Math.max(0, c))).toString(16).padStart(2, "0");
+    return `#${channel(rgb.r)}${channel(rgb.g)}${channel(rgb.b)}`;
+}
 // 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

package/dist/contrast/oklch.d.ts

@@ -0,0 +1,2 @@
+import type { RGB } from "./luminance.js";
+export declare function oklchToRgb(value: string): RGB | null;

package/dist/contrast/oklch.js

@@ -0,0 +1,67 @@
+// L and C each accept a plain number or a percentage; H accepts a plain
+// degree number or an explicit `deg` suffix (`180` and `180deg` render
+// identically -- confirmed against a real browser, see below). An alpha
+// component (`/ A`) or the `none` keyword for any channel is deliberately
+// unsupported and falls through to the "not oklch" case below: the palette
+// only ever stores fully opaque colors today (HEX_RE in luminance.ts
+// doesn't accept 4/8-digit hex with alpha either), so this mirrors an
+// existing limit rather than introducing a new one.
+// A real number shape only -- `\d+(?:\.\d+)?|\.\d+` matches "5", "5.5", and
+// ".5" but not "5." or "0..5". The looser `[\d.]+` this replaced accepted
+// "0..5" too, which Number() coerces to NaN -- silently producing an
+// {r:NaN,g:NaN,b:NaN} object where oklchToRgb's contract says this should
+// have been rejected outright (caught in review; the isFinite guard below
+// is a second, independent layer against the same failure mode).
+const NUM = String.raw `\d+(?:\.\d+)?|\.\d+`;
+const OKLCH_RE = new RegExp(`^oklch\\(\\s*(${NUM})(%)?\\s+(${NUM})(%)?\\s+(${NUM})(deg)?\\s*\\)$`);
+// Standard OKLab <-> linear sRGB conversion matrices (Björn Ottosson's
+// published reference, the same ones browsers implement per CSS Color 4).
+// Verified this session against a real headless Chrome: rendered each of
+// white/black/a midtone gray/saturated red/teal/purple/an intentionally
+// out-of-gamut saturated red-orange/percentage-L/percentage-C/a deg-suffixed
+// hue onto a <canvas> and read back the actual pixel RGB via getImageData()
+// -- getComputedStyle().color isn't usable for this, since modern Chrome
+// serializes a computed oklch() value back out as oklch(), not rgb(). Every
+// case matched the real browser-rendered pixel exactly (0 channel
+// difference), including the out-of-gamut case, confirming both the
+// matrices and the clamp-before-gamma-encode approach below are correct as
+// implemented, not just approximately close.
+function gammaEncode(linear) {
+    const clamped = Math.min(1, Math.max(0, linear));
+    return clamped <= 0.0031308 ? 12.92 * clamped : 1.055 * clamped ** (1 / 2.4) - 0.055;
+}
+export function oklchToRgb(value) {
+    const match = OKLCH_RE.exec(value.trim());
+    if (!match)
+        return null;
+    const [, lRaw, lPct, cRaw, cPct, hRaw] = match;
+    const L = lPct ? Number(lRaw) / 100 : Number(lRaw);
+    const C = cPct ? (Number(cRaw) / 100) * 0.4 : Number(cRaw); // 100% chroma == 0.4, the CSS Color 4 reference range
+    const H = Number(hRaw);
+    // Belt-and-suspenders: independent of whether the regex above is airtight,
+    // this makes the RGB | null contract impossible to violate -- a NaN here
+    // would otherwise propagate silently into a "successfully resolved" but
+    // garbage color (rgbToHex would render it as the literal string
+    // "#NaNNaNNaN", which downstream code happens to reject today, but only
+    // by accident of a stricter hex regex elsewhere, not because this
+    // function actually enforced its own contract).
+    if (!Number.isFinite(L) || !Number.isFinite(C) || !Number.isFinite(H))
+        return null;
+    const hRad = (H * Math.PI) / 180;
+    const a = C * Math.cos(hRad);
+    const b = C * Math.sin(hRad);
+    const l_ = L + 0.3963377774 * a + 0.2158037573 * b;
+    const m_ = L - 0.1055613458 * a - 0.0638541728 * b;
+    const s_ = L - 0.0894841775 * a - 1.2914855480 * b;
+    const l = l_ ** 3;
+    const m = m_ ** 3;
+    const s = s_ ** 3;
+    const rLin = 4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s;
+    const gLin = -1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s;
+    const bLin = -0.0041960863 * l - 0.7034186147 * m + 1.7076147010 * s;
+    return {
+        r: Math.round(gammaEncode(rLin) * 255),
+        g: Math.round(gammaEncode(gLin) * 255),
+        b: Math.round(gammaEncode(bLin) * 255),
+    };
+}

package/dist/index.d.ts

@@ -4,6 +4,8 @@ export { extractTouchTargetChecks, extractTouchTargetSkips, type TouchTargetChec
 export { checkTouchTargets, type TouchTargetViolation } from "./rules/checkTouchTarget.js";
 export { extractFocusIndicatorChecks, type FocusIndicatorCheck } from "./parser/extractFocusIndicators.js";
 export { checkFocusIndicators, checkFocusContrast, type FocusIndicatorViolation, type FocusContrastViolation, } from "./rules/checkFocusIndicator.js";
+export { extractReducedMotionChecks, type ReducedMotionCheck } from "./parser/extractReducedMotion.js";
+export { checkReducedMotion, type ReducedMotionViolation } from "./rules/checkReducedMotion.js";
 export { hexToRgb, contrastRatio, meetsWCAG, requiredRatio, type RGB } from "./contrast/luminance.js";
 export { resolveTheme, findTailwindConfig, loadCustomTheme, findTailwindThemeCss, loadThemeFromCssFile, mergePalette, mergeSpacing, type ResolvedTheme, type RawCustomTheme, } from "./theme/loadCustomTheme.js";
 export { parseThemeCss } from "./theme/parseThemeCss.js";

package/dist/index.js

@@ -4,6 +4,8 @@ export { extractTouchTargetChecks, extractTouchTargetSkips } from "./parser/extr
 export { checkTouchTargets } from "./rules/checkTouchTarget.js";
 export { extractFocusIndicatorChecks } from "./parser/extractFocusIndicators.js";
 export { checkFocusIndicators, checkFocusContrast, } from "./rules/checkFocusIndicator.js";
+export { extractReducedMotionChecks } from "./parser/extractReducedMotion.js";
+export { checkReducedMotion } from "./rules/checkReducedMotion.js";
 export { hexToRgb, contrastRatio, meetsWCAG, requiredRatio } from "./contrast/luminance.js";
 export { resolveTheme, findTailwindConfig, loadCustomTheme, findTailwindThemeCss, loadThemeFromCssFile, mergePalette, mergeSpacing, } from "./theme/loadCustomTheme.js";
 export { parseThemeCss } from "./theme/parseThemeCss.js";

package/dist/parser/extractReducedMotion.d.ts

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

package/dist/parser/extractReducedMotion.js

@@ -0,0 +1,50 @@
+import * as t from "@babel/types";
+import { getStaticClassName, parseJSX, traverse } from "./babelInterop.js";
+const TRANSITION_BASES = new Set(["transition", "transition-all", "transition-transform"]);
+const INTERACTION_VARIANTS = new Set(["hover", "focus", "focus-visible", "focus-within", "active"]);
+function baseUtility(raw) {
+    return raw.slice(raw.lastIndexOf(":") + 1);
+}
+// Every variant applied to a class, in source order -- NOT just the one
+// immediately before the base utility. Caught in independent review:
+// Tailwind variants stack (`motion-safe:hover:scale-110` and
+// `hover:motion-safe:scale-110` compile to the identical nested media query,
+// confirmed against a real v4 build), so checking only the innermost
+// segment made this extractor's own candidacy gate order-dependent -- it
+// would only recognize the interaction variant when it happened to be
+// written last, silently missing the equally valid `hover:motion-safe:...`
+// ordering. checkReducedMotion.ts uses the same helper for the same reason.
+function variantSegments(raw) {
+    return raw.split(":").slice(0, -1);
+}
+export function extractReducedMotionChecks(code, filePath) {
+    const ast = parseJSX(code, filePath);
+    if (!ast)
+        return [];
+    const checks = [];
+    traverse(ast, {
+        JSXElement(path) {
+            const opening = path.node.openingElement;
+            const className = getStaticClassName(opening.attributes);
+            if (!className)
+                return;
+            const classes = className.split(/\s+/).filter(Boolean);
+            const hasTransitionBase = classes.some((raw) => TRANSITION_BASES.has(baseUtility(raw)));
+            const hasInteractionClass = classes.some((raw) => variantSegments(raw).some((v) => INTERACTION_VARIANTS.has(v)));
+            // Not a candidate at all unless there's some transition utility
+            // (scoped or not) *and* some interaction-scoped class -- narrows the
+            // set of elements checkReducedMotion.ts has to reason about, without
+            // pre-deciding any of the nuance (unscoped vs motion-safe:, identity
+            // values, motion-reduce: guards) that belongs in the rule.
+            if (!hasTransitionBase || !hasInteractionClass)
+                return;
+            checks.push({
+                file: filePath,
+                line: opening.loc?.start.line ?? 0,
+                tagName: t.isJSXIdentifier(opening.name) ? opening.name.name : "unknown-element",
+                classes,
+            });
+        },
+    });
+    return checks;
+}

package/dist/rules/checkReducedMotion.d.ts

@@ -0,0 +1,11 @@
+import type { ReducedMotionCheck } from "../parser/extractReducedMotion.js";
+export interface ReducedMotionViolation {
+    type: "reduced-motion";
+    file: string;
+    line: number;
+    tagName: string;
+    transitionClass: string;
+    motionClass: string;
+    level: "AAA";
+}
+export declare function checkReducedMotion(checks: ReducedMotionCheck[], strict?: boolean): ReducedMotionViolation[];

package/dist/rules/checkReducedMotion.js

@@ -0,0 +1,109 @@
+// Verified against a real Tailwind v4 build: only these three include
+// transform/translate/scale/rotate in their transition-property list.
+// transition-colors/-opacity/-shadow don't -- so a scale/rotate/translate
+// change under hover on an element with only one of those never actually
+// animates (the browser has nothing telling it to transition that
+// property), and correctly isn't flagged.
+const TRANSITION_BASES = new Set(["transition", "transition-all", "transition-transform"]);
+const INTERACTION_VARIANTS = new Set(["hover", "focus", "focus-visible", "focus-within", "active"]);
+function baseUtility(raw) {
+    return raw.slice(raw.lastIndexOf(":") + 1);
+}
+// Every variant applied to a class, in source order -- see the identical
+// helper (and full explanation) in extractReducedMotion.ts. Duplicated
+// rather than imported, matching this codebase's own established
+// precedent of small per-file primitives (e.g. checkFocusIndicator.ts's own
+// baseUtility is separate from extractFocusIndicators.ts's).
+function variantSegments(raw) {
+    return raw.split(":").slice(0, -1);
+}
+// Positive shape filter, not a denylist -- same reasoning as COLOR_TOKEN in
+// extractClasses.ts. Excludes each utility's identity value (scale-100,
+// rotate-0, translate-x-0/-y-0, skew-x-0/-y-0), since those utilities are
+// real but move nothing -- flagging them would be a false positive, the
+// same "shape looks real but isn't" failure class this project has hit
+// before. Arbitrary bracket values (scale-[1.5]) and 3D transform utilities
+// (rotate-x-*, translate-z-*, ...) are out of scope for v1 -- unmatched, so
+// silently not considered "motion" here rather than guessed at.
+const SCALE_RE = /^(scale|scale-x|scale-y)-(\d+)$/;
+const ROTATE_RE = /^-?rotate-(\d+(?:\.\d+)?)$/;
+const TRANSLATE_RE = /^-?(translate-x|translate-y)-(\d+(?:\.\d+)?)$/;
+const SKEW_RE = /^-?(skew-x|skew-y)-(\d+(?:\.\d+)?)$/;
+function isNonIdentityMotionUtility(base) {
+    const scale = SCALE_RE.exec(base);
+    if (scale)
+        return Number(scale[2]) !== 100;
+    const rotate = ROTATE_RE.exec(base);
+    if (rotate)
+        return Number(rotate[1]) !== 0;
+    const translate = TRANSLATE_RE.exec(base);
+    if (translate)
+        return Number(translate[2]) !== 0;
+    const skew = SKEW_RE.exec(base);
+    if (skew)
+        return Number(skew[2]) !== 0;
+    return false;
+}
+// `strict` gates the whole check for the scan-everything-by-default
+// adapters (CLI/VS Code/GitHub Action) -- WCAG 2.3.3 is AAA-only, and
+// unconditionally enabling a brand-new AAA check would silently start
+// failing existing users' CI on a routine upgrade, unlike a genuine AA
+// baseline (2.4.7's focus-indicator check, the one other check in this file
+// with no strict tier). Consistent with this project's own `strict` =
+// "hold every check to its AAA tier where one exists" framing. The ESLint
+// rule is the one caller that always passes `true` regardless -- enabling
+// `tailwind-a11y/reduced-motion` in an ESLint config is itself the opt-in
+// gesture there, so a second gate on top would just make the rule silently
+// report nothing when a user enabled it expecting it to check something.
+export function checkReducedMotion(checks, strict = false) {
+    if (!strict)
+        return [];
+    const violations = [];
+    for (const check of checks) {
+        let unscopedTransition = null;
+        let hasMotionReduceGuard = false;
+        for (const raw of check.classes) {
+            const base = baseUtility(raw);
+            const segments = variantSegments(raw);
+            if (segments.length === 0 && TRANSITION_BASES.has(base))
+                unscopedTransition = raw;
+            if (segments.includes("motion-reduce") && (base === "transition-none" || base === "transform-none")) {
+                hasMotionReduceGuard = true;
+            }
+        }
+        // A transition scoped only under motion-safe: (never unscoped) means it
+        // simply doesn't exist unless motion is already safe -- a complete
+        // alternative way of satisfying 2.3.3, not a partial one -- so this
+        // correctly falls through as a pass, not a skip-because-unresolvable.
+        if (!unscopedTransition)
+            continue;
+        if (hasMotionReduceGuard)
+            continue;
+        const motionClass = check.classes.find((raw) => {
+            const segments = variantSegments(raw);
+            // motion-safe: anywhere in this specific class's own variant stack
+            // means the motion utility itself doesn't apply unless motion is
+            // already safe -- the same complete-alternative reasoning as the
+            // transition side above, just checked per-candidate instead of once
+            // for the whole element (a class can be interaction-scoped *and*
+            // self-guarded at the same time, e.g. `hover:motion-safe:scale-110`).
+            if (segments.includes("motion-safe"))
+                return false;
+            if (!segments.some((v) => INTERACTION_VARIANTS.has(v)))
+                return false;
+            return isNonIdentityMotionUtility(baseUtility(raw));
+        });
+        if (!motionClass)
+            continue; // no real, un-self-guarded motion actually triggered by interaction
+        violations.push({
+            type: "reduced-motion",
+            file: check.file,
+            line: check.line,
+            tagName: check.tagName,
+            transitionClass: unscopedTransition,
+            motionClass,
+            level: "AAA",
+        });
+    }
+    return violations;
+}

package/dist/theme/loadCustomTheme.js

@@ -5,7 +5,10 @@ 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"];
+// .mjs appended last (lowest priority) -- the newly-supported format behind
+// the two established ones, same "most established first" ordering
+// CSS_THEME_CANDIDATES below already uses for its own list.
+const CONFIG_FILENAMES = ["tailwind.config.js", "tailwind.config.cjs", "tailwind.config.mjs"];
 // 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
@@ -42,15 +45,46 @@ export function findTailwindThemeCss(rootDir) {
     }
     return null;
 }
-// Loads a Tailwind v3-style tailwind.config.js/.cjs and extracts only
+// Loads a Tailwind v3-style tailwind.config.js/.cjs/.mjs 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
+// `theme.colors`/`theme.spacing` replacement, or .ts configs. 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).
 //
+// .mjs works via plain require() -- verified this session that Node
+// 20.19+/22.13+ can require() an ESM module synchronously, no import(), no
+// async refactor. On an older Node this throws ERR_REQUIRE_ESM, already
+// caught below and treated as "no config found," so this degrades exactly
+// as gracefully as it did before .mjs was supported. Every adapter's actual
+// runtime already clears the threshold: the GitHub Action runs on Node 24
+// (action.yml), eslint-plugin-tailwind-a11y's own engines.node already
+// excludes every version that lacks this, and the CLI's broad >=18 floor
+// just falls back safely on anything older.
+//
+// .ts is a deliberate non-goal, not a "not yet": Node's native TypeScript
+// type-stripping only activates when the *host* process is launched with
+// --experimental-strip-types (verified this session -- a library can't
+// turn this on for the user), so the only way to support .ts transparently
+// would be promoting esbuild from a devDependency to a real runtime
+// dependency of this package purely to transpile config files, a real
+// native-binary weight increase. Also verified this session: a fresh
+// `create-next-app --typescript --tailwind` no longer generates a JS/TS
+// config file at all -- Tailwind v4 projects put theme customization in a
+// CSS `@theme` block instead (see loadThemeFromCssFile() below), so .ts
+// config support would only help a shrinking population of legacy
+// v3-plus-TypeScript projects, not worth the dependency.
+//
+// Known limitation, not fixed: bustRequireCache() below does NOT work for
+// a .mjs config. Node's synchronous require(esm) caches the module in its
+// own internal ESM registry, not (only) in `require.cache` -- deleting the
+// `require.cache` entry doesn't force a reload, confirmed with a real
+// edit-and-reload test this session. CLI and GitHub Action are unaffected
+// (fresh process per run either way); the VS Code extension's live-reload
+// guarantee, which does work correctly for .js/.cjs/.css configs, does NOT
+// extend to .mjs -- editing a .mjs config requires reloading the window.
+//
 // 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
@@ -83,7 +117,20 @@ export function loadCustomTheme(configPath) {
         const cached = require.cache[resolved];
         if (cached)
             bustRequireCache(require, cached, new Set());
-        const config = require(resolved);
+        const loaded = require(resolved);
+        // Node's require() of an ESM module returns the module namespace object
+        // (`{ __esModule: true, default: <the actual export>, ...named exports
+        // }`), not the export itself. Gated strictly on the .mjs extension --
+        // caught in independent review: a structural check ("does it have a
+        // `default` key") instead of this would silently misfire on a genuine
+        // CJS config that happens to export its own top-level `default` key
+        // (e.g. `module.exports = { default: "unrelated", theme: {...} }`),
+        // discarding the real theme with no error. .mjs is the only path that
+        // can ever produce this wrapped shape here: a `.js`/`.cjs` require()
+        // either returns the CJS export as-is, or -- inside a "type": "module"
+        // package -- throws ERR_REQUIRE_ESM before this line is ever reached
+        // (already handled by the catch block below, and already tested).
+        const config = resolved.endsWith(".mjs") && loaded && typeof loaded === "object" ? loaded.default : loaded;
         const extend = config?.theme?.extend ?? {};
         const result = {};
         if (extend.colors && typeof extend.colors === "object") {

package/dist/theme/themeValueParsers.js

@@ -1,4 +1,5 @@
-import { hexToRgb } from "../contrast/luminance.js";
+import { hexToRgb, rgbToHex } from "../contrast/luminance.js";
+import { oklchToRgb } from "../contrast/oklch.js";
 const SPACING_RE = /^-?[\d.]+(rem|px)$/;
 export function parseSpacingValue(value) {
     if (typeof value !== "string")
@@ -13,6 +14,19 @@ export function parseSpacingValue(value) {
 // 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.
+// Resolves a shade value to the plain hex string every downstream consumer
+// (resolveColorValue -> hexToRgb in checkContrast.ts/checkFocusIndicator.ts)
+// already assumes every palette entry is. A hex value is stored as-is; an
+// oklch() value is converted to hex once, here, so the conversion never has
+// to be repeated (or reimplemented) at every place a palette color gets
+// used. Anything else (rgb()/hsl()/var()/lab()/lch()/color()/...) is still
+// skipped -- out of scope for now, same "don't guess" precedent as before.
+function resolveShadeHex(shadeValue) {
+    if (hexToRgb(shadeValue) !== null)
+        return shadeValue;
+    const oklchRgb = oklchToRgb(shadeValue);
+    return oklchRgb ? rgbToHex(oklchRgb) : null;
+}
 export function parseColorScale(value) {
     if (typeof value !== "object" || value === null || Array.isArray(value))
         return null;
@@ -22,9 +36,10 @@ export function parseColorScale(value) {
             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;
+        const hex = resolveShadeHex(shadeValue);
+        if (hex === null)
+            continue; // neither hex nor oklch -- skip, don't guess
+        shades[shade] = hex;
     }
     return Object.keys(shades).length > 0 ? shades : null;
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "tailwind-a11y",
-  "version": "0.10.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.",
+  "version": "0.13.0",
+  "description": "Static analysis CLI that catches WCAG accessibility violations — color contrast, touch target size, and focus indicator removal/contrast — in Tailwind CSS class combinations before they ship.",
   "type": "module",
   "bin": {
     "tailwind-a11y": "./dist/cli.js"
@@ -61,6 +61,6 @@
     "esbuild": "^0.28.0",
     "tsx": "^4.19.0",
     "typescript": "^5.5.0",
-    "vitest": "^2.1.0"
+    "vitest": "^4.1.11"
   }
 }