/web-accessibility

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`."

/* 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