Spotlight modal

A specific branded pattern that uses a modal component and behavior stack to serve informational content to a user in the context of their actions and browsing.

Spotlight modal

Desktop Components library

Due to its highly visible and window-blocking nature, all proposals involving this pattern require approval from the Acorn team.

Usage

This pattern’s intended uses include onboarding and discovery of features in Firefox.

When using this pattern, reach out to the #content-design team for guidance on content strategy and copy for your specific implementation of this pattern.

Use to make a user aware of new or hidden features in context of their current actions and/or behaviors. For example, Onboarding a new user or explaining how to use Picture-in-Picture when a video is played.

Give clear affordances for dismissing this modal. See Behavior and interaction.

Use viewport-blocking modal scrims. This pattern currently uses window-blocking scrims, but we are recommending a move to viewport-blocking instead.

Use sparingly and with intent.

Don't

Use this pattern to advertise a product, service, add-on, or subscription.

Use this pattern to ask for donations.

Use deceptive patterns or feature obstruction to force a user to interact with the modal's content.

Use stacking or multiple Spotlight modals in the same experience.

Design properties

See Storybook for code

Property	Values	Default
Input slot InstanceSwap	Input slot	Slot
Show logo Boolean	true \| false	true
Show tertiary action link Boolean	true \| false	true
Show dismiss button Boolean	true \| false	true
Image slot InstanceSwap	Image slot	Slot
Show tertiary action button Boolean	true \| false	true
Show input slot Boolean	true \| false	true
Image layout Variant	None \| Padding \| Edge-to-edge	None

Types

Default

Suitable for most use cases. When in doubt, use this type.

Full Bleed

Use when you have a widescreen ratio image or illustration.

Custom

Only use when the other options aren't suitable or you need very specific or detailed content — be sure to discuss with the Acorn team.

Behavior and interaction

Spotlight modal should animate in on launch and animate out on dismiss.

There should be redundant, clear ways to dismiss a Spotlight modal. The following are acceptable, and at least one must present in every Spotlight modal:

Closing "X" in the top right corner. This must be clickable, visible, and have good contrast. This affordance is the bare minimum.

A cancel action. A secondary action, that behaves in the same way as the closing "X". This is only needed when there is a primary call to action in the modal. The label for this action should be clear and contextual to the primary action.

Clicking outside the modal, on the scrim overlay or browser chrome.

Typing "ESC" on the keyboard.

Frequency cap

A Spotlight modal can be shown no more than once every 28 days.

Writing guidelines

If you plan to use a spotlight modal, reach out to #content-design.

Due to the stopping power of this component, content should be clear, descriptive, and have a singular focus (e.g. drawing attention to a new feature, etc.). When in doubt, rely on the overall content guidance in Acorn.

Button labels should be clear and contextual to the primary action.

Write content that introduces new features or informs users of high-value changes made to Firefox (e.g. introducing picture-in-picture).

Don't

Use the spotlight modal to advertise Mozilla products or services. The spotlight modal is not a place to sell add-on services, subscriptions, or ask for donations.

Changelog

Date	Version	Notes
Aug 4, 2025	2.0.0	Simplified template
Jul 12, 2023	1.0.0	Initial draft of spotlight modal guidance