a11y-audit

Use for any accessibility audit or a11y fix (WCAG 2.2 A/AA, color contrast, compliance report, CI check) in React, Next.js, Vue, Angular, Svelte or HTML. Scans with a11y_scanner.py and checks contrast with contrast_checker.py, then fixes and re-verifies.

1,002
installs: 0 up / 0 down, score 0.00
votes: 29,342
repo stars
Updated: less than a month ago
In the catalog since: 11 Nov 2026
From: alirezarezvani/claude-skills

Get it through your agent npx skills add alirezarezvani/claude-skills@a11y-audit

Skill instructions

Rendered from the published SKILL.md, 207 lines.

Accessibility Audit

WCAG 2.2 Accessibility Audit and Remediation Skill

Description

The a11y-audit skill provides a complete accessibility audit pipeline for modern web applications. It implements a three-phase workflow -- Scan, Fix, Verify -- that identifies WCAG 2.2 Level A and AA violations, generates exact fix code per framework, and produces stakeholder-ready compliance reports.

For every violation it finds, it provides the precise before/after code fix tailored to your framework (React, Next.js, Vue, Angular, Svelte, or plain HTML).

What this skill does:

Scans your codebase for every WCAG 2.2 Level A and AA violation, categorized by severity (Critical, Major, Minor)
Fixes each violation with framework-specific before/after code patterns
Verifies that fixes resolve the original violations and introduces no regressions
Reports findings in a structured format suitable for developers, PMs, and compliance stakeholders
Integrates into CI/CD pipelines to prevent accessibility regressions

Features

Feature	Description
Full WCAG 2.2 Scan	Checks all Level A and AA success criteria across your codebase
Framework Detection	Auto-detects React, Next.js, Vue, Angular, Svelte, or plain HTML
Severity Classification	Categorizes each violation as Critical, Major, or Minor
Fix Code Generation	Produces before/after code diffs for every issue
Color Contrast Checker	Validates foreground/background pairs against AA and AAA ratios
Compliance Reporting	Generates stakeholder reports with pass/fail summaries
CI/CD Integration	GitHub Actions, GitLab CI, Azure DevOps pipeline configs
Keyboard Navigation Audit	Detects missing focus management and tab order issues
ARIA Validation	Checks for incorrect, redundant, or missing ARIA attributes

Severity Definitions

Severity	Definition	Example	SLA
Critical	Blocks access for entire user groups	Missing alt text, no keyboard access to navigation	Fix before release
Major	Significant barrier that degrades experience	Insufficient color contrast, missing form labels	Fix within current sprint
Minor	Usability issue that causes friction	Redundant ARIA roles, suboptimal heading hierarchy	Fix within next 2 sprints

Usage

Quick Start

# Scan entire project
python scripts/a11y_scanner.py /path/to/project

# Scan with JSON output for tooling
python scripts/a11y_scanner.py /path/to/project --json

# Check color contrast for specific values
python scripts/contrast_checker.py --fg "#777777" --bg "#ffffff"

# Check contrast across a CSS/Tailwind file
python scripts/contrast_checker.py --file /path/to/styles.css

Slash Command

/a11y-audit                    # Audit current project
/a11y-audit --scope src/       # Audit specific directory
/a11y-audit --fix              # Audit and auto-apply fixes
/a11y-audit --report           # Generate stakeholder report
/a11y-audit --ci               # Output CI-compatible results

Three-Phase Workflow

Phase 1: Scan -- Walk the source tree, detect framework, apply rule set.

python scripts/a11y_scanner.py /path/to/project --format table

Phase 2: Fix -- Apply framework-specific fixes for each violation.

See references/framework-a11y-patterns.md for the complete fix patterns catalog.

Phase 3: Verify -- Re-run the scanner to confirm fixes and check for regressions.

python scripts/a11y_scanner.py /path/to/project --baseline audit-baseline.json

Example: React Component Audit

// BEFORE: src/components/ProductCard.tsx
function ProductCard({ product }) {
  return (
    <div onClick={() => navigate(`/product/${product.id}`)}>
      <img src={product.image} />
      <div style={{ color: '#aaa', fontSize: '12px' }}>{product.name}</div>
      <span style={{ color: '#999' }}>${product.price}</span>
    </div>
  );
}

