У проєкті з 5 розробниками та 2 дизайнерами середовище — хаос. Один використовує #1A73E8, інший — #1565C0, а в Figma колір називається Blue/600. Темізація виливається в дублювання стилів — кожен новий дизайн вимагає переписування CSS. Команда витрачає до 20 годин на тиждень на узгодження кольорів та відступів, що призводить до 100+ стильових багів на місяць. Рішення — впровадження Design Tokens: єдине джерело правди для кольору, відступів, типографіки, тіней та анімацій. Ми пройшли цей шлях у 30+ проєктах і знаємо, як уникнути граблів. Досвід показує, що з токенами швидкість змін зростає в 3 рази, а кількість багів падає на 70%.
Чому дизайн-токени — це не просто CSS-змінні?
Пряма заміна #1A73E8 на --color-primary — це змінна, не токен. Токен несе семантику: --color-action-primary-default, --color-action-primary-hover. Різниця принципова: при зміні фірмового кольору потрібно змінити одне значення в одному місці, а не шукати всі входження «основного синього» по кодовій базі. Без токенів команда з 5 осіб витрачає до 20% часу на стилізації: дизайнер змінює Blue/600 у Figma, розробник не знає, що це #1D4ED8 вже використовується в 12 місцях під різними hex-значеннями. Темізація вимагає дублювання стилів замість перемикання набору змінних. За даними Amazon Style Dictionary, токени скорочують overhead на 40%.
Як впровадити Design Tokens у дизайн-систему?
Впровадження починається з аудиту поточних стилів та Figma. Потім ми проєктуємо трирівневу модель токенів: primitive, semantic та component. Primitive токени зберігають сирі значення без контексту: color.blue.500: #3B82F6. Semantic токени прив'язують сенс: color.action.primary.default: {color.blue.500}. Component токени задають конкретні компоненти: button.background: {color.action.primary.default}. Це дозволяє змінювати дизайн глобально, змінюючи одне значення в примітивах, і робить темізацію простим перемиканням файлів.
Трирівнева модель вирішує проблему дублювання
Якщо потрібно змінити відтінок синього, змінюється лише primitive токен, і всі компоненти автоматично отримують новий колір. Без цієї моделі довелося б правити кожну кнопку, картку та посилання окремо. Це в 10 разів ефективніше за ручне оновлення CSS.
| Проблема | Рішення з токенами | Результат |
|---|---|---|
| Різні значення одного кольору | Централізоване зберігання | Одна зміна для всіх |
| Труднощі темізації | Семантичні токени для кожної теми | Перемикання CSS-файлів |
| Невідповідність Figma та коду | Двостороння синхронізація | Єдине джерело правди |
Інтеграція токенів з Figma
Використовуємо плагін Tokens Studio для двосторонньої синхронізації з GitHub. Робочий процес:
- Дизайнер змінює токен у Figma
- Плагін пушить зміну в гілку
tokens/update-blue-palette - CI запускає Style Dictionary, генерує CSS/JS
- PR з оновленими артефактами — код-рев'ю та merge
Налаштування Tailwind для токенів
У Tailwind 4 токени підключаються через директиву @theme:
@theme {
--color-primary: var(--color-action-primary-default);
--radius-button: var(--button-radius);
}
Версіонування токенів
Токени — частина кодової бази. Зберігаємо їх у монорепозиторії дизайн-системи та публікуємо як npm-пакет @company/[email protected]. Семантичне версіонування критичне: перейменування токена — breaking change (major), додавання — minor, виправлення значення — patch або minor залежно від контексту. Changelog пишемо читабельним для дизайнерів.
Приклад структури файлів токенів
tokens/
primitive/
color.json
spacing.json
typography.json
semantic/
color.json
spacing.json
component/
button.json
card.json
Інструменти трансформації
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 генерує CSS та JS. Output для CSS:
:root {
--color-blue-500: #3B82F6;
--color-action-primary-default: var(--color-blue-500);
--button-background: var(--color-action-primary-default);
}
Темну тему можна додати окремим набором семантичних токенів і збирати в tokens-dark.css.
Етапи робіт
| Етап | Тривалість | Результат |
|---|---|---|
| Аудит існуючих стилів та Figma | 1–2 дні | Звіт про невідповідності |
| Проєктування primitive та semantic токенів | 2–3 дні | JSON-схема токенів |
| Налаштування Style Dictionary та компіляція | 2–3 дні | CSS/JS/SCSS артефакти |
| Інтеграція в проєкт | 2–4 дні | Мерж-реквест з токенами |
| Інтеграція з Figma (опціонально) | 3–5 днів | Двостороння синхронізація |
Що входить в роботу
Ми проводимо аудит поточних стилів та бібліотеки Figma, проєктуємо трирівневу схему токенів, налаштовуємо компіляцію через Style Dictionary та інтегруємо в код (CSS, JS, Tailwind). Готуємо документацію з використання токенів та навчаємо команду (1–2 години). На всі роботи діє гарантія 3 місяці на працездатність токенів.
Типові помилки при впровадженні: не змішуйте primitive та semantic токени в одному файлі; не використовуйте токени для значень, що не є дизайн-рішеннями (наприклад, z-index модалки); завжди додавайте fallback для старих браузерів; версіонуйте токени з SemVer.
Зв'яжіться з нами для попередньої оцінки вашого проєкту — ми визначимо терміни за 1 день. Отримайте консультацію інженера безкоштовно. Замовте впровадження дизайн-токенів і позбавте команду хаосу в стилях.