@k8ordo/color-scheme

Styling

Read the dark class on <html> in your stylesheet to switch to the dark colors. It works with Tailwind CSS or plain CSS.

On this page

Where the class goes

html
<html class="dark">

The dark class goes on <html> only when the scheme resolves to dark. Light adds nothing, and there is no light class. Neither the name nor the element can be changed.

ColorSchemeScript adds the class before the first paint, and ColorSchemeProvider adds and removes it after that. A stylesheet only has to read the class to follow the visitor’s choice.

@k8ordo/ui’s tokens and the dark: and light: variants of its tailwind.css read this class. See Theming in @k8ordo/ui under “Dark mode”.

With Tailwind CSS alone

globals.css
@import 'tailwindcss';

@custom-variant dark (&:where(.dark, .dark *));
Redeclares `dark:` to read the class

Tailwind CSS 4’s dark: reads prefers-color-scheme by default, so it follows the OS and ignores the visitor’s choice.

With plain CSS

globals.css
:root {
  color-scheme: light;
  --page-bg: #ffffff;
  --page-fg: #1f1f1f;
}

:root.dark {
More specific than `:root`
  color-scheme: dark;
  --page-bg: #1f1f1f;
  --page-fg: #f5f5f5;
}

body {
  background: var(--page-bg);
  color: var(--page-fg);
}

Keep the colors in custom properties and switch them under :root.dark. A bare .dark is as specific as :root, so whichever comes later wins. With :root.dark, the dark values take precedence even when the light ones come later.

The color-scheme property

globals.css
:root {
  color-scheme: light dark;
  color-scheme: light;
}

.dark {
  color-scheme: dark;
}

The color-scheme property sets the scheme of what the browser draws itself, such as scrollbars and form controls. This package does not set it. Without @k8ordo/ui, declare it yourself next to your colors.

With light dark, the browser picks the scheme from prefers-color-scheme. With the OS on dark and the visitor on light, scrollbars and form controls are drawn dark, against the visitor’s choice. Switch it with the same class as the colors.

Once color-scheme follows the class, the light-dark() function does too. It takes the light and dark values in one declaration, as in color: light-dark(#1f1f1f, #f5f5f5).

The browser’s own UI

src/routes/layout.tsx
<head>
  <ColorSchemeScript
    themeColor={{ light: '#ffffff', dark: '#1f1f1f' }}
  />
</head>

The address bar and the status bar take their color from <meta name="theme-color">. One whose media names a prefers-color-scheme follows the OS, not the visitor’s choice.

Pass the light and dark colors to ColorSchemeScript’s themeColor, and the script writes the theme-color <meta> along with the class. After hydration, ColorSchemeProvider updates them as the choice changes.

Once the visitor chooses, or with a 'light' or 'dark' default, that scheme’s color applies whatever the OS says. With a 'system' default and nothing chosen, a <meta> per scheme follows the OS.

The colors are written into the script. What to pass when allowing it by hash is covered in CSP.

Warning

Pitfall

Do not render a theme-color <meta> of your own. React writes <meta> after the stylesheets, behind the ones the script wrote, so it never applies.

OS contrast settings

globals.css
@media (prefers-contrast: more) {
  :root {
    --page-fg: #000000;
  }

  :root.dark {
    --page-fg: #ffffff;
  }
}

prefers-contrast: more and forced-colors: active are OS settings; this package neither stores nor toggles them. When your own CSS supports them, give values for both light and dark.

@k8ordo/ui’s stylesheet holds high-contrast values for both :root and .dark, so they apply in either scheme. See Theming in @k8ordo/ui under “High contrast”.

k8ordo

React libraries that use Baseline features without holding back.