Tools panel: avoid unnecessary mismatch between visible label and accessible name

Description

In the Tools panel, the aria-label attributes for the elements that are shown / hidden and reset mismatch the visible text. As such, this is a mismatch between vissual label and actual accessible bane that is a barrier for some users.

This kind of mismatch should always be avoided. For example:

The visibele text is H2.
The actual accessible name is either Show H2 or Hide and reset H2.
This is:
- Confusing for sighted screen reader users.
- An actual barrier for speech recognition / voice control users.

Worth also reminding the label of a control i.e. its accessible name is not the right place to communicate states or values.

gutenberg/packages/components/src/tools-panel/tools-panel-header/component.tsx

Lines 101 to 111 in b1c9676

    
           const itemLabel = isSelected 
        
           	? sprintf( 
        
           			// translators: %s: The name of the control being hidden and reset e.g. "Padding". 
        
           			__( 'Hide and reset %s' ), 
        
           			label 
        
           	  ) 
        
           	: sprintf( 
        
           			// translators: %s: The name of the control to display e.g. "Padding". 
        
           			__( 'Show %s' ), 
        
           			label 
        
           	  );

Step-by-step reproduction instructions

Go, for example, to Site Editor > Styles > Colors > Elements > Elements options (the ellipsis icon button)
Open the Elements options popover.
Observe the toggleable items in the menu have a visible text like H1, H2, etc.
Observe the aria-label of these items is either Show H1, Show H2, etc. or Hide and reset H1, Hide and reset H2, etc. depending on the state.

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

I would argue that also from a visual design perspective, the entire tools panel purpose and functionality isn't clear.

The ellipsis button toggle that opens the popover is labeled Elements options.
The Menu within the Popover has a visible title Elements.
However, its actual aria-label is aria-label="Elements options" so this is one more mismatch between visible label and accessible name.
The first Group within the menu is labeled Elements via an aria-labelledby="components-menu-group-label-1" which just adds more confusion.
There's no visible text or any label or description that actually explains this menu is meant to toggle the visibility of the elements available in the main panel.

As a user, I'd only understand what this menu is about only after I try to use it and _only if I'm able to notice that new items appear or are removed from the main panel. To me, any UI should be self-explanatory instead of forcing users to 'try and discover' to learn how it works.

Shouldn't the aria-label be removed? The button has a visible text.

This was fixed by #84341. Each menu item now starts with the name you see, for example "H2, show" or "H2, hide and reset". Closing, but feel free to reopen if you find a case that still doesn't match.

Navigation Menu

Repository navigation

Tools panel: avoid unnecessary mismatch between visible label and accessible name #65241

Description

Step-by-step reproduction instructions

Screenshots, screen recording, code snippet

Environment info

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

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

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

	const itemLabel = isSelected
	? sprintf(
	// translators: %s: The name of the control being hidden and reset e.g. "Padding".
	__( 'Hide and reset %s' ),
	label
	)
	: sprintf(
	// translators: %s: The name of the control to display e.g. "Padding".
	__( 'Show %s' ),
	label
	);

Tools panel: avoid unnecessary mismatch between visible label and accessible name #65241

Description

Description

Step-by-step reproduction instructions

Screenshots, screen recording, code snippet

Environment info

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

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

Activity

afercia commented on Sep 11, 2024

carolinan commented on Apr 12, 2025

aaronrobertshaw commented on Oct 23, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions