# Color Accessibility Audit

> >

- **Type:** Skill
- **Install:** `agentstack add skill-georgekhananaev-claude-skills-vault-color-accessibility-audit`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [georgekhananaev](https://agentstack.voostack.com/s/georgekhananaev)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [georgekhananaev](https://github.com/georgekhananaev)
- **Source:** https://github.com/georgekhananaev/claude-skills-vault/tree/main/.claude/skills/color-accessibility-audit
- **Website:** https://www.npmjs.com/package/claude-skills-vault

## Install

```sh
agentstack add skill-georgekhananaev-claude-skills-vault-color-accessibility-audit
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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](https://github.com/georgekhananaev)
- **Source:** [georgekhananaev/claude-skills-vault](https://github.com/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.

## 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-georgekhananaev-claude-skills-vault-color-accessibility-audit
- Seller: https://agentstack.voostack.com/s/georgekhananaev
- 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%.