tailwind-a11y 0.9.0 → 0.12.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 must meet WCAG 2.5.5 (AAA, 44x44px), not just 2.5.8 (AA, 24x24px)
+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
@@ -56,6 +56,8 @@ Exits `1` on violations — safe to use as a CI gate.
 | 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 — 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

@@ -8,7 +8,9 @@ import { checkContrast, checkContrastValueSkips } from "./rules/checkContrast.js
 import { extractTouchTargetChecks, extractTouchTargetSkips } from "./parser/extractTouchTargets.js";
 import { checkTouchTargets } from "./rules/checkTouchTarget.js";
 import { extractFocusIndicatorChecks } from "./parser/extractFocusIndicators.js";
-import { checkFocusIndicators } from "./rules/checkFocusIndicator.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).
@@ -26,6 +28,15 @@ function formatViolation(v) {
         }
         case "focus-indicator":
             return `${v.line}: <${v.tagName}> removes the focus outline (${v.removalClass}) with no visible replacement (focus:ring-*/border-*/shadow-*/bg-*/outline-*)`;
+        case "focus-contrast": {
+            const sc = v.level === "AAA" ? "2.4.13" : "1.4.11";
+            const base = `${v.line}: <${v.tagName}> focus indicator ${v.indicatorClass} on ${v.bgClass} — ratio ${v.ratio.toFixed(2)}, needs ${v.required} (WCAG ${sc})`;
+            return v.thicknessPx !== undefined
+                ? `${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) {
@@ -79,7 +90,8 @@ async function main() {
         try {
             const code = readFileSync(absPath, "utf8");
             const contrastChecks = extractChecks(code, file);
-            violations.push(...checkContrast(contrastChecks, palette), ...checkTouchTargets(extractTouchTargetChecks(code, file, spacing), strict), ...checkFocusIndicators(extractFocusIndicatorChecks(code, file)));
+            const focusChecks = extractFocusIndicatorChecks(code, file);
+            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,14 +3,20 @@
 const HELP_TEXT = `Usage: tailwind-a11y [options] [<glob>...]
 
 Static analysis for Tailwind CSS accessibility violations -- color contrast,
-touch target size, and focus indicator removal.
+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
   -V, --version      Print the version number
   -h, --help         Print this help message
       --strict       Touch targets must meet WCAG 2.5.5 (AAA, 44x44px)
-                      instead of the default 2.5.8 (AA, 24x24px)
+                      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);
+                      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

@@ -3,7 +3,9 @@ export { checkContrast, checkContrastValueSkips, suggestContrastFix, type Contra
 export { extractTouchTargetChecks, extractTouchTargetSkips, type TouchTargetCheck, type TouchTargetSkip } from "./parser/extractTouchTargets.js";
 export { checkTouchTargets, type TouchTargetViolation } from "./rules/checkTouchTarget.js";
 export { extractFocusIndicatorChecks, type FocusIndicatorCheck } from "./parser/extractFocusIndicators.js";
-export { checkFocusIndicators, type FocusIndicatorViolation } from "./rules/checkFocusIndicator.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

@@ -3,7 +3,9 @@ export { checkContrast, checkContrastValueSkips, suggestContrastFix } from "./ru
 export { extractTouchTargetChecks, extractTouchTargetSkips } from "./parser/extractTouchTargets.js";
 export { checkTouchTargets } from "./rules/checkTouchTarget.js";
 export { extractFocusIndicatorChecks } from "./parser/extractFocusIndicators.js";
-export { checkFocusIndicators } from "./rules/checkFocusIndicator.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/extractFocusIndicators.d.ts

@@ -3,5 +3,7 @@ export interface FocusIndicatorCheck {
     line: number;
     tagName: string;
     focusClasses: string[];
+    bgClass?: string | null;
+    bgSource?: "self" | "parent" | null;
 }
 export declare function extractFocusIndicatorChecks(code: string, filePath: string): FocusIndicatorCheck[];

package/dist/parser/extractFocusIndicators.js

@@ -1,6 +1,7 @@
 import * as t from "@babel/types";
 import { getStaticClassName, parseJSX, traverse } from "./babelInterop.js";
 import { isInteractiveElement } from "./isInteractiveElement.js";
+import { lastColorToken } from "./extractClasses.js";
 function focusScopedClasses(className) {
     return className
         .split(/\s+/)
@@ -27,11 +28,30 @@ export function extractFocusIndicatorChecks(code, filePath) {
             const focusClasses = focusScopedClasses(className);
             if (focusClasses.length === 0)
                 return; // nothing under focus:/focus-visible: — not a candidate
+            const ownBg = lastColorToken(className, "bg");
+            let bgClass = ownBg;
+            let bgSource = ownBg ? "self" : null;
+            if (!bgClass) {
+                // Only the immediate JSX parent, same limit as extractClasses.ts's
+                // own contrast resolution — no deeper ancestor walk, no
+                // cross-component resolution.
+                const parentNode = path.parentPath?.node;
+                if (parentNode && t.isJSXElement(parentNode)) {
+                    const parentClassName = getStaticClassName(parentNode.openingElement.attributes);
+                    const parentBg = parentClassName ? lastColorToken(parentClassName, "bg") : null;
+                    if (parentBg) {
+                        bgClass = parentBg;
+                        bgSource = "parent";
+                    }
+                }
+            }
             checks.push({
                 file: filePath,
                 line: opening.loc?.start.line ?? 0,
                 tagName: t.isJSXIdentifier(opening.name) ? opening.name.name : "onClick-element",
                 focusClasses,
+                bgClass,
+                bgSource,
             });
         },
     });

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

