playbooks

home / skills / vadimcomanescu / codex-skills / accessibility-auditor

accessibility-auditor skill

/skills/.experimental/design/accessibility-auditor

This skill helps you audit and fix WCAG accessibility issues across structure, keyboard, contrast, forms, media, and ARIA.

npx playbooks add skill vadimcomanescu/codex-skills --skill accessibility-auditor

Review the files below or copy the command above to add this skill to your agents.

Files (3)
SKILL.md
2.2 KB
---
name: accessibility-auditor
description: Web accessibility specialist for WCAG compliance, ARIA implementation, and inclusive design. Use when auditing websites for accessibility issues, implementing WCAG 2.1 AA/AAA standards, testing with screen readers, or ensuring ADA compliance. Expert in semantic HTML, keyboard navigation, and assistive technology compatibility.
---

# Accessibility Auditor

Make interfaces usable for everyone by finding and fixing WCAG issues with clear, actionable remediation.

## Quick Start
1) Scope the surface area (page(s), flow, or component set) and the target level (WCAG 2.1 AA by default).
2) Audit in this order: structure → keyboard → contrast → forms → media → ARIA.
3) Report issues as: **Problem → Impact → Fix → Verification**.

## Audit Checklist (practical)
- **Structure**: one `h1`, correct heading order, landmarks (`nav`, `main`, `footer`), lists for lists.
- **Keyboard**: tab order logical, no traps, visible focus state, skip link when needed.
- **Contrast**: text ≥ 4.5:1 (AA), large text ≥ 3:1, UI elements ≥ 3:1.
- **Forms**: every input has a label; errors are announced and tied to fields.
- **Media**: alt text for informative images; captions/transcripts for audio/video.
- **ARIA**: only when native semantics can’t solve it; roles/states must match behavior.

## Recommended Workflow
1) **Static review**: check semantics in markup and component structure.
2) **Keyboard pass**: navigate every interactive control without a mouse.
3) **Screen reader spot check**: validate names, roles, and announcements.
4) **Contrast pass**: verify text and UI component contrast ratios.
5) **Document fixes**: include exact file/line (if codebase) and the change required.

## Output Format (default)
- **Summary**: pass/fail and the highest-risk issues.
- **Findings**: numbered list with severity (High/Med/Low) and fix guidance.
- **Verification steps**: how to confirm each fix.

## Guardrails
- Prefer native HTML semantics over ARIA.
- Do not remove focus outlines; replace with an accessible, visible alternative if needed.
- If a fix changes behavior, call out any product impact explicitly.

## References
- Extended examples: `references/examples.md`

Overview

This skill is an accessibility auditor focused on WCAG compliance, ARIA implementation, and inclusive design. I help teams find high-impact accessibility issues and provide clear, actionable remediation steps tied to code or content. The goal is measurable improvements: accessible semantics, reliable keyboard navigation, and compatibility with assistive technologies.

How this skill works

I inspect pages, flows, or component sets using a structured audit sequence: structure → keyboard → contrast → forms → media → ARIA. The audit combines static markup review, keyboard passes, screen reader spot checks, and contrast measurements. Findings are reported as Problem → Impact → Fix → Verification, with severity levels and explicit file/line guidance when applicable.

When to use it

  • Before release to verify WCAG 2.1 AA (or AAA) compliance
  • When implementing ARIA for complex widgets or dynamic content
  • During UI component library reviews or new page launches
  • To validate keyboard navigation and screen reader behavior
  • When preparing accessibility documentation for legal/ADA audits

Best practices

  • Prefer native HTML semantics before adding ARIA roles or properties
  • Start audits with document structure: headings, landmarks, and lists
  • Do a dedicated keyboard pass to detect traps and missing focus states
  • Report fixes with exact code locations and step-by-step verification
  • Keep contrast and labelling checks automated where possible, then spot-check manually

Example use cases

  • Audit a marketing site for WCAG 2.1 AA and deliver a prioritized findings list
  • Review a component library to ensure semantic HTML and keyboard support
  • Validate form error handling so announcements and field associations work with screen readers
  • Test an interactive widget that uses ARIA and recommend native alternatives where feasible
  • Produce verification steps for engineering to confirm fixes during code review

FAQ

Which WCAG level do you target by default?

WCAG 2.1 AA is the default target, with options to audit for AAA on request.

When should I use ARIA vs native HTML?

Use ARIA only when native semantics cannot express the needed behavior; native HTML is more reliable for assistive tech.