Коли команда вперше сідає будувати дизайн-токени, майже завжди відбувається одне й те саме: хтось відкриває Figma Variables, створює кілька кольорів типу button/primary/background і вважає, що токени готові. Це не токени — це захардкоджені значення з гарними назвами.

Справжня архітектура токенів складається з трьох шарів, і важливо розуміти, для чого кожен існує.

Три шари: primitive → semantic → component

Primitive-токени — це сирі значення без контексту. Вони описують "що є", але не "де використовується". Наприклад: color/blue/500: #3B82F6, color/gray/100: #F3F4F6, spacing/4: 16px. Primitive-токени ніколи не використовуються напряму в компонентах.

Semantic-токени — це посилання на primitives з контекстуальним значенням. Наприклад: color/background/primary: {color/blue/500}, color/text/muted: {color/gray/400}. Саме цей шар дає можливість зробити темну тему: ви просто змінюєте значення semantic-токена, а не переписуєте всі компоненти.

Component-токени — опціональний третій шар для компонентів з особливою логікою. Наприклад: button/primary/background: {color/background/primary}. Потрібен тоді, коли один компонент має свої унікальні варіації, які не описуються semantic-рівнем.

Правило: якщо ваш semantic-токен вказує безпосередньо на hex-значення — у вас немає primitive-шару. Якщо ваш компонент вказує безпосередньо на hex — у вас немає жодного шару.

Як назвати primitive-токени

Найчастіша помилка — давати примітивам семантичні назви. Не треба color/brand/primary на рівні primitive. Треба color/lime/400. Primitive описує колір, а не його призначення.

Рекомендована структура назви: category / scale / step. Для кольорів: color/{hue}/{step}, де step — число від 50 до 950 або 100 до 900 (Tailwind-підхід). Для spacing: spacing/{multiplier}, де multiplier — крок сітки (4, 8, 12, 16...).

Чому не можна починати з семантики

Якщо у вас немає primitive-шару, при зміні брендового кольору доведеться оновлювати десятки semantic-токенів вручну. З primitives — ви змінюєте одне значення, і всі посилання оновлюються автоматично.

Друга проблема — темна тема. Без primitives реалізувати dark mode без дублювання всіх токенів практично неможливо. З правильною архітектурою — це питання годин, а не тижнів.

Як почати: мінімальний набір primitives

  • Кольори: мінімум 2 кольори бренду × 9 ступенів, нейтральна шкала (gray) × 9 ступенів, semantic кольори (success, error, warning, info) × 3 ступені
  • Spacing: кратно 4px або 8px — від 2px до 64px
  • Typography: font-size, line-height, font-weight, letter-spacing — окремими шкалами
  • Border radius: від 0 до full (999px)
  • Shadow: sm, md, lg, xl

Практичний крок: почніть з кольорової шкали

Візьміть свій брендовий колір. Згенеруйте шкалу з 9–11 ступенів (найсвітліший 50, найтемніший 950). Зробіть це для кожного кольору бренду і для нейтрального gray. Це і є ваш перший primitive-шар. Далі — маппінг на semantic.

Правильна архітектура токенів — фундамент, який вирішує 80% проблем масштабування дизайн-системи наперед.