Block Toolbar: Screen readers do not correctly read descriptions of focused elements

[t-hamano]

Description

Issues discovered in this comment: #61168 (comment)

For example, NVDA reads the element's label, role, and description when an element is focused. However, for focusable elements in the block toolbar, it does speak the description of the previously focused element, and in my testing, it appears to speak the focused element's label twice.

Users who use screen readers will be very confused because the read-out label and description do not match.

According to this comment, it seems that this issue first appeared in Gutenberg 19.2. Also, since this issue also occurs in WordPress 6.7 Beta1, it is necessary to identify the commit that caused the problem and fix it within the 6.7 cycle.

Step-by-step reproduction instructions

Below are the test steps when using Windows OS and NVDA.

WordPress 6.6.2

Everything is read correctly. In my testing, the screen reader basically reads out the label, role and description of the focused element.

• Open the post editor.
• Insert two Paragraph blocks.
• Select the First paragraph block.
• Press Shift+Tab to focus the block switcher button in the block toolbar. the screen reader should read:

  Edit Post “Test” ‹ gutenberg — WordPress  document   
  main landmark
  Editor content  region
  Block tools  tool bar
  Paragraph  menu button  collapsed  subMenu  Change block type or style
  

• Press the right arrow key to focus the "Move up" button. The screen reader should read:

  Move up  button  unavailable  Block Paragraph is at the beginning of the content and can’t be moved up
  

• Press the right arrow key to focus the "Move down" button. The screen reader should read:

  Move down  button  Move Paragraph block from position 1 down to position 2
  

• Press the right arrow key to focus the "Align text" button. The screen reader should read:

  Align text  menu button  collapsed  subMenu  Change text alignment
  

WordPres 6.7 Beta1 or Gutenberg 19.4.0-rc.1

All of these are incorrect. In my testing, screen readers read a description of the previously focused element, the label of the focused element, the role of the focused element and the label of the focused element.

• Open the post editor.
• Insert two Paragraph blocks.
• Select the First paragraph block.
• Press Shift+Tab to focus the block switcher button in the block toolbar. the screen reader should read:

  Edit Post “Test” ‹ gutenberg — WordPress  document   
  main landmark
  Editor content  region
  Block tools  tool bar
  Paragraph  menu button  collapsed  subMenu
  Paragraph
  

• Press the right arrow key to focus the "Move up" button. The screen reader should read:

  Change block type or style
  Move up  button  unavailable
  Move up
  

• Press the right arrow key to focus the "Move down" button. The screen reader should read:

  Block Paragraph is at the beginning of the content and can’t be moved up
  Move down  button
  Move down
  

• Press the right arrow key to focus the "Align text" button. The screen reader should read:

  Move Paragraph block from position 1 down to position 2
  Align text  menu button  collapsed  subMenu
  Align text
  

Screenshots, screen recording, code snippet

No response

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

[t-hamano]

@talksina, If there are any other issues I've missed, I'd be grateful if you could add them.

@joedolson @afercia, I can't test on MacOS, so I'd appreciate it if you could test if this issue occurs with VoiceOver as well.

[t-hamano]

After investigating using git bisect, I found that this problem was caused by #64066.

@WordPress/gutenberg-components Do you have any good ideas to solve this? I suspect something about this code might be affecting it.

[t-hamano]

I also noticed that even outside of the block toolbar, buttons with tooltips changed what my screen reader announced when they received focus.

For example, if I focus on the "Toggle block inserter", "Tools", "Undo", "Redo", "Document overview" buttons in the post editor header in that order, my screen reader reads them as follows:

Before #64066

Toggle block inserter  toggle button  not pressed  collapsed

Tools  menu button  collapsed  subMenu

Undo  button  unavailable

Redo  button  unavailable

Document Overview  toggle button  not pressed  collapsed

After #64066

Toggle block inserter  toggle button  not pressed  collapsed
Toggle block inserter

Tools  menu button  collapsed  subMenu
Tools

Undo  button  unavailable UndoCtrl+Z

Redo  button  unavailable  RedoCtrl+Y

Document Overview  toggle button  not pressed  collapsed  Document OverviewShift+Alt+O

In addition to the aria-label text, the tooltip text also appears to be spoken.

[ciampo]

I haven't look too much in details, but the code that you highlighted seems to be doing the right thing — ie. adding a aria-describedby attribute, so that the anchor of the tooltip is described by the tooltip's text.

Also, for additonal context, this change on our side was necessary because arikit stopped adding the aria-describedby attribute to its tooltips — the code changes that you highlighted are a patch on our side to preserve that same behaviour while we decided if the resons why ariakit removed this feature should be considered in our component as well.

cc @DaniGuardiola who worked on this change, and @diegohaz in case he can spot anything missing from our patch which could cause this change in what the screen reader announces.

[DaniGuardiola]

