Update tabs accessibility.mdx

src/pages/components/tabs/accessibility.mdx

@@ -18,79 +18,131 @@ import {
 
 <PageDescription>
 
-The tabs React Carbon component has been tested against the latest
-[W3C Web Content Accessibility Guidelines (WCAG) 2.1 Level A and AA success criteria](https://www.w3.org/TR/WCAG21/).
+Design annotations are needed for specific instances shown below, but for the
+standard tabs component, also called a tablist, Carbon already incorporates
+accessibility.
 
 </PageDescription>
 
 <AnchorLinks>
-  <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>
 
-## Accessibility considerations
+## What Carbon provides
 
-1. Each tab must have a unique title that clearly describes tab panel content.
-   This is particularly helpful for users of assistive technologies so they have
-   the necessary information to efficiently navigate the content.
-2. Carbon components should be used to create the content that displays within
-   each tab panel.
-3. Content authors need to ensure the content that is added to the tab panel is
-   accessible. For example, if you add an image to the panel you need to include
-   alternative text to pass accessibility testing.
+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.
 
-## Resources
+### Keyboard interactions
 
-- [W3C WAI-ARIA Tab Design Pattern](https://www.w3.org/TR/wai-aria-practices-1.1/#tabpanel)
-  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))
+Tabs take at least two tabstops, one for the tablist and one for the tabpanel.
+When tabbing away from the tablist, focus will either go to the first operable
+element in the tabpanel or, where there are no operable elements, the entire
+tabpanel will take focus to support scrolling of its content.
 
-## Accessibility testing
+<DoDontRow>
+  <DoDont type="do" caption="The tablist takes a single tabstop with focus then moving to the first item in the tabpanel.">
 
-Automated, manual and screen reader accessibility verification test has been
-performed on the structure list React Carbon Component.
-[WCAG 2.1 Level A and AA success criteria](https://www.w3.org/TR/WCAG21/) issues
-have been identified and the list of open accessibility violations is available
-in the Carbon Component GitHub repository.
+![A user reaches the tablist with the Tab key. Pressing the Tab key again moves focus to a link inside the tabpanel's content](images/tab-accessibility-1a.png)
 
-### Automated test
+  </DoDont>
+  <DoDont type="do" caption="Where a tabpanel has no interactive items, the focus moves from the tablist to the entire tabpanel.">
+
+![A user tabs through a tablist. The focus goes from the tablist to the whole tabpanel, which contains only text.](images/tab-accessibility-1b.png)
+
+  </DoDont>
+</DoDontRow>
+
+Arrow keys are used to navigate between individual tab items in the tablist.
+When the end of the tablist is reached, the focus wraps to the opposite end of
+the list. For scrollable tablists, where the number of tabs exceeds the
+horizontal space, the keyboard navigation does not change. The user presses the
+`Left` or `Right` arrow key, which moves the focus to the next tab item and,
+where necessary, scrolls the tablist to keep the selected item visible. For mouse
+users, clickable arrows appear at the end of the tablist to provide the same
+scrolling, but these are not needed for keyboard users and they are not in the
+focus order.
+
+<Row>
+
+<Column colLg={8}>
+
+![An image pair showing two views of the same tablist of 6 items. The user navigates between tab with left and right arrow keys. If the user presses the left arrow on the first item, the focus wraps around to item 6. Likewise arrowing right from tab item 6 moves to the first tab](images/tab-accessibility-4.png)
+
+<Caption>
+  Arrow keys move between tabs in the tablist (wrapping from last
+  back to first) and scroll automatically to keep the focused
+  tab visible.
+</Caption>
+
+</Column>
+</Row>
+
+Automatic and manual tablists differ in how the tab items are activated. The
+following illustration shows what will happen for each variant when a right
+arrow key is pressed with the Overview tab selected and focused.
+
+For automatic tablists, focus and selection are synchronized. When the user
+arrows to a tab, it is selected, and the tabpanel under the tab is updated in
+real time.
+
+Manual tablists allow the user to arrow between the tab items without updating
+the tabpanel underneath. When the user right arrows, the Overview tab remains
+selected while focus moves to the Details tab. In order to select the Details
+tab (and update the tabpanel under the tab) the user would press `Enter` or
+`Space`.
+
+<Row>
+<Column colLg={8}>
+
+![Automatic and manual versions of a tablist with tabs called Overview, Details, and Support. In the first, the Details tab is selected and focused. In the second the Overview tab is still selected and the Details tab has a focus indicator](images/tab-accessibility-2.png)
+
+<Caption>
+  After pressing the `Right Arrow` key, the second tab is selected in an
+  automatic tablist. For the manual tablist, Details has focus but Overview is
+  still selected. Pressing the Space or Enter key will select Details.
+</Caption>
+
+</Column>
+</Row>
+
+## Design recommendations
+
+### Indicate which variant to implement
+
+The automatic and manual tablists are visually indistinguishable in a wireframe,
+so designers should annotate which variant the team has decided to implement.
+Since the choice largely concerns technical considerations about potential
+latency when updating the tabpanel’s information, architects or developers
+should be involved in the discussion.
 
 <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 colLg={8}>
+
+![Two tabs, one with a pink annotation reading "auto", the other with an annotation "manual"](images/tab-accessibility-3.png)
+
+<Caption>
+  Annotate whether the tabs should be implemented as automatic or manual.
+</Caption>
+
+</Column>
 </Row>
+
+## Development considerations
+
+Keep these considerations in mind if you are modifying Carbon or creating a
+custom component.
+
+- Tabs are implemented as a `tablist`, with each tab item implemented as a
+  `<button>` with a role of `tab`.
+- The selected tab has attributes `aria-selected="true"` and `tabindex="0"`. All
+  other tabs have these attribute values set to `"false"` and `"-1"`.
+- Each tab is associated with its tabpanel through `aria-controls`.
+- See the
+  [ARIA authoring practices guidance for tabs](https://w3c.github.io/aria-practices/#tabpanel)
+  for more considerations.
+- For accessibility considerations for manual tabs, see
+  [Deciding when to make selection automatically follow focus](https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/#kbd_selection_follows_focus).