Spotlight

A spotlight introduces users to points of interest, from focused messages to multi-step tours.

Usage

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.

Track and reduce message fatigue with Post Office (Atlassians only), (opens new window)

Single-step spotlight

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.

Multi-step tour

A tour is a series of spotlights that point to multiple areas of the UI.
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

Example of a first spotlight in multi-step tour with content about Loom pointing at a Loom video.

Advancing to the next step introduces a Back button

Example of a second spotlight in multi-step tour with content about creating docs in Jira pointing at a Jira update.

Tour use

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.

Example of a single-step spotlight with content that combines the example content of the multi-step tour next to it.

Do

Keep things lightweight. Aim for one step with active and concise messaging.

Example of a multi-step spotlight with content that that can be combined into a single step.

Don’t

Avoid tours unless the steps are crucial. Consolidate information first.

Triggered spotlights

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

Spotlight use cases

Onboarding

Guide first-time users to essential features and workflows.

Feature discovery

Help existing users learn about new or updated capabilities.

Cross-flow, cross-join, and co-use

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.

Principles of use

Example of spotlight with content that explains what Rovo is.

Do

Use spotlights to educate users or introduce them to something new.

Example of a spotlight with content that promotes purchasing collections to get Rovo.

Don’t

Use spotlights for upsells or other transactional messaging.

Parts

Example spotlight with a diagram that points to the elements that exist within a spotlight.

Name	Usage	Description
`Headline`	required	27 characters max See content guidelines for appropriate usage
`Arrow`	required	Points to the referenced UI element. It can appear: left, start and end right, start and end top, start, center, and end bottom, start, center, and end Ensure that the spotlight is not truncated by the bounds of the browser
`Media`	optional	Can include an image, gif, or a video 295 Width X 135 Height See media media guidelines for appropriate usage
`Body`	required	75 characters max See content guidelines for appropriate usage
`StepCount`	required	Only used in tours and is required to guide the user
`Dismiss`	required	Included dismissal at the upper right
`PrimaryCTA`	required	See content guidelines for appropriate usage
`SecondaryCTA`	required	Required in tours for “Back” navigation to previous spotlight

Visual guidelines

Media

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.

Low complexity

Low cognitive load

Only use text when features are straightforward and easy to understand through the UI.

Example of a low complexity, text-only spotlight that is describing how to create a page.

Medium complexity

Moderate cognitive load

Use a single-frame illustration with a clear focal point for features that offer straightforward and intuitive interactions, but require a visual reference for comprehension.

Example of a medium complexity spotlight that includes a single frame illustration that is describing creating tasks with the right information.

High complexity

High cognitive load

If a feature is complex, use multiple images or a short video (like a GIF or MP4) to help explain how it works.

Example of a high complexity spotlight that includes a short video that is describing the benefit of creating a huddle for your team.

Color application

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

Platform Collection

Apps: Home, Teams, Goals, Projects
Background color: color/background/accent/gray/subtler/default

Teamwork Collection

Apps: Jira, Confluence, Loom
Background color: color/background/accent/blue/subtlest/pressed

Software Collection

Apps: Rovo Dev, DX, Pipelines, Bitbucket, Compass
Background color: color/background/accent/lime/subtler/hovered

Strategy Collection

Apps: Focus, Talent, Align
Background color: color/background/accent/orange/subtler/pressed

Service Collection

Apps: Jira Service Management, Customer Service Management, Assets
Background color: color/background/accent/orange/subtlest/pressed

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.

Was this page helpful?

We use this feedback to improve our documentation.