Design Tokens Are Not CSS Variables. Here's the Difference That Matters.

The Confusion Is Everywhere

Ask ten frontend engineers what a design token is and nine of them will show you a CSS custom property.

That's not wrong. But it's also not the whole story — and the difference matters more than most teams realize until they're deep in a multi-platform codebase with drift between iOS, web, and Figma.

What a Design Token Actually Is

A design token is a platform-agnostic name-value pair with semantic meaning.
The key word: platform-agnostic.

CSS variables live in CSS. A design token lives in a format that can compile into CSS, Swift, Kotlin, Tailwind config, or whatever your stack needs. The token is the source of truth. The CSS variable is one output of that source of truth.

The W3C DTCG (Design Token Community Group) format makes this concrete:

This is what tools like Style Dictionary, Theo, and Supernova expect. This is what Figma Variables exports. This is what enables one palette to compile into every target format your team ships.

Why the Distinction Breaks Teams

Scenario 1: You hardcode CSS variables.

Six months in, your iOS engineer asks for the same palette in Swift. Now someone has to manually translate 120 tokens. Drift is guaranteed.

Scenario 2: You define tokens in Figma manually.

You've got 40 variables named Primary/500. Your Figma file and your codebase are "the same" until someone changes a shade in one place and forgets the other. Now they're not.

Scenario 3: You skip the shade scale.
You pick #6C47FF as primary and define three states: default, hover, disabled. Then a new surface needs a 10% opacity tint. Your "token system" has no answer. Someone invents --color-primary-light and the naming debt begins.

What a Real Token Architecture Looks Like

Three layers. This is the pattern that doesn't break:

Layer 1 — Primitive tokens
The raw values. Every shade from 50–900, generated mathematically so perceptual weight is uniform across the scale.

Layer 2 — Semantic tokens
Meaning mapped to primitives. This is what components reference.

Layer 3 — Component tokens (optional, but worth it at scale)
Scoped overrides for specific components.

The result: you can retheme an entire product by changing one primitive. No grep. No find-and-replace.

The Tailwind Problem No One Talks About

Tailwind is great. But out of the box, it encourages a pattern that breaks token systems:

Now your color values live in your markup, not in your tokens. If you ever change purple-500, you're doing a codebase-wide find-and-replace, not changing one token.

The fix is to extend Tailwind's config to reference your CSS variables:

Now your Tailwind classes reference your token layer. Change the variable, change the whole system. No component edits.

The Gap This Creates for Every Design Tool

The workflow most teams run today:

1. Designer picks colors in Figma
2. Designer documents hex codes in a Notion page
3. Engineer manually creates CSS variables
4. Engineer adds those to Tailwind config by hand
5. Six months later, Figma and code have drifted

The gap between "we have a palette" and "our tokens are in code" is still entirely manual.

This is the exact problem I built Paletta to close. Generate a palette → validate accessibility → export as CSS variables, Tailwind config, or DTCG-format tokens in one step. No translation. No drift.

The Design Tokens export (DTCG format) is shipping next. It's the piece that completes the workflow from Figma to code without the manual step.

Where to Start if You're Rebuilding Your System

You don't have to adopt the full three-layer architecture on day one.

Start here:

1. Generate your full shade scale (50–900) before you name a single token. You need the raw material before you build the semantic layer.
2. Run accessibility validation on your base colors before you commit. Your 500 shade needs to pass WCAG AA on white. Discover that now, not in QA.
3. Name your semantic tokens for intent, not value. color-primary is good. color-purple is a primitive, not a semantic token. color-brand-purple is naming debt.

Wrapping Up

CSS variables are an output. Tokens are the source.

Getting this right up front means zero translation step between design and code, zero drift between platforms, and the ability to retheme without touching components.

The tooling is finally good enough to do this from day one. There's no reason to still be doing it manually.

Try Paletta

usepaletta.io — free tier available. Design Tokens export (DTCG format) shipping soon.
The Figma plugin is in Community review. Follow @andresmclavijo on X or @usepaletta.io on Instagram for updates.

Next: How accessibility-first color selection changes the way you build design systems — not just how you audit them.