Поганий нейменінг токенів — одна з головних причин, чому дизайн-системи деградують. Дизайнер бачить color-primary і думає, що це синій бренд-колір. Розробник бачить те саме і використовує для кнопки. Через пів року хтось міняє color-primary на темно-зелений, і половина UI ламається несподівано.

Вирішення — семантичний нейменінг і чітка ієрархія рівнів.

Три рівні токенів

Primitive (глобальні): Чисті значення без контексту. Визначають всю палітру системи.

  • color.green.500 → #A8FF57
  • color.blue.400 → #57D9FF
  • spacing.4 → 16px

Semantic (семантичні): Описують призначення, посилаються на primitive. Це основний шар для використання в компонентах.

  • color.action.primary → {color.green.500}
  • color.text.default → {color.neutral.100}
  • color.background.surface → {color.neutral.900}

Component (компонентні): Специфічні для компонента, посилаються на semantic.

  • button.primary.background → {color.action.primary}
  • button.primary.text → {color.text.inverse}

Правила нейменінгу

Правило 1: назва описує призначення, не значення.

❌ color.green — прив'язує до кольору, а не до функції
✅ color.action.primary — описує роль у системі

Правило 2: використовуйте kebab-case або dot.notation, не camelCase.

CSS-змінні не підтримують крапки, але в Tokens Studio та W3C DTCG стандарті dot-notation є стандартом. Конвертація відбувається автоматично через Style Dictionary.

Правило 3: консистентний порядок сегментів.

Формат: категорія.компонент-або-роль.властивість.стан
Приклад: color.button.background.hover

Золоте правило: якщо ви перейменуєте токен — і в Figma, і в CSS-змінній назва має бути однаковою (або маппинг задокументований). Розбіжність між Figma і кодом — найчастіша причина плутанини.

Нейменінг для dark/light режимів

Не робіть color.background.dark і color.background.light — це антипатерн. Натомість: один семантичний токен color.background.surface, який перемикається залежно від активного mode (через Figma Variables modes або CSS data-theme).

Чеклист перед релізом токенів

  • Всі primitive токени визначені і не використовуються напряму в компонентах?
  • Semantic токени описують роль, а не значення?
  • Назви узгоджені між Figma і кодом?
  • Є документація: що означає кожен токен і де використовується?
  • Є заборона на hardcode-значення в компонентах?

Будуємо правильну token-архітектуру з першого дня — primitive, semantic, component, light/dark mode і повний Style Dictionary pipeline.