Web Accessibility (WCAG & ARIA)
debt(d5/e5/b5/t7)
Closest to 'specialist tool catches it' (d5). The detection_hints list axe, lighthouse, wave, and nvda — all specialist accessibility tools. Common automated linters do not catch most accessibility issues (missing labels, focus ring removal, ARIA misuse), and many issues (e.g. incorrect ARIA roles with no keyboard handler) require runtime testing with assistive technology. Automated tools catch a meaningful subset but not all cases, placing this squarely at d5.
Closest to 'touches multiple files / significant refactor in one component' (e5). The quick_fix covers several distinct actions: adding alt text, associating labels, ensuring focus visibility, and testing Tab navigation. Common mistakes span multiple patterns (div/span misuse, missing alt, missing labels, incorrect ARIA). Fixing accessibility across a page or component requires touching many elements and potentially refactoring interactive components to use semantic HTML, which is more than a single-line patch but typically scoped within a component rather than a full architectural rework.
Closest to 'persistent productivity tax' (b5). Accessibility applies broadly to all web contexts (applies_to: web) and affects every interactive UI element, form, image, and dynamic content update. It imposes an ongoing discipline across the frontend — every new component must be designed and tested with accessibility in mind. However, it does not reshape the entire system architecture, so b7 would be too high. It is more than a localised tax (b3) since it affects all UI work streams.
Closest to 'serious trap' (t7). The misconception is explicit: developers believe adding ARIA attributes makes an element accessible, when in fact incorrect ARIA usage (e.g. role='button' on a non-focusable div) is actively worse than no ARIA. This directly contradicts the intuitive expectation that more annotation equals more accessibility. It also contradicts patterns from similar concepts (e.g. CSS classes that are purely visual), making it a serious trap for competent developers unfamiliar with ARIA semantics.
Also Known As
TL;DR
Explanation
WCAG 2.1 organises requirements under four principles (POUR): Perceivable (alt text for images, captions for video, sufficient colour contrast ≥4.5:1), Operable (keyboard navigation, focus indicators, no seizure-inducing content), Understandable (clear labels, consistent navigation, error messages), Robust (valid HTML, ARIA correctly used). ARIA (Accessible Rich Internet Applications) supplements semantic HTML for complex widgets — role='dialog', aria-expanded, aria-live for dynamic content. Golden rule: use native HTML elements first (a button is better than a div with role='button' and tabindex='0' and keyboard handlers). Test with a screen reader (NVDA, VoiceOver) and keyboard-only navigation. For PHP-generated HTML, validate output with axe-core or Lighthouse.
Common Misconception
Why It Matters
Common Mistakes
- Using div and span for interactive elements instead of button and a — keyboard and screen reader support is lost.
- Missing alt attributes on images — screen readers read file names instead.
- Form inputs without associated labels — screen readers cannot describe what the input is for.
- ARIA attributes that contradict the underlying semantic HTML — role=button on a div that cannot receive focus.
Code Examples
<div onclick="submitForm()">Submit</div>
<div class="red">This field is required</div>
<img src="logo.png"><!-- Use native elements — keyboard accessible, screen reader friendly -->
<button type="submit" onclick="submitForm()">Submit</button>
<!-- Associate error with input -->
<input id="email" aria-describedby="email-error" aria-invalid="true">
<span id="email-error" role="alert">This field is required</span>
<!-- Always provide alt text -->
<img src="logo.png" alt="Acme Corp logo">
<!-- Decorative images: empty alt, role=presentation -->
<img src="divider.png" alt="" role="presentation">