# A11Y Audit

> This skill should be used when the user asks to "check accessibility", "audit WCAG compliance", "scan HTML for a11y issues", "check color contrast", or "find accessibility violations in web pages".

- Skill: `majiayu000/a11y-audit` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds add majiayu000/a11y-audit`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/a11y-audit/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- License: MIT + Commons Clause
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/a11y-audit

---

# Accessibility Audit

> **Category:** Engineering
> **Domain:** Web Accessibility

## Overview

The **Accessibility Audit** skill provides automated scanning of HTML files for WCAG 2.1 compliance violations and color contrast checking against AA/AAA standards. It catches missing alt text, broken heading hierarchies, unlabeled form inputs, and insufficient color contrast early in development.

## Clarify First

Before running the audit, confirm these inputs. If any is unknown or vague, ASK — do not assume:

- [ ] **Target & scope** — which HTML files, directory, or CSS to scan (determines what gets checked and the `--file`/`--dir`/`--css` arguments)
- [ ] **Conformance level** — A, AA, or AAA target (sets contrast thresholds and which violations are CRITICAL vs WARNING vs INFO)
- [ ] **Use context** — one-off remediation vs CI gate (drives `--strict` gating and JSON output)

Stop rule: ask only the 2-3 that most change the output. If the user says "just draft it," proceed and list your assumptions at the top of the artifact.

## Quick Start

```bash
# Scan HTML for WCAG violations
python scripts/a11y_scanner.py --file index.html

# Scan a directory of HTML files
python scripts/a11y_scanner.py --dir ./src/templates

# Check color contrast
python scripts/contrast_checker.py --foreground "#333333" --background "#ffffff"

# Parse CSS file for contrast issues
python scripts/contrast_checker.py --css styles.css

# JSON output for CI
python scripts/a11y_scanner.py --file index.html --format json
```

## Tools Overview

### a11y_scanner.py

Scans HTML files for WCAG 2.1 violations including structural, semantic, and interactive element issues.

| Feature | Description |
|---------|-------------|
| Image alt text | Detects missing or empty alt on non-decorative images |
| Heading hierarchy | Validates h1-h6 levels are sequential |
| Form labels | Ensures inputs have associated label elements |
| ARIA attributes | Checks ARIA usage correctness |
| Link text | Flags generic text like "click here" or "read more" |
| Language attribute | Checks for lang on html element |
| Tab order | Detects positive tabindex values |
| Landmarks | Validates semantic landmark usage |

### contrast_checker.py

Checks color contrast ratios against WCAG AA and AAA thresholds.

| Feature | Description |
|---------|-------------|
| Ratio calculation | Computes relative luminance contrast ratio |
| AA compliance | 4.5:1 normal text, 3:1 large text |
| AAA compliance | 7:1 normal text, 4.5:1 large text |
| CSS parsing | Extracts color/background pairs from CSS |
| Color suggestions | Recommends nearest compliant color |

## Workflows

### Full Accessibility Audit

1. **Scan HTML** - Run a11y_scanner.py on all templates
2. **Check contrast** - Run contrast_checker.py on stylesheets
3. **Triage** - Prioritize Level A violations first
4. **Remediate** - Fix critical issues (alt text, form labels, headings)
5. **Re-scan** - Verify fixes pass all checks

### CI Integration

```bash
# Gate on Level A violations
python scripts/a11y_scanner.py --dir ./templates --format json --level A --strict

# Check CSS contrast
python scripts/contrast_checker.py --css ./static/css/main.css --format json
```

### Development Workflow

1. **Pre-commit** - Quick scan of changed HTML files
2. **PR review** - Full scan as part of review checklist
3. **Staging audit** - Comprehensive scan before release
4. **Monitoring** - Regular scheduled audits

## Reference Documentation

- [WCAG Guidelines](references/wcag-guidelines.md) - Conformance levels, success criteria, common fixes

## Common Patterns Quick Reference

### WCAG Levels
| Level | Description | Typical Requirement |
|-------|-------------|-------------------|
| A | Minimum baseline | Legal compliance |
| AA | Industry standard | Most regulations, ADA |
| AAA | Enhanced | Best practice goal |

### Contrast Ratios
| Context | AA | AAA |
|---------|-----|-----|
| Normal text (<18pt) | 4.5:1 | 7:1 |
| Large text (>=18pt bold or >=14pt) | 3:1 | 4.5:1 |
| UI components | 3:1 | 3:1 |

### Quick Fixes
| Issue | Fix |
|-------|-----|
| Missing alt text | `<img alt="Description of image">` |
| Skipped heading | Use sequential h1 through h6 |
| No form label | `<label for="inputId">Label</label>` |
| Generic link text | Replace "click here" with descriptive text |
| Missing lang | `<html lang="en">` |
| Positive tabindex | Use tabindex="0" or tabindex="-1" only |

### Severity Mapping
- **CRITICAL** - WCAG Level A violations
- **WARNING** - WCAG Level AA violations
- **INFO** - WCAG Level AAA recommendations