1. a11y Is Not a “Need of a Few”#

Many teams treat accessibility (a11y) as a “compliance checkbox” before launch—until someone posts a screenshot in an issue showing “the Tab key can’t even reach the submit button.”

Accessibility actually serves far more users than you’d imagine:

• There are roughly 250 million visually impaired people worldwide, but the larger groups are those with color vision deficiency (about 8% of men), motor impairments, and cognitive disabilities;
• Everyone is “temporarily disabled” in certain scenarios: operating a phone one-handed on the subway, struggling to read low-contrast text in bright sunlight, or having to use only the keyboard because the mouse battery died;
• Screen reader users, voice control users, and magnifier users all browse the DOM in ways completely different from yours.

In other words, a11y isn’t charity for “marginalized groups”—it’s about keeping the interface usable across more input methods. And the cost, in the vast majority of cases, is simply “writing HTML correctly.”

Below is a practical checklist you can paste directly into your Code Review checklist.

2. First Priority: Semantic HTML#

Browsers come with a wealth of built-in accessibility semantics: <button> is naturally focusable and can be triggered with Space/Enter; <a> naturally enters the Tab sequence; <input> is naturally bound to a label; <nav>, <main>, and <header> naturally form landmarks that screen reader users can jump to with a single keystroke.

As long as you don’t abuse <div>, you get 80% of accessibility for free.

1
<!-- ❌ Anti-pattern: screen readers only see a pile of text -->
2
<div class="btn" onclick="submit()">Submit</div>
3
<div class="link" onclick="go()">View details</div>
4

5
<!-- ✅ Correct approach: semantics, focus, and keyboard events all come for free -->
6
<button type="submit">Submit</button>
7
<a href="/detail">View details</a>

A rule of thumb: if you’ve written onclick, tabindex="0", role="button", and keyboard event listeners for a div, you’re essentially hand-writing a <button>—just use it directly.

The same applies to page structure:

1
<body>
2
  <a class="skip-link" href="#main">Skip to main content</a>
3
  <header>
4
    <nav aria-label="Main navigation">...</nav>
5
  </header>
6
  <main id="main">
7
    <h1>Article title</h1>
8
    <!-- Don't skip heading levels: h1 → h2 → h3 -->
9
  </main>
10
  <footer>...</footer>
11
</body>

aria-label is used to distinguish multiple landmarks of the same type (when a page has two <nav> elements, screen readers need to know which is the main navigation and which is the footer navigation).

3. Keyboard Accessibility: Focus Is Part of the User Experience#

Walking through your core flows using only the keyboard (Tab / Shift+Tab / Enter / Esc / arrow keys) is the highest-ROI test you can do. Common problems cluster in three areas:

1. Custom components don’t manage focus. When a Modal opens, focus should move into the dialog and be “trapped” inside; when it closes, focus should return to the trigger button.

1
function openDialog(dialog, trigger) {
2
  const focusables = dialog.querySelectorAll(
3
    'a[href], button:not([disabled]), input, select, textarea, [tabindex]:not([tabindex="-1"])'
4
  );
5
  const first = focusables[0];
6
  const last = focusables[focusables.length - 1];
7

8
  dialog.showModal(); // Native <dialog> comes with focus trapping and Esc to close
9
  first?.focus();
10

11
  dialog.addEventListener('keydown', (e) => {
12
    if (e.key !== 'Tab') return;
13
    if (e.shiftKey && document.activeElement === first) {
14
      e.preventDefault();
15
      last.focus();
16
    } else if (!e.shiftKey && document.activeElement === last) {
17
      e.preventDefault();
18
      first.focus();
19
    }
20
  });
21

22
  dialog.addEventListener('close', () => trigger?.focus(), { once: true });
23
}

It’s worth emphasizing: the native <dialog> + showModal() already provides focus trapping, Esc to close, and background inerting for free. Hand-writing this logic is a hotspot for a11y bugs—if you can use the native solution, don’t reinvent it.

2. Focus styles are killed by outline: none. Globally removing focus outlines for the sake of “looking good” is equivalent to leaving keyboard users completely lost. The right approach is to keep it and make it prettier:

