Directory

Site editor: Fix the document title announcement for screen readers · Issue #56188 · WordPress/gutenberg · GitHub
Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Site editor: Fix the document title announcement for screen readers #56188

Closed
afercia opened this issue Nov 16, 2023 · 6 comments · Fixed by #56339
Closed

Site editor: Fix the document title announcement for screen readers #56188

afercia opened this issue Nov 16, 2023 · 6 comments · Fixed by #56339
Assignees
Labels
[Focus] Accessibility (a11y) Changes that impact accessibility and need corresponding review (e.g. markup changes). [Type] Bug An existing feature does not function as intended

Comments

@afercia
Copy link
Contributor

afercia commented Nov 16, 2023

Description

Alternative to #56167

The Site Editor uses a 'single page app' navigation type, where navigating through the different views of the editor updates the content of the page but the HTML document is always the same.
As such, like in all single page apps, the navigation needs to be announced bt screen readers to emulate the native beheavir of a traditional navigation across different pages, where the document title is announced as first thing.

The current implementation in the Site editor uses a speak() to announce the updated document title and the site title, also appending the string WordPress:

if ( title && siteTitle ) {
// @see https://github.com/WordPress/wordpress-develop/blob/94849898192d271d533e09756007e176feb80697/src/wp-admin/admin-header.php#L67-L68
const formattedTitle = sprintf(
/* translators: Admin screen title. 1: Admin screen name, 2: Network or site name. */
__( '%1$s ‹ %2$s — WordPress' ),
decodeEntities( title ),
decodeEntities( siteTitle )
);
document.title = formattedTitle;
// Announce title on route change for screen readers.
speak(
sprintf(
/* translators: The page title that is currently displaying. */
__( 'Now displaying: %s' ),
document.title
),
'assertive'
);
}

There's a few problems though:

  • Sometimes, the document title doesn't actually reflect the displayed view. For example, the initial view is called 'Design' but the current state of the editor is displaying the Home bloc template. The document title is <title>Blog Home ‹ Template ‹ Editor ‹ WordPress Develop — WordPress</title> and that gets announced, which is misleading and doesn't reflect what is shown visually.
  • When navigating to some page, the document title doesn't change. For example clicking on 'Templates', I would expect the document title to tell me I'm in the Templages page. Intead, it is still <title>Blog Home ‹ Template ‹ Editor ‹ WordPress Develop — WordPress</title>. This gets announced by screen readers and it's just wrong.
  • The same thing happens when clicking on Navigation, Styles, Pages, or Patterns: the document title is not announced so the audible feedback is just wrong. It appears all 'first level' pages in the routing mechanism don't update the document title correctly.
  • The announcement is too verbose anyways. For example, when navigating to the 'Single posts' template page, as a screen reader user I just need to know that the navigation completed succesfully and I'm now in the Single Posts view. Insteead, the announcement is really too long and annoying:
    Now displaying: Single Posts ‹ Template ‹ Editor ‹ WordPress Develop — WordPress

Suggested remediation:

  • Make sure the document title is always updated.
  • Make sure the document title always accurately reflects what the current view is.
  • Shorten the audibel message and strip out the part ‹ Editor ‹ WordPress Develop — WordPress.

Step-by-step reproduction instructions

  • Test with a screen reader. For this issue, using Safari and VoiceOver is sufficient. On Windows, you can try Firefox and NVDA.
  • Go to the Site editor and navigate through the site editor views.
  • Observe the navigation announcement is incorrect for the first level views.
  • Observe the announcement is too verbose and annoying.

Screenshots, screen recording, code snippet

Wrong document title announced on the Templates view:

wrong document title

Wrong document title announced on the Navigation view:

Screenshot 2023-11-16 at 09 14 59

Example of too verbose announcement:

too verbose

Environment info

No response

Please confirm that you have searched existing issues in the repo.

Yes

Please confirm that you have tested with all plugins deactivated except Gutenberg.

Yes

@afercia afercia added the [Focus] Accessibility (a11y) Changes that impact accessibility and need corresponding review (e.g. markup changes). label Nov 16, 2023
@jordesign jordesign added the [Type] Bug An existing feature does not function as intended label Nov 16, 2023
@alexstine
Copy link
Contributor

@afercia How would you feel about completely eliminating this message? My PR does just that. #56167. We now have progress bar to communicate loading state and the heading structure is much improved for context. I see this as being much less of an issue compared to the beginning of FSE.

@afercia
Copy link
Contributor Author

afercia commented Nov 20, 2023

@alexstine I'm not sure entirely removing these announcements would be good for all users.

We now have progress bar to communicate loading state

I had a look at the progressbar implementation and I doubt it can work correctly as it misses some important attributes like aria-valuenow. Also, when used as a loading indicator, the progressbar should be responsible to set aria-busy on the region that is being loaded. All this is well explained in the spec but I don't see any of that in the current code. Regardless, testing with Safari and VoiceOver, I don't get any progress announcement. We should create an issue to fix the progressbar.

and the heading structure is much improved for context.

Yes that is improved but I'm not sure it is sufficient. When testing #56167 upon navigation the announcement would only tell something about the back button. Something like:

Back, button, Navigation, region

and nothing else, which isn't great, in my opinion.

@alexstine
Copy link
Contributor

I'll make a follow-up to fix Progressbar. I thought we covered everything there but guess not. 😞 Testing in Storybook and site editor produced two different results I suppose.

@alexstine
Copy link
Contributor

@kevin940726 or @youknowriad Can you offer up any ideas on what might be setting incorrect page titles in the site editor?

Make sure the document title always accurately reflects what the current view is.

I traced through the selectors and it looks like it tries to make a guess based off of template name and template type but the home page of the site editor should be neither of those. Need some custom fallback logic? I bet it's getting a default set somewhere and that's what makes it return the wrong page when the proper context can't be found.

@youknowriad
Copy link
Contributor

I think at the moment the useTitle call is within the "Editor" component and is using the title from the useEditedEntityRecord hook. Which means it's showing the title of the parent template for the pages that show "pages within their templates". That's probably causing some issues.

The other thing is that as written today the "title" is guessed from the edited entity in the editor but in a lot of site editor pages, we always show the home page but the sidebar is different (templates, ...) so it makes more sense to tie the "title" to the "routing" instead.

To be honest, the routing as implemented today in the site editor is very basic and adhoc and not well organized. I know @kevin940726 has started some explorations to improve the situations, maybe just a poc for now. But we will solve this properly once we have a solid routing system in place I think.

@alexstine
Copy link
Contributor

@youknowriad Yeah, being able to properly tie the title to the path is likely a better solution going forward. I will not attempt to fix that in my PR, I will simply shorten the title as requested and leave this issue open for reference. Looks like this is going to be a much bigger effort than accessibility alone.

Thanks.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
[Focus] Accessibility (a11y) Changes that impact accessibility and need corresponding review (e.g. markup changes). [Type] Bug An existing feature does not function as intended
Projects
None yet
Development

Successfully merging a pull request may close this issue.

4 participants