A reliable accessibility audit for a React application combines automated testing with human checks. This guide compares axe, Lighthouse, browser DevTools, Storybook accessibility testing, keyboard navigation, and screen-reader review, then turns them into a repeatable pull-request and CI workflow.
Overview
No single accessibility testing tool can identify every usability barrier. Automated tools are effective at finding certain patterns, such as missing accessible names, invalid ARIA relationships, and some color-contrast problems. They do not replace testing with a keyboard, a screen reader, or a person who understands the intended interaction.
For a React or modern web application, the most productive approach is to test at several levels:
- Component level: Catch regressions while developing reusable buttons, dialogs, forms, menus, and data displays.
- Page level: Check routes, layouts, content states, and integrations in a browser.
- End-to-end level: Verify that users can complete important flows with keyboard and assistive technology.
- Release level: Review representative pages and document findings that automation cannot reliably judge.
Think of these tools as complementary rather than interchangeable. axe is useful for focused automated rule checks, Lighthouse provides a broader page audit, browser DevTools help investigate the rendered interface, and Storybook can bring accessibility checks close to component development. Manual keyboard and screen-reader checks supply the context that automated WCAG testing lacks.
| Tool or method | Best use | What it cannot prove |
|---|---|---|
| axe | Automated checks in tests, Storybook, or a browser | That a complete user journey is understandable and usable |
| Lighthouse | A quick page-level review during development or release checks | That every state, route, or interaction is accessible |
| Browser DevTools | Inspecting the accessibility tree, focus behavior, and rendered semantics | That the design works for all assistive-technology users |
| Storybook accessibility testing | Checking isolated components and their documented states | How components behave in the full application context |
| Keyboard and screen-reader checks | Validating real interaction paths and communication | Fast, complete coverage of every page and code path |
Checklist by scenario
When building a reusable React component
- Give the component a semantic HTML foundation before adding ARIA. A native button, label, heading, or list often provides behavior that is difficult to recreate correctly.
- List the component's meaningful states: loading, empty, error, disabled, expanded, selected, and validation failure where applicable.
- Render each state in Storybook or an equivalent component-development environment.
- Run an automated accessibility check against each important story. Treat findings as development feedback, not as a complete sign-off.
- Use the keyboard to confirm focus order, visible focus, activation, escape behavior, and recovery after a dialog or menu closes.
- Check that the accessible name and role make sense in the browser's accessibility inspection tools.
Component isolation is especially useful for design systems. It reduces the time between introducing a regression and locating its cause. It also makes review more concrete: a pull request can show the component's keyboard behavior and state coverage rather than relying only on a screenshot.
When reviewing a page or route
- Run Lighthouse or another page-level audit against the rendered route, not only the source markup.
- Run axe in the browser or through your test setup to identify rule violations that need investigation.
- Inspect headings, landmarks, form labels, link purpose, image alternatives, and error messages.
- Tab through the complete page. Confirm that the focus indicator remains visible and that no interactive control is skipped or trapped.
- Repeat the review for meaningful states, including open navigation, validation errors, permission messages, loading completion, and empty results.
A page audit is more useful when it follows a user task. For example, review the complete path from opening a form to submitting it and resolving an error, rather than checking only the initial page load.
When preparing a pull request
- Run the project's automated accessibility tests locally.
- Confirm that new interactive elements have a keyboard path.
- Review changes to labels, headings, focus management, color usage, and status messages.
- Test at least one narrow viewport and one representative desktop layout if responsive behavior changes.
- Record known limitations as explicit follow-up work instead of silently accepting a failing check.
Keep this checklist close to the pull-request template. The goal is not to create paperwork; it is to make the same small set of checks habitual for every UI change. For broader frontend testing context, see the practical comparison of frontend testing tools.
When adding accessibility checks to CI
- Choose a stable set of representative components, routes, and user flows.
- Run fast component checks on ordinary pull requests.
- Run route-level or end-to-end checks for changes that affect navigation, forms, dialogs, authentication, or shared layout.
- Fail the build for newly introduced violations, while managing legacy findings through a tracked baseline or remediation plan.
- Keep the CI environment consistent enough that changes in browser rendering or test data do not create unexplained noise.
- Have a person review any exception before it becomes permanent.
Automation works best when it produces actionable failures. A large, unowned list of existing violations teaches contributors to ignore the tool. Start with high-value surfaces and expand coverage as the team learns which checks are stable and useful.
What to double-check
Names and instructions: Every control should communicate its purpose through its accessible name. Placeholder text should not be the only instruction for a form field. If an icon-only button is necessary, verify its name and its visible tooltip or surrounding context.
Focus management: Opening a modal, menu, or custom picker should place focus where the user expects. Closing it should return focus to a sensible control. Route changes and dynamically inserted content should not leave keyboard users guessing where they are.
State communication: Visual changes such as success, failure, expanded, selected, or busy should be available through appropriate semantics or text. Check both the initial state and the transition between states.
Reading order: Compare visual order with DOM order. CSS layout can make an interface appear logical while presenting content in a confusing sequence to keyboard or screen-reader users.
Contrast and non-color cues: Automated checks may flag some contrast issues, but review the interface in context. Do not communicate errors, selection, or status through color alone; add text, shape, iconography, or another perceivable cue.
Dynamic React behavior: Re-rendering can remove focus, replace content, or create duplicate IDs. Test after state updates, not just after the first render. React DevTools can help trace component state and rerenders during this investigation; the React DevTools guide is a useful companion for that workflow.
Common mistakes
- Treating a passing scan as an accessibility certificate. Automated tools cover detectable rules, not comprehension, task completion, or every assistive-technology combination.
- Testing only the happy path. Error, loading, empty, and permission states often contain the most important accessibility problems.
- Adding ARIA before fixing HTML. Extra roles and properties can create conflicting or misleading semantics when native elements would have worked.
- Testing only static markup. React applications change after user actions, data fetching, and navigation. Include those transitions in the audit.
- Ignoring focus because the mouse flow works. A successful click-through does not show whether keyboard users can reach, operate, and leave each control.
- Suppressing findings without documenting why. A disabled rule should have a reason, an owner, and a review date.
When to revisit
Revisit the workflow whenever a shared component, routing pattern, form system, design token, or testing integration changes. It is also worth scheduling a broader review before a major release, after a substantial redesign, and during accessibility remediation work.
Tool integrations, browser behavior, package APIs, and WCAG guidance can change. Check the current documentation for the versions used by your project before copying CI configuration or assuming that a rule has the same coverage. Review the audit itself at least when the application adds new interaction patterns, such as complex tables, drag-and-drop, rich text editing, virtualized lists, or custom comboboxes.
For a practical recurring routine, use this sequence:
- Run automated component and route checks.
- Investigate each finding in the rendered interface.
- Keyboard-test the affected flow from start to finish.
- Use a screen reader for high-value journeys and dynamic states.
- Record unresolved issues with an owner and a follow-up point.
- Update the checklist when the application's tools or interaction patterns change.
This combination keeps accessibility testing integrated with developer productivity rather than postponing it to a final audit. The result is a workflow that catches regressions early, makes manual review deliberate, and gives every release a clear set of checks to repeat.
