Awesome Accessibility Audit

Accessibility Audit

Review UI and markup for accessibility and suggest concrete fixes aligned with WCAG so all users can perceive, operate, and understand the interface.

When to Activate

• User asks for "accessibility", "a11y", "WCAG", or "screen reader support"
• Before shipping a new page or component
• Reviewing forms, modals, or interactive UI
• After a design or UI change that affects interaction or content

Work Process

1. Define scope — Page, component, or flow to review (e.g. login form, report table, modal dialog).
2. Check each area — Semantic HTML, keyboard, labels and names, color and contrast, dynamic content, motion. Use the checklists below.
3. Document findings — Location (component/file or element type), WCAG criterion or principle, issue, impact, and recommended fix. Severity: Critical / High / Medium.
4. Suggest fixes — Code snippet or attribute change where possible. Prefer native HTML and correct ARIA over custom widgets when they suffice.
5. Recommend follow-up — Suggest automated tools (e.g. axe, Lighthouse, pa11y; in CI, fail the build on critical) and manual testing for broader coverage. Automated tools catch roughly 30–40% of WCAG issues — the rest is manual. Recommend a flow × assistive-tech matrix: test each key user flow across keyboard-only, a screen reader (VoiceOver on Mac/iOS, NVDA on Windows, TalkBack on Android), 200% and 400% zoom / reflow (WCAG 1.4.10), Windows High Contrast, and reduced-motion; note Voice Control/Dragon and Switch Control where relevant. Do not claim full WCAG compliance from a single review.

• For automated assertions in tests: axe-core with .withTags(['wcag2a','wcag2aa']) targets a specific WCAG tier and can fail CI on violations; Playwright's page.ariaSnapshot() (1.59+) asserts the accessibility tree of dialogs, menus, and composite widgets — coverage beyond what axe/Lighthouse give.
• Run automated scans at more than one viewport (mobile and desktop breakpoints, not only the default): focus-obscured, overlapping targets, and reflow violations appear or vanish with viewport size, so a single-viewport scan silently under-reports.

Focus Areas and Checklist

1. Semantic HTML and structure

• [ ] One `` per page; heading levels in order (no skipping 2 → 4).
• [ ] Skip link to main content as the first focusable element (WCAG 2.4.1 Bypass Blocks).
• [ ] Viewport meta does not disable zoom: flag user-scalable=no and maximum-scale=1 (WCAG 1.4.4).
• [ ] Landmarks: `, , , ` where appropriate.
• [ ] Lists use `//; tables use , scope`, and caption if applicable.
• [ ] Buttons are ` or ; links are . Do not use ` for actions without role, keyboard, and focus.
• [ ] Form controls have correct type and grouping (`, ` for groups).

2. Keyboard

• [ ] All interactive elements are focusable (no tabindex="-1" on buttons/links unless managed for modal).
• [ ] Focus order is logical (matches visual order or is explicitly managed).
• [ ] Visible focus indicator (outline or custom style); not removed with outline: none without replacement. Prefer :focus-visible (no ring on mouse click) and :focus-within for compound controls.
• [ ] No keyboard trap: user can tab out of modals and menus; Escape closes where expected.
• [ ] Custom widgets (tabs, accordions, menus) operable with keyboard (Enter/Space to activate, Arrow keys if applicable).

3. Labels and names

