fix(a11y): add persistent instructions for search field#401
Merged
Conversation
The Search combobox relied on a placeholder that disappears once the user types, leaving no persistent label or instructions describing its purpose. Adds programmatically-associated, persistent instructions via aria-describedby pointing to an sr-only element that describes the field's purpose and how to operate the suggestions (arrow keys / Enter). The existing aria-label="Search" is preserved. Fixes WCAG 3.3.2 (Labels or Instructions). Applies site-wide via the shared navbar include. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
xuzhg
approved these changes
Jun 15, 2026
There was a problem hiding this comment.
Pull request overview
This PR improves the accessibility of the site-wide navbar search combobox by adding persistent, programmatically-associated usage instructions for screen reader users (addressing reliance on a disappearing placeholder).
Changes:
- Added
aria-describedby="main-search-instructions"to the main search input. - Added an
sr-onlyinstructional<span>describing the search purpose and how to navigate suggestions via keyboard.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
The Search combobox relied on a placeholder that disappears once the user types, leaving no persistent label or instructions describing its purpose, failing WCAG 3.3.2 (Labels or Instructions).
Where the issue is
The "Search Suggestion" edit field in the navbar on the Home page (applies site-wide via the shared navbar include).
Solution
Add programmatically-associated, persistent instructions via
aria-describedbypointing to ansr-onlyelement that describes the field and how to operate the suggestions (arrow keys / Enter). The existingaria-label="Search"is preserved.Where in code
_includes/navbar.html-aria-describedby="main-search-instructions"on the input plus a new<span id="main-search-instructions" class="sr-only">...</span>.Validated against WCAG 2.1 AA (keyboard, screen reader, and 400% zoom where applicable).