Accessibility (a11y)

Accessibility (a11y) is the practice of building products that people with disabilities can use. Around 15% of the world’s population lives with some form of disability — visual, motor, auditory, or cognitive. Accessibility is not a feature you add at the end; it is a quality attribute baked into every component you build.

WCAG Levels

The Web Content Accessibility Guidelines (WCAG) define three conformance levels:

Level	Description	Target
A	Minimum — must not block access	Required baseline
AA	Standard — most accessibility needs	Target for most products
AAA	Enhanced — maximally inclusive	Aspirational for specific content

Most legal standards (ADA, EN 301 549, AODA) require WCAG 2.1 AA. WCAG 2.2 added new criteria around focus and dragging; WCAG 3.0 is in development.

Semantic HTML

Semantic HTML gives the browser and assistive technology the correct role and name for each element without any ARIA. A button that submits a form is <button>, not <div class="button">. A landmark that contains navigation is <nav>, not <div class="nav">.

<!-- ❌ Bad: role and keyboard behavior must be faked with ARIA + JS -->
<div class="btn" onclick="submit()">Submit</div>

<!-- ✅ Good: semantics, keyboard, and focus come for free -->
<button type="submit">Submit</button>

Key semantic elements: <header>, <main>, <nav>, <aside>, <footer>, <article>, <section>, <h1>–<h6>, <button>, <a href>, <label>, <fieldset>, <legend>.

TIP

Screen readers use heading levels to build a document outline. Never skip heading levels (e.g., jump from <h2> to <h4>) just for visual sizing. Use CSS to control the size; use heading levels to communicate hierarchy.

ARIA Roles, Properties, and States

Use ARIA to fill gaps where HTML semantics are insufficient — custom components like date pickers, comboboxes, or tabs:

<!-- ARIA role tells assistive tech what the element is -->
<div role="tablist" aria-label="Settings panels">
  <button role="tab" aria-selected="true" aria-controls="panel-general">General</button>
  <button role="tab" aria-selected="false" aria-controls="panel-privacy">Privacy</button>
</div>
<div id="panel-general" role="tabpanel" tabindex="0">...</div>

Properties describe what an element is (aria-label, aria-labelledby, aria-describedby, aria-controls). States describe what an element is currently doing (aria-selected, aria-expanded, aria-checked, aria-disabled).

WARNING

The first rule of ARIA is: do not use ARIA if you can use native HTML. Adding role="button" to a <div> does not give you keyboard behavior, click-on-Space, or focus styling — you must implement all of that yourself. A <button> does it automatically.

Every interactive element must be reachable and operable with a keyboard alone. Users navigate with Tab (forward), Shift+Tab (backward), Enter/Space (activate), and arrow keys (within widgets like menus and tabs).

Rules:

Do not remove focus outlines without providing an equivalent replacement
tabindex="0" adds an element to the tab order in DOM sequence
tabindex="-1" removes an element from the tab order but keeps it programmatically focusable
Never use positive tabindex values — they break the natural order

Focus management: when you open a modal dialog, move focus into it. When you close it, return focus to the element that opened it:

const triggerRef = useRef<HTMLButtonElement>(null);
const modalRef = useRef<HTMLDivElement>(null);

function openModal() {
  setOpen(true);
  // Focus moves to the modal after the next render
  requestAnimationFrame(() => modalRef.current?.focus());
}

function closeModal() {
  setOpen(false);
  triggerRef.current?.focus(); // return focus to trigger
}

Color Contrast

WCAG 2.1 AA requires:

4.5:1 contrast ratio for normal text (under 18pt / 14pt bold)
3:1 for large text and UI components (borders, icons)

IMPORTANT

Contrast failures are the most common WCAG violation in real-world audits. Always verify contrast with a tool — perceived brightness is not a reliable judge.

Auditing with axe DevTools

axe DevTools (browser extension) catches ~57% of WCAG issues automatically. Run it on every page before shipping. Each violation includes impact level (critical, serious, moderate), the affected element, and a fix description.

Automated tools cannot catch everything — missing captions on video, logical reading order issues, and complex keyboard patterns require manual testing. Test with VoiceOver (macOS/iOS) or NVDA (Windows) and a keyboard only.

NOTE

The a11yproject.com checklist is a practical, plain-language reference for manual testing across all WCAG 2.1 AA criteria.

Further Learning

Search these terms to go deeper:

“WCAG 2.1 quick reference” — filterable list of every success criterion with techniques
“a11yproject.com checklist” — plain-language manual testing checklist
“WebAIM million report” — annual automated audit of the top 1 million homepages; shows the most common failures
“ARIA authoring practices guide APG” — WAI-ARIA patterns for every common widget with keyboard behavior specs
“axe DevTools browser extension” — free automated accessibility scanner with guided remediation

Accessibility (a11y)

Accessibility (often shortened to “a11y” — an “a”, 11 letters, then “y”) means building things people with disabilities can actually use — folks who are blind, can’t use a mouse, are colorblind, and more. It’s not an add-on at the end; it’s a quality you build in from the start. And it makes your site better for everyone.

The single biggest win: use the right HTML

Most accessibility comes free if you use real HTML elements instead of faking them with <div>s:

<!-- ❌ A fake button — no keyboard support, screen readers ignore it -->
<div class="btn" onclick="submit()">Submit</div>

<!-- ✅ A real button — keyboard, focus, and screen-reader support built in -->
<button type="submit">Submit</button>

A real <button> can be tabbed to, pressed with Enter or Space, and is announced correctly — all for free. A <div> gives you none of that.

WARNING

The first rule of ARIA (accessibility attributes) is: don’t use ARIA if plain HTML can do it. Use <button>, <nav>, <label>, headings, and links, and you’ve done most of the work already.

Make everything keyboard-friendly

Lots of people navigate without a mouse. Every button, link, and input must be reachable with Tab and usable with Enter/Space. Two rules:

Don’t remove the focus outline (the ring showing where you are) without adding your own.
When you open a popup/modal, move focus into it — and when it closes, send focus back to what opened it.

Check your colors

Text needs enough contrast against its background or people can’t read it. The standard (WCAG AA) asks for a 4.5:1 ratio for normal text. Don’t eyeball it — use a contrast checker.

IMPORTANT

Low color contrast is the most common accessibility problem on real websites. Always verify with a tool.

Scan your page automatically

Install the free axe DevTools browser extension and run it on your pages. It instantly flags many issues (missing labels, low contrast, bad structure) with plain-language fixes. It won’t catch everything, so also try tabbing through with just your keyboard.

The standard to aim for

Accessibility guidelines (WCAG) have three levels: A (bare minimum), AA (the real target — what most laws require), and AAA (extra strict). Aim for AA.

In one sentence

Use real HTML elements (not <div>s pretending to be buttons), make everything keyboard-operable, ensure enough color contrast, and scan with axe DevTools — targeting the WCAG AA level.

Want to go deeper?

Switch to Expert mode above for ARIA roles/states, focus-management code, the full WCAG levels, and screen-reader testing.

Accessibility (a11y)

WCAG Levels

Semantic HTML

ARIA Roles, Properties, and States

Keyboard Navigation

Color Contrast

Auditing with axe DevTools

Further Learning

Accessibility (a11y)

The single biggest win: use the right HTML

Make everything keyboard-friendly

Check your colors

Scan your page automatically

The standard to aim for

In one sentence

Want to go deeper?