hexcolors

Learn / Tutorials

How to create a color palette in CSS with custom properties

Build a maintainable palette with primitive and semantic CSS variables in five steps.

November 21, 20261 min readBy the hexcolors team

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.

The hexcolors teamWe build free color tools and write practical guides. Follow us on X, Instagram and LinkedIn.