New contribution proposal: Expanding the Underline Popover Tooltip pattern to Text and Select fields

[ksvihar]

TL;DR

We want to include an underline popover tooltip in Polaris as a new treatment for providing clarifying definitions. Current use cases in production on admin include card, section, and table column titles. We’d like to expand and include this treatment for text and select fields as well.

Proposal

We want to add the underline to the text and select field labels with 0.125 rem and border or border-strong colour token.

In cases where the label is not actionable (labels on text and select fields, titles), tooltip can be shown on both hover and click (for mobile). On mobile, when the tooltip is open on click, scrolling or tapping anywhere else will close the popover automatically.

In cases where the label is actionable (column headings where sorting is possible), we could have the sort order icon be the clickable element and use a tooltip on hover to annotate the sort order (e.g. lowest to highest). The label could be underlined to offer in-context definition of the term with a popover on hover.

Champion

@ksvihar

Stakeholders

@ctankei, @dGoligorsky, Products & Pricing Create Team, Shipping Team

Estimated timeline

Ready to start upon alignment. 1-2 weeks

What problem are you solving?

We want to away from using help (?) icons paired with tooltips to explain text/selection field labels. Tooltip icons bring more attention than required.

We’re making this proposal considering we want to support cases where we don’t want to use subtext in order to keep the UI compact. This is for supplemental information that doesn’t always have to be displayed in the main UI.

How does your solution improve Polaris?

This solution reduces page density and visual distractions on pages, so that the user can view supplemental information only as needed, This ensures that merchants have additional information to understand and populate accurate inputs.

• The Products & Pricing Create team (Core) will be able to consider this treatment across Product and Collection pages that currently use an outdated treatment we’re moving away from of help icons paired with tooltips
• The Shipping team (Merchant Services) will be able to use this treatment for terms that require clarifying definitions, such as “ready-to-pack product dimensions”, “HS code”, “Contract number (Carrier Connect Flow)”, etc.

Adding this treatment (with examples, components and guidance) to Polaris Figma Library and the Polaris website will help other designers refer to the applicable use cases as well.

Have you tested and verified your solution?

The dotted underline treatment paired with a popover has been effective in other parts of admin. It's currently being used in Analytics, Index Pages and Tables. We typically use this underline treatment for card, section and column header titles.

We just want to expand this pattern to text and select field labels as well.

What is the scope of work?

• Update Figma Polaris Library
• Add the component to Storybook
• Update Polaris Documentation with component examples and guidance
• Update relevant fields in product creation and shipping surface areas

What is the impact on existing implementations, and do you have a plan to address it?

We can use the Polaris website as reference material to share with our groups on this change. We can work with Polaris to help communicate any changes as well. Some potential activities:

• Update relevant fields in product creation and shipping surface areas
• Share in Workplace (Admin UX, Polaris)
• Share in Slack (Polaris, Respective Team UX Channels)
• Include in any Polaris monthly/quarterly updates
• Sharing in Quality Wins (Slack and Workplace)
• Suggest other teams (with leadership help) to audit their own surface areas to make changes as applicable

Are there any known blockers or risks?

Not really. We (Products & Pricing Create team and Shipping team) are ready to get this proposal approved from the Polaris team and the accessibility specialists so we can implement it in respective use cases.

[alex-page]

Thanks for the proposal. I am aligned that this design outcome is useful for merchants but have some thoughts on the technical approach. This reminds me of <abbr> in HTML. I don't know if we want to lean into the HTML spec for this solution.

I think there is a way to make this a simple contribution to add a dotted underline to the <Text> component. This would allow teams to compose combinations of components to achieve this outcome. e.g. a <Text dottedUnderline> + <Tooltip> or a <Text dottedUnderline> and <Popover> could be used in a form label, index table heading, a paragraph or any other part of the admin.

Can labels take a React element? if not they should?

This coupled with guidance on what the dotted underline is used for would help.

[ksvihar]

Thanks, @alex-page . @Alex-Palad is currently looking at creating a prototype based on your inputs. We'll share it back here when we have something good.

[heyjoethomas]

Couple thoughts:

1. I think we would need to be careful replacing helper text with a tooltip. If it is important information that helps merchants successfully fill out the field then hiding it in a tooltip could be problematic. We should only be replacing things that were already inside of a tooltip via an icon.
2. I think we could probably just us the border token for all dotted underlines. Maybe this is something we could document and help standardize.

[alex-page]

Yes. Great points Joe.

[ksvihar]

+1 on using border token for all dotted-underline use cases, Joe!

This dotted-underline tooltip pattern is surely not a replacement for helper subtexts. It's a subtler alternative to it. The best practice is to still have helper texts under the fields/titles especially if they help (clarifies and/or accelerates) the user enter correct inputs.

The places and use cases where I see the underline tooltip primarily being useful is:

• In surface areas that are used fairly often where the user already knows the meanings (whats, hows, whys) for different titles and fields, but the existence of help texts still is good for quick reference in case they have a quick doubt or for double checking when dealing with new use cases (like adding a new type of product, new type of discount, etc).
• In surface areas where cognitive load plays a direct role by impacting speed of task, confusion and/or conversion. Having hover based tooltips in such cases help with reducing the cognitive load and make the interfaces less overwhelming while still ensuring help information in within quick reach.

[heyjoethomas]

@ksvihar Seems like there is consensus on this proposal. Let's go forward and create an issue to track this work. Let's use @alex-page suggestion above as the starting point for a solution and if you have questions along the way feel free to reach out to us directly so we everyone remains in alignment.