You've hit the wall. You defined --blue: #3B82F6, used it in 40 components, and then the client wanted a different blue. You changed the value and half the app broke because --blue was doing triple duty — buttons, informational alerts, link colors, focus rings. The variable was convenient, not architectural. A CSS variables color system that actually supports theming requires three distinct layers: primitives, semantics, and components. Most developers only build one of them.
No boilerplate setup, no beginner explanations of what var() does. You know the syntax. What follows is the correct structural pattern — the one that makes dark mode trivial, brand updates atomic, and component refactors possible without touching tokens.
CSS Variables vs Sass Variables: Why Native Wins
Sass variables are compiled at build time. They resolve to static values in the output CSS. There is no variable at runtime — the browser sees color: #3B82F6, not color: $brand-blue. This means Sass variables cannot respond to user preferences, system dark mode, runtime theme switches, or JavaScript manipulation.
CSS custom properties exist at runtime. They live in the cascade. They can be overridden by any selector with higher specificity, read and written by JavaScript, and they respond to @media (prefers-color-scheme: dark) or an attribute selector like [data-theme="dark"] the same way any other CSS property does.
The practical consequence: a theme switch with CSS custom properties is one JavaScript line and one CSS block. With Sass variables, it's a stylesheet swap and a flash of unstyled content.
The Three-Layer Architecture
Layer 1: Primitive Tokens
Primitives are raw values. They have no semantic meaning. They are never used directly in component styles. Their only job is to give names to the raw color options available in your system.
:root {
/* Color primitives — the palette, nothing more */
--color-blue-500: #3B82F6;
--color-blue-400: #60A5FA;
--color-blue-600: #2563EB;
--color-slate-50: #F8FAFC;
--color-slate-100: #F1F5F9;
--color-slate-200: #E2E8F0;
--color-slate-500: #64748B;
--color-slate-800: #1E293B;
--color-slate-900: #0F172A;
--color-slate-950: #020617;
--color-white: #FFFFFF;
--color-black: #000000;
/* Typography primitives */
--font-sans: 'Inter', system-ui, sans-serif;
--font-mono: 'JetBrains Mono', 'Fira Code', monospace;
--font-serif: 'Playfair Display', Georgia, serif;
/* Radius primitives */
--radius-2: 2px;
--radius-4: 4px;
--radius-8: 8px;
--radius-12: 12px;
--radius-16: 16px;
--radius-full: 9999px;
}These values never appear in a component stylesheet. If you find yourself writing color: var(--color-blue-500) in a button component, that's a red flag — you've skipped the semantic layer.
Layer 2: Semantic Tokens
Semantics are role-based aliases. They point to primitives and give them UI meaning. These are what components reference. This is also the layer you override for theming.
:root {
/* Surface colors — background hierarchy */
--color-bg: var(--color-white);
--color-surface: var(--color-slate-50);
--color-surface-raised: var(--color-white);
--color-surface-overlay: var(--color-white);
/* Border */
--color-border: var(--color-slate-200);
/* Text */
--color-text: var(--color-slate-900);
--color-text-muted: var(--color-slate-500);
/* Accent — the brand color in context */
--color-accent: var(--color-blue-500);
--color-accent-hover: var(--color-blue-600);
--color-accent-soft: rgba(59, 130, 246, 0.08);
--color-accent-fg: var(--color-white); /* text on accent bg */
/* Typography semantics */
--font-heading: var(--font-sans);
--font-body: var(--font-sans);
--font-code: var(--font-mono);
/* Radius semantics */
--radius-sm: var(--radius-4);
--radius-base: var(--radius-8);
--radius-lg: var(--radius-12);
--radius-xl: var(--radius-16);
/* Shadow semantics */
--shadow-sm: 0 1px 2px rgba(15, 23, 42, 0.05);
--shadow-base: 0 1px 3px rgba(15, 23, 42, 0.08), 0 4px 16px rgba(15, 23, 42, 0.06);
--shadow-lg: 0 4px 6px rgba(15, 23, 42, 0.07), 0 10px 40px rgba(15, 23, 42, 0.10);
}Every semantic token encodes intent, not value. --color-accent means "the interactive brand color." --color-surface means "the elevated container background." When you read a component that uses var(--color-accent), you know its role without checking what the resolved value is.
Layer 3: Component Tokens
Component tokens are semantic aliases scoped to a specific component. They're optional — small systems skip this layer entirely — but for larger applications they provide a critical benefit: you can reskin a single component without touching the global semantic layer.
/* Button component tokens */
.btn-primary {
--btn-bg: var(--color-accent);
--btn-bg-hover: var(--color-accent-hover);
--btn-text: var(--color-accent-fg);
--btn-radius: var(--radius-base);
--btn-shadow: var(--shadow-sm);
background: var(--btn-bg);
color: var(--btn-text);
border-radius: var(--btn-radius);
box-shadow: var(--btn-shadow);
transition: background 0.15s ease;
}
.btn-primary:hover {
--btn-bg: var(--btn-bg-hover);
}
/* Card component tokens */
.card {
--card-bg: var(--color-surface);
--card-border: var(--color-border);
--card-radius: var(--radius-lg);
--card-shadow: var(--shadow-base);
--card-padding: 24px;
background: var(--card-bg);
border: 1px solid var(--card-border);
border-radius: var(--card-radius);
box-shadow: var(--card-shadow);
padding: var(--card-padding);
}Components reference their own tokens. Their own tokens reference semantics. Semantics reference primitives. The chain is explicit, traceable, and auditable.
Dark Mode Is Now Trivial
With the three-layer architecture in place, implementing dark mode is a semantic token override. You never touch primitives. You never touch component styles. You add one block:
[data-theme="dark"] {
/* Override semantic tokens only */
--color-bg: #0D1117;
--color-surface: #161B22;
--color-surface-raised: #1C2128;
--color-surface-overlay: #21262D;
--color-border: #30363D;
--color-text: #E6EDF3;
--color-text-muted: #8B949E;
/* Accent desaturated for dark context */
--color-accent: #58A6FF;
--color-accent-hover: #79B8FF;
--color-accent-soft: rgba(88, 166, 255, 0.10);
--color-accent-fg: #0D1117;
/* Shadows replaced — invisible on dark surfaces */
--shadow-sm: none;
--shadow-base: none;
--shadow-lg: none;
}Every component that uses var(--color-surface) now gets #161B22 in dark mode. Every button using var(--color-accent) gets the dark-calibrated blue. Nothing else changed. One override block, full application retheme.
// Toggle dark mode — one line
document.documentElement.setAttribute('data-theme', isDark ? 'dark' : 'light');
// Respect system preference on load
const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
document.documentElement.setAttribute('data-theme', prefersDark ? 'dark' : 'light');Atomic Brand Color Update
A client approves a new brand blue. The old one was #3B82F6. The new one is #0EA5E9.
Without the three-layer architecture, this is a codebase audit — grep for every hex value, every Tailwind blue-500 class, every hardcoded color in inline styles. You'll miss some. The ones you miss will ship.
With the primitive-to-semantic structure, the update is one line:
/* Before */
--color-blue-500: #3B82F6;
/* After */
--color-blue-500: #0EA5E9;Every semantic token that points to --color-blue-500 — accent, hover states, focus rings, active indicators — updates automatically. Every component that references those semantics inherits the change. This is the core promise of the architecture: changes are intentional and complete, not approximate and leaky.
The Complete :root Declaration
Full production-ready starting point. Expand the primitive palette to match your brand, update the semantic aliases to point to the right primitives:
:root {
/* === PRIMITIVE LAYER === */
/* Brand palette */
--p-brand-400: #60A5FA;
--p-brand-500: #3B82F6;
--p-brand-600: #2563EB;
/* Neutral palette */
--p-neutral-0: #FFFFFF;
--p-neutral-50: #F8FAFC;
--p-neutral-100: #F1F5F9;
--p-neutral-200: #E2E8F0;
--p-neutral-400: #94A3B8;
--p-neutral-500: #64748B;
--p-neutral-800: #1E293B;
--p-neutral-900: #0F172A;
--p-neutral-950: #020617;
/* Type scale */
--p-font-sans: 'Inter', system-ui, sans-serif;
--p-font-mono: 'JetBrains Mono', monospace;
--p-font-serif: 'Playfair Display', Georgia, serif;
/* Radius scale */
--p-r-2: 2px;
--p-r-4: 4px;
--p-r-8: 8px;
--p-r-12: 12px;
--p-r-16: 16px;
--p-r-full: 9999px;
/* === SEMANTIC LAYER === */
/* Surfaces */
--color-bg: var(--p-neutral-0);
--color-surface: var(--p-neutral-50);
--color-surface-raised: var(--p-neutral-0);
--color-border: var(--p-neutral-200);
/* Text */
--color-text: var(--p-neutral-900);
--color-text-muted: var(--p-neutral-500);
/* Accent */
--color-accent: var(--p-brand-500);
--color-accent-hover: var(--p-brand-600);
--color-accent-soft: rgba(59, 130, 246, 0.08);
--color-accent-fg: var(--p-neutral-0);
/* Typography */
--font-heading: var(--p-font-sans);
--font-body: var(--p-font-sans);
--font-code: var(--p-font-mono);
--font-weight-heading: 700;
--font-weight-body: 400;
--line-height-body: 1.7;
--letter-spacing-tight: -0.02em;
/* Radius */
--radius-sm: var(--p-r-4);
--radius-base: var(--p-r-8);
--radius-lg: var(--p-r-12);
--radius-xl: var(--p-r-16);
/* Shadows */
--shadow-sm: 0 1px 2px rgba(15, 23, 42, 0.05);
--shadow-base: 0 1px 3px rgba(15, 23, 42, 0.08), 0 4px 16px rgba(15, 23, 42, 0.06);
--shadow-lg: 0 4px 6px rgba(15, 23, 42, 0.07), 0 10px 40px rgba(15, 23, 42, 0.10);
/* Gradient */
--gradient-hero: linear-gradient(135deg, var(--color-accent-soft) 0%, transparent 60%);
}
[data-theme="dark"] {
--color-bg: #0D1117;
--color-surface: #161B22;
--color-surface-raised: #1C2128;
--color-border: #30363D;
--color-text: #E6EDF3;
--color-text-muted: #8B949E;
--color-accent: #58A6FF;
--color-accent-hover: #79B8FF;
--color-accent-soft: rgba(88, 166, 255, 0.10);
--color-accent-fg: #0D1117;
--shadow-sm: none;
--shadow-base: none;
--shadow-lg: none;
}Building this correctly from scratch takes approximately four hours — getting the primitive scale right, calibrating the dark mode accent, testing contrast ratios at each tier, validating the shadow replacement on dark surfaces.
Or: SeedFlip's DNA export outputs this exact architecture, correctly calibrated for whichever of the 100+ curated seeds you're working with. Background, surface tiers, border, text, muted text, accent, accent-soft, radius scale, shadow stack — all structured exactly as above, with values that were designed to work together. Free export, no account required beyond email.
The architecture isn't the secret. The calibration — picking values that actually work at every tier, in both modes, at every contrast ratio — is where the hours go. The DNA handles that.
Browse the full seed library and pull a DNA export at seedflip.co. The architecture is already built.