Menu accessibility tab doc update (#4250)

* update_1 * update_2 * Update src/pages/components/menu/accessibility.mdx * Update src/pages/components/menu/accessibility.mdx Co-authored-by: Lauren Rice <[email protected]> * Update src/pages/components/menu/accessibility.mdx Co-authored-by: Lauren Rice <[email protected]> * Update src/pages/components/menu/accessibility.mdx Co-authored-by: Lauren Rice <[email protected]> * Update src/pages/components/menu/accessibility.mdx Co-authored-by: Lauren Rice <[email protected]> * Update src/pages/components/menu/accessibility.mdx Co-authored-by: Lauren Rice <[email protected]> * Update src/pages/components/menu/accessibility.mdx Co-authored-by: Lauren Rice <[email protected]> * Update src/pages/components/menu/accessibility.mdx Co-authored-by: Lauren Rice <[email protected]> * update_2 * update_3 * update_4 * chore: yarn format * update_5 * update 6 * update_7 --------- Co-authored-by: Alina Jacob <[email protected]> Co-authored-by: Ariella Gilmore <[email protected]> Co-authored-by: Lauren Rice <[email protected]> Co-authored-by: Alison Joseph <[email protected]>
carbon-design-system · Sep 23, 2024 · 2d19fac · 2d19fac
1 parent 3a033ba
commit 2d19fac
Show file tree

Hide file tree

Showing 7 changed files with 81 additions and 5 deletions.
diff --git a/src/pages/components/menu-buttons/accessibility.mdx b/src/pages/components/menu-buttons/accessibility.mdx
@@ -27,7 +27,7 @@ incorporates accessibility.
 ## What Carbon provides
 
 Carbon bakes keyboard operation into its components, improving the experience of
-blind users and others who operate via keyboard. Carbon also incorporates other
+blind users and others who operate via keyboard. Carbon incorporates other
 accessibility considerations, some of which are described below.
 
 ### Keyboard interaction

diff --git a/src/pages/components/menu/accessibility.mdx b/src/pages/components/menu/accessibility.mdx
@@ -6,10 +6,85 @@ tabs: ['Usage', 'Style', 'Code', 'Accessibility']
 
 import A11yStatus from 'components/A11yStatus';
 
-<InlineNotification>
+<PageDescription>
 
-**Coming soon!** This page is a work in progress.
+No accessibility annotations are needed for menus, but keep these considerations
+in mind if you are modifying Carbon or creating a custom component.
 
-</InlineNotification>
+</PageDescription>
+
+<AnchorLinks>
+
+<AnchorLink>What Carbon provides</AnchorLink>
+<AnchorLink>Development considerations</AnchorLink>
+
+</AnchorLinks>
+
+## What Carbon provides
+
+Carbon bakes keyboard operation into its components, improving the experience of
+blind users and others who operate via keyboard. Carbon incorporates many other
+accessibility considerations, some of which are described below.
+
+### Keyboard interaction
+
+The menu is reached by `Tab`. When the menu is open, the first item takes focus.
+Use the `Up` and `Down` arrow keys to navigate between menu items.
+
+<Row>
+
+<Column colLg={8}>
+
+![example of menu keyboard interaction](images/accessibility-menu-1.png)
+
+<Caption>
+  Menu is reached by Tab and when opened, the first menu item takes focus. Arrow
+  keys move focus.
+</Caption>
+
+</Column>
+</Row>
+
+Pressing `Space` or `Enter` on a focused menu item activates it and collapses
+the menu. Pressing `Space` or `Enter` on a submenu opens it. A submenu can also
+be opened and closed using the right and left arrow keys respectively. When the
+menu or submenu is open, the first item takes focus. An activated menu item can
+have different results depending on its functionality. If the item is a link, it
+launches the selection. If the item is selectable, it selects or deselects the
+item. The menu item retains its selected or unselected state when the menu is
+opened again.
+
+<Row>
+<Column colLg={12}>
+
+![example of menu keyboard interaction](images/accessibility-menu-2.png)
+
+<Caption>
+  Space and Enter keys activates, selects, or deselects the menu item with
+  focus. A submenu is opened and closed with the right and left arrow keys
+  respectively.
+</Caption>
+
+</Column>
+</Row>
+
+## Development considerations
+
+Keep these considerations in mind if you are modifying Carbon or creating a
+custom component.
+
+- Each menu, including nested menus, are `ul` elements with `role="menu"`.
+- Menu items are `li` elements with `role="menuitem"`.
+- If a Menu item contains a sub-menu, it is given `aria-haspopup="true"` and
+  `aria-expanded` of true or false depending on if the sub-menu is open/visible.
+- Selectable menu items are given `role="menuitemcheckbox"`.
+- Menu item groups are `li` elements with `role="group"`.
+- Menu item radio groups get `role="menuitemradio"`.
+- Menu items with really long labels can get truncated depending on the screen
+  size. This label will be exposed by a browser rendered tooltip on hover or
+  focus.
+- Menu implements the
+  [menu design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/menubar/)
+  defined in the ARIA Authoring Practices Guide (APG).
 
 <A11yStatus layout="table" components="Menu" />
diff --git a/src/pages/components/menu/images/accessibility-menu-1.png b/src/pages/components/menu/images/accessibility-menu-1.png
diff --git a/src/pages/components/menu/images/accessibility-menu-2.png b/src/pages/components/menu/images/accessibility-menu-2.png
diff --git a/src/pages/components/menu/images/usage-menu-RTL.png b/src/pages/components/menu/images/usage-menu-RTL.png
diff --git a/src/pages/components/menu/images/usage-menu-overflow-truncate.png b/src/pages/components/menu/images/usage-menu-overflow-truncate.png
diff --git a/src/pages/components/menu/usage.mdx b/src/pages/components/menu/usage.mdx
@@ -328,7 +328,8 @@ including the direction of the caret and keyboard shortcuts.
 #### Overflow
 
 Consider using short and precise labels for menu items. However, when deciding
-to truncate long menu items, use a tooltip on hover to reveal the full text.
+to truncate long menu items, a browser rendered title tooltip will reveal the
+full text on hover.
 
 <Row>
 <Column colLg={8}>