A practical CSS variable setup for light/dark mode without theme flash

Dark mode is easy to start.

It is harder to ship cleanly.

Most implementations need to handle:

light mode
dark mode
system preference
stored user preference
a toggle button
no flash of the wrong theme on page load

The flash is the annoying part.

You save the user's choice in localStorage, but your app JavaScript usually runs after the browser has already started parsing HTML and CSS.

So the page may briefly render in the wrong theme before your JavaScript applies the saved preference.

This article shows a practical setup using:

CSS variables
data-theme on <html>
prefers-color-scheme
localStorage
a tiny inline script in <head>

No framework required.

The goal

I want components to use semantic variables like this:

body {
  background: var(--color-background);
  color: var(--color-text);
}

.card {
  background: var(--color-surface);
  border: 1px solid var(--color-border);
}

.button {
  background: var(--color-primary);
  color: var(--color-on-primary);
}

The component should not care whether the app is currently light or dark.

Only the variable values should change.

Define light mode variables

Start with light mode as the default.

:root {
  color-scheme: light;

  --color-background: #ffffff;
  --color-surface: #f8fafc;
  --color-text: #0f172a;
  --color-muted: #64748b;
  --color-border: #e2e8f0;

  --color-primary: #2563eb;
  --color-on-primary: #ffffff;
}

This means that if nothing else happens, the site renders in light mode.

That is a safe default.

Add explicit dark mode

Now add dark mode using data-theme="dark" on the root element.

:root[data-theme="dark"] {
  color-scheme: dark;

  --color-background: #020617;
  --color-surface: #0f172a;
  --color-text: #f8fafc;
  --color-muted: #94a3b8;
  --color-border: #1e293b;

  --color-primary: #60a5fa;
  --color-on-primary: #020617;
}

When this attribute exists:

<html data-theme="dark">

the dark variables override the light variables.

Add system preference support

Users may have an OS-level preference for dark mode.

You can respect that with prefers-color-scheme.

@media (prefers-color-scheme: dark) {
  :root:not([data-theme="light"]) {
    color-scheme: dark;

    --color-background: #020617;
    --color-surface: #0f172a;
    --color-text: #f8fafc;
    --color-muted: #94a3b8;
    --color-border: #1e293b;

    --color-primary: #60a5fa;
    --color-on-primary: #020617;
  }
}

The important part is this selector:

:root:not([data-theme="light"])

It means:

Use system dark mode unless the user explicitly selected light mode.

So the behavior becomes:

User choice	Result
No saved choice + OS light	light
No saved choice + OS dark	dark
Saved `light`	light
Saved `dark`	dark

Prevent the wrong theme from flashing

This is the critical piece.

Add a small inline script in <head> before your theme CSS.

<script>
  (function () {
    try {
      var storedTheme = localStorage.getItem('theme');

      if (storedTheme === 'light' || storedTheme === 'dark') {
        document.documentElement.setAttribute('data-theme', storedTheme);
      }
    } catch (_) {}
  })();
</script>

Do not run this script after the page loads.

Avoid:

<script defer src="/theme.js"></script>

Avoid:

document.addEventListener('DOMContentLoaded', ...)

The script should run immediately while the browser is still parsing the <head>.

Why?

Because the browser reads the document top to bottom.

If this script sets data-theme="dark" before the CSS is applied, the correct variables are active before the first paint.

That prevents the wrong theme from flashing.

Recommended HTML structure

Put the inline script before the CSS.

<!doctype html>
<html lang="en">
  <head>
    <script>
      (function () {
        try {
          var storedTheme = localStorage.getItem('theme');

          if (storedTheme === 'light' || storedTheme === 'dark') {
            document.documentElement.setAttribute('data-theme', storedTheme);
          }
        } catch (_) {}
      })();
    </script>

    <style>
      :root {
        color-scheme: light;

        --color-background: #ffffff;
        --color-surface: #f8fafc;
        --color-text: #0f172a;
        --color-muted: #64748b;
        --color-border: #e2e8f0;

        --color-primary: #2563eb;
        --color-on-primary: #ffffff;
      }

      :root[data-theme="dark"] {
        color-scheme: dark;

        --color-background: #020617;
        --color-surface: #0f172a;
        --color-text: #f8fafc;
        --color-muted: #94a3b8;
        --color-border: #1e293b;

        --color-primary: #60a5fa;
        --color-on-primary: #020617;
      }

      @media (prefers-color-scheme: dark) {
        :root:not([data-theme="light"]) {
          color-scheme: dark;

          --color-background: #020617;
          --color-surface: #0f172a;
          --color-text: #f8fafc;
          --color-muted: #94a3b8;
          --color-border: #1e293b;

          --color-primary: #60a5fa;
          --color-on-primary: #020617;
        }
      }
    </style>
  </head>

  <body>
    <button id="theme-toggle" type="button">
      Toggle theme
    </button>
  </body>
</html>

Add the toggle function

Now add a simple toggle.

