Responsive preview icons in Customizer need visible text

[ahortin]

The new icons at the bottom of the Customizer for toggling the preview window of your site really need tooltips to indicate what they're for.

Just like the tooltips on the Visual Editor icons, other icons in the Dashboard should have tooltips as well. As leading usability expert Jakob Nielsen explains;

A user’s understanding of an icon is based on previous experience. Due to the absence of a standard usage for most icons, text labels are necessary to communicate the meaning and reduce ambiguity.

​https://www.nngroup.com/articles/icon-usability/

Even the Google Design Guidelines recommend tooltips for icons
​https://www.google.com/design/spec/components/tooltips.html#

I originally raised this as a post on the ​Beta forum but it was suggested that since it's getting late in the 4.5 release cycle it would be best to raise it as a Trac ticket.

[westonruter]

+1

I personally feel the tooltips would be helpful. The icons aren't totally clear what the buttons do. Here the accessible text is even more clear than the visual icons, I think. Here the visual users need an accessibility aid.

[celloexpressions]

Repeating my comment from Slack:

Because these buttons perform non-destructive actions that are visually obvious when clicked, I think the simplicity of not having tooltips is better. They would certainly become distracting once the user knows what the buttons do, and after using them a few times I would expect most users to remember their purpose. My only concern would be whether users try clicking them in the first place, and that could potentially be solved with a feature pointer or by the specific way it's highlighted on the about page.

I also wouldn't want to attach text to these as the specific buttons are intentionally ambiguous - the previewed sizes are arbitrary and not intended to represent specific devices, only provide a general idea of how the site behaves on different screen sizes.

If appropriately vague text labels could be found, we could look at doing this. I personally feel that the labels there for screen readers are a bit too specific (potentially mis-interpreted) already.

Full conversation: ​https://wordpress.slack.com/archives/core-customize/p1460024296000353.

[ahortin]

@celloexpressions the fact that they're non-destructive is irrelevant. People shouldn't have to click a button to find out what it does. That's the most annoying thing ever. Why is there a tooltip on the Distraction Free Writing icon in the Visual Editor? It's non-desctructive as well. By your way of thinking, this tooltip should be removed also.

You should know what an icon/button does BEFORE you click it. If I'm using an interface and I don't know what a particular button does, I'm less likely to click it at all, just in case it messes up my work. If I don't know what the icon/button does, how do I know if it's non-destructive?

Even though the sizes may be arbitrary, they'd still benefit from having labels like "Mobile view/Tablet view/Desktop view", or something along those lines. They're not device specific and will at least give people an idea of what the icon does.

Also, tooltips don't become distracting once you know what an icon/button does. I refer to the Visual Editor again. I don't find the tooltips on any of those buttons annoying and I've been using them for 10+ years. Once you know what an icon does, you simply click it and move on. Your mouse doesn't tend to hover over it. The tooltip will only display for a microsecond.

[rianrietveld]

Discussed this ticket in the wpa11y meeting:
Adding Tooltips seems like a good idea:
@iamjolly: I really like how GitHub does the icons with aria-label and tooltips.

[iamjolly]

GitHub icons in hover state showing tooltip text

[iamjolly]

GitHub icons with focus showing tooltip and appropriate VoiceOver output for icon

[Cheffheid]

