Agent skill
color-contrast-auditor
Detects and fixes color contrast violations using WCAG 2.1 guidelines and perceptual analysis. Expert in contrast ratio calculation, color blindness simulation, and providing accessible alternatives. Activate on "check contrast", "color accessibility", "WCAG audit", "readability check", "contrast ratio", "hard to read", "can't see text". NOT for general color theory (use color-theory-palette-harmony-expert), brand color selection (use web-design-expert), or non-visual accessibility (use ux-friction-analyzer).
Install this agent skill to your Project
npx add-skill https://github.com/curiositech/some_claude_skills/tree/main/.claude/skills/color-contrast-auditor
Metadata
Additional technical details for this skill
- tags
-
accessibility wcag contrast color a11y visual-design
- category
- Design & Creative
- pairs with
-
[ { "skill": "web-design-expert", "reason": "Implement accessible color fixes" }, { "skill": "ux-friction-analyzer", "reason": "Broader accessibility context" }, { "skill": "design-system-creator", "reason": "Build accessible design tokens" } ]
SKILL.md
Color Contrast Auditor
Detects color contrast violations that make text unreadable and provides WCAG-compliant fixes. Uses both mathematical contrast ratio analysis and perceptual evaluation via vision capabilities.
When to Use
Activate on:
- Screenshots of websites/apps with suspected contrast issues
- CSS/Tailwind files for color audit
- "I can't read this" or "this is hard to see"
- Pre-launch accessibility checks
- Design system color validation
NOT for:
- Choosing brand colors (use
web-design-expert) - Color harmony/aesthetics (use
color-theory-palette-harmony-expert) - Non-visual accessibility (screen readers, keyboard nav)
WCAG 2.1 Contrast Requirements
Minimum Ratios (AA - Required)
| Text Type | Minimum Ratio | Example |
|---|---|---|
| Normal text (<24px, <18.66px bold) | 4.5:1 | Body copy, labels, buttons |
| Large text (≥24px or ≥18.66px bold) | 3:1 | Headlines, hero text |
| UI components (borders, icons) | 3:1 | Form inputs, icons, focus rings |
| Graphical objects | 3:1 | Charts, infographics |
Enhanced Ratios (AAA - Recommended)
| Text Type | Minimum Ratio |
|---|---|
| Normal text | 7:1 |
| Large text | 4.5:1 |
Non-Text Elements
| Element | Requirement |
|---|---|
| Focus indicators | 3:1 against adjacent colors |
| Form field borders | 3:1 against background |
| Icons conveying meaning | 3:1 against background |
| Disabled elements | No requirement (but consider UX) |
Contrast Ratio Formula
Contrast Ratio = (L1 + 0.05) / (L2 + 0.05)
Where L1 = lighter color's relative luminance
L2 = darker color's relative luminance
Calculating Relative Luminance
function relativeLuminance(r, g, b) {
// Convert 0-255 to 0-1
let [rs, gs, bs] = [r, g, b].map(c => c / 255);
// Apply gamma correction
const gamma = c => c <= 0.03928
? c / 12.92
: Math.pow((c + 0.055) / 1.055, 2.4);
const [R, G, B] = [rs, gs, bs].map(gamma);
// Weighted sum (human eye sensitivity)
return 0.2126 * R + 0.7152 * G + 0.0722 * B;
}
function contrastRatio(color1, color2) {
const l1 = relativeLuminance(...color1);
const l2 = relativeLuminance(...color2);
const lighter = Math.max(l1, l2);
const darker = Math.min(l1, l2);
return (lighter + 0.05) / (darker + 0.05);
}
Common Failing Patterns
1. Light Text on Light Background
❌ FAILING EXAMPLE (from user screenshot):
┌─────────────────────────────────────────────┐
│ Background: #F5F2E8 (beige/cream) │
│ Text: #C8FF00 (lime green) │
│ │
│ "Scan. Crawl. Match. Report." │
│ ← UNREADABLE │
│ │
│ Calculated Ratio: ~1.5:1 │
│ Required: 4.5:1 (normal) or 3:1 (large) │
│ Verdict: FAIL by 3x │
└─────────────────────────────────────────────┘
✅ FIXED OPTIONS:
• Darken text to #5A7300 → Ratio: 4.5:1
• Darken background to #2A2A2A → Ratio: 12:1
• Use dark green #1A4D00 → Ratio: 8:1
2. Gray Text Syndrome
❌ COMMON FAILURE:
Background: #FFFFFF
Text: #AAAAAA (light gray)
Ratio: 2.3:1 ← FAIL
✅ FIXES:
• Text: #767676 → Ratio: 4.5:1 (minimum AA)
• Text: #595959 → Ratio: 7:1 (AAA)
3. Saturated Colors That Look Bright
❌ DECEPTIVE FAILURE:
Background: #FFF8E7 (warm white)
Text: #FF6B6B (coral/salmon)
Ratio: 2.8:1 ← FAIL (looks "colorful" but fails)
✅ FIXES:
• Text: #C62828 (darker red) → Ratio: 5.2:1
• Text: #8B0000 (dark red) → Ratio: 8.1:1
4. Trendy Low-Contrast Aesthetic
❌ "MINIMALIST" FAILURE:
Background: #FAFAFA
Text: #E0E0E0
Ratio: 1.3:1 ← SEVERELY FAILING
This is NOT minimalism. This is inaccessible.
✅ MINIMALIST + ACCESSIBLE:
Background: #FAFAFA
Text: #616161 → Ratio: 5.7:1
5. Placeholder Text Too Light
❌ COMMON FORM FAILURE:
Input background: #FFFFFF
Placeholder: #CCCCCC
Ratio: 1.6:1 ← FAIL
✅ FIX:
Placeholder: #757575 → Ratio: 4.6:1
6. Gradient Backgrounds
❌ VARIABLE CONTRAST:
Gradient: #FFFFFF → #000080
Text: #FFFFFF (fixed)
Top of gradient: 1:1 (invisible!)
Bottom of gradient: 8.6:1 (good)
✅ SOLUTIONS:
• Add text shadow/outline
• Use semi-transparent overlay behind text
• Ensure ALL gradient stops pass contrast
Audit Methodology
Step 1: Visual Scan (Screenshot Analysis)
When given a screenshot, identify:
-
Text elements by size:
- Headlines (large text → 3:1 required)
- Body copy (normal text → 4.5:1 required)
- UI labels (buttons, links → 4.5:1)
- Captions/fine print (4.5:1 required)
-
Interactive elements:
- Button borders/backgrounds
- Form field borders
- Focus states
- Icons with meaning
-
Red flags to look for:
- Light text on light backgrounds
- Gray text on white
- Colored text on colored backgrounds
- Text over images without overlay
Step 2: Extract Colors
From CSS/code:
# Find all color declarations
grep -E "(color:|background:|#[0-9a-fA-F]{3,8}|rgb|hsl)" styles.css
From Tailwind:
# Find text/bg color classes
grep -E "(text-|bg-)" *.tsx *.jsx
Step 3: Calculate Ratios
For each text/background pair:
- Convert colors to RGB
- Calculate relative luminance
- Compute contrast ratio
- Compare to WCAG requirement
Step 4: Generate Report
# Contrast Audit Report
## Summary
- Total color pairs tested: X
- Passing (AA): Y
- Failing: Z
- Critical failures (<2:1): N
## Failures by Severity
### Critical (Ratio < 2:1)
| Location | Foreground | Background | Ratio | Required | Fix |
|----------|------------|------------|-------|----------|-----|
| Hero tagline | #C8FF00 | #F5F2E8 | 1.5:1 | 3:1 | #5A7300 |
### Moderate (Ratio 2:1 - 3:1)
...
### Minor (Ratio 3:1 - 4.5:1, normal text only)
...
## Recommended Fixes
[Specific color replacements with new ratios]
Color Blindness Considerations
Contrast requirements help but don't fully address color blindness. Additional checks:
Types to Consider
| Type | Affected | Consideration |
|---|---|---|
| Deuteranopia | 6% of males | Red/green confusion |
| Protanopia | 2% of males | Red appears dark |
| Tritanopia | <1% | Blue/yellow confusion |
Best Practices
-
Never rely on color alone for meaning
- Add icons, patterns, or text labels
- Red/green for error/success needs icons too
-
Test problematic pairs:
- Red + Green (stop/go)
- Blue + Purple
- Green + Brown
- Light green + Yellow
-
Use sufficient lightness difference
- Even with same hue, different lightness helps
Quick Reference: Safe Color Pairs
On White (#FFFFFF)
| Use Case | Color | Hex | Ratio |
|---|---|---|---|
| Body text | Dark gray | #333333 | 12.6:1 |
| Secondary text | Medium gray | #767676 | 4.5:1 |
| Links | Blue | #0066CC | 5.3:1 |
| Success | Green | #2E7D32 | 5.1:1 |
| Error | Red | #C62828 | 6.0:1 |
| Warning | Orange-brown | #E65100 | 4.5:1 |
On Black (#000000)
| Use Case | Color | Hex | Ratio |
|---|---|---|---|
| Body text | Light gray | #E0E0E0 | 13.4:1 |
| Secondary | Medium gray | #9E9E9E | 6.3:1 |
| Accent | Light blue | #90CAF9 | 7.3:1 |
On Dark Gray (#1A1A1A)
| Use Case | Color | Hex | Ratio |
|---|---|---|---|
| Body text | Off-white | #F5F5F5 | 14.1:1 |
| Secondary | Light gray | #BDBDBD | 8.3:1 |
Tools & Validation
Online Checkers
Browser DevTools
// Chrome DevTools: Elements → Styles → hover color swatch
// Shows contrast ratio automatically
// Firefox: Accessibility Inspector
// Shows color contrast issues
Automated Testing
// axe-core (popular a11y testing library)
const axe = require('axe-core');
axe.run(document, { rules: ['color-contrast'] });
// Lighthouse (built into Chrome)
// Performance → Accessibility → Color contrast
CLI Tools
# Lighthouse CLI
npx lighthouse https://example.com --only-categories=accessibility
# Pa11y
npx pa11y https://example.com
Integration with This Skill
When analyzing a screenshot or codebase:
- I will identify all text/background color pairs
- I will calculate contrast ratios for each
- I will flag anything below WCAG AA thresholds
- I will suggest specific hex values that pass
- I will provide before/after comparisons
For the example screenshot (lime on beige):
AUDIT RESULT: CRITICAL FAILURE
Element: Hero tagline "Scan. Crawl. Match. Report."
Foreground: ~#C8FF00 (lime green)
Background: ~#F5F2E8 (beige)
Calculated Ratio: ~1.5:1
Required (large text): 3:1
Required (normal text): 4.5:1
Status: ❌ FAILS BY 2-3x
RECOMMENDED FIXES:
1. Darken text to #5A7300 (olive) → 4.8:1 ✓
2. Darken text to #3D5C00 (dark olive) → 7.1:1 ✓✓
3. Keep lime, darken BG to #3D3D3D → 8.2:1 ✓✓
4. Use #1B5E20 (dark green) → 8.4:1 ✓✓
Checklist for New Designs
Before shipping:
- All body text has ≥4.5:1 contrast
- All large text has ≥3:1 contrast
- All form borders have ≥3:1 contrast
- All icons conveying meaning have ≥3:1 contrast
- Placeholder text is readable (≥4.5:1)
- Focus states are clearly visible (≥3:1)
- Links are distinguishable without color alone
- Error/success states use icons, not just color
- Tested with color blindness simulators
- Automated accessibility scan passes
Philosophy: Beautiful design and accessibility are not mutually exclusive. High contrast can be striking, dramatic, and intentional. Low contrast isn't "minimalist"—it's exclusionary. Every unreadable word is a user lost.
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
3d-cv-labeling-2026
Expert in 3D computer vision labeling tools, workflows, and AI-assisted annotation for LiDAR, point clouds, and sensor fusion. Covers SAM4D/Point-SAM, human-in-the-loop architectures, and vertical-specific training strategies. Activate on '3D labeling', 'point cloud annotation', 'LiDAR labeling', 'SAM 3D', 'SAM4D', 'sensor fusion annotation', '3D bounding box', 'semantic segmentation point cloud'. NOT for 2D image labeling (use clip-aware-embeddings), general ML training (use ml-engineer), video annotation without 3D (use computer-vision-pipeline), or VLM prompt engineering (use prompt-engineer).
project-management-guru-adhd
Expert project manager for ADHD engineers managing multiple concurrent projects. Specializes in hyperfocus management, context-switching minimization, and parakeet-style gentle reminders. Activate on 'ADHD project management', 'context switching', 'hyperfocus', 'task prioritization', 'multiple projects', 'productivity for ADHD', 'task chunking', 'deadline management'. NOT for neurotypical project management, rigid waterfall processes, or general productivity advice without ADHD context.
large-scale-map-visualization
Master of high-performance web map implementations handling 5,000-100,000+ geographic data points. Specializes in Leaflet.js optimization, Supercluster algorithms, viewport-based loading, canvas rendering, and progressive disclosure UX patterns.
adhd-design-expert
Designs digital experiences for ADHD brains using neuroscience research and UX principles. Expert in reducing cognitive load, time blindness solutions, dopamine-driven engagement, and compassionate design patterns. Activate on 'ADHD design', 'cognitive load', 'accessibility', 'neurodivergent UX', 'time blindness', 'dopamine-driven', 'executive function'. NOT for general accessibility (WCAG only), neurotypical UX design, or simple UI styling without ADHD context.
liaison
Translate multi-agent ecosystem activity into human-readable status briefings, decision requests, and progress summaries. Use for 'status update', 'brief me', 'what happened', 'summarize progress'. NOT for project planning (use project-management-guru-adhd), code review, or technical documentation.
windows-95-web-designer
Modern web applications with authentic Windows 95 aesthetic. Gradient title bars, Start menu paradigm, taskbar patterns, 3D beveled chrome. Extrapolates Win95 to AI chatbots, mobile UIs, responsive layouts. Activate on 'windows 95', 'win95', 'start menu', 'taskbar', 'retro desktop', '95 aesthetic', 'clippy'. NOT for Windows 3.1 (use windows-3-1-web-designer), vaporwave/synthwave, macOS, flat design.
Didn't find tool you were looking for?