Dark Mode in the Hub Page embed

Overview

Hub embeds offer three color schemes: "light", "dark", and "system" (which is the default). It’s important to choose the value that best matches the behavior of the page you are embedding into.

How to update the Hub Color Scheme setting

You can update the color scheme setting in the Hub app in the Page, Widget, or Portal design settings for your Workspace. This will update the value for all embedded <released-page> or <released-widget> elements respectively for that Workspace, or for that Workspace’s Portal in the Product Hub.

If you have a specific widget or page that is embedded into a different context, you can add the color-scheme="{light|dark|system}" attribute to that element to override the value you’ve set in the Workspace settings. For example, to st a single Announcement Page to use the Light color scheme:

<released-page color-scheme="light" (other attributes)></released-page>

Light, Dark, and System/Auto - which setting do I want?

Which Hub Color Scheme you choose depends on how your page handles the native browser color-scheme values for your users. Specifically, it depends on how your page interacts with:

Your user’s prefers-color-scheme CSS media feature, which describes whether the user has configured their browser to prefer a dark or light color scheme.
The HTML document’s color-scheme CSS property which describes the actual color-scheme the document is using. Technically, we only look at the color-scheme value on the <released-page> or <released-widget> element itself, but this is usually inherited and consistent across the whole document.

Color scheme	HTML attribute value	Use this value if…
Light	light	your page doesn’t respond to a user’s `prefer-color-scheme` settings and always has a light background, or your page has a Dark Mode setting, but doesn’t set the CSS `color-scheme` property to match, and the user has chosen a Light color scheme in your app.
Dark	dark	your page doesn’t respond to a user’s`prefer-color-scheme` settings and always has a dark background, or your page has a Dark Mode setting, but doesn’t set the CSS `color-scheme` property to match, and the user has chosen a Dark color scheme in your app.
Auto	system	your page does respond to a user’s `prefer-color-scheme`, or your page sets the CSS `color-scheme` property to match the color-scheme it is displaying.

Specific examples

At night, my Announcement Page header text looks white on a white background

This happens because:

Your operating system or browser:
- may be using an Automatic color scheme. It sets prefers-color-scheme to "light" during the day, and "dark" at night.
The page where you’ve embedded Hub:
- uses a white background at all times,
- does not use a prefers-color-scheme media query to change the background if the user prefers a dark color scheme,
- does not set a color-scheme: light CSS value to indicate that it is using a Light color scheme.
Your Workspace Page Color Scheme is set to “Auto” (if the user’s prefers-color-scheme is "dark") or “Dark”.

You should set your Workspace Page Color Scheme to “Light” to match the behavior of your web page.

When users choose my app’s Dark color scheme, the Hub Announcement Page header text looks black on a black background

This happens because:

The user’s operating system or browser:
- may be using a Light or Automatic color scheme and has currently set prefers-color-scheme to "light".
The page where you’ve embedded Hub:
- uses a black background for this user,
- does not set a color-scheme: dark CSS value to indicate that it is using a Dark color scheme.
Your Workspace Page Color Scheme setting is set to “Auto” (if the user’s prefers-color-scheme is "light") or “Light”.

You should either:

Begin applying the color-scheme CSS property to match your users’ Dark Mode choices and set your Workspace Page Color Scheme to “Auto” to match the behavior of your web page.
Add an explicit color-scheme attribute to your <released-page> element that matches the current user’s choice of light or dark color scheme.