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
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-encapsulation
Analyzes PHP code for encapsulation violations. Detects public mutable state, exposed internals, Tell Don't Ask violations, getter/setter abuse, and information hiding breaches.
acc-check-bounded-contexts
Analyzes bounded context boundaries in DDD projects. Detects cross-context coupling, shared kernel violations, context mapping issues, and ubiquitous language inconsistencies. Generates context map diagrams and boundary recommendations.
a11y-review
Controleer toegankelijkheid conform WCAG 2.1 AA. Gebruik bij het reviewen van templates, CSS of HTML, of wanneer de gebruiker vraagt om toegankelijkheid te checken.
a11y-personas
Library of accessibility personas representing people with various disabilities, impairments, and situational limitations. Use this skill when users ask about disability types, accessibility personas, user needs for specific conditions, how people with disabilities use technology, assistive technology users, or designing for accessibility. Triggers on requests about blindness, deafness, cognitive disabilities, motor impairments, low vision, screen readers, sign language, autism, ADHD, temporary disabilities, or any question about "how would a person with X use this".
a11y-debugging
Uses Chrome DevTools MCP for accessibility (a11y) debugging and auditing based on web.dev guidelines. Use when testing semantic HTML, ARIA labels, focus states, keyboard navigation, tap targets, and color contrast.
a11y-annotation-generator
Adds accessibility annotations (ARIA labels, roles, alt text) to make web content accessible. Use when user asks to "add accessibility", "make accessible", "add aria labels", "wcag compliance", or "screen reader support".
ui-design-a11y
无障碍设计审查与修复能力。
asyncredux-check-internet-mixin
Add the CheckInternet mixin to ensure network connectivity before action execution. Covers automatic error dialogs, combining with NoDialog for custom UI handling, and AbortWhenNoInternet for silent abort.
astro-a11y
Accessibility patterns for Astro lead generation sites. WCAG 2.1 AA compliance, screen readers, keyboard navigation, focus management, ARIA. Use for all accessibility implementation.
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.