Search results: Update Results description with Structure and Code guidance

[Copilot]

💬Hello! This PR is to add code guidance to implementing a results description. Main problem is that result descriptions (like on Search or Find a Form) use <h2> for some reason and should instead be plain text. Additionally, screen readers announce the results description in a fragmented way. A MHV engineer wrote new guidance to mitigate these issues for future engineers when developing result descriptions. Note that in terms of visual changes the "[query]" portion will need to be unbolded (is currently in Figma Search Results template)

(rest of this is generated by Copilot)

The Results description section lacked format guidance and accessibility/coding best practices, leaving teams to infer implementation details from existing VA.gov examples (some of which use an unnecessary <h2>).

Changes

• src/_includes/components/results-description.md — Restructured content into two subsections:

Structure

Clarifies the canonical format and its variants:

• Base: Showing 1–10 of 999 for "[query]"
• Non-search contexts: omit for "[query]" (e.g., medications, appointments)
• Filtered results: append with X filters applied; sorting doesn't require it since the Sort component is the visual indicator

Code guidance

Seven developer-facing bullets from accessibility testing findings:

• <h2> is not required — a stable element with an ID is sufficient for focus management
• role="status" gives implicit aria-live="polite"; no explicit aria-live needed
• tabindex="-1" is required to support programmatic focus
• Content announces as a single unit when focus moves to it (assuming atomic DOM update)
• Inline elements (<strong>, <span>, etc.) can fragment VoiceOver announcements — prefer plain text
• aria-atomic="true" may help when inline styling is unavoidable, but screen reader behavior varies

Example implementation:

<div id="showingResults" role="status" tabindex="-1">
  Showing 1 to 10 of 18 medications with Active status
</div>

Original prompt

Create a PR to update the “Results description” section of the Search results template documentation page so it matches the structure and guidance below.

Target page (docs site): https://design.va.gov/templates/search-results#results-description

Repository: department-of-veterans-affairs/vets-design-system-documentation

Related issue:

• Update Search Results template guidance for results description #5829

Desired new content/structure

Replace/restructure the existing “results description” section so it has:

Results description

Text describing how many results are being shown.

Structure

The 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.

Code guidance

• An

  is not required for the results description. Some implementations on VA.gov may use this convention, but this is not necessary. 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. Based on this, we recommend avoiding inline stylistic elements within the results description when possible, and instead relying 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.

Implementation notes

• Find the source file that renders the Search results template page and update only the relevant section.
• Keep headings consistent with the existing page’s heading hierarchy and markdown conventions.
• Ensure the anchor #results-description remains valid.
• Add/adjust any internal links if necessary.

PR expectations

• Include a clear PR title referencing updating the Results description guidance.
• Mention/close issue Update Search Results template guidance for results description #5829 in the PR description if appropriate.
• Ensure docs build/tests (if present) still pass.

The following is the prior conversation context from the user's chat exploration (may be truncated):

User: Help me create a PR that will edit the result description section in the search results template: https://design.va.gov/templates/search-results#results-description.

Restructure that section so that this is the new structure

Results description

Text describing how many results are being shown.

Structure

The 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.

Code guidance

• An

  is not required for the results description. Some implementations on VA.gov may use this convention, but this is not necessary. 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. Based on this, we recommend avoiding inline stylistic elements within the results description when possible, and instead relying 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 ...

This pull request was created from Copilot chat.

Open Preview Environment

[Copilot]

Pull request overview

Updates the shared “results description” guidance used by the Search results template (and other pages that include it) to better document the expected text structure and accessibility-oriented implementation considerations.

Changes:

• Reorganizes the “Results description” content into “Structure” and “Code guidance” subsections.
• Documents the canonical results description string format and variants (non-search contexts, filtered results).
• Adds developer guidance for focus management and live-region announcements (role="status", tabindex="-1", avoiding inline elements).

[Copilot]

The aria-atomic="true" suggestion is a bit confusing alongside the recommendation to use role="status": elsewhere in the docs role="status" is described as implicitly setting aria-atomic="true" already. Consider clarifying that role="status" includes aria-atomic, and only suggest adding aria-atomic when using a different live-region approach.

Suggested change

	* 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.
	* 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 and you are using a live region approach other than `role="status"`, `aria-atomic="true"` may help, but results can still vary across screen readers.

[derekwang99]

Im not the best person to make the call on whether to commit this suggestion so feedback is welcome.

[jeana-adhoc]

@derekwang99 - I see this is still in draft mode - are you ready for our review?

[jeana-adhoc]

should this say "results" ? showing 1-10 of 999 what?

Maybe there was a content decision to leave off the noun, and I trust the content folks. it just feels weird not not have the noun/object of the search displayed

[jeana-adhoc]

Is the intent here to use a live region and to move focus at the same time to the results description? This seems like it would be redunandant? Moving focus to the description would also cause it to be announced. And the role="status" with the implicit aria-live would also cause it to be announced.