Key takeaways
- Use primitive tokens for raw colors and semantic tokens for roles.
- Components should only use semantic tokens.
- Test every text pair before you ship.
A palette in CSS is more than a list of hex codes. Using custom properties in two layers keeps your colors consistent and easy to change. This tutorial takes about ten minutes.
Step 1: Choose your base colors
Pick a primary color, a dark neutral for text and a light neutral for backgrounds. Generate a scale for each with the shade scale generator so you have light and dark steps ready.
Step 2: Define primitive tokens
Primitives are the raw colors, named by hue and step. They describe what a color is, not where it is used.
:root {
--blue-500: #3b6cff;
--blue-100: #e6edff;
--gray-900: #0c0c14;
--gray-50: #f6f6fa;
}Step 3: Add semantic tokens
Semantic tokens describe the job a color does and point at primitives. Your components will only use these.
:root {
--color-action: var(--blue-500);
--color-text: var(--gray-900);
--color-surface: var(--gray-50);
}Step 4: Use the tokens in components
Reference semantic tokens everywhere. When the brand color changes, you edit one line.
.button {
background: var(--color-action);
color: #fff;
}
body {
background: var(--color-surface);
color: var(--color-text);
}Step 5: Test the contrast
Check every text and background pair with the contrast matrix. Body text needs at least 4.5:1.
Wrap up
You now have a two-layer palette that is easy to theme. The next step is dark mode, which only needs the semantic tokens remapped. See how to add dark mode with CSS variables.