When setting up CSS custom properties for a new project, it’s tempting to name variables after the values they hold. We’ve all written code like --accent-blue: #3b82f6; or --dark-gray: #1e293b;.
It feels quick and explicit at first. But as soon as your design scales—or as soon as you need to implement dark mode—value-based variable names start working against you.
The Problem with Value Names
Value-based names tell you what a color is, but they don't tell you how or where it should be used.
If --accent-blue is used for primary buttons, active tab borders, focus rings, and success notifications, what happens when a design update changes the primary button to purple while keeping focus rings blue? You end up creating --accent-blue-2 or --accent-purple, and your stylesheet grows sideways.
Even worse, value names completely break down under theme switching:
/* Fragile: Value-based naming in Dark Mode */
:root {
--bg-white: #ffffff;
--text-black: #0f172a;
}
[data-theme="dark"] {
/* Reading "--bg-white" when the hex is dark gray creates instant code confusion */
--bg-white: #0f172a;
--text-black: #f8fafc;
}
The Solution: Semantic Tokens
Semantic design tokens give variables a role rather than a descriptive name. A semantic token answers the question: "What function does this element perform in the UI?"
When you name custom properties by intent, dark mode and component overrides become effortless:
/* Scalable: Role-based Semantic Tokens */
:root {
/* Primitive Brand Values */
--blue-600: #2563eb;
--slate-900: #0f172a;
--slate-50: #f8fafc;
/* Semantic UI Tokens (Light Theme) */
--color-surface-base: var(--slate-50);
--color-text-main: var(--slate-900);
--color-action-primary: var(--blue-600);
--color-border-focus: var(--blue-600);
}
[data-theme="dark"] {
/* Dark Theme Overrides map seamlessly without changing variable names */
--color-surface-base: var(--slate-900);
--color-text-main: var(--slate-50);
--color-action-primary: #3b82f6;
--color-border-focus: #60a5fa;
}
How Semantic Tokens Simplify Component Code
By enforcing semantic tokens, your component styles become immune to global color refactors:
.button-primary {
background-color: var(--color-action-primary);
color: var(--color-text-inverse, #ffffff);
}
.button-primary:focus-visible {
outline: 2px solid var(--color-border-focus);
}
When your tokens describe intent, changing a color scheme across an entire application takes seconds—and your codebase remains self-documenting for any engineer who reads it.
Call to Action (CTA)
How do you usually structure your CSS variables? Do you rely on raw color names or strict semantic tokens when scaling dark mode? Let’s talk in the comments!
(Published by Joseph Salaki — Visual Designer & Frontend Engineer at byjoemetry.com)