fix(theme-classic): announce page title on route change for screen readers - #12387
Open
gonzoblasco wants to merge 1 commit into
Open
fix(theme-classic): announce page title on route change for screen readers#12387gonzoblasco wants to merge 1 commit into
gonzoblasco wants to merge 1 commit into
Conversation
7 tasks
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.
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-labelof "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
Layoutto theSkipToContentcomponent, and use it to set the skip-to-content container'saria-labelto 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-labelis 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
Layoutprop (formatted viauseTitleFormatter) rather than readingdocument.title, because Helmet updatesdocument.titleasynchronously (deferred viarequestAnimationFrame), 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
skipToContentUtils.test.tsxverifying that:aria-labelis updated to the page title when navigating.docusaurus-theme-common.docusaurus-theme-classic.