AccessibilitybeginnerNew
Fix color contrast issues
✓Works with OpenClaudeYou are an accessibility specialist. The user wants to fix color contrast issues in their web application to meet WCAG standards.
What to check first
- Run your HTML/CSS through WebAIM's contrast checker or use
npm install --save-dev axe-coreto detect contrast violations - Identify which text/background color pairs fail (use browser DevTools → Accessibility panel or axe DevTools extension)
- Check your current WCAG level target: AA requires 4.5:1 for normal text, 3:1 for large text; AAA requires 7:1 and 4.5:1
Steps
- Calculate the relative luminance of your foreground and background colors using the WCAG formula:
(0.299 × R + 0.587 × G + 0.114 × B) / 255 - Convert RGB values to sRGB (divide by 255) and apply gamma correction using
if (value <= 0.03928) then value / 12.92 else ((value + 0.055) / 1.055) ^ 2.4 - Compute contrast ratio:
(L1 + 0.05) / (L2 + 0.05)where L1 is lighter luminance and L2 is darker - Use
npm install contrast-ratioor build a utility function to automate these calculations for your color pairs - Audit text elements using
getComputedStyle(element).colorandgetComputedStyle(element).backgroundColorin DevTools console - Adjust color values: lighten dark backgrounds or darken light text to increase contrast
- Test with accessibility tools like axe, WAVE, or Lighthouse to verify 4.5:1 minimum ratio achieved
- Document color pairs in a design system token file (JSON, CSS custom properties, or Figma) to prevent future violations
Code
// Utility function to calculate WCAG contrast ratio
function getContrastRatio(rgb1, rgb2) {
// Convert "rgb(r, g, b)" or "#hex" to [r, g, b]
const toRGB = (color) => {
if (color.startsWith('#')) {
const hex = color.slice(1);
return [
parseInt(hex.substr(0, 2), 16),
parseInt(hex.substr(2, 2), 16),
parseInt(hex.substr(4, 2), 16)
];
}
return color.match(/\d+/g).map(Number);
};
// Calculate relative luminance
const getLuminance = (rgb) => {
const [r, g, b] = rgb.map(val => {
const v = val / 255;
return v <= 0.03928 ? v / 12.92 : Math.pow((v + 0.055) / 1.055, 2.4);
});
return
Note: this example was truncated in the source. See the GitHub repo for the latest full version.
Common Pitfalls
- Auto-generated alt text from filenames — always describe the actual image content, not the filename
- Using
aria-hidden="true"on focusable elements — the element will still receive focus but be invisible to screen readers, breaking keyboard navigation - Color contrast ratios that pass on the design file but fail in production due to anti-aliasing or font weight differences
- Adding ARIA labels to elements that already have semantic HTML — this often confuses screen readers more than it helps
- Skipping the
langattribute on the<html>element — screen readers won't pronounce content correctly without it
When NOT to Use This Skill
- When your component is purely decorative and not part of the user-interactive flow
- When you're prototyping and the design will change significantly — wait until the design stabilizes
- On third-party embeds where you can't modify the markup (use a wrapper-level fix instead)
How to Verify It Worked
- Run
axe DevToolsbrowser extension on the page — should show 0 violations - Test with a screen reader (VoiceOver on Mac, NVDA on Windows) — every interactive element should be announced clearly
- Navigate the entire flow using only the Tab key — you should be able to reach and activate every interactive element
- Check Lighthouse accessibility score — should be 95+ for production
Production Considerations
- Add accessibility tests to your CI pipeline so regressions don't ship — fail the build on critical violations
- Real users with disabilities navigate differently than automated tools — schedule manual testing with disabled users at least once per quarter
- WCAG 2.1 AA is the legal minimum in most jurisdictions (ADA, EAA). AAA is aspirational, not required
- Document your accessibility decisions in a public a11y statement — required for ADA compliance in the US
Related Accessibility Skills
Other Claude Code skills in the same category — free to download.
Accessibilityintermediate
A11y Audit
Audit accessibility issues in components
Accessibilityintermediate
ARIA Fixer
Add proper ARIA attributes
Accessibilityintermediate
Keyboard Nav
Implement keyboard navigation
Accessibilityintermediate
Screen Reader Fix
Fix screen reader issues
Accessibilityintermediate
Focus Management
Implement focus management
Accessibilitybeginner
Skip Navigation
Add skip navigation links
Accessibilityintermediate
A11y Testing
Set up automated accessibility testing
Want a Accessibility skill personalized to YOUR project?
This is a generic skill that works for everyone. Our AI can generate one tailored to your exact tech stack, naming conventions, folder structure, and coding patterns — with 3x more detail.