agentleFS
neeraj181-dotneeraj181-dot/ClaudeSkills/.claude/skills/accessibility-auditor/SKILL.md

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

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
  1. Distinctive:

    Read-only by default: Do not modify code during the audit.

    line 15
  2. Very specific:

    Read manifests: package.json, framework config, component library config.

    line 27
  3. Distinctive:

    When authorized to fix, work in this order:

    line 135
  4. Distinctive:

    Verify the change in context.

    line 143
  5. Distinctive:

    Run the project's build/lint if present.

    line 144
  6. Distinctive:

    Ensure the fix does not break existing functionality.

    line 145
  7. Distinctive:

    If a section has no issues, say so in one line.

    line 176

“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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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:

  1. Read-only by default. Do not modify code during the audit. Only fix when the user explicitly requests it (Phase 11).
  2. 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 — h1 through h6 used in logical order, no skipped levels.
  • Landmark regions — header, nav, main, aside, footer used appropriately.
  • Lists — ul/ol/dl for list content, not styled divs.
  • Tables — th, scope, caption, thead/tbody for tabular data.
  • Buttons vs links — <button> for actions, <a> for navigation. No div or span acting 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-visible styles present; no outline: none without 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-label on non-interactive elements, redundant roles, incorrect aria-* 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-live used 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> (via for/id or wrapping).
  • Required fields — indicated with aria-required or required, 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 — autocomplete attributes 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 have alt attributes. Decorative images use alt="".
  • 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, or role="img" with aria-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-reverse on parent).
  • Hidden content — aria-hidden="true" used correctly to hide decorative/redundant content. display: none or visibility: hidden for content that should not be read.
  • Visually hidden text — .sr-only / .visually-hidden class 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:

  1. Critical barriers (keyboard traps, missing labels on required fields, no alt text on meaningful images).
  2. High-severity issues (missing landmarks, broken heading hierarchy, poor focus management).
  3. Medium-severity issues (ARIA misuse, missing live regions, contrast problems).
  4. 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 Order

For 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.