WCAG 2.1 AA: What Every Web Developer Needs to Know

What Is WCAG and Who Makes It?

The Web Content Accessibility Guidelines (WCAG) are published by the World Wide Web Consortium (W3C) through the Web Accessibility Initiative (WAI). Version 2.1 was published in June 2018 and is the current legal benchmark for accessibility in the United States, European Union, Canada, and many other jurisdictions.

WCAG defines three conformance levels: A (minimum), AA (standard), and AAA (enhanced). Level A covers the most critical barriers. Level AA adds the requirements that are broadly achievable without fundamentally changing content. Level AAA is aspirational and not required in most legal contexts. When someone says "WCAG compliant," they almost always mean Level AA.

The Four Principles (POUR)

Every WCAG success criterion maps to one of four principles:

• Perceivable (1.x): Users must be able to perceive all information — visually, auditorily, or through assistive tech.
• Operable (2.x): All UI functionality must be operable via keyboard alone, and navigation must be predictable.
• Understandable (3.x): Text must be readable, pages must behave predictably, and errors must be clearly communicated.
• Robust (4.x): Markup must be valid enough that assistive technologies can reliably parse and announce it.

The Criteria Developers Most Commonly Fail

1.1.1 — Non-text Content (Level A)

Every meaningful image, icon, and non-text element needs a text alternative. For <img> elements, this is the alt attribute. For decorative images, set alt="". For SVG icons inside buttons, add aria-label to the button and aria-hidden="true" to the SVG.

1.3.1 — Info and Relationships (Level A)

Structure that is conveyed visually must also be conveyed programmatically. Use <label> for form inputs (not placeholder text), use <th scope="col"> for table headers, use proper heading hierarchy, and use semantic HTML elements like <nav>, <main>, and <aside>.

1.4.3 — Contrast (Minimum) (Level AA)

Normal text must have a contrast ratio of at least 4.5:1 against its background. Large text (18pt regular or 14pt bold) requires 3:1. This is tested using the WCAG relative luminance formula — not visual judgment. Many design systems fail this criterion on their gray-on-white secondary text styles.

2.1.1 — Keyboard (Level A)

All functionality must be operable with a keyboard alone. Common failures are: custom dropdowns and modals that trap focus or are not keyboard navigable, onclick handlers on non-interactive elements like <div> without accompanying keyboard event handlers, and elements with tabindex="-1" that users need to reach.

2.4.4 — Link Purpose (Level AA)

Every link must communicate its purpose from its text alone. "Click here," "read more," and "learn more" fail this criterion when used without additional context, because a screen reader user navigating by links will hear only the link text with no surrounding context.

4.1.2 — Name, Role, Value (Level A)

For all UI components, the accessible name, role, and state must be programmatically determinable. A custom toggle switch built from a <div> must have role="switch", aria-checked, and an accessible name via aria-label.

WCAG 2.1's New Criteria (Compared to 2.0)

WCAG 2.1 added 17 criteria on top of WCAG 2.0. The most impactful for developers at Level AA are:

• 1.3.4 Orientation: Do not lock content to portrait or landscape orientation.
• 1.3.5 Identify Input Purpose: Use the HTML autocomplete attribute for personal data fields so password managers and autofill can assist users.
• 1.4.10 Reflow: Content must not require horizontal scrolling at 320px width (equivalent to 400% zoom on desktop).
• 1.4.11 Non-text Contrast: UI components like text input borders, checkboxes, and focus indicators must have at least 3:1 contrast against adjacent colors.
• 1.4.12 Text Spacing: Content must not break when users override line-height to 1.5x, letter-spacing to 0.12em, and word-spacing to 0.16em.
• 1.4.13 Content on Hover or Focus: Hover/focus-triggered tooltips must be dismissible, hoverable, and persistent.
• 2.5.3 Label in Name: Visible button/link labels must be included in the accessible name.

Testing Strategy for Developers

A practical testing approach combines three layers: automated scanning (fast, catches ~30–40% of failures), keyboard testing (tab through every interactive element on every page), and screen reader testing (NVDA + Firefox on Windows, VoiceOver + Safari on macOS). Start with automated scanning to clear the obvious failures, then invest time in the manual layers.