color-contrast

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

1. Get colors: Ask for foreground and background colors (hex, rgb, oklch, hsl)
2. Calculate ratio: Compute relative luminance and contrast ratio
3. Report compliance: Show AA/AAA pass/fail for text sizes
4. If failing: Suggest closest compliant alternatives
5. 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