function toggleTheme() {
  var html = document.documentElement;
  var currentTheme = html.getAttribute('data-theme');

  var nextTheme = currentTheme === 'dark' ? 'light' : 'dark';

  html.setAttribute('data-theme', nextTheme);
  localStorage.setItem('theme', nextTheme);
}

document
  .getElementById('theme-toggle')
  ?.addEventListener('click', toggleTheme);

Now clicking the button switches between:

<html data-theme="light">

and:

<html data-theme="dark">

Add a system mode option

A good theme switcher often has three options:

light
dark
system

For system mode, remove the attribute and clear localStorage.

function resetToSystemTheme() {
  document.documentElement.removeAttribute('data-theme');
  localStorage.removeItem('theme');
}

Now the browser falls back to:

@media (prefers-color-scheme: dark) {
  :root:not([data-theme="light"]) {
    /* dark variables */
  }
}

Why `color-scheme` matters

This line is easy to forget:

color-scheme: light;

and:

color-scheme: dark;

It tells the browser which color scheme your page supports.

That affects built-in UI such as:

form controls
scrollbars
default input styling
browser-rendered UI pieces

So your page does not only change your custom CSS variables. Native browser UI also gets a better matching appearance.

Component CSS stays simple

Once the variables are defined, component CSS becomes boring.

That is good.

body {
  margin: 0;
  background: var(--color-background);
  color: var(--color-text);
  font-family: system-ui, sans-serif;
}

.card {
  background: var(--color-surface);
  border: 1px solid var(--color-border);
  border-radius: 12px;
  padding: 1rem;
}

.card-muted {
  color: var(--color-muted);
}

.button {
  background: var(--color-primary);
  color: var(--color-on-primary);
  border: 0;
  border-radius: 8px;
  padding: 0.625rem 1rem;
  cursor: pointer;
}

There is no separate .dark .button rule.

The variables handle the mode.

The limitation

This setup solves the theme switching structure.

It does not solve color design for you.

You still need to decide:

which light colors to use
which dark colors to use
whether text has enough contrast
what hover/pressed/disabled states should be
what color should go on top of primary buttons
how semantic colors like success/warning/danger behave in both modes

For a small project, manually writing variables may be enough.

For a larger system, it becomes repetitive.

Generating the variables instead

This is why I started working on salt-theme-gen.

Instead of manually maintaining separate light and dark token files, you can generate both modes from one call:

import { generateTheme } from 'salt-theme-gen';

const theme = generateTheme({ preset: 'ocean' });

That returns:

theme.light;
theme.dark;

Each mode has the same structure:

theme.light.colors;
theme.light.states;
theme.light.spacing;
theme.light.radius;
theme.light.fontSizes;
theme.light.accessibility;

So the CSS variable setup can be generated instead of handwritten.

For example:

function kebab(str: string): string {
  return str.replace(/([A-Z])/g, '-$1').toLowerCase();
}

function modeToVars(mode: typeof theme.light): string {
  const lines: string[] = [];

  for (const [key, value] of Object.entries(mode.colors)) {
    lines.push(`  --color-${kebab(key)}: ${value};`);
  }

  for (const [key, value] of Object.entries(mode.spacing)) {
    lines.push(`  --space-${key}: ${value}px;`);
  }

  for (const [key, value] of Object.entries(mode.radius)) {
    lines.push(`  --radius-${key}: ${value}px;`);
  }

  for (const [key, value] of Object.entries(mode.fontSizes)) {
    lines.push(`  --text-${key}: ${value}px;`);
  }

  return lines.join('\n');
}

Then:

const themeCSS = `
:root {
  color-scheme: light;
${modeToVars(theme.light)}
}

:root[data-theme="dark"] {
  color-scheme: dark;
${modeToVars(theme.dark)}
}
`;

The browser still uses the same CSS variable strategy.

The difference is that the design tokens are generated from a system instead of being maintained by hand.

The bottom line

A reliable light/dark setup does not need to be complicated.

The key pieces are:

CSS variables for tokens
data-theme on <html>
prefers-color-scheme for system fallback
localStorage for user preferences
inline script in <head> to avoid theme flash

The most important rule:

Set the saved theme before the CSS is applied.

After that, your components can stay clean:

background: var(--color-background);
color: var(--color-text);

The values change between light and dark mode.

The component contract stays the same.

推荐订阅源

DEV Community

The goal

Define light mode variables

Add explicit dark mode

Add system preference support

Prevent the wrong theme from flashing

Recommended HTML structure

Add the toggle function

Add a system mode option

Why `color-scheme` matters

Component CSS stays simple

The limitation

Generating the variables instead

The bottom line

推荐订阅源

DEV Community

The goal

Define light mode variables

Add explicit dark mode

Add system preference support

Prevent the wrong theme from flashing

Recommended HTML structure

Add the toggle function

Add a system mode option

Why color-scheme matters

Component CSS stays simple

The limitation

Generating the variables instead

The bottom line

Why `color-scheme` matters