ContrastCheck

Check color contrast accessibility on websites using real browser rendering.

Install

npm install -g contrastcheck
# or
bun install -g contrastcheck

Or run directly with npx:

npx contrastcheck <url>

Usage

Quick check

contrastcheck https://example.com

The tool accepts URLs, local HTML files, or any file path:

contrastcheck ./index.html
contrastcheck https://localhost:3000
contrastcheck ../dist/index.html

Commands

Command	Description
check <url>	Check a URL for contrast issues
wizard	Interactive setup wizard
compare <fg> <bg>	Compare contrast between two colors
login <url>	Save browser session for authenticated scanning
help	Show help

Check options

Option	Default	Description
-o, --output <path>	./contrast-report.html	Output path for HTML report
--no-headless	headless	Show browser window during scan
-w, --viewport <wxh>	1280x720	Viewport size
--dark-mode	false	Force dark mode preference
-f, --format <type>	html	Output format: html, json, compact
--json	false	Output JSON to stdout instead of HTML report
-q, --quiet	false	Minimal output (no spinners, progress bars)
--all	false	Include passing elements in output (default shows failures only)
--watch	false	Watch for file changes and re-check automatically
--threshold <level>	aa	Violation threshold: critical (ratio < 3), aa (< 4.5), strict (< 7)
--ci	false	CI mode: enables --json --quiet --yes --no-screenshots
--no-screenshots	false	Skip capturing element screenshots (faster, smaller output)
--no-exclude-devtools	false	Include devtools panels in the scan
--exclude-selectors	[]	Additional CSS selectors to exclude (space-separated)
--auth-file <path>	—	Path to Playwright auth state file (saved via login)
--include-auth-pages	false	Include auth-protected pages in crawl (requires --auth-file)
--crawl	false	Automatically discover and scan linked pages
--depth <number>	1	How many levels of links to follow
--max-pages <number>	10	Maximum number of pages to scan
-y, --yes	false	Skip confirmation prompt and scan all discovered pages

Examples

# Generate an HTML report
contrastcheck https://example.com -o report.html

# Check in dark mode with mobile viewport
contrastcheck https://example.com --dark-mode -w 390x844

# Output JSON to stdout (failures only by default)
contrastcheck https://example.com --json
# or
contrastcheck https://example.com -f json

# Include all results (passes + failures)
contrastcheck https://example.com -f json --all

# Watch a local file for changes
contrastcheck ./index.html --watch

# Run with visible browser window
contrastcheck https://example.com --no-headless

# Include devtools panels in the scan (default excludes them)
contrastcheck https://example.com --no-exclude-devtools

# Exclude additional custom selectors (space-separated)
contrastcheck https://example.com --exclude-selectors ".my-overlay" "#debug-panel"

# Set violation threshold
contrastcheck https://example.com --threshold strict

# Scan authenticated pages
contrastcheck login https://localhost:3000
contrastcheck https://localhost:3000 --auth-file ~/.contrastcheck/auth.json --include-auth-pages

# Scan with CI-friendly output
contrastcheck https://example.com --ci

# Crawl and scan linked pages
contrastcheck https://example.com --crawl --depth 2 --max-pages 20

# Minimal output for CI
contrastcheck https://example.com -q -f compact

Config file

Skip repeating flags by creating a .contrastcheckrc or contrastcheck.config.json in your project root:

{
  "authFile": "~/.contrastcheck/localhost_3000-auth.json",
  "includeAuthPages": true,
  "threshold": "aa",
  "excludeSelectors": [".TanStackRouterDevtools", ".sr-only"],
  "quiet": true,
  "json": true,
  "viewport": "1280x720"
}

The config file is auto-discovered from the current directory (walking up). CLI flags always override config values.

Supported config keys: authFile, includeAuthPages, threshold, excludeSelectors, excludeDevtools, viewport, darkMode, headless, format, json, quiet, noScreenshots, output.

Interactive wizard

contrastcheck wizard

Guides you through URL, viewport, dark mode, headless, and output options.

How it works

1. Launch a real browser (Playwright Chromium) and load the target page
2. Extract rendered colors for every visible text element, accounting for CSS, inline styles, inheritance, transparency, and background images
3. Calculate WCAG contrast ratios using the standard relative luminance formula
4. Flag violations against AA and AAA thresholds:
   • Normal text: AA ≥ 4.5, AAA ≥ 7
   • Large text (18.66px+ bold or 24px+): AA ≥ 3, AAA ≥ 4.5
5. Suggest fixes by shifting foreground colors to meet the failing threshold
6. Generate a report with screenshots of each violation

Output formats

By default, all formats show only failures to keep output focused. Use --all to include passing elements.

• HTML (default): Report with violation list, screenshots, and fix suggestions
• JSON: Machine-readable output with analyzed pairs and metadata
• Compact: One-line summary for CI/logs