Home › Accessibility › Web accessibility (WCAG 2.2) rules

Web accessibility (WCAG 2.2) rules

Windsurf rules for building accessible web UIs to WCAG 2.2 AA: semantics, keyboard, focus, contrast, and testing.

WindsurfAccessibility

Copy accessibility.md

How to use

Save this as .windsurf/rules/accessibility.md in your repository root, commit it, and your agent will pick it up automatically. Edit the commands to match your project.

# Accessibility (WCAG 2.2 AA)

## Semantics first
- Use native elements: `<button>` for actions, `<a href>` for navigation, `<label for>` for inputs, headings in order (one `<h1>` per page), landmarks (`<header>`, `<nav>`, `<main>`, `<footer>`).
- ARIA only when no native element fits; then follow the APG pattern exactly. No `role="button"` on a `<div>` when a `<button>` works.
- Every image has `alt` (empty `alt=""` for decorative). Icon-only buttons get an `aria-label`.

## Keyboard and focus
- Everything works with keyboard only: Tab order follows visual order, no `tabindex` > 0.
- Visible focus indicator on all interactive elements; never `outline: none` without a replacement.
- Dialogs trap focus, close on Esc, and return focus to the trigger (use `<dialog>` or the UI library's accessible dialog).
- Targets are at least 24x24 CSS px.

## Forms
- Errors are announced (`aria-describedby` to the message, `aria-invalid="true"`), not shown by color alone.
- Use `autocomplete` attributes for personal data fields.

## Visual
- Text contrast >= 4.5:1 (3:1 for large text and UI components). Support 200% zoom and reflow at 320px width.
- Respect `prefers-reduced-motion`.

## Dynamic content
Announce async updates with a polite live region (`aria-live="polite"`).

## Check
Run axe (`@axe-core/playwright` or the browser extension) on changed pages with zero violations, and tab through the flow once.