a11y-audit
by alirezarezvania11y-audit is an accessibility audit skill for frontend codebases that scans, fixes, and verifies WCAG 2.2 Level A and AA issues. It supports React, Next.js, Vue, Angular, Svelte, and HTML with severity-based findings, contrast checks, report templates, and CI/CD guidance.
This skill scores 78/100, which means it is a solid listing candidate for directory users who want an agent-assisted accessibility audit workflow. It has enough concrete workflow content, scripts, examples, and references to justify installation, but users should treat its broad WCAG coverage claims cautiously and expect to do some setup validation.
- Strong triggerability: the frontmatter clearly says to use it for accessibility audits, a11y violation fixes, color contrast checks, compliance reports, and CI/CD accessibility checks.
- Good operational support: the skill includes a substantial SKILL.md plus scanner and contrast-checker scripts, sample inputs, expected JSON/report outputs, and references for WCAG, ARIA, framework patterns, testing, and CI/CD.
- Useful agent leverage: the Scan/Fix/Verify workflow and framework-specific remediation references should help an agent produce more structured audits and fixes than a generic accessibility prompt.
- No install command or README is present in the skill path, so users may need to infer how to install or invoke it in their agent environment.
- The repository evidence includes some overbroad claims such as scanning “every WCAG 2.2 Level A and AA violation,” and the CI example appears to expect a `violations` JSON key while the sample output uses `findings`.
Overview of a11y-audit skill
What a11y-audit is for
a11y-audit is an accessibility audit skill for finding, fixing, and verifying WCAG 2.2 Level A and AA issues in web codebases. It is most useful when you want an AI agent to move beyond general accessibility advice and produce structured findings with severity, WCAG references, framework-aware remediation, and a report that developers or compliance stakeholders can act on.
Best-fit users and projects
The a11y-audit skill fits frontend teams working in React, Next.js, Vue, Angular, Svelte, or plain HTML. It is especially relevant for teams preparing a release, cleaning up known accessibility debt, reviewing pull requests, or adding accessibility checks to CI/CD. It is less useful if you only need broad UX commentary, legal certification, or manual screen reader testing without code-level remediation.
What makes this skill different
The skill is organized around a Scan, Fix, Verify workflow rather than a one-off prompt. Its supporting files include Python scripts for scanning and contrast checking, sample outputs, report templates, CI/CD guidance, WCAG 2.2 references, ARIA patterns, testing checklists, and framework-specific examples. That makes it easier for an agent to produce repeatable audit output instead of vague “improve accessibility” suggestions.
Important adoption considerations
a11y-audit can help identify common code-level violations such as missing alt text, keyboard-inaccessible click handlers, missing labels, positive tabIndex, table header problems, ARIA misuse, and contrast failures. It should still be paired with human review, browser testing, keyboard testing, and assistive technology checks. Automated and AI-assisted auditing cannot fully validate user intent, content meaning, focus experience, or real screen reader behavior.
How to Use a11y-audit skill
a11y-audit install and repository path
Install the skill from the GitHub repository with:
npx skills add alirezarezvani/claude-skills --skill a11y-audit
The skill lives at:
engineering-team/a11y-audit/skills/a11y-audit
After installation, read SKILL.md first, then inspect references/wcag-quick-ref.md, references/testing-checklist.md, references/framework-a11y-patterns.md, references/aria-patterns.md, and references/ci-cd-integration.md. Preview expected_outputs/sample-scan-report.md and expected_outputs/sample-scan-output.json so you know what good output should look like before asking the agent to audit your own code.
Inputs that produce better audits
For strong a11y-audit usage, give the agent the actual component files, framework, routing context, design-system constraints, and target standard. A weak prompt is:
“Check this page for accessibility.”
A stronger prompt is:
“Use the a11y-audit skill to review these React components for WCAG 2.2 Level AA. Focus on keyboard access, form labels, image alternatives, table semantics, ARIA use, and color contrast. Return findings grouped by severity with file/line references, WCAG criteria, before/after code, and verification steps. Do not change our design-system Button API.”
This gives the skill enough context to prioritize real fixes and avoid generic rewrites.
Suggested Scan, Fix, Verify workflow
Start with a focused scan of a small surface area: one page, component folder, or pull request. Ask for JSON-style findings if you need machine-readable output, or a markdown report if humans will review it. Then ask the agent to fix critical and serious issues first, preserving existing behavior and framework conventions.
A practical sequence:
- Run or request a scan for a defined path such as
src/components/UserCard.tsx. - Review findings by severity and WCAG criterion.
- Apply fixes in small batches: keyboard support, labels, semantics, contrast, ARIA.
- Ask the skill to verify that each original issue is resolved.
- Produce a final report using the structure in
references/audit-report-template.md.
Using the included scripts and references
The repository includes scripts/a11y_scanner.py and scripts/contrast_checker.py. Use them as practical helpers or examples when you want reproducible checks outside the chat session. The contrast sample shows exact ratios and pass/fail thresholds for normal text, large text, and UI components. The CI/CD reference includes a GitHub Actions pattern for failing pull requests on critical accessibility violations, which is useful if you want a11y-audit for Frontend Development workflows that prevent regressions instead of only producing one-time reports.
a11y-audit skill FAQ
Is a11y-audit suitable for beginners?
Yes, if you have basic frontend knowledge. The skill explains violations with WCAG references and concrete fixes, so it can teach while auditing. Beginners should start with one component and ask for explanations of each issue before applying broad changes across a codebase.
How is it better than an ordinary accessibility prompt?
A normal prompt may produce a checklist or generic recommendations. The a11y-audit skill provides a more constrained workflow, severity model, sample outputs, report format, framework examples, ARIA guidance, contrast guidance, and CI/CD integration notes. That structure helps an agent produce output that is easier to review, implement, and verify.
Can it certify WCAG compliance?
No. a11y-audit can support WCAG 2.2 Level A and AA remediation, but it does not replace a formal accessibility audit, user testing, legal review, or assistive technology validation. Treat it as a developer-focused audit and remediation accelerator, not a certification authority.
When should I not use a11y-audit?
Do not rely on it alone for native mobile apps, PDF accessibility, video captioning workflows, legal conformance statements, or complex assistive technology behavior that requires manual testing. It is strongest on web UI source code, especially HTML and modern frontend framework components.
How to Improve a11y-audit skill
Make a11y-audit prompts more specific
The most common failure mode is asking for an audit without enough source context. Include framework, file paths, component purpose, relevant CSS or design tokens, and whether changes must preserve public APIs. If color is involved, provide foreground and background values, not just class names. If forms are involved, include validation behavior and visible label requirements.
Ask for fixes that match your codebase
Tell the skill your preferred patterns. For example: “Use our existing <Button> and <TextField> components,” “avoid adding ARIA when semantic HTML is available,” or “keep route behavior unchanged.” This reduces overcorrection, such as replacing components unnecessarily or adding redundant roles to semantic elements.
Validate beyond the first answer
After the first report, ask a11y-audit to verify each fix against the original WCAG criterion and identify possible regressions. Good follow-up prompts include: “Check keyboard order after these changes,” “Confirm the accessible names for all icon buttons,” and “Review whether these ARIA attributes are necessary or harmful.” This turns the skill from a scanner into a remediation loop.
Add project-specific guardrails
For recurring use, maintain a short internal accessibility brief with your supported frameworks, design-system components, severity policy, browser support, and CI threshold. Pair that with the repository references such as testing-checklist.md, wcag-22-new-criteria.md, and ci-cd-integration.md. The more consistently you define acceptance criteria, the more useful a11y-audit becomes for pull requests, release checks, and long-term frontend quality.