Alert - a11y documentation for announcing alerts (role="alert")

[humancompanion-usds]

Description

Update a11y documentation and guidance for Alert on design.va.gov. Brian on Governance recently "clarified" use of role="alert" on Alerts. This guidance needs to be added to the Alert component to make it clear to teams how and when Alerts should be announced. Slack thread. This thread needs to be boiled down into a decision tree that folks can follow to arrive at a sensible conclusion. If focus management should also be covered then let's also create a sub-section for that.

Details

The guidance should be reviewed by Brian so that he agrees to not contradict guidance during collab touchpoints.

Tasks

• Write component documentation for design.va.gov
• Request documentation review

Acceptance Criteria

• Component a11y documentation is update on design.va.gov

[caw310]

Please add your planning poker estimate with Zenhub @rsmithadhoc

[rsmithadhoc]

Hi @humancompanion-usds,

I put a draft below with the changes, but here's a quick summary of what was updated:

• Updated role="alert" with some more detail.
• Placed role="alertdialog" as a sub-bullet. The criteria for role="alert" applies to role="alertdialog" as well.
• I removed the bullet for role="region", while the information there is generally true, I don't think an alert should ever be made a region. Instead, I added a bullet directing them to Summary box, as that seems to fit better with crucial information before proceeding. Also, that component was recently updated to have a role="region", which it is better suited for.
• I think focus management should be left out from this because it is something that could be potentially disruptive and should be done sparingly, so I would not want to advise it as a generally applicable strategy, especially not for an alert.
• Updated the link at the bottom from ARIA specific roles to ARIA: alert role, as it has more specific and relevant information on this.

---

Assign an appropriate ARIA role

In some situations, an ARIA role may need to be added to the alert component for it to work best for people who use assistive technology. ARIA should be used sparingly to supplement and enhance the native features of HTML.

• Static alert: No Role. If the alert is a static alert that exists on the page when the page gets loaded, it doesn’t need a role.
• Important, time-sensitive information: Use role="alert" Use this role on alert components that appear after a user interaction.
  • This is for live updates page that would not get noticed otherwise. Updates to a page can occur without the user refreshing the page, so these may go unnoticed when using assistive technologies. role="alert" ensures assistive technology announces these updates and keeps the user informed.
  • Because this can be intrusive to the user experience, this should be used sparingly for information that requires the user's immediate attention.
  • Interactive alerts: Use role="alertdialog" instead. For alerts that fit the criteria of role="alert", but also contain content requiring user interaction, use role="alertdialog" instead of role="alert". For example, expecting the user to acknowledge the alert by closing it before proceeding.
• For must-read information that is present on page load, consider using a Summary box instead of an alert.

More on ARIA: alert role.