diff --git a/src/_includes/components/results-description.md b/src/_includes/components/results-description.md index cee77de65..dd7ee2b6c 100644 --- a/src/_includes/components/results-description.md +++ b/src/_includes/components/results-description.md @@ -1,12 +1,17 @@ Text describing how many results are being shown. -* **Showing 1–10 of 999 results for "[query]".** The implementation should follow this format: +#### Structure -> Showing 1–10 of 999 results for "[query]" - * When used in non-search contexts, omit the `for "[query]"` portion. For example: `Showing 1–10 of 999 results.` +The implementation should follow this format: -* **Update when filters change.** The results description must update when filters are changed so that all users can understand that the results have been updated. Implementation should follow this format: +* Showing 1–10 of 999 for "[query]" + * When used in non-search contexts, omit the `for "[query]"` portion. + * If a filter is applied to the results, add "with X filters applied" to the end. This is not necessary when sorting is applied since the Sort component itself acts as the visual indicator. -> Showing 1–10 of 999 results for "[query]" with 5 filters applied. +#### Code guidance -* **Do not reflect changes to sort.** The Sort component itself acts as the visual indicator of the order. +* An `

` is not required for the results description. Some implementations on VA.gov may use this convention, but this is discouraged. A stable, targetable element (e.g., ID) is sufficient for focus management. +* Using `role="status"` provides an implicit `aria-live="polite"`, which will announce updates when the content changes. Adding an explicit `aria-live` is not necessary. +* To support programmatic focus, `tabindex="-1"` is required if we intend to move focus to the results description element. This is a focus-driven announcement pattern and is separate from live region behavior. +* When moving focus to the results description, the content should be announced as a single unit, assuming the DOM update is atomic. In testing (especially with VoiceOver), inline elements such as ``, ``, etc., can cause the content to be announced in fragmented chunks instead of a single cohesive sentence, even though this is not consistently expected behavior. +* Avoid inline stylistic elements within the results description when possible, and instead rely on plain text to ensure consistent, single-pass announcements across assistive technologies. If inline styling is required, additional measures such as `aria-atomic="true"` may help, but results can still vary across screen readers.