Update toast notification docs

[kingtraceyj]

Summary

Notification component and pattern documentation should reflect the new toast notification updates

Updates needed

Component docs

• Actions
• Dismissal
• Accessibility tab

Pattern docs

• Description
• Best practices

[kingtraceyj]

Current accessibility content:

How it works

Notification Carbon components are messages that communicate information to a user. The WAI-ARIA role="alert" is equivalent to aria-live="assertive". It is used to display a message to the user in a way that attracts the user’s attention without receiving focus to communicate the message without interrupting the users current task. If the notification does not contain an urgent message, consider changing it to aria-live="polite" so the notification is queued until whatever task the user is currently working on is complete.

The close button contains an ARIA label of aria-label="close", and the icon has aria-hidden="true" so it is ignored by assistive technologies. TheTabkey is used to move focus to the close button within the notification and the Space key or Enter key activate the button to close the notification.

[tay1orjones]

Keeping carbon-design-system/carbon#8703 in mind, here's a tentative rough draft of how I think we might want to amend the accessibility content:

How it works

Notification Carbon components are messages that communicate information to a user. The WAI-ARIA role="status" and role="log" are equivalent to aria-live="polite". It is used to display a message to the user in a way that does not interrupt the users current task and queues the notification until whatever task the user is currently working on is complete. If the notification contains an urgent message, a role="alert" can be used, it is equivalent to aria-live="assertive". It is used to display a message to the user that interrupts the users current task. These are considerably more disruptive to users than the role="status" or role="log". In either case, these notifications attract the user’s attention without receiving focus to communicate the message.

Details pertaining to these roles include specifics around containing interactive elements, focus behavior, and close behavior. The role of status, log, and alert can not contain interactive elements, should not be given focus, and can optionally be closed by pressing the Escape key. The close button is given aria-hidden="true" so it is ignored by assistive technologies.

Notification components are allowed interactive children (actions) though, and when an interactive element is provided, a role="alertdialog" is used. These notifications should immediately be given focus so the user can navigate through the interactive elements. The close button is given an ARIA label of aria-label="close", and the icon has aria-hidden="true" so it is ignored by assistive technologies. The Tab key is used to move focus to the action and close button within the notification and the Space key or Enter key activate the appropriate button within the notification. It can also be optionally closed via pressing the Escape key.

@dakahn @mbgower please double check me here and let me know if I'm mistaken or should clarify anything

[dakahn]

@tay1orjones love this! Would be great to somehow include this in a more dev visible place like our Storybook as well. Can this go into usage docs for v11 toasts?

[tay1orjones]

@dakahn We have a link to this accessibility page in the notification.mdx. Do you think that's enough? I'm not opposed to adding a new section on the storybook docs but do wonder if one or the other will fall out of date having it in two places.