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

Andres Clavijo Reyes — Thu, 02 Apr 2026 14:15:25 +0000

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:

Designer picks colors in Figma
Designer documents hex codes in a Notion page
Engineer manually creates CSS variables
Engineer adds those to Tailwind config by hand
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:

Generate your full shade scale (50–900) before you name a single token. You need the raw material before you build the semantic layer.
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.
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.

Your Figma Color System Is Manual. Here's Why That Breaks at Scale.

Andres Clavijo Reyes — Mon, 30 Mar 2026 13:10:20 +0000

The Reality No One Talks About

You start a project with three brand colors. Six months later, your Figma file has 42
different shades of "slightly different light grey" and your accessibility contrast
ratios are a disaster.

Building a color system isn't about picking hex codes. It's about logic, scalability,
and accessibility from day one. But why is the process still entirely manual?

Three Mistakes That Break Every Color System

1. The Eyeball Method

Picking shades by moving the cursor until it looks right. The result: perceptual
inconsistency across displays and zero reproducibility when someone else opens the file.

2. Accessibility as an Afterthought

Checking contrast ratios after the design is finished only to discover your primary
brand color fails WCAG. Now you're making late-stage decisions with downstream
consequences across every component.

3. Naming Debt

Blue-Light-1, Blue-Light-Final-v2, Blue-Light-Final-FINAL. Without a systematic token approach, your color library becomes archaeology within a year.

What a Generative System Actually Solves

To scale, you need a system that generates shades from mathematical curves, not vibes.

Perceptual uniformity Every "500" weight shade feels equivalent to the human eye across your entire palette.
Instant iteration Change one base color; the full shade scale updates.
Developer-ready output Your tokens exist the moment the palette does. No translation step.

Why I Built Paletta

The gap between "I have a brand color" and "my system is dev ready" was still entirely manual. I built Paletta to close it.

The workflow is three steps: Generate. Validate. Implement.

Shade scales from 50–900, generated mathematically.
No more eyeballing. Paletta generates the full spectrum from your base color perceptually uniform, systematically named, ready to use.

Accessibility lens built into the palette view.
Run vision simulations (deuteranopia, protanopia, tritanopia, achromatopsia) directly on your palette before you design a single component. WCAG contrast validation isn't a separate step — it's built into color selection.

Export to CSS variables, Tailwind config, or design tokens.
One palette, three export formats. Frontend engineers get production-ready output without translation overhead.

Figma plugin (currently in Community review).
Build your palette in Paletta, push it into your Figma file. No copy-paste. No drift.

The Shift Worth Making

The era of "picking colors" is ending. The era of managing color systems is here.

If you want to spend less time tweaking hex codes and more time on actual UX problems, the system should handle the math. Paletta does.

Try Paletta

usepaletta.io — free tier available

The Figma plugin is in Community review. Follow @andresmclavijo on X for launch updates.

I'm documenting the full build process here on dev.to — follow for the next post on design token architecture.

DEV Community: Andres Clavijo Reyes