- Home
- Skills
- UX & UI Design
- WCAG Contrast Audit: Find failing color pairs and fixes
More screenshots
Works with the AI Agents you already use
WCAG Contrast Audit: Find failing color pairs and fixes
Your muted caption text looks fine to you and fails WCAG for everyone else. Check every foreground/background pair in your design tokens against AA or AAA and get the nearest color that passes.
$12
WCAG Contrast Audit: Find failing color pairs and fixes
Example session with this skill installed
Audit references/example-palette.json for WCAG contrast, suggest foreground fixes, and explain cases that require background or alpha changes.
- Read your context and instructions
- Compiled the wcag contrast audit
Actual stdout from python3 -I -B scripts/contrast_audit.py --input references/example-palette.json --fix (exit 1):
WCAG 2.2 contrast audit
2/9 pairs pass, 7 fail.
| Pair | Foreground | Background | Use | Level | Ratio | Required | Result |
|---|---|---|---|---|---|---|---|
| Body text | #1f2937 | #ffffff | text | AA | 14.679:1 | 4.5:1 | PASS |
| Muted caption | #777777 | #ffffff | text | AA | 4.478:1 | 4.5:1 | FAIL |
| Muted caption, large | #777777 | #ffffff | large-text | AA | 4.478:1 | 3:1 | PASS |
| Button label | #ffffff | #2f80ed | text | AA | 3.866:1 | 4.5:1 | FAIL |
| Accent text | #ff6666 | #ffffff | text | AA | 2.859:1 | 4.5:1 | FAIL |
| Link on dark | #3b82f6 | #1e293b | text | AA | 3.977:1 | 4.5:1 | FAIL |
| Input border | #cbd5e1 | #ffffff | non-text | AA | 1.484:1 | 3:1 | FAIL |
| Overlay hint text (40% black) | #00000066 | #f3f4f6 | text | AA | 2.814:1 | 4.5:1 | FAIL |
| Headline, AAA | #2f80ed | #ffffff | large-text | AAA | 3.866:1 | 4.5:1 | FAIL |
Suggested fixes (OKLCH lightness search; chroma may decrease)
- Muted caption: replace
#777777with#767676(darker, 4.542:1, dE_OK 0.003) - Button label: replace
#ffffffwith#1a1a1a(darker, 4.501:1, dE_OK 0.782) - Accent text: replace
#ff6666with#d63f45(darker, 4.510:1, dE_OK 0.114) - Link on dark: replace
#3b82f6with#458dff(lighter, 4.532:1, dE_OK 0.032) - Input border: replace
#cbd5e1with#8c96a1(darker, 3.003:1, dE_OK 0.200)
Overlay hint text (40% black): no foreground lightness reaches 4.5:1 on #f3f4f6 (best possible 2.814:1); change the background or the alpha instead
- Headline, AAA: replace
#2f80edwith#2274e0(darker, 4.523:1, dE_OK 0.038)
FAIL: 2 of 9 pairs pass and 7 fail, so the exit code stays 1 even with fixes suggested. Look at the button first, because its fix swaps white text for dark text. The muted caption passes at 4.542:1 with #767676. The overlay can't pass by changing its color at 40% opacity, so change the opacity or background and run it again.
Connects securely to your tools. The creator never sees your data.
About this skill
The problem Your palette or token file is about to ship and you need to know which text and border colors are too faint. Pasting pairs into a web checker one at a time is slow, and it's easy to miss a near miss: a gray caption at 4.478:1 fails normal-text AA but passes for large text. When a pair fails, you also have to guess a darker shade and check it again.
See it before you buy: real input, real output Command (from the package folder, exit code 1, 0.026 s):
python3 -I -B scripts/contrast_audit.py --input references/example-palette.json --fix
Before: Your palette (excerpt of references/example-palette.json)
"primary": "#1f2937",
"muted": "#777777",
"inverse": "#ffffff",
"primary": { "$value": "#2f80ed" },
{ "name": "Muted caption", "foreground": "text.muted", "background": "surface.default" },
{ "name": "Button label", "foreground": "text.inverse", "background": "brand.primary" },
After: lines copied from the script's output (excerpt):
**2/9 pairs pass**, 7 fail.
| Muted caption | `#777777` | `#ffffff` | text | AA | 4.478:1 | 4.5:1 | FAIL |
| Button label | `#ffffff` | `#2f80ed` | text | AA | 3.866:1 | 4.5:1 | FAIL |
## Suggested fixes (OKLCH lightness search; chroma may decrease)
- **Muted caption**: replace `#777777` with `#767676` (darker, 4.542:1, dE_OK 0.003)
- **Button label**: replace `#ffffff` with `#1a1a1a` (darker, 4.501:1, dE_OK 0.782)
- **Overlay hint text (40% black)**: no foreground lightness reaches 4.5:1 on `#f3f4f6` (best possible 2.814:1); change the background or the alpha instead
What the numbers show
- Audited 488 pairs from Tailwind v3.4.17, plus Primer and Material samples; ten ratios worked out by hand with the WCAG formula all matched.
- Each audit run took under 0.05 seconds, Python startup included.
- Honest limit: the pass/fail rows are pairs I picked to exercise the tool, not bugs in those design systems.
What you get
- One Python script with no dependencies. It reads a JSON list of color pairs, or your nested hex design tokens.
- Each pair is checked against normal text, large text and UI-border targets at AA and AAA.
- A Markdown or JSON report, and exit code 0 (all pass), 1 (something fails) or 2 (bad input), so it can gate CI.
- With
--fix, a replacement foreground for each failure, re-measured to confirm it passes. If transparency makes a pass impossible, it tells you the best ratio you can reach. - 510 real color pairs from Tailwind, Primer and Material to try it on, plus input notes and four saved sample reports.
- Instructions that tell your agent to confirm text size and target first, run the audit, then rank the fixes for you to approve.
Measured on real data (full detail)
| Palette sample | Pairs checked | Pass normal-text AA | Fail normal-text AA |
|---|---|---|---|
| Tailwind v3.4.17 | 488 | 245 | 243 |
| Primer light snapshot | 10 | 9 | 1 |
| Material v1 sample | 12 | 5 | 7 |
"Pass" and "fail" here mean the pair meets or misses the 4.5:1 ratio for normal-size text. These are combinations I picked to exercise the tool, not bugs in those design systems. The Tailwind row is each of its 244 named colors on white and on black. The one Primer failure is the disabled-text color, which WCAG may exempt. I also worked out ten of the ratios by hand with the WCAG formula, and all ten matched the script's numbers and pass/fail calls. Each audit run took under 0.05 seconds. Sources, file hashes and the hand calculations are in references/benchmarks.md.
Known limitations
- You give it the hex pairs. It doesn't read CSS, open web pages, or find hover and focus states you left out.
- It only checks WCAG 2 contrast ratios. No APCA, images, gradients or color-blindness simulation, and a pass is not an accessibility certificate.
- Fixes keep the transparency and roughly the same hue, but may make the color less saturated. They pass, but they may not be the closest color or one your brand team likes.
- Backgrounds must be solid colors. You decide the text size and whether contrast rules apply (disabled controls are often exempt).
- The sample palettes are older releases (Tailwind v3, Material v1), not current themes.
Who it's for Frontend developers and design-system maintainers who already know which colors sit on which backgrounds and want a repeatable check with fixes they can review.
Requires Python 3.8 or newer, standard library only, and a terminal or an agent that can run a script. No packages, no API keys. I tested it on Python 3.13; it uses only features available since 3.8, but I couldn't run it on 3.8 or 3.12 myself.
Runs locally with no network or telemetry. It writes only when you redirect output or request --json-out.
Check it yourself
23 test cases pass, including four saved sample reports that match the script's output exactly, and 14 extra edge cases (empty, malformed, Unicode, CRLF and large inputs, every flag) give the same output and exit codes as version 1.1.0. To check it yourself from the package folder, run python3 -I -B scripts/contrast_audit.py -i references/example-palette.json --fix and compare with references/sample-output/fail.md. references/benchmarks.md has the commands for the 510-pair counts.
Price and guarantee $12 one time, yours to use with any agent that can run Python. Covered by Agensi's money-back guarantee if it doesn't do what this page promises.
Find more skills like this on the Claude Skills Marketplace, the Codex Skills Marketplace and the Gemini Skills Marketplace, or browse Claude Skills for UX & UI Design.
WCAG 2.x only (no APCA). No CSS parsing or image analysis. Requires resolved hex values. Foreground fix search adjusts lightness only.
How to use
- 1
Connect your agent to the Agensi MCP
Copy the prompt and paste it into Claude, ChatGPT, Cursor or any agent that supports MCP. It sets up the connection for you. Manual setup
- 2
Sign in to Agensi
Your agent shows a sign-in link. Sign in and click Allow.
- 3
Ask for what you need
Your agent loads this skill and uses it on your task. It always asks before buying a skill.
Reviews
No reviews yet
Be one of the first to try it. Every listed skill goes through the trust checks below.
Security scanned
Checked by our 8-point scan before listing
Fresh listing
Recently published to Agensi
Money-back guarantee
Doesn't do what its page promises? You get your money back.
Trust & safety
Security scan
Security scan passed 15 days ago
- Software
Git
Permissions
Use a terminal to run Python and read only the explicitly supplied JSON input or stdin. Reports go to stdout/stderr; no files are written unless the user redirects output or selects a --json-out path, which is overwritten. No network access, no telemetry, and nothing is sent anywhere. The agent may create a temporary input file from reference text for the demo.