# 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. - **Type:** Skill - **Install:** `agentstack add skill-curiositech-some-claude-skills-color-contrast-auditor` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [curiositech](https://agentstack.voostack.com/s/curiositech) - **Installs:** 0 - **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [curiositech](https://github.com/curiositech) - **Source:** https://github.com/curiositech/some_claude_skills/tree/main/.claude/skills/color-contrast-auditor ## Install ```sh agentstack add skill-curiositech-some-claude-skills-color-contrast-auditor ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # 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 ```javascript 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: 1. **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) 2. **Interactive elements:** - Button borders/backgrounds - Form field borders - Focus states - Icons with meaning 3. **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: ```bash # Find all color declarations grep -E "(color:|background:|#[0-9a-fA-F]{3,8}|rgb|hsl)" styles.css ``` From Tailwind: ```bash # Find text/bg color classes grep -E "(text-|bg-)" *.tsx *.jsx ``` ### Step 3: Calculate Ratios For each text/background pair: 1. Convert colors to RGB 2. Calculate relative luminance 3. Compute contrast ratio 4. Compare to WCAG requirement ### Step 4: Generate Report ```markdown # 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 1. **Never rely on color alone** for meaning - Add icons, patterns, or text labels - Red/green for error/success needs icons too 2. **Test problematic pairs:** - Red + Green (stop/go) - Blue + Purple - Green + Brown - Light green + Yellow 3. **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 - [WebAIM Contrast Checker](https://webaim.org/resources/contrastchecker/) - [Coolors Contrast Checker](https://coolors.co/contrast-checker) - [Adobe Color Accessibility](https://color.adobe.com/create/color-accessibility) ### Browser DevTools ```javascript // Chrome DevTools: Elements → Styles → hover color swatch // Shows contrast ratio automatically // Firefox: Accessibility Inspector // Shows color contrast issues ``` ### Automated Testing ```javascript // 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 ```bash # 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: 1. **I will identify** all text/background color pairs 2. **I will calculate** contrast ratios for each 3. **I will flag** anything below WCAG AA thresholds 4. **I will suggest** specific hex values that pass 5. **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. ## Source & license This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [curiositech](https://github.com/curiositech) - **Source:** [curiositech/some_claude_skills](https://github.com/curiositech/some_claude_skills) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-curiositech-some-claude-skills-color-contrast-auditor - Seller: https://agentstack.voostack.com/s/curiositech - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.