#	WCAG	Severity	Issue
1	1.1.1	Critical	`<img>` missing `alt` attribute
2	2.1.1	Critical	`<div onClick>` not keyboard accessible
3	1.4.3	Major	Color `#aaa` on white fails contrast (2.32:1, needs 4.5:1)
4	1.4.3	Major	Color `#999` on white fails contrast (2.85:1, needs 4.5:1)
5	4.1.2	Major	Interactive element missing role and accessible name

// AFTER: src/components/ProductCard.tsx
function ProductCard({ product }) {
  return (
    <a href={`/product/${product.id}`} className="product-card"
       aria-label={`View ${product.name} - $${product.price}`}>
      <img src={product.image} alt={product.imageAlt || product.name} />
      <div style={{ color: '#595959', fontSize: '12px' }}>{product.name}</div>
      <span style={{ color: '#767676' }}>${product.price}</span>
    </a>
  );

Show the whole skill (87 more lines)

}


> See [references/examples-by-framework.md](references/examples-by-framework.md) for Vue, Angular, Next.js, and Svelte examples.

## Tools Reference

### a11y_scanner.py

Usage: python scripts/a11y_scanner.py [options]

Options: --json Output results as JSON --format {table,csv} Output format (default: table) --severity {critical,major,minor} Filter by minimum severity --framework {react,vue,angular,svelte,html,auto} Force framework (default: auto) --baseline FILE Compare against previous scan results --report Generate stakeholder report --output FILE Write results to file --quiet Suppress output, exit code only --ci CI mode: non-zero exit on critical issues


### contrast_checker.py

Usage: python scripts/contrast_checker.py [options]

Options: --fg COLOR Foreground color (hex) --bg COLOR Background color (hex) --file FILE Scan CSS file for color pairs --tailwind DIR Scan directory for Tailwind color classes --json Output results as JSON --suggest Suggest accessible alternatives for failures --level {aa,aaa} Target conformance level (default: aa)


## Common Pitfalls

| Pitfall | Correct Approach |
|---------|------------------|
| `role="button"` on a `<div>` | Use native `<button>` -- includes keyboard handling for free |
| `tabindex="0"` on everything | Only interactive elements need focus; use native elements |
| `aria-label` on non-interactive elements | Use `aria-labelledby` pointing to visible text |
| `display: none` for screen reader hiding | Use `.sr-only` class instead |
| Color alone to convey meaning | Add icons, text labels, or patterns alongside color |
| Placeholder as only label | Always provide a visible `<label>` |
| `outline: none` without replacement | Always provide a visible focus indicator via `focus-visible` |
| Empty `alt=""` on informational images | Informational images need descriptive alt text |
| Skipping heading levels (h1 -> h3) | Heading levels must be sequential |
| `onClick` without `onKeyDown` | Add keyboard support or prefer native elements |
| Ignoring `prefers-reduced-motion` | Wrap animations in `@media (prefers-reduced-motion: no-preference)` |

## Related Skills

| Skill | Relationship |
|-------|-------------|
| **senior-frontend** | Frontend patterns used in a11y fixes |
| **code-reviewer** | Include a11y checks in code review workflows |
| **senior-qa** | Integration of a11y testing into QA processes |
| **playwright-pro** | Automated browser testing with accessibility assertions |
| **epic-design** | WCAG 2.1 AA compliant animations and scroll storytelling |
| **tdd-guide** | Test-driven development patterns for a11y test cases |

## Reference Documentation

