a11y-automation

Skill: Accessibility Automation

Purpose

Run automated accessibility checks using linters and browser-based testing tools to identify WCAG violations.

Inputs

• targetPath: Path to files or directory to check
• checkType: lint, browser, or both

Outputs

• Violation summary with counts by severity
• Exit code (0 for pass, non-zero for failures)
• Actionable remediation steps with code fixes

Procedures

1. Validate Target Path

Ensure the path exists and contains testable files.

For lint: Look for .tsx, .jsx, .ts, .js files. For browser: Look for test files or running application.

2. Run Linting Checks

Execute: .agents/skills/a11y-automation/scripts/run-a11y-lint.sh <targetPath>

This script:

1. Checks if eslint-plugin-jsx-a11y is configured.
2. Runs eslint on the target path.
3. Outputs violations grouped by rule.

If linter is not configured, output setup instructions.

3. Run Browser-Based Checks (Optional)

If checkType is browser or both:

Execute: node .agents/skills/a11y-automation/scripts/run-axe-playwright.mjs <targetPath>

This script:

1. Checks if Playwright and @axe-core/playwright are available.
2. Runs axe checks on rendered components or pages.
3. Outputs violations by severity.

If not configured, provide setup guidance.

4. Parse Results

Extract:

• Total violation count
• Violations by severity (critical, serious, moderate, minor)
• Violations by rule (grouped)
• File and line number for each violation

5. Summarize Findings

Output to chat:

• Summary statistics (total violations, by severity, by rule)
• Per-file breakdown with line numbers
• Brief descriptions of each violation type

6. Propose Fixes

For critical and serious violations:

• Show code snippet with issue
• Provide corrected version
• Reference applicable WCAG guideline
• Apply fixes using minimal diffs

6. Output Remediation Steps

For each violation type, provide:

• WCAG guideline reference (e.g., 2.4.7 Focus Visible)
• Explanation of why it matters
• Code example of correct implementation