---
id: design-tokens
sidebarLabel: Дизайн токены

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

Дизайн-токен — атомарная единица дизайна (цвет, типографика, отступ, тень), которая используется для построения визуальной части интерфейса. Как правило дизайн-токен не зависит от конкретной платформы (web, mobile) и может быть преобразован в любой формат (css, json, xml), при помощи [themekit][themekit], данный подход позволяет переиспользовать токены в различных системах.

Токены можно разделить на два типа — **глобальные токены** и **токены компонента**.

## Глобальные токены

Глобальные токены как правило описывают примитивы, такие как палитра, типографика, размерная сетка и распологаются в папке с темой проекта, это позволяет вносить визуальные изменения для всего проекта в одном месте.

**💁‍♂️ Пример:**

```sh
‣ src/Theme/
├── themes
│   └── • default.theme.json
└── tokens
    ├── • color-light.tokens.yml
    ├── • legacy.tokens.yml
    ├── • space.tokens.yml
    └── • typography.tokens.yml
```

## Токены компонента

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

**💁‍♂️ Пример:**

```sh
‣ src/Component
└── Component.tokens
    └── • Component.tokens.yml
```

### Структура

> При создании новых токенов желательно сохранять максимально плоскую структуру файла.

Файл может состоять из:

1. Базовых токенов компонента/элемента
1. Токенов модификаторов компонента/элемента

В результате итоговый токен может содержать информацию об компоненте, модификаторе/элементе и его состоянии.

**💁‍♂️ Пример (yml):**

```yaml
button:
  # Базовый токен компонента
  borderRadius:
    value: "4px"

  # Элемент
  text:
    # Базовый токен элемента
    fontFamily:
      value: "Arial"

  # Модификатор
  sizeM:
    # Токен модификатора компонента
    padding: "0 8px"

    text:
      # Токен модификатора элемента
      fontSize:
        value: "16px"
```

**💁‍♂️ Результат (css):**

```css
:root {
  --button-border-radius: 4px;
  --button-text-font-family: Arial;
  --button-size-m-padding: 0 8px;
  --button-size-m-text-font-size: 16px;
}
```

## Хорошие практики

### Избегайте излишней вложенности

Излишняя вложенность для "сохранения контекста" усложняет понимание и дальнейшую поддержку такого файла.

**🚫 Плохо:**

```yml
button:
  font:
    weight:
      bold:
        value: "..."
```

**✅ Хорошо:**

```yml
button:
  fontWeightBold:
    value: "..."
```

### Обозначения элементов

Так как токен *свойства* сложно отличить от токена *элемента*, желательно добавлять комментарий с пояснением.

**💁‍♂️ Пример:**

```yaml
button:
  # Элемент Button-Text
  text:
    fontFamily:
      value: "Arial"
```

### Понятное описание для документации

При необходимости есть возможность дополнительно описать токен для документации.

**💁‍♂️ Пример:**

```yaml
button:
  borderRadius: "4px"
  comment: "Внешнее скругление кнопки"
```

### Использование глобальных токенов

Если в проекте уже существует токен с необходимым значением, то стоит ссылаться на него и не писать значение по месту использования.

**🚫 Плохо:**

```yaml
button:
  text:
    fontFamily:
      value: "'YS Text', 'Helvetica Neue', Helvetica, Arial, sans-serif"
```

**✅ Хорошо:**

```yaml
button:
  text:
    fontFamily:
      value: "{typography.fontFamily.value}"
```

### Описание состояний

Ниже собран пример с именованием распространенных состояний компонента.

**💁‍♂️ Пример:**

```yaml
button:
  fillColor:
    # Базовое состояние
    base:
      value: "..."
    # Состояние ховера
    hovered:
      value: "..."
    # Состояние фокуса
    focused:
      value: "..."
    # Неактивное состояние
    disabled:
      value: "..."
    # Состояние нажатия
    pressed:
      value: "..."
    # Выбранное состояние
    selected:
      value: "..."
    # Отмеченное состояние
    checked:
      value: "..."
    # Состояние прогресса
    progress:
      value: "..."
```

[themekit]: https://github.com/bem/themekit