Color scheme

Semantic Tokens and Dark Mode

You recently built a color ramp from a single seed using oklch() and color-mix(). That ramp gives you raw material: a set of numbered steps like --blue-200 through --blue-800. But raw material is not a system. A system needs names that describe purpose, not appearance, and it needs to respond automatically when the user switches between light and dark mode.

This page teaches the three CSS features that make that possible: the color-scheme property, the prefers-color-scheme media query, and the light-dark() function. Together, they let you write one set of token declarations that the browser resolves differently depending on the active theme. This site uses exactly this approach. Try the theme toggle at the top of the page and watch every color on this page update instantly.

Primitive vs Semantic Tokens

A primitive token describes what a color looks like: --blue-500, --gray-200, --green-700. A semantic token describes what a color does: --color-surface, --color-text, --color-accent. The distinction matters because the same purpose needs different colors in different contexts. Your page background might be a light gray in light mode and a dark navy in dark mode, but it is always "the background." If your components reference --color-bg instead of --gray-100, you can change the underlying value for each theme without touching a single component rule.


        /* Primitive tokens: describe appearance */
        --blue-500: oklch(0.55 0.2 260);
        --gray-100: #f4f6f8;
        --gray-900: oklch(0.22 0.02 260);

        /* Semantic tokens: describe purpose */
        --color-bg: var(--gray-100);
        --color-text: var(--gray-900);
        --color-accent: var(--blue-500);
    

The pattern is straightforward. Define your primitive ramp values first (your seeds), then create semantic tokens that point to the appropriate primitive for each context. When dark mode enters the picture, you do not change the primitives. You change which primitive each semantic token resolves to.

The color-scheme Property

The color-scheme property tells the browser which color modes an element supports. When you set it on the root element, it affects the entire page:


        :root {
            color-scheme: light;
        }
    

This declaration does two things. First, it signals to the browser that the page is in light mode, which affects native UI elements like scrollbars, form controls, and the default canvas color. Second, and more importantly for our purposes, it determines which value the light-dark() function picks. When color-scheme is light, light-dark() returns its first argument. When it is dark, it returns the second.

You can also set color-scheme: light dark to let the browser choose based on the operating system preference. But for a custom theme toggle, you typically set it to one or the other explicitly, then flip it based on user interaction.

How This Site Handles It

This course site sets color-scheme: light as the default on :root. When you pick a theme from the toggle at the top of the page, a CSS :has() selector detects which radio input is checked and overrides color-scheme to dark or light accordingly. The system option uses prefers-color-scheme to match your OS. No JavaScript is required for the switch itself.

prefers-color-scheme

The prefers-color-scheme media query reads the color mode preference from the operating system. It has two values: light and dark.


        @media (prefers-color-scheme: dark) {
            :root {
                color-scheme: dark;
            }
        }
    

This is the automatic approach. If the user has their OS set to dark mode, the media query matches, and you flip color-scheme to dark. Every light-dark() call on the page immediately resolves to its second value. If you combine this with a manual toggle (like this site does), the media query handles the "system default" option while the toggle handles the explicit light and dark choices.

The :has() Toggle Pattern

A common pattern for building a theme toggle without JavaScript is to use hidden radio inputs and :has() on the html element. When a radio with a specific value is checked, a selector like html:has(input[name='theme-preference'][value='dark']:checked) matches and sets color-scheme: dark. The system option wraps its color-scheme flip inside a prefers-color-scheme: dark media query so it only activates when the OS is dark. This is exactly the pattern this site uses.


            /* Default */
            :root {
                color-scheme: light;
            }

            /* User chose dark */
            html:has(input[name='theme-preference'][value='dark']:checked) {
                color-scheme: dark;
            }

            /* User chose system and OS is dark */
            @media (prefers-color-scheme: dark) {
                html:has(input[name='theme-preference'][value='system']:checked) {
                    color-scheme: dark;
                }
            }
        

light-dark()

The light-dark() function accepts two values and returns one of them based on the computed color-scheme of the element. If the scheme is light, it returns the first value. If the scheme is dark, it returns the second.


        :root {
            color-scheme: light;

            --seed-bg: #f4f6f8;
            --color-bg: light-dark(var(--seed-bg), oklch(0.18 0.02 260));
        }
    

