diff --git a/src/pages/components/search/accessibility.mdx b/src/pages/components/search/accessibility.mdx index 3c7be909d14..030252763a6 100644 --- a/src/pages/components/search/accessibility.mdx +++ b/src/pages/components/search/accessibility.mdx @@ -14,255 +14,138 @@ import { ListItem, } from '@carbon/react'; + + +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. + + + - How it works - Accessibility considerations - Accessibility testing - -## How it works +What Carbon provides +Design recommendations +Development considerations -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. + + +## 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)) + + -## 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+). + + The search input is in the tab order just like any other input. + -### Automated test + + - - - - - - Automated test environment - - Results - - - - - - - macOS Mojave version 10.14.6 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: -
- No violations - - - - - + + +![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) + + The user can clear the input by pressing Esc or activating the X button that + appears inside the input. + + + -### 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. - - - - - 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: - - - Tab to the Search Custom Button component. VO announces, "Search - edit text main". - - - Enter text in the text field. VO announces each letter as its - entered. - - - Tab to the X button. VO announces, "Clear search input button." - - - Press the Enter key and the text box is cleared. - - Tab back to the text box. - - Enter text in the text field. VO announces each letter as its - entered. - - - Tab to the X button and then Tab back. VO announces the - previously entered text. - - - Press Tab twice. VO announces the Search button. - - - Press Tab again. VO announces the Filter button. - - - - - - - - + -### Windows screen reader tests +![illustration showing the search icon being activated via Enter or Space](images/search-accessibility-3.png) + + A variation where the search input is revealed by activating the magnifying + glass icon. + + + + - - - - - Environment - Results - - - - - - - Microsoft Windows 10 -
- - JAWS 19.1810.64 -
- - Firefox version 67 -
- Carbon React version 7.7.1 - - - JAWS test: - - - Tab to the Search Custom Button component. JAWS announces, "Main - region. Search edit type and text." - - - Enter text in the text field. JAWS announces each letter as its - entered. - - - Tab to the X button. JAWS announces, "Clear search input - button." - - - Press the Enter key and the text box is cleared and focus moves - back to the text field. - - - Enter text in the text field. JAWS announces each letter as its - entered. - - - Tab to the X button and then Tab back. JAWS announces the - previously entered text. - - - Press Tab twice. JAWS announces the Search button. - - - Press Tab again. JAWS announces the Filter button. - - - - - - - + + +![putting focus on the magnifying glass causes the search input to be revealed and given focus](images/search-accessibility-4.png) + + + A variation where the search input is revealed when the magnifying glass + receives focus. + + + -### 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”). - - - - Environment - Results - - - - - - iOS version 13.1.3 with VoiceOver -
- - Safari version 13.1.3 -
- Carbon React version 7.7.1 - - - VoiceOver test: - - - Swipe Right to the Search Custom Button component. VO announces, - "Search Search text field. Double tap to edit. Insertion point - at end." - - - Enter text in the text field. VO announces each letter as its - entered. - - - Swipe Right to the X button. VO announces, "Clear search input - button." - - Double tap and the text box is cleared. - - Swipe Left to go back to the text box. Note: There is an open - issue of iOS because focus moves to browser address bar. - - - Navigate back to the Search input and enter text in the text - field. VO announces each letter as its entered. - - - Swipe Right twice. VO announces the Search button. - - - Swipe Right again. VO announces the Filter button. - - - - - - - + + +![role and input named "search", and button named 'clear search input'](images/search-accessibility-5.png) + + + The search region, input name, and clear button are all incorporated by + Carbon. + + + + +## 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. diff --git a/src/pages/components/search/images/search-accessibility-1.png b/src/pages/components/search/images/search-accessibility-1.png new file mode 100644 index 00000000000..dc0fc608b05 Binary files /dev/null and b/src/pages/components/search/images/search-accessibility-1.png differ diff --git a/src/pages/components/search/images/search-accessibility-2.png b/src/pages/components/search/images/search-accessibility-2.png new file mode 100644 index 00000000000..3593da32f67 Binary files /dev/null and b/src/pages/components/search/images/search-accessibility-2.png differ diff --git a/src/pages/components/search/images/search-accessibility-3.png b/src/pages/components/search/images/search-accessibility-3.png new file mode 100644 index 00000000000..7e288f8e216 Binary files /dev/null and b/src/pages/components/search/images/search-accessibility-3.png differ diff --git a/src/pages/components/search/images/search-accessibility-4.png b/src/pages/components/search/images/search-accessibility-4.png new file mode 100644 index 00000000000..9eaba32a1ac Binary files /dev/null and b/src/pages/components/search/images/search-accessibility-4.png differ diff --git a/src/pages/components/search/images/search-accessibility-5.png b/src/pages/components/search/images/search-accessibility-5.png new file mode 100644 index 00000000000..093d8e5440f Binary files /dev/null and b/src/pages/components/search/images/search-accessibility-5.png differ