tailwind-a11y 0.12.0 → 0.13.1

package/README.md

@@ -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`).
 

package/dist/parser/extractClasses.js

@@ -26,16 +26,28 @@ const NON_COLOR_SCALE_NAMES = new Set(["opacity", "linear", "conic"]);
 export function lastColorToken(className, prefix) {
     let found = null;
     for (const raw of className.split(/\s+/).filter(Boolean)) {
-        const base = raw.slice(raw.lastIndexOf(":") + 1); // strip hover:/dark:/md: variants
-        if (!base.startsWith(`${prefix}-`))
+        // Variant-scoped classes (hover:/dark:/md:/...) are skipped entirely,
+        // not stripped down to their base utility -- fixed after independent
+        // testing found a real false negative: `bg-white dark:bg-gray-900`
+        // with `text-gray-300` silently passed, because stripping the `dark:`
+        // prefix let it participate in last-token-wins as if it were the real,
+        // always-rendered resting-state background, when `dark:bg-gray-900`
+        // only ever applies under a completely different condition. Mirrors
+        // `extractTouchTargets.ts`'s `lastSizeToken`, which already excludes
+        // any variant-scoped size token from resting-state resolution the same
+        // way (`if (raw.includes(":")) continue;`) -- this had no equivalent
+        // guard for colors.
+        if (raw.includes(":"))
             continue;
-        const rest = base.slice(prefix.length + 1);
+        if (!raw.startsWith(`${prefix}-`))
+            continue;
+        const rest = raw.slice(prefix.length + 1);
         if (!COLOR_TOKEN.test(rest))
             continue;
         const scaleName = /^([a-z]+)-\d/.exec(rest)?.[1];
         if (scaleName && NON_COLOR_SCALE_NAMES.has(scaleName))
             continue;
-        found = base;
+        found = raw;
     }
     return found;
 }

package/dist/rules/checkFocusIndicator.js

@@ -115,23 +115,30 @@ const FOCUS_INDICATOR_MIN_THICKNESS_PX = 2;
 // can't currently distinguish, so bare ring/outline contributes color (if
 // paired with an explicit color utility) but never a thickness value.
 const WIDTH_SCALE = { "0": 0, "1": 1, "2": 2, "4": 4, "8": 8 };
-// Near-duplicate of extractClasses.ts's lastColorToken, not a call to it:
-// that function takes a single prefix ("text" | "bg") and this needs
-// last-token-wins across *two* prefixes (outline-*, ring-*) in one pass, so
-// whichever was actually written last in the class list wins regardless of
-// which utility it is. Reuses COLOR_TOKEN (the one shared "is this
-// color-shaped" test) and only excludes the "opacity" scale name locally --
-// lastColorToken's full NON_COLOR_SCALE_NAMES set also excludes
-// "linear"/"conic", but those are bg-gradient-angle utilities with no
-// outline-*/ring-* equivalent, so they can never appear here.
-function lastIndicatorColorToken(focusClasses) {
+// Last-token-wins WITHIN one prefix only. Fixed after independent testing
+// found a real bug: the original version raced outline-* against ring-*
+// in one shared last-token-wins slot, so an element with BOTH a passing
+// outline-* and a failing ring-* (or vice versa) got a verdict that
+// depended purely on which was written later in the class string -- even
+// though outline-*/ring-* are two independent CSS mechanisms
+// (outline-color/-width vs. box-shadow) that both render simultaneously
+// regardless of order (verified against a real Tailwind v4 build).
+// Last-token-wins is still correct *within* a single prefix (e.g.
+// `outline-red-500 outline-blue-600` really does render as blue-600, the
+// later declaration winning in CSS) -- only racing the two prefixes
+// against each other was wrong. Reuses COLOR_TOKEN (the shared
+// "is this color-shaped" test) and only excludes the "opacity" scale name
+// locally -- extractClasses.ts's lastColorToken's full NON_COLOR_SCALE_NAMES
+// set also excludes "linear"/"conic", but those are bg-gradient-angle
+// utilities with no outline-*/ring-* equivalent, so they can never appear
+// here.
+function lastColorTokenForIndicator(focusClasses, prefix) {
     let found = null;
     for (const raw of focusClasses) {
         const base = raw.slice(raw.lastIndexOf(":") + 1);
-        const match = /^(?:outline|ring)-(.+)$/.exec(base);
-        if (!match)
+        if (!base.startsWith(`${prefix}-`))
             continue;
-        const rest = match[1];
+        const rest = base.slice(prefix.length + 1);
         if (!COLOR_TOKEN.test(rest))
             continue;
         const scaleName = /^([a-z]+)-\d/.exec(rest)?.[1];
@@ -141,19 +148,18 @@ function lastIndicatorColorToken(focusClasses) {
     }
     return found;
 }
-// Same last-token-wins-across-both-prefixes shape as above, but for width:
-// only an enumerated outline-{N}/ring-{N} or an arbitrary [Npx] sets a
-// thickness. A color token (ring-blue-400), ring-offset-*, ring-inset, etc.
-// don't match either shape and are silently ignored here -- they're a
-// different utility's job (color, offset, inset), not this one's.
-function lastIndicatorThicknessPx(focusClasses) {
+// Same per-prefix last-token-wins shape as above, but for width: only an
+// enumerated outline-{N}/ring-{N} or an arbitrary [Npx] sets a thickness.
+// A color token (ring-blue-400), ring-offset-*, ring-inset, etc. don't
+// match either shape and are silently ignored here -- they're a different
+// utility's job (color, offset, inset), not this one's.
+function thicknessTokenForIndicator(focusClasses, prefix) {
     let found = null;
     for (const raw of focusClasses) {
         const base = raw.slice(raw.lastIndexOf(":") + 1);
-        const match = /^(?:outline|ring)-(.+)$/.exec(base);
-        if (!match)
+        if (!base.startsWith(`${prefix}-`))
             continue;
-        const token = match[1];
+        const token = base.slice(prefix.length + 1);
         if (token in WIDTH_SCALE) {
             found = WIDTH_SCALE[token];
             continue;
@@ -169,26 +175,44 @@ export function checkFocusContrast(checks, strict = false, palette = defaultPale
     for (const check of checks) {
         if (!check.bgClass)
             continue; // no resolvable background — skip, not a guess
-        const indicatorBase = lastIndicatorColorToken(check.focusClasses);
-        if (!indicatorBase)
-            continue; // no explicit outline-*/ring-* color — out of scope, see CLAUDE.md
-        const indicatorHex = resolveColorValue(indicatorBase, palette);
         const bgHex = resolveColorValue(check.bgClass, palette);
-        if (!indicatorHex || !bgHex)
+        const bgRgb = bgHex ? hexToRgb(bgHex) : null;
+        if (!bgRgb)
             continue; // custom theme color / unsupported arbitrary value — skip
-        const indicatorRgb = hexToRgb(indicatorHex);
-        const bgRgb = hexToRgb(bgHex);
-        if (!indicatorRgb || !bgRgb)
-            continue;
-        const ratio = contrastRatio(indicatorRgb, bgRgb);
-        const contrastFails = ratio < NON_TEXT_MIN_RATIO;
-        let thicknessPx = null;
-        if (strict)
-            thicknessPx = lastIndicatorThicknessPx(check.focusClasses);
-        const thicknessFails = strict && thicknessPx !== null && thicknessPx < FOCUS_INDICATOR_MIN_THICKNESS_PX;
-        if (!contrastFails && !thicknessFails)
+        // outline-* and ring-* are evaluated as independent candidates, not
+        // raced against each other -- both are real, simultaneously-rendering
+        // mechanisms (see lastColorTokenForIndicator's comment for why), so an
+        // element can have zero, one, or both present at once.
+        const candidates = [];
+        for (const prefix of ["outline", "ring"]) {
+            const indicatorBase = lastColorTokenForIndicator(check.focusClasses, prefix);
+            if (!indicatorBase)
+                continue; // this mechanism isn't in use on this element
+            const indicatorHex = resolveColorValue(indicatorBase, palette);
+            const indicatorRgb = indicatorHex ? hexToRgb(indicatorHex) : null;
+            if (!indicatorRgb)
+                continue; // custom theme color / unsupported arbitrary value — skip this candidate
+            const ratio = contrastRatio(indicatorRgb, bgRgb);
+            const contrastFails = ratio < NON_TEXT_MIN_RATIO;
+            let thicknessPx = null;
+            if (strict)
+                thicknessPx = thicknessTokenForIndicator(check.focusClasses, prefix);
+            const thicknessFails = strict && thicknessPx !== null && thicknessPx < FOCUS_INDICATOR_MIN_THICKNESS_PX;
+            candidates.push({ indicatorBase, ratio, contrastFails, thicknessPx, thicknessFails });
+        }
+        if (candidates.length === 0)
+            continue; // no resolvable outline-*/ring-* color at all
+        // A user only needs ONE sufficiently visible (and, under strict,
+        // sufficiently thick) focus indicator to perceive the focus state --
+        // if any present candidate fully passes, this element is compliant
+        // even if another present indicator independently would have failed.
+        const allFail = candidates.every((c) => c.contrastFails || c.thicknessFails);
+        if (!allFail)
             continue;
-        const rawIndicatorClass = check.focusClasses.find((raw) => raw.slice(raw.lastIndexOf(":") + 1) === indicatorBase);
+        // More than one candidate present and both fail -- report the worst
+        // (lowest-ratio) offender.
+        const worst = candidates.reduce((a, b) => (b.ratio < a.ratio ? b : a));
+        const rawIndicatorClass = check.focusClasses.find((raw) => raw.slice(raw.lastIndexOf(":") + 1) === worst.indicatorBase);
         violations.push({
             type: "focus-contrast",
             file: check.file,
@@ -196,11 +220,11 @@ export function checkFocusContrast(checks, strict = false, palette = defaultPale
             tagName: check.tagName,
             indicatorClass: rawIndicatorClass,
             bgClass: check.bgClass,
-            ratio,
+            ratio: worst.ratio,
             required: NON_TEXT_MIN_RATIO,
-            level: thicknessFails ? "AAA" : "AA",
-            ...(thicknessFails && thicknessPx !== null
-                ? { thicknessPx, requiredThicknessPx: FOCUS_INDICATOR_MIN_THICKNESS_PX }
+            level: worst.thicknessFails ? "AAA" : "AA",
+            ...(worst.thicknessFails && worst.thicknessPx !== null
+                ? { thicknessPx: worst.thicknessPx, requiredThicknessPx: FOCUS_INDICATOR_MIN_THICKNESS_PX }
                 : {}),
         });
     }

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/package.json

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