• [ ] Every form input has a visible ` or aria-label; labels are associated (e.g. for/id` or wrapping).
• [ ] Inputs carry correct type/inputmode and autocomplete attributes (WCAG 1.3.5 Identify Input Purpose).
• [ ] Form errors appear inline next to their fields, each associated to its field via aria-describedby (without it a screen reader doesn't read the error when the field gets focus). On submit, focus moves to the first error; for long forms, add a keyboard-focusable error summary at the top that links to each errored field (GOV.UK pattern).
• [ ] User input is preserved on submit error, not cleared (reduces re-entry burden; see 3.3.7). Validate on blur, not on every keystroke.
• [ ] Paste is never blocked (onPaste + preventDefault is an anti-pattern) — anywhere, not just password fields.
• [ ] Buttons and links have clear, unique names (text content or aria-label). No "Click here" or "Read more" without context.
• [ ] Images: meaningful images have alt describing content; decorative images have alt="" or role="presentation". Decorative icons (inline SVG, icon fonts) get aria-hidden="true".
• [ ] Iframe and embedded content have title or aria-label.

4. Color and contrast

• [ ] Text meets contrast ratio (e.g. 4.5:1 for normal text, 3:1 for large; 3:1 for UI components). Check against background. (Newer design systems may use APCA, the perceptual model slated for WCAG 3.0 — note it if the project targets APCA, but audit against WCAG 2.2 ratios unless told otherwise.)
• [ ] Information is not conveyed by color alone (e.g. required fields, errors, status). Use icon, text, or pattern as well.
• [ ] Focus indicator is visible and not reliant only on color change.

5. Dynamic content and focus

• [ ] Content that appears or updates (e.g. toast, live results) is announced: aria-live="assertive" only for urgent interruptions (errors, toasts requiring action); aria-live="polite" for feed updates and result counts.
• [ ] SPA route changes are silent to screen readers: announce the new page via an aria-live="polite" region or move focus to the new page's ``.
• [ ] Modals and dialogs: focus moves into the modal when opened; focus is trapped inside; focus returns to trigger when closed; first focusable element or explicit autoFocus per pattern.
• [ ] State is communicated: expanded/collapsed (aria-expanded), selected (aria-selected), current (aria-current), disabled (disabled or aria-disabled).

6. Motion

• [ ] If the project supports it: respect prefers-reduced-motion (disable or reduce animation). Optional but recommended for vestibular sensitivity.

7. WCAG 2.2 additions (often missed)

• [ ] 2.4.11 Focus not obscured — sticky headers/footers must not hide the focused element (scroll-margin-top helps).
• [ ] 2.5.8 Target size — interactive targets at least 24×24 CSS px, or sufficient spacing between smaller ones. When the visible control is smaller, extend the hit area to 40–44px with a pseudo-element; two interactive elements must never have overlapping hit areas; a checkbox/radio and its label share one continuous target.
• [ ] 2.5.7 Dragging movements — every drag operation has a click/tap alternative.
• [ ] 3.3.7 Redundant entry — don't ask for the same information twice within one flow.
• [ ] 3.3.8 Accessible authentication — no cognitive test to log in; paste allowed in password fields; passkey or email-link alternative offered.
• [ ] 3.2.6 Consistent help — help mechanism appears in the same place on every page.

Output Format

For each issue:

**[Location: file or component/element]**
- **Issue:** [What is wrong.]
- **WCAG / principle:** [Criterion or principle, e.g. 1.3.1 Info and Relationships, 2.1.1 Keyboard.]
- **Impact:** [Who is affected and how.]
- **Recommendation:** [Concrete fix: code or attribute. For contrast findings, cite computed ratios: "#aaa on #fff = 2.32:1, needs 4.5:1 → use #595959 (7.0:1)".]
- **Severity:** Critical | High | Medium

Example of a populated finding:

**[src/components/LoginForm.tsx — error message]**
- **Issue:** The "Invalid email" error renders visually below the field but is not associated with the input and is never announced.
- **WCAG / principle:** 3.3.1 Error Identification; 4.1.3 Status Messages.
- **Impact:** A screen-reader user submits, hears nothing, and cannot tell the form failed or which field to fix.
- **Recommendation:** Link it: `` + `Invalid email`; on submit, move focus to the first invalid field.
- **Severity:** Critical

Summary: "Reviewed: [scope]. Found X critical, Y high, Z medium. Recommend automated scan (axe/Lighthouse) and keyboard/screen reader testing."

Severity

• Critical — Blocks core task (e.g. cannot submit form, cannot navigate with keyboard, no labels on required fields). Fix before release.
• High — Significant barrier (e.g. poor contrast, missing headings, confusing order). Fix soon.
• Medium — Improvement (e.g. redundant label, minor contrast). Backlog or fix when touching the component.

Good vs bad examples

Button:

Submit

Submit

Image:

Form:

Email

When a rule breaks

Each checklist item encodes a default that prevents the most common failure mode. When the context inverts the failure mode, the rule may invert too — a decorative element that a screen reader should skip wants aria-hidden, not a label; a native ` must not also get a keydown` handler (double activation). The work is recognizing the inversion, not memorizing exceptions. Never let an exception breach the correctness/a11y floor: keyboard operability, a programmatic name, and sufficient contrast are not negotiable.

Rules

• Do not claim full compliance — Frame as "issues found in reviewed scope." Recommend automated and manual testing for full coverage.
• Prefer native HTML — Use `, , , etc. Use ARIA when semantics cannot be expressed with HTML (e.g. aria-expanded` on a custom accordion).
• Component libraries — If the project uses one (e.g. Radix, MUI), note library a11y patterns (focus trap, roles) and ensure they are used correctly rather than reimplementing.

Checklist (before finishing)

• [ ] Scope clearly defined
• [ ] Each finding has location, issue, WCAG reference, recommendation, severity
• [ ] At least semantic structure, keyboard, and labels/names covered
• [ ] Follow-up (automated + manual testing) suggested
• [ ] No "fully WCAG 2.1 AAA compliant" without full audit

Anti-patterns

| Anti-pattern | Better approach | |--------------|-----------------| | Only checking color contrast | Cover keyboard, labels, structure, and dynamic content | | Suggesting "add aria-label" everywhere | Prefer visible labels and semantic HTML; use ARIA when necessary | | Ignoring focus order in modals | Document focus trap and return focus behavior | | Claiming compliance after code review only | Recommend axe/Lighthouse and real assistive tech testing |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: khasky
• Source: khasky/awesome-agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.