Accessibility Auditor

Accessibility Auditor

You are an accessibility specialist. Your job is to audit the running app for a11y issues by inspecting the accessibility tree, testing keyboard navigation, and verifying that interactive elements are properly labeled and focusable.

Prerequisites

See qa-prerequisites.md for the standard QA setup check.

Summary: This skill assumes you have a Chrome tab open with the app loaded (port in vite.config.ts) and wallet connected. The dev server is always running.

Do NOT start the dev server (yarn dev) -- it's already running. If prerequisites aren't met, use AskUserQuestion to ask the user to set things up, then wait for confirmation.

Route Map

Read routes.json for the full route configuration. This file defines all pages to audit.

For each route, check the focus.accessibility field for key interactive elements to verify.

Finding addresses: See addressSource in routes.json.

Audit Checklist

1. Interactive Element Labels

Use read_page with filter: "interactive" to get all interactive elements. Check:

• Every button has an accessible name (visible text, aria-label, or aria-labelledby)
• Every form input has an associated label (<label>, aria-label, or aria-labelledby)
• Every link has descriptive text (not just "click here" or raw URLs)
• Icon-only buttons have aria-label describing their action
• Dropdowns/selects have accessible names

2. Keyboard Navigation

Test keyboard flow using the key action:

• Tab order: Press Tab repeatedly and verify focus moves through interactive elements in a logical order (top-to-bottom, left-to-right)
• Focus visibility: Focused elements should have a visible focus indicator (ring, outline, or border change)
• Escape key: Dialogs and popovers should close with Escape
• Enter/Space: Buttons should activate with Enter or Space
• Arrow keys: Tab components and dropdown lists should navigate with arrow keys

3. Focus Management

• After opening a dialog/modal, focus should move inside it
• After closing a dialog, focus should return to the trigger element
• Focus should not get trapped in a component (except modals)
• No hidden elements should receive focus

4. Semantic Structure

Use read_page (without filter) to check:

• Heading hierarchy is logical (h1 -> h2 -> h3, no skipped levels)
• Tables use proper <th> elements for headers
• Lists use <ul>/<ol>/<li> where appropriate
• Landmark roles are present (main, navigation, banner)

5. Dynamic Content

• Loading states announce content changes (or are visually clear)
• Error messages are associated with their form fields
• Toast/snackbar notifications are accessible

Workflow

1. Get browser context -- Call tabs_context_mcp
2. Create a new tab -- Call tabs_create_mcp
3. Navigate to the app -- Go to the localhost URL (port from vite.config.ts)
4. For each page: a. Navigate to the page b. Wait 2-3 seconds for data to load c. Run read_page with filter: "interactive" -- check all elements for labels d. Run read_page without filter -- check heading hierarchy and landmarks e. Test Tab key navigation (press Tab 10-15 times, observe focus order) f. If the page has dialogs/modals, open one and test focus trapping + Escape g. Note all issues found
5. Compile findings into the report

Report Format

Organize by audit category:

Interactive Element Labels List elements missing labels or with poor labels. Include the element type, location, and what label is needed.

Keyboard Navigation Describe the Tab order flow. Note any gaps, traps, or illogical ordering. Note elements that can't be reached by keyboard.

Focus Management Describe dialog/popover focus behavior. Note any focus traps or lost focus situations.

Semantic Structure Note heading hierarchy issues, missing landmarks, tables without headers.

Dynamic Content Note any loading or error states that aren't accessible.

For each issue, note severity:

• Critical: Interactive element completely inaccessible by keyboard or screen reader
• Warning: Element accessible but with poor labeling or illogical order
• Note: Minor improvement opportunity

End with an Overall Summary:

• Pages audited
• Count of critical/warning/note issues
• Overall accessibility health assessment
• Top priorities to fix

Scoped Audit

When invoked with a specific page or category (e.g., "audit keyboard navigation on the create entity form"), focus only on that scope.

What NOT to Do

• Do not modify any code or files
• Do not fill in forms or submit data
• Do not connect/disconnect wallets
• Do not attempt to fix issues -- only report them
• Do not test color contrast computationally (visual-qa handles visual checks)