Color Contrast Checker

A comprehensive WCAG 2.1 color contrast checker that validates text and background color combinations against accessibility standards (AA and AAA levels) and provides suggested fixes for failing contrasts.

Features

• ✅ WCAG 2.1 Compliance Checking: Validates against AA and AAA standards
• 📊 Accurate Contrast Ratios: Calculates precise contrast ratios using relative luminance
• 🎨 Multiple Color Formats: Supports hex (#RGB, #RRGGBB), rgb(), and rgba()
• 💡 Smart Suggestions: Automatically generates alternative colors that meet requirements
• 📏 Text Size Awareness: Different thresholds for normal and large text
• 🚀 CLI and Library: Use as a command-line tool or integrate into your projects

Installation

npm install

Usage

Command Line Interface

node cli.js <foreground> <background> [options]

Options

• --level: WCAG level to check (AA or AAA, default: AA)
• --size: Font size (normal or large, default: normal)
• --help: Show help message

Examples

# Check black text on white background
node cli.js "#000000" "#ffffff"

# Check with AAA level requirement
node cli.js "#333" "#fff" --level AAA

# Check large text
node cli.js "rgb(0,0,0)" "rgb(255,255,255)" --size large

# Get suggestions for failing contrast
node cli.js "#999999" "#ffffff"

As a Library

const { checkContrast, getContrastRatio } = require('./index.js');

// Check contrast and get suggestions
const result = checkContrast('#999999', '#ffffff', { 
  level: 'AA', 
  fontSize: 'normal' 
});

console.log(`Contrast Ratio: ${result.ratio}:1`);
console.log(`AA: ${result.AA ? 'PASS' : 'FAIL'}`);
console.log(`AAA: ${result.AAA ? 'PASS' : 'FAIL'}`);

if (result.suggestions.length > 0) {
  console.log('Suggestions:', result.suggestions);
}

// Get just the contrast ratio
const ratio = getContrastRatio('#000000', '#ffffff');
console.log(`Ratio: ${ratio}:1`); // 21:1

WCAG Standards

Contrast Ratio Requirements

Level	Normal Text	Large Text
AA	4.5:1	3:1
AAA	7:1	4.5:1

Large text is defined as:

• 14pt (18.66px) and bold or larger
• 18pt (24px) or larger

Understanding Contrast Ratios

• 21:1 - Maximum contrast (black on white)
• 7:1 - AAA normal text requirement
• 4.5:1 - AA normal text requirement
• 3:1 - AA large text requirement
• 1:1 - No contrast (same color)

API Reference

checkContrast(foreground, background, options)

Main function to check color contrast and get suggestions.

Parameters:

• foreground (string): Foreground color (text color)
• background (string): Background color
• options (object, optional):
  • level (string): 'AA' or 'AAA' (default: 'AA')
  • fontSize (string): 'normal' or 'large' (default: 'normal')

Returns: Object with:

• ratio (number): Contrast ratio
• AA (boolean): Passes AA level
• AAA (boolean): Passes AAA level
• AAThreshold (number): Required AA ratio
• AAAThreshold (number): Required AAA ratio
• suggestions (array): Alternative colors that meet requirements

getContrastRatio(color1, color2)

Calculate contrast ratio between two colors.

Parameters:

• color1 (string): First color
• color2 (string): Second color

Returns: Number (contrast ratio)

parseColor(color)

Parse color string to RGB values.

Parameters:

• color (string): Color in hex, rgb, or rgba format

Returns: Object with r, g, b properties (0-255)

getRelativeLuminance(rgb)

Calculate relative luminance according to WCAG 2.1 formula.

Parameters:

• rgb (object): Object with r, g, b properties

Returns: Number (0-1)

Color Format Support

Hex Colors

"#000000"  // 6-digit hex
"#000"     // 3-digit hex (expanded to 6-digit)

RGB Colors

"rgb(0, 0, 0)"
"rgb(255, 255, 255)"

RGBA Colors

"rgba(0, 0, 0, 1)"
"rgba(255, 255, 255, 0.5)"  // Alpha channel is ignored

Testing

Run the test suite:

npm test

The test suite covers:

• Color parsing (hex, rgb, rgba)
• Relative luminance calculations
• Contrast ratio calculations
• WCAG compliance checking
• Suggestion generation
• Edge cases and error handling

Examples

Example 1: Passing Contrast

$ node cli.js "#000000" "#ffffff"

============================================================
COLOR CONTRAST CHECK RESULTS
============================================================

Foreground: #000000
Background: #ffffff
Font Size:  normal

Contrast Ratio: 21:1

WCAG Compliance:
  AA  (4.5:1):  ✓ PASS
  AAA (7:1):  ✓ PASS
============================================================

Example 2: Failing Contrast with Suggestions

$ node cli.js "#999999" "#ffffff" --level AA

============================================================
COLOR CONTRAST CHECK RESULTS
============================================================

Foreground: #999999
Background: #ffffff
Font Size:  normal

Contrast Ratio: 2.85:1

WCAG Compliance:
  AA  (4.5:1):  ✗ FAIL
  AAA (7:1):  ✗ FAIL

SUGGESTED FIXES:

1. Make foreground darker:
   Color: #767676
   New Ratio: 4.54:1

2. Make background darker:
   Color: #323232
   New Ratio: 4.5:1

============================================================

Resources

• WCAG 2.1 Guidelines
• Understanding Contrast
• WebAIM Contrast Checker

License

MIT License - see LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Author

Max Base