Improve : showTooltip documentation

[Vrishabhsk]

What?

• Improve README.md for components that have showTooltip prop.

Why?

• Improve documentation of the showTooltip prop in various components #66523

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: Vrishabhsk <[email protected]>
Co-authored-by: mirka <[email protected]>
Co-authored-by: afercia <[email protected]>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[afercia]

Thanks for your PR!

• Tooltips should provide additional, helpful information beyond what's visible on the screen.
• For users relying on screen readers, ensure that the tooltip content complements rather than duplicates the component's accessible name or visible text.

Actually, that's not the recommended usage for tooltips.
Tooltips have been originally implemented for the specific purpose of visually exposing the label (the accessible name) of icon buttons. Later on, their usage became a little inconsistent and they have been used also for additional information like descriptions. There is an ongoing effort to review all these cases inappropriate usage. As such, it would be good to document clearly that:

• Tooltips must be used only to visually expose the label of controls that don't show visible text.
• Tooltips usage must take into account the showIconLabels preference: when enabled ant the control shows visible text, the tooltip must be disabled.

[Vrishabhsk]

Hi @afercia 👋

I have updated the docs as per your recommendation. Thanks

[afercia]

Thanks @Vrishabhsk it looks good to me. I'd appreciate a review from @WordPress/gutenberg-components

[mirka]

@afercia I have some questions about this.

Tooltips must be used only to visually expose the label of controls that don't show visible text.

This kind of makes to me, but then there are cases like this With Tooltip example for ToggleGroupControl. Is this acceptable or not? Does it matter whether something like "A→Z" (or "AB"/"Ab" for capitalization) is rendered as a string or an icon? Maybe there is a way to rephrase this guidance because currently the "why" is unclear.

Tooltips usage must take into account the showIconLabels preference

As discussed in #61763, we have the conundrum where showIconLabels is not a wp-components feature. This guidance can't really belong here, and to be honest I think it is unrealistic to expect all devs (first and third-party) to know about and test for the showIconLabels feature. I thought the showIconLabels feature was intended to be something that "just works". If it's not, then we need to bake that feature in at the component level. Have we considered ways to automate this consideration about the redundant tooltips in showIconLabels mode?

[afercia]

there are cases like this With Tooltip example for ToggleGroupControl. Is this acceptable or not?

No, that is not acceptable because it introduces a mismatch between the visible text and the accessible name. As explained several times, that is a barrier for sighted screen reader users, voice control / speech recognition users etc. Also, it's a violation of WCAG Label in Name.

That kind of usege of tooltip is closer to the old, deprecated, usage of the title attribute to 'expand' soem information or add descriptions.

If it's not, then we need to bake that feature in at the component level. Have we considered ways to automate this consideration about the redundant tooltips in showIconLabels mode?

That's the reason why I opened #61763 6 months ago, still no great progress though. I understand the approach I proposed in #61824 may be not ideal and I'm totally open to better options.

I'd like to remind again that buttons that only show an icon are a problem for accessibility. We need to provide consnistent ways to make them accessible. Also, it's pretty common on operating systems and apps to have option to display:

• Icon + text
• Only icon
• Only text

All the 3 options have advantages for specific users needs. For example, only icon may help users with dyslexia but they are not accessible for other users. The only way to solve this long standing issue is to make sure any design provides a design for this preference as well and clearly document why.

[mirka]

No, that is not acceptable because it introduces a mismatch between the visible text and the accessible name.

On the contrary, wouldn't something like "A→Z" be what the WCAG clarifies as being "symbolic text characters", rather than "expressing something in human language"? It would be the same as if "A→Z" were an icon image. These are not considered "visible labels", so the tooltip is only exposing the accessible name of the button, just as it would for an icon button.

For example, would a rephrasing like the following work? Does it capture the intent of why this guideline is in place?

"Tooltips must be used only for visually exposing the accessible name of controls where the accessible name is not clear in the default visual state. The tooltip must not be used to convey additional information (such as usage hints) about the control."

And then we could accompany that with a pair of Do and Don't examples (cc @auareyou @juanbuis who are working on improving docs). It may also be useful add a recommended pattern for conveying additional information about the control, instead of using a tooltip.

[mirka]

How about we discuss the showIconLabels part of the problem as a separate issue? That in itself is a pretty big topic, and much harder to address than the general tooltip usage guidance.

[afercia]

On the contrary, wouldn't something like "A→Z" be what the WCAG clarifies as being "symbolic text characters", rather than "expressing something in human language"? It would be the same as if "A→Z" were an icon image. These are not considered "visible labels", so the tooltip is only exposing the accessible name of the button, just as it would for an icon button.

Well, as the WRC explain that may be considered 'Images of Text'. When images contain text, their alt attribute must be the represented text. Similarly, if we consider this case as equivalent to an image, then the accessible name should be A→Z which also meets Label in Name.

Anyways, I see many don't understand well the consequences of a mismatch between the visible label and the actual accessible name. I would encourage anyone to use Voice Control (on macOS) or other speech recognition software and try to activate any control where the visible label mismatches the accessible name.

[mirka]

Similarly, if we consider this case as equivalent to an image, then the accessible name should be A→Z which also meets Label in Name.

This isn't consistent with the fact that we use "images of text with symbolic text characters" such as "B" or "H2", which have an accessible name of "Bold" (for text style) or "Change level" (for headings). And to be clear I'm not arguing about specific cases, but rather that we should figure out the appropriate verbiage to issue this accessibility guidance in our documentation.

The original verbiage "Tooltips must be used only to visually expose the label of controls that don't show visible text" does not cover the symbolic text characters case. My suggested tweak "Tooltips must be used only for visually exposing the accessible name of controls where the accessible name is not clear in the default visual state" aims to be generic enough to cover those cases.

[afercia]

This isn't consistent with the fact that we use "images of text with symbolic text characters" such as "B" or "H2", which have an accessible name of "Bold" (for text style) or "Change level" (for headings).

I would argue that the "Change level" example isn't the best example as 1. the symolic text is dynamic 2. it is used to communicat ethe selected vallue and not the function.

Regardless: the proposed text:

"Tooltips must be used only for visually exposing the accessible name of controls where the accessible name is not clear in the default visual state"

isn't ideal because it doesn't make clear that when a control already has visible text that matches the accessible name, tooltips must not be used.

I wouldn't be opposed to expand the documentation with a few examples in the 'usage' or 'best practices' sections.