Custom Properties (CSS Variables) You Won't Regret

Store brand colours and spacing as custom properties, override them on a section when needed, and stop hunting hex codes. After this, a rebrand is a few root values.

5 min HTML and CSS Web Development Intermediate

Skip ahead: If you already keep brand tokens on :root and override them on a section when needed, skip to "Theming a section", then continue.

Hard-coded #034bff in forty rules is a rebrand tax. Custom properties let you name the colour once and point every rule at the name.

Tokens on :root

:root {
  --color-bg: #f2f8ff;
  --color-text: #080b0e;
  --color-muted: #626976;
  --color-brand: #034bff;
  --color-surface: #ffffff;
  --radius: 8px;
  --space: 1rem;
}

body {
  background: var(--color-bg);
  color: var(--color-text);
  margin: 0;
  font-family: system-ui, sans-serif;
}

.card {
  background: var(--color-surface);
  border: 1px solid var(--color-muted);
  border-radius: var(--radius);
  padding: var(--space);
}

.btn--primary {
  background: var(--color-brand);
  color: #ffffff;
}

var(--color-brand) reads the current value. Change --color-brand and every consumer updates.

Theming a section

.banner-promo {
  --color-brand: #0a7a3e;
  --color-surface: #e8f5e9;
  background: var(--color-surface);
  padding: var(--space);
}

.banner-promo .btn--primary {
  background: var(--color-brand);
}

Custom properties inherit. Set them on a subtree and children see the new values without rewriting each rule. That is how a promo strip can go green without a second button class.

Fallbacks

color: var(--color-text, #080b0e);

The second argument is used when the property is missing. Useful while migrating an old sheet.

⚠ Warning: Do not store every possible value as a variable on day one. Start with colour, radius and spacing. Variables for one-off margins add noise.

Common mistakes

Variables named after a page (--home-blue). Name the role (--color-brand).
Forgetting inheritance. A variable on .card does not affect a sibling.
Mixing raw hex and tokens randomly. Pick tokens for the brand; keep one-off neutrals rare and commented.

Spacing and radius as tokens

:root {
  --space-1: 0.25rem;
  --space-2: 0.5rem;
  --space-3: 1rem;
  --space-4: 1.5rem;
  --radius: 8px;
}

.card { padding: var(--space-3); border-radius: var(--radius); gap: var(--space-2); }

You do not need a token for every pixel. You need enough that a spacing change does not require hunting twenty literals.

Dark section without a second stylesheet

.panel-dark {
  --color-bg: #080b0e;
  --color-text: #f2f8ff;
  --color-muted: #9aa3b2;
  --color-surface: #12161c;
  background: var(--color-bg);
  color: var(--color-text);
}

Same component classes, different tokens. That is the payoff.

Migration tip

When an old rule still has a raw hex, leave a comment: /* TODO: move to --color-brand */. Do not block shipping a page on a perfect token migration. Do block shipping a third copy of the same hex.

What happens if you skip this

Marketing will ask for a darker blue. You will change twenty places and miss the hover state on the checkout button.

Try it

Replace three hard-coded brand blues with var(--color-brand). Then override --color-brand on a promo section and watch the button follow.

If a colour appears more than twice, why is it still a raw hex?

About