basforge

Search titles, text and the “If it doesn’t work” cases.

    RU
    ConfigDesignColor

    A palette in CSS: role-based tokens for the light and dark themes

    Define colors once — as role-based variables in :root — and let components use only var(--…). Dark mode is the same names with other values: it turns on by system setting or by toggle, and a small script in <head> applies the choice before the first paint. Here’s this site’s tokens file, line by line.

    How it works

    Components know only the names: background: var(--raised), color: var(--ink-3). The values live in one file, in three places: the light ones in :root, the dark ones for the toggle and for the system theme. The theme changes by substituting other values under the same names, without touching the components’ CSS.

    The file

    src/styles/tokens.css — shortened, by role
    :root {
      color-scheme: light;
    
      --ground: #f4f2ee;
      --raised: #ffffff;
      --sunken: #f0ece5;
      --ink: #1a1816;
      --ink-2: #4a4540;
      --ink-3: #66605a;
      --line: #e3ded5;
      --line-strong: #d3ccc0;
    }
    Key part

    Names by role: the page background, a card, a field; three levels of text; lines. Compute pairs, not colors: --ink-3 on --ground is 5.55:1, on --raised 6.20:1, on --sunken 5.27:1, so a caption passes AA on any of the site’s backgrounds. color-scheme: light tells the browser its fields and scrollbars are light.

    default:color-scheme normal

    :root {
      --accent: #cc3f23;
      --accent-hover: #b73519;
      --accent-ink: #bc3a1f;
      --accent-soft: rgba(204, 63, 35, 0.09);
      --on-accent: #ffffff;
    }

    One accent, five roles. --accent is the button fill; white text on it is 4.88:1. The same color as text on the #f4f2ee background is 4.37:1, short of AA, so links get their own slightly darker --accent-ink: 4.99:1. --accent-soft is a 9% tint, --on-accent the text on the fill: in dark mode it turns dark.

    :root {
      --ok: #2e7d4f;
      --ok-soft: rgba(46, 125, 79, 0.1);
      --warn: #9a4e0a;
      --warn-soft: rgba(240, 160, 40, 0.14);
      --on-warn: #ffffff;
    }

    States. --ok on the background is 4.51:1, a hundredth above the threshold; --warn is 5.42:1, and white text on it 6.06:1. The pale -soft ones are tints under blocks; text on them stays the regular --ink.

    :root[data-theme='dark'] {
      color-scheme: dark;
    
      --ground: #131210;
      --raised: #1f1d1a;
      --ink: #f2eee8;
      --ink-3: #a39b90;
      --accent: #ff7a55;
      --accent-ink: #ff9473;
      --on-accent: #1a0d08;
      /* … the remaining tokens — same names */
    }
    Key part

    The toggle’s choice is a data-theme attribute on <html>. Same names, values picked anew: the background isn’t black and the text isn’t white — 16.2:1, captions #a39b90 at 6.82:1. The old accent #cc3f23 would give 3.84:1 on the dark background; the new #ff7a55 gives 7.28:1. White text on it is 2.57:1, so --on-accent is dark: 7.39:1.

    @media (prefers-color-scheme: dark) {
      :root:not([data-theme='light']) {
        color-scheme: dark;
    
        --ground: #131210;
        /* … the same dark set in full */
      }
    }

    The system theme — until light is chosen with the toggle. Without :not([data-theme='light']) a dark system would override the choice. The cost: the dark set is written in the file twice, and a dark color is edited in two places.

    :root {
      color-scheme: light dark;
    
      --ground: light-dark(#f4f2ee, #131210);
      --ink: light-dark(#1a1816, #f2eee8);
      --accent: light-dark(#cc3f23, #ff7a55);
    }
    
    :root[data-theme='light'] {
      color-scheme: light;
    }
    
    :root[data-theme='dark'] {
      color-scheme: dark;
    }

    A version without the repetition: light-dark() takes the first value with a light scheme and the second with a dark one, and color-scheme sets the scheme — by system or by toggle. Each color is one line; Chrome 123, Firefox 120, Safari 17.5. This site doesn’t use it: some dark values aren’t colors. Shadows in dark mode have a different shape, a 0 0 0 1px ring instead of a soft shadow, and --when-dark switches display; light-dark() chooses only between colors or images.

    The choice — before the first paint

    <script>
      try {
        const theme = localStorage.getItem('theme');
        if (theme === 'light' || theme === 'dark') document.documentElement.dataset.theme = theme;
      } catch {}
    </script>

    The script sits in <head> and is a plain one — not a module and without defer: the browser runs it while parsing <head>, and the page paints in the chosen theme right away. In Astro such a script is written with is:inline; otherwise Astro bundles it into a module, and it runs after the paint. The try covers the case where the site isn’t allowed to store data: then accessing localStorage throws. The toggle writes the choice to localStorage.theme and sets the same attribute; without a choice there’s no attribute, and the system decides the theme.

    The color of the browser’s bar on a phone is set by HTML, which CSS variables don’t reach — these are the site’s only hex values outside the tokens file:

    <meta name="theme-color" media="(prefers-color-scheme: light)" content="#F4F2EE" />
    <meta name="theme-color" media="(prefers-color-scheme: dark)" content="#131210" />

    How to check

    • DevTools, the Rendering panel, Emulate CSS media feature prefers-color-scheme: dark — the site goes dark without the toggle. Choose light with the toggle — the site stays light even under the dark emulation.
    • Check the contrast of every text token in both themes with the DevTools picker (Text contrast).

    Find hex values outside the tokens file like this — here only the two theme-color lines turn up; anything else would be a color bypassing the palette:

    grep -rnE '#[0-9a-fA-F]{3,8}' src --include=*.css --include=*.astro | grep -v tokens.css

    If it doesn’t work

    The theme switched, but some elements stayed light

    Cause
    A component has a color written as a hex value instead of a token, and the dark set doesn’t change it.
    Fix
    Find hex values outside the tokens file — grep -rnE '#[0-9a-fA-F]{3,8}' src --include=*.css --include=*.astro | grep -v tokens.css — and replace them with var(--…).

    Chose the light theme, and with a dark system the site is still dark

    Cause
    The dark set in @media (prefers-color-scheme: dark) sits on a bare :root and overrides the toggle’s choice.
    Fix
    Use the condition :root:not([data-theme='light']): the system theme applies until light is chosen.

    Dark mode flashes light on every navigation

    Cause
    The choice from localStorage is read by a script at the end of <body>, with defer or as a module — the page manages to paint light first.
    Fix
    Put the script in <head>, a plain one, without defer or type=module: it runs before the first paint. In Astro, <script is:inline>.

    light-dark() always returns the light value

    Cause
    The element has no color-scheme that includes dark: the function looks at that, not at the system theme directly.
    Fix
    color-scheme: light dark on :root; the toggle switches color-scheme to light or dark.