USWDS-Site - Alert: Update ARIA role guidance

[amyleadem]

Summary

Updated accessibility documentation for the alert component to give clearer instructions for adding the appropriate ARIA role.

Related issue

Closes uswds/uswds#3832

Preview link

Preview link: Alert component page

Problem statement

It is important that users are informed of the attributes the alert component needs to make it accessible. However, our current documentation provides information on only some of the available roles and does not give a clear indication of exactly how and where these attributes should be used.

Solution

ARIA provides several role attributes that can be added to the alert component to make content more readily available to users of assistive technologies. Each role generates a different behavior and should be chosen based on the urgency and importance of the message.

• The alert role is a live region with implicit values of aria-live="assertive" and aria-atomic="true" W3C Alert role
• The status role is a live region with implicit values of aria-live="polite" and aria-atomic="true" status role
• The region role is a landmark and does not have implicit aria-live or aria-atomic values. However, it does make the component appear in the landmarks menu, which can make finding that content easier. This role does require the addition of aria-labelledby or aria-label. Region role

The proposed solution in this PR creates a table that shows a list of available ARIA roles, use cases for each, and examples chosen from our component variants.

Note: I added the region role because it gives the option to add the alert as a page landmark so that users can more easily find it via rotor, etc. It is debatable to me if our alerts should be included as landmarks — the site alert component is a clearer candidate for a landmark role — but I included the information here because it might be useful in certain cases. If we decide the alert should be a landmark by default, we can change the wrapping div in this component to a section, which is automatically added to the landmarks menu.

Note: I removed recommendations for alertdialog because the specs indicate that using this role should also involve adding a behavior that moves and traps user focus on the alertdialog element. Because this did not fit the pattern of the existing alert component, I removed it from the list of recommended roles.

Content authors SHOULD make alert dialogs modal by ensuring that, while the alertdialog is shown, keyboard and mouse interactions only operate within the dialog. (W3C Alertdialog)

Possible next steps:

If we move forward with these examples and recommendations, we should consider adding these roles to the component code. It also might be worth considering converting the outer <div> to be a <section> instead so that it is automatically included in page landmarks and role="region" would no longer be needed.

Testing and review

• Proofread the copy for errors and clarity
• Confirm that the provided roles are the ones we want to recommend
• Confirm at all the information a user needs for quick reference is made available

---

Before opening this PR, make sure you’ve done whichever of these applies to you:

• Run git pull origin [base branch] to pull in the most recent updates from your base and check for merge conflicts. (Often, the base branch is develop).
• Run npm test and confirm that all tests pass.

[bonnieAcameron]

Checked for: clarity, typos, links

[thisisdano]

Excellent summary and documentation