Dark mode

This page is about developing dark mode for GitLab. For more information on how to enable dark mode, see Profile preferences.

How dark mode works

  1. The color palette values are reversed using design tokens to provide darker colors for smaller scales.
  2. app/assets/stylesheets/themes/_dark.scss imports dark mode design tokens SCSS variables for colors.
  3. app/assets/stylesheets/themes/dark_mode_overrides.scss imports dark mode design tokens CSS custom properties for colors.
  4. Bootstrap variables overridden in app/assets/stylesheets/framework/variables_overrides.scss are given dark mode values in _dark.scss.
  5. _dark.scss is loaded before application.scss to generate separate application_dark.css stylesheet for dark mode users only.

SCSS variables vs CSS custom properties

Design tokens generate both SCSS variables and CSS custom properties which are imported into the dark mode stylesheet.

  • SCSS variables: are used in framework, components, and utility classes and override existing color usage for dark mode.
  • CSS custom properties: are used for any colors within the app/assets/stylesheets/page_bundles directory.

As we do not want to generate separate *_dark.css variants of every page_bundle file, we use CSS custom properties with SCSS variables as fallbacks. This is because when we generate the page_bundles CSS, we get the variable values from _variables.scss, so any SCSS variables have light mode values.

As the CSS custom properties defined in _dark.scss are available in the browser, they have the correct colors for dark mode. 

color: var(--gray-500, $gray-500);

Utility classes

We generate a separate utilities_dark.css file for utility classes containing the inverted values. So a class such as gl-text-white specifies a text color of #333 in dark mode. This means you do not have to add multiple classes every time you want to add a color.

Currently, we cannot set up a utility class only in dark mode. We hope to address that issue soon.

Using different values between light and dark mode

In most cases, we can use the same values for light and dark mode. If that is not possible, you can add an override using the .gl-dark class that dark mode adds to body: 

color: $gray-700;
.gl-dark & {
  color: var(--gray-500);
}
note
Avoid using a different value for the SCSS fallback
// avoid where possible
// --gray-500 (#999) in dark mode
// $gray-700 (#525252) in light mode
color: var(--gray-500, $gray-700);

We plan to add the CSS variables to light mode. When that happens, different values for the SCSS fallback will no longer work.