From 89c93e544fd92c8a88c30bf12215f778ffcf30a9 Mon Sep 17 00:00:00 2001 From: Mike Gower Date: Mon, 7 Mar 2022 14:45:40 -0800 Subject: [PATCH 1/8] Update accessibility.mdx Add revised accessibility materials --- .../components/accordion/accessibility.mdx | 463 +++--------------- 1 file changed, 64 insertions(+), 399 deletions(-) diff --git a/src/pages/components/accordion/accessibility.mdx b/src/pages/components/accordion/accessibility.mdx index ad615de12f8..807377cef40 100755 --- a/src/pages/components/accordion/accessibility.mdx +++ b/src/pages/components/accordion/accessibility.mdx @@ -7,423 +7,88 @@ description: tabs: ['Usage', 'Style', 'Code', 'Accessibility'] --- -import { - StructuredListWrapper, - StructuredListHead, - StructuredListBody, - StructuredListRow, - StructuredListInput, - StructuredListCell, - OrderedList, - ListItem, -} from 'carbon-components-react'; + + +Design annotations are needed for specific instances shown below, but for the standard accordion component, Carbon already incorporates accessibility. + + - How it works - Accessibility considerations - Resources - Accessibility testing + What Carbon provides + Design annotations + Developer considerations -## How it works - -The accordion Carbon component provides a vertically stacked layout for web -content, commonly used to reduce scrolling. The accordion header is a button -that is used to expand and collapse each accordion panel. Buttons are used so -that the accordions are tab-able by keyboard users and accessible to screen -readers. `Tab` and `Shift-Tab` are used to navigate through each accordion -header and all focusable elements in the accordion should be included in the -page `Tab` sequence. `Enter` or `Space` expand and collapse each accordion -panel. - -When an accordion panel is collapsed the content is hidden, therefore the ARIA -state `aria-expanded="false"` advises users of assistive technologies that the -accordion panel is not visible. When the accordion header is expanded the ARIA -state changes to `aria-expanded="true"` and the accordion panel content is -displayed. Each accordion header contains an ARIA label, and the header buttons -have an ARIA-control property set that points to the unique id of the panel it -controls. When focus is on the accordion header there is a prominent style -change to the border as well as background of the accordion header. - -## Accessibility considerations - -This component has been validated to meet the -[WCAG 2.0 AA](https://www.w3.org/TR/WCAG20/) 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. Each accordion header must have a unique title (implemented via the label for - the button) that clearly describes the accordion panel content. This is - particularly helpful for users of assistive technologies so they have the - necessary information to efficiently navigate the content without having to - expand every section. -1. Carbon components should be used to create the content that displays within - each accordion panel. -1. Avoid keyboard traps when adding components to the accordion panel. For - example, the user expands an accordion, but is unable to tab to the next - focusable element. -1. Although the accordion component passes accessibility testing, content - authors need to ensure the content that is added to the accordion is - accessible. For example, if you add an image to the accordion header or panel - you need to include alternative text to pass accessibility testing. - -## Resources - -- [W3C WAI-ARIA Authoring Practices Accordion Design Pattern](https://www.w3.org/TR/wai-aria-practices/#accordion) - 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.1.2 No Keyboard Trap](https://www.ibm.com/able/requirements/requirements/#2_1_2) - (WCAG Success Criteria - [2.1.2](https://www.w3.org/WAI/WCAG21/Understanding/no-keyboard-trap)) - - [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)) - -## Accessibility testing - -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+accordion%22+). - -### Automated test +## What Carbon provides - - - - - - - Automated test environment - - Results - - - - - - - macOS Mojave version 10.14.2 with VoiceOver -
- - Chrome version 77.0.3865.90 -
- - Dynamic Assessment Plugin (DAP) version 1.8.0.0 - IBM - Accessibility WCAG 2.1 Sept. 2019 Ruleset -
- Carbon React version 7.7.1 - - - DAP test: -
- Violations - - - - - - +No annotations for keyboard interaction or labels are needed. Carbon bakes in the interaction to support users. -### macOS screen reader tests +### Keyboard interactions + +Each accordion is a tab stop. `Space` or `Enter` keys expand or collapse accordions, which are collapsed by default. Interactive elements within expanded accordions integrate into the tab order automatically. - - - - - Environment - Results - - - - - - - macOS Mojave version 10.14.6 with VoiceOver -
- - Chrome version 77.0.3865.90 -
- Carbon React version 7.7.1 - - - VoiceOver(VO) Test: - - - The Tab key and Shift-Tab navigate between accordion headers. VO - announces, expand/collapse, title, collapsed, button, the - button's state (expanded or collapsed), list, 1 item. You are - currently on a button... - - - Press Control-Option-Space (or Space) to expand or collapse the - accordion panel. VO announces expand/collapse title, the - button's state (expanded or collapsed). - - - With the second or third accordion header expanded, Press - Control-Option-Right Arrow. VO announces, the accordion panel - content and the line number in the list. - - - Press Control-Option-Left Arrow - VO announces reads the - accordion header again. - - - - - - - - macOS Mojave version 10.14.6 with VoiceOver -
- - Safari version 13.0.2 -
- Carbon React version 7.7.1 - - - VoiceOver(VO) test: - - - The Tab key and Shift-Tab navigate between accordion headers. VO - announces, expand/collapse, title, collapsed, button, the - button's state (expanded or collapsed), group. - - - Press Control-Option-Space (or Space) to expand or collapse the - accordion panel. VO announces expand/collapse title, the - button's state (expanded or collapsed). - - - With the second or third accordion header expanded, Press - Control-Option-Right Arrow. VO announces, the accordion panel - content and the line number in the list. Your are currently on a - text area. - - - Press Control-Option-Left Arrow - VO announces reads the - accordion header again. - - - - - - - + + +![example of accordion keyboard interaction](images/accordion-accessibility-1.png) + + -### Windows screen reader tests +Accordions are reached by `Tab` and activated by `Space` and `Enter` keys. + +### Labelling and states + +The collapsed or expanded state of the accordions is [programmatically set](https://www.ibm.com/able/requirements/requirements/#4_1_2) by default, eliminating the need for any [text equivalent](https://www.ibm.com/able/toolkit/design/content/text-equivalents/) for the chevron icons. - - - - - Environment - Results - - - - - - - Microsoft Windows 10 -
- - JAWS 19.1903.47 -
- - Firefox version 67 -
- Carbon React version 7.7.1 - - - JAWS test: - - - The Tab key and Shift-Tab navigate between accordion headers. - JAWS announces, title, and expand/collapse status. - - - Press the Enter or Space key on the title. JAWS announces expand - or collapsed. - - - Navigate the text using the Up and Down Arrow keys, when JAWS - read the headers and associated text if expanded in a linear - order. - - - Please note that sometimes it takes a second for the text to - update after a title is expanded. When pressing the down arrow - key immediately after JAWS announces "expanded", JAWS jumps past - the text and reads the next title. - - - - - - - - Microsoft Windows 10 -
- - JAWS 19.1903.47 -
- - Chrome version 71.0.3578.98 (Official Build) (64-bit) -
- Carbon React version 7.7.1 - - - JAWS test: - - - The Tab key and Shift-Tab navigate between accordion headers. - JAWS announces, title, and expand/collapse status. - - - Press the Enter or Space key on the title. JAWS announces expand - or collapsed. - - - Navigate the text using the Up and Down Arrow keys, when JAWS - read the headers and associated text if expanded in a linear - order. - - - Please note that sometimes it takes a second for the text to - update after a title is expanded. When pressing the down arrow - key immediately after JAWS announces "expanded", JAWS jumps past - the text and reads the next title. - - - - - - - - Microsoft Windows 10 -
- - NVDA version 2018.4.1 -
- - Chrome version 72.0.3626.96 (Official Build) (64-bit) -
- Carbon React version 7.7.1 - - - NVDA test: - - - The Tab key and Shift-Tab navigate between accordion headers. - NVDA announces, title, and expand/collapse status. - - - Press the Enter or Space key on the title. NVDA announces expand - or collapsed. - - - Navigate the text using the Up and Down Arrow keys, when JAWS - read the headers and associated text if expanded in a linear - order. - - - - - - - + + +![expanded and collapsed accordions](images/accordion-accessibility-2.png) + + -### iOS screen reader tests +Carbon handles the accessibility of the chevron indicators. + +## Design annotations + +Design annotations are needed for the following instances. + +### Headings + +Carbon accordions are not set as headings by default. For improved accessibility, annotate accordions as headings on the first occurrence in a product. Annotate the heading level of accordions as needed. See [Indicate heading levels](https://www.ibm.com/able/toolkit/design/content/text-meaning/#heading-levels). - - - - Environment - Results - - - - - - iOS version 13.1.3 with VoiceOver -
- - Safari version 13.1.3 -
- Carbon React version 7.7.1 - - - VoiceOver test: - - - To navigate the accordion, swipe left or right, or use the Left - or Right Arrow keys when quick nav mode is on. On each header, - VoiceOver announces the header, and expanded/collapsed status. - - - To expand or collapse the accordion, doubletap on the header, or - press Control+Option+Space. VoiceOver announces, expanded or - collapses. - - - In some cases, VoiceOver also reads out the entire header, it - seems to happen randomly, possibly have to do with the speed of - the phone. - - - Navigate the text by swiping left or right, or by pressing the - Left or Right Arrow keys when quick navigation mode is on. After - each title, when moving to the left or right, VoiceOver will - read the text if it is expanded. - - - - - - - + + +![H1 and H2 annotations for headings, plus direction to ‘include accordion titles as headings'](images/accordion-accessibility-3.png) + + -### Android screen reader tests +If accordion titles act as headings, annotate for development. + +### Alignment + +Carbon chevrons are right-aligned by default, but left-aligned chevrons are more accessible for users with low vision, as the expanded/collapsed indicator is closer to the accordion title. - - - - - Environment - Results - - - - - - - Android version 9 with Talkback -
- - Chrome version 72.0.3626.96 (Official Build) (64-bit) -
- Carbon React version 7.7.1 - - - Talkback test: - - - To navigate the accordion, swipe left or right, or use the - Alt+Left or Right Arrow keys. On each header, TalkBack announces - the header, and expanded/collapsed status. - - - To expand or collapse the accordion, doubletap on the header, or - press Alt+Enter. Talkback announces expanded or collapses. - - - Navigate the text by swiping left or right, or by pressing the - Left or Right Arrow keys. After each title, when moving to the - left or right, Talkback will read the text if it is expanded. - - - - - - - + + +![annotation stating ‘position chevrons on the left of accordion titles'](images/accordion-accessibility-4.png) + + + +Annotate if the accordion chevrons should be left-aligned. + +## Developer considerations + +Keep these considerations in mind if you’re modifying Carbon or creating a custom component: + +* The accordion header has a role of `