@atlaskit/spotlight
Version:
A spotlight introduces users to points of interest, from focused messages to multi-step tours.
246 lines (184 loc) • 8.5 kB
text/mdx
import {
SpotlightTable,
SpotlightVisualGuidelines,
SpotlightCollectionBackgroundColors,
} from '@af/design-system-docs-ui';
import { Stack } from '@atlaskit/primitives/compiled';
import Image from '@atlaskit/image';
import tourUseDo from '../images/tour-use-do.png';
import tourUseDont from '../images/tour-use-dont.png';
import singleStepLight from '../images/single-step-light.png';
import singleStepDark from '../images/single-step-dark.png';
import triggeredSpotlightLight from '../images/triggered-spotlight-light.png';
import triggeredSpotlightDark from '../images/triggered-spotlight-dark.png';
import principlesDoLight from '../images/principles-of-use-do-light.png';
import principlesDoDark from '../images/principles-of-use-do-dark.png';
import principlesDontLight from '../images/principles-of-use-dont-light.png';
import principlesDontDark from '../images/principles-of-use-dont-dark.png';
import spotlightAnatomyLight from '../images/spotlight-anatomy-light.png';
import spotlightAnatomyDark from '../images/spotlight-anatomy-dark.png';
import colorApplicationLight from '../images/color-application-light.png';
import colorApplicationDark from '../images/color-application-dark.png';
Use a spotlight to bring attention to a specific part of the UI, such as a button or icon, to
educate users about key features or workflows.
Spotlights are most effective for onboarding new users, driving feature discovery, or highlighting
important changes. Use them sparingly. If your UI needs frequent spotlights, consider simplifying
the core experience instead.
[](https://go.atlassian.com/use-post-office)
The ideal spotlight experience is lightweight and a single-step. Always try to limit your experience
to one spotlight to prevent information overload for the user.
<Image
src={singleStepLight}
srcDark={singleStepDark}
alt="Example of a single-step spotlight with content about Jira tasks pointing at a task on a Jira board."
/>
A tour is a series of spotlights that point to multiple areas of the UI. <br /> Ensure your tour:
- has a maximum of three steps
- is logically sequenced
- is limited to one screen
- includes a “Back” call-to-action (CTA) after the initial spotlight
- displays a step count
**In a tour, the initial spotlight references step count and clear next action**
**Advancing to the next step introduces a Back button**
Tours should be used sparingly. Before designing a tour, assess if you can combine or eliminate
steps to keep the experience as lightweight as possible, as seen below.
<DoDontGrid>
<DoDont
type="do"
image={{
url: tourUseDo,
alt: 'Example of a single-step spotlight with content that combines the example content of the multi-step tour next to it.',
}}
>
Keep things lightweight. Aim for one step with active and concise messaging.
</DoDont>
<DoDont
type="dont"
image={{
url: tourUseDont,
alt: 'Example of a multi-step spotlight with content that that can be combined into a single step.',
}}
>
Avoid tours unless the steps are crucial. Consolidate information first.
</DoDont>
</DoDontGrid>
Spotlights can activate UI if triggered by another component. Although they are a second step in an
experience, they should not use a step count or “Back” CTA.
**In this example, a banner triggers a spotlight that opens a dropdown**
<Image
src={triggeredSpotlightLight}
srcDark={triggeredSpotlightDark}
alt="Example of a single-step spotlight with content that combines the example content of the multi-step tour next to it."
/>
Guide first-time users to essential features and workflows.
Help existing users learn about new or updated capabilities.
Trigger a spotlight from another component to elaborate on the message. For example, a flag with a
“Show me” CTA triggers a spotlight to demonstrate the feature in context. Triggered spotlights can
also activate UI.
<DoDontGrid>
<DoDont
type="do"
image={{
url: principlesDoLight,
urlDarkMode: principlesDoDark,
alt: 'Example of spotlight with content that explains what Rovo is.',
}}
>
Use spotlights to educate users or introduce them to something new.
</DoDont>
<DoDont
type="dont"
image={{
url: principlesDontLight,
urlDarkMode: principlesDontDark,
alt: 'Example of a spotlight with content that promotes purchasing collections to get Rovo.',
}}
>
Use spotlights for upsells or other transactional messaging.
</DoDont>
</DoDontGrid>
<Image
src={spotlightAnatomyLight}
srcDark={spotlightAnatomyDark}
alt="Example spotlight with a diagram that points to the elements that exist within a spotlight."
/>
<SpotlightTable />
Media should only be used to make messaging clearer for more complex features. For simple
experiences, stick to text to avoid distracting the user.
The cognitive load necessary for comprehension should determine the level of complexity.
<br />
<SpotlightVisualGuidelines />
<br />
<Image
src={colorApplicationLight}
srcDark={colorApplicationDark}
alt="Example spotlight with a diagram that points to the background color then outlines that it should be the right collection color."
/>
- Use solid color for the background color to drive focus to the main UI elements
- Incorporate the collection color into background color to further strengthen the color association
to the collection (see colors below)
- Start with the color designated for each collection, then evenly distribute other brand colors to
the UI elements
- Limit the use to no more than three different colors in a single composition
- Different shades can be used to create contrast and spatial depth in the UI illustrations, but
avoid using too many shades within one composition
### Collection background colors
<br />
<SpotlightCollectionBackgroundColors />
<br />
## Content guidelines
A successful spotlight can be understood in just a few seconds. Spotlight content should be as
concise as possible, easy to scan, and only communicate essential information.
### Messaging guidelines
- Prioritize the most relevant information and if more context is needed, find a way to provide a
path to further learning
- Don’t talk about things the user cannot see at that time
#### Headline
- 27 characters max
- Start with an active verb
- Clearly communicate intent
- Focus on benefits rather than announcements
- Personalize with words such as, “your” where it is relevant
#### Body copy
- 75 characters max
- Brief and direct
- Elaborate value
#### Primary CTA
- 24 characters max for single-step
- 15 characters max for tour
- Provide an obvious next action
- If used for dismissal, use “Done”
- Let them know where they’re going next when navigating to another screen “Go to Jira”
- Be explicit when activating UI components “Chat with Rovo” opens the Rovo panel
- Use “Learn more” when navigating to more detailed information
- For tours: start with “Next” and conclude the flow with “Done”
#### Secondary CTA
- Reserved for “Back” navigation in tours
## Accessibility
- The headline is used as the accessible name for the spotlight dialog
- Keep content concise and avoid motion that could be disruptive
- Ensure the arrow and spotlight are not truncated by the browser bounds
### Focus management
For a **single-step spotlight** or the **first in a multi-step tour**, tabbing begins after the
targeted element so the user is aware of what the spotlight is referring to. It follows a normal
tabbing order, automatically starting with the "X" dismissal on the top right, even if a "…" show
more is included ahead of it.
Unless the first spotlight is dismissed with the "X," in a **multi-step tour** the second and third
spotlights grab focus to continue the messaging narrative then return to the targeted element once
complete so the user can perform the intended action.