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 {
/* Accessible text on light backgrounds */
--text-on-light: #1f2937; /* 14.5:1 on white */
--text-muted-on-light: #4b5563; /* 7.2:1 on white */
/* Accessible text on dark backgrounds */
--text-on-dark: #f9fafb; /* 18.1:1 on gray-900 */
--text-muted-on-dark: #d1d5db; /* 11.3:1 on gray-900 */
/* Accessible text on brand color */
--text-on-primary: #ffffff; /* 5.2:1 on primary-500 */
}
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
- [ ] Primary text on all background colors
- [ ] Secondary/muted text on backgrounds
- [ ] Interactive elements (buttons, links)
- [ ] Focus indicators against backgrounds
- [ ] Error, warning, success states
- [ ] Disabled states (3:1 minimum for discernible)
- [ ] Placeholder text in inputs