USWDS-Site - Navigation: Remove redundant "navigation" from aria-labels - #3237
Open
AKnassa wants to merge 1 commit into
Open
USWDS-Site - Navigation: Remove redundant "navigation" from aria-labels#3237AKnassa wants to merge 1 commit into
AKnassa wants to merge 1 commit into
Conversation
Screen readers announce the navigation role after the label, so labels like "Primary navigation" were read as "Primary navigation navigation". Strip the trailing word so each landmark is announced once, as originally intended. Add navigation_aria_label_spec to guard every site-owned template and content file against reintroducing the redundancy. Fixes uswds#3059
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
1 participant
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.
Summary
Removed the redundant word "navigation" from aria-labels on the site's navigation landmarks so screen readers announce each landmark once instead of twice (e.g. "Primary navigation navigation").
Related issue
Closes #3059
Problem statement
Screen readers announce an element's navigation role after reading its label. Site templates labeled their
<nav>landmarks with phrases ending in "navigation" ("Primary navigation", "Page navigation", "Next report internal navigation"), so users of screen readers heard the word twice on every page — the exact redundancy MDN's navigation role guidance says to avoid.Solution
Stripped the trailing "navigation" from every site-owned navigation landmark, so what's announced is exactly what each label originally intended, once:
_includes/navbar.html— "Primary navigation" → "Primary" (the site-wide top nav)_includes/next/next-prefooter.html— "Page navigation" → "Page"_layouts/next-content.htmland_next/01-summary.md— "Next report internal navigation" → "Next report internal"Deliberately left unchanged, with reasons:
<aside>labels (_layouts/pattern.html,_layouts/styleguide.html) — asides announce as "complementary", not "navigation", so there's no redundancy there. The in-page-nav component also builds its own inner<nav>labeled fromdata-title-text, not the aside's label.@uswds/uswdspackage — those labels are covered by USWDS - Bug: Remove "navigation" text from aria labels for navigation roles uswds#6301 and should be fixed there.Also added
spec/navigation_aria_label_spec.rb, which scans every site-owned.htmland.mdfile for navigation landmarks whose aria-label still contains "navigation" — it caught the fourth offender in_next/01-summary.mdduring development and guards against the redundancy coming back.Testing and review
bundle exec rspec— 11 examples, 0 failures.bundle exec jekyll build— the built homepage rendersaria-label="Primary"and the /next/ report pages render the shortened labels; no site-owned nav landmark retains the redundant word.