Audit and improve ToolsPanel's a11y

[apeatling]

(semantics, focus management, announcing changes to screen reader users)

[ciampo]

@afercia @joedolson @WordPress/gutenberg-components @aaronrobertshaw in the context of looking to stabilize the component, is there any feedback that you'd like to share?

[afercia]

Besides the genereal considerations i reported on #67954, from an a11y perspective I would like to see a few points to be considered:

1. This component is an ARIA menu. As such, I would like to see the component enforce via code, or at the very least have some linting, to only allow the children expected in an ARIA menu. See similar issue for DropdownMenu Enforce DropdownMenu to follow the ARIA menu pattern or add linting to make sure it does #67795
2. It should not use an ellipsis icon. This icon has inherent problems as it's little visible for low vision users. See Make the ellipsis button more visible #61909. More importantly, the concept of the ellipsis icon is 'more' but the editor is extending this icon usage to many other concepts and I'm not sure that's ideal. This component is about toggling the visibility of settings. It should be identified with an icon related to settings.
3. The labeling of the menuitems when the 'reset' action is available should be improved. The visible text mismatches the actual aria label, as the order of the words is different. E.g.

• Visible text: Block spacing RESET
• Aria label: Reset Block spacing

4. The strings for the speak message __( '%s reset to default' ), __( '%s hidden and reset to default' ), __( '%s is now visible' ) don't follow the WordPress best practices for l10n. In gendered languages, the name of a setting may be masculine or feminine and the adjectives like 'hidden' and 'reset' can't be translated correctly when the gender is unknown.

Screenshot of mismatching visible text and accessible name:

[joedolson]

I'll second @afercia's comments. In regards to point 3, referring to the usage of aria-label, I'd go a bit further and say that we really need some kind of control over when aria-label is used; this is a completely unnecessary usage of of the attribute, as the visible text of these buttons is completely adequate to convey what they do. All aria-label does in this case is introduce the potential for a WCAG 2.5.3 violation, and introduce the probability of best practice problems with mismatched text, as cited by Andrea above.

In my opinion, if a control has a visible text label, it should not have an aria-label unless there is a very strong reason that this control needs additional explanation.

[afercia]

unless there is a very strong reason that this control needs additional explanation

To further clarify: any 'explanation' as in: a description, should not be used for labeling. A description should be separated and be part of the accessible description. Instead, a label is determines the accessible name, which is what the control is about. It's the what the control does. In some cases, the what can be expanded a little but longer descriptions or explanations should go in a description.

[ciampo]

Thank you both for replying!

This component is an ARIA menu. As such, I would like to see the component enforce via code, or at the very least have some linting, to only allow the children expected in an ARIA menu

This shouldn't be the case in ToolsPanel since all menu items are added internally by the component itself.

It should not use an ellipsis icon. [...] the concept of the ellipsis icon is 'more' but the editor is extending this icon usage to many other concepts and I'm not sure that's ideal. This component is about toggling the visibility of settings. It should be identified with an icon related to settings.

This should be an easy change if/once we identity a better icon (cc @WordPress/gutenberg-design for feedback)

The labeling of the menuitems when the 'reset' action is available should be improved.

Do I understand correctly that the labels in this care are redundant and that removing them would solve the issue?

The strings for the speak message __( '%s reset to default' ), __( '%s hidden and reset to default' ), __( '%s is now visible' ) don't follow the WordPress best practices for l10n. In gendered languages, the name of a setting may be masculine or feminine and the adjectives like 'hidden' and 'reset' can't be translated correctly when the gender is unknown.

What about tweaking the label to "the %s value was ..." ? Or any other way where "%s" stops being the subject, so that we avoid the issue about the gender/

[jameskoster]

I don't think we ever landed on the perfect design for resetting. It's a bit strange how the 'Reset' text takes the place of the checkmark glyph and is made to look like a discrete interactive element. Additionally "Reset Block spacing" reads much better (in English at least) than "Block spacing RESET".

That said, if we change the menu item label to "Reset Block spacing" the appearance is going to be confusing by virtue of the adjacent checkmark... "Reset Block spacing ✅".

Probably not a popular idea, but I wonder if these should be separate menus. One about toggling tools, and another for resetting them.

[jasmussen]

Connecting some dots with @juanfra who I believe recently added a reset button for color Items directly in the Item itself.

[afercia]

Probably not a popular idea, but I wonder if these should be separate menus

Personally, I'd encourage to explore a separation between toggling and reset as I think it's one of the main sources of confusion in this UI.

[jameskoster]

Connecting some dots with @juanfra who I believe recently added a reset button for color Items directly in the Item itself.

Placing the reset affordance in close proximity to the associated control is a part of the proposal in #49278 (see 'Local overrides' section):

[juanfra]

Connecting some dots with @juanfra, who I believe recently added a reset button for color items directly within the item itself.

One thing that came up during implementation was the importance of ensuring that focus isn’t lost. Sometimes, icons for resetting values can be in specific locations and may disappear after being actioned, which could lead to a11y/focus issues.

From a usability and intuitiveness standpoint, I believe consistency is key. It’s essential to define clear wording and iconography and apply them consistently wherever we offer the same action.

[ciampo]

I also agree that separating toggling from resetting controls feels like an improvement, although I'm not sure I like having the dropdown menu toggle inline with the input's label.

Alternatively, we could take inspiration from #41546 and have a custom dialog with a close button and a custom UI (TBD) to more clearly toggle and/or reset items.

[richtabor]

Probably not a popular idea, but I wonder if these should be separate menus. One about toggling tools, and another for resetting them.

I don't think we should introduce more icons/UI if possible. The controls are already a lot to digest as is.

[richtabor]

I also agree that separating toggling from resetting controls feels like an improvement

I'm not confident in this. If you toggle off a control, the expectation is that it is no longer applied, therefore "reset."

If these concerns are separate, you could end up with a control not visible, but still have its values reflected in the block, correct?

[ciampo]

I guess the interactions that we're interested in implementing are:

• when a control is visible (and can be hidden): "hide and reset" and "reset"
• when a control is visible (and can't be hidden): "reset"
• when a control is hidden: "show"

Listing all possible combinations may help us to find the right UX

[jameskoster]

The controls are already a lot to digest as is.

I think it's really a question of where the digestion occurs. Currently all the flows @ciampo outlined above are bundled into single a menu which seems simpler on the surface, but can lead to some confusing scenarios (see discussion in #67954). This will get worse as #67813 is implemented.

There are some smaller trade-offs too, like forcing us to use strange labels e.g. "Block spacing RESET", the knock-on effect of which is including arguably unnecessary clarification aria-labels e.g. "Reset Block spacing".

I'm all for keeping the resting UI as clean as possible. But I think this is a scenario where a bit more UI might actually be helpful. For instance the 'Reset' menu trigger would only appear when the panel contains local overrides; which actually goes a small way to visualising the hierarchy of styles (#49278)—users can tell at-a-glance whether or not a panel contains overrides rather than having to check the ellipsis menu. A bit similar to the 'Detach' button in Figma, which only appears when using variables: