Repository navigation
Make the site search box's accessible name match its visible text #266
Description
What is wrong
The search box at the top of every page of the published site is announced as "Search documentation", but the text a sighted user sees in it is "Search docs...". In scripts/build-html.js the input has both a visually hidden <label> ("Search docs") and an aria-label="Search documentation"; the aria-label replaces the label, so the accessible name does not contain the visible words. A voice control user who says "click Search docs" may not reach the field (WCAG 2.5.3 Label in Name), and the label element is dead code.
Found by a code review of the site template on 2026-10-28; not yet confirmed with assistive technology.
Why this is a good first issue
It is a one-attribute change in one file, and it teaches how a field gets its accessible name.
What to do
- In
scripts/build-html.js, removearia-label="Search documentation"from thesite-searchinput, so its name comes from<label for="site-search">Search docs</label>. - Check the search page template in the same file for the same pattern.
- Run
npm run build:htmland commit the script with the regeneratedhtml/files.
Acceptance criteria
- The search input has no
aria-label, and its<label>text matches the start of its visible placeholder. - With a screen reader, Tab to the search box: it is announced as "Search docs" and as an edit or search field. Say in the pull request which screen reader and browser you used.
Generated by Claude Code
Activity
accesswatch commentedon Oct 28, 2026
The markup fix is merged in #271:
aria-label="Search documentation"is removed from thesite-searchinput in both templates (every page and the search page), so the field takes its name from<label for="site-search">Search docs</label>.What remains is the screen reader check from the acceptance criteria, which could not be done where the change was made. Tab to the search box and confirm it is announced as "Search docs" and as an edit or search field. Then close this issue and say which screen reader and browser you used.
Generated by Claude Code
accesswatch commentedon Oct 28, 2026
Checked on the live site in a browser (Chromium, in the Claude desktop app) after pull request 271 deployed. The search box (
#site-search, type search) no longer has an aria-label. Its name comes from its label element, "Search docs", which is visually hidden but present in the accessibility tree. The visible text is the placeholder "Search docs…", so the accessible name contains the visible text, as WCAG 2.5.3 Label in Name asks. The submit button is named "Submit search". This is a check of the accessibility tree, not a listen with a screen reader. Closing as fixed.Generated by Claude Code
docs(a11y): drop known limitations fixed in #273 (#282)