Agent skill
color-contrast
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.
Install this agent skill to your Project
npx add-skill https://github.com/dylantarre/design-system-skills/tree/main/skills/accessibility/color-contrast
SKILL.md
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
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
dylantarre/design-system-skills
getting-started
Introduction to the design system skills plugin. Use when first installing the plugin, exploring available skills, or planning a design system implementation.
dylantarre/design-system-skills
responsive-typography
Implements fluid typography using CSS clamp() that scales with viewport. Use when creating responsive font sizes, viewport-aware headings, or type that adapts smoothly without breakpoints.
dylantarre/design-system-skills
spacing-scale
Generates consistent spacing tokens using base values and ratios. Use when creating margin/padding systems, gap tokens, or layout spacing. Outputs CSS custom properties, Tailwind config, or JSON tokens.
dylantarre/design-system-skills
color-scale
Generates perceptually uniform OKLCH color palettes from brand colors. Use when creating color systems, theme palettes, or converting hex values to 11-step scales. Outputs CSS custom properties, Tailwind config, or JSON tokens.
dylantarre/design-system-skills
shadow-scale
Generates layered box-shadow elevation tokens for depth hierarchy. Use when creating elevation systems, card shadows, modal depth, or dark mode shadow variants. Outputs CSS, Tailwind, or JSON.
dylantarre/design-system-skills
breakpoints
Generates responsive breakpoint tokens for media queries and container queries. Use when setting up responsive design, mobile-first layouts, or viewport-based styling. Outputs CSS, Tailwind, or JSON.
Didn't find tool you were looking for?