Skip to content

Fix 508 accessibility issues on the website#18924

Open
tinogutierrez wants to merge 3 commits intomainfrom
om/tino/fix-508-accessibility-issues-website
Open

Fix 508 accessibility issues on the website#18924
tinogutierrez wants to merge 3 commits intomainfrom
om/tino/fix-508-accessibility-issues-website

Conversation

@tinogutierrez
Copy link
Collaborator

@tinogutierrez tinogutierrez commented Mar 10, 2026

This PR fixes all 6 acceptance criteria from #18031 (WAVE and ARC toolkit findings), addressing 508/WCAG accessibility violations on the ReportStream website.

Test Steps:

  1. Navigate to http://localhost:3000
  2. Tab to the "Skip to main content" link and press Enter — confirm focus moves to <main>
  3. Open browser DevTools and confirm aria-controls on "About" and "Getting started" nav buttons matches the id of their dropdown menus
  4. Inspect <header> elements — confirm only 2 exist and neither is inside <main>
  5. Inspect the home logo link — confirm aria-label="ReportStream home"
  6. Confirm header[aria-label="Primary navigation"] is present in the DOM

Changes

  • ReportStreamHeader.tsx: Fix aria-controls/id mismatch on nav dropdown buttons — both now derive from menuName.toLowerCase().replace(/\s+/g, "-") + "-dropdown" (ARC issue 1)
  • ReportStreamHeader.tsx: Add aria-label="Primary navigation" to primary <Header> landmark (ARC issue 2)
  • ReportStreamHeader.tsx: Add aria-label="Secondary navigation" to auth <Header> landmark (ARC issue 2)
  • ReportStreamHeader.tsx: Update home link from aria-label="Home"aria-label="ReportStream home" to satisfy WCAG 2.5.3 Label in Name (ARC issue 4)
  • MainLayout.tsx: Add USWDS skip nav link (<a class="usa-skipnav">) before the header (ARC issue 3)
  • MainLayout.tsx: Add tabIndex={-1} to <main id="main-content"> so skip nav correctly moves keyboard focus (ARC issue 3)
  • home/index.mdx: Replace <header> with <section> in the hero to remove a spurious banner landmark inside <main> (ARC issue 2)

Checklist

Testing

  • Tested locally?
  • Ran ./prime test or ./gradlew testSmoke against local Docker ReportStream container?
  • (For Changes to /frontend-react/...) Ran npm run lint:write?
  • Added tests?

Process

  • Are there licensing issues with any new dependencies introduced?
  • Includes a summary of what a code reviewer should test/verify?
  • Updated the release notes?
  • Database changes are submitted as a separate PR?
  • DevOps team has been notified if PR requires ops support?

Linked Issues

To Be Done

No remaining work in this PR.

Specific Security-related subjects a reviewer should pay specific attention to

  • Does this PR introduce new endpoints? No
  • Does this PR include changes in authentication and/or authorization of existing endpoints? No
  • Does this change introduce new dependencies that need vetting? No
  • Does this change require changes to our infrastructure? No
  • Does logging contain sensitive data? No
  • Does this PR include or remove any sensitive information itself? No

Tino Gutierrez added 3 commits March 9, 2026 11:52
Without tabIndex={-1} on <main>, activating the skip nav link scrolled
to #main-content but left focus on BODY, breaking keyboard navigation.
Explicitly setting tabIndex={-1} ensures focus moves to <main> on
activation while keeping it out of the natural tab order.
The hero used <header> as a styling wrapper inside <main>, which
browsers expose as a top-level banner landmark to assistive
technologies — causing the ARC toolkit "multiple header landmarks"
violation. Replaced with <section>, which carries no landmark role
and is the correct semantic element for a thematic content grouping.
Reduces top-level <header> elements from 3 to 2.
@scott-aquia
Copy link
Collaborator

Snyk checks have passed. No issues have been found so far.

Status Scanner Critical High Medium Low Total (0)
Open Source Security 0 0 0 0 0 issues

💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Fix 508 accessibility issues on the website

2 participants