跪拜 Guibai
← All articles
CSS · Frontend · Frontend Engineering

One theme.css to Rule Every Color: Three Token Layers Collapse 84 Hardcoded Hex Values into a Single data-theme Override

By ENCI ·
Read original on juejin.cn ↗ Google Translate ↗ Alt translation

A rebrand or dark-mode sprint without a token layer means auditing dozens of scattered hex literals by eye, with tests blind to the result. One theme.css with a three-layer token structure makes the same change a single data-theme override, and the runnable template documents the Vite CSS-ordering and FOUC traps most codebases hit anyway.

Summary

Hardcoding colors across component files moves the cost to the first rebrand: 84 literals scattered over 12 files each have to be inspected to find which are the brand color and which were intentional. Different components write the same "secondary text" gray as #666, #6b7280, and rgba(0,0,0,.6), and tests can't catch any of it because component tests assert DOM, not paint. A single theme.css is the only file allowed to contain hex literals, describing what each color is for rather than what any component looks like.

Values are organized into three layers: primitive values hold the raw colors (--gray-900, --brand-500), semantic values say what a color is for (--text-primary, --bg-card) and point at primitives, and component values expose per-component knobs (--button-bg). Components may only reference the semantic and component layers. A dark theme is just a [data-theme="dark"] block after :root that overrides the semantic layer, so components keep the same variable names and redraw with zero edits.

A build-free, dependency-free example shows the full loop: it reads the saved theme from localStorage in a synchronous <head> script before first paint to avoid a white flash, and declares color-scheme: light dark so scrollbars and form controls follow the theme. The approach has a drawn boundary: static pages with five colors and no second theme, style-isolated micro-frontends, and projects where a third-party UI library reads neither your variables nor your intent. The test for any project is whether one color change touches one file.

Takeaways
— One rule defines the setup: theme.css is the only file where color literals like #2563eb may appear; any hex value in another .css, .vue, or .tsx file counts as a violation.
— Colors live in three layers: primitive (--gray-900), semantic (--text-primary), component (--button-bg); components may reference only the semantic and component layers.
— A medium project with 12 component files, each holding 7 hardcoded colors, carries 84 literals that a rebrand must touch. A token setup reduces that to one definition and zero component changes.
— Sass variables compile into constants, so they cannot respond to a runtime theme switch; CSS custom properties resolve in the browser and inherit down the DOM.
— Theme switching works by placing a [data-theme="dark"] block after :root; with equal specificity (both 0,1,0), source order decides which values win.
— Avoid FOUC by reading the stored theme in a synchronous <head> script before first paint, then falling back to prefers-color-scheme; the order is always local storage > system preference > light default.
— Declare color-scheme: light dark on :root so scrollbars, form controls, and the default focus ring follow the theme; without it, a dark page shows a white scrollbar.
— Component styles must load after theme.css because var() on an undefined variable resolves to nothing and elements render transparent; Vite's CSS code splitting can inject component styles first in production, so the theme file must be imported first at the entry.
— The listed pitfalls: writing literals back into semantic variables, naming variables by color (--blue-500) instead of purpose, skipping transitions, using !important to override tokens, and piling 300 ungrouped variables into :root.
— Skip the global theme.css for a single static page with no second theme, for micro-frontends whose children isolate styles, and for projects dominated by a third-party UI library that won't read your tokens; there, align the library's config with your semantic variables instead of re-theming.
Conclusions

A hex value hand-written a third time already functions as the project's de facto standard, just one hidden across three files with no one knowing who decides. Enforcing a single source of truth is an exercise in recognizing standards that were never declared.

Sass variables compile away into constants, so no preprocessor-based theme system can survive a runtime switch; CSS custom properties resolve in the browser and inherit down the DOM, which is the only thing that makes runtime theming possible.

Dark mode changes what a color is for, never the color itself. Overriding the semantic layer alone works because components are forbidden from touching primitive values; that one restriction is what makes zero-component-change theming possible.

One test outperforms every token-layer checklist: "how many files does one color change touch?" When the answer is 1, theming stops being a burden; when the answer is a dozen, the first move is cleaning up scattered literals, not adding variables.

Concepts & terms
Design Tokens
Named values that encode design decisions such as colors, spacing, and radii. Here they are organized in three layers — primitive, semantic, component — so a theme switch only overrides the semantic layer and components never reference raw values.
FOUC
Flash of Unstyled Content: the visible flash of the light theme that appears when a theme script runs after the browser's first paint. The fix is reading the saved theme in a synchronous <head> script that executes before first paint.
prefers-color-scheme
A CSS media query that detects whether the user's OS or browser declares a light or dark preference. It can only seed a default value, never override the user's manual choice on the site.
color-scheme
A CSS property on :root that tells the browser to render scrollbars, form controls, and default focus rings in the matching theme colors; without it, a dark page shows a white scrollbar.
Source: juejin.cn ↗ Google Translate ↗ Backup ↗