theunwindfront/tailwindcss-contrast-checker

A build-time CLI tool to catch accessibility (a11y) violations by checking Tailwind CSS text and background color combinations for WCAG contrast ratios.

v1.0.0 2026-06-23 13:05 UTC

Requires

• php: ^8.2
• illuminate/support: ^10.0|^11.0|^12.0|^13.0

MIT

• Sagar Pansuriya

README

A fast, lightweight CLI tool that scans your codebase for accessibility (a11y) violations by checking Tailwind CSS text and background color combinations against WCAG 2.1 contrast standards.

The Problem

Accessibility (a11y) is often treated as an afterthought in rapid UI development. Developers frequently combine text and background utility classes (like bg-gray-300 text-white) that fail WCAG contrast ratios, making the application illegible for visually impaired users. Catching these issues manually or relying on browser extensions is slow and error-prone.

The Solution

This CLI tool scans your HTML, Vue, React, Svelte, or Blade templates, extracts the Tailwind utility classes, and mathematically calculates the relative luminance of overlapping background and text color pairs. It warns you in the terminal before you ship to production.

# Example output in terminal
src/components/Button.jsx
  Line 12: FAIL [ Aa ] bg-gray-300 + text-white -> Contrast Ratio: 1.6:1 (Needs 4.5:1 for AA)

Installation

Install the package via Composer (for Laravel integration) and NPM:

composer require theunwindfront/tailwindcss-contrast-checker
npm install -D @theunwindfront/tailwindcss-contrast-checker

Usage Guide

You can run the checker manually or add it to your CI/CD pipeline or build scripts.

npx tailwind-contrast "resources/views/**/*.blade.php"

Adding to package.json

"scripts": {
  "lint:a11y": "tailwind-contrast \"src/**/*.{html,js,jsx,ts,tsx,vue}\""
}

Features

• 🚀 Framework Agnostic: Scans HTML, JS, JSX, TS, TSX, Vue, Svelte, and Blade files.
• 🎨 Smart Defaults: Supports standard Tailwind CSS v3 and v4 default colors.
• 📐 Arbitrary Values: Supports arbitrary hex color values (e.g., bg-[#ff0000]).
• ⚡ High Performance: Powered by fast-glob for rapid codebase scanning.

👥 Credits

• Sagar Pansuriya - Lead Creator & Developer

🤝 Support

For questions or issues, contact [e-mail]

📄 License

The MIT License (MIT). Please see License File for more information.