Реализация Design Tokens для дизайн-системы веб-приложения

Реализация Design Tokens для дизайн-системы веб-приложения

Design tokens — именованные переменные, хранящие атомарные дизайн-решения: цвета, размеры шрифтов, отступы, радиусы, тени, длительности анимаций. Токены — не просто CSS-переменные. Это контракт между дизайнером и разработчиком, реализованный в виде платформо-независимого формата (JSON/YAML), который компилируется в нужный output для каждой платформы: CSS custom properties, JS/TS-объекты, Swift-константы, XML для Android.

Зачем токены вместо переменных

Прямая замена #1A73E8 на --color-primary — это переменная, не токен. Токен несёт семантику: --color-action-primary-default, --color-action-primary-hover, --color-action-primary-disabled. Разница принципиальная: при смене фирменного цвета нужно менять одно значение в одном месте, а не искать все вхождения «основного синего» по кодовой базе.

Реальная боль без токенов в проекте с командой 5+ человек:

• дизайнер меняет Blue/600 в Figma, разработчик не знает, что это #1D4ED8 используется в 12 местах под разными hex-значениями
• темизация требует дублирования стилей вместо переключения набора переменных
• onboarding нового разработчика занимает дни вместо часов — нет единого источника правды

Структура токенов: трёхуровневая модель

Primitive tokens (Global tokens) — сырые значения без контекста:

{
  "color": {
    "blue": {
      "50": { "value": "#EFF6FF" },
      "500": { "value": "#3B82F6" },
      "900": { "value": "#1E3A5F" }
    },
    "gray": {
      "0":   { "value": "#FFFFFF" },
      "100": { "value": "#F3F4F6" },
      "900": { "value": "#111827" }
    }
  },
  "spacing": {
    "1": { "value": "4px" },
    "2": { "value": "8px" },
    "4": { "value": "16px" },
    "8": { "value": "32px" }
  }
}

Semantic tokens (Alias tokens) — привязка смысла к примитивам:

{
  "color": {
    "action": {
      "primary": {
        "default": { "value": "{color.blue.500}" },
        "hover":   { "value": "{color.blue.600}" },
        "disabled":{ "value": "{color.gray.300}" }
      }
    },
    "surface": {
      "default":   { "value": "{color.gray.0}" },
      "subtle":    { "value": "{color.gray.100}" }
    },
    "text": {
      "primary":   { "value": "{color.gray.900}" },
      "secondary": { "value": "{color.gray.600}" }
    }
  }
}

Component tokens — переменные конкретного компонента:

{
  "button": {
    "background": { "value": "{color.action.primary.default}" },
    "background-hover": { "value": "{color.action.primary.hover}" },
    "radius": { "value": "{border-radius.md}" },
    "padding-x": { "value": "{spacing.4}" }
  }
}

Инструменты трансформации

Style Dictionary (Amazon) — стандарт де-факто для компиляции токенов:

// config.js
module.exports = {
  source: ['tokens/**/*.json'],
  platforms: {
    css: {
      transformGroup: 'css',
      buildPath: 'dist/css/',
      files: [{
        destination: 'tokens.css',
        format: 'css/variables',
        options: { outputReferences: true }
      }]
    },
    js: {
      transformGroup: 'js',
      buildPath: 'dist/js/',
      files: [{
        destination: 'tokens.js',
        format: 'javascript/es6'
      }]
    }
  }
};

npx style-dictionary build --config config.js

Output для CSS:

:root {
  --color-blue-500: #3B82F6;
  --color-action-primary-default: var(--color-blue-500);
  --button-background: var(--color-action-primary-default);
}

Token Pipeline с поддержкой тем:

// Тёмная тема — отдельный набор semantic токенов
platforms: {
  'css/dark': {
    transformGroup: 'css',
    prefix: 'dt',
    buildPath: 'dist/css/',
    files: [{
      destination: 'tokens-dark.css',
      format: 'css/variables',
      filter: (token) => token.filePath.includes('themes/dark'),
      options: {
        selector: '[data-theme="dark"]'
      }
    }]
  }
}

Интеграция с Figma

Токены в Figma управляются через:

• Tokens Studio (плагин) — двусторонняя синхронизация с JSON через GitHub/GitLab
• Figma Variables (встроено с 2023) — нативная поддержка, но пока ограниченный API для экспорта

При использовании Tokens Studio рабочий процесс:

1. Дизайнер меняет токен в Figma
2. Плагин пушит изменение в ветку tokens/update-blue-palette
3. CI запускает Style Dictionary, генерирует CSS/JS
4. PR с обновлёнными артефактами — код-ревью и merge

Tailwind CSS + токены

Tailwind можно полностью параметризировать через токены:

// tailwind.config.js
const tokens = require('./dist/js/tokens');

module.exports = {
  theme: {
    extend: {
      colors: {
        'action-primary': tokens.ColorActionPrimaryDefault,
        'surface-subtle': tokens.ColorSurfaceSubtle,
      },
      spacing: {
        // маппинг из токенов
      },
      borderRadius: {
        sm: tokens.BorderRadiusSm,
        md: tokens.BorderRadiusMd,
      }
    }
  }
};

Но лучше использовать CSS custom properties в Tailwind 4 через @theme:

@theme {
  --color-primary: var(--color-action-primary-default);
  --radius-button: var(--button-radius);
}

Версионирование и governance

Токены — часть кодовой базы. Они живут в репозитории (обычно в monorepo дизайн-системы или отдельном пакете) и публикуются как npm-пакет:

@company/[email protected]
  ├── dist/css/tokens.css
  ├── dist/js/tokens.js
  ├── dist/js/tokens.d.ts
  └── dist/scss/_tokens.scss

Семантическое версионирование критично: переименование токена — breaking change (major), добавление нового — minor, исправление значения — может быть patch или minor в зависимости от контекста.

Changelog токенов должен быть читаемым для дизайнеров, не только для разработчиков.

Типовые сроки

Начальная реализация (аудит существующих стилей → определение primitive/semantic токенов → настройка Style Dictionary → интеграция в один проект) для среднего веб-приложения — 8–12 рабочих дней. Если нужна двусторонняя синхронизация с Figma через Tokens Studio + CI/CD pipeline — +3–5 дней. Полный перевод legacy-проекта с hard-coded значений на токены — оценивается отдельно по объёму кодовой базы.