@@ -1,7 +1,10 @@
 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);
+    // outline/ring are here for checkFocusIndicator.ts's non-text-contrast
+    // check (WCAG 1.4.11/2.4.13) -- same palette/arbitrary-hex/semantic-color
+    // resolution as text/bg, just a different utility prefix.
+    const match = /^(?:text|bg|outline|ring)-(.+)$/.exec(utilityClass);
     if (!match)
         return null;
     const token = match[1];

package/dist/rules/checkFocusIndicator.d.ts

@@ -1,4 +1,5 @@
 import type { FocusIndicatorCheck } from "../parser/extractFocusIndicators.js";
+import type { Palette } from "../theme/defaultPalette.js";
 export interface FocusIndicatorViolation {
     type: "focus-indicator";
     file: string;
@@ -7,3 +8,17 @@ export interface FocusIndicatorViolation {
     removalClass: string;
 }
 export declare function checkFocusIndicators(checks: FocusIndicatorCheck[]): FocusIndicatorViolation[];
+export interface FocusContrastViolation {
+    type: "focus-contrast";
+    file: string;
+    line: number;
+    tagName: string;
+    indicatorClass: string;
+    bgClass: string;
+    ratio: number;
+    required: number;
+    level: "AA" | "AAA";
+    thicknessPx?: number;
+    requiredThicknessPx?: number;
+}
+export declare function checkFocusContrast(checks: FocusIndicatorCheck[], strict?: boolean, palette?: Palette): FocusContrastViolation[];

package/dist/rules/checkFocusIndicator.js

@@ -1,4 +1,7 @@
 import { COLOR_TOKEN } from "../parser/extractClasses.js";
+import { resolveColorValue } from "./checkContrast.js";
+import { contrastRatio, hexToRgb } from "../contrast/luminance.js";
+import { defaultPalette } from "../theme/defaultPalette.js";
 const REMOVAL_BASE = "outline-none";
 // Utilities that match the "replacement" shape but are semantically no-ops —
 // the same failure mode as bg-opacity-50 masking a real color match: a
@@ -97,3 +100,109 @@ export function checkFocusIndicators(checks) {
     }
     return violations;
 }
+// Flat non-text threshold -- not luminance.ts's requiredRatio()/meetsWCAG(),
+// which model the text-specific large-text/small-text AA/AAA table that
+// doesn't apply to UI-component contrast.
+const NON_TEXT_MIN_RATIO = 3;
+// WCAG 2.4.13's "2 CSS pixel thick perimeter" -- verified against a real
+// tailwindcss@4.3.3 compile (see CLAUDE.md) rather than assumed.
+const FOCUS_INDICATOR_MIN_THICKNESS_PX = 2;
+// outline-{0,1,2,4,8} / ring-{0,1,2,4,8} -- Tailwind's fixed width scale for
+// both utilities, verified against a real build. Bare `ring`/`outline` (no
+// digit) is deliberately NOT in this map: verified via that same build that
+// it resolves to 1px in Tailwind v4, but v3's bare `ring` default is
+// documented elsewhere as 3px -- a real cross-version difference this tool
+// 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) {
+    let found = null;
+    for (const raw of focusClasses) {
+        const base = raw.slice(raw.lastIndexOf(":") + 1);
+        const match = /^(?:outline|ring)-(.+)$/.exec(base);
+        if (!match)
+            continue;
+        const rest = match[1];
+        if (!COLOR_TOKEN.test(rest))
+            continue;
+        const scaleName = /^([a-z]+)-\d/.exec(rest)?.[1];
+        if (scaleName === "opacity")
+            continue;
+        found = base;
+    }
+    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) {
+    let found = null;
+    for (const raw of focusClasses) {
+        const base = raw.slice(raw.lastIndexOf(":") + 1);
+        const match = /^(?:outline|ring)-(.+)$/.exec(base);
+        if (!match)
+            continue;
+        const token = match[1];
+        if (token in WIDTH_SCALE) {
+            found = WIDTH_SCALE[token];
+            continue;
+        }
+        const arbitrary = /^\[(\d+(?:\.\d+)?)px\]$/.exec(token);
+        if (arbitrary)
+            found = Number(arbitrary[1]);
+    }
+    return found;
+}
+export function checkFocusContrast(checks, strict = false, palette = defaultPalette) {
+    const violations = [];
+    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)
+            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)
+            continue;
+        const rawIndicatorClass = check.focusClasses.find((raw) => raw.slice(raw.lastIndexOf(":") + 1) === indicatorBase);
+        violations.push({
+            type: "focus-contrast",
+            file: check.file,
+            line: check.line,
+            tagName: check.tagName,
+            indicatorClass: rawIndicatorClass,
+            bgClass: check.bgClass,
+            ratio,
+            required: NON_TEXT_MIN_RATIO,
+            level: thicknessFails ? "AAA" : "AA",
+            ...(thicknessFails && thicknessPx !== null
+                ? { thicknessPx, requiredThicknessPx: FOCUS_INDICATOR_MIN_THICKNESS_PX }
+                : {}),
+        });
+    }
+    return violations;
+}

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/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.9.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.12.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"
   }
 }