Version 2.0.0

Contextual help

Contextual help shows a user extra information about the state of either an adjacent component or an entire view. It explains a high-level topic about an experience and can point users to more information elsewhere.

Key example of contextual help used next to a disabled button, button label Create segment. Quiet action button, info icon. Popover, title Permission required, description Your admin must grant you permission before you can create a segment, link Learn about permissions.Key example of contextual help used next to a disabled button, button label Create segment. Quiet action button, info icon. Popover, title Permission required, description Your admin must grant you permission before you can create a segment, link Learn about permissions.

Anatomy#


Image illustrating through labels the component parts of contextual help, including an extra-small quiet icon-only action button, popover divided into a header that containers a title area, and a body which contains a body area.

Options#


Key example of contextual help used to display two types of content, in-line information or help. Action button with a pencil icon and label Edit, extra-small quiet action button to the right with an info icon. Action button with a pencil icon and label Edit, extra-small quiet action button to the right with a help icon.

Icon#

Contextual help can be used to display two types of supplementary content in an experience: in-line information (the info icon) or help and resources to learn more (the help icon).

3 examples of contextual help popover placement. First example, placement: bottom start. Popover is aligned to the left and below the action button.  Second example, placement: top. Popover is centered and directly above the action button. Third example, placement: right top. Popover is aligned to the right upper corner of the action button. All 3 examples have header text, Permission required, body text, Your admin must grant you permission before you can create a segment.

Popover placement#

The popover is positioned in relation to the action button. The placement property values are the following: top, top left, top right, top start, top end, bottom, bottom left, bottom right, bottom start, bottom end, left, left top, left bottom, start, start top, start bottom, right, right top, right bottom, end, end top, end bottom. The default placement value is bottom start.

Key example of contextual help popover offset, showing through labels a 6 pixel gap between the action button and popover. Header text, Permission required. Body text, Your admin must grant you permission before you can create a segment.

Popover offset#

The offset is the distance between the action button and the popover edge. The default value is 6 px on desktop and 8 px on mobile, but this can be adjusted depending on the context.

Example of the contextual help popover with placement of top start and cross offset of -16 pixels. Header text, Permission required. Body text, Your admin must grant you permission before you can create a segment.

Popover cross offset#

The cross offset is the placement offset on the cross axis (x-axis for top and bottom, y-axis for left and right). The default value is 0 px.

Example of a contextual help popover with top placement and 8 pixels of container padding. Header text, Permission required. Body text, Your admin must grant you permission before you can create a segment.

Container padding#

To make sure that a popover will stay within certain boundaries (e.g., a browser window) it’s possible to define a container, and a container padding value, to respect. The default value is 8 px.

Table of options#

From the design point of view, each component has a number of options. These options and their names are platform agnostic, and each implementation should adapt these to fit into their framework.

PropertyValuesDefault Value
icon
info / help
info
popover placement
top / top left / top right / top start / top end / bottom / bottom left / bottom right / bottom start / bottom end / left / left top / left bottom / start / start top / start bottom / right / right top / right bottom / end / end top / end bottom
bottom start
popover offset
number
6 px (desktop) or 8 px (mobile)
popover cross offset
number
0 px
container padding
number
8 px

Composition#


Image showing the composition of the title area of contextual help in relation to other parts of the component. Title area is inside the popover at the very top.

Title area#

The title area is reserved for the text that will be the title, or header, of the contextual help. Be sure to use proper formatting.

Image showing the composition of the body area of contextual help in relation to other parts of the component. Body area is below the title area, inside the popover.

Body area#

The body area is reserved for the description, or body text. This is usually a short paragraph and can include a standalone link when appropriate. Be sure to use proper formatting.

Usage guidelines#


Tooltip vs. contextual help#

A tooltip shows in-line information about the element that a user is hovering or focusing on. Contextual help describes a larger experience, such as something that’s associated with that element in a broader sense. Use contextual help to communicate information about an entire view, rather than a specific element of the experience (e.g., in high-level section headers).

Tooltips are meant for a few words or a short sentence, such as showing the label for an icon-only button. Contextual help offers more space to give more information, or to describe where a user can find further help.

Key example showing correct usage of contextual help. Disabled button, label Create segment. Contextual help with info icon. Popover, title Permission required, description Your admin must grant you permission before you can create a segment.
Key example showing incorrect usage of tooltip instead of contextual help. Disabled button, label Create segment. Quiet icon-only action button with info icon and tooltip label, title Permission required, description Your admin must grant you permission before you can create a segment.

Help text vs. contextual help#

Help text is readily visible, in-line information about a specific UI element. The information in the contextual help component is about an entire experience or view, is hidden within a popover, and only appears once a user interacts with the icon-only action button.

Use help text for critical information that a user needs to know to complete a task. Don’t hide essential information in contextual help; it’s intended to supplement the experience with minimal disruption.

Key examples showing correct usage of help text and contextual help with info icon. First example, required text field label Password. Help text description, Password must be at least 8 characters. Second example, required text field label Password. Contextual help info icon, title Need help?, description, If you’re having issues accessing your account, contact our customer support team for help.
Key examples showing incorrect usage of help text and contextual help with info icon. First example, required text field label Password. No help text. Second example, required text field label Password. Contextual help info icon, title Password requirements, description Passwords must be at least 8 characters.

