Fixing Common Violations: Contrast, Forms and ARIA
On this page
- The broken form
- 1. label: the input has no accessible name
- 2. color-contrast: the hint text is too light
- 3. aria-required-attr: a fake checkbox
- 4. button-name: an icon-only button
- 5. aria-hidden-focus: a hidden link you can still tab to
- The fixed form, and proving it
- Patterns that come up again and again
Finding violations is the easy half. This chapter takes a small sign-up form with five of the most common WCAG failures, shows what axe reports for each and fixes them properly. "Properly" matters here: for most of these rules there is a quick fix that makes axe go quiet without helping anyone, and the chapter points those out as it goes.
The broken form#
Save this as tests/pages/signup-broken.html:
<!doctype html>
<html lang="en">
<head><title>Sign up</title></head>
<body>
<main>
<h1>Create your account</h1>
<form>
<input id="email" type="email" autocomplete="email">
<p class="hint" style="color:#999">We never share your email.</p>
<div class="toggle" role="checkbox" tabindex="0">Send me product news</div>
<button type="submit">
<svg width="16" height="16" aria-hidden="true"><path d="M2 8h12"/></svg>
</button>
<a href="/terms" aria-hidden="true">Terms</a>
</form>
</main>
</body>
</html>
It looks plausible, and with a mouse it mostly works. A test pins down what axe thinks of it. page.setContent() loads the HTML straight into the browser, so there is no server to run, and it works the same on a remote browser:
import fs from 'node:fs';
import path from 'node:path';
import { test, expect, WCAG_AA } from './axe';
import AxeBuilder from '@axe-core/playwright';
const readPage = (name: string) => fs.readFileSync(path.join(__dirname, 'pages', name), 'utf8');
test('broken sign-up form: the violations axe reports', async ({ page }) => {
await page.setContent(readPage('signup-broken.html'));
const results = await new AxeBuilder({ page }).withTags(WCAG_AA).analyze();
// Safari also reports target-size: WebKit renders the empty button smaller than 24px.
expect(results.violations.map(v => v.id)).toEqual(expect.arrayContaining([
'aria-hidden-focus',
'aria-required-attr',
'button-name',
'color-contrast',
'label',
]));
});
Five rules fail in Chromium and Firefox. In Safari a sixth appears: WebKit lays out the empty button at 32 by 23.3 pixels, under the 24 pixel minimum of WCAG 2.2's target-size rule. The same markup can produce different results per engine, which is why chapter 7 scans in more than one browser and why this test uses arrayContaining.
1. label: the input has no accessible name#
axe reports the email input as "Form elements must have labels". A screen reader announces it as "edit text", with no hint of what to type (WCAG 1.3.1 and 4.1.2).
Fix: a visible <label> tied to the input with for and id:
<label for="email">Email address</label>
<input id="email" type="email" autocomplete="email" aria-describedby="email-hint">
A visible label helps everyone, including voice control users who say "click Email address", and clicking it focuses the input.
The tempting non-fix: placeholder="Email address". axe accepts a placeholder as a name, so the violation disappears, but the placeholder vanishes as soon as someone types, usually has poor contrast, and is not a label to many users. Chapter 8 shows a scan that passes with exactly this pattern.
2. color-contrast: the hint text is too light#
#999 on white is 2.85:1. Normal-size text needs at least 4.5:1, large text (24px, or about 18.7px bold) at least 3:1 (WCAG 1.4.3).
Fix: a darker colour. #767676 is the lightest grey that passes on white, at 4.54:1; the fixed form uses #595959, which reaches 7:1 and leaves room for anti-aliasing and screen glare. Fix contrast in your design tokens rather than per element, or the next component reintroduces the old grey.
Remember chapter 2's TodoMVC filter links at #777: 4.48:1, rounded by axe to 4.47:1. There is no "close enough"; the threshold is the threshold. Contrast over images and gradients usually lands in incomplete instead, and needs a person with a contrast checker.
Body text at 16px measures 4.4:1 against its background. Which statement is correct?
3:1 applies only to large text (24px, or about 18.7px bold). 16px regular text needs 4.5:1, and the threshold is not rounded. AAA (1.4.6) asks for 7:1.
3. aria-required-attr: a fake checkbox#
<div class="toggle" role="checkbox" tabindex="0">Send me product news</div>
role="checkbox" promises assistive technology a checkbox, and a checkbox must say whether it is checked, so axe reports the missing aria-checked. Adding aria-checked="false" silences axe, but the div still needs JavaScript to toggle the attribute, to handle Space, and to keep the state in sync with the form data. Miss any of that and keyboard and screen reader users get a control that lies about its state.
Fix: the first rule of ARIA, use the native element:
<label><input type="checkbox" name="news"> Send me product news</label>
Native form controls come with focus, keyboard handling, state, form submission and a name from the wrapping label. Style them with CSS (appearance, accent-color) instead of rebuilding them.
4. button-name: an icon-only button#
The submit button contains only an SVG marked aria-hidden="true", so it has no accessible name. A screen reader says "button", and nobody knows what it does (WCAG 4.1.2).
Fix: visible text, which also helps users who do not recognise the icon:
<button type="submit">
<svg width="16" height="16" aria-hidden="true"><path d="M2 8h12"/></svg>
Create account
</button>
If the design really has no room for text, as in a toolbar, use aria-label="Create account" on the button, keep the SVG hidden, and give it a tooltip. The name must describe the action, not the icon: "Delete", not "Trash can".
5. aria-hidden-focus: a hidden link you can still tab to#
aria-hidden="true" removes an element from the accessibility tree, but not from the tab order. A keyboard user lands on the Terms link and the screen reader announces nothing, or something confusing. This usually comes from hiding "decorative" content too broadly, or from off-screen menus that are hidden with ARIA but not with CSS or inert.
Fix: if the link is meant for everyone, remove aria-hidden:
<a href="/terms">Terms</a>
If it is really meant to be hidden, such as a closed menu, hide it for everyone with hidden, display: none or the inert attribute, which removes it from both the tab order and the accessibility tree.
A closed off-canvas menu is moved off screen with CSS and marked aria-hidden="true". axe reports aria-hidden-focus. What is the right fix?
The real bug is that keyboard users can tab into an invisible menu. inert or display: none removes it from the tab order and the accessibility tree together. Removing aria-hidden would make screen readers read a closed menu.
The fixed form, and proving it#
tests/pages/signup-fixed.html puts the fixes together:
<!doctype html>
<html lang="en">
<head><title>Sign up</title></head>
<body>
<main>
<h1>Create your account</h1>
<form>
<label for="email">Email address</label>
<input id="email" type="email" autocomplete="email" aria-describedby="email-hint">
<p id="email-hint" class="hint" style="color:#595959">We never share your email.</p>
<label><input type="checkbox" name="news"> Send me product news</label>
<button type="submit">
<svg width="16" height="16" aria-hidden="true"><path d="M2 8h12"/></svg>
Create account
</button>
<a href="/terms">Terms</a>
</form>
</main>
</body>
</html>
aria-describedby links the hint to the input, so a screen reader reads "Email address, edit text, We never share your email." The test checks both what axe says and what assistive technology will get:
test('fixed sign-up form has no WCAG A/AA violations', async ({ page }) => {
await page.setContent(readPage('signup-fixed.html'));
const results = await new AxeBuilder({ page }).withTags(WCAG_AA).analyze();
expect(results.violations).toEqual([]);
await expect(page.getByRole('textbox', { name: 'Email address' })).toHaveAccessibleDescription(
'We never share your email.',
);
await expect(page.getByRole('button', { name: 'Create account' })).toBeVisible();
});
The last two lines are not axe. getByRole with a name finds elements the way the browser's accessibility tree exposes them, and toHaveAccessibleDescription checks the computed description. If someone later deletes the label, these locators stop matching even if a placeholder keeps axe happy. Both tests pass in Chromium, Firefox and Safari.
Patterns that come up again and again#
-
Images: informative images get
alttext that says what the image means in context; decorative images getalt="". Do not repeat "image of" (the screen reader already says "image"). - Links: the text must make sense on its own. "Read more" ten times in a list is useless in a screen reader's links list. Use "Read more about pricing", or visually hidden extra text.
-
Errors: connect each error message to its field with
aria-describedby, setaria-invalid="true"on the field, and move focus to the first invalid field or a summary on submit. -
Language:
<html lang="en">. One attribute, and every screen reader pronounces the page correctly. -
Dialogs: use the native
<dialog>element withshowModal(). It traps focus inside, closes onEscapeand makes the rest of the page inert.
Every fix in this chapter replaced custom markup with a native element or a native relationship. That is the pattern to look for first whenever axe reports an ARIA rule.