docs: update tag docs on a11y tab (#3946)

* update accessibility.mdx * update a11y.mdx * remove anchor link * remove old a11y testing section * update a11y mdx * update a11y mdx * update images * update image * take out overflow guidance * Update src/pages/components/tag/accessibility.mdx Co-authored-by: Guilherme Datilio Ribeiro <[email protected]> * add tab order comment * update a11y.mdx --------- Co-authored-by: Guilherme Datilio Ribeiro <[email protected]> Co-authored-by: kodiakhq[bot] <49736102+kodiakhq[bot]@users.noreply.github.com>
carbon-design-system · Apr 11, 2024 · 8df4a1a · 8df4a1a
1 parent 2b4ec10
commit 8df4a1a
Show file tree

Hide file tree

Showing 6 changed files with 42 additions and 177 deletions.
diff --git a/src/pages/components/tag/accessibility.mdx b/src/pages/components/tag/accessibility.mdx
@@ -19,205 +19,70 @@ import {
   ListItem,
 } from '@carbon/react';
 
+<PageDescription>
+
+No accessibility annotations are needed for tags, but keep these considerations
+in mind if you are modifying Carbon or creating a custom component.
+
+</PageDescription>
+
 <AnchorLinks>
-  <AnchorLink>How it works</AnchorLink>
-  <AnchorLink>Accessibility considerations</AnchorLink>
-  <AnchorLink>Resources</AnchorLink>
-  <AnchorLink>Accessibility testing</AnchorLink>
+  <AnchorLink>What Carbon provides</AnchorLink>
+  <AnchorLink>Development considerations</AnchorLink>
 </AnchorLinks>
 
 <A11yStatus layout="table" components="Tag" />
 
-## How it works
+## What Carbon provides
 
-Tags are used for web content that needs to be labeled, categorized, or
-organized using keywords that describe them. Tags are often used as a filter
-where all tags are in the same color, or used when content is mapped to multiple
-categories, where color is used to differentiate between categories.
+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.
 
-## Accessibility considerations
+### Keyboard interaction
 
-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.
+Read-only tags are not in the tab order, are not interactive, and do not receive
+focus.
 
-1. Be sure the tag text is clear and concise.
-2. Color should not be used as the only means to differentiate tag categories.
-3. When using custom colors be sure the minimum contrast requirements are met.
-4. Tags that are modified as a link to filter content should also follow the
-   link Carbon Component guidance.
+Dismissible tags are in the tab order and receive focus around the close icon.
+Pressing `Enter` or `Space` will dismiss the tag. Tabbing away from the tag will
+move focus to the next element in the tab order.
 
-## Resources
+<Row>
+<Column colLg={8}>
 
-#### Helpful resources for creating customized accessible implementations
+![Dismissible tag in the tab order receiving focus on the close icon to potentially dismiss the tag.](images/tag-accessibility-dismissible.png)
 
-- [IBM Accessibility Requirements](https://www.ibm.com/able/requirements/requirements/):
-  - [1.4.1 Use of Color](https://www.ibm.com/able/requirements/requirements/#1_4_1)
-    (WCAG Success Criteria
-    [1.4.1](https://www.w3.org/WAI/WCAG21/Understanding/use-of-color))
-  - [1.4.3 Contrast (Minimum)](https://www.ibm.com/able/requirements/requirements/#1_4_3)
-    (WCAG Success Criteria
-    [1.4.3](https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum))
+</Column>
+</Row>
 
-## Accessibility testing
+Selectable tags are in the tab order and focus is shown around each tag.
+Pressing `Enter` or `Space` toggles the selection on and off.
 
-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+tag%22+)
+<Row>
+<Column colLg={8}>
 
-### Automated test
+![A group of selectable tags in the tab order, with each tag receiving focus to select or deselect.](images/tag-accessibility-selectable.png)
 
-<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 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 />- Violations
-          </StructuredListCell>
-        </StructuredListRow>
-      </StructuredListBody>
-    </StructuredListWrapper>
-  </Column>
+</Column>
 </Row>
 
-### macOS Screen reader tests
+Operational tags are in the tab order and focus is shown around each tag.
+Pressing `Enter` or `Space` will disclose additional related tags.
 
 <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 />
-            - Safari Version 13.0.2
-            <br />- Carbon React version 7.7.1
-          </StructuredListCell>
-          <StructuredListCell>
-            <strong>VoiceOver(VO) test:</strong>
-            <OrderedList>
-              <ListItem>
-                Control-Option-Shift-Down Arrow to enter the Web area.
-              </ListItem>
-              <ListItem>
-                Press Control-Option-Right Arrow key. VO announces the label and
-                that it is a text element.
-              </ListItem>
-              <ListItem>
-                Navigate to the tag with filter. VO announces, "Clear Filter,
-                you are currently on a group. To interact with items in this
-                group press Control-Option-Shift-Down Arrow." (Note: There is an
-                open issue. VO does not announce the "X" clear filter when Tab
-                is pressed immediately after the Tag text is read.)
-              </ListItem>
-            </OrderedList>
-          </StructuredListCell>
-        </StructuredListRow>
-      </StructuredListBody>
-    </StructuredListWrapper>
-  </Column>
-</Row>
+<Column colLg={8}>
 
-### Windows screen reader tests
+![An operational tag in the tab order, disclosing related tags.](images/tag-accessibility-operational.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>
-                Navigate to the Tag. JAWS announces the tag text.
-              </ListItem>
-              <ListItem>
-                Navigate to the Tag with Filter. JAWS announces the tag text and
-                clear filter.
-              </ListItem>
-            </OrderedList>
-          </StructuredListCell>
-        </StructuredListRow>
-      </StructuredListBody>
-    </StructuredListWrapper>
-  </Column>
+</Column>
 </Row>
 
-### iOS screen reader tests
+## Developer considerations
 
-<Row>
-  <Column noGutterSm>
-    <StructuredListWrapper>
-      <StructuredListRow head>
-        <StructuredListCell head>Environment </StructuredListCell>
-        <StructuredListCell head>Results</StructuredListCell>
-      </StructuredListRow>
-      <StructuredListBody>
-        <StructuredListRow>
-          <StructuredListCell>
-            - iOS version 12.2 with VoiceOver
-            <br />
-            - Safari version 12.2
-            <br />- Carbon React version 7.7.1
-          </StructuredListCell>
-          <StructuredListCell>
-            <strong>VoiceOver test:</strong>
-            <OrderedList>
-              <ListItem>
-                Swipe Right to the tag. VO announces the tag text and main
-                landmark.
-              </ListItem>
-              <ListItem>
-                Navigate to the tag with filter. Swipe Right to the "X". VO
-                announces "Clear Filter Image. Possibly very sharp close."
-                (Note: There is an open issue. VO should announce this as a
-                clear filter button.)
-              </ListItem>
-            </OrderedList>
-          </StructuredListCell>
-        </StructuredListRow>
-      </StructuredListBody>
-    </StructuredListWrapper>
-  </Column>
-</Row>
+Keep this in mind if you’re modifying Carbon or creating a custom component.
+
+- Do not add an `onClick` functionality to the dismissible tag, and only reserve
+  interactions for the close icon in the tag.
+- Do not nest buttons within the operational tag. Consider using the `as` prop
+  to change an element tag to avoid nesting buttons.
diff --git a/src/pages/components/tag/images/tag-accessibility-dismissible.png b/src/pages/components/tag/images/tag-accessibility-dismissible.png
diff --git a/src/pages/components/tag/images/tag-accessibility-operational.png b/src/pages/components/tag/images/tag-accessibility-operational.png
diff --git a/src/pages/components/tag/images/tag-accessibility-overflow.png b/src/pages/components/tag/images/tag-accessibility-overflow.png
diff --git a/src/pages/components/tag/images/tag-accessibility-read-only.png b/src/pages/components/tag/images/tag-accessibility-read-only.png
diff --git a/src/pages/components/tag/images/tag-accessibility-selectable.png b/src/pages/components/tag/images/tag-accessibility-selectable.png