In light mode, --color-bg resolves to the seed value (#f4f6f8, a near-white gray). In dark mode, it resolves to the second value (oklch(0.18 0.02 260), a very dark blue-gray). The component rules that reference --color-bg never change. Only the token definition knows about both modes.

This is the core idea. Every semantic token gets one light-dark() call. The light value is typically your seed or a direct reference to it. The dark value can be a handpicked color, or it can be derived from the seed using the color-mix() or relative color techniques you learned on the previous page.


        :root,
        html {
            --seed-text: #1e293b;
            --seed-surface: #ffffff;
            --seed-accent: #006eb6;

            --color-text: light-dark(
                var(--seed-text),
                oklch(0.88 0.02 260)
            );
            --color-surface: light-dark(
                var(--seed-surface),
                oklch(0.22 0.03 260)
            );
            --color-accent: light-dark(
                var(--seed-accent),
                oklch(0.62 0.15 240)
            );
        }
    

The light-dark() function requires color-scheme to be set on the element or an ancestor. If no color-scheme is declared, the function may not resolve as expected. Always set color-scheme on :root or html.

Wiring It Together

The full pattern has three layers. First, declare your seed colors as primitive tokens. Second, set color-scheme on the root and provide a way to flip it (media query, toggle, or both). Third, define semantic tokens using light-dark() where each call maps a seed to both its light and dark appearance.

The card below follows this exact pattern. Its background, text, border, and accent colors all use semantic tokens defined with light-dark(). We copied the color mode toggle from the top of this page and added it to the card. Use it to switch themes and see the card update automatically.

Semantic Tokens in Action
Every color here is a light-dark() pair

This card uses six semantic tokens. The background, text, muted text, accent, border, and badge colors all flip automatically when you toggle the site theme. No class changes, no duplicate rulesets, no JavaScript.

light-dark()
Color scheme

Notice that the component CSS references only semantic token names. It has no idea what "light mode" or "dark mode" actually look like. All of that knowledge lives in the token definitions on :root.

accent-color

Native HTML form controls (checkboxes, radio buttons, range sliders, progress bars) use the browser's default colors. The accent-color property lets you tint them to match your theme without rebuilding the controls from scratch:


        :root {
            accent-color: var(--color-accent);
        }
    

Since --color-accent is already a light-dark() token, the native controls automatically pick up the appropriate accent for each theme. This one line of CSS handles checkboxes, radios, range inputs, and progress bars across both modes.

Limitations of accent-color

The accent-color property only affects the accent tint. It does not give you full control over the control's appearance. If you need to style the track of a range slider, the check mark shape, or the border of a checkbox, you still need appearance: none and custom styling. But for simple brand alignment, accent-color does the job with minimal effort.

Testing Both Themes

Dark mode is easy to implement and easy to implement badly. Colors that look fine in light mode can become unreadable, washed out, or glaring in dark mode. Before you consider your token system complete, verify these things in both themes:

  • Body text is readable against the background with sufficient contrast (at least 4.5:1 for normal text, 3:1 for large text)
  • Links are distinguishable from surrounding text in both modes
  • Borders are visible but not harsh against the surface color
  • Form controls (inputs, selects, buttons) do not disappear into the background
  • Status colors (success, warning, error) remain distinct and meaningful
  • Images and media do not blind the user in dark mode (consider reducing brightness or adding a subtle overlay)
  • Shadows are visible but not overdone (dark mode needs softer, more transparent shadows than light mode)

Use your browser's DevTools to emulate prefers-color-scheme: dark without changing your OS settings. In Chrome, open DevTools, press Ctrl+Shift+P (or Cmd+Shift+P on macOS), type "color scheme," and select the emulation option. This lets you test both modes quickly without flipping your entire system back and forth.

Check Your Understanding

Apply your knowledge by working through this coding exercise. A set of seed tokens and a color-scheme declaration are provided. Your job is to create semantic tokens using light-dark() that map each seed to an appropriate dark mode alternative. Use the copy icon to copy your completed code and paste it as a prompt to your AI assistant for feedback.


        /**
         * Create semantic tokens using light-dark().
         *
         * The seed tokens and color-scheme are done for you.
         * For each semantic token, the light value should
         * reference the seed with var(). The dark value should
         * be an oklch() color you choose.
         *
         * Dark mode guidelines:
         *   - Surface colors: lightness around 0.18 to 0.25
         *   - Text colors: lightness around 0.85 to 0.92
         *   - Accent colors: slightly lighter than the light
         *     version, with reduced chroma
         *   - Borders: lightness around 0.30 to 0.35
         */

        :root {
            color-scheme: light;

            /* --- Seeds (do not change these) --- */
            --seed-bg: #f4f6f8;
            --seed-surface: #ffffff;
            --seed-text: #1e293b;
            --seed-accent: #006eb6;
            --seed-border: #e2e8f0;

            /* --- Semantic tokens (fill these in) --- */
            --color-bg: light-dark(var(--seed-bg), /* dark value */);
            --color-surface: /* your turn */
            --color-text: /* your turn */
            --color-accent: /* your turn */
            --color-border: /* your turn */
        }