| Reference | Description |
|-----------|-------------|
| [wcag-quick-ref.md](references/wcag-quick-ref.md) | WCAG 2.2 Level A & AA criteria quick reference |
| [wcag-22-new-criteria.md](references/wcag-22-new-criteria.md) | New WCAG 2.2 success criteria (Focus Appearance, Target Size, etc.) |
| [aria-patterns.md](references/aria-patterns.md) | ARIA patterns, keyboard interaction, and live regions |
| [framework-a11y-patterns.md](references/framework-a11y-patterns.md) | Framework-specific fix patterns (React, Vue, Angular, Svelte, HTML) |
| [color-contrast-guide.md](references/color-contrast-guide.md) | Color contrast checker details, Tailwind palette mapping, sr-only class |
| [ci-cd-integration.md](references/ci-cd-integration.md) | GitHub Actions, GitLab CI, Azure DevOps, pre-commit hook configs |
| [audit-report-template.md](references/audit-report-template.md) | Stakeholder-ready audit report template |
| [testing-checklist.md](references/testing-checklist.md) | Manual testing checklist (keyboard, screen reader, visual, forms) |
| [examples-by-framework.md](references/examples-by-framework.md) | Full audit examples for Vue, Angular, Next.js, and Svelte |

## Resources

- [WCAG 2.2 Specification](https://www.w3.org/TR/WCAG22/)
- [WAI-ARIA Authoring Practices 1.2](https://www.w3.org/WAI/ARIA/apg/)
- [Deque axe-core Rules](https://github.com/dequelabs/axe-core/blob/develop/doc/rule-descriptions.md)
- [eslint-plugin-jsx-a11y](https://github.com/jsx-eslint/eslint-plugin-jsx-a11y)

Get it through your agent

Call the Graph-of-Skills MCP server's retrieve_skill_bundle tool and it returns this skill's text inside your budget.

{
  "tool": "retrieve_skill_bundle",
  "arguments": {
    "query": "a11y-audit"
  }
}

New to this? Set up Graph-of-Skills or get a free key. The text on this page comes from its authors: how skills are sourced and what we check. If none fits your task, your agent can write a skill for your own library. To keep a skill from your own library on a machine, see how to install one of your skills.

Share on X Share on LinkedIn Share on Bluesky Share on Hacker News

Share on Reddit

Source

Source repository alirezarezvani/claude-skills
Listing on skills.sh

From alirezarezvani/claude-skills via skills.sh

Related skills

accessibility
Audit and improve web accessibility following WCAG 2.2 guidelines. Use when asked to "improve accessibility", "a11y audit", "WCAG compliance", "screen reader support", "keyboard navigation", or "make accessible".
69,170 installs
accessibility-audit
Whole site or product — a full web accessibility (a11y) audit against WCAG 2.2, following the WCAG-EM methodology. Defines scope, samples representative pages and flows, runs the automated tier (`accessibility-scan`) and the hands-on manual tier (`accessibility-inspect`), and produces one conformance report. Grades each finding by severity and evidence basis, and states per-criterion conformance as pass, fail, or undetermined (needs a human). Use it for 'audit my site for accessibility', 'is this product accessible', 'a11y audit', 'WCAG or Section 508 conformance report', or any multi-page assessment. Assesses; does not fix (use `accessibility-fix`) or diff (use `accessibility-diff`). For a single page use `accessibility-scan`; for hands-on keyboard and screen-reader checks use `accessibility-inspect`.
1,280 installs
accessibility-review
Run a WCAG 2.1 AA accessibility audit on a design or page. Trigger with "audit accessibility", "check a11y", "is this accessible?", or when reviewing a design for color contrast, keyboard navigation, touch target size, or screen reader behavior before handoff.
4,334 installs
accessibility-fix
Remediation only — repair web accessibility (a11y) violations against WCAG 2.2 with a baseline, edit, and verify loop. Takes a target (URL, files, directory) or a findings worklist from `accessibility-scan`/`accessibility-inspect`/`accessibility-audit`, applies mechanical fixes as given, leaves TODOs for visual or contextual judgment, and verifies by re-running the baseline check. It only fixes. To find issues use `accessibility-scan` (one page, automated), `accessibility-inspect` (one page, manual), or `accessibility-audit` (whole site, WCAG-EM); to check for regressions use `accessibility-diff`. Use it for 'fix the a11y issues in X', 'make this accessible', 'add missing alt text and labels', 'apply these accessibility fixes', 'remediate these violations'.
1,122 installs
accessibility-audit
Audit an existing interface against WCAG, producing findings with severity ratings and remediation steps. Use when you have a design or build to assess now. Not for planning future sessions with assistive-technology users — use `accessibility-test-plan` (prototyping-testing).
2,402 installs