In-app Documentation Coach Marks Ui Design

Version 5.1.1

Coach mark

Coach marks are temporary messages that educate users through new or unfamiliar product experiences. They can be chained into a sequence to form a tour.

Coach mark for action button in side-panel. Label Pan camera, 4 of 17, description Switch to the Hand tool then click and drag in the canvas to move your camera up, down, left, and right. Primary button, label Next. One quiet button, label Skip tour.

Anatomy#

Image illustrating through labels the parts of a Coach mark, including its Indicator, Image, Steps, Title, Body, and Buttons including Skip tour and next.

Options#

Key example showing coach mark in a tour. Title Enable smart filters, step 2 of 8. Description Smart filters are nondestructive and will preserve your original images. One quiet button, label Skip tour. Primary button, label Next.

In a tour#

Coach marks are in a tour when the primary action of one coach mark will lead to the display of another. The "Skip tour" button creates an escape path for the user to avoid having to click through each step.

A step indicator is optional but encouraged. Display of progress should be consistent throughout the tour — either all steps should have this, or none.

Key example showing coach mark with image. Title Enable smart filters. Description Smart filters are nondestructive and will preserve your original images. One quiet button, label Skip tour. Primary button, label Next.

With image#

Coach marks can contain images that relate to their content, such as demonstrations of gestures, the UI being used, or illustrations.

Key example showing coach mark in a tour dependent on an action. Title Shared library. Description Your shared library items are available in the Library panel. Add an asset from the library to continue. One quiet button, label Skip tour.

Action dependent#

Coach marks in a tour can be dependent on an action. Unless the tour is skipped, they will persist until the user takes the corresponding action. In this example, the coach mark would disappear once a user opens the panel.

Key example showing all the different Indicator color variants in their respective size variants.

Indicator color#

The coach mark indicator comes in standard (large) and quiet (small), with a light, dark, and blue variant for contrast in different situations.

Behaviors#

Key example of a coach mark showing text overflow. Title Use smart filters to maintain your originals, step 3 of 8. Description Smart filters are nondestructive and will preserve your original images. One quiet button, label Skip tour. Primary button, label Next.

Text overflow#

When the title and body text are too long for the available horizontal space, they wrap to form another line. The steps are always shown in full and never wrap or truncate.

Usage guidelines#

Use a consistent width#

Choose a width for your coach marks that is spacious enough to accommodate all of your content. Within a tour that includes many coach marks, keep the width consistent across each one.

Keep titles concise#

Aim for concise titles, and keep complex information in the body text. Titles should be in sentence case. Avoid wrapping if possible.

Keep body text succinct and informative#

Coach marks are meant to be quick overviews of functionality. Body text should be at least a few words, but no more than a few sentences.

Coach mark copy should be concise, but written in complete sentences and expressing encouragement and usefulness. View the voice and tone guidelines for more information.

Align coach marks with the action being explained#

Coach marks are aligned with their related components in the same way as popovers. Choose a placement that keeps the related component visible on screen.

Key example showing correct usage of alignment and placement for coach marks. A coach mark explaining a play button is aligned above three action buttons ("back, play, forward") and a video timeline.

Key example showing incorrect usage of alignment and placement for coach marks. A coach mark explaining a play button is aligned below three action buttons ("back, play, forward") and aligned above a video timeline, covering the video timeline.

Don't obscure a relevant part of the UI with the coach mark.

Use an indicator to show the source#

Unlike popovers, the UI component a coach mark refers to does not need to take a down state. Use the placement of the coach mark and its indicator atop the component to indicate source.

Using the "Skip tour" button#

The "Skip tour" button should always be a quiet secondary button, even when it's the only button available in the dialog. Omit this button on the last step of a tour.

Don't use inconsistent action names within a tour#

The primary action should be brief and consistent. Use "OK" for a single coach mark. Within a tour, use "Next" for all but the last step, and "Finish" for the last step. Don't use different primary action names for every step in a tour.

Allow dismissal when a coach mark depends on an action#

When a coach mark is dependent on a user action, it's OK to remove the primary action button as long as the user still has a way to exit.

On a one-off coach mark, this means that the primary action button should remain as a way to dismiss. In a tour, it's acceptable to show only the "Skip tour" button.

Don't require users to confirm that they've taken an action#

When a coach mark is dependent on a user action, don't force the user to confirm that they've taken that action.

Key example showing incorrect usage of a coach mark confirmation. A coach mark with the primary action button labeled "asset added" forces a dependent user action in order to continue the tour.

Internationalization#

Key example showing a coach mark in the right-to-left language use case. The coach mark indicator is align on the top right of the coach mark and the title and body text are align to the right. The primary action button is align to the left followed by the secondary quiet button.

RTL#

For RTL (right-to-left) languages, the default layout of the coach mark is mirrored. Text is right-aligned while the chevron and the button group are left-aligned.

Keyboard interactions#

Key	Interaction
Tab	Moves focus to the next button inside the popover (last becomes first).
Esc	Exits the current coach mark. If in a tour, proceeds to the next coach mark (does not skip the entire tour).

Changelog#

Date	Number	Notes
Sep 11, 2019	5.1.1	Increased opacity of the animated indicator
Aug 22, 2019	5.1.0	Added text overflow behavior
Apr 19, 2019	5.0.0	This component is now individually versioned (individual versions of existing components start at 5.0.0) Added RTL (right-to-left) guidelines

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.)

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.