a11y-self-check
Proactively validates Claude Code's own generated HTML/JSX/TSX output for accessibility before presenting to users. Use this skill automatically when generating UI code to ensure WCAG 2.1 AA compliance.
Best use case
a11y-self-check is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
Proactively validates Claude Code's own generated HTML/JSX/TSX output for accessibility before presenting to users. Use this skill automatically when generating UI code to ensure WCAG 2.1 AA compliance.
Teams using a11y-self-check should expect a more consistent output, faster repeated execution, less prompt rewriting.
When to use this skill
- You want a reusable workflow that can be run more than once with consistent structure.
When not to use this skill
- You only need a quick one-off answer and do not need a reusable workflow.
- You cannot install or maintain the underlying files, dependencies, or repository context.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/a11y-self-check/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How a11y-self-check Compares
| Feature / Agent | a11y-self-check | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
Proactively validates Claude Code's own generated HTML/JSX/TSX output for accessibility before presenting to users. Use this skill automatically when generating UI code to ensure WCAG 2.1 AA compliance.
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
SKILL.md Source
# A11y Self-Check for Claude Code
This skill enables Claude Code to validate its own generated HTML/JSX/TSX output for accessibility issues before presenting code to users.
## When to Use
Proactively run self-check when you (Claude Code):
1. **Generate new HTML/JSX/TSX files** - Validate before suggesting to user
2. **Write UI components** - Check before completing the task
3. **Modify existing templates** - Verify changes don't introduce issues
4. **Create forms, modals, navigation** - High-risk accessibility areas
## Self-Check Workflow
### Step 1: Write Code to Temporary File
When generating HTML/JSX/TSX code, write it to a temporary file:
```bash
# For generated HTML
cat > /tmp/claude-generated.html << 'EOF'
[your generated HTML here]
EOF
# For JSX/TSX
cat > /tmp/claude-generated.tsx << 'EOF'
[your generated JSX/TSX here]
EOF
```
### Step 2: Run A11y Lint
Execute the lint script on the temporary file:
```bash
bash ${CLAUDE_PLUGIN_ROOT}/skills/html-lint-runner/scripts/lint-html.sh /tmp/claude-generated.html
```
### Step 3: Analyze Results
Check the JSON output for issues:
```json
{
"summary": {
"axe_violations": 0,
"markuplint_problems": 0,
"total_issues": 0
}
}
```
- If `total_issues` is 0: Code is ready to present
- If `total_issues` > 0: Fix issues before presenting
### Step 4: Fix and Re-validate
If issues found:
1. Look up WCAG/ARIA reference: `${CLAUDE_PLUGIN_ROOT}/skills/wcag-aria-lookup/`
2. Apply fixes to your generated code
3. Re-run lint to confirm resolution
4. Present corrected code to user
## Quick Checks (No Tool Required)
Before running lint tools, perform mental checks:
### Images
- [ ] All `<img>` have `alt` attribute
- [ ] Decorative images use `alt=""`
- [ ] Complex images have `aria-describedby`
### Forms
- [ ] All inputs have associated `<label>`
- [ ] Required fields have `aria-required="true"`
- [ ] Error states use `aria-invalid` and `aria-describedby`
### Interactive Elements
- [ ] Buttons have accessible names
- [ ] Links have descriptive text (not "click here")
- [ ] Custom controls have proper ARIA roles
### Structure
- [ ] Headings follow logical order (h1 → h2 → h3)
- [ ] Landmarks are used (`<main>`, `<nav>`, `<aside>`)
- [ ] Language is set on `<html lang="...">`
### Color & Contrast
- [ ] Text contrast ≥ 4.5:1 (normal), ≥ 3:1 (large)
- [ ] Information not conveyed by color alone
## Integration with /a11y-audit
For comprehensive validation, use the `/a11y-audit` command:
```
/a11y-audit /tmp/claude-generated.html
```
This spawns the `a11y-fixer` agent for detailed analysis with WCAG references.
## Example: Self-Validated Component Generation
```
User: "Create a login form component"
Claude Code (internal process):
1. Generate LoginForm.tsx
2. Write to /tmp/claude-generated.tsx
3. Run: bash ${CLAUDE_PLUGIN_ROOT}/skills/html-lint-runner/scripts/lint-html.sh /tmp/claude-generated.tsx
4. Results show: missing label association
5. Fix: Add htmlFor and id attributes
6. Re-run lint: 0 issues
7. Present validated code to user
```
## Proactive Quality Assurance
This skill transforms Claude Code from generating "potentially accessible" code to generating "validated accessible" code by:
1. **Pre-flight checks** - Mental validation before writing
2. **Automated validation** - Tool-based verification after writing
3. **Reference lookup** - WCAG/ARIA guidance for fixes
4. **Iteration** - Fix → Validate → Confirm cycle
Users receive code that has already passed accessibility checks.Related Skills
adr-check
Validate code changes against Architecture Decision Records (ADRs)
add-strict-checks
Enable stricter TypeScript and linting checks to catch bugs early, especially useful when iterating with AI assistance.
add-check
Add a new code quality check to CI, justfile, and pre-commit hooks. Use when adding linters, formatters, type checkers, or other code quality tools to the project.
accessibility-design-checklist
Эксперт по accessibility дизайну. Используй для WCAG, a11y чеклистов и inclusive design.
accessibility-design-checker
Ensures designs meet accessibility requirements including WCAG compliance, color contrast, keyboard navigation, screen reader support, and focus management. Reviews designs for accessibility issues and provides recommendations.
accessibility-checklist
When building UI components, forms, or any user-facing interface. Check before every frontend PR.
accessibility-checker
Validate WCAG 2.1 Level AA compliance and accessibility best practices. Use when performing accessibility audits and WCAG certification.
accessibility-check
Run accessibility audit on frontend components for WCAG 2.1 AA compliance
accessibility-basic-check
Run a basic accessibility checklist for UI changes. Use when a junior developer needs quick a11y guidance.
accessibility-a11y
Semantic HTML, keyboard navigation, focus states, ARIA labels, skip links, and WCAG contrast requirements. Use when ensuring accessibility compliance, implementing keyboard navigation, or adding screen reader support.
acc-check-leaky-abstractions
Detects leaky abstractions in PHP code. Identifies implementation details exposed in interfaces, concrete returns from abstract methods, framework leakage into domain, and infrastructure concerns in application layer.
acc-check-immutability
Analyzes PHP code for immutability violations. Checks Value Objects, Events, DTOs for readonly properties, no setters, final classes, and wither patterns. Ensures domain objects maintain invariants.