Accessibility
Accessibility testing for design system components
Overview
The VA Design System is built on a foundation of accessibility. We test components to meet WCAG 2.2 Level AA standards and Section 508 of the Rehabilitation Act, and we strive to go beyond compliance to ensure an inclusive and equitable experience for everyone.
Working together to ensure accessibility
The Design System team tests components in isolation, which means we can’t account for accessibility issues that emerge from surrounding context, like page structure, content, or how multiple components interact. Building accessible products for Veterans requires a partnership between the Design System team and the product teams who implement our components. This page outlines each team’s role in that effort.
What we do
We review accessibility throughout the component development lifecycle:
- Define requirements — Before design begins, we document accessibility expectations and concerns in an architecture document
- Review design — Visual and code designs are reviewed against these accessibility requirements
- Test during development — Components are evaluated during and after development to ensure they meet requirements, which we refine as needed
- Audit before release — Our accessibility specialists conduct a final audit using the Accessibility Test Library before the component goes to staging review, where the VA Platform accessibility team conducts an independent review
How we audit components
Our audit process includes:
Code review — We review component code for valid HTML usage, proper ARIA implementation, and correct labeling techniques to ensure semantic markup and maximum compatibility with assistive technologies.
Automated scans — Each component variation is scanned with axe-core via Cypress and browser extensions to identify potential accessibility issues.
Manual testing — We test across multiple assistive technologies and input methods:
- Screen readers (text to speech)
- Voice command (speech to text)
- Zoom and screen magnification
- Keyboard-only navigation
- Mouse-only navigation
- Touch-only navigation
Note: Alternative input devices such as sip-and-puff switches, eye-tracking software, and refreshable Braille displays are not directly tested. However, these devices typically map to keyboard or mouse interactions, so robust support for keyboard and mouse combined with semantic HTML and proper ARIA usage ensures compatibility.
We test with these assistive technologies on real devices in the following environments:
Screen readers:
- macOS Safari/VoiceOver (required)
- Windows Chrome/JAWS (required)
- Windows Edge/NVDA (required)
- macOS Chrome/VoiceOver
- Android Chrome/Talkback
- iOS Safari/VoiceOver
Voice control:
- macOS Voice Control
- Windows Voice Recognition
Mobile browsers:
- Android Chrome (required)
- iOS Safari (required)
Desktop browsers:
- macOS Safari
- Windows Chrome
- macOS Chrome
- macOS Edge
- Windows Edge
See the Accessibility Test Library for complete test procedures and expected behaviors.
Test results on component pages
We publish audit results on each component’s documentation page in an “Accessibility tests” section. These results show which tests were run, the outcome in each environment (Passed, Failed, or Conditional), and when the tests were last performed. See the Accessibility Test Library for details on what each status means.
This helps teams understand what has been validated and where they should focus their own testing.
We’re actively auditing components, so not all component pages have test results yet. As we complete audits, results will be added to each component page.
What teams must do
Using Design System components alone does not guarantee that your product is accessible. Teams building products on VA.gov are responsible for testing their own products for accessibility and meeting the VA.gov Experience Standards.
Our component-level testing helps catch issues early, but your product must still pass a holistic accessibility review before launch.
Test in your product context
Some accessibility criteria can only be evaluated in the context of a full page or user flow. When using components, test how they function within your complete experience.
In the Accessibility Test Library, these context-dependent tests are marked as “conditional” in component test results, meaning they can only be evaluated in your implementation of the component. The following areas are typically marked as conditional in the test library, so be sure to test for these in your products:
Common areas to evaluate:
- Heading hierarchy: Do component headings fit into the overall heading hierarchy of the page? Is nearby content grouped logically?
- Buttons and link text: Is hardcoded text appropriate for your user flow? When adding your own text, is it meaningful and descriptive?
- Labels: Are labels appropriate and clearly understood? Are they concise and easy to follow?
- Form grouping: Are related form inputs properly grouped using fieldsets with descriptive legends?
- Plain language: Do error messages clearly describe the issue and provide a path for resolution?
- Color contrast: Check contrast against backgrounds and nearby or adjacent elements
Use automated tools
Make sure axe-core is set up in your implementation to catch common automated issues. Automated testing should be part of your continuous integration process.
Write end-to-end (e2e) tests to cover accessibility tests that can be automated. While many accessibility tests must be performed manually, many accessibility-focused code checks can be validated programmatically. Incorporating these into your e2e test suite ensures consistent accessibility coverage as your product evolves.
Conduct manual testing
We recommend a mix of automated, semi-automated, and manual testing.
Whenever possible, conduct tests with real users of assistive technologies. People who rely on assistive technologies daily can identify usability issues that may not be caught by manual testing alone, even when following established procedures. Their feedback provides invaluable insights into the actual experience of navigating your product.
Testing resources
For guidance on how to test with assistive technologies:
- VA Platform accessibility testing manual — General testing procedures and requirements
- VA Platform guidance to prepare for an accessibility staging review — Instructions for completing accessibility testing prior to the collaboration cycle’s staging review
- WebAIM screen reader testing — How to test with screen readers
- WebAIM keyboard testing — How to test keyboard accessibility
Report accessibility defects
If you identify an accessibility defect in a component, please submit an issue on GitHub describing the defect.