Дизайн-токены: имена вместо чисел

Дизайн-токен — именованное дизайн-решение, например цвет главного действия, независимое от платформы. Формат W3C DTCG — общий JSON для файлов токенов.

Имя вместо числа

Слова «этот синий» на странице значат одно, а в голове у разработчика другое. Один пишет #0b5cad, другой #0c5cae, третий «чуть темнее». Вместо этого можно один раз решить: «это цвет действия», дать решению имя, и везде ссылаться на имя. Именованное дизайн-решение называется дизайн-токеном.

Токен это не то же самое, что CSS-переменная. Переменная это механизм: способ хранить значение на странице. Токен это договорённость: у решения есть имя, значение, смысл и хозяин, а хранится оно независимо от платформы. Из одного файла токенов получают и CSS-переменные для сайта, и переменные для Figma, и значения для приложения на телефоне. Поэтому две системы, где всё названо токенами, можно привести к одному виду, не переписывая вручную.

Три слоя

Если называть токены просто по цвету («синий-600»), смены темы вы не переживёте: кнопка так и останется синей. Поэтому токены складывают в три слоя, и каждый ссылается на нижний.

1. Базовые (primitive). Сырые значения: color.accent.600 равно #0b5cad, space.4 равно 16 пикселей. Это «палитра» и «линейка». Базовые токены называют по виду.
2. Смысловые (semantic, их ещё называют alias). Роли: semantic.action (цвет главного действия), semantic.surface (фон), semantic.text (цвет текста). Они ссылаются на базовые и называются по роли.
3. Компонентные. Значения для конкретной детали: component.button.bg (фон кнопки) ссылается на semantic.action.

Почему именно так? Сменить базовый цвет акцента: изменится смысловой токен, который на него ссылается, а за ним все компоненты, которые ссылаются на смысловой. Сменить тему: у смысловых токенов surface и text заменяют ссылку на другие базовые значения, а компоненты вообще не трогают, потому что они ссылаются на роли, а не на цвета.

Поиграйте: измените базовый цвет, выберите другую ступень для действия и переключите тему. Слева файл токенов, справа цепочка ссылок и результат.

{
  "color": {
    "$type": "color",
    "accent": {
      "500": {
        "$value": "#3c7dbd"
      },
      "600": {
        "$value": "#0b5cad"
      },
      "700": {
        "$value": "#084582"
      }
    },
    "neutral": {
      "50": {
        "$value": "#faf9f7"
      },
      "900": {
        "$value": "#1c1b19"
      }
    }
  },
  "semantic": {
    "$type": "color",
    "action": {
      "$value": "{color.accent.600}"
    },
    "surface": {
      "$value": "{color.neutral.50}"
    },
    "text": {
      "$value": "{color.neutral.900}"
    }
  },
  "component": {
    "button": {
      "bg": {
        "$type": "color",
        "$value": "{semantic.action}"
      },
      "fg": {
        "$type": "color",
        "$value": "{semantic.surface}"
      }
    }
  }
}

В реальных системах то же самое. В Material Design 3 три слоя называются reference, system и component. В Fluent 2 это глобальные токены и алиасы. У Atlassian имя состоит из свойства, роли и состояния: color.text.accent.red.

Как называть токены

Правила, которые помогают не запутаться:

• Смысловые и компонентные по роли, базовые по виду. Не color.dark-grey, а color.text.primary: тёмно-серый можно заменить, а роль останется.
• Иерархия слева направо: от общего к частному: color → text → primary.
• Состояния отдельным словом: hover, pressed, disabled.
• Шкала в числах для базовых ступеней (50, 100, … 900) и отступов (space.2, space.4).
• Не прячьте смысл в числе. Имя space.4 лучше, чем space.16: если шаг поменяется, имя не станет ложью.

Формат W3C DTCG

Чтобы файл токенов понимали все инструменты, у него есть общий формат. Его разрабатывает W3C Design Tokens Community Group, сообщество разработчиков, дизайнеров и производителей инструментов. В октябре 2025 года вышла первая стабильная версия формата (2025.10).

Файл это JSON. Расширение по рекомендации .tokens.json. Структура такая:

• Токен: объект со свойством $value (обязательно), необязательными $type (тип) и $description (пояснение).
• Группа: объект без $value, в котором лежат токены и вложенные группы. Тип можно задать на группе, тогда он наследуется.
• Ссылка на другой токен: значение в фигурных скобках, например "{color.accent.600}".
• Типы: color, dimension, fontFamily, fontWeight, duration, cubicBezier, number и составные (shadow, border, typography и другие).

{
  "color": {
    "$type": "color",
    "accent": { "600": { "$value": "#0b5cad" } }
  },
  "semantic": {
    "$type": "color",
    "action": { "$value": "{color.accent.600}" }
  }
}

Оговорка про запись значений. В ранних черновиках цвет писали строкой ("#0b5cad"), а размер строкой ("16px"). Стабильная версия 2025.10 описывает цвет объектом с цветовым пространством и компонентами (colorSpace, components, необязательно hex), а размер и время объектом из числа и единицы: { "value": 16, "unit": "px" }. Много файлов и инструментов всё ещё используют краткую запись, поэтому вы встретите обе. В практике мы пользуемся краткой записью, чтобы не считать компоненты цвета руками.

Из файла токенов программа вроде Style Dictionary делает выходные файлы под каждую платформу: CSS-переменные, значения для iOS и Android. Вам для маленького сайта хватит написать переменные вручную, повторив структуру файла.

Токены в CSS

В CSS слои повторяют структуру файла: сначала базовые, потом смысловые через var(), потом компонентные.

:root {
  --color-accent-600: #0b5cad;
  --action: var(--color-accent-600);
  --button-bg: var(--action);
}
[data-theme="dark"] {
  --surface: var(--color-neutral-900);
}

Теперь любое правило ссылается на var(--button-bg), а не на цвет. Если в CSS где-то остался «сырой» цвет вне блока переменных, это значит, что токен пропущен: проверьте это сами поиском по файлу.

Живой пример: токены этого учебника

У самого учебника токены устроены так же. Откройте файл design/tokens.css в репозитории: он не писался вручную, а получен из файла токенов в формате DTCG в проекте NoeticEcho (откуда и как, записано в design/PROVENANCE.md). В нём те же слои. Базовые значения называются по виду и ступени (--ink-100, --paper-100, --brass-500). Смысловые называются по роли (--surface-canvas, --text-primary, --accent-command) и ссылаются на базовые через var(). И там, где автор что-то решил, оставлен комментарий: например, у цвета для текста есть отдельная, более светлая ступень, потому что исходный цвет на тёмной панели не проходил проверку контраста. Решение записано в имени и в файле, а не в голове автора.

Практика

Соберите токены вашего проекта в двух видах. Сначала допишите файл в формате DTCG (он лежит прямо на странице как блок script с типом application/json; на готовом сайте его не будет, он помечен data-scaffold). Потом повторите те же токены переменными в styles.css и сделайте тёмную тему, переопределив только смысловой слой.

Когда проверки пройдут, поменяйте --color-accent-600 и посмотрите, как перекрасились обе кнопки. Если одна осталась прежней, значит, где-то остался «сырой» цвет.

Что было не так с 2014 годом

В 2014 году переменных в CSS почти не было: цвета повторяли в двадцати местах, а для «переменных» пользовались препроцессорами вроде Sass и Less, которые подставляли значения до того, как страница попадала в браузер. Нативные CSS-переменные только что появились в Firefox, а во всех основных браузерах они заработали к 2017 году. А единого формата токенов не было вообще, и каждая система придумывала свой.