3 layer of design token matter

"Why do you need 3 layers of CSS variables? Just use brand-800 directly."

That was me. Here's what changed my mind.

I made a table of how shades map in light vs dark mode:

Button surface: 800 → 200 (flip to light)

Badge surface: 100 → 900 (flip to dark)

Disabled state: 400 → 600 (shift middle)

Border color: 200 → 800 (flip to dark)

See the problem? Every row flips in a DIFFERENT direction. There's no single "reverse the palette" trick that handles all of them.

That's the whole reason semantic tokens exist.

Layer 1: --color-brand-800 (the raw color)

Layer 2: --color-surface-brand-primary: var(--color-brand-800)

Layer 3: --color-button-brand-default-surface: var(--color-surface-brand-primary)

Dark mode? Override Layer 2.

Theme switch? Swap Layer 1.

One component needs something different? Override Layer 3.

Let me show you the real math at scale.

Say your design system has:

• 30 components (button, checkbox, input, badge, tab, card...)

• 4 states each (default, hover, focus, disabled)

• 3 properties per state (surface, text, icon)

• 2 modes (light + dark)

• 5 color themes (blue, violet, pink, cyan, orange)

WITHOUT layers (direct brand-800 usage):

Dark mode overrides: 30 × 4 × 3 = 360 per theme

Across 5 themes: 360 × 5 = 1,800 overrides

Plus base dark mode: + 360

Total: ~2,160 CSS overrides to maintain

WITH 3 layers:

Layer 1 — Theme switch: 12 palette values × 5 themes = 60 overrides

Layer 2 — Dark mode: ~30 semantic tokens (covers ALL components at once)

Layer 3 — Exceptions: maybe 5-10 one-off component overrides

Total: ~100 CSS overrides

That's a 95% reduction. And it gets better as you grow.

Add 10 more components?

• Without layers: +400 new overrides to write and maintain

• With layers: +0 (they just reference existing semantic tokens)

Add a new theme?

• Without layers: +360 overrides

• With layers: +12 (just swap the base palette)

Add a new mode (high contrast)?

• Without layers: +1,800 overrides

• With layers: +30 (new semantic mapping)

The cost of maintaining without layers grows EXPONENTIALLY:

components × states × properties × modes × themes

The cost with layers grows LINEARLY:

palette values + semantic mappings + exceptions

At 30 components it's 2,160 vs 100.

At 100 components it's 6,000+ vs ~120.

At 200 components it's 12,000+ vs ~140.

The overhead of setting up 3 layers pays for itself after your 3rd component.

More work upfront. Orders of magnitude less work over time.