| name | color-contrast |
| description | Validates WCAG 2.1 contrast ratios and generates accessible color pairings. Use when checking accessibility compliance, fixing contrast issues, or selecting text/background combinations for AA or AAA levels. |
Color Contrast Checker
Overview
Validate and generate accessible color combinations that meet WCAG 2.1 contrast requirements. Check existing palettes or find compliant alternatives for any color pair.
When to Use
- Validating a color palette for accessibility
- Finding accessible text colors for a background
- Checking if brand colors meet WCAG standards
- Generating accessible color pairings from tokens
Quick Reference: WCAG Requirements
| Level | Normal Text | Large Text | UI Components |
|---|
| AA | 4.5:1 | 3:1 | 3:1 |
| AAA | 7:1 | 4.5:1 | 4.5:1 |
Large text: 18pt (24px) regular or 14pt (18.5px) bold
The Process
- Get colors: Ask for foreground and background colors (hex, rgb, oklch, hsl)
- Calculate ratio: Compute relative luminance and contrast ratio
- Report compliance: Show AA/AAA pass/fail for text sizes
- If failing: Suggest closest compliant alternatives
- Batch mode: If given a palette, check all combinations
Contrast Ratio Scale
| Ratio | Rating | Suitable For |
|---|
| 21:1 | Maximum | Black on white |
| 7:1+ | Excellent | AAA all text |
| 4.5:1+ | Good | AA normal text, AAA large |
| 3:1+ | Minimum | AA large text, UI components |
| < 3:1 | Failing | Decorative only |
Output Formats
Single Pair Check:
Contrast Check: #1a1a1a on #ffffff
Ratio: 16.1:1
✓ AA Normal Text (4.5:1)
✓ AA Large Text (3:1)
✓ AAA Normal Text (7:1)
✓ AAA Large Text (4.5:1)
✓ UI Components (3:1)
Verdict: Passes all WCAG 2.1 criteria
Failing Pair with Suggestions:
Contrast Check: #6b7280 on #ffffff
Ratio: 4.0:1
✓ AA Large Text (3:1)
✗ AA Normal Text (4.5:1) - needs 4.5:1
✗ AAA Normal Text (7:1)
✓ UI Components (3:1)
Suggested fixes:
- Darken foreground to #5b6370 for AA (4.5:1)
- Darken foreground to #3d4351 for AAA (7:1)
Palette Matrix:
Color Contrast Matrix (AA Normal Text = 4.5:1)
white gray-100 gray-900 primary
white - 1.1 16.1 5.2
gray-100 1.1 - 14.5 4.7
gray-900 16.1 14.5 - 3.1
primary 5.2 4.7 3.1 -
Legend: ✓ = 4.5:1+ | ⚠ = 3:1-4.5:1 | ✗ = <3:1
CSS with Accessible Pairs:
:root {
--text-on-light: #1f2937;
--text-muted-on-light: #4b5563;
--text-on-dark: #f9fafb;
--text-muted-on-dark: #d1d5db;
--text-on-primary: #ffffff;
}
Algorithm
Relative Luminance (L):
For each RGB channel (0-255):
1. Normalize: value / 255
2. If ≤ 0.03928: channel / 12.92
3. Else: ((channel + 0.055) / 1.055) ^ 2.4
L = 0.2126 * R + 0.7152 * G + 0.0722 * B
Contrast Ratio:
ratio = (L1 + 0.05) / (L2 + 0.05)
where L1 is lighter, L2 is darker
Common Patterns
Accessible grays on white:
| Gray | Hex | Ratio | Use |
|---|
| 600 | #4b5563 | 7.2:1 | Body text (AAA) |
| 500 | #6b7280 | 4.6:1 | Body text (AA) |
| 400 | #9ca3af | 2.9:1 | Large text only |
Accessible brand colors:
- Light backgrounds: Darken brand to 500-700 range
- Dark backgrounds: Lighten brand to 300-400 range
- On brand: Use white (dark brands) or gray-900 (light brands)
Integration with Color Scale
When using with the color-scale skill:
1. Generate palette with color-scale
2. Run contrast check on key combinations:
- Text colors (900, 800) on backgrounds (50, 100)
- Background (500) with white/dark text
- Adjacent scale steps for borders
3. Adjust chroma/lightness if needed
4. Document accessible pairings
Testing Checklist
