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. 1. Scope

• - Define flows, pages, components, and complete processes.
• Identify highest-risk areas: forms, checkout, auth, navigation, modals, dynamic updates.

1. 2. Baseline automated checks (optional)

• - Run axe and lighthouse on key pages when runtime URLs are available.
• Capture and deduplicate issues.
• If automation dependencies are missing, continue with manual workflow and mark automation as skipped.

1. 3. Manual keyboard audit

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

1. 4. Visual audit

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

1. 5. Zoom and reflow audit

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

1. 6. Forms and errors audit

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

1. 7. Semantics and ARIA audit

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

1. 8. Status messages audit (AA)

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

1. 9. Synthesis

• - Map each finding to WCAG SC.
• Assign severity.
• Propose design and engineering fixes.
• Add acceptance criteria and verification steps.

Output Contract (Always Deterministic)

Always render output with these sections in this exact order using templates:

• - INLINECODE24
• INLINECODE25
• INLINECODE26
• INLINECODE27
• INLINECODE28

Use these files directly:

• - INLINECODE29
• INLINECODE30
• INLINECODE31

Findings Quality Bar

Every finding must include:

• - WCAG SC ID, name, and level
• Severity: Blocker, High, Medium, INLINECODE35
• 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 INLINECODE37

Severity Rubric

• - Blocker: Prevents task completion for one or more user groups.
• INLINECODE39: Causes major friction or frequent failure.
• INLINECODE40: Noticeable barrier with workaround.
• INLINECODE41: 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:

CODEBLOCK0

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:

• - INLINECODE48

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