Accessibility
Accessibility testing for design system components
Overview
Accessibility specialists on the VA.gov design system team test components before they are added or updated in the Design System. Our goal is to establish a reliable baseline of accessible behavior for each component, including expected interactions, compatibility with common assistive technologies, and known limitations. Testing is an ongoing process that’s revisited as components evolve.
For the specific tests we run and how to interpret test results on component pages, see the Accessibility Test Library.
What the design system provides
The design system establishes baseline accessible behavior for individual components, including:
- Expected interaction patterns (for example: focus management, announcements, and state changes)
- Semantic structure and labeling
- Compatibility with common assistive technologies and input methods
What the design system does not guarantee
Using design system components alone won’t guarantee that your product is accessible.
Accessibility issues can still be introduced when:
- Components are combined in complex ways
- Content or labels aren’t clear or are misleading
- Components are used in contexts that weren’t anticipated during testing
Product teams are responsible for evaluating accessibility in the context of their full experience.
How components are tested
We evaluate accessibility through a combination of code review, automated tooling, and manual testing across assistive technologies and input methods. Each method contributes a different perspective, and no single approach is sufficient on its own. Accessibility issues often emerge through interaction and state changes, which is why manual testing across assistive technologies is a core part of this process.
Testing principles
POUR
Each component is evaluated against the four principles of accessibility:
- Perceivable - Information and user interface components must be presentable to users in ways they can perceive.
- Operable - User interface components and navigation must be operable.
- Understandable - Information and the operation of user interface must be understandable.
- Robust - Content must be robust enough that it can be interpreted reliably by a wide variety of user agents, including assistive technologies.
WCAG 2.2 AA
These principles are the foundation of Section 508 of the Rehabilitation Act, which incorporates Web Content Accessibility Guidelines (WCAG) 2.0 Level AA success criteria. We aim to adhere to the latest version of WCAG Level AA, which is currently WCAG 2.2. We strive to not only meet those standards, but to go beyond compliance with thorough testing to ensure that we’re creating an inclusive and equitable experience for everyone.
Behavior-based testing
Accessibility tests are derived from expected user interactions and outcomes. For example:
- When a user completes an action, the result is communicated clearly
- When content updates dynamically, the change is announced appropriately
- When an error occurs, the user is informed and can recover
This approach helps ensure components behave consistently across assistive technologies and input methods.
Multiple types of assistive technologies
Components are evaluated across a range of assistive technologies and interaction modalities, including:
- Screen readers
- Voice command software
- Screen magnification tools
- Browser display settings
- Keyboard, mouse, and touch input
Testing methodology
Code review
We review component code to ensure semantic HTML, appropriate ARIA (Accessible Rich Internet Applications) usage, and clear labeling. This helps ensure components are correctly interpreted by browsers and assistive technologies.
Automated scans
We use automated tools, such as aXe DevTools, to identify common accessibility issues. Automated testing supports, but does not replace, manual evaluation.
Readability evaluation
Components and patterns are evaluated for clear and understandable content, including heading structure, link and button text, labels, and adherence to plain language standards.
Use of color
Components are tested for sufficient color contrast and to ensure information is not communicated through color alone.
Text resizing, zoom, and magnification
Components are tested at up to 400% browser zoom and with screen magnification tools to ensure layouts remain usable and content remains readable.
Screen readers
Components are tested with the following screen reader and browser combinations:
- JAWS + Chrome on Windows
- NVDA + Edge on Windows
- VoiceOver + Safari on MacOS
- TalkBack + Chrome on Android
- VoiceOver + Safari on iOS
We verify that content is announced in logical order, interactive elements have appropriate accessible names and states, and common screen reader interaction patterns are supported.
Input and interaction methods
Components are tested across different input methods, including keyboard, mouse, touch, and voice control.
- Voice Control + Safari on MacOS
- Dragon + Edge or Chrome on Windows
We verify keyboard accessibility (focus management, keyboard operability, and visible focus indicators), touch and mouse compatibility (appropriate target sizes and gesture support), and voice command compatibility (accessible names that match visible labels).
Alternative input devices such as sip-and-puff switches, eye-tracking software, and refreshable Braille displays are not directly tested but are supported through robust keyboard and mouse support, along with standards-based code and proper ARIA usage.
Using components in your product
We test design system components in isolation. While these tests provide a baseline of accessible behavior, issues may emerge when components are used together or placed within a broader page context.
Accessibility testing expectations
Teams building products on VA.gov are responsible for testing their own products for accessibility and meeting the VA.gov Experience Standards. Teams are also required to complete an accessibility testing artifact as they prepare for a staging review.
What to evaluate
When using a component, teams should evaluate how it functions within the full experience.
Readability and structure
Readability depends on surrounding context. Evaluate:
- Headings and sub-headings
- 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?
- Plain language
- Do error messages clearly describe the issue and provide a path for resolution?
Color considerations
When using a component, teams should check:
- Color contrast against backgrounds and nearby or adjacent elements.
Report accessibility defects
If you identify an accessibility defect in a component, please submit an issue on GitHub describing the defect.
Scope and limitations
Accessibility testing for design system components is intentionally scoped.
- We test components in isolation, not within full product flows
- We don’t test all assistive technology and browser combinations
- Some accessibility issues may only emerge in real-world product contexts
The design system provides a tested baseline, but accessibility must be validated at the product level.
Test results on component pages
The Accessibility Test Library defines the specific tests, expected behaviors, and environments used to evaluate components.
On each component page, the “Accessibility tests” section shows:
- Which tests apply to the component
- The status of those tests (Pass, Failed, Conditional)
- The environments in which testing was performed
- When the tests were last completed
This helps teams understand what has been validated and what should be verified within their own implementation.