Реалізація 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 значень на токени — оцінюється окремо по обсягу кодової бази.