A11y Audit Example

[dlabaj]

Agent Name

a11y-audit

Problem It Solves

An agent that runs and analyzes the accessibility of a react front end application. It does this by statically analyzing the repo, looking for a11y violations.

Agent Markdown

---

description: Perform a comprehensive accessibility (a11y) audit of the codebase

You are performing an accessibility audit of this React codebase. Use the Task tool with subagent_type=Explore to conduct a thorough analysis.

Analysis Areas

1. Images and Media

• Find all <img> elements and verify they have meaningful alt attributes
• Check for decorative images that should have alt="" or role="presentation"
• Look for background images in CSS that convey important information
• Check <svg> elements have appropriate aria-label or <title> elements

2. Interactive Elements

• Find buttons/links without accessible text content
• Check for onClick handlers on non-interactive elements (div, span) without:
  • Proper role attributes (e.g., role="button")
  • tabIndex={0} for keyboard access
  • onKeyDown handlers for Enter/Space keys
• Verify form inputs have associated labels (via <label>, aria-label, or aria-labelledby)
• Check that custom components with interactive behavior implement keyboard navigation

3. ARIA Usage

• Look for incorrect ARIA roles (e.g., role="button" on actual <button> elements)
• Check for missing required ARIA attributes (e.g., aria-expanded on expandable elements)
• Find elements with aria-label that might be redundant or incorrect
• Verify aria-hidden="true" is not used on focusable elements
• Check that ARIA landmarks are used appropriately

4. Semantic HTML

• Find instances where divs/spans are used instead of semantic elements (button, nav, main, header, etc.)
• Check heading hierarchy (h1, h2, h3) is logical and sequential
• Verify lists use proper <ul>, <ol>, <li> structure
• Check tables have proper <th>, <caption>, and scope attributes

5. Keyboard Navigation

• Find modal/dialog implementations and check for focus trapping
• Verify focus management in dynamic content (e.g., after route changes, opening panels)
• Check for keyboard event handlers alongside mouse event handlers
• Look for tabIndex values greater than 0 (anti-pattern)

6. Forms

• Check all form inputs have labels
• Verify error messages are associated with inputs (aria-describedby, aria-invalid)
• Look for required field indicators that are accessible
• Check for autocomplete attributes where appropriate

7. Color and Contrast

• Search for hardcoded color values in styles
• Flag cases where color alone conveys meaning
• Look for custom focus indicators and verify they're visible

8. Dynamic Content

• Check for live regions (aria-live, role="status", role="alert")
• Verify loading states are announced to screen readers
• Look for content that updates without page refresh

Output Format

Provide your findings in this format:

Summary

• Total files analyzed: X
• Critical issues: X
• Warnings: X
• Suggestions: X

Critical Issues

Issues that make content inaccessible:

• [Issue description] in file_path:line_number
  • Current code: ...
  • Recommendation: ...

Warnings

Issues that may cause accessibility problems:

• [Issue description] in file_path:line_number
  • Recommendation: ...

Suggestions

Best practice improvements:

• [Suggestion] in file_path:line_number

Positive Findings

Highlight examples of good accessibility practices found in the codebase.

Instructions

1. Use the Task tool with subagent_type=Explore and thoroughness level "very thorough"
2. Focus on the component library source code (typically in src/ or packages/)
3. Prioritize critical issues that completely block accessibility
4. Provide specific file paths and line numbers for all findings
5. Include code snippets to illustrate issues
6. Offer concrete, actionable recommendations

Start the audit now.

Testing Notes (Optional)

• Download a repo
• Enter the repo, start claude and run the slash command /a11y-audit

Tested on: Dataview

What worked:
Found a11y issues.

What needs improvement:
Output needs to be formatted in table format.

Edge cases or limitations:
Recommended to use this as a follow up for a11y testing, not in-lieu of testing.