web-accessibility

Web Accessibility Guide

Applies to: Any website or web app | Updated: March 2026

A practical reference for building accessible websites - covering WCAG 2.2 criteria, semantic HTML, ARIA, forms, touch, and testing.

Section 0: Before You Start

Answer these questions before generating accessibility code. Each answer changes which sections apply.

Q: Where are your users? Default: worldwide - EU/UK requirements (EAA, PSBAR) will be flagged as applicable throughout this guide. Options: US only | Europe/EU | UK | Worldwide

Q: What kind of product is this? Default: company/marketing website Options: Company/marketing website | Online shop/e-commerce | Web app/SaaS | Media/video site | Document tool

Q: Will people use this on mobile phones or tablets as well as desktop? Default: yes - touch target sizing and pointer accessibility sections apply.

Q: Are you building with a component library? Default: none Options: Radix UI | shadcn/ui | MUI | Chakra UI | Other | None - if a library is detected in package.json, note which accessibility features it handles natively so you don't duplicate them.

Q: Do you need to comply with a specific standard for legal or contract reasons? Default: WCAG 2.2 AA - current best-practice baseline. Options: WCAG 2.1 AA | WCAG 2.2 AA | Section 508 | EN 301 549 | Not sure

AI assistant: Use these answers to prioritize. For EU products: apply EAA compliance notes. For mobile: apply touch target and pointer sections. If a known accessible component library is detected, note which patterns it handles so you don't duplicate effort.

Contents

