---
name: web-accessibility
description: 'Use this skill whenever the user is building or reviewing any web UI. Accessibility is a baseline requirement, not a niche concern. Covers WCAG 2.2 AA, semantic HTML, ARIA patterns, keyboard navigation, focus management, color contrast, touch targets, forms, and testing with axe / screen readers. Trigger when generating any interactive component or page (forms, modals, menus, tables, navigation, layouts), before any "launch" or "go live", during pre-launch checklists, and whenever producing new HTML/JSX markup, even if the user does not explicitly mention a11y or WCAG. Skip for backend-only changes, CLI tools, or non-UI code.'
---
# 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`."
```css
/* 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.
```html
⠿
Item label
```
### 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).
```css
/* 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.
```html
```
### 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
Page Title - Site Name
Page Heading
Section Title
```
For inline content in a different language, add the `lang` attribute on the element - screen readers use this to switch pronunciation:
```html
The French say bonjour as a greeting.
```
### Use the right element
Native HTML elements carry built-in keyboard support, roles, and states. Prefer them over custom implementations. Use `