docs (notifications a11y): update to new template (#4270)

* docs (notifications accessibility): update to new template

* docs (notifications accessibility): minor fix

* docs (notifications accessibility): images updated

* chore: yarn format

* docs (notifications accessibility): document updated

* chore: yarn format

---------

Co-authored-by: Alison Joseph <[email protected]>

src/pages/components/notification/accessibility.mdx

@@ -19,83 +19,101 @@ import {
   ListItem,
 } from '@carbon/react';
 
+<PageDescription>
+
+No accessibility annotations are needed for notifications, but keep these
+considerations in mind if you are modifying Carbon or creating a custom
+component.
+
+</PageDescription>
+
 <AnchorLinks>
-  <AnchorLink>How it works</AnchorLink>
-  <AnchorLink>Accessibility considerations</AnchorLink>
-  <AnchorLink>Resources</AnchorLink>
-  <AnchorLink>Accessibility testing</AnchorLink>
+  <AnchorLink>What Carbon provides</AnchorLink>
+  <AnchorLink>Design recommendations</AnchorLink>
+  <AnchorLink>Development considerations</AnchorLink>
 </AnchorLinks>
 
-## 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 user's 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 user's 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, close behavior, and semantic contents. 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. Generally, plain text is preferred to be used within
-these notifications. When read by screenreaders, any semantic meaning
-surrounding the contents is not reflected to the user. For instace - Bold or
-italic emphasis, and/or semantic elements such as `<li>` etc. are not read to
-the user. If semantics are included, it should be non-essential to the
-understanding or meaning of the contents.
-
-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.
-
-## Accessibility considerations
-
-1. Avoid using a toast notification for critical alerts or long messages because
-   they are timed and will disappear automatically making it difficult for
-   people with various disabilities to get the entire message. An alert that
-   disappears too quickly can lead to failure of the optional
-   [WCAG 2.0 success criterion 2.2.3 (AAA)](https://www.w3.org/TR/UNDERSTANDING-WCAG20/time-limits-no-exceptions.html).
-2. Provide a means to turn off nonessential alerts to enhance usability for
-   people with visual and cognitive disabilities. Additional information is
-   available in
-   [WCAG 2.0 success criterion 2.2.4 (AAA)](https://www.w3.org/TR/UNDERSTANDING-WCAG20/time-limits-postponed.html).
-   Note: Providing this functionality is optional.
-
-3. Ensure the use of color and hidden icons are not used as the only means of
-   conveying the importance of the notification.
-
-## Resources
-
-#### Helpful resources for creating customized accessible implementations
-
-- [W3C W3C WAI-ARIA Authoring Practices Alert Design Pattern](https://www.w3.org/TR/wai-aria-practices-1.1/#alert)
-  covers the usage of ARIA names, state and roles.
-- [W3C W3C Web Accessibility Tutorial - User Notifications](https://www.w3.org/WAI/tutorials/forms/notifications/)
-  provides a tutorial on notification accessibility.
-- [IBM Accessibility Requirements](https://www.ibm.com/able/requirements/requirements/):
-  - [3.3.1 Error Identification](https://www.ibm.com/able/requirements/requirements/#3_3_1)
-    (WCAG Success Criteria
-    [3.3.1](https://www.w3.org/TR/UNDERSTANDING-WCAG20/minimize-error-identified.html))
-  - [3.3.2 Labels and Instructions](https://www.ibm.com/able/requirements/requirements/#3_3_2)
-    (WCAG Success Criteria
-    [3.3.2](https://www.w3.org/TR/UNDERSTANDING-WCAG20/minimize-error-cues.html))
-  - [3.3.3 Error Suggestion](https://www.ibm.com/able/requirements/requirements/#3_3_3)
-    (WCAG Success Criteria
-    [3.3.3](https://www.w3.org/TR/UNDERSTANDING-WCAG20/minimize-error-suggestions.html))
-
-## Accessibility testing
+## What Carbon provides
+
+Carbon bakes keyboard operation into its components, improving the experience of
+blind users and others who operate via the keyboard. Carbon incorporates many
+other accessibility considerations, some of which are described below.
+
+### Keyboard interactions
+
+Users can navigate through the interactive elements within the notification
+using the `Tab` key. Actions such as closing or activating buttons can be
+performed using the `Enter` or `Space` keys. Additionally, some notifications
+can optionally be closed by pressing the `Escape` key.
+
+#### Inline and toast
+
+Inline and toast notifications do not contain interactive elements, and they do
+not receive focus.
+
+#### Actionable
+
+Actionable notifications may contain interactive elements such as links and
+buttons. This component grabs and traps focus until an action is taken or the
+notification is dismissed. Users can navigate through the interactive elements
+using the `Tab` key, and actions like closing or activating buttons can be
+performed using the `Enter` or `Space` keys. Additionally, the notification can
+be optionally closed by pressing the `Escape` key.
+
+<Row>
+<Column colLg={8}>
+
+![Retaining focus until an action is taken or the notification is dismissed.](images/notification-accessibility-actionable.png)
+
+<Caption>
+  Retaining focus until an action is taken or the notification is dismissed.
+</Caption>
+
+</Column>
+</Row>
+
+#### Callout
+
+A callout can include interactive elements such as links, which users can
+navigate through using the `Tab` key. Actions on these links can be performed
+using the `Enter` or `Space` keys.
+
+<Row>
+<Column colLg={8}>
+
+![Navigating through interactive elements using the Tab key.](images/notification-accessibility-callout.png)
+
+<Caption>Navigating through interactive elements using the Tab key.</Caption>
+
+</Column>
+</Row>
+
+## Development considerations
+
+Keep these considerations in mind if you are modifying Carbon or creating a
+custom component.
+
+- Use the roles `alert`, `log`, or `status` for notifications that do not
+  require user action.
+- Use the role `alertdialog` for notifications that require user action.
+- Callouts do not have an aria-live attribute, and are not automatically
+  announced by screen readers.
+
+Special care should be given to focus management for notifications with
+interactive elements or actions. It is not recommended to venture beyond using
+the roles `alert`, `log`, `status`, or `alertdialog` for event-driven
+notifications, as this can present unique challenges. If you choose to do so,
+there are two known approaches you may want to research further:
+
+- Collect notifications in a persistent area in your application for users to be
+  able to navigate to and take action on notifications.
+- Render notifications in an already-existing `region` that can be accessed via
+  a hotkey. Focus should jump to the notification region after the hotkey is
+  invoked. Once the user has reached the end of the region, focus should return
+  to the previously focused item in the document before the hotkey was invoked.
+
+Neither approach is perfect, but in either case, ensure that notifications are
+properly announced, respect user timeout preferences, and are easily navigable
+by keyboard or screen reader for users to take action.
 
 <A11yStatus layout="table" components="Notification" />