WCAG Guidelines
debt(d7/e7/b7/t7)
Closest to 'only careful code review or runtime testing' (d7), adjusted from d5. Tools like axe, Lighthouse, WAVE, and colour-contrast-analyser are listed and do provide automated detection, but the common_mistakes field explicitly notes these tools only catch ~30% of issues — the majority require manual testing with real assistive technology (NVDA, VoiceOver), making full detection closer to d7 than d5.
Closest to 'cross-cutting refactor across the codebase' (e7). The quick_fix lists four distinct categories of requirement (contrast, keyboard, flicker, alt text) and common_mistakes shows failures span colour, keyboard navigation, semantic markup, and assistive-technology compatibility. Retrofitting WCAG AA compliance across an existing web product touches templates, components, CSS, JS interactions, and media assets — a cross-cutting concern, not a localised patch.
Closest to 'strong gravitational pull' (b7). WCAG compliance applies broadly across all web contexts (applies_to: web) and affects frontend decisions at every level — component design, colour palette, interaction patterns, markup semantics, media handling. Every future UI change must be evaluated against WCAG criteria, imposing a persistent compliance tax on all work streams.
Closest to 'serious trap' (t7). The misconception field identifies a fundamental wrong belief: that accessibility affects only a small minority. Common_mistakes reinforce a second serious trap: developers believe passing automated tooling (axe/Lighthouse) means compliance, when in fact those tools catch only ~30% of issues. This contradicts the reasonable expectation that 'automated accessibility testing = accessible site', making it a serious cognitive trap for competent developers.
Also Known As
TL;DR
Explanation
WCAG 2.2 (current) is organised under four principles — POUR: Perceivable, Operable, Understandable, Robust. Level A is minimum accessibility; AA is the legal requirement in most jurisdictions (ADA, EN 301 549, AODA); AAA is aspirational. Key AA requirements include 4.5:1 colour contrast, keyboard navigability, focus indicators, alt text for images, captions for video, and no keyboard traps. WCAG 3.0 is in development with a different conformance model.
Diagram
flowchart TD
WCAG[WCAG 2.1] --> POUR[4 Principles]
POUR --> P[Perceivable<br/>text alternatives<br/>captions colour contrast]
POUR --> O[Operable<br/>keyboard accessible<br/>no seizure triggers]
POUR --> U[Understandable<br/>readable predictable<br/>input assistance]
POUR --> R[Robust<br/>compatible with<br/>assistive technologies]
subgraph Levels
A[Level A - minimum]
AA[Level AA - standard target]
AAA[Level AAA - enhanced]
A --> AA --> AAA
end
style P fill:#1f6feb,color:#fff
style O fill:#238636,color:#fff
style U fill:#d29922,color:#fff
style R fill:#6e40c9,color:#fff
style AA fill:#238636,color:#fff
Common Misconception
Why It Matters
Common Mistakes
- Only testing with automated tools — axe and Lighthouse catch ~30% of accessibility issues; manual testing and screen reader testing are required.
- Colour contrast only — passing contrast ratios while failing keyboard navigation or missing alt text still fails WCAG.
- Not testing with actual assistive technology — NVDA (Windows) and VoiceOver (Mac/iOS) reveal issues automated tools miss.
- Overlaying widgets (AccessiBe) as a WCAG compliance solution — they do not provide true compliance and have been criticised by the disability community.
Code Examples
<!-- Multiple WCAG failures:
<div onclick="submitForm()">Submit</div> <!-- Not keyboard accessible, no role -->
<img src="logo.png"> <!-- Missing alt text -->
<input type="text" placeholder="Email"> <!-- No label element -->
<p style="color: #999">Fine print</p> <!-- Likely fails 4.5:1 contrast --><!-- WCAG AA compliant:
<button type="submit">Submit</button> <!-- Natively keyboard accessible -->
<img src="logo.png" alt="Company Logo"> <!-- Descriptive alt text -->
<label for="email">Email address</label>
<input type="email" id="email" name="email" autocomplete="email" required>
<p style="color: #595959">Fine print</p> <!-- 7:1 contrast ratio — AAA -->