Please add hover text to commonly used icons - gear, vertical ellipsis (kebab)

[dayleparker]

Summary: The documentation team for the Red Hat Hybrid Cloud Console would like to request a tooltip on a few icons commonly used in the Hybrid Cloud Console - in particular, the gear icon, and the vertical ellipsis (“kebab”) icon.

Details:

• We suggest “Settings” as the tooltip label for the gear icon
• We suggest “More options” as the tooltip label for the ellipsis (also see discussion in https://issues.redhat.com/browse/MGDX-331 )

Background/rationale: Currently, documenting a navigation path in a procedure can be difficult and prone to inconsistency across services as there’s no agreed-upon name for these icons in the console.

The docs team has used a few workarounds to try to direct users to the correct place in the console – one is to use a small icon image and a name for the image. Including an image poses some problems with docs tooling, and the label we should use for the icon has never been made completely official, so this was always seen as a temporary solution. A text label on the icon would also improve accessibility, as screen readers could read this in the docs and in PatternFly UIs. When writing docs for the console, we will be consistent with a name, (and not require an image in the docs to describe it) and we can provide a better user experience.

Additional info: This was discussed in the PatternFly dev office hours on March 15. There was discussion by the development team that one way of doing this is to implement a ‘recommended tooltip’ in the React component groups.

A consideration mentioned is that some icons are used in different ways - while the gear is always (or at least always in the Hybrid Cloud Console?) Settings, the ellipsis might be used for different purposes, so attaching a tooltip for “More options” might or might not be as straightforward. If this is the case, perhaps the ellipsis could have a recommended tooltip of “More options”, but could be editable if the icon is used for a different purpose.

To provide an example that comes to mind where the ellipsis isn’t ‘More options’ really - in User Access in the Hybrid Cloud Console, in Groups > Roles, you select roles you want to edit, and then you must click the ‘More options’ icon at the top of the roles list to reveal the ‘Remove’ option (the only option here). Perhaps that could be replaced by a button or hover text if needed that says “Remove roles” instead of a ‘More options’ - but that’s probably a Hybrid Cloud Console design discussion and has other reasons for being the way it is.

Screenshot:

Related info:

• See examples of how different docs sets have handled these icons in Hybrid Cloud Console docs terminology & style examples - not an exhaustive study, and we are working on making these the same across docs sets.

[mcarrano]

@mmenestr @andrew-ronaldson @edonehoo This issues came out of a discussion at the PF Office Hours on Wednesday. From a capability standpoint, there's no reason we can't have tooltips on these buttons. However it's also true that we don't really have any standards for this. If we were to agree of standard tooltips for common actions as requested here, any thoughts about the best place to document that?

[abigaeljamie]

@mcarrano , I've worked with the Docs team in the past to document tooltip labels on PatternFly's "Icons" page: https://www.patternfly.org/v4/guidelines/icons

Any icons with standard tooltip labels (such as the kebab/ellipses) have the tooltip label documented in the "Usage/tooltip" column.

[mcarrano]

Thanks @abigaeljamie .

@dayleparker does this give you what you need? Is there a way we can make this more discoverable/findable?

[jgiardino]

I think the problem with the current documentation is there is no way to provide a link directly to the recommendation when we need to be able to reference PF recommendations. With this type of recommendation, I'm not sure what the best approach is. Should the terminology page be updated to be a "Terminology and tooltips" page and include tooltips like this?

The other problem is that most designers don't go to this level of detail in designs. They're usually just showing a view with a kebab on items. The developers will then copy the react example code to use as a starting point. Having PF recommendations baked into PF react examples would go a long way toward getting PF design recommendations adopted.

[mcarrano]

@jgiardino Yes, I can understand how this guidance can be hard to find if it only lives in the Icons table. I think the question becomes where would people most likely look for this? Perhaps UX writing is a good location. The recommendations could also be added to the Tooltip component guidelines here: https://www.patternfly.org/v4/components/tooltip/design-guidelines Or we could add a new page somewhere. Curious to hear other's thoughts.

Also agree that it would help to bake these recommended tooltips into our examples and demos. But as you know, there are a lot of them and it will be hard to touch them all. Are there specific examples that would most benefit from having standard tooltips added?

[abigaeljamie]

+1 to moving these labels out of the icons chart and onto a page that is easier to find and navigate. I like the idea of either adding "Tooltip labels" to the "Terminology" page of the UX writing style guide OR adding a new page to the UX writing style guide entitled "Tooltip labels" so that it gets its own page in the nav under "UX writing." Thoughts?

[dayleparker]

Thanks for these links, everyone! I didn't realize that everything that we need to implement this in the Red Hat Hybrid Cloud Console is already documented clearly in the terminology and tooltip design guidelines pages. Which is amazing!

I like the idea of having certain tooltips baked in, as @mcarrano says. From the projects I've worked on in the console over the last few years, Settings and More options have been the most problematic to document in procedures. I'd suggest 'baking in' these tooltips at minimum (from the 14 tooltips I found in https://www.patternfly.org/v4/guidelines/icons/). I can poll other docs people to see if any of the others have caused user confusion/trouble with documentation.

@abigaeljamie I like your ideas! I think a new page in the UX writing guide would get the most visibility. But adding on @jgiardino's comment - will the developers read this and implement the tooltip if it's available (but not baked in)? Where do developers look when implementing a React component?

In the meantime, I think there's a need to see if the Hybrid Cloud Console would consider implementing some of these tooltips, so I created an issue on that project that I will follow.

[abigaeljamie]

@dayleparker Baked-in definitely sounds like the way to go as far as dev implementation 👍 In addition to baking them in, I was thinking about how to increase their visibility/findability among designers and any content creators — the existing labels are a little hard to find right now buried in the icons table. Having a separate page for them might be easier for folks to find if they're writing any content that refers to the icons (and then having them baked in on top of that will take care of the labeling in the UI).

[jgiardino]

@mcarrano - Following discussion in https://issues.redhat.com/browse/MGDX-331, it sounds like the PF table component doesn't currently support tooltips on the kebab. Is this a known issue? Even if design guidelines are updated per this issue, product teams would be blocked from following this guidance.

[mcarrano]

@jgiardino I'm not aware of this restriction. @nicolethoen is it true that tooltips cannot be applied to actions within a table? Do you know why that's the case?

[nicolethoen]

Tooltips can be placed on the actions within a table's actions menu, but it's possible a tooltip can cannot be placed on the kebab toggle of the actions menu. I'll take a peek now.

[nicolethoen]

Here is a codesandbox demonstrating how to define a customActionsToggle to add a tooltip to the a kebab style actions menu on a composable table: https://codesandbox.io/s/table-custom-actions-toggle-with-tooltip-5ie401

Here is one demonstrating how to do it using the legacy table: https://codesandbox.io/s/deprecated-table-custom-actions-menu-toggle-with-tooltip-sych48

The consumer will definitely need to define a custom actions menu toggle as is done in both code sandboxes, since the actions menu is dynamically built by the Table component - so including a tooltip is not part of the original feature set.

[jgiardino]

Thanks for looking into this, @nicolethoen. Adding @riccardo-forina for awareness.

@mcarrano to follow up on your question above:

Also agree that it would help to bake these recommended tooltips into our examples and demos. But as you know, there are a lot of them and it will be hard to touch them all. Are there specific examples that would most benefit from having standard tooltips added?

It looks like there are only a handful of non-legacy examples that use the kebab. Given what Nicole described above, it sounds like this could be challenging to update existing table component examples to follow these recommendations, since it's not a matter of just applying a prop with this tooltip label. But it would be ideal to have at least one example that illustrates how PF design guidelines can be supported.

One suggestion is to update the Composable: Actions example to include a new toggle "Actions toggle with tooltip" as the default option, and also include a note with this example that links to the design guidelines explaining why this is the recommended method when using a kebab for the toggle.

I do however question if it's normal to have PF react examples that aren't capable of supporting design guidelines. For example, should we even show the "Default actions toggle" as part of this example if it can't support the design guidelines we recommend.

[nicolethoen]

Once/if this suggestion if officially incorporated into the PF design guidelines, we can update our examples to follow our own guidelines for sure. And i'd suggest that (especially for the case of the actions menu in a table) we consider updating the tooltip delay timer to be more than 300 milliseconds as is the default time for most tooltips.

[jgiardino]

I was rereading this discussion thread and had a question about this comment:

Once/if this suggestion if officially incorporated into the PF design guidelines, we can update our examples to follow our own guidelines for sure.

In a previous comment, @abigaeljamie noted that we do have this recommendation provided in patternfly.org (see example below). The issue that I raised above is that there is no way to provide a direct link to that recommendation. But my understanding is that the way it's currently documented still qualifies as a PF design guideline. So I'm wondering if this patternfly-design issue really is a blocker to updating our PF react examples?

[nicolethoen]

That's fair - might be worth an audit on all those icons to see if we implement the tooltips as mentioned in that table across our docs. I'd imagine we don't.

[pankajshivpuje]

@andrew-ronaldson Upon reviewing all the comments in the thread and discussion during the PF design meeting, I am recommending that we close this issue with following recommendations:

• Current PF icons page provides guidance on the standard tooltip options.
• For icons Gear (Unicode#f013) recommended tooltip is 'Settings' and for Ellipses icons (Unicode#142) recommended tooltip is 'More options'.
• @dayleparker has a pending issue on the ConsoleDot for implementation.

Here are the following issues/pain points that still need to addressed from the documentation and discoverability perspective:

• PF recommended standard tooltips for commonly used icons/buttons are not easily discoverable on the PF site
• There is no way to provide a link directly to the recommendation when we need to be able to reference PF recommendations for tooltips.
• There are no react examples of the standard tooltips
• Standard tooltips are not baked-in for development

Based on the review in PF design meetings, following issues/pain points have come up:

• Tooltips and popovers can be confused with each other due to its design and affordance and are used interchangeably used with mix and match of colors and actions. (RHTAP's current implementation)
• No guidance or standards on the actual text that can be used as tooltip vs in the popover

My recommendation would be to close the original issue #1246 and open one issue addressing discoverability of the PF recommended tooltips and another issue to address design issues. I am happy to pursue this if it works for you.

[jgiardino]

Thanks for this summary, @pankajshivpuje. Regarding this note:

• No guidance or standards on the actual text that can be used as tooltip vs in the popover

There are some guidelines on when to use tooltips vs popovers in the design guidelines for both components. For example, here's the link to the section in the popover design guidelines: https://www.patternfly.org/v4/components/popover/design-guidelines#when-to-use-tooltips-vs.-popovers

Was the issue noted related to these guidelines as they are written, or is the issue more about not knowing that these guidelines exist?

From my perspective, there are some things that could be clarified a bit better. A lot of what's recommended stems from the accessibility of these items. Tooltips should only ever contain plain text contents, and never interactive elements. Whereas popovers can contain interactive contents (like links to documentation).