Skip to content

fix(theme-classic): announce page title on route change for screen readers - #12387

Open
gonzoblasco wants to merge 1 commit into
facebook:mainfrom
gonzoblasco:fix/announce-page-title-on-route-change
Open

fix(theme-classic): announce page title on route change for screen readers#12387
gonzoblasco wants to merge 1 commit into
facebook:mainfrom
gonzoblasco:fix/announce-page-title-on-route-change

Conversation

@gonzoblasco

Copy link
Copy Markdown

Summary

Fixes #11332: SPA route navigations are not announced by screen readers (NVDA, VoiceOver).

Root cause

Docusaurus already moves focus to the skip-to-content container on route change (PUSH), but that container has a static aria-label of "Skip to main content". When a screen reader user navigates, focus lands on that container and the SR announces "Skip to main content region" (or nothing), not the title of the page they landed on. The user knows a navigation happened but not which page they are on.

Change

Pass the page title down from the Layout to the SkipToContent component, and use it to set the skip-to-content container's aria-label to the formatted page title when navigating. The container is focused on route change, so the screen reader announces the page title.

The container's aria-label is restored to "Skip to main content" on the next render, so the skip link keeps working as before for keyboard users who tab to it.

This uses the page title from the Layout prop (formatted via useTitleFormatter) rather than reading document.title, because Helmet updates document.title asynchronously (deferred via requestAnimationFrame), so it is not reliable at the moment focus moves.

Why focus management (not a live region)

A live region would announce on the audio channel but does not reliably reach refreshable braille displays, and it competes with the new page's own announcements. Moving focus to a meaningful landmark is the one mechanism all screen readers and braille displays agree on, and it matches the MPA behavior the issue asks for.

Tests

  • Added skipToContentUtils.test.tsx verifying that:
    • Focus moves to the skip-to-content container on route change.
    • The container's aria-label is updated to the page title when navigating.
  • 116 tests pass in docusaurus-theme-common.
  • 51 tests pass in docusaurus-theme-classic.
  • Typecheck passes for both packages.

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

Labels

CLA Signed Signed Facebook CLA

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Single page app (SPA) route navigations sometimes not announced by screen readers (NVDA, VoiceOver)

1 participant