Color Tokens in CSS and Tailwind
· 3 min read
How to name and organize color variables by role, wire up light and dark mode in CSS, and use the same tokens in a Tailwind v4 theme.
Hard-coded hex values scattered through a stylesheet are the main reason color changes are painful. Rebranding, adding dark mode or fixing a contrast problem turns into a search-and-replace across hundreds of lines. Color tokens — named variables that describe what a color is for — solve this. This guide shows how to structure them in plain CSS and use the same tokens in Tailwind.
Two layers: primitives and roles
A robust setup separates what the colors are from how they are used.
Primitive tokens are the raw palette, named by hue and step. They never appear directly in component styles.
:root {
--blue-100: #E3E8FF;
--blue-500: #3D5AFE;
--blue-700: #2638C4;
--sand-50: #F7F5F0;
--ink-900: #1D2433;
}Semantic (role) tokens describe a job in the interface and point at a primitive or hold a value of their own. Components only ever use these.
:root {
--color-bg: var(--sand-50);
--color-surface: #EFECE4;
--color-border: #DAD6CC;
--color-text: var(--ink-900);
--color-muted: #5C6475;
--color-primary: var(--blue-500);
--color-on-primary: #FFFFFF;
--color-accent: #C2410C;
}.button {
background: var(--color-primary);
color: var(--color-on-primary);
}
.card {
background: var(--color-surface);
border: 1px solid var(--color-border);
color: var(--color-text);
}Now the button does not know it is blue. If the brand moves to green, you change one line. If a contrast check fails, you adjust one token and every component follows.
Name tokens by role, not by appearance
Names like --light-gray or --brand-blue describe what a color looks like today. They become wrong the moment the value changes — and in dark mode, --light-gray would hold a dark color. Role names stay true:
--color-bg,--color-surface,--color-borderfor structure.--color-textand--color-mutedfor content.--color-primary,--color-accentfor emphasis.--color-on-primary,--color-on-accentfor text placed on filled colors.- Optional status roles:
--color-success,--color-warning,--color-danger.
Keep the list short. A dozen role tokens cover most products; adding a token for every component brings back the original problem.
Dark mode becomes a set of new values
With role tokens, dark mode is not a second stylesheet. It is the same names with different values. The pattern below follows the system setting and still lets a toggle force either theme with a data-theme attribute:
@media (prefers-color-scheme: dark) {
:root:not([data-theme="light"]) {
--color-bg: #14161F;
--color-surface: #1C1F2B;
--color-border: #2C3040;
--color-text: #E6E8EF;
--color-muted: #9AA1B2;
--color-primary: #8C9EFF;
--color-on-primary: #14161F;
--color-accent: #FB923C;
}
}
:root[data-theme="dark"] {
/* the same values, for people who choose dark manually */
}Note that the dark primary is a lighter blue and its label is dark. Dark values should be chosen, not computed by inversion — the dark mode guide explains why.
Modern browsers also support the light-dark() function, which keeps both values on one line. It follows the color-scheme property, so it needs that declaration to work:
:root {
color-scheme: light dark;
--color-bg: light-dark(#F7F5F0, #14161F);
--color-text: light-dark(#1D2433, #E6E8EF);
}Derive the quiet colors
Surfaces and borders can be mixed from the background and text instead of being picked by hand. color-mix() does this in CSS, and mixing in OKLCH gives even, natural steps:
:root {
--color-surface: color-mix(in oklch, var(--color-bg) 94%, var(--color-text));
--color-border: color-mix(in oklch, var(--color-bg) 82%, var(--color-text));
}Because they reference other tokens, these update automatically in dark mode. Check the border against 3:1 if it marks an input or other control.
Using the tokens in Tailwind CSS v4
Tailwind v4 is configured in CSS. Any --color-* variable declared in @theme becomes a full set of utilities (bg-*, text-*, border-* and so on). The generated utilities read the variable at runtime — bg-primary becomes background-color: var(--color-primary) — so overriding the variable for dark mode is enough:
@import "tailwindcss";
/* light values become utilities: bg-bg, text-text, bg-primary ... */
@theme {
--color-bg: #F7F5F0;
--color-surface: #EFECE4;
--color-text: #1D2433;
--color-muted: #5C6475;
--color-primary: #3D5AFE;
--color-on-primary: #FFFFFF;
--color-accent: #C2410C;
}
/* dark values override the same variables */
@media (prefers-color-scheme: dark) {
:root {
--color-bg: #14161F;
--color-text: #E6E8EF;
--color-primary: #8C9EFF;
--color-on-primary: #14161F;
/* ... */
}
}<button class="bg-primary text-on-primary">Save</button>
<p class="text-muted">Last edited 2 hours ago</p>There is no need for dark: variants on every element: the tokens already switch, so bg-primary is correct in both themes.
Tailwind v3
In v3, map the same variables in the config file:
// tailwind.config.js
module.exports = {
theme: {
extend: {
colors: {
bg: 'var(--color-bg)',
surface: 'var(--color-surface)',
text: 'var(--color-text)',
primary: 'var(--color-primary)',
accent: 'var(--color-accent)',
},
},
},
}Writing values in OKLCH
Hex is fine for storing colors, but OKLCH is easier to reason about when you edit them. Its three channels are lightness, chroma (saturation) and hue, and lightness corresponds closely to what the eye sees. To make a darker version of a brand color for text, you lower L and leave the rest alone: oklch(55% 0.2 265) becomes oklch(42% 0.2 265). All current major browsers support oklch().
Skip the typing
Every palette on Colorset exports exactly this structure: role tokens for light and dark mode as CSS variables, a Tailwind v4 theme, a Tailwind v3 config, SCSS, JSON or design tokens, in HEX, RGB, HSL or OKLCH. Pick a scheme you like, open Export, and paste. The shades generator creates a 50–950 primitive scale from any color if you want to build the primitive layer yourself.