1
/* ❌ Don't do this */
2
*:focus { outline: none; }
3

4
/* ✅ Use :focus-visible to show it only for keyboard users, and ensure contrast */
5
:focus-visible {
6
  outline: 3px solid #2563eb;
7
  outline-offset: 2px;
8
  border-radius: 4px;
9
}

The beauty of :focus-visible is that mouse clicks don’t trigger the outline, but keyboard Tab does—preserving both the design mockup and usability.

3. Dynamic content changes aren’t announced. Form validation failures, Toast notifications, loading completion—these are “visible changes” to sighted users, but “nothing happened” to screen reader users. Use aria-live to announce them:

1
<div role="status" aria-live="polite" class="sr-only">
2
  Saved 3 changes
3
</div>
4
<!-- Use aria-live="assertive" for urgent errors; it interrupts the current announcement, so use with caution -->

Pair it with a utility class that’s visually hidden but readable by screen readers:

1
.sr-only {
2
  position: absolute;
3
  width: 1px;
4
  height: 1px;
5
  padding: 0;
6
  margin: -1px;
7
  overflow: hidden;
8
  clip-path: inset(50%);
9
  white-space: nowrap;
10
  border: 0;
11
}

4. ARIA: Use It as Little as Possible#

The first rule of ARIA is: if you can express the semantics with native HTML elements, don’t use ARIA. The behavior of native elements (keyboard interaction, focus management, state synchronization) is implemented by the browser, whereas ARIA only “tells the screen reader what this is”—it doesn’t handle behavior.

1
<!-- ❌ ARIA misuse: having a role but not implementing the behavior makes things worse -->
2
<div role="checkbox" aria-checked="false">Agree to terms</div>
3

4
<!-- ✅ Native elements: both behavior and semantics are correct -->
5
<label>
6
  <input type="checkbox" name="terms" />
7
  Agree to terms
8
</label>

There are three scenarios where ARIA genuinely earns its keep:

• States that native elements can’t express: aria-expanded (collapsible panels), aria-current="page" (current navigation item), aria-invalid (validation failure);
• Relationships that native elements can’t express: aria-describedby (associating help text with an input), aria-controls;
• Custom composite components: such as combobox, tree, tablist—these should directly adopt the patterns given in the WAI-ARIA Authoring Practices rather than being invented from scratch.

One high-frequency detail that’s almost always overlooked is the “icon button”:

1
<!-- With only an SVG icon, screen reader users hear "button" and don't know what it does -->
2
<button><svg aria-hidden="true">...</svg></button>
3

4
<!-- ✅ Provide an accessible name while hiding decorative icons from AT -->
5
<button aria-label="Close dialog">
6
  <svg aria-hidden="true" focusable="false">...</svg>
7
</button>

5. Visual and Perceptual: Contrast, Motion, and Not Conveying Information by Color Alone#

Contrast is the most quantifiable item in WCAG: body text against its background must be at least 4.5:1, large text (≥18.66px bold or ≥24px) at least 3:1, and UI component boundaries at least 3:1. The “premium feel design” of light gray text on a gray background is often the worst offender.

Don’t convey information by color alone—this is the core pain point for users with color vision deficiency:

1
<!-- ❌ Indicating errors with red alone -->
2
<input style="border-color: red" />
3

4
<!-- ✅ Color + icon + text, triple redundancy -->
5
<input aria-invalid="true" aria-describedby="email-error" />
6
<p id="email-error" class="error">
7
  <span aria-hidden="true">⚠</span> Email address is not valid — check for a missing @
8
</p>

Respect users’ motion preferences. Users with vestibular disorders may experience dizziness from parallax scrolling or large displacement animations, and the system-level setting can be read directly:

1
@media (prefers-reduced-motion: reduce) {
2
  *, *::before, *::after {
3
    animation-duration: 0.01ms !important;
4
    animation-iteration-count: 1 !important;
5
    transition-duration: 0.01ms !important;
6
    scroll-behavior: auto !important;
7
  }
8
}

