tailwind-a11y 0.4.0 → 0.5.1

package/README.md

@@ -50,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 |
 
@@ -63,7 +63,10 @@ When a case can't be resolved with confidence, it's skipped rather than guessed:
 - A full `theme.colors`/`theme.spacing` replacement, `.mjs`/`.ts` configs, or
   Tailwind v4's CSS-based `@theme` config (only `theme.extend` in a `.js`/`.cjs`
   config is read — see [CLAUDE.md](./CLAUDE.md))
-- Color + opacity shorthand (`bg-white/50`)
+- 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/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/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/rules/checkContrast.js

@@ -1,4 +1,4 @@
-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, palette = defaultPalette) {
     const match = /^(?:text|bg)-(.+)$/.exec(utilityClass);
@@ -19,16 +19,50 @@ export function resolveColorValue(utilityClass, palette = defaultPalette) {
         return null;
     return palette[scale]?.[shade] ?? null; // unknown/custom color — skip
 }
+// 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, palette);
         const bgHex = resolveColorValue(check.bgColorClass, palette);
-        if (!textHex || !bgHex)
+        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
@@ -50,18 +84,22 @@ export function checkContrast(checks, palette = defaultPalette) {
     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.
+// 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 match = TEXT_SCALE_SHADE_RE.exec(textClass);
+    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 = palette[scale];
     if (!shades?.[shade])
@@ -75,34 +113,64 @@ export function suggestContrastFix(textClass, bgClass, required, palette = defau
         .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.
+// 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, palette);
         const bgHex = resolveColorValue(check.bgColorClass, palette);
-        if (textHex && bgHex)
+        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.js

@@ -73,7 +73,14 @@ function bustRequireCache(require, mod, seen) {
 // spacing returns {}, which callers must not treat as an error.
 export function loadCustomTheme(configPath) {
     try {
-        const require = createRequire(import.meta.url);
+        // createRequire is anchored to the config file itself, NOT import.meta.url:
+        // esbuild's CJS output (the VS Code and GitHub Action bundles) rewrites
+        // import.meta to an empty object, so createRequire(import.meta.url) throws
+        // inside a bundle -- and this function's own try/catch would swallow that
+        // into a silent "no config found" fallback. configPath is documented as
+        // absolute, which is exactly what createRequire needs as an anchor, and it
+        // also makes relative require()s inside the config resolve correctly.
+        const require = createRequire(configPath);
         const resolved = require.resolve(configPath);
         const cached = require.cache[resolved];
         if (cached)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tailwind-a11y",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "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": {
@@ -58,6 +58,7 @@
   "devDependencies": {
     "@types/babel__traverse": "^7.20.6",
     "@types/node": "^22.0.0",
+    "esbuild": "^0.28.0",
     "tsx": "^4.19.0",
     "typescript": "^5.5.0",
     "vitest": "^2.1.0"