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';

## 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)](https://go.atlassian.com/use-post-office)

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

<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."
/>

### Multi-step tour

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**

![Example of a first spotlight in multi-step tour with content about Loom pointing at a Loom video.](../images/multi-step-step-1.png)

**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.](../images/multi-step-step-2.png)

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

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

### 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**

<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."
/>

## 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

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

## Parts

<Image
	src={spotlightAnatomyLight}
	srcDark={spotlightAnatomyDark}
	alt="Example spotlight with a diagram that points to the elements that exist within a spotlight."
/>

<SpotlightTable />

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

<br />
<SpotlightVisualGuidelines />
<br />

### Color application

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