@atlaskit/spotlight 0.7.0 → 0.7.2

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @atlaskit/spotlight
 
+## 0.7.2
+
+### Patch Changes
+
+- [`ccbe07df5c620`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/ccbe07df5c620) -
+  Update documentation to include motion example.
+
+## 0.7.1
+
+### Patch Changes
+
+- [`991d1598db6d6`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/991d1598db6d6) -
+  Documentation for upcoming beta release.
+
 ## 0.7.0
 
 ### Minor Changes

package/README.md

@@ -1,13 +1,8 @@
 # Spotlight
 
-Note: This package is in pre-alpha. It is not ready to be consumed and used.
-
-A spotlight introduces users to various points of interest across Atlassian through focused messages
-or multi-step tours.
+A spotlight introduces users to points of interest, from focused messages to multi-step tours.
 
 ## Usage
 
-`import { Spotlight } from '@atlaskit/spotlight';`
-
 Detailed docs and example usage can be found
 [here](https://atlaskit.atlassian.com/packages/design-system/spotlight).

package/constellation/index/examples.mdx

@@ -7,31 +7,30 @@ import SingleStepExample from '../../examples/constellation/single-step';
 import MultipleStepsExample from '../../examples/constellation/multiple-steps';
 import MediaExample from '../../examples/constellation/media';
 import ControlsExample from '../../examples/constellation/controls';
+import MotionExample from '../../examples/constellation/motion';
 
-## Single Step
+## Single step
 
-Ideally, spotlights should only have a single step so as not to overwhelm users with too much
-information. Try and combine or eliminate tasks where possible. Dismiss functionality is required.
-Don't force users to participate.
+Always aim for a single step experience.
 
-By design `@atlaskit/spotlight` does not have a blanket, scroll-lock, focus-trap, or click-outside
-to dismiss functionality. This is to ensure the user is not hijacked into the spotlight experience,
-and can opt-in if they are interested.
+By design, `@atlaskit/spotlight` does not have a blanket, scroll-lock, or focus-trap functionality.
+This is to ensure the user is not hijacked into the spotlight experience, and can opt-in if they are
+interested.
 
 To show/hide the `SpotlightCard`, simply use a `useState` to control the `isVisible` prop on
 `PopoverContent`. To position the `SpotlightCard`, use `PopoverProvider`, `PopoverTarget` and
 `PopoverContent` and set the `placement` prop.
 
-<Example Component={SingleStepExample} packageName="@atlaskit/spinner" />
+<Example Component={SingleStepExample} packageName="@atlaskit/spotlight" />
 
-## Multiple Steps/Tour
+## Multi-step tour
 
-Multiple steps should be avoided if possible. Try and combine or eliminate steps where possible. If
-multiple steps are required, preference managing the tour with a `useState`. As a last resort a
-React context may be used. However, these contexts will often need to be wrapping the entire `App`
-and therefore will cause the entire `App` to re-render every time a new spotlight step is shown.
+Multiple steps should be avoided if possible, but if they are required, manage the tour with a
+`useState`. If `useState` is not feasible, then a React context may be used. However, these contexts
+will often need to be wrapping the entire `App` and therefore will cause the entire `App` to
+re-render every time a new spotlight step is shown.
 
-<Example Component={MultipleStepsExample} packageName="@atlaskit/spinner" />
+<Example Component={MultipleStepsExample} packageName="@atlaskit/spotlight" />
 
 ## Placements
 
@@ -39,18 +38,25 @@ Spotlight placements are static. They do not change as the user scrolls, or if t
 overflows out of the viewport. Make sure to choose a placement that ensures the `SpotlightCard` is
 displayed in full.
 
-<Example Component={PlacementsExample} packageName="@atlaskit/spinner" />
+<Example Component={PlacementsExample} packageName="@atlaskit/spotlight" />
 
 ## Media
 
-Media is optional for a `SpotlightCard`. However if it is used it must be 295px width X 135px
-height. This is to ensure correct reflow on smaller viewports.
+Media is optional for a `SpotlightCard`and should only be used for more complex features. To ensure
+correct reflow on smaller viewports, media must be 295px width X 135px height.
 
-Media can be an image, video, animation, or any other visual aid to communicate spotlight intent.
+Media can be an image, gif, or video that helps communicate spotlight intent.
 
-<Example Component={MediaExample} packageName="@atlaskit/spinner" />
+<Example Component={MediaExample} packageName="@atlaskit/spotlight" />
 
 ## Controls
 
 `SpotlightDismissControl` is required for all `SpotlightCard` components. It **must** be the first
 focusable element on the `SpotlightCard` card to provide an accessible experience.
+
+## Motion
+
+`@atlaskit/spotlight` can be composed with `@atlaskit/motion` or other CSS animation packages to
+create smooth 'enter' or 'exit' transitions.
+
+<Example Component={MotionExample} packageName="@atlaskit/spotlight" />

package/constellation/index/usage.mdx

@@ -1,127 +1,212 @@
-import { SingleStepSpotlightTable, MultiStepSpotlightTable } from '@af/design-system-docs-ui';
+import {
+	SpotlightTable,
+	SpotlightVisualGuidelines,
+	SpotlightCollectionBackgroundColors,
+} from '@af/design-system-docs-ui';
+import { Stack } from '@atlaskit/primitives/compiled';
+
+import tourUseDo from '../images/tour-use-do.png';
+import tourUseDont from '../images/tour-use-dont.png';
+import principlesDo from '../images/principles-of-use-do.png';
+import principlesDont from '../images/principles-of-use-dont.png';
 
 ## Usage
 
-A spotlight focuses attention on 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.
+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.
 
-## Spotlight Scenarios
+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.
 
-### Top use cases
+### Single-step spotlight
 
-- **Onboarding new users**: Guide first-time users to essential features and workflows.
-- **Feature discovery**: Help existing users learn about new or updated capabilities.
+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.
 
-### Growth use cases
+![Example of a single-step spotlight with content about Jira tasks pointing at a task on a Jira board.](../images/single-step.png)
 
-- **Cross-flow, cross-join, co-use**: Use spotlights only when triggered by another message type
-  (e.g., a banner that asks for permission to “show me” before triggering a spotlight).
+### Multi-step tour
 
-### Unsupported use cases
+A tour is a series of spotlights that point to multiple areas of the UI. <br /> Ensure your tour:
 
-- **Transactional**: Never use spotlights for transactional messages.
+- 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
 
-## Guiding Principles
+**In a tour, the initial spotlight references step count and clear next action**
 
-- **Use sparingly**: Spotlights are a Level 3 (Neutral Plus) attention component. Overuse can
-  distract and fatigue users.
-- **One at a time**: Only show one spotlight at a time.
-- **Dismissibility**: Always provide a dismiss option. Never force participation.
-- **Step count**: Prefer single-step spotlights. For tours, keep flows short (2–3 steps max).
-- **Orchestration**: Build spotlights with Post Office to avoid message collisions and enforce
-  fatigue rules (Atlassians Only).
-- **Media**: Use media (images or video) only when it enhances understanding. Exclude media if the
-  spotlight already focuses attention effectively.
+![Example of a first spotlight in multi-step tour with content about Loom pointing at a Loom video.](../images/multi-step-step-1.png)
 
-## Anatomy & Specifications
+**Advancing to the next step introduces a Back button**
 
-### Single Step Spotlight
+![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)
 
-<SingleStepSpotlightTable />
-<br />
+### Tour use
 
-### Multi Step Spotlight/Tour
+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.
 
-<MultiStepSpotlightTable />
-<br />
+<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>
 
-## Visual Guidance
+<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>
 
-- **Complexity**: Match the visual complexity to the feature’s learning curve. Use text-only for
-  simple features, a single illustration for moderate complexity, and a narrative/motion for complex
-  flows.
+### Triggered spotlights
 
-- **Brand color**: Use solid backgrounds to focus attention. Limit to three brand colors per
-  composition.
+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.
 
-- **Composition**: Highlight the focal point with size, color, and gesture lines. Use motion only if
-  it clarifies the feature.
+**In this example, a banner triggers a spotlight that opens a dropdown**
 
-## Behavior
+![Example of a single-step spotlight with content that combines the example content of the multi-step tour next to it.](../images/triggered-spotlight.png)
 
-- **Entry points**: Spotlights should be triggered contextually and never interrupt core workflows.
-  For cross-product or promotional spotlights, use a less obtrusive entrypoint (like a banner)
-  first.
+## Spotlight use cases
 
-- **Tours**: Sequence steps logically. Keep flows short and focused.
+### Onboarding
 
-## Best Practices
+Guide first-time users to essential features and workflows.
 
-- Use spotlights only when necessary to drive understanding or adoption.
-- Sequence multi-step spotlights logically; aim for 2–3 steps max.
-- Always allow users to dismiss or skip.
-- Avoid competing with other in-product messages.
-- Prefer embedded, contextual education over overlays.
+### Feature discovery
 
-## Accessibility
+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
+
+<DoDont
+	type="do"
+	image={{
+		url: principlesDo,
+		alt: 'Example of spotlight with content that explains what Rovo is.',
+	}}
+>
+	Use spotlights to educate users or introduce them to something new.
+</DoDont>
 
-- The headline is used as the accessible name for the spotlight dialog.
-- Keep content concise and avoid motion that could be disruptive.
-- Ensure the carat and spotlight are not truncated by the browser bounds.
+<DoDont
+	type="dont"
+	image={{
+		url: principlesDont,
+		alt: 'Example of a spotlight with content that promotes purchasing collections to get Rovo.',
+	}}
+>
+	Use spotlights for upsells or other transactional messaging.
+</DoDont>
 
-### Focus Management
+## Anatomy and specifications
 
-#### Single step spotlights
+![Example spotlight with a diagram that points to the elements that exist within a spotlight.](../images/spotlight-anatomy.png)
 
-The spotlight should **not** grab focus. Allow users to tab onto the spotlight in normal tabbing
-order. By default the tabbable elements in spotlight will be ordered directly after the target
-element to give screen-reader/keyboard users context about what the spotlight is related to.
+<SpotlightTable />
 
-The first focusable element in the spotlight should **always** be the dismiss button at the top of
-the card. This will happen automatically even when a show-more button is visually ahead of it. So
-product engineers shouldn't need to do any additional work.
+## Visual guidelines
 
-#### Multi step spotlights
+### Media
 
-The first spotlight in a tour should **not** grab focus. Allow users to tab onto the spotlight in
-normal tabbing order.
+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 second (and subsequent step) spotlights **should** grab focus. This is because screen-reader
-users have no other method of knowing where the new spotlight steps are shown.
+The cognitive load necessary for comprehension should determine the level of complexity.
 
-Once the tour completes, focus should be returned to the target element for the first step. This
-allows screen-reader users to easily perform the actions just taught to them via the spotlight tour.
+<br />
+<SpotlightVisualGuidelines />
+<br />
+
+### Color application
+
+![Example spotlight with a diagram that points to the background color then outlines that it should be the right collection color.](../images/color-application.png)
 
-## Content Guidelines
+- 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
 
-## Headline
+### Collection background colors
+
+<br />
+<SpotlightCollectionBackgroundColors />
+<br />
 
-- Required. Begin with an active verb where possible.
-- Brief and direct; communicate the main benefit.
-- Limit to one line and use sentence case.
+## 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
 
-## Body
+- 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
 
-- Required. Briefly elaborate on the intent.
-- Avoid repeating the headline verb.
-- Two lines max. Focus on benefits and relevance.
-- Reference only visible elements.
+### Focus management
 
-## CTA
+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.
 
-- Required. One clear next action.
-- Avoid plan or feature names in CTAs.
-- For tours: “Next”, “Back”, “Done”.
-- For features: 1–3 words; “Done” is acceptable if no clear next action.
+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.

package/dist/cjs/ui/body/index.js

@@ -18,7 +18,7 @@ var styles = {
 /**
  * __SpotlightBody__
  *
- * `SpotlightBody` is required in a `Spotlight`. The content should be brief and direct to elaborate on the intent.
+ * `SpotlightBody` is required in a spotlight. The content should be brief and direct to elaborate on the intent.
  *
  */
 var SpotlightBody = exports.SpotlightBody = /*#__PURE__*/(0, _react.forwardRef)(function (_ref, ref) {

package/dist/cjs/ui/secondary-action/index.js

@@ -19,7 +19,7 @@ var styles = {
 /**
  * __Spotlight secondary action__
  *
- * `SpotlightSecondaryAction` is not required for all `Spotlight` components. It should supplement the SpotlightPrimaryAction.
+ * `SpotlightSecondaryAction` is not required for all spotlight components. It should supplement the `SpotlightPrimaryAction`.
  * It is intended to be used to go back to the previous step in multi step spotlight tours, or other similar actions.
  *
  */

package/dist/cjs/ui/show-more-control/index.js

@@ -20,7 +20,7 @@ var styles = {
 /**
  * __SpotlightShowMoreControl__
  *
- * SpotlightShowMoreControl allows the user to close the `Spotlight`.
+ * `SpotlightShowMoreControl` provides follow-up actions and customizations for the spotlight.
  *
  */
 var SpotlightShowMoreControl = exports.SpotlightShowMoreControl = /*#__PURE__*/(0, _react.forwardRef)(function (_ref, ref) {

package/dist/es2019/ui/body/index.js

@@ -10,7 +10,7 @@ const styles = {
 /**
  * __SpotlightBody__
  *
- * `SpotlightBody` is required in a `Spotlight`. The content should be brief and direct to elaborate on the intent.
+ * `SpotlightBody` is required in a spotlight. The content should be brief and direct to elaborate on the intent.
  *
  */
 export const SpotlightBody = /*#__PURE__*/forwardRef(({

package/dist/es2019/ui/popover-provider/index.js

@@ -3,7 +3,6 @@ import * as React from 'react';
 import { ax, ix } from "@compiled/react/runtime";
 import { Manager } from '@atlaskit/popper';
 import { SpotlightContextProvider } from '../../controllers/context';
-
 /**
  * __Popover provider__
  *

package/dist/es2019/ui/popover-target/index.js

@@ -2,7 +2,6 @@
 import * as React from 'react';
 import { ax, ix } from "@compiled/react/runtime";
 import { Reference } from '@atlaskit/popper';
-
 /**
  * __Target__
  *

package/dist/es2019/ui/secondary-action/index.js

@@ -11,7 +11,7 @@ const styles = {
 /**
  * __Spotlight secondary action__
  *
- * `SpotlightSecondaryAction` is not required for all `Spotlight` components. It should supplement the SpotlightPrimaryAction.
+ * `SpotlightSecondaryAction` is not required for all spotlight components. It should supplement the `SpotlightPrimaryAction`.
  * It is intended to be used to go back to the previous step in multi step spotlight tours, or other similar actions.
  *
  */

package/dist/es2019/ui/show-more-control/index.js

@@ -11,7 +11,7 @@ const styles = {
 /**
  * __SpotlightShowMoreControl__
  *
- * SpotlightShowMoreControl allows the user to close the `Spotlight`.
+ * `SpotlightShowMoreControl` provides follow-up actions and customizations for the spotlight.
  *
  */
 export const SpotlightShowMoreControl = /*#__PURE__*/forwardRef(({

package/dist/esm/ui/body/index.js

@@ -10,7 +10,7 @@ var styles = {
 /**
  * __SpotlightBody__
  *
- * `SpotlightBody` is required in a `Spotlight`. The content should be brief and direct to elaborate on the intent.
+ * `SpotlightBody` is required in a spotlight. The content should be brief and direct to elaborate on the intent.
  *
  */
 export var SpotlightBody = /*#__PURE__*/forwardRef(function (_ref, ref) {

package/dist/esm/ui/popover-provider/index.js

@@ -3,7 +3,6 @@ import * as React from 'react';
 import { ax, ix } from "@compiled/react/runtime";
 import { Manager } from '@atlaskit/popper';
 import { SpotlightContextProvider } from '../../controllers/context';
-
 /**
  * __Popover provider__
  *

package/dist/esm/ui/popover-target/index.js

@@ -2,7 +2,6 @@
 import * as React from 'react';
 import { ax, ix } from "@compiled/react/runtime";
 import { Reference } from '@atlaskit/popper';
-
 /**
  * __Target__
  *

package/dist/esm/ui/secondary-action/index.js

@@ -11,7 +11,7 @@ var styles = {
 /**
  * __Spotlight secondary action__
  *
- * `SpotlightSecondaryAction` is not required for all `Spotlight` components. It should supplement the SpotlightPrimaryAction.
+ * `SpotlightSecondaryAction` is not required for all spotlight components. It should supplement the `SpotlightPrimaryAction`.
  * It is intended to be used to go back to the previous step in multi step spotlight tours, or other similar actions.
  *
  */

package/dist/esm/ui/show-more-control/index.js

@@ -11,7 +11,7 @@ var styles = {
 /**
  * __SpotlightShowMoreControl__
  *
- * SpotlightShowMoreControl allows the user to close the `Spotlight`.
+ * `SpotlightShowMoreControl` provides follow-up actions and customizations for the spotlight.
  *
  */
 export var SpotlightShowMoreControl = /*#__PURE__*/forwardRef(function (_ref, ref) {

package/dist/types/ui/body/index.d.ts

@@ -11,15 +11,15 @@ export interface SpotlightBodyProps {
      */
     testId?: string;
     /**
-     * Textual content is required for all spotlights. It should be brief and direct
-     * to quickly elaborate on the intent.
+     * Textual content is required for all spotlights.
+     * It should be brief and direct to quickly elaborate on the value.
      */
     children: ReactNode;
 }
 /**
  * __SpotlightBody__
  *
- * `SpotlightBody` is required in a `Spotlight`. The content should be brief and direct to elaborate on the intent.
+ * `SpotlightBody` is required in a spotlight. The content should be brief and direct to elaborate on the intent.
  *
  */
 export declare const SpotlightBody: React.ForwardRefExoticComponent<React.PropsWithoutRef<SpotlightBodyProps> & React.RefAttributes<HTMLDivElement>>;

package/dist/types/ui/card/index.d.ts

@@ -11,7 +11,7 @@ export interface SpotlightCardProps {
      */
     testId?: string;
     /**
-     * Elements to be rendered inside the spotlight.
+     * Elements to be rendered inside the `SpotlightCard`.
      */
     children?: ReactNode;
 }

package/dist/types/ui/dismiss-control/index.d.ts

@@ -15,7 +15,7 @@ export interface SpotlightDismissControlProps {
      *
      * Specifies whether the dismiss button should be focused when the spotlight is rendered.
      * For spotlights that are triggered by user-action, this should be `true`. In the event that
-     * a spotlight is rendered on pageload, without explicit user interaction, this should be `false`.
+     * a spotlight is rendered on page load, without explicit user interaction, this should be `false`.
      */
     autoFocus?: boolean;
 }

package/dist/types/ui/headline/index.d.ts

@@ -11,7 +11,7 @@ export interface SpotlightHeadlineProps {
      */
     testId?: string;
     /**
-     * A brief and direct title to quickly hook the user on the intent.
+     * A brief and direct title to clearly communicate the intent.
      */
     children: ReactNode;
 }

package/dist/types/ui/media/index.d.ts

@@ -11,8 +11,7 @@ export interface SpotlightMediaProps {
      */
     testId?: string;
     /**
-     * Textual content is required for all spotlights. It should be brief and direct
-     * to quickly elaborate on the intent.
+     * Media to be displayed. This can be an image, video, gif that helps communicate spotlight intent.
      */
     children: ReactNode;
 }

package/dist/types/ui/popover-content/index.d.ts

@@ -11,15 +11,54 @@ interface BasePopoverContentProps {
      * serving as a hook for automated tests
      */
     testId?: string;
+    /**
+     * The position in relation to the target the content should be shown at.
+     */
     placement: Placement;
+    /**
+     * Controls whether or not `PopoverContent` is visible. Defaults to `true`.
+     */
     isVisible?: boolean;
+    /**
+     * Controls whether the 'dismiss' action is invoked when the user clicks outside the content. Defaults to `true`.
+     */
     shouldDismissOnClickOutside?: boolean;
+    /**
+     * Spotlights can be dismissed by:
+     * - Clicking the `SpotlightDismissControl`
+     * - Clicking any DOM element outside the spotlight (if `shouldDismissOnClickOutside === true`)
+     * - Pressing the Escape key
+     *
+     * These events align to the React.MouseEvent<HTMLButtonElement, MouseEvent>, MouseEvent, and KeyboardEvent events respectively.
+     * Defaults to `true`.
+     */
     dismiss: (event: DismissEvent) => void;
+    /**
+     * Invoked when the user clicks `SpotlightSecondaryAction`. If an `onClick` handler is provided to `SpotlightSecondaryAction`
+     * then that takes precedence, and `back` will be ignored.
+     */
     back?: (event: BackEvent) => void;
+    /**
+     * The content to be rendered in `PopoverContent`. This is intended to be a `SpotlightCard`.
+     */
     children: ReactNode;
 }
 export type PopoverContentProps = BasePopoverContentProps & ({
+    /**
+     * Invoked when the user clicks `SpotlightPrimaryAction` in a tour.
+     * If an `onClick` handler is provided to `SpotlightPrimaryAction` then that takes precedence,
+     * and `next` will be ignored.
+     *
+     * If `next` is passed to `PopoverContent`, then `done` cannot be passed. This will result in a type error.
+     */
     next: (event: NextEvent) => void;
+    /**
+     * Invoked when the user clicks `SpotlightPrimaryAction`.
+     * If an `onClick` handler is provided to SpotlightPrimaryAction then that takes precedence,
+     * and `done` will be ignored.
+     *
+     * If `done` is passed to PopoverContent, then `next` cannot be passed. This will result in a type error.
+     */
     done?: never;
 } | {
     done: (event: DoneEvent) => void;

package/dist/types/ui/popover-provider/index.d.ts

@@ -3,12 +3,17 @@
  * @jsx jsx
  */
 import { type ReactNode } from 'react';
+interface PopoverProviderProps {
+    /**
+     * The to be rendered in `PopoverProvider`. This is intended to be `PopoverContent`, and `PopoverTarget`.
+     */
+    children: ReactNode;
+}
 /**
  * __Popover provider__
  *
  * A popover provider provides necesary context for the `PopoverContent` and `PopoverTarget` components.
  *
  */
-export declare const PopoverProvider: ({ children }: {
-    children: ReactNode;
-}) => JSX.Element;
+export declare const PopoverProvider: ({ children }: PopoverProviderProps) => JSX.Element;
+export {};

package/dist/types/ui/popover-target/index.d.ts

@@ -3,11 +3,16 @@
  * @jsx jsx
  */
 import { type ReactNode } from 'react';
+interface PopoverTargetProps {
+    /**
+     * The content to be rendered in `PopoverTarget`. This is intended to be the element you want to point the spotlight at.
+     */
+    children: ReactNode;
+}
 /**
  * __Target__
  *
  * A target is the element that the popover content will be positioned in relation to.
  */
-export declare const PopoverTarget: ({ children }: {
-    children: ReactNode;
-}) => JSX.Element;
+export declare const PopoverTarget: ({ children }: PopoverTargetProps) => JSX.Element;
+export {};

package/dist/types/ui/primary-action/index.d.ts

@@ -20,7 +20,7 @@ export interface SpotlightPrimaryActionProps {
      */
     onClick?: PressableProps['onClick'];
     /**
-     * An accessible label to read out in the event that the displayed text does not provide anough context.
+     * An accessible label to read out in the event that the displayed text does not provide enough context.
      */
     'aria-label'?: string;
 }

package/dist/types/ui/secondary-action/index.d.ts

@@ -20,14 +20,14 @@ export interface SpotlightSecondaryActionProps {
      */
     onClick?: PressableProps['onClick'];
     /**
-     * An accessible label to read out in the event that the displayed text does not provide anough context.
+     * An accessible label to read out in the event that the displayed text does not provide enough context.
      */
     'aria-label'?: string;
 }
 /**
  * __Spotlight secondary action__
  *
- * `SpotlightSecondaryAction` is not required for all `Spotlight` components. It should supplement the SpotlightPrimaryAction.
+ * `SpotlightSecondaryAction` is not required for all spotlight components. It should supplement the `SpotlightPrimaryAction`.
  * It is intended to be used to go back to the previous step in multi step spotlight tours, or other similar actions.
  *
  */

package/dist/types/ui/show-more-control/index.d.ts

@@ -14,7 +14,7 @@ export interface SpotlightShowMoreControlProps {
 /**
  * __SpotlightShowMoreControl__
  *
- * SpotlightShowMoreControl allows the user to close the `Spotlight`.
+ * `SpotlightShowMoreControl` provides follow-up actions and customizations for the spotlight.
  *
  */
 export declare const SpotlightShowMoreControl: React.ForwardRefExoticComponent<React.PropsWithoutRef<SpotlightShowMoreControlProps> & React.RefAttributes<HTMLButtonElement>>;

package/dist/types-ts4.5/ui/body/index.d.ts

@@ -11,15 +11,15 @@ export interface SpotlightBodyProps {
      */
     testId?: string;
     /**
-     * Textual content is required for all spotlights. It should be brief and direct
-     * to quickly elaborate on the intent.
+     * Textual content is required for all spotlights.
+     * It should be brief and direct to quickly elaborate on the value.
      */
     children: ReactNode;
 }
 /**
  * __SpotlightBody__
  *
- * `SpotlightBody` is required in a `Spotlight`. The content should be brief and direct to elaborate on the intent.
+ * `SpotlightBody` is required in a spotlight. The content should be brief and direct to elaborate on the intent.
  *
  */
 export declare const SpotlightBody: React.ForwardRefExoticComponent<React.PropsWithoutRef<SpotlightBodyProps> & React.RefAttributes<HTMLDivElement>>;

package/dist/types-ts4.5/ui/card/index.d.ts

@@ -11,7 +11,7 @@ export interface SpotlightCardProps {
      */
     testId?: string;
     /**
-     * Elements to be rendered inside the spotlight.
+     * Elements to be rendered inside the `SpotlightCard`.
      */
     children?: ReactNode;
 }

package/dist/types-ts4.5/ui/dismiss-control/index.d.ts

@@ -15,7 +15,7 @@ export interface SpotlightDismissControlProps {
      *
      * Specifies whether the dismiss button should be focused when the spotlight is rendered.
      * For spotlights that are triggered by user-action, this should be `true`. In the event that
-     * a spotlight is rendered on pageload, without explicit user interaction, this should be `false`.
+     * a spotlight is rendered on page load, without explicit user interaction, this should be `false`.
      */
     autoFocus?: boolean;
 }

package/dist/types-ts4.5/ui/headline/index.d.ts

@@ -11,7 +11,7 @@ export interface SpotlightHeadlineProps {
      */
     testId?: string;
     /**
-     * A brief and direct title to quickly hook the user on the intent.
+     * A brief and direct title to clearly communicate the intent.
      */
     children: ReactNode;
 }

package/dist/types-ts4.5/ui/media/index.d.ts

@@ -11,8 +11,7 @@ export interface SpotlightMediaProps {
      */
     testId?: string;
     /**
-     * Textual content is required for all spotlights. It should be brief and direct
-     * to quickly elaborate on the intent.
+     * Media to be displayed. This can be an image, video, gif that helps communicate spotlight intent.
      */
     children: ReactNode;
 }

package/dist/types-ts4.5/ui/popover-content/index.d.ts

@@ -11,15 +11,54 @@ interface BasePopoverContentProps {
      * serving as a hook for automated tests
      */
     testId?: string;
+    /**
+     * The position in relation to the target the content should be shown at.
+     */
     placement: Placement;
+    /**
+     * Controls whether or not `PopoverContent` is visible. Defaults to `true`.
+     */
     isVisible?: boolean;
+    /**
+     * Controls whether the 'dismiss' action is invoked when the user clicks outside the content. Defaults to `true`.
+     */
     shouldDismissOnClickOutside?: boolean;
+    /**
+     * Spotlights can be dismissed by:
+     * - Clicking the `SpotlightDismissControl`
+     * - Clicking any DOM element outside the spotlight (if `shouldDismissOnClickOutside === true`)
+     * - Pressing the Escape key
+     *
+     * These events align to the React.MouseEvent<HTMLButtonElement, MouseEvent>, MouseEvent, and KeyboardEvent events respectively.
+     * Defaults to `true`.
+     */
     dismiss: (event: DismissEvent) => void;
+    /**
+     * Invoked when the user clicks `SpotlightSecondaryAction`. If an `onClick` handler is provided to `SpotlightSecondaryAction`
+     * then that takes precedence, and `back` will be ignored.
+     */
     back?: (event: BackEvent) => void;
+    /**
+     * The content to be rendered in `PopoverContent`. This is intended to be a `SpotlightCard`.
+     */
     children: ReactNode;
 }
 export type PopoverContentProps = BasePopoverContentProps & ({
+    /**
+     * Invoked when the user clicks `SpotlightPrimaryAction` in a tour.
+     * If an `onClick` handler is provided to `SpotlightPrimaryAction` then that takes precedence,
+     * and `next` will be ignored.
+     *
+     * If `next` is passed to `PopoverContent`, then `done` cannot be passed. This will result in a type error.
+     */
     next: (event: NextEvent) => void;
+    /**
+     * Invoked when the user clicks `SpotlightPrimaryAction`.
+     * If an `onClick` handler is provided to SpotlightPrimaryAction then that takes precedence,
+     * and `done` will be ignored.
+     *
+     * If `done` is passed to PopoverContent, then `next` cannot be passed. This will result in a type error.
+     */
     done?: never;
 } | {
     done: (event: DoneEvent) => void;

package/dist/types-ts4.5/ui/popover-provider/index.d.ts

@@ -3,12 +3,17 @@
  * @jsx jsx
  */
 import { type ReactNode } from 'react';
+interface PopoverProviderProps {
+    /**
+     * The to be rendered in `PopoverProvider`. This is intended to be `PopoverContent`, and `PopoverTarget`.
+     */
+    children: ReactNode;
+}
 /**
  * __Popover provider__
  *
  * A popover provider provides necesary context for the `PopoverContent` and `PopoverTarget` components.
  *
  */
-export declare const PopoverProvider: ({ children }: {
-    children: ReactNode;
-}) => JSX.Element;
+export declare const PopoverProvider: ({ children }: PopoverProviderProps) => JSX.Element;
+export {};

package/dist/types-ts4.5/ui/popover-target/index.d.ts

@@ -3,11 +3,16 @@
  * @jsx jsx
  */
 import { type ReactNode } from 'react';
+interface PopoverTargetProps {
+    /**
+     * The content to be rendered in `PopoverTarget`. This is intended to be the element you want to point the spotlight at.
+     */
+    children: ReactNode;
+}
 /**
  * __Target__
  *
  * A target is the element that the popover content will be positioned in relation to.
  */
-export declare const PopoverTarget: ({ children }: {
-    children: ReactNode;
-}) => JSX.Element;
+export declare const PopoverTarget: ({ children }: PopoverTargetProps) => JSX.Element;
+export {};

package/dist/types-ts4.5/ui/primary-action/index.d.ts

@@ -20,7 +20,7 @@ export interface SpotlightPrimaryActionProps {
      */
     onClick?: PressableProps['onClick'];
     /**
-     * An accessible label to read out in the event that the displayed text does not provide anough context.
+     * An accessible label to read out in the event that the displayed text does not provide enough context.
      */
     'aria-label'?: string;
 }

package/dist/types-ts4.5/ui/secondary-action/index.d.ts

@@ -20,14 +20,14 @@ export interface SpotlightSecondaryActionProps {
      */
     onClick?: PressableProps['onClick'];
     /**
-     * An accessible label to read out in the event that the displayed text does not provide anough context.
+     * An accessible label to read out in the event that the displayed text does not provide enough context.
      */
     'aria-label'?: string;
 }
 /**
  * __Spotlight secondary action__
  *
- * `SpotlightSecondaryAction` is not required for all `Spotlight` components. It should supplement the SpotlightPrimaryAction.
+ * `SpotlightSecondaryAction` is not required for all spotlight components. It should supplement the `SpotlightPrimaryAction`.
  * It is intended to be used to go back to the previous step in multi step spotlight tours, or other similar actions.
  *
  */

package/dist/types-ts4.5/ui/show-more-control/index.d.ts

@@ -14,7 +14,7 @@ export interface SpotlightShowMoreControlProps {
 /**
  * __SpotlightShowMoreControl__
  *
- * SpotlightShowMoreControl allows the user to close the `Spotlight`.
+ * `SpotlightShowMoreControl` provides follow-up actions and customizations for the spotlight.
  *
  */
 export declare const SpotlightShowMoreControl: React.ForwardRefExoticComponent<React.PropsWithoutRef<SpotlightShowMoreControlProps> & React.RefAttributes<HTMLButtonElement>>;

package/package.json

@@ -1,11 +1,17 @@
 {
 	"name": "@atlaskit/spotlight",
-	"version": "0.7.0",
-	"description": "A spotlight introduces users to various points of interest across Atlassian through focused messages or multi-step tours.",
+	"version": "0.7.2",
+	"description": "A spotlight introduces users to points of interest, from focused messages to multi-step tours.",
 	"author": "Atlassian Pty Ltd",
 	"license": "Apache-2.0",
 	"atlassian": {
-		"team": "Design System Team"
+		"team": "Design System Team",
+		"website": {
+			"category": "Messaging",
+			"status": {
+				"type": "beta"
+			}
+		}
 	},
 	"homepage": "https://atlassian.design/components/spotlight/",
 	"repository": "https://bitbucket.org/atlassian/atlassian-frontend-mirror",
@@ -34,7 +40,7 @@
 		"@atlaskit/icon": "^28.5.0",
 		"@atlaskit/image": "^3.0.0",
 		"@atlaskit/popper": "^7.1.0",
-		"@atlaskit/primitives": "^16.0.0",
+		"@atlaskit/primitives": "^16.1.0",
 		"@atlaskit/tokens": "^7.0.0",
 		"@atlaskit/visually-hidden": "^3.0.0",
 		"@babel/runtime": "^7.0.0",