majiayu000 SEO & Accessibility Analyzer
Analyzes HTML/JSX/TSX files for SEO issues and WCAG 2.1 AA compliance.
Quick Start
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
Step 1: Read Target File
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)
Step 2: Quick Checks (P0 Critical Issues)
Check these immediately - they block compliance:
1. Title Tag (WCAG 2.4.2)
<!-- Required -->
<title>Descriptive Page Title - Site Name</title>
- Must exist and be non-empty
- Recommended length: 50-60 characters
- Should be unique per page
2. Meta Description (SEO)
<!-- Required -->
<meta name="description" content="Concise page description...">
- Must exist
- Recommended length: 150-160 characters
3. H1 Uniqueness (WCAG 2.4.6)
- Exactly one
<h1>per page - Must be descriptive and unique
4. Heading Hierarchy
- No skipped levels (h1 → h3 without h2)
- Logical nesting structure
5. Image Alt Text (WCAG 1.1.1)
<!-- Informative image -->
<img src="photo.jpg" alt="Team members at annual retreat">
<!-- Decorative image -->
<img src="decoration.png" alt="">
- All
<img>must havealtattribute - Decorative images:
alt="" - Informative images: descriptive text (not filename)
6. Color Contrast (WCAG 1.4.3)
- Normal text: 4.5:1 minimum
- Large text (18pt / 14pt bold+): 3:1 minimum
- See reference/color-contrast.md for common color combinations
If any P0 issue found, report immediately with location and fix.
Step 3: Detailed Checks
SEO Checks
See reference/seo-checks.md for complete list (30 items).
Key items:
- Canonical URL:
<link rel="canonical" href="..."> - Open Graph tags:
<meta property="og:title">,og:description,og:image - Twitter Cards:
<meta name="twitter:card">,twitter:title - Structured data:
<script type="application/ld+json"> - Mobile viewport:
<meta name="viewport" content="width=device-width, initial-scale=1"> - Language attribute:
<html lang="en">
WCAG Checks
See reference/wcag-quick-ref.md for criteria reference.
Key items:
- Form labels: All inputs must have associated
<label>oraria-label - Link text: Avoid "click here", use descriptive text
- Focus indicators: Ensure
:focusstyles are visible - Keyboard navigation: All interactive elements must be keyboard accessible
ARIA Checks
- Valid roles only (no custom roles like
role="hamburger") - Required attributes present (slider needs
aria-valuenow,aria-valuemin,aria-valuemax) - No
aria-hidden="true"on focusable elements - No redundant roles on native elements (
<button role="button">)
Step 4: Validate with axe-core CLI
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
Interpret Results
| 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.
Step 5: Generate Report
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]
Serious Issues
[Same format as above]
Warnings
[Same format as above]
Passed Checks
- [list of successful checks]
## 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:
- Applied fix for [issue]
- Re-ran axe-core
- Confirmed resolution
## 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>
Missing Alt Text
<!-- Before -->
<img src="product.jpg">
<!-- After -->
<img src="product.jpg" alt="Blue wireless headphones with noise cancellation">
Low Contrast Text
/* Before: #999 on #fff = 2.85:1 */
.text { color: #999999; }
/* After: #767676 on #fff = 4.54:1 */
.text { color: #767676; }
Missing Form Label
<!-- Before -->
<input type="email" placeholder="Email">
<!-- After -->
<label for="email">Email address</label>
<input type="email" id="email" placeholder="Email">
JSX/TSX Specifics
When analyzing React files:
- Check
classNameinstead ofclass - Verify
htmlForinstead offoron labels - Check for
keyprops in lists (not accessibility, but important) - Look for accessible component patterns in design system usage
Examples
See reference/examples.md for:
- Complete page audit example
- React component audit example
- Before/after fix comparisons
When NOT to Use This Skill
- URL-based testing (use axe-core CLI directly on served pages)
- Dynamic content analysis (requires browser rendering)
- Complex SPA testing (use Lighthouse or Playwright)
- PDF accessibility (different tooling required)