Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Button accessibility #2775

Merged
merged 11 commits into from
Mar 16, 2022
Merged

Button accessibility #2775

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
ffcd641
Update accessibility.mdx
mbgower Mar 8, 2022
c7d56c0
Update accessibility.mdx
mbgower Mar 8, 2022
5de8344
added images
mbgower Mar 9, 2022
7d8c2f8
Update accessibility.mdx
mbgower Mar 9, 2022
079b5ef
Updated images
mbgower Mar 11, 2022
6a20ca0
Update accessibility.mdx
mbgower Mar 11, 2022
8ec241d
Update accessibility.mdx
mbgower Mar 11, 2022
41427fc
updated image; added caption
mbgower Mar 11, 2022
540f0e1
Update accessibility.mdx
mbgower Mar 11, 2022
14dafe7
Merge branch 'main' into button-accessibility
mbgower Mar 12, 2022
080a4b0
Merge branch 'main' into button-accessibility
mbgower Mar 16, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
350 changes: 59 additions & 291 deletions src/pages/components/button/accessibility.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,314 +6,82 @@ description:
tabs: ['Usage', 'Style', 'Code', 'Accessibility']
---

import {
StructuredListWrapper,
StructuredListHead,
StructuredListBody,
StructuredListRow,
StructuredListInput,
StructuredListCell,
OrderedList,
ListItem,
} from 'carbon-components-react';
<PageDescription>

Design annotations are needed for specific instances shown below, but for the standard button component, Carbon already incorporates accessibility.

</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

The `Button` component is used to trigger an action or event, such as submitting
a form, opening a modal, canceling an action, or performing an add or delete
operation. Almost all interactions in the Carbon Design System are implemented
using the native `<button>` element.

By default, interactive elements like `<button>` are included in the tab order
of the document. When a button has focus, both the `Space` and `Enter` keys will
activate the button. If the button is disabled, then the `disabled` attribute is
provided.

The label for a button can be computed by the contents of the underlying
`<button>`, or provided by the `aria-label` or `aria-labelledby` attributes.
Additional information about the button may be supplied by the
`aria-describedby` attribute.

## Accessibility considerations

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.

