Design tokens explained: what they are and why your project needs them

Design tokens are not just variables. They're not a Sass file with hex codes. They're not a JSON blob that a build tool consumes. Those are implementations. A design token is something more fundamental: it's a contract between design and code.

A token says: "This value has a name, a purpose, and a consistent meaning across every platform, every component, and every tool in your stack." When a designer says "use the accent color," they're referencing a token. When a developer writes var(--color-accent), they're consuming the same token. Same name. Same intent. No translation layer.

That's the idea. Here's how it works in practice.

What tokens actually are

A design token is a named value that represents a design decision. Not a CSS value — a decision. "Our background color is this warm cream" is a decision. --color-background: #FAF7F2 is the token that captures it.

Tokens cover every visual property in a design system:

• Color: Background, text, accent, borders, status indicators
• Spacing: Margins, padding, gaps — usually a scale (4px, 8px, 16px, 24px, 32px)
• Typography: Font families, sizes, weights, line heights
• Shadow: Elevation levels, blur radii, offsets
• Border: Widths, radii, styles

Color tokens are the most impactful. They're the most visible, the most frequently referenced, and the most likely to change. A spacing scale rarely changes after v1. A color palette changes with every rebrand, every dark mode implementation, every accessibility audit.

Get your color tokens right and the rest follows.

Color tokens: roles over labels

The biggest mistake teams make with color tokens is naming them after what they look like. --blue-500. --warm-gray. --dark-red. These names are brittle. Rebrand and every name is wrong.

The right approach is role-based naming. Each color has a job. The name describes the job, not the appearance.

• Background: The surface where content lives. Usually the lightest value in light mode.
• Ink: Primary text and headings. Maximum contrast against background.
• Accent: The attention color. CTAs, links, focus rings, active states.
• Support: Secondary text, captions, metadata. Lower contrast than ink, but still readable.
• Neutral: Borders, dividers, subtle backgrounds. The structural glue.

Five roles. That's it. Every color in your interface maps to one of these. This is the model Paletter uses. When you generate a palette, the system assigns roles automatically based on luminance, contrast, and color relationships. Not random — deliberate.

Format-agnostic by design

The power of tokens is that they're format-agnostic. The same five color decisions can be expressed in any format your stack needs. The token is the decision. The format is just serialization.

CSS custom properties

:root {
  --color-background: #FAF7F2;
  --color-ink: #1A1A1A;
  --color-accent: #E8C547;
  --color-support: #7A7A6E;
  --color-neutral: #D4CFC6;
}

Tailwind v4 @theme

@theme {
  --color-background: #FAF7F2;
  --color-ink: #1A1A1A;
  --color-accent: #E8C547;
  --color-support: #7A7A6E;
  --color-neutral: #D4CFC6;
}

JSON (Style Dictionary / DTCG format)

{
  "color": {
    "background": {
      "$value": "#FAF7F2",
      "$type": "color"
    },
    "ink": {
      "$value": "#1A1A1A",
      "$type": "color"
    }
  }
}

SCSS variables

$color-background: #FAF7F2;
$color-ink: #1A1A1A;
$color-accent: #E8C547;
$color-support: #7A7A6E;
$color-neutral: #D4CFC6;

Same five decisions. Four different formats. Change the palette once and every format updates. That's what Paletter does — you generate one palette and export it in every format you need.

Who uses tokens and why

Design systems teams

If you maintain a design system, tokens are your source of truth. They bridge the gap between Figma and code. The designer references color/accent in Figma. The developer references --color-accent in CSS. Same token, different environments. When the token changes, both sides update.

Paletter's Figma integration makes this loop seamless. Generate a palette, export to Figma variables and CSS custom properties simultaneously. Design and code stay in sync because they share the same source.

Frontend developers

Even without a formal design system, tokens make your code better. Instead of hardcoded hex values scattered across components, you have a centralized palette with semantic names. Refactoring is easy. Dark mode is possible. Consistency is automatic.

Figma-to-code workflows

Tools like Figma's Dev Mode, Locofy, and Builder.io generate code from designs. The code quality depends entirely on whether the design uses tokens. If the Figma file uses named variables, the generated code uses named variables. If it uses raw hex values, you get raw hex values. Tokens make the entire pipeline better.

AI coding workflows

This is the newest consumer. AI coding tools like Claude Code, Cursor, and Windsurf generate components faster than any human. But they need to know your colors. A COLORS.md file gives AI tools your tokens with roles, contrast ratios, and usage rules. The token system you define becomes the constraint the AI operates within.

How Paletter fits in

Paletter generates a curated five-color palette from any source — a photograph, a color theory preset, an inspiration palette. Each color gets a role. Each pair gets a contrast check. Then you export in whatever format your project needs.

One palette, all formats. CSS custom properties for vanilla projects. Tailwind v4 @theme blocks for Tailwind projects. JSON for Style Dictionary pipelines. SCSS variables for legacy codebases. COLORS.md for AI tools.

The token is the palette. The format is just export.

Start with five colors

You don't need a 200-token system on day one. You need five colors with clear roles. Build components with those five. Add tints and shades as needed. Add component-level tokens when your system grows. But start with five.

Background. Ink. Accent. Support. Neutral. That's a design system. Everything else is refinement.