Filter results a11y docs (#617)

* adds documentation about announcing the completion of a filter process * Update content/components/text-input.mdx Co-authored-by: Natalya Shelburne <[email protected]> * updates a11y guidance on conveying filter status --------- Co-authored-by: Natalya Shelburne <[email protected]>
primer · Oct 26, 2023 · 428fc2e · 428fc2e
1 parent 3331b40
commit 428fc2e
Show file tree

Hide file tree

Showing 3 changed files with 27 additions and 0 deletions.
diff --git a/content/components/action-list.mdx b/content/components/action-list.mdx
@@ -283,6 +283,12 @@ A nav list organizes navigation links for the user's current context and indicat
 
 ## Accessibility
 
+### Conveying filter results to assistive technologies
+
+If an action list is being used to display a filtered list of options, a screen reader should announce when filtering is completed.
+
+For more information, see the [conveying status (filter results)](/ui-patterns/loading#filter-results) section of the loading state pattern guidelines.
+
 ### Tooltips and dialogs on inactive items
 
 <Box

diff --git a/content/components/text-input.mdx b/content/components/text-input.mdx
@@ -156,6 +156,7 @@ See [text input with tokens](/components/text-input-with-tokens)
   - The placeholder text disappears as soon as the input has a value
   - Placeholder text colors are typically too light to meet the minimum color contrast ratio required for accessibility
   - Screen readers do not read placeholder text as a label
+- Text inputs whose value is used to filter a list of results should be paired with an announcement for the effect of the filter. For more information, see the [conveying status (filter results)](/ui-patterns/loading#filter-results) section of the loading state pattern guidelines.
 
 ### Known accessibility issues (GitHub staff only)
 
@@ -166,3 +167,4 @@ See [text input with tokens](/components/text-input-with-tokens)
 - [Forms](../ui-patterns/forms/overview)
 - [Autocomplete](/components/autocomplete)
 - [Text input with tokens](/components/text-input-with-tokens)
+11
diff --git a/content/ui-patterns/loading.mdx b/content/ui-patterns/loading.mdx
@@ -328,6 +328,25 @@ There are many cases where it will be obvious that a process has completed or fa
 
 For other cases, the status will need to be manually conveyed to assistive technologies. Use a `role="status"` message or put content in an `aria-live` element that communicates the status of a process.
 
+#### Filter results
+
+<Box display="flex" flexDirection={['column', 'column', 'column', 'column', 'row']} sx={{alignItems: 'flex-start', gap: 3, mb: 3}}>
+
+<div>
+
+If the user needs to wait for filtering to complete, a screen reader should announce how many results were returned from filtering. For example: "No items match the filter", or "5 items match the filter".
+
+To ensure that assistive technology is informed about the filter update, put the message in an element that has a `role` of `"status"`. The element with `role="status"` must always be rendered, not just when the message should be announced.
+
+Implementations of this pattern can be seen in the following examples:
+- [Lookbook - Autocomplete](https://view-components-storybook.eastus.cloudapp.azure.com/view-components/lookbook/inspect/primer/alpha/auto_complete/playground)
+- [Storybook - ActionList](https://primer.style/react/storybook/?path=/story/components-actionlist-examples--async-list-with-spinner)
+
+</div>
+
+<img width="456" role="presentation" src="https://github.com/primer/design/assets/2313998/61171c17-274d-416b-81a7-825a610fdd24" />
+</Box>
+
 ### Preventing partially loaded content from being announced
 
 If an `aria-live` region of a page is being updated, set `aria-busy="true"` on the live region until the updates are complete. Then, set `aria-busy="false"`. This prevent assistive technologies from announcing updates until the updates are complete.