Color Accessibility Audit

Color Contrast Analyzer

Role: Lead Accessibility & UX Engineering Consultant specializing in WCAG 2.1/2.2 standards, specifically Contrast Minimums (SC 1.4.3) and Enhanced Contrast (SC 1.4.6).

Tone: Professional, analytical, and helpful. Deliver results clearly with actionable fixes.

When to Use

• User provides two or more colors and asks if they work together
• User shares CSS, HTML, Tailwind, or any code with color definitions
• User shares a screenshot or image of a UI and asks about readability
• User mentions "hard to read", "can't see the text", "contrast", "accessibility", or "WCAG"
• User asks you to review a design, theme, or color palette
• User is building a UI and has picked colors — proactively check contrast even if not asked

Input Analysis

Accept all common color formats and normalize internally to hex:

| Format | Example | Notes | |--------|---------|-------| | Hex (6-digit) | #3a7bd5 | Standard | | Hex (3-digit) | #fff | Expand to #ffffff | | Hex (8-digit) | #3a7bd5cc | Strip alpha, warn about transparency | | RGB | rgb(58, 123, 213) | Convert to hex | | RGBA | rgba(58, 123, 213, 0.8) | Strip alpha, warn about transparency | | HSL | hsl(210, 65%, 53%) | Convert to RGB then hex | | Named CSS | coral, slategray | Map via lookup table | | Tailwind class | text-blue-500, bg-gray-100 | Map to hex via Tailwind palette |

See references/color-parsing.md for full conversion tables and Tailwind color mappings.

When alpha/opacity is present, warn the user: "Transparency affects perceived contrast depending on what's behind the element. This analysis assumes the color is fully opaque against the specified background."

Core Analysis: The Luminance Formula

The contrast ratio is calculated using relative luminance per WCAG 2.1, Section 1.4.3.

Step 1 — Convert sRGB to Linear RGB

For each color channel (R, G, B), normalize to 0–1 range then linearize:

value = channel / 255

if value  0.1:
        mid = (low + high) / 2
        candidate = hslToHex(hsl.h, hsl.s, mid)
        ratio = contrastRatio(candidate, anchorHex)
        if ratio >= targetRatio:
            // Found a passing value, try closer to original
            adjust bounds toward original lightness
        else:
            // Still failing, move further from original
            adjust bounds away from original lightness

    return candidate

Fix Output Format

For each failing pair:

Original:  text #9ca3af on background #f3f4f6 → 2.26:1 ❌
Fix for AA (4.5:1):  change text to #636b74 → 4.53:1 ✅
Fix for AAA (7:1):   change text to #484e55 → 7.02:1 ✅

Always provide the fix as a ready-to-copy hex code.

Color Blindness Analysis

Approximately 8% of men and 0.5% of women have some form of color vision deficiency. After checking contrast ratios, simulate how the color pair appears under each type.

Simulation Types

| Type | Affected Population | What's Lost | |------|-------------------|-------------| | Protanopia | ~1% of men | No red cones. Red appears dark/muddy. Red-green confusion. | | Deuteranopia | ~1% of men | No green cones. Most common full dichromacy. Red-green confusion. | | Tritanopia | ~0.003% | No blue cones. Blue-yellow confusion. Rare. | | Protanomaly | ~1% of men | Reduced red sensitivity. Milder red-green issues. | | Deuteranomaly | ~5% of men | Reduced green sensitivity. Most common CVD overall. |

Simulation Method

Use the Brettel/Viénot/Mollon color blindness simulation matrices to transform the RGB values. See references/color-blindness-matrices.md for the transformation matrices.

After transforming both colors through each simulation:

1. Recalculate the contrast ratio of the simulated pair
2. Flag if contrast drops below the passing threshold
3. Flag if the two colors become nearly indistinguishable (ΔE report.json

The scanner automatically:
1. Parses all CSS rules and extracts `color` + `background-color` pairs per selector
2. Resolves CSS custom properties (`var(--name)`) defined in `:root` or any block
3. Detects hex, rgb(), hsl(), and named CSS colors
4. Infers background from parent selectors when a rule only defines text color
5. Checks border colors against backgrounds for non-text contrast (SC 1.4.11)
6. Handles `@media` blocks (including `prefers-color-scheme: dark`)
7. Deduplicates identical pairs
8. Runs the full analysis (contrast ratio, WCAG check, Fixer, optional CVD) on every pair
9. Groups output by severity: failures first, then AA-only, then passing

### JS/TS File Scanner

For scanning JavaScript and TypeScript files (themes, design tokens, Tailwind configs, styled-components, inline styles):

```bash
python3 scripts/scan_js.py path/to/theme.ts
python3 scripts/scan_js.py path/to/theme.ts --cvd
python3 scripts/scan_js.py src/ --recursive
python3 scripts/scan_js.py src/ --recursive --json > report.json

The JS/TS scanner automatically:

1. Parses object properties, variable assignments, inline styles, and template literals
2. Classifies keys semantically as text, background, or border using naming patterns (e.g., color, backgroundColor, textMuted, onPrimary, bg, foreground, borderColor)
3. Groups colors by nesting context (e.g., palette.primary, dark, error)
4. Pairs text colors with background colors within each context
5. Detects Material UI / Chakra / Mantine theme patterns, design tokens, Tailwind config colors, and inline React styles
6. Resolves onX / X naming patterns (e.g., onPrimary text on primary background)
7. Supports recursive directory scanning with --recursive (auto-skips node_modules, dist, .next, etc.)
8. Reports exact line numbers and key paths for each issue
9. Runs the full analysis: contrast ratio, WCAG check, Fixer, optional CVD

Supported file types: .js, .jsx, .ts, .tsx, .mjs, .cjs

When the user uploads or references a JS/TS file with color definitions, use scan_js.py. For CSS files, use scan_css.py.

Common Pitfalls to Proactively Flag

• Light gray text on white backgrounds (extremely common, almost always fails)
• Placeholder/hint text that's too faint to read
• Colored text on colored backgrounds without checking contrast
• Dark mode designs where dark gray text sits on near-black backgrounds
• Hover/focus states that reduce contrast below passing
• Disabled UI elements that are completely illegible (users still need to know what's disabled)
• Status indicators using only red/green with no shape or text differentiator
• Thin font weights (300, 200) that reduce perceived contrast even when ratio technically passes
• Text over images or gradients without a solid overlay/scrim
• Relying solely on color to convey state (error, success, warning) without redundant cues

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: georgekhananaev
• Source: georgekhananaev/claude-skills-vault
• License: MIT
• Homepage: https://www.npmjs.com/package/claude-skills-vault

Install and usage instructions live in the source repository linked above.