ralph-playwright:a11y-scan

A11y Scan — Accessibility Audit via CLI

Prerequisites

• playwright-cli installed globally (see /ralph-playwright:setup)
• Target app running

Process

Step 1: Execute (freeform, a11y goal)

Generate session name: <date>-a11y-scan-<slug>

Spawn explorer-agent with:

• url: Target URL (from arguments or ask)
• goal: "Systematically audit this page for WCAG 2.2 AA accessibility compliance. Focus on: form labels, tab order, keyboard operability, color contrast ratios, ARIA attributes, heading hierarchy, alt text, and focus management."
• session: The generated session name

The agent navigates the page, interacts with all interactive elements (especially via keyboard), and captures snapshots at each state.

Step 2: Reflect (a11y signals only)

Read the journey trace. For each step, examine the accessibility snapshot (.md file) for:

• Missing or empty labels: Form fields without associated <label> or aria-label
• Broken tab order: Elements not reachable via Tab, or illogical order
• Keyboard inoperability: Buttons/links not operable via Enter/Space
• Missing ARIA: Interactive components without role, aria-expanded, aria-describedby etc.
• Heading hierarchy: Skipped levels (h1 → h3), missing h1, multiple h1s
• Color contrast: Text against background ratios below 4.5:1 (normal) or 3:1 (large)
• Missing alt text: Images without alt attribute
• Focus management: Modals/dialogs that don't trap focus, focus not returned on close

Classify all findings as a11y_violation signals with WCAG success criteria references.

Write signal report to .playwright-cli/<session>/signal-report.yaml.

Step 3: Act

For each signal:

1. Critical/high: Create GitHub issue with WCAG reference, element details, and remediation guidance
2. Promote evidence screenshots showing the violation context
3. Write research note to thoughts/shared/research/<date>-<slug>-a11y-audit.md with full findings

Step 4: Report

== A11y Scan: http://localhost:3000/login ==
WCAG 2.2 AA | playwright-cli | N violations

🔴 CRITICAL (N):
  - <violation> → <remediation> (WCAG <criterion>)

🟠 HIGH (N):
  - <violation> → <remediation> (WCAG <criterion>)

🟡 MEDIUM (N):
  - <violation> → <remediation> (WCAG <criterion>)

Actions: N issues created, N screenshots promoted