Note that this isn’t about “turning off all animations,” but about downgrading decorative displacement to non-moving opacity changes, so that the information is still fully conveyed.

6. Forms: Error messages must clearly state “how to fix it”#

Forms are where interaction is the most complex and where a11y issues are most likely to arise. Three hard requirements:

1. Every control must have a programmatically associated label (<label for>, a wrapping label, or aria-label);
2. Error messages must explain in text how to fix the problem, and be associated with the corresponding control;
3. When an error occurs, move focus to the first control with an error, and make the aria-invalid state readable.

1
<form novalidate>
2
  <div class="field">
3
    <label for="email">Email address</label>
4
    <input
5
      id="email"
6
      name="email"
7
      type="email"
8
      required
9
      aria-describedby="email-hint email-error"
10
      aria-invalid="false"
11
    />
12
    <p id="email-hint" class="hint">Used to receive login verification codes, will not be made public</p>
13
    <p id="email-error" class="error" role="alert" hidden></p>
14
  </div>
15
  <button type="submit">Register</button>
16
</form>

1
form.addEventListener('submit', (e) => {
2
  e.preventDefault();
3
  const firstInvalid = form.querySelector('input:invalid');
4

5
  form.querySelectorAll('[aria-invalid]').forEach((el) => {
6
    const error = document.getElementById(`${el.id}-error`);
7
    el.setAttribute('aria-invalid', String(el.matches(':invalid')));
8
    error.hidden = el.validity.valid;
9
    error.textContent = el.validity.valid
10
      ? ''
11
      : el.validity.valueMissing
12
        ? 'This field is required, please enter your email address'
13
        : 'Invalid email format, should look like name@example.com';
14
  });
15

16
  firstInvalid?.focus();
17
});

Note that role="alert" only renders text when an error appears, avoiding empty elements being announced on page load.

7. Testing: automate 40%, test manually 60%#

Automated tools can efficiently find “structural problems” — missing alt, insufficient contrast, missing labels, misspelled ARIA attributes.

1
npm i -D @axe-core/cli
2
npx axe https://your-site.com --exit

Integrating into E2E only takes a few lines:

1
import AxeBuilder from '@axe-core/playwright';
2
import { test, expect } from '@playwright/test';
3

4
test('No accessibility violations on the home page', async ({ page }) => {
5
  await page.goto('/');
6
  const results = await new AxeBuilder({ page })
7
    .withTags(['wcag2a', 'wcag2aa', 'wcag22aa'])
8
    .analyze();
9
  expect(results.violations).toEqual([]);
10
});

But automation cannot detect these issues, which must be done manually:

• Unplug the mouse and complete the main flows of registration / checkout / form submission using only the keyboard;
• Turn on VoiceOver (macOS Cmd+F5) or NVDA, and listen to whether the page structure makes sense;
• Zoom the browser to 200% and check whether content is still readable and does not overlap;
• Force-enable prefers-reduced-motion and high contrast mode, and confirm the interface does not break.

8. Conclusion#

Accessibility is not a project that can be “finished,” but a set of ongoing engineering habits. When implementing it, it is recommended to proceed in this order:

1. Semantic HTML — lowest cost, greatest benefit; replace div buttons;
2. Keyboard accessible + visible focus — a single :focus-visible style can save the day;
3. Do not convey information by color alone + meet contrast requirements — most issues can be solved once and for all with design tokens;
4. Readable form errors — directly affects conversion rates, and business stakeholders are happy to pay for it;
5. Run axe in CI — blocking regressions is far cheaper than auditing after the fact.

A commonly cited point is: when accessibility is done right, everyone’s experience improves — clearer heading hierarchy, more explicit error messages, more predictable keyboard interaction. It is essentially a byproduct of good engineering practice, not an extra burden.

References#

• W3C — Web Content Accessibility Guidelines (WCAG) 2.2
• MDN — Accessibility
• WAI-ARIA Authoring Practices Guide (APG)
• Deque — axe-core rule set documentation
• The A11Y Project — Web Accessibility Checklist
• MDN — :focus-visible