Skip to content

Commit

Permalink
accessibility content for overflow menu (#3083)
Browse files Browse the repository at this point in the history 
* accessibility content for overflow menu

text and images for accessibility guidance

* fix: run format

Co-authored-by: Josefina Mancilla <32556167+jnm2377@users.noreply.github.com>
Co-authored-by: Josefina Mancilla <josefinanoemi4@gmail.com>
Co-authored-by: kodiakhq[bot] <49736102+kodiakhq[bot]@users.noreply.github.com>
  • Loading branch information
@mbgower @jnm2377 @kodiakhq
4 people committed Aug 23, 2022
1 parent 59d6c3a commit 5f71fd2
Show file tree
Hide file tree
Showing 3 changed files with 46 additions and 225 deletions.
271 changes: 46 additions & 225 deletions src/pages/components/overflow-menu/accessibility.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,249 +17,70 @@ import {
ListItem,
} from '@carbon/react';

<AnchorLinks>
<AnchorLink>How it works</AnchorLink>
<AnchorLink>Accessibility considerations</AnchorLink>
<AnchorLink>Resources</AnchorLink>
<AnchorLink>Accessibility testing</AnchorLink>
</AnchorLinks>
<PageDescription>

## How it works
No accessibility annotations are needed for overflow menus, but keep these
considerations in mind if you are modifying Carbon or creating a custom
component.

The Carbon overflow menu component is used when there is limited space to
provide a pop-up list of actions that are available to the user. The overflow
menu button uses `tabindex="0"` to ensure it is in the tab order for keyboard
only users.
</PageDescription>

When the button has focus, Space key as well as the Enter key activates the
pop-up menu. WAI-ARIA roles and states are used to ensure the component is
accessible to people using assistive technologies. The pop-up menu has the ARIA
role of `role="menu"`, a label of `aria-label="Menu"` and includes
`aria-haspopup="true"` to let the user know it is a pop-up menu.

When the menu button is collapsed the pop-up menu is hidden so the ARIA state is
set to `aria-expanded="false"` to advise users of assistive technologies that
the pop-up menu is not visible. When the pop-up menu is expanded the ARIA state
changes to `aria-expanded="true"` and the menu is displayed.
<AnchorLinks>

Each menu option contains an ARIA role of `role="menuitem"` and unique ARIA
labels for each option. When focus is on each option there is a prominent style
change to the border to ensure the focus is clearly displayed.
<AnchorLink>What Carbon provides</AnchorLink>
<AnchorLink>Development considerations</AnchorLink>

## Accessibility considerations
</AnchorLinks>

This component has been validated to meet the
[WCAG 2.1 AA](https://www.w3.org/TR/WCAG21/) and
[Section 508](http://www.section508.gov/) accessibility guidelines, however
changes made by the content owner can affect accessibility compliance. Be sure
to review and follow the guidance in this section when updating or adding new
content to this component.
## What Carbon provides

1. Labels should be clear and concise.
1. If a colored button is used in the menu, be sure color is not the only way
the information is conveyed.
1. If a menu item is disabled it should not be in the tab order.
Carbon bakes keyboard operation into its components, improving the experience of
blind users and others who operate via keyboard. Carbon also incorporates other
accessibility considerations, some of which are described below.

## Resources
### Keyboard interaction

- [W3C WAI-ARIA Authoring Practices Dialog Menu Button Design Pattern](https://www.w3.org/TR/wai-aria-practices-1.1/#menubutton)
covers the usage of ARIA names, state and roles, as well as the expected
keyboard interactions.
- [IBM Accessibility Requirements:](https://www.ibm.com/able/requirements/requirements/)
- [1.3.1 Info and Relationships](https://www.ibm.com/able/requirements/requirements/#1_3_1)
(WCAG Success Criteria
[1.3.1](https://www.w3.org/WAI/WCAG21/Understanding/info-and-relationships))
- [1.3.2 Meaningful Sequence](https://www.ibm.com/able/requirements/requirements/#1_3_2)
(WCAG Success Criteria
[1.3.2](https://www.w3.org/WAI/WCAG21/Understanding/meaningful-sequence))
- [2.1.1 Keyboard](https://www.ibm.com/able/requirements/requirements/#2_1_1)
(WCAG Success Criteria
[2.1.1](https://www.w3.org/WAI/WCAG21/Understanding/keyboard))
- [2.4.3 Focus Order](https://www.ibm.com/able/requirements/requirements/#2_4_3)
(WCAG Success Criteria
[2.4.3](https://www.w3.org/WAI/WCAG21/Understanding/focus-order))
- [2.4.6 Headings and Labels](https://www.ibm.com/able/requirements/requirements/#2_4_6)
(WCAG Success Criteria
[2.4.6](https://www.w3.org/WAI/WCAG21/Understanding/headings-and-labels))
- [2.4.7 Focus Visible](https://www.ibm.com/able/requirements/requirements/#2_4_7)
(WCAG Success Criteria
[2.4.7](https://www.w3.org/WAI/WCAG21/Understanding/focus-visible))
- [4.1.2 Name, Role, Value](https://www.ibm.com/able/requirements/requirements/#4_1_2)
(WCAG Success Criteria
[4.1.2](https://www.w3.org/TR/UNDERSTANDING-WCAG20/ensure-compat-rsv.html))
Each overflow menu is in the tab order and is activated by `Space` or `Enter`.
When the menu is open, the first item takes focus. Focus is moved between menu
items with the `Up` and `Down` arrow keys. `Space` or `Enter` activates the item
with focus (which causes focus to go somewhere else and the menu to close).
`Esc` collapses the menu and puts focus onto the menu button.

## Accessibility testing
<Row>
<Column colLg={8}>

Accessibility issues are tracked in the
[Carbon Component GitHub repository](https://github.com/carbon-design-system/carbon/issues?q=is%3Aopen+label%3A%22type%3A+a11y+%E2%99%BF%22+label%3A%22component%3A+overflow-menu%22+).
![example of overflow menu keyboard interaction](images/overflow-menu-accessibility-1.png)

### Automated test
<Caption>
Overflow menus are reached by Tab. Space and Enter keys open the menu as well
as activating menu items with focus.
</Caption>

<Row>
<Column noGutterSm>
<StructuredListWrapper>
<StructuredListHead>
<StructuredListRow head>
<StructuredListCell head>
Automated test environment
</StructuredListCell>
<StructuredListCell head>Results</StructuredListCell>
</StructuredListRow>
</StructuredListHead>
<StructuredListBody>
<StructuredListRow>
<StructuredListCell>
- macOS Mojave version 10.14.6 with VoiceOver
<br />
- Chrome version 77.0.3865.90
<br />
- Dynamic Assessment Plugin (DAP) version 1.8.0.0 - IBM
Accessibility WCAG 2.1 Sept. 2019 Ruleset
<br />- Carbon React version 7.7.1
</StructuredListCell>
<StructuredListCell>
<strong>DAP test:</strong>
<br />- No violations
</StructuredListCell>
</StructuredListRow>
</StructuredListBody>
</StructuredListWrapper>
</Column>
</Column>
</Row>

### macOS screen reader tests

<Row>
<Column noGutterSm>
<StructuredListWrapper>
<StructuredListHead>
<StructuredListRow head>
<StructuredListCell head>Environment </StructuredListCell>
<StructuredListCell head>Results</StructuredListCell>
</StructuredListRow>
</StructuredListHead>
<StructuredListBody>
<StructuredListRow>
<StructuredListCell>
- macOS Mojave version 10.14.6 with VoiceOver
<br />
- Chrome version 77.0.3865.90
<br />- Carbon React version 7.7.1
</StructuredListCell>
<StructuredListCell>
<strong>VoiceOver(VO) test:</strong>
<OrderedList>
<ListItem>
Tab to the Overflow Menu. VO announces the menu label and pop-up
button.
</ListItem>
<ListItem>
The Enter or Space key opens the menu. VO announces the menu
item label the number and the total number of options.
</ListItem>
<ListItem>
The Up and Down Arrow keys navigate through the list of options
and VO announces each menu item label.
</ListItem>
<ListItem>
The Escape key closes the menu. (Note: Space and Enter key also
close the menu.)
</ListItem>
</OrderedList>
</StructuredListCell>
</StructuredListRow>
</StructuredListBody>
</StructuredListWrapper>
</Column>
</Row>
<Column colLg={8}>

### Windows screen reader tests
![illustration showing an open menu with the focus on the first item, and the arrow and Esc keys called out](images/overflow-menu-accessibility-2.png)

<Row>
<Column noGutterSm>
<StructuredListWrapper>
<StructuredListHead>
<StructuredListRow head>
<StructuredListCell head>Environment</StructuredListCell>
<StructuredListCell head>Results</StructuredListCell>
</StructuredListRow>
</StructuredListHead>
<StructuredListBody>
<StructuredListRow>
<StructuredListCell>
- Microsoft Windows 10
<br />
- Firefox version 68
<br />
- JAWS 18
<br />- Carbon React version 7.7.1
</StructuredListCell>
<StructuredListCell>
<strong>JAWS test:</strong>
<OrderedList>
<ListItem>
Tab to the Overflow Menu. JAWS announces the menu label and
pop-up button, as well as press Space to expand.
</ListItem>
<ListItem>
The Space key opens the menu briefly and then it disappears. The
Enter key opens the menu and JAWS announces the menu item label
</ListItem>
<ListItem>
The Up and Down Arrow keys navigate through the list of options
and JAWS announces each menu item label.
</ListItem>
<ListItem>
The Escape key closes the menu. (Note: Space and Enter key also
close the menu.)
</ListItem>
</OrderedList>
</StructuredListCell>
</StructuredListRow>
</StructuredListBody>
</StructuredListWrapper>
</Column>
<Caption>
When opened, the first item in the menu takes focus. Arrow keys move focus,
Esc closes the menu.
</Caption>

</Column>
</Row>

### iOS screen reader tests
## Development considerations

<Row>
<Column noGutterSm>
<StructuredListWrapper>
<StructuredListRow head>
<StructuredListCell head>Environment </StructuredListCell>
<StructuredListCell head>Results</StructuredListCell>
</StructuredListRow>
<StructuredListBody>
<StructuredListRow>
<StructuredListCell>
- iOS version 13.1.3 with VoiceOver
<br />
- Safari version 13.1.3
<br />- Carbon React version 7.7.1
</StructuredListCell>
<StructuredListCell>
<strong>VoiceOver test:</strong>
<OrderedList>
<ListItem>
Swipe right to the Overflow Menu. VO announces the main
landmark, menu label, and that the pop-up button is collapsed.
</ListItem>
<ListItem>
Double tap to open the menu. VO announces the menu item label.
</ListItem>
<ListItem>
Swipe right or left to navigate through the list of options and
VO announces each menu item label.
</ListItem>
<ListItem>
Double tap closes the menu. (Note: Space and Enter key also
close the menu.)
</ListItem>
</OrderedList>
</StructuredListCell>
</StructuredListRow>
</StructuredListBody>
</StructuredListWrapper>
</Column>
</Row>
Keep these considerations in mind if you are modifying Carbon or creating a
custom component.

- Overflow menus are buttons with `aria-haspopup` set to "true".
- The overflow menu is named with `aria-label`.
- Each menu item is an `li` in a `ul`.
- Each list item contains a button with `role="menuitem"` and `tabindex="-1"`.
See the
[ARIA authoring practices on menubutton](https://w3c.github.io/aria-practices/#menubutton)
for more considerations.
Binary file added src/pages/components/overflow-menu/images/overflow-menu-accessibility-1.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added src/pages/components/overflow-menu/images/overflow-menu-accessibility-2.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.

1 comment on commit 5f71fd2

@vercel
Copy link

@vercel vercel bot commented on 5f71fd2 Aug 23, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Successfully deployed to the following URLs:

carbondesignsystem – ./

carbondesignsystem.vercel.app
carbondesignsystem-git-main-carbon-design-system.vercel.app
carbondesignsystem-carbon-design-system.vercel.app

Please sign in to comment.