A menu that doesn’t open with the keyboard, an unlabeled form field, a “button” made with a div: each a small mistake on its own. The problem is when they show up in the pre-release audit report, copied from the component library across dozens of screens. At that point, fixing them is expensive. This guide translates WCAG 2.2 success criteria into the daily decisions of a front-end developer: semantic HTML, ARIA, keyboard and focus, forms, contrast and the testing flow, at component level.
WCAG structure and conformance levels
WCAG (Web Content Accessibility Guidelines) is published by the W3C and rests on four principles: perceivable, operable, understandable and robust (POUR). Under each principle are guidelines, and under the guidelines are testable success criteria. Each criterion is at level A, AA or AAA; in corporate web projects and in legislative references, the target is usually AA, meaning all A and AA criteria.
WCAG 2.2 added new criteria on top of 2.1 and removed criterion 4.1.1 Parsing. The new criteria that directly concern developers are these:
| Criterion | Level | What it means in code |
|---|---|---|
| 2.4.11 Focus Not Obscured (Minimum) | AA | A sticky header/cookie banner mustn’t completely cover the focused element |
| 2.5.7 Dragging Movements | AA | Drag-and-drop operations must have a single-pointer alternative |
| 2.5.8 Target Size (Minimum) | AA | Click targets at least 24×24 CSS pixels or with sufficient spacing |
| 3.2.6 Consistent Help | A | The help link in the same relative position across pages |
| 3.3.7 Redundant Entry | A | Information entered in the same process mustn’t be requested again, or must be auto-filled |
| 3.3.8 Accessible Authentication (Minimum) | AA | No mandatory cognitive test at sign-in; password managers and pasting mustn’t be blocked |
The primary source for the full text of the criteria and the “Understanding” documents is the W3C WCAG 2.2 Recommendation page. When interpreting a criterion, look at the examples and exceptions in these documents, not at a blog post. That’s where the debate ends.
Using semantic HTML and ARIA
Most accessibility errors are solved with the right HTML element. A <button> is focusable with the keyboard, triggered with Enter and Space, and announced to screen readers as a “button”. Getting the same behavior with <div onclick> requires adding tabindex, role and keyboard event handlers; in code review we often see at least one of them missing. Criteria 1.3.1 Info and Relationships and 4.1.2 Name, Role, Value are the direct counterparts of these errors.
- Use
header,nav,mainandfooterfor page regions; screen reader users jump between these regions. - Choose the heading level by content hierarchy, not visual size; CSS sets the appearance.
<a href>for navigation,<button>for actions. A “button” that changes the page or a “link” that performs an action breaks user expectations.- Mark up tabular data with
<table>and header cells with<th scope>.
The first rule of ARIA: if there’s an equivalent native HTML element, don’t use ARIA. ARIA only changes the information in the accessibility tree; it doesn’t add behavior. An element given role="button" still can’t be triggered with the keyboard. A role is a label, not an engine. Where ARIA is really needed is for components with no equivalent in HTML: tabs, combobox, tree view, menu button. The expected roles, states and keyboard behaviors of these patterns are defined in the W3C ARIA Authoring Practices Guide; don’t deviate from these patterns when writing custom components.
<!-- Wrong: the icon button has no accessible name -->
<button><svg>…</svg></button>
<!-- Right: invisible name + decorative icon -->
<button aria-label="Clear filters">
<svg aria-hidden="true" focusable="false">…</svg>
</button>
<!-- Disclosure panel: state is announced with ARIA -->
<button aria-expanded="false" aria-controls="filter-panel">Filters</button>
<div id="filter-panel" hidden>…</div>
Keyboard access and focus management
2.1.1 Keyboard requires all functions to be usable with the keyboard, and 2.1.2 No Keyboard Trap requires that focus isn’t trapped in a component after entering it. 2.4.3 Focus Order requires the order to be meaningful, and 2.4.7 Focus Visible requires focus to be visible. In code, this means:
- Don’t use positive
tabindexvalues (1, 2, 3…); DOM order determines focus order. If the visual order has been separated from the DOM order with CSS (e.g.order,flex-direction: row-reverse), focus appears to jump around randomly to the user. - If you’ve removed the focus ring with
outline: none, define a clear alternative with:focus-visible. The mistake we find most often in the field is a CSS reset file silently removing the focus ring. - When a modal opens, move focus inside it, prevent it from escaping to the background while open, close it with Escape and return focus to the button that opened the modal when it closes. The native
<dialog>element’sshowModal()method makes the background inert and provides the Escape behavior. - In single-page apps, when the route changes, focus stays on the clicked link on the old page. Move focus to the new page’s main heading (with
tabindex="-1") and updatedocument.title. - Put a “Skip to content” link before long navigation menus (2.4.1 Bypass Blocks).
/* Focus visibility: a clear ring only on keyboard focus */
:focus-visible {
outline: 3px solid var(--color-focus);
outline-offset: 2px;
}
/* Keep the sticky header from covering the focused element (2.4.11) */
html { scroll-padding-top: 5rem; }
Forms, error messages and dynamic content
In custom web applications, forms are where accessibility errors are most concentrated. Every field must have a programmatically associated label (<label for>). A placeholder doesn’t replace a label: it disappears once you start typing, and its contrast is usually low. Related fields (an address block, a radio group) are grouped with <fieldset> and <legend>.
On the error side, 3.3.1 Error Identification requires the error to be described in text, and 3.3.3 Error Suggestion requires a correction suggestion where possible. A red border alone isn’t enough (1.4.1 Use of Color). A color-blind user can’t see which field is wrong.
<label for="tax-no">Tax number</label>
<input id="tax-no" name="taxNo" inputmode="numeric"
autocomplete="off"
aria-invalid="true"
aria-describedby="tax-no-hint tax-no-error">
<p id="tax-no-hint">Enter your 10-digit tax number.</p>
<p id="tax-no-error">The tax number must be 10 digits.</p>
If there’s more than one error on submission, put an error summary at the top of the form and move focus there, linking each item in the summary to the relevant field. Setting up validation rules consistently on client and server and mapping server errors to fields are covered in the managing form validation with a single schema guide.
Content that changes without a page reload (“Saved”, “3 results found”, a background job finishing) falls under 4.1.3 Status Messages. These messages are announced without moving focus: role="status" (polite, read at the next opportunity) or role="alert" for urgent errors. The live region element must exist in the DOM before the content changes. A live region added to the DOM at the same time as the message isn’t announced reliably in many screen reader–browser combinations; this is often the reason for notifications that “work for us” but stay silent in NVDA.
Contrast, motion and visual layout
| Topic | Criterion | Threshold |
|---|---|---|
| Normal text contrast | 1.4.3 (AA) | At least 4.5:1 |
| Large text contrast | 1.4.3 (AA) | At least 3:1 (18 pt, or 14 pt bold) |
| UI component and graphics contrast | 1.4.11 (AA) | At least 3:1 |
| Reflow | 1.4.10 (AA) | No horizontal scrolling at a width of 320 CSS pixels |
| Resize text | 1.4.4 (AA) | No loss of function at 200% zoom |
Don’t measure contrast screen by screen; verify it at the level of design tokens and keep a list of approved color pairs. This approach is explained together with token management in the corporate design system guide. Disabled components are exempt from the contrast criterion; but if the user can’t understand why something is disabled, that’s still a usability problem.
Parallax, auto-rotating carousels and large transition animations affect users with vestibular disorders. 2.2.2 Pause, Stop, Hide (A) requires that motion that starts automatically, lasts more than five seconds and is presented alongside other content can be paused, stopped or hidden. Respecting the operating system’s “reduce motion” preference takes a few lines; the example below does it with a general rule:
@media (prefers-reduced-motion: reduce) {
*, *::before, *::after {
animation-duration: 0.01ms !important;
animation-iteration-count: 1 !important;
transition-duration: 0.01ms !important;
scroll-behavior: auto !important;
}
}
Testing method and component checklist
Automated tools (axe-core, the Lighthouse accessibility audit, WAVE) quickly catch missing alt text, low contrast, unlabeled fields and invalid ARIA attributes. They can’t assess whether the focus order is logical, whether alt text says anything meaningful or whether a modal can be used with the keyboard. A green report doesn’t mean an accessible application. That’s why you should set up the testing flow in three layers:
- Development and CI: In component tests, run automated scans for every component and critical page using
jest-axeor Playwright with@axe-core/playwright; if a new violation appears, the build should break. - Keyboard testing: Put the mouse aside. Complete every workflow from start to finish with Tab, Shift+Tab, Enter, Space, Escape and the arrow keys. Focus must be visible at all times and the order logical.
- Screen reader testing: Listen to critical flows with NVDA on Windows, VoiceOver on macOS and iOS, and TalkBack on Android. Every component’s name, role and state must be read correctly, and status messages must be announced.
// Page scan with Playwright + axe
import { test, expect } from '@playwright/test';
import AxeBuilder from '@axe-core/playwright';
test('order list has no WCAG AA violations', async ({ page }) => {
await page.goto('/orders');
const results = await new AxeBuilder({ page })
.withTags(['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa', 'wcag22aa'])
.analyze();
expect(results.violations).toEqual([]);
});
Component checklist
- Button: A native
<button>; an accessible name on icon buttons; a target size of at least 24×24 CSS pixels. - Modal: Focus moves inside on open, it closes with Escape, focus returns on close, and its title is associated with
aria-labelledby. - Dropdown / combobox: Arrow key behavior following the APG pattern,
aria-expandedkept current, the selected option announced. - Form field: A visible label, hint and error associated with
aria-describedby, the error expressed in text,autocompleteset to the right value. - Table: Header cells with
thandscope;aria-sorton sortable columns. - Notification: A
role="status"region already present in the DOM; enough time or a persistent alternative for notifications that disappear on their own. - Image: Descriptive
alton meaningful images, emptyalt=""on decorative ones.
If you solve accessibility at the component library level, the same mistake isn’t made again on every screen; the fix is made once and spreads everywhere. To build an accessible component set together with a design system, see our UI/UX and corporate design system service page.
Frequently asked questions
Which WCAG level should a corporate web application aim for?
The common target is WCAG 2.2 level AA, which means meeting all success criteria at levels A and AA. Since not all AAA criteria are applicable to every type of content, usually only selected criteria are targeted.
Are automated accessibility tools enough?
No. axe-core or Lighthouse find errors a machine can measure, such as contrast, missing labels and invalid ARIA. The logic of the focus order, the meaningfulness of alt text and the usability of complex components require manual testing with a keyboard and a screen reader.
Does adding ARIA always improve accessibility?
No. ARIA only changes the information passed to assistive technology; it doesn’t add behavior. ARIA added with the wrong role or missing keyboard support can give a worse result than having no ARIA at all. Use the native HTML element first.
Which areas are affected most when moving to WCAG 2.2?
The areas most often affected are small click targets, sticky headers covering the focused element, interfaces that work by drag and drop, and sign-in screens that block password pasting or require a cognitive test.