Skip to content

Commit

Permalink
Update accessibility.mdx (#3187)
Browse files Browse the repository at this point in the history 
* Update accessibility.mdx

first draft of new content. illustrations not yet added

* First image uploads

* Update accessibility.mdx

Minor text updates

* image paid attempt

attempt

* Update accessibility.mdx

attempt to remove the DoDont key word in mdx

* Update accessibility.mdx

Attempt to remove do don't styline on pair of images

* Update accessibility.mdx

attempt to incorporate captions

* addition image and text updates

* Update accessibility.mdx

change caption position. minor tweaks to style

* Update accessibility.mdx

Slight tweaks to wording

* chore(format): output of yarn:format

* Update accessibility.mdx

removing superfluous quotation mark

* Updated images and altered layout

Changes to images from Lauren. Also made side by side images into stacked images, as per her request.

* Update accessibility.mdx

Tried changing case on Row element

Co-authored-by: Taylor Jones <taylor.jones826@gmail.com>
Co-authored-by: Lauren Rice <43969356+laurenmrice@users.noreply.github.com>
  • Loading branch information
@mbgower @tay1orjones @laurenmrice
3 people authored Oct 18, 2022
1 parent 68a729e commit cec4859
Show file tree
Hide file tree
Showing 6 changed files with 110 additions and 227 deletions.
337 changes: 110 additions & 227 deletions src/pages/components/search/accessibility.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Binary file added src/pages/components/search/images/search-accessibility-1.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added src/pages/components/search/images/search-accessibility-2.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added src/pages/components/search/images/search-accessibility-3.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added src/pages/components/search/images/search-accessibility-4.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added src/pages/components/search/images/search-accessibility-5.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.

1 comment on commit cec4859

@vercel
Copy link

@vercel vercel bot commented on cec4859 Oct 18, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Successfully deployed to the following URLs:

carbondesignsystem – ./

carbondesignsystem.vercel.app
carbondesignsystem-git-main-carbon-design-system.vercel.app
carbondesignsystem-carbon-design-system.vercel.app

Please sign in to comment.