That's correct @ciampo, and I think we more or less agreed to remove it but patch it to keep the impact of the upgrade relatively small. I think we could take a similar route to what we did with button sizes and introduce a __next prop, then progressively opt into the new behavior making any appropriate changes that retain accessibility.

[t-hamano]

Thank you for your feedback.

However, it is true that there is an issue with screen readers not reading element labels and descriptions correctly, at least with NVDA.

For example, I added the following story about the Button component:

Details

export const MultipleIcons = () => {
	return (
		<>
			<Button
				icon={ formatBold }
				label="Bold"
				description="Bold icon description"
			/>
			<Button
				icon={ formatItalic }
				label="Italic"
				description="Italic icon description"
			/>
			<Button
				icon={ link }
				label="Link"
				description="Link icon description"
			/>
		</>
	);
};

When I use the tab key to focus through the buttons, I hear:

(Focus the Bold button)

Bold button

(Focus the Italic button)

Bold icon description
Italic button

(Focus the Link button)

Italic icon description

Link button

Video recording of the test:

actual.mp4

I can see that the description, i.e. the aria-describedby text, is not being read out correctly.

Before #64066, it was read out as follows, which I believe is the correct reading:

(Focus the Bold button)

Bold  button  Bold icon description

(Focus the Italic button)

Italic  button  Italic icon description

(Focus the Link button)

Link  button  Link icon description

Video recording of the test:

expected.mp4

I would appreciate it if you could confirm if this issue occurs with VoiceOver as well.

[talksina]

with JAWS it's the same. I would expect it to read command, description and keyboard shortcut - maybe description and keyboard shortcut should appear in the control's "title" attribute? I'm not a coder unfortunately but what I know is that before Gutenberg 19.2 the issue wasn't there. Elena Brescacin - Accessibility, WordPress, HIV awareness E-Mail: ***@***.*** MOBILE: +39 328 7483161 LINK: ***@***.*** <https://linktr.ee/ilmondopositivo> Il giorno sab 5 ott 2024 alle 16:38 Aki Hamano ***@***.***> ha scritto:

…

Thank you for your feedback. However, it is true that there is an issue with screen readers not reading element labels and descriptions correctly, at least with NVDA. For example, I added the following story about the Button component: Details export const MultipleIcons = () => { return ( <> <Button icon={ formatBold } label="Bold" description="Bold icon description" /> <Button icon={ formatItalic } label="Italic" description="Italic icon description" /> <Button icon={ link } label="Link" description="Link icon description" /> </> );}; When I use the tab key to focus through the buttons, I hear: (Focus the Bold button) Bold button (Focus the Italic button) Bold icon description Italic button (Focus the Link button) Italic icon description Link button Video recording of the test: https://github.com/user-attachments/assets/e47492c7-7e4e-47e7-ac94-82ec8e7cd192 I can see that the description, i.e. the aria-describedby text, is not being read out correctly. Before #64066 <#64066>, it was read out as follows, which I believe is the correct reading: (Focus the Bold button) Bold button Bold icon description (Focus the Italic button) Italic button Italic icon description (Focus the Link button) Link button Link icon description Video recording of the test: https://github.com/user-attachments/assets/793f650c-4f8b-4786-9ae5-2fe13e4ee1de I would appreciate it if you could confirm if this issue occurs with VoiceOver as well. — Reply to this email directly, view it on GitHub <#65888 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ADT5KDURNPZA4PX3WSUTTO3ZZ72VTAVCNFSM6AAAAABPM6ZHJWVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDGOJVGA3TSMJVHE> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[joedolson]

Confirmed this is also happening on VoiceOver.

I looked at what's happening, and the aria-describedby value is changing dynamically when the tooltip is present. If the tooltip is present, the aria-describedby refers to the tooltip; if it isn't, it refers to the description. Since the tooltip is triggered when the component receives focus, the description used is not the right one.

The tooltip is usually the accessible name of the control; as such, it should be in the aria-label (which it is), and not also duplicated by the aria-description. There may be cases where we're using tooltips for additional information, but in most cases it's just the name of the control. I'd only render an aria-description if the text used is not the same as the value used in the aria-label.

[DaniGuardiola]

@joedolson that could be a way to improve the patch while we figure out how to transition away from it.

[t-hamano]

The important thing to note is that this issue also occurs in WP 6.7.

[diegohaz]

@diegohaz in case he can spot anything missing from our patch which could cause this change in what the screen reader announces.

How can I test WordPres 6.7 Beta1 or Gutenberg 19.4.0-rc.1? I tried https://wordpress.github.io/gutenberg and https://gutenberg.run, but I couldn't reproduce the issue using Safari and VoiceOver. I can try NVDA on Windows later, but I'm afraid I'm not using the correct version.

[t-hamano]

@diegohaz You can use the Playground to test WP 6.7 Beta1: https://playground.wordpress.net/?php=8.0&wp=beta