Colour Contrast
debt(d3/e3/b3/t5)
Closest to 'default linter catches the common case' (d3). Tools like axe, Lighthouse, and Colour Contrast Analyser (all listed in detection_hints.tools) catch contrast failures automatically and are commonly integrated into CI/CD pipelines or browser DevTools. These aren't quite 'instant compiler errors' but are standard accessibility audit tools that flag violations readily.
Closest to 'simple parameterised fix' (e3). The quick_fix indicates checking with DevTools and adjusting colour values. Fixing contrast typically means updating CSS colour declarations — often a few property changes in stylesheets. However, if a design system uses low-contrast colours throughout, multiple files may need updates, but usually within a localised scope.
Closest to 'localised tax' (b3). Contrast requirements apply only to web contexts per applies_to. Once a proper colour palette with accessible contrast ratios is established in a design system, the ongoing burden is minimal. The choice doesn't spread across architectural layers — it's contained within styling decisions and can be systematically addressed through design tokens.
Closest to 'notable trap' (t5). The misconception field explicitly states developers believe 'as long as text is readable to most users, contrast is fine' — ignoring that 15% of men have colour vision deficiency. The common_mistakes show grey text appearing 'modern' while failing WCAG, and using colour alone for meaning. These are documented gotchas that experienced accessibility practitioners learn, but catch many developers who assume their own perception is universal.
Also Known As
TL;DR
Explanation
Contrast ratio is calculated from relative luminance: 1:1 (identical) to 21:1 (black on white). WCAG AA requires: 4.5:1 for text under 18pt (or 14pt bold), 3:1 for large text (18pt+ or 14pt+ bold), 3:1 for UI components and graphical objects. WCAG AAA requires 7:1 for normal text. Grey text on white, light text on coloured backgrounds, and disabled-looking active elements are common failures. Tools: Colour Contrast Analyser, browser DevTools accessibility panel.
Diagram
flowchart TD
subgraph WCAG_Requirements
AA_NORMAL[AA Normal text<br/>minimum 4.5:1 ratio]
AA_LARGE[AA Large text 18pt+<br/>minimum 3:1 ratio]
AAA_NORMAL[AAA Normal text<br/>minimum 7:1 ratio]
end
FORE[Foreground colour] --> RATIO[Calculate contrast ratio]
BACK[Background colour] --> RATIO
RATIO --> CHECK{Passes?}
CHECK -->|yes| PASS[Accessible]
CHECK -->|no| ADJUST[Darken foreground<br/>or lighten background]
subgraph Tools
TOOL1[browser DevTools<br/>accessibility panel]
TOOL2[WebAIM contrast checker]
TOOL3[axe browser extension]
end
style AA_NORMAL fill:#238636,color:#fff
style PASS fill:#238636,color:#fff
style ADJUST fill:#d29922,color:#fff
Common Misconception
Why It Matters
Common Mistakes
- Grey text that looks 'modern' but fails contrast — #999999 on white is 2.85:1, failing WCAG AA.
- Placeholder text as the only hint — placeholder disappears on input and typically has low contrast.
- Colour alone to convey meaning — red/green distinction fails for colour-blind users; add icons or text.
- Not testing interactive states — focus, hover, and active states must also meet contrast requirements.
Code Examples
/* Common contrast failures:
.text-muted { color: #999; } /* 2.85:1 on white — FAIL */
.subtitle { color: #aaa; } /* 2.32:1 on white — FAIL */
.error { color: #f00; } /* 3.99:1 on white — FAIL for normal text */
.link { color: #6699cc; } /* 3.04:1 on white — FAIL *//* WCAG AA passing contrast ratios on white (#fff):
.text-muted { color: #767676; } /* 4.54:1 — PASS AA */
.subtitle { color: #595959; } /* 7.0:1 — PASS AAA */
.error { color: #d93025; } /* 4.75:1 — PASS AA */
.link { color: #0066cc; } /* 4.51:1 — PASS AA */
/* Test at: https://webaim.org/resources/contrastchecker/ */