Design Tokens vs CSS Variables: What's the Difference?

"Design tokens" and "CSS variables" are often used interchangeably, but they're not the same thing. Understanding the difference helps you communicate clearly with designers and build better design systems.

What Are CSS Variables?

CSS variables (officially "CSS custom properties") are a browser feature. They're a way to define reusable values in CSS:

:root {
  --primary-color: #3b82f6;
  --spacing-md: 1rem;
}

.button {
  background-color: var(--primary-color);
  padding: var(--spacing-md);
}

CSS variables are an implementation mechanism. They live in your CSS files and are interpreted by browsers.

What Are Design Tokens?

Design tokens are a design concept. They're the smallest pieces of a design system—named values that capture design decisions:

• Color tokens: primary, secondary, background, text
• Spacing tokens: sm, md, lg, xl
• Typography tokens: font family, sizes, weights
• Effect tokens: shadows, borders, radii

Design tokens are platform-agnostic. They can be implemented as CSS variables, JavaScript constants, Swift values, XML resources, or any other format.

The Key Difference

Think of it this way: design tokens are the what (the design decisions), CSS variables are one how (one way to implement them).

When to Use Each Term

Say "Design Tokens" When:

• Talking to designers about the design system
• Documenting your design decisions
• Discussing cross-platform consistency
• Working with tools like Figma Tokens or Style Dictionary

Say "CSS Variables" When:

• Writing CSS code
• Discussing browser features
• Debugging stylesheet issues
• Explaining implementation details to developers

Design Tokens Implemented as CSS Variables

In practice, most web projects implement design tokens as CSS variables. Here's how the relationship works:

/* Design Token (conceptual):
   Name: color.primary
   Value: #3b82f6
   Purpose: Primary brand color, used for CTAs and links
*/

/* CSS Variable (implementation): */
:root {
  --color-primary: #3b82f6;
}

The design token includes metadata (purpose, usage guidelines) that CSS variables alone can't express. A complete design system has both:

• Token documentation describing each token's purpose and usage
• CSS implementation with variables for web use
• Other implementations for other platforms (optional)

Other Implementation Formats

While CSS variables are the most common web implementation, design tokens can be exported to many formats:

JSON Tokens

{
  "color": {
    "primary": {
      "value": "#3b82f6",
      "type": "color",
      "description": "Primary brand color"
    }
  },
  "spacing": {
    "md": {
      "value": "1rem",
      "type": "dimension"
    }
  }
}

JSON is platform-agnostic and can be transformed into any format using tools like Style Dictionary.

JavaScript/TypeScript

export const theme = {
  colors: {
    primary: '#3b82f6',
    secondary: '#64748b',
  },
  spacing: {
    md: '1rem',
    lg: '1.5rem',
  },
};

Useful for CSS-in-JS libraries like Styled Components or Emotion.

Sass Variables

$color-primary: #3b82f6;
$color-secondary: #64748b;
$spacing-md: 1rem;

Static variables that compile away (no runtime flexibility, but IE11 compatible).

How PickCSS Bridges the Gap

PickCSS exports your design tokens in multiple formats simultaneously:

• theme.css - CSS variables for direct use
• tokens.json - JSON format for tools and documentation
• theme.ts - TypeScript constants for type safety
• tailwind.config.js - Tailwind CSS extension
• design-system.md - Human-readable documentation

You get both the conceptual design tokens (with documentation) and the implementation-ready code.

Summary

• Design tokens = design concept (what to store)
• CSS variables = implementation (how to store it in CSS)
• Most web projects use CSS variables to implement design tokens
• Use the right term for your audience (designers vs developers)

Getting Started

Want design tokens without the terminology confusion? PickCSS gives you production-ready tokens in every format you need.

Create your design tokens and export them as CSS variables, JSON, TypeScript, and more.