Just to give this a bit of a push forward. I jacked some of the Github code and created a .tooltip class (limited to #customize-controls for now). Would definitely appreciate some design input on these things to help them match the admin look better.

One complication that I'm running into with these CSS-only tooltips is that when one of those buttons is clicked the tooltip sticks around. I think there are JS solutions to fix that (like ​https://marcysutton.com/button-focus-hell/), but I'm a bit too overwhelmed by the amount of Customizer JS to make that change properly.

Will add a patch with what I have so far, which adds the tooltip class CSS and adds the class to the device buttons.

[JoshuaWold]

We just discussed this in our #design triage. As long as the tooltips are created the same way as "tooltips" for the WordPress Gutenberg editor (with accessibility in mind), then it definitely makes sense to include in the Customizer.

Also, the text suggested seems to work well.

[estelaris]

This ticket has had design recommendations from 3 years ago. Can a developer please pick it up from here and add a patch with screenshots to see the patch working

Trac ticket:

The failing tests seem unrelated to the changes made in the PR.

[oglekler]

The tooltip appears below the arrow

[oglekler]

Existing tooltips with JS

[oglekler]

The proposed implementation (PR 8593) has an issue with z-index, but I wonder if this is the right approach because we already have some tooltips, and they are powered by JS and already have some styling (check the screenshots above).

@joedolson What the approach should be taken in general?

[joedolson]

Punting this again.

@oglekler What we'd ideally like to do is implement tooltips using native CSS popovers, but we're waiting on Firefox to complete their implementation.

There are tooltips already, but they're only in the editor, and not readily available. What you're pointing to is just a title attribute, and I don't think there's any JS or custom styling involved there.

[joedolson]

With CSS anchor positioning having meet the basic criteria for ​WordPress browser support, let's go ahead and work on a new patch to get this resolved using native tooltips.

[afercia]

From an accessibility (and usability) perspective, tooltips are anyways a compromise. They don't solve all the problems.

The most accessible apps and software do use both icons and visible labels. Simply because:

• Some users are blind to icons of they don't understand them. They prefer text.
• Some users struggle with text and prefer icons.

From an accessibility perspective, we should establish a principle and that's use bothicons and visible labels, whenever possible.

I'm attaching a screenshot to illustrate a quick experiment I made by editing only the related CSS for these icon buttons.

[wildworks]

As 7.1 Beta1 is approaching, I would like to check the status of this ticket. My understanding is that this ticket depends on #51006, and the mechanism using native tooltips needs to be implemented in the core first.

Trac ticket: https://core.trac.wordpress.org/ticket/36447

## Use of AI Tools

None

[afercia]

In ​https://github.com/WordPress/wordpress-develop/pull/12519 I'm proposing to make the device button labels visible, shortened to:

• Desktop
• Tablet
• Mobile

I'd think the shortened labels are sufficiently clear and there is no need to specify the enter a preview mode.

This approach also aims to establish a few principles:

• Tooltips are a compromise anyways. Visible labels should always be preferred wherever possible.
• The most accessible web and desktop applications do use a combination of icon + visible label to take into account the widest spectrum of user needs.

The existing layout and CSS already take into account longer translations. When the 'Hide controls' label or the buttons labels are longer than in English, the layout doesn't break. See attached screenshot.

@joedolson if you think this approach is acceptable, I would suggest to merge this enhancement soon. The only doubt I have is that the label text size must necessarily be pretty small.

To test:

• Set Twenty Twenty-One as the active theme.
• Access the Customizer and observe the device preview buttons at the bottom of the left panel.
• Same in a Theme preview from WP Admin > Appearance > Themes > Live Preview

[joedolson]

These controls are fairly large already, so having room for that switching makes sense to me. Visible labels are definitely preferred, and less distracting than adding tooltips.

I agree with you that the very small text isn't great, but the words are common and supported by associated images, so the text isn't really *critical*. And given that these controls haven't had any visible text up to now, it's a clear improvement over what's already there.

I also agree with simplifying the labels; all of that extra verbiage to describe what the buttons do should be clear from context, especially given how common responsive controls are at this point.

The only change I think I'd consider is switching div class="devices-wrapper" to have role="menu" and an aria-label for context. I can push that change up.

[joedolson]

I'm reconsider role="menu"; I think just marking as a group is sufficient. I don't think we want to go to the extensive changes required to change the keyboard navigation.

[joedolson]

With the addition of the group role, I think that the context is sufficient, and this is commit-ready.

[joedolson]

In 62745:

Customize: Add visible text on responsive view switches.

Add a visible text label on the Customizer's responsive view switches. While the text is very small, it serves to supplement the icons to help more readily comprehend the purpose of these controls. Consolidate the labels so the visible label matches the accessible name of the control for voice command users, and add a group role with aria-label to provide improved context for screen reader users.

Developed in ​https://github.com/WordPress/wordpress-develop/pull/12519

Props ahortin, iamjolly, cheffheid, oglekler, afercia, abcd95, westonruter, celloexpressions, rianrietveld, joshuawold, estelaris, mukesh27, joedolson, wildworks.
Fixes #36447.