1. [Legal & Compliance](#legal--compliance)
2. [WCAG Standards Overview](#wcag-standards-overview)
3. [WCAG 2.2 - What's New](#wcag-22--whats-new)
4. [Semantic HTML](#semantic-html)
5. [Keyboard Navigation](#keyboard-navigation)
6. [ARIA](#aria)
7. [Images & Media](#images--media)
8. [Forms](#forms)
9. [Touch & Pointer](#touch--pointer)
10. [Color & Contrast](#color--contrast)
11. [Focus Management](#focus-management)
12. [Motion & Animation](#motion--animation)
13. [Testing](#testing)
14. [Anti-Patterns to Flag](#anti-patterns-to-flag)
15. [Checklist by Product Type](#checklist-by-product-type)

Legal & Compliance

Accessibility is a legal requirement across most major markets. Non-compliance carries real risk - fines, market access restrictions, and litigation.

| Jurisdiction | Law / Standard | Scope | Notes | |---|---|---|---| | EU | European Accessibility Act (EAA) | Private-sector e-commerce, banking, transport, streaming. Enforceable since June 28, 2025. | Standard: EN 301 549 v3.2.1, which references WCAG 2.1 AA; WCAG 2.2 strongly recommended. Non-compliance = market access restrictions. | | US | ADA Title III | Private-sector websites and apps | ~4,000 - 4,500 lawsuits/year; e-commerce and hospitality are primary targets. Overlay-only solutions have been named in lawsuits as insufficient. | | US Federal | Section 508 | Federal agencies and contractors | References WCAG 2.0 AA. Agencies procuring software must meet this baseline. | | UK | Web Accessibility Regulations 2018 + Equality Act 2010 | Public sector: WCAG 2.2 AA required. Private sector: Equality Act applies. | PSBAR (Public Sector Bodies Accessibility Regulations) requires a published accessibility statement. |

Overlay warning: Single-script accessibility overlays (AccessiBe, UserWay, etc.) do not achieve WCAG conformance and have been directly challenged in ADA litigation. Flag this clearly if a user asks about "automatic" or "one-line" accessibility fixes.

WCAG Standards Overview

WCAG (Web Content Accessibility Guidelines) uses three conformance levels:

• Level A - minimum baseline; blocking failures (e.g. images with no alt)
• Level AA - standard legal requirement across most jurisdictions (e.g. 4.5:1 contrast)
• Level AAA - enhanced; not required site-wide but worth targeting for specific features

Target WCAG 2.2 Level AA as your default baseline.

On WCAG 3.0: It is a research-stage Working Draft with no published adoption timeline. It uses a different scoring model and will not replace WCAG 2.x for the foreseeable future. Do not use it as a current compliance target.

WCAG 2.2 - What's New

WCAG 2.2 was published October 2023. These criteria are not in most existing guides or tools. They represent the highest-value additions to implement.

2.4.11 Focus Appearance (AA)

The focus indicator must meet two conditions simultaneously:

1. Area: The focus indicator area must be at least as large as a 2px perimeter outline around the unfocused component.
2. Contrast: The color change between focused and unfocused states must have a contrast ratio of at least 3:1.

A 1px dotted border fails both. This goes beyond "don't remove outline."

/* Fails 2.4.11  -  thin, low-contrast */
:focus {
  outline: 1px dotted #999;
}

/* Passes 2.4.11  -  thick, high-contrast */
:focus-visible {
  outline: 3px solid #005fcc;  /* Check #005fcc vs background meets 3:1 */
  outline-offset: 2px;
}

2.5.7 Dragging Movements (AA)

Any interaction that uses drag-and-drop, slider, or map pan must have a single-pointer (click/tap) alternative. Drag is not a safe assumption - users with motor disabilities cannot rely on it.

<!-- Sortable list: provide up/down buttons alongside drag handles -->
<li>
  <span class="drag-handle" aria-hidden="true">⠿</span>
  Item label
  <button aria-label="Move item up">↑</button>
  <button aria-label="Move item down">↓</button>
</li>

2.5.8 Target Size Minimum (AA)

Interactive targets must be at least 24×24 CSS pixels, or have spacing such that the total clickable zone (target + surrounding space) reaches 24×24.

Best practice: 44×44px (Apple HIG), 48×48px (Material Design).

/* Minimum compliant  -  24×24px */
.icon-btn {
  min-width: 24px;
  min-height: 24px;
}

/* Best practice  -  44×44px tap target */
.icon-btn {
  min-width: 44px;
  min-height: 44px;
  display: inline-flex;
  align-items: center;
  justify-content: center;
}

3.3.8 Accessible Authentication (AA)

Login and signup flows cannot rely solely on a cognitive test (e.g. image CAPTCHA with no alternative). Acceptable alternatives: passkeys, magic link via email, CAPTCHA with an audio alternative, or copy-paste support in the password field.

Do not block clipboard paste in password fields - this breaks password managers and fails this criterion.

3.3.7 Redundant Entry (AA)

Multi-step forms must not ask for the same information twice unless it is essential to re-enter. Auto-populate or display previously entered data.

<!-- Step 2: shipping address  -  if billing address was entered in step 1 -->
<label>
  <input type="checkbox" id="same-as-billing" />
  Same as billing address
</label>

3.2.6 Consistent Help (AA)

If a help mechanism (chat widget, phone number, help link, contact form) appears on more than one page, it must appear in the same relative location on every page.

4.1.1 Parsing - Removed in WCAG 2.2

WCAG 2.2 removed criterion 4.1.1 Parsing. Modern browsers reliably handle malformed HTML; it no longer represents an accessibility barrier. Automated tools that still report 4.1.1 violations are reporting against a deprecated criterion. Remove it from test baselines if you're targeting WCAG 2.2.

Semantic HTML

Semantic HTML is the highest-value accessibility improvement - it is free, requires no ARIA, and works with all assistive technologies.

Page structure

<html lang="en">  <!-- Always declare language; use lang="fr" etc. for other languages -->
<head>
  <title>Page Title - Site Name</title>  <!-- Unique, descriptive title per page -->
</head>
<body>
  <header>
    <nav aria-label="Main">...</nav>
  </header>
  <main>          <!-- One <main> per page  -  screen readers jump here -->