WCAG 2.1 AA Web UI Audit

Skill Version

• 1.0.0

Trigger Phrases

Use this skill when the request includes any of the following: - WCAG 2.1 AA audit - Accessibility audit or UI accessibility review - A11y checklist or conformance report - Remediation plan for accessibility issues - Keyboard navigation or focus issues - Contrast issues - Zoom/reflow issues - ARIA or name/role/value issues - Status message or toast announcement issues - Forms and accessibility issues

Scope & Assumptions (Required First Output)

When invoked, first output a ## Scope & Assumptions section before any findings. Include: - Product type - Key flows and complete processes in scope - Platforms in scope - Components in scope - Access constraints (timebox, environments, auth constraints) - Evidence type boundaries: - confirmed implementation issue: verified on running UI or artifact with reproducible behavior - design-time risk: predicted from design artifacts/spec without runtime confirmation - Conformance note: "This report provides accessibility conformance guidance against WCAG 2.1 Level A and AA."

Inputs and Best-Effort Defaults

Collect these inputs. If missing, proceed with defaults and state assumptions explicitly.

• Product type
• Preferred input: SaaS, ecommerce, content
• Default: SaaS (switch to ecommerce if cart/checkout is in scope)
• Key flows to test
• Preferred input: explicit flows
• Default: sign-in, onboarding, search/filter, forms, checkout (if applicable)
• Target platforms
• Preferred input: desktop, mobile, or both
• Default: desktop + mobile
• Known UI components
• Preferred input: explicit component list
• Default: navigation, modal, drawer, toast/status, carousel, date picker, table, forms
• Access constraints
• Preferred input: timebox, environments, authentication access
• Default: single-pass audit on available environment within stated timebox
• Evidence artifacts
• Preferred input: URLs and/or design files/specs
• Default behavior: if no URLs/artifacts are provided, run a clearly labeled Readiness Review only

Deterministic Workflow

Run these steps in order.

1. Scope
2. Define flows, pages, components, and complete processes.

3. Identify highest-risk areas: forms, checkout, auth, navigation, modals, dynamic updates.

4. Baseline automated checks (optional)

5. Run axe and lighthouse on key pages when runtime URLs are available.
6. Capture and deduplicate issues.

7. If automation dependencies are missing, continue with manual workflow and mark automation as skipped.

8. Manual keyboard audit

9. Validate tab order, focus visibility, keyboard traps, skip links, modals, menus, and custom controls.

10. Visual audit

11. Validate text contrast, non-text contrast, focus indicator visibility/contrast, non-color error cues, and hover/focus content behavior.

12. Zoom and reflow audit

13. Validate at 200% zoom, 320 CSS px width, text-spacing overrides, and orientation behavior.

14. Forms and errors audit

15. Validate labels, instructions, error identification, error suggestions, and error prevention for legal/financial/data commitments.

16. Semantics and ARIA audit

17. Validate name/role/value, label-in-name, autocomplete/input purpose semantics, and parsing robustness.

18. Status messages audit (AA)

19. Validate that toasts and inline status updates are announced without forced focus moves when appropriate.

20. Synthesis

21. Map each finding to WCAG SC.
22. Assign severity.
23. Propose design and engineering fixes.
24. Add acceptance criteria and verification steps.

Output Contract (Always Deterministic)

Always render output with these sections in this exact order using templates: - A) Audit Summary (One Page) - B) Findings Table - C) Per-Flow Notes - D) Remediation Backlog - E) Definition of Done (Engineering + QA)

Use these files directly: - templates/audit-report-template.md - templates/finding-template.md - templates/remediation-backlog-template.md

Findings Quality Bar

Every finding must include: - WCAG SC ID, name, and level - Severity: Blocker, High, Medium, Low - Affected user groups - Repro steps - Expected vs actual behavior - Suggested fix split into design and engineering actions - Verification steps (manual and tool-based where relevant) - Evidence type: confirmed implementation issue or design-time risk

Severity Rubric

• Blocker: Prevents task completion for one or more user groups.
• High: Causes major friction or frequent failure.
• Medium: Noticeable barrier with workaround.
• Low: Minor barrier or polish issue.

Component Fix Recipes

Use docs/ui-component-checklists.md for fix-oriented component recipes covering: - Buttons/links - Inputs/selects/forms - Modal/dialog - Tooltip/popover - Carousel - Toast/status - Tabs - Accordion - Table - Date picker

Optional Automation Script

Use the optional script only when runtime URLs are provided:

node scripts/run_axe_playwright.js --url https://example.com
node scripts/run_axe_playwright.js --urls-file ./urls.txt

Behavior expectations: - Writes outputs/axe-results.json and outputs/axe-summary.md. - Deduplicates by (rule id + target selector + page). - Continues on per-URL failures. - If playwright or @axe-core/playwright is missing, prints install guidance and exits without failing.

"All Requirements" Requests

If the user asks for all WCAG requirements, point to and include or excerpt: - docs/wcag21-aa-success-criteria.md

Conformance Language Guardrail

Do not issue legal determinations or certification statements. Use conformance phrasing such as: - "accessibility conformance guidance" - "conformance risk" - "current conformance gaps"

Source Notes

Use WCAG terminology and SC names from: - WCAG 2.1 Recommendation - WAI How to Meet WCAG (Quick Reference) filtered to Level A and AA - Understanding WCAG, including 4.1.3 Status Messages