One theme.css to Rule Every Color: Three Token Layers Collapse 84 Hardcoded Hex Values into a Single data-theme Override
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.
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.
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.