Color schemes

Microbe includes light and dark color schemes in the core stylesheet. Schemes change the color tokens used by the framework, including the lightness scale, foreground and background colors, focus colors, and native form control appearance.

A color scheme is selected by the user's operating system by default, or explicitly with a class. The classes can be applied to the document or to an individual part of an interface, so a page can use the system preference while a component uses a fixed scheme.

Modes

There are three ways to select a scheme:

  • System (default). Do not add a color-scheme class. Microbe starts in light mode and switches to dark mode when the browser matches the prefers-color-scheme: dark media feature.
  • Light. color-scheme-light forces the light palette and light native controls, regardless of the system preference.
  • Dark. color-scheme-dark forces the dark palette and dark native controls, regardless of the system preference.

The classes are ordinary CSS classes; Microbe does not require JavaScript to select a scheme. To change a scheme at runtime, add or remove the class with your own application code. Removing both classes returns the element to system mode.

Applying a scheme

Apply a class to the element that owns the interface. Put the class on the document root to control the whole page:

<html class="microbe color-scheme-dark">...</html>

A scheme can also be scoped to a part of a page. Descendants inherit its color variables and native control preference:

<section class="color-scheme-light">...</section>

When using the core stylesheet, make sure the interface is inside a microbe container. This is normally the document root, as in the first example.

Switching schemes

This example changes the scheme by toggling the classes on a containing element. The selection control is only demo code; an application can use a saved preference, a user setting, or the system preference instead.

We will send you a newsletter every week

Color tokens

Both built-in schemes use the same token names, so components do not need separate light and dark styles. The scheme changes the values behind these tokens:

  • --lightness-0 through --lightness-12 define the palette's lightness steps. See the Palette page for the complete scale.
  • --foreground-lightness and --background-lightness define the default text and surface contrast.
  • --focus-lightness, --focus-outline-width, and --focus-outline-offset adapt focus indicators to the selected contrast.
  • --accent-saturation and --error-saturation adjust semantic accent and error colors for the background.
  • --neutral-hue, --neutral-saturation, and --shadow-color adjust neutral surfaces and shadows.

The light scheme uses a white background and a black foreground. The dark scheme uses a dark background, a light foreground, a reduced accent saturation, and a neutral hue derived from the accent hue. All Microbe components consume these variables, so the same semantic HTML works in either scheme.

Browser preference

Microbe sets the CSS color-scheme property for each mode so the browser can style native controls, scrollbars, and other user-agent UI consistently. The system mode follows prefers-color-scheme: dark; an explicit color-scheme-light or color-scheme-dark class takes precedence over that media query.

Microbe does not store a user's choice or provide a preference switch. If an application offers a selector, it should manage the class and persist the choice as appropriate. The example above demonstrates the smallest possible class-switching implementation.