Update accessibility.mdx

src/pages/components/search/accessibility.mdx

@@ -14,255 +14,138 @@ import {
   ListItem,
 } from '@carbon/react';
 
+<PageDescription>
+
+Carbon’s search component provides the basic input mechanism for conducting a
+search. No accessibility annotations are needed for the input, but design
+annotations are needed to make the search messaging and results accessible.
+
+</PageDescription>
+
 <AnchorLinks>
-  <AnchorLink>How it works</AnchorLink>
-  <AnchorLink>Accessibility considerations</AnchorLink>
-  <AnchorLink>Accessibility testing</AnchorLink>
-</AnchorLinks>
 
-## How it works
+<AnchorLink>What Carbon provides</AnchorLink>
+<AnchorLink>Design recommendations</AnchorLink>
+<AnchorLink>Development considerations</AnchorLink>
 
-The search Carbon component contains a collection of items and objects that, as
-a whole, combine to create search functionality to content on the website. WAI
-ARIA labels are used on each button so users of assistive technologies
-understand the purpose of the button.
+</AnchorLinks>
+
+## What Carbon provides
 
-## Accessibility considerations
+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.
 
-1. Provide a search function to help users find content.
-1. If a page includes more than one search landmark, each search field should
-   have a unique label.
-1. If you change any of the default labels, be sure the new label is clear and
-   concise.
+### Keyboard interaction
 
-## Resources
+The search component is in the tab order, and users can type directly into the
+search input on focus. Users press `Enter` to submit their text as a search
+term, or they can press `Esc` to clear it. Once users start typing, a Cancel
+icon ('x') will appear, which becomes the next tab stop and provides another way
+to clear the input field via click, `Space` or `Enter` keys.
 
-- [W3C WAI-ARIA Landmarks Example](https://www.w3.org/TR/wai-aria-practices/examples/landmarks/search.html)
-  covers the usage of ARIA landmarks on a search widget.
-- [IBM Accessibility Requirements](https://www.ibm.com/able/requirements/requirements/):
-  - [1.3.1 Information and Relationships](https://www.ibm.com/able/requirements/requirements/#1_3_1)
-    (WCAG Success Criteria
-    [1.3.1](http://www.w3.org/TR/2016/NOTE-UNDERSTANDING-WCAG20-20161007/content-structure-separation-programmatic.html))
-  - [3.3.2 Labels and Instructions](https://www.ibm.com/able/requirements/requirements/#3_3_2)(WCAG
-    Success Criteria
-    [3.3.2](http://www.w3.org/TR/UNDERSTANDING-WCAG20/minimize-error-cues.html))
-  - [4.1.2 Name, Role, Value](https://www.ibm.com/able/requirements/requirements/#4_1_2)
-    (WCAG Success Criteria
-    [4.2.1](https://www.w3.org/WAI/WCAG21/Understanding/name-role-value))
+<Row>
+<Column colLg={8}>
 
-## Accessibility testing
+![example of search keyboard navigation](images/search-accessibility-1.png)
 
-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+search%22+).
+<Caption>
+  The search input is in the tab order just like any other input.
+</Caption>
 
-### Automated test
+</Column>
+</Row>
 
 <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}>
+
+![illustration showing that after a user begins typing in a search field, an X button appears on the right side of the input that can be tabbed to and activated with Space or Enter](images/search-accessibility-2.png)
 
+<Caption>
+  The user can clear the input by pressing Esc or activating the X button that
+  appears inside the input.
+</Caption>
+
+</Column>
 </Row>
 
-### MacOS screen reader tests
+Variations of the search component use a non-persistent text input that is
+hidden behind a magnifying glass icon. In one variation, the user activates the
+icon-only button to reveal and put focus into the search input. In another
+variation, as the icon receives focus it exposes the input and the focus is
+immediately placed into the search input. Once in the input, the interaction,
+described above, is the same for all variations.
 
 <Row>
-  <Column>
-    <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 Search Custom Button component. VO announces, "Search
-                edit text main".
-              </ListItem>
-              <ListItem>
-                Enter text in the text field. VO announces each letter as its
-                entered.
-              </ListItem>
-              <ListItem>
-                Tab to the X button. VO announces, "Clear search input button."
-              </ListItem>
-              <ListItem>
-                Press the Enter key and the text box is cleared.
-              </ListItem>
-              <ListItem>Tab back to the text box.</ListItem>
-              <ListItem>
-                Enter text in the text field. VO announces each letter as its
-                entered.
-              </ListItem>
-              <ListItem>
-                Tab to the X button and then Tab back. VO announces the
-                previously entered text.
-              </ListItem>
-              <ListItem>
-                Press Tab twice. VO announces the Search button.
-              </ListItem>
-              <ListItem>
-                Press Tab again. VO announces the Filter button.
-              </ListItem>
-            </OrderedList>
-          </StructuredListCell>
-        </StructuredListRow>
-      </StructuredListBody>
-    </StructuredListWrapper>
-  </Column>
-</Row>
+<Column colLg={8}>
 
-### Windows screen reader tests
+![illustration showing the search icon being activated via Enter or Space](images/search-accessibility-3.png)
 
+<Caption>
+  A variation where the search input is revealed by activating the magnifying
+  glass icon.
+</Caption>
+
+</Column>
+</Row>
 <Row>
-  <Column noGutterSm>
-    <StructuredListWrapper>
-      <StructuredListHead>
-        <StructuredListRow head>
-          <StructuredListCell head>Environment</StructuredListCell>
-          <StructuredListCell head>Results</StructuredListCell>
-        </StructuredListRow>
-      </StructuredListHead>
-      <StructuredListBody>
-        <StructuredListRow>
-          <StructuredListCell>
-            - Microsoft Windows 10
-            <br />
-            - JAWS 19.1810.64
-            <br />
-            - Firefox version 67
-            <br />- Carbon React version 7.7.1
-          </StructuredListCell>
-          <StructuredListCell>
-            <strong>JAWS test:</strong>
-            <OrderedList>
-              <ListItem>
-                Tab to the Search Custom Button component. JAWS announces, "Main
-                region. Search edit type and text."
-              </ListItem>
-              <ListItem>
-                Enter text in the text field. JAWS announces each letter as its
-                entered.
-              </ListItem>
-              <ListItem>
-                Tab to the X button. JAWS announces, "Clear search input
-                button."
-              </ListItem>
-              <ListItem>
-                Press the Enter key and the text box is cleared and focus moves
-                back to the text field.
-              </ListItem>
-              <ListItem>
-                Enter text in the text field. JAWS announces each letter as its
-                entered.
-              </ListItem>
-              <ListItem>
-                Tab to the X button and then Tab back. JAWS announces the
-                previously entered text.
-              </ListItem>
-              <ListItem>
-                Press Tab twice. JAWS announces the Search button.
-              </ListItem>
-              <ListItem>
-                Press Tab again. JAWS announces the Filter button.
-              </ListItem>
-            </OrderedList>
-          </StructuredListCell>
-        </StructuredListRow>
-      </StructuredListBody>
-    </StructuredListWrapper>
-  </Column>
+<Column colLg={8}>
+
+![putting focus on the magnifying glass causes the search input to be revealed and given focus](images/search-accessibility-4.png)
+
+<Caption>
+  A variation where the search input is revealed when the magnifying glass
+  receives focus.
+</Caption>
+
+</Column>
 </Row>
 
-### iOS Screen Reader Tests
+### Role and label
+
+Carbon assigns the entire search interaction a `role` of "search". It also
+provides non-visible labels for the search input and icon (“search”), and for
+the cancel icon (“clear search input”).
 
 <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 Search Custom Button component. VO announces,
-                "Search Search text field. Double tap to edit. Insertion point
-                at end."
-              </ListItem>
-              <ListItem>
-                Enter text in the text field. VO announces each letter as its
-                entered.
-              </ListItem>
-              <ListItem>
-                Swipe Right to the X button. VO announces, "Clear search input
-                button."
-              </ListItem>
-              <ListItem>Double tap and the text box is cleared.</ListItem>
-              <ListItem>
-                Swipe Left to go back to the text box. Note: There is an open
-                issue of iOS because focus moves to browser address bar.
-              </ListItem>
-              <ListItem>
-                Navigate back to the Search input and enter text in the text
-                field. VO announces each letter as its entered.
-              </ListItem>
-              <ListItem>
-                Swipe Right twice. VO announces the Search button.
-              </ListItem>
-              <ListItem>
-                Swipe Right again. VO announces the Filter button.
-              </ListItem>
-            </OrderedList>
-          </StructuredListCell>
-        </StructuredListRow>
-      </StructuredListBody>
-    </StructuredListWrapper>
-  </Column>
+<Column colLg={8}>
+
+![role and input named "search", and button named 'clear search input'](images/search-accessibility-5.png)
+
+<Caption>
+  The search region, input name, and clear button are all incorporated by
+  Carbon.
+</Caption>
+
+</Column>
 </Row>
+
+## Design recommendations
+
+Carbon provides a
+[search pattern](https://carbondesignsystem.com/patterns/search-pattern/) that
+outlines three search types: basic, active, and focused. Each of these types
+starts with the basic search input mechanism provided by Carbon’s search
+component. However, each search type displays suggestions or results in
+different ways, which all have accessibility considerations. There are three
+broad areas that designers need to consider and annotate for accessibility:
+
+- Search suggestions and typeaheads
+- Search outcomes and status (e.g., “25 results found”, “no results found”)
+- Results navigation
+
+Future updates to this guidance will offer specific documentation on these
+accessibility needs.
+
+## Development considerations
+
+Keep these considerations in mind if you are modifying Carbon or creating a
+custom component.
+
+- The div containing the search function is given a `role="button"`.
+- The hidden label for the input has a default value of “search”.
+- The input is `type="text"` with a `role="searchbox"`; using `type="search"` is
+  equivalent and also valid.
+- See the
+  [Mozilla search input documentation](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/search)
+  for more considerations.