docs (notifications a11y): update to new template

src/pages/components/notification/accessibility.mdx

@@ -19,83 +19,119 @@ 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 `Space` or `Enter` keys. Additionally, the notification can
+optionally be closed by pressing the `Escape` key.
+
+#### Inline and toast
+
+Inline and toast notifications do not contain interactive elements. They use the
+roles of `status`, `alert`, or `log`, 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 `Space` or `Enter` keys. Additionally, the notification can
+be optionally closed by pressing the `Escape` key.
+
+<Row>
+<Column colLg={8}>
+
+![Focus trapped until an action is taken or the notification is dismissed.](images/notification-accessibility-actionable.png)
+
+<Caption>
+ Focus trapped until an action is taken or the notification is dismissed.
+</Caption>
+
+</Column>
+</Row>
+
+#### Callout
+
+A Callout is not automatically announced by screen readers. It can include
+interactive elements such as links, which users can navigate through using the
+`Tab` key. Additionally, actions to activate these links can be performed using
+the `Space` or `Enter` 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>
+
+## Design recommendations
+
+### Semantic styling
+
+When using semantic styling on notifications, it's crucial to ensure
+accessibility by providing clear, concise text. Colours used to indicate status
+should always be paired with icons to avoid reliance on colour alone.
+
+#### Text
+
+It is recommended that notification messages use plain text, as semantic styling
+such as bold or italic and structural elements like `<li>` are not conveyed to
+users by screen readers. If semantic styling must be included, it should not be
+essential for understanding the notification
+
+#### Icon and colours
+
+Ensure that screen readers can access the icon within the Callout to convey the
+type or semantic meaning of the message. The icon should have descriptive alt
+text that provides context about the Callout's type (e.g., information or
+warning). This helps users understand the nature and importance of the message.
+
+## Development considerations
+
+Use a role of `alert`, `log`, or `status` for notifications that do not require
+user action. For notifications that require user action, use a role of
+`alertdialog`.
+
+Special care should be given to focus management for notifications with
+interactive elements or actions. Venturing beyond using a role of `alert` `log`
+`status` or `alertdialog` for event-driven notifications is not recommended at
+this time as presents unique challenges. If you choose to do so, there are two
+known possible approaches to consider and research on your own.
+
+- 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 with either one: ensure notifications are
+properly announced, respect user timeout preferences, and ultimately provide an
+easy way to be navigated to by keyboard/screenreader to take action.
 
 <A11yStatus layout="table" components="Notification" />