seo-a11y-analyzer
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".
What this skill does
# 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)
```html
<!-- 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)
```html
<!-- 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)
```html
<!-- Informative image -->
<img src="photo.jpg" alt="Team members at annual retreat">
<!-- Decorative image -->
<img src="decoration.png" alt="">
```
- All `<img>` must have `alt` attribute
- 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](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](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](reference/wcag-quick-ref.md) for criteria reference.
Key items:
- Form labels: All inputs must have associated `<label>` or `aria-label`
- Link text: Avoid "click here", use descriptive text
- Focus indicators: Ensure `:focus` styles 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.
```bash
npx @axe-core/cli file.html --tags wcag21aa
```
Or use the provided script:
```bash
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:
```markdown
# 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**:
```html
[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
```html
<!-- Before -->
<img src="product.jpg">
<!-- After -->
<img src="product.jpg" alt="Blue wireless headphones with noise cancellation">
```
### Low Contrast Text
```css
/* Before: #999 on #fff = 2.85:1 */
.text { color: #999999; }
/* After: #767676 on #fff = 4.54:1 */
.text { color: #767676; }
```
### Missing Form Label
```html
<!-- 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 `className` instead of `class`
- Verify `htmlFor` instead of `for` on labels
- Check for `key` props in lists (not accessibility, but important)
- Look for accessible component patterns in design system usage
## Examples
See [reference/examples.md](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)
## References
- [WCAG 2.1 Quick Reference](https://www.w3.org/WAI/WCAG21/quickref/)
- [axe-core Rules](https://dequeuniversity.com/rules/axe/)
- [WebAIM Contrast Checker](https://webaim.org/resources/contrastchecker/)
Related in Ads & Marketing
ads
IncludedMulti-platform paid advertising audit and optimization skill. Analyzes Google, Meta, YouTube, LinkedIn, TikTok, Microsoft, and Apple Ads. 250+ checks with scoring, parallel agents, industry templates, and AI creative generation.
banana
IncludedAI image generation Creative Director powered by Google Gemini Nano Banana models. Use this skill for ANY request involving image creation, editing, visual asset production, or creative direction. Triggers on: generate an image, create a photo, edit this picture, design a logo, make a banner, visual for my anything, and all /banana commands. Handles text-to-image, image editing, multi-turn creative sessions, batch workflows, and brand presets.
rpg-migration-analyzer
IncludedAnalyzes legacy RPG (Report Program Generator) programs from AS/400 and IBM i systems for migration to modern Java applications. Extracts business logic from RPG III/IV/ILE source code, identifies data structures (D-specs), file operations (F-specs), program dependencies (CALLB/CALLP), and converts RPG constructs to Java equivalents. Generates migration reports, complexity estimates, and Java implementation strategies with POJO classes, JPA entities, and service methods. Use when modernizing AS/400 or IBM i legacy systems, analyzing RPG source files (.rpg, .rpgle, .RPGLE), converting RPG to Java, mapping data specifications to Java classes, planning legacy system migration, or when user mentions RPG analysis, Report Program Generator, RPG III/IV/ILE, AS/400 modernization, IBM i migration, packed decimal conversion, or mainframe application rewrite.
brand-library-architect
IncludedBuild a complete brand library for a product — visual asset render pipeline, brand documentation set (BRAND, COPY, MANIFESTO, BIOS, FAQ, GLOSSARY, TONE, PRICING), open-source convention files (README, CONTRIBUTING, SECURITY, CODE_OF_CONDUCT), and a self-contained press kit. This skill should be used when the user asks to "build a brand library / brand kit / press kit / brand assets" for a product, "set up a brand library workflow," "create a positioning manifesto plus visual identity," or any combination of brand documentation + visual asset pipeline. Apply phase-by-phase or run end-to-end. Templates are product-agnostic and use {{TOKEN}} placeholders the skill prompts the user to fill.
writing-tech-post
IncludedAuthors engineering blog posts end-to-end: launch deep-dives, incident postmortems, architecture migrations, performance case studies, tutorials, AI/agent system writeups, security disclosures, and research-to-product translations. Picks the correct archetype, plans the abstraction ladder, enforces an evidence cadence (diagrams, benchmarks, profiles, traces, code, ablations), tunes voice against publisher house styles (Datadog, Vercel, GitHub, AWS, Meta, Cloudflare, Jane Street), and runs a pre-publish gate for narrative momentum and disclosure ethics. Use when drafting a new engineering post, restructuring a draft that feels flat, deciding which evidence form belongs where, validating that depth and product context are balanced, or preparing a postmortem, migration, or performance narrative for external publication. Do not use for API reference documentation, README authoring, marketing copy, release notes, generic SEO content, ghost-written executive thought leadership, or non-engineering long-form essays.
blog-google
IncludedGoogle API integration for blog performance: PageSpeed Insights, CrUX Core Web Vitals with 25-week history, Search Console performance, URL Inspection, Indexing API, GA4 organic traffic, NLP entity analysis for E-E-A-T, YouTube video search for embedding, and Google Ads Keyword Planner. Progressive feature availability based on credential tier (API key, OAuth/service account, GA4, Ads). Shares config with claude-seo at ~/.config/claude-seo/google-api.json. Use when user says "google data", "page speed", "core web vitals", "search console", "indexation", "GA4", "keyword research", "nlp entities", "blog performance", "youtube search", "google api setup".