Spotlight modal



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








Scrim: Blocking overlay


token unavailable


Shape: Background color


token unavailable


Shape: Padding (block, inline)


No token


Shape: Margin (block, inline)


No token


Shape: Border radius


token unavailable


Shape: Drop shadow

0 2px 14px 0 rgba(0, 0, 0, 0.2)

token unavailable


Shape: Position

absolute, center, center

token unavailable


Shape: Dimension (height, width)

Variable, 504px

token unavailable


Behavior: Close button (icon)


token unavailable




No token


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


Spotlight modal has four available types.

A note on slots: these are placeholders used in our Figma files to make them more flexible. Live examples of this pattern will not include the slots as seen below. We've left them visible in these examples to illustrate where the different Spotlight modal types are the most flexible in terms of layout and content.


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


Full Bleed

Use when you have a widescreen ratio image or illustration.


⚠️ Deprecated: Noodles

Reserved for special uses, typically celebratory in nature (100 Thanks).

Noodles also includes animated shapes between the modal container and the scrim overlay. Guidance for this is forthcoming.



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. Additional details on animation specifics to come.

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:

  1. Closing "X" in the top right corner. This must be clickable, visible, and have good contrast. This affordance is the bare minimum.
  2. 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.
  3. Clicking outside the modal, on the scrim overlay or browser chrome.
  4. Typing "ESC" on the keyboard.

Frequency cap

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

Writing guidelines

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

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.


Accessibility guidance coming in the future. Please reach out to #accessibility on Slack with any specific questions.





Jul 12, 2023


Initial draft of spotlight modal guidance

Status checklist

Overview of this pattern's status.

All States

Includes all applicable states (hover, focus, disabled, etc...)

All Themes

Works properly across all themes (theme name, theme name, etc...)

All Modes

Works properly across all modes (light, dark, high contrast)

All Desktop Environments

Works properly across all environments (Windows, MacOS, Linux)

All Mobile Environments

Works properly across all environments (iOS, Android)

Overall Accessibility

Has been tested and reviewed by A11y Team.

Color / Accessibility

All color has been tested against and passed all the latest WCAG 2.1 A & AA standards.

Text / Accessibility

All text has been tested against and passed all the latest WCAG 2.1 A & AA standards.

Contrast / Accessibility

All contrast has been tested against and passed all the latest WCAG 2.1 A & AA standards.

Interaction / Accessibility

All interactions have been tested against and passed all the latest WCAG 2.1 A & AA standards.

Content Design Review

Has been tested and reviewed by Content Design Team.

Writing Guidelines

Follows guidance for writing and language use.


Works properly across locales, and includes guidance for RTL languages.

Defined Behavior

Guidance for behavior when interacted with.

Defined Interactions

Guidance for interaction capabilities, ie. keyboard interactions.

Usage Guidelines

Includes guidance for usage, dos and don'ts, best practices.


All attributes are available as tokens.

Figma Library

Has a reusable Figma component.


Is documented in Storybook.


Has a code counterpart.