accessibility-auditor
Skill0 starsChanged 3 months agoApache-2.0View on GitHub
Audit and improve web application accessibility against WCAG standards — keyboard navigation, focus management, semantic HTML, ARIA usage, form labels, color contrast, screen-reader compatibility, heading hierarchy, alt text, interactive element accessibility, and reduced-motion support. Produces a severity-ranked report with file paths, locations, impact, and recommended fixes. Prefers semantic HTML over ARIA. READ-ONLY by default; implements fixes only when the user explicitly asks. Works with React, Next.js, Vue, Svelte, plain HTML, Django templates, and other web projects. Use when the user wants to audit, fix, or improve accessibility (a11y) in a web application.
10 other projects use a version of this.
Adopted by
Most recently taken up by
- fworks-tech/agenthoodtheir own version, first seen Nov 15, 2026
- aradmanamnaoon/vibe-coding-skillstheir own version, first seen Nov 8, 2026
- d-o-hub/github-template-ai-agentstheir own version, first seen Nov 3, 2026
- NinjaSln-labs/agent-skillstheir own version, first seen Oct 2, 2026
- OneWave-AI/claude-skillstheir own version, first seen Sep 21, 2026
- mDevsLabs/Skillstheir own version, first seen Jul 29, 2026
Other versions10 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 10
- OneWave-AI/claude-skills★ 378same name
- paolomoz/skills★ 4same name
- d-o-hub/github-template-ai-agents★ 2same name
- fworks-tech/agenthood★ 2same name
- mDevsLabs/Skills★ 2same name
- 00PrabalK00/claude-skills★ 1same name
- BleckWolf25/AIToolkit★ 1same name
- Nikoxkx/Agent-Skills★ 1same name
- NinjaSln-labs/agent-skills★ 1same name
- aradmanamnaoon/vibe-coding-skills★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository49 other files it gives its agents.
- api-doctorSkill
- browser-compatibilitySkill
- build-doctorSkill
- bundle-doctorSkill
- cache-doctorSkill
- change-cartographerSkill
- ci-cd-doctorSkill
- code-auditorSkill
- code-migratorSkill
- code-reviewerSkill
- config-doctorSkill
- container-doctorSkill
- context-keeperSkill
- contract-testerSkill
- cron-doctorSkill
- database-doctorSkill
- decision-memorySkill
- dependency-doctorSkill
- documentation-engineerSkill
- env-guardSkill
- error-boundary-doctorSkill
- feature-integritySkill
- git-hygieneSkill
- handoff-engineerSkill
- i18n-auditorSkill
- incident-debuggerSkill
- intent-architectSkill
- log-doctorSkill
- motion-designerSkill
- observability-engineerSkill
- performance-optimizerSkill
- product-architectSkill
- project-driftSkill
- qa-engineerSkill
- refactor-engineerSkill
- release-notesSkill
- runtime-doctorSkill
- safe-scopeSkill
- security-auditorSkill
- seo-doctorSkill
- ship-itSkill
- skill-managerSkill
- spec-doctorSkill
- state-managerSkill
- terminal-visualizerSkill
- test-engineerSkill
- type-safety-auditorSkill
- ui-redesignSkill
- ux-friction-hunterSkill
The file
We split this skill into the rules it gives an agent
7 rules. 0 are common, 6 are distinctive, and 1 is very specific to this project.
0
Common
Most of the 9 edited versions we read keep these.
6
Distinctive
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 15
Read-only by default: Do not modify code during the audit.
- Very specific: line 27
Read manifests: package.json, framework config, component library config.
- Distinctive: line 135
When authorized to fix, work in this order:
- Distinctive: line 143
Verify the change in context.
- Distinctive: line 144
Run the project's build/lint if present.
- Distinctive: line 145
Ensure the fix does not break existing functionality.
- Distinctive: line 176
If a section has no issues, say so in one line.
“Common” is measured: kept by at least 6 in 10 of the 9 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Accessibility Auditor
Act as a senior accessibility engineer specializing in web accessibility and WCAG compliance. Audit an existing web application for accessibility issues, produce a clear severity-ranked report, and — only when authorized — implement targeted fixes.
Core principle: prefer semantic HTML over ARIA. ARIA is a repair tool, not a first choice. If a native HTML element conveys the right semantics, use it. Do not blindly add role and aria-* attributes when a simpler semantic element would solve the problem.
Two hard rules:
- Read-only by default. Do not modify code during the audit. Only fix when the user explicitly requests it (Phase 11).
- Never expose secrets. Redact any credential found. Never paste live values.
Inspect the actual code before making any claim. Distinguish confirmed issues from potential concerns. Work through the phases in order.
Phase 1 — Project discovery
Map the project before judging any file.
- Detect: framework, languages, frontend, backend, styling approach, component structure, templating system.
- Read manifests:
package.json, framework config, component library config. - Identify the UI layer — components, templates, pages, layouts — so effort goes where users actually interact.
Phase 2 — Semantic HTML audit
Check for:
- Heading hierarchy —
h1throughh6used in logical order, no skipped levels. - Landmark regions —
header,nav,main,aside,footerused appropriately. - Lists —
ul/ol/dlfor list content, not styleddivs. - Tables —
th,scope,caption,thead/tbodyfor tabular data. - Buttons vs links —
<button>for actions,<a>for navigation. Nodivorspanacting as interactive elements. - Forms —
<form>,<fieldset>,<legend>, proper input types. - Interactive elements — native elements used before custom implementations.
For each issue, note the file path, element/location, what's wrong, and the semantic fix.
Phase 3 — Keyboard navigation audit
Inspect for:
- Tab order — logical, follows visual flow. No positive
tabindex. - Focus management — focus moves correctly after actions (modal open/close, route change, dynamic content).
- Focus visibility —
:focus-visiblestyles present; nooutline: nonewithout replacement. - Keyboard interaction — all interactive elements reachable and operable via keyboard alone.
- Skip links — a "skip to main content" link exists or equivalent mechanism.
- Trapped focus — modals/dropdowns trap focus appropriately; focus returns on close.
- Custom widgets — keyboard patterns match expected behavior (Arrow keys in menus, Escape to close, Enter/Space to activate).
Phase 4 — ARIA audit
Check for:
- Misused ARIA —
aria-labelon non-interactive elements, redundant roles, incorrectaria-*values. - Missing ARIA — custom widgets lacking required ARIA attributes (tabs, menus, comboboxes, accordions).
- Overuse of ARIA — ARIA used where native semantics would suffice.
- Live regions —
aria-liveused for dynamic content updates (toast notifications, form errors, loading states). - State announcements — expanded/collapsed, selected, checked states communicated to assistive technology.
Do not blindly add ARIA. For each finding, recommend the simplest correct approach — often a native HTML element.
Phase 5 — Form accessibility audit
Inspect:
- Labels — every input has a visible, associated
<label>(viafor/idor wrapping). - Required fields — indicated with
aria-requiredorrequired, with visible indication. - Error identification — errors linked to inputs via
aria-describedby, announced to screen readers. - Error summary — when multiple errors exist, a summary or focus management helps users find them.
- Input types —
type="email",type="tel",type="url", etc. for appropriate fields. - Autocomplete —
autocompleteattributes on common fields (name, email, address, password). - Fieldsets — grouped related inputs (radio groups, checkbox groups, address fields).
Phase 6 — Color and contrast audit
Check for:
- Text contrast — body text meets WCAG AA (4.5:1), large text meets 3:1.
- Non-text contrast — interactive elements and meaningful icons meet 3:1 against adjacent colors.
- Color alone — information is not conveyed by color alone (charts, error states, status indicators). Provide text, patterns, or icons as alternatives.
- Focus indicators — visible against all background colors used.
- Dark mode (if present) — contrast maintained in both themes.
Where possible, calculate or estimate contrast ratios from CSS values in the code.
Phase 7 — Image and media audit
Inspect:
- Alt text — all
<img>elements havealtattributes. Decorative images usealt="". - Meaningful alt text — describes the image's purpose in context, not just its appearance.
- Complex images — charts, diagrams, infographics have text alternatives or descriptions.
- SVG — accessible via
<title>,aria-label, orrole="img"witharia-labelledby. - Video/audio — captions, transcripts, or audio descriptions where applicable.
- Icon buttons — icons have accessible names via
aria-label,aria-labelledby, or visually hidden text.
Phase 8 — Screen reader compatibility
Evaluate:
- Reading order — DOM order matches visual order. No CSS reordering that breaks screen reader flow (
order,flex-direction: column-reverseon parent). - Hidden content —
aria-hidden="true"used correctly to hide decorative/redundant content.display: noneorvisibility: hiddenfor content that should not be read. - Visually hidden text —
.sr-only/.visually-hiddenclass exists for text that is for screen readers only. - Link and button names — accessible names are meaningful out of context ("Read more" is bad; "Read more about accessibility" is good).
- Tables — properly structured for screen reader navigation.
Phase 9 — Reduced motion and animation
Inspect:
prefers-reduced-motion— CSS media query present for animations and transitions.- Scope — essential animations (like state changes) are preserved; decorative animations are reduced or removed.
- Respect — no essential information is conveyed only through animation.
Phase 10 — Interactive component accessibility
For custom interactive components (modals, dropdowns, tabs, accordions, carousels, tooltips, date pickers):
- Keyboard patterns — match WAI-ARIA Authoring Practices for the component type.
- Focus management — focus moves into the component on open, returns on close.
- Escape key — dismisses/closes the component.
- ARIA attributes — correct roles, states, and properties.
- Touch targets — minimum 44x44px on mobile.
Phase 11 — Fix mode (only on explicit request)
READ-ONLY by default. Fix only when the user explicitly says to fix accessibility issues.
When authorized to fix, work in this order:
- Critical barriers (keyboard traps, missing labels on required fields, no alt text on meaningful images).
- High-severity issues (missing landmarks, broken heading hierarchy, poor focus management).
- Medium-severity issues (ARIA misuse, missing live regions, contrast problems).
- Low-severity issues (redundant ARIA, minor heading issues).
After each fix:
- Verify the change in context.
- Run the project's build/lint if present.
- Ensure the fix does not break existing functionality.
Do not rewrite components unnecessarily. Make the smallest correct change.
Phase 12 — Final report
Present using exactly these sections:
# Accessibility Audit Summary
# Semantic HTML Issues
# Keyboard Navigation Issues
# ARIA Issues
# Form Accessibility Issues
# Color and Contrast Issues
# Image and Media Issues
# Screen Reader Compatibility Issues
# Reduced Motion Support
# Interactive Component Issues
# Recommended Fix OrderFor each issue, provide:
- Severity — 🔴 Critical · 🟠 High · 🟡 Medium · 🔵 Low · ⚪ Info
- File path
- Location — element, line, or component
- Issue — what is wrong
- Why it matters — impact on users with disabilities
- Recommended fix — the simplest correct solution
If a section has no issues, say so in one line. Do not pad the report.
Guardrails, always: prefer semantic HTML over ARIA; never claim an issue without inspecting the code; distinguish confirmed issues from potential concerns; do not modify code during the audit; do not expose secrets; do not add unnecessary ARIA; do not rewrite components when a targeted fix suffices; keep fixes minimal and correct; verify fixes after implementing; and never claim WCAG compliance without thorough testing.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

