Перейти к основному содержимому

Дизайн-токены

Определение​

Дизайн-токены - атомарные переменные, которые хранят значения:

  • цветов
  • типографики
  • отступов
  • радиусов
  • теней
  • других UI-параметров

Токены живут отдельно от компонентов и применяются везде, где нужна визуальная консистентность.

Уровни токенов​

MUST​

  • UI-код использует семантические или компонентные токены.
  • Базовые (core) токены используются только внутри слоя токенов.

Структура​

  1. Core tokens — "сырьевые" значения.
  2. Semantic tokens — значения с бизнес-смыслом (text, bg, border, etc).
  3. Component tokens — локальные токены для компонента (опционально).

Пример

// tokens/base.json
{
  "color": {
    "base": {
      "neutral": {
        "900": { "value": "#1b1b1b" }
      }
    }
  }
}
// tokens/semantic.json
{
  "color": {
    "text": {
      "primary": { "value": "{color.base.neutral.900}" }
    }
  }
}
// tokens/components.json
{
  "button": {
    "primary": {
      "bg": { "value": "{color.bg.brand}" },
      "text": { "value": "{color.text.inverse}" }
    }
  }
}

Правила использования​

MUST​

  • Все значения UI берутся из токенов.
  • Новые компоненты не добавляют hard-code значений.

SHOULD​

  • Семантика важнее цвета: color.text.primary, а не color.blue.500.
  • Компонентные токены вводятся только если компонент реально уникален.

FORBIDDEN​

  • Использовать core токены напрямую в UI.
  • Создавать токены "на один экран".

Нейминг и структура​

MUST​

  • Имена должны отражать смысл использования, а не конкретный цвет.
  • Иерархия должна быть предсказуемой и единообразной.

Пример нейминга

color.text.primary
color.bg.surface
space.m
radius.s
shadow.level.1

❌ Плохо

color.blue.500
space.cardPadding

Темизация и ребрендинг​

MUST​

  • Переключение темы меняет семантические токены, а не UI-код.

Пример​

:root {
  --color-text-primary: #1b1b1b;
  --color-bg-surface: #ffffff;
}

[data-theme='dark'] {
  --color-text-primary: #f5f5f5;
  --color-bg-surface: #121212;
}

Поставка токенов​

MUST​

  • Токены хранятся в репозитории, отдельном от продуктового кода.
  • Продукты получают токены в виде артефактов сборки (CSS variables, TS, JSON).

SHOULD​

  • Использовать генераторы вроде Style Dictionary.
  • Версионировать токены и фиксировать изменения в changelog.

Примеры использования​

✅ Хорошо

.card {
  background: var(--color-bg-surface);
  color: var(--color-text-primary);
  padding: var(--space-m);
  border-radius: var(--radius-m);
}

❌ Плохо

.card {
  background: #fff;
  color: #1b1b1b;
  padding: 16px;
  border-radius: 12px;
}

Bad Practices​

❌ Использовать core токены прямо в UI

.title {
  color: var(--color-base-neutral-900);
}

❌ Делать токен для единичного значения

{ "space": { "promoCardSpecial": { "value": "18px" } } }

Процедуры контроля (Code Review)​

Ревьюер должен убедиться, что:​

  • UI использует семантические/компонентные токены
  • в новом коде нет hard-code значений
  • нейминг токенов не содержит "цветовых" названий
  • темы меняются через токены, а не через стили компонентов