More information about disabled components#

Contextual help can be used to explain why a component is disabled and how to enable it. Don’t make disabled components interactive (with focus states or hovering) as a way to display contextual information.

Key example showing correct usage of contextual help with disabled components. Disabled button, label Create segment. Contextual help with info icon. Popover, title Permission required, description Your admin must grant you permission before you can create a segment.
Key example showing incorrect usage of contextual help with disabled components. Disabled button, label Create segment. Keyboard focus ring around disabled button. Popover, title Permission required, description Your admin must grant you permission before you can create a segment.

Content standards#


Informative vs. helpful content#

The content within the contextual help’s popover reflects the icon it’s associated with: either the info icon or the help icon.

Use the info icon for informative content: specific, brief, and contextual guidance. This is best for supplemental or nice-to-know information, in-line with a label or a component (if there is no label). The content should be instructive in tone.

Use the help icon for helpful content: more detailed, in-depth guidance about a task, UI element, tool, or keyboard shortcuts. This may include an image, video, or link and should be helpful in tone.

Correct usage of how to write informative vs helpful content. First example, an informative tone. Contextual help with info icon, title Permission required, description Your admin must grant you permission before you can create a segment. Second example, a helpful tone. Contextual help with help icon, title What is a segment?, description Segments identify who your visitors are, what devices and services they use, where they navigated from, and much more. Standalone link, Learn more about segments.

Use proper formatting#

For this component, don’t add a period to the end of the title. A question mark is acceptable, depending on the context.

For the description, add a period to the end of the sentence, even if it’s only a single sentence.

If using a standalone link, do not add punctuation to the end of the link text.

Correct usage of proper formatting. Contextual help with info icon, title Permission required, description Your admin must grant you permission before you can create a segment. Standalone link, Learn about permissions.
Incorrect usage of proper formatting. Contextual help with info icon, title You need permission first! Description Ask your admin to grant you permission so you can create a segment. Standalone link, Learn more to continue.

If using a standalone link, make sure that the landing experience is intuitive, helpful, and naturally builds upon the information being introduced in the component. For example, don’t link to an external sales website unless the information there is directly related to a user being able to do something within the product.

A generic “Learn more” can be acceptable, but it’s more helpful to include another word or two in the link text that gives more context about the landing experience.

Correct usage of including a “Learn more” link. Contextual help with help icon, title What is a segment?, description Segments identify who your visitors are, what devices and services they use, where they navigated from, and much more. Standalone link, Learn more about segments.
Incorrect usage of a “Learn more” link. Contextual help with help icon, title About segments, description Segments identify everything from where your visitors are coming from to how they like their coffee! Standalone link, Learn more now.

Keyboard interactions#


KeyInteraction
Space or EnterOpens the popover.
EscCloses the popover and moves focus back to the action button.

Changelog#


DateNumberNotes
Apr 06, 20222.0.0
  • Updated all colors to 6.0.0
Mar 21, 20221.1.0
  • Added options for popover (placement, offset, cross offset, container padding)
  • Added composition section
  • Added keyboard interactions section
Sep 23, 20211.0.1
  • Added mobile scale to the UI kit
Sep 09, 20211.0.0
  • This component has been added to the website

Design checklist#


All interactive states

Includes all interactive states that are applicable (hover, down, focus, keyboard focus, disabled).

All color themes

Works properly across all four color themes (lightest, light, dark, darkest).

All platform scales

Includes a desktop scale (UWP, macOS, web desktop) and a mobile scale (iOS, Android, web mobile).

Accessible use of color

Color is not used as the only visual means of conveying information (WCAG 2.0 1.4.1).

Accessible contrast for text

Text has a contrast ratio of at least 4.5:1 for small text and at least 3:1 for large text (WCAG 2.0 1.4.3).

Accessible contrast for UI components

Visual information required to identify components and states (except inactive components) has a contrast ratio of at least 3:1 (WCAG 2.1 1.4.11).

Content design

UI language and information design considerations have been incorporated into component design.

Defined options

Includes relevant options (variant, style, size, orientation, optional iconography, decorations, selection, error state, etc.)

N/A

Defined behaviors

Includes guidelines for keyboard focus, layout (wrapping, truncation, overflow), animation, interactions, etc.

Usage guidelines

Includes a list of dos and don'ts that highlight best practices and common mistakes.

Writing guidelines

Includes content standards or usage guidelines for how to write or format in-product content for the component.

Internationalization guidelines

Works properly across various locales and includes guidelines for bi-directionality (RTL).

Keyboard interactions

Follows WCAG 2.0 standards for keyboard accessibility guidelines and includes a description of the keyboard interactions.

Design tokens

All design attributes (color, typography, layout, animation, etc.) are available as design tokens.

UI kit

Includes a downloadable XD file that shows multiple options, states, color themes, and platform scales.

Generated UI kit

Includes a downloadable XD file, generated by code using design tokens defined in Spectrum DNA, and shows multiple options, states, color themes, and platform scales.

In Spectrum for Adobe XD plugin

Component is included in the Spectrum for Adobe XD plugin.