1. The button can be activated using both the `Space` or `Enter` key.
1. The button should have text or label that accurately describes the action of
the button.
1. If a description of the button's function is present, the button element
should have an `aria-describedby` set to the ID of the element containing the
description.
1. After the button is activated ensure the focus is set correctly based on the
type of action the button performs. See
[W3C WAI-ARIA Authoring Practices Button Design Pattern](https://www.w3.org/TR/wai-aria-practices-1.1/#button)
for a list of examples.

## Resources

- [W3C WAI-ARIA Authoring Practices Button Design Pattern](https://www.w3.org/TR/wai-aria-practices-1.1/#button)
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/)
- [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))
- [3.2.2 On Input](https://www.ibm.com/able/requirements/requirements/#3_2_2)
(WCAG Success Criteria
[3.2.2](https://www.w3.org/TR/2016/NOTE-UNDERSTANDING-WCAG20-20161007/consistent-behavior-unpredictable-change.html))

## Accessibility testing

Accessibility issues are tracked in the
[Carbon Design System 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+button%22+).

### Automated test
## What Carbon provides

<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>
</Row>
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

### macOS screen reader tests
Buttons can be reached by `Tab` and selected with `Space` or `Enter`.

<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 first button, VO announces, "The button label".
</ListItem>
<ListItem>
Clicking the Enter or Space key activates the button.
</ListItem>
</OrderedList>
</StructuredListCell>
</StructuredListRow>
<StructuredListRow>
<StructuredListCell>
- macOS Mojave version 10.14.6 with VoiceOver
<br />
- Safari version 13.0.2
<br />- Carbon React version 7.7.1
</StructuredListCell>
<StructuredListCell>
<strong>VoiceOver(VO) test:</strong>
<OrderedList>
<ListItem>
Tab to the first button, VO announces, "The button label".
</ListItem>
<ListItem>
Clicking the Enter or Space key activates the button.
</ListItem>
</OrderedList>
</StructuredListCell>
</StructuredListRow>
</StructuredListBody>
</StructuredListWrapper>
</Column>
<Column colLg={8}>

![example of button keyboard interaction](images/button-accessibility-1.png)

<Caption>Carbon buttons retain expected interactions.</Caption>

</Column>
</Row>

### Windows screen reader tests
### Behavior

Icon-only butttons, which do not persistently display a text label, expose their label on hover and focus. When icon-only buttons are used to open menus, they are treated as separate components in Carbon. See [Dropdown](https://carbondesignsystem.com/components/dropdown/usage/) and [Overflow menu](https://carbondesignsystem.com/components/overflow-menu/usage/).

<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 67
<br />
- JAWS 19.1810.64
<br />- Carbon React version 7.7.1
</StructuredListCell>
<StructuredListCell>
<strong>JAWS test:</strong>
<OrderedList>
<ListItem>
Tab to the first button, JAWS announces, "The button label".
</ListItem>
<ListItem>
Clicking the Enter or Space key activates the button.
</ListItem>
</OrderedList>
</StructuredListCell>
</StructuredListRow>
<StructuredListRow>
<StructuredListCell>
- Microsoft Windows 10
<br />
- Chrome Version 73.0.3683.68 (Official Build) (64-bit)
<br />
- JAWS Version 19.1810.64
<br />- Carbon React version 7.7.1
</StructuredListCell>
<StructuredListCell>
<strong>JAWS test:</strong>
<OrderedList>
<ListItem>
Tab to the first button, JAWS announces, "The button label".
</ListItem>
<ListItem>
Clicking the Enter or Space key activates the button.
</ListItem>
</OrderedList>
</StructuredListCell>
</StructuredListRow>
<StructuredListRow>
<StructuredListCell>
- Microsoft Windows 10
<br />
- Chrome Version 73.0.3683.68 (Official Build) (64-bit)
<br />
- NVDA Version 2018.4.1
<br />- Carbon React version 7.7.1
</StructuredListCell>
<StructuredListCell>
<strong>NVDA test:</strong>
<OrderedList>
<ListItem>
Tab to the first button, NVDA announces, "The button label".
</ListItem>
<ListItem>
Clicking the Enter or Space key activates the button.
</ListItem>
</OrderedList>
</StructuredListCell>
</StructuredListRow>
</StructuredListBody>
</StructuredListWrapper>
</Column>
</Row>
<Column colLg={8}>

![a pointer hovering over an icon-only button shows the name ‘Close’](images/button-accessibility-2.png)

<Caption>Icon-only buttons have their labels exposed automatically on hover and focus.</Caption>

### iOS screen reader tests
</Column>
</Row>

<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>
Tab to the first button, VO announces, "The button label".
</ListItem>
<ListItem>
Clicking the Enter or Space key activates the button.
</ListItem>
</OrderedList>
</StructuredListCell>
</StructuredListRow>
</StructuredListBody>
</StructuredListWrapper>
</Column>
<Column colLg={8}>

![an activated button reveals 3 options in a menu](images/button-accessibility-3.png)

<Caption>Buttons that open menus are separate components in Carbon.</Caption>
</Column>
</Row>

### Android screen reader tests
## Design recommendations

Design annotations are needed for the following instances.

### Labeling

When buttons do not have a persistently displayed label, they must be annotated with a label that will be exposed on hover or focus.

<Row>
<Column noGutterSm>
<StructuredListWrapper>
<StructuredListHead>
<StructuredListRow head>
<StructuredListCell head>Environment </StructuredListCell>
<StructuredListCell head>Results</StructuredListCell>
</StructuredListRow>
</StructuredListHead>
<StructuredListBody>
<StructuredListRow>
<StructuredListCell>
- Android version 9 with Talkback
<br />
- Chrome version 72.0.3683.68 (Official Build) (64-bit)
<br />- Carbon React version 7.7.1
</StructuredListCell>
<StructuredListCell>
<strong>Talkback test:</strong>
<OrderedList>
<ListItem>
Tab to the first button, Talkback announces, "The button label".
</ListItem>
<ListItem>
Clicking the Enter or Space key activates the button.
</ListItem>
</OrderedList>
</StructuredListCell>
</StructuredListRow>
</StructuredListBody>
</StructuredListWrapper>
</Column>
<Column colLg={8}>

![a button with a pencil icon has an annotation ‘label=Rename’](images/button-accessibility-4.png)

<Caption>Annotate the label for icon-only buttons so the proper tooltip appears.</Caption>

</Column>
</Row>

## Development considerations

Keep these considerations in mind if you are modifying Carbon or creating a custom component:

* Where links have been ‘repurposed’ as a button, they need to be coded so the `Space` key can also activate (since links are only activated by default by `Enter`).
* Toggle buttons can be accessibility supported by changing the value of `aria-pressed` between `"true"` and `"false"` or with a change of name that
reflects a change in the icon shape (for example: "play" / "pause" )
* See the [ARIA authoring practices](https://www.w3.org/TR/wai-aria-practices-1.2/#button) for more considerations.
Binary file added src/pages/components/button/images/button-accessibility-1.png
View file
Open in desktop
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/button/images/button-accessibility-2.png
View file
Open in desktop
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/button/images/button-accessibility-3.png
View file
Open in desktop
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/button/images/button-accessibility-4.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.