Design tokens: what they are, why they matter, and how to use them in CSS, Tailwind, and JSON

Design tokens are the foundation of any serious design system. They let you store all visual decisions in one place and automatically synchronize them across Figma, CSS, React, and mobile apps.

What are design tokens

A design token is a named variable that stores a specific visual value: a color, spacing, font size, border radius, or shadow. Instead of writing #1a73e8 in every component, you use the token color-primary, and define its value in one place.

Examples of tokens:

Why use design tokens

A single source of truth. All colors, sizes, and spacing values are stored in one file. When the brand color changes, you update one line instead of hundreds of places in the code.

Synchronization with design. Tokens are exported from Figma and imported into code, so designers and developers work with the same values.

Theme support. Dark mode, client customization, and seasonal changes can all be implemented by overriding tokens, without changing components.

Scalability. In a large team, tokens prevent disagreements over which shade of gray is “correct.”

CSS custom properties

The most straightforward way to implement tokens is with CSS custom properties:

:root {
  /* Цвета */
  --color-primary: #1a73e8;
  --color-primary-hover: #1557b0;
  --color-secondary: #34a853;
  --color-danger: #ea4335;
  --color-text: #202124;
  --color-text-muted: #5f6368;
  --color-bg: #ffffff;
  --color-bg-surface: #f8f9fa;

  /* Отступы */
  --spacing-xs: 4px;
  --spacing-sm: 8px;
  --spacing-md: 16px;
  --spacing-lg: 24px;
  --spacing-xl: 32px;
  --spacing-2xl: 48px;

  /* Типографика */
  --font-size-sm: 14px;
  --font-size-base: 16px;
  --font-size-lg: 18px;
  --font-size-xl: 24px;
  --font-size-2xl: 32px;

  /* Радиусы */
  --radius-sm: 4px;
  --radius-md: 8px;
  --radius-lg: 16px;
  --radius-full: 9999px;
}

A dark theme overrides only the tokens it needs:

[data-theme="dark"] {
  --color-text: #e8eaed;
  --color-bg: #202124;
  --color-bg-surface: #303134;
}

Tailwind config

In Tailwind, design tokens are defined in tailwind.config.js:

module.exports = {
  theme: {
    extend: {
      colors: {
        primary: {
          DEFAULT: '#1a73e8',
          hover: '#1557b0',
          light: '#e8f0fe',
        },
        secondary: '#34a853',
        danger: '#ea4335',
      },
      spacing: {
        xs: '4px',
        sm: '8px',
        md: '16px',
        lg: '24px',
        xl: '32px',
      },
      borderRadius: {
        card: '8px',
        button: '4px',
      },
      fontSize: {
        body: ['16px', { lineHeight: '1.5' }],
        heading: ['32px', { lineHeight: '1.2', fontWeight: '700' }],
      },
    },
  },
}

Components can then use semantic names: bg-primary, text-danger, rounded-card — instead of magic values like bg-blue-600.

JSON token format

The W3C Design Tokens standard provides a JSON structure for exchanging tokens between tools:

{
  "color": {
    "primary": {
      "$value": "#1a73e8",
      "$type": "color",
      "$description": "Основной акцентный цвет бренда"
    },
    "text": {
      "default": { "$value": "#202124", "$type": "color" },
      "muted": { "$value": "#5f6368", "$type": "color" }
    }
  },
  "spacing": {
    "md": { "$value": "16px", "$type": "dimension" },
    "lg": { "$value": "24px", "$type": "dimension" }
  }
}

From this JSON, tools such as Style Dictionary can generate CSS, SCSS, JS constants, and Swift variables at the same time.

Naming tokens

A good naming scheme: {категория}-{роль}-{состояние}.

• color-primary — default
• color-primary-hover — on hover
• color-primary-disabled — inactive
• spacing-component-gap — spacing between components

Avoid names tied to a value: color-blue-500 is bad; color-brand-cta is good.

A tool on reChecker

The design token generator on reChecker creates CSS custom properties, Tailwind config, and JSON from a single palette. Set colors, spacing, and fonts to get ready-to-use files for your project.

Open the tool on reChecker →