While our components are designed and developed with accessibility as a core requirement, they can still be implemented in a way that results in an application that doesn’t conform to WCAG Guidelines.
To that end, HashiCorp product teams should consider the following best practices to ensure they’re implementing accessible products.
Page organization
All content should be contained in elements with landmark roles. Typically this includes the header, main, and footer elements, but depending on your page layout, you might also be using aside and nav as direct descendants of the body element.
Titles and labels
Page titles
Ensure that each page has a relevant page title. This is included in Ember applications by default, but older applications that have been updated over the years may need to manually add this in with ember-page-title.
Headings
Headings (h1–h6) should follow a logical order and shouldn’t skip any levels. Dynamic applications can make this challenging, so this may require extra attention in checking what renders to the browser.
Input labels
All inputs should have associated labels. These are built-in to the form components by default. If you need to compose custom fields using the base elements, remember that a placeholder attribute is not an acceptable substitute for a label.
Accessible name
Not every element is allowed to use aria-label. Check the element’s role documentation to see what aria-attributes are permissible. As the saying goes, "no ARIA is better than bad ARIA," so when in doubt, ask in #team-design-system.
Focus management
There are some key points to remember about focus management:
- Focus should return from whence it came. For example, if a button opens a modal window, closing that modal window should return focus to the button.
- Trap the focus! Focus should remain in a modal or other popup when it is open. Try ember-focus-trap.
- Focus order should match DOM order.
Accessible routing
Adding support for accessible routing ensures that route transitions are appropriately announced to users with assistive technology. We recommend ember-a11y-refocus, an addon that provides three things:
- It adds a message to the page to let the screen reader user know that the route has changed and regular page navigation can resume (it’s similar to a11y-announcer but doesn’t use
aria-live). - It moves the focus to that message for the screen reader user, effectively resetting focus in Ember apps (similar to how a native web page works).
- It provides an optional bypass mechanism so the user can skip to the page’s primary content (see Technique G1). See the
Optionssection in the documentation for available options.
Automated testing
Use available automated tooling for static and dynamic analysis. Ember apps can use ember-template-lint for static analysis and ember-a11y-testing for dynamic analysis. Additionally, consider adding HTML validation to your CI.
Manual testing
Keyboard support
Ensure your application is keyboard navigable. Everything you can do with a mouse should have an equivalent experience with a keyboard.
Browser extensions
We recommend using Microsoft’s Accessibility Insights and Deque’s aXe browser extensions to check for accessibility issues directly in the browser.
Safari and VoiceOver
Your development environment has a screen reader built in. Become familiar with VoiceOver and use it to test your application within Safari, especially if you’re implementing an uncommon UI and want to make sure it’s inclusive for our users.
Accessibility support
There are many ways to learn about implementing accessible applications within HashiCorp.
Internal training
Training is available for HashiCorp employees within the Accessibility library in Workramp.
Accessibility Guild
The Accessibility Guild is a space where HashiCorp employees of all roles can join and learn more about accessibility. We offer multiple meeting days/times to accommodate our globally-distributed workforce and record meetings for those who can’t attend.
Have a question? We’re here to help! Ask in our internal Slack channel #talk-a11y.