USWDS-Site - Site alert: Add aria-label information to accessibility docs #1774
Conversation
| - **Don’t visually hide alert messages and then make them visible when they are needed.** Users of older assistive technologies may still be able to perceive hidden alert messages. Fully remove alert messages when they’re not needed. | ||
| - **Include a descriptive ARIA label.** Add an `aria-label` or `aria-labelledby` attribute to the `.usa-site-alert` element to ensure that your site alert appears in the landmarks menu. A well-written label can help assistive technology users easily find and understand the top-level information of your site alert. | ||
| - **Add an ARIA role to dynamically-updated site alerts.** If your site alert will be dynamically updated during a session, add an ARIA `role` attribute to notify assistive technologies users of important and time-sensitive changes. To elevate importance, add the appropriate `role` to the `.usa-site-alert` element, chosen from the following table: |
There was a problem hiding this comment.
Suggesting: "To elevate importance, choose an appropriate 'role' to the '.usa-site-alert' element from the Aria Role Table [linked]"
The above:
-removes passive voice
-sends users directly to the table they need, regardless of page layout
There was a problem hiding this comment.
Updated in 39c6fe0
| - **Don’t visually hide alert messages and then make them visible when they are needed.** Users of older assistive technologies may still be able to perceive hidden alert messages. Fully remove alert messages when they’re not needed. | ||
| - **Include a descriptive ARIA label.** Add an `aria-label` or `aria-labelledby` attribute to the `.usa-site-alert` element to ensure that your site alert appears in the landmarks menu. A well-written label can help assistive technology users easily find and understand the top-level information of your site alert. | ||
| - **Add an ARIA role to dynamically-updated site alerts.** If your site alert will be dynamically updated during a session, add an ARIA `role` attribute to notify assistive technologies users of important and time-sensitive changes. To elevate importance, add the appropriate `role` to the `.usa-site-alert` element, chosen from the following table: |
There was a problem hiding this comment.
Suggesting: "... will be dynamically updated during a session, for example when a user does XYZ,"
to provide additional context for how this could be used.
There was a problem hiding this comment.
I reorganized the aria role section a bit for clarity to more accurately explain the use case. I also added an example as suggested. 39c6fe0
|
@bonnieAcameron Thanks for the helpful suggestions! I made some updates to the ARIA role section. Let me know if you have thoughts! |
Summary
Added instruction for using descriptive ARIA labels to ensure that assistive technology users can find and understand the site alert from the landmarks menu.
Additionally, added instruction for using ARIA roles to announce content changes to assistive technology users.
Related issue
Closes uswds/uswds#4589
Preview link
Preview link: Site alert accessibility section
Problem statement
Site alerts should be included in the page landmarks so that users of assistive technologies can more easily find site alert content on the page. However, if a user excludes the ARIA label, the site alert will not appear in the landmarks menu.
Additionally, some site alerts should be announced to assistive technologies users as new information is added to it. However, our docs do not explain ARIA roles for live regions.
Solution
Providing instruction about for using ARIA labels will increase the likelihood that users will include helpful labels on their site alerts.
Additionally, providing information about adding ARIA roles can help users understand how to announce changes to users of assistive technologies.
Note: It is unclear if instructions for the ARIA roles is appropriate here because the component specifically speaks to static items. This update was written on the assumption that injecting static content based on site needs (rather than user action) fit the construct of a static message. If this is inappropriate, we can safely remove.
From the site alert component page:
Testing and review
Copyeditors:
Developers: