carbon-design-system · kodiakhq · Oct 18, 2022 · Oct 5, 2022 · Oct 5, 2022 · Oct 5, 2022
diff --git a/src/pages/components/accordion/usage.mdx b/src/pages/components/accordion/usage.mdx
@@ -55,7 +55,8 @@ extra click; instead use a full scrolling page with normal headers.
       id: 'accordion',
       label: 'Accordion',
     },
-  ]}>
+  ]}
+>
   <ComponentVariant
     id="accordion"
     knobs={{
@@ -70,7 +71,8 @@ extra click; instead use a full scrolling page with normal headers.
       Vue: 'http://vue.carbondesignsystem.com/?path=/story/components-cvaccordion--default',
       'Web Components':
         'https://web-components.carbondesignsystem.com/?path=/story/components-accordion--default',
-    }}>
+    }}
+  >
     {`
   <Accordion>
     <AccordionItem title="Title 1"><p>The accordion component delivers large amounts of content in a small space through progressive disclosure. The user gets key details about the underlying content and can choose to expand that content within the constraints of the accordion. Accordions work especially well on mobile interfaces or whenever vertical space is at a premium.</p></AccordionItem>

@@ -14,255 +14,136 @@ import {
   ListItem,
 } from '@carbon/react';
 
-<AnchorLinks>
-  <AnchorLink>How it works</AnchorLink>
-  <AnchorLink>Accessibility considerations</AnchorLink>
-  <AnchorLink>Accessibility testing</AnchorLink>
-</AnchorLinks>
+<PageDescription>
 
-## How it works
+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.
 
-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.
+</PageDescription>
 
-## Accessibility considerations
+<AnchorLinks>
 
-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.
+<AnchorLink>What Carbon provides</AnchorLink>
+<AnchorLink>Design recommendations</AnchorLink>
+<AnchorLink>Development considerations</AnchorLink>
 
-## Resources
+</AnchorLinks>
 
-- [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))
+## What Carbon provides
 
-## Accessibility testing
+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.
 
-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+).
+### Keyboard interaction
 
-### Automated test
+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.
 
 <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}>
 
-</Row>
+![example of search keyboard navigation](images/search-accessibility-1.png)
+
+<Caption>
+  The search input is in the tab order just like any other input.
+</Caption>
 
-### MacOS screen reader tests
+</Column>
+</Row>
 
 <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>
+<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>
 
-### Windows 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 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 colMd={4} colLg={4}>
+
+![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>
+<Column colMd={4} colLg={4}>
+
+![putting focus on the magnifying glass causes the search input to be revealed](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.