Analyzes HTML/JSX/TSX files for SEO and accessibility issues including WCAG 2.1 AA compliance, color contrast (4.5:1), heading hierarchy, meta tags, image alt text, and ARIA attributes. Use when checking web pages for SEO, accessibility, WCAG compliance, or when user mentions "a11y", "contrast", "alt text", "meta tags", "heading structure", or "accessibility audit".
This skill inherits all available tools. When active, it can use any tool Claude has access to.
reference/color-contrast.mdreference/examples.mdreference/seo-checks.mdreference/wcag-quick-ref.mdscripts/validate-with-axe.shAnalyzes HTML/JSX/TSX files for SEO issues and WCAG 2.1 AA compliance.
Copy this workflow checklist and track progress:
Analysis Progress:
- [ ] Step 1: Read target file
- [ ] Step 2: Run quick checks (P0 critical issues)
- [ ] Step 3: Run detailed checks (all issues)
- [ ] Step 4: Validate with axe-core CLI
- [ ] Step 5: Generate report with fixes
Read the HTML/JSX/TSX file using the Read tool.
Identify file type:
.html - Standard HTML.jsx / .tsx - React components (check className instead of class)Check these immediately - they block compliance:
<!-- Required -->
<title>Descriptive Page Title - Site Name</title>
<!-- Required -->
<meta name="description" content="Concise page description...">
<h1> per page<!-- Informative image -->
<img src="photo.jpg" alt="Team members at annual retreat">
<!-- Decorative image -->
<img src="decoration.png" alt="">
<img> must have alt attributealt=""If any P0 issue found, report immediately with location and fix.
See reference/seo-checks.md for complete list (30 items).
Key items:
<link rel="canonical" href="..."><meta property="og:title">, og:description, og:image<meta name="twitter:card">, twitter:title<script type="application/ld+json"><meta name="viewport" content="width=device-width, initial-scale=1"><html lang="en">See reference/wcag-quick-ref.md for criteria reference.
Key items:
<label> or aria-label:focus styles are visiblerole="hamburger")aria-valuenow, aria-valuemin, aria-valuemax)aria-hidden="true" on focusable elements<button role="button">)Required: Run axe-core for automated WCAG validation.
npx @axe-core/cli file.html --tags wcag21aa
Or use the provided script:
bash scripts/validate-with-axe.sh path/to/file.html
| Severity | Action |
|---|---|
| critical | Must fix - blocks compliance |
| serious | Should fix - affects many users |
| moderate | Nice to fix - best practice |
| minor | Consider fixing |
Goal: Zero critical and serious issues.
Use this exact format:
# Accessibility & SEO Report: [filename]
## Summary
- Critical: [count]
- Serious: [count]
- Warnings: [count]
- Info: [count]
## Critical Issues (P0)
### 1. [Issue Title] - [WCAG X.X.X or SEO]
**Problem**: [specific description]
**Location**: Line [number] or `[CSS selector]`
**Current code**:
```html
[problematic code]
Fixed code:
[corrected code]
Why this matters: [brief explanation]
[Same format as above]
[Same format as above]
## Validation Loop
For complex fixes, follow this pattern:
1. Apply fix
2. Re-run axe-core validation
3. If issues remain → refine fix, return to step 1
4. **Only proceed when validation passes**
Validation Loop:
## Common Fix Patterns
### Missing Title
```html
<!-- Before -->
<head>
<meta charset="UTF-8">
</head>
<!-- After -->
<head>
<meta charset="UTF-8">
<title>Page Title - Site Name</title>
</head>
<!-- Before -->
<img src="product.jpg">
<!-- After -->
<img src="product.jpg" alt="Blue wireless headphones with noise cancellation">
/* Before: #999 on #fff = 2.85:1 */
.text { color: #999999; }
/* After: #767676 on #fff = 4.54:1 */
.text { color: #767676; }
<!-- Before -->
<input type="email" placeholder="Email">
<!-- After -->
<label for="email">Email address</label>
<input type="email" id="email" placeholder="Email">
When analyzing React files:
className instead of classhtmlFor instead of for on labelskey props in lists (not accessibility, but important)See reference/examples.md for: