Гайд по Token Diff

Token Diff сравнивает две версии токенов дизайн-системы и показывает, что изменилось, что сломается у тех, кто ими пользуется, и какой номер версии нужен релизу. Открыть Token Diff

Зачем он нужен

Обычно релиз токенов проверяют по диффу JSON в pull request. Такой дифф прячет именно то, что бьёт по пользователям:

• Переименование выглядит как удаление и добавление. Никто не замечает, что space-sm стал space-small, пока не упадёт сборка.
• Цепочки ссылок прячут последствия. Поменяли один базовый цвет — тихо поменялись все семантические токены, которые на него ссылаются.
• Темы легко пропустить. Значение может измениться только в тёмной теме, в одном файле из двадцати.
• Номер версии ставят на глаз. Удаление, выпущенное минорной версией, ломает всех, кто обновился.

Token Diff читает обе версии так, как их увидит пользователь: разрешает все ссылки в каждой теме, сопоставляет токены между версиями и оценивает каждое изменение по тому, к чему оно приведёт.

Все иллюстрации на этой странице живые: dsgraph прямо в вашем браузере сравнивает небольшую учебную дизайн-систему — две версии одного CSS-файла со светлой и тёмной темой, — и вы видите ровно то, что показал бы Token Diff.

Кому он нужен

Как пользоваться

1. Выберите две версии. Для каждой стороны — один из источников:
   • npm: имя пакета; версии подтянутся сами, по умолчанию последняя сравнивается с предыдущей.
   • GitHub: владелец/репозиторий/папка и ветка, тег или коммит. Без токена GitHub даёт 60 запросов в час; для приватного репозитория нажмите Токен и вставьте токен с правом чтения. Он хранится только во вкладке и не попадает в ссылки.
   • Файлы: перетащите на строку файлы токенов или целую папку либо выберите их вручную.
2. Добавьте свой код, если хотите. Перетащите папку проекта в строку Ваш код или переключите её на GitHub и укажите репозиторий: стили, JSX и TSX, классы Tailwind, Vue и Svelte читаются в браузере и никуда не загружаются. Репозиторий попадает и в ссылку, так что результатом можно поделиться. Тогда в результате будут места в вашем коде, которые каждое изменение сломает или изменит, доля значений на токенах и то, что написать вместо значений, вписанных вручную.
3. Нажмите «Сравнить» (⌘ ↵).
4. Прочитайте результат и выгрузите то, что нужно.

Token Diff понимает JSON в формате DTCG 2025.10 (включая документы резолвера с наборами и темами, а также режимы в $extensions.mode из выгрузки переменных Figma), JSON токенов старого формата с value и type (наборы токенов, файлы тем и ссылки вида .value тоже), CSS-переменные с темами в :root, [data-theme], .dark или prefers-color-scheme и снимки dsgraph. Формулы вроде {space.base} * 2 и модификаторы цвета вычисляются, поэтому изменение базового значения видно во всём, что на нём построено. Если в пакете много файлов, укажите нужные в поле Файлы, например dist/tokens.css или tokens/**/*.json.

Что вы получите

• Итог: ломающий, минорный, патч или без последствий — и цифры, на которых он основан.
• То, что сломается, — первым: удалённые токены, переименования с оценкой уверенности, смена типа, токены, пропавшие из темы.
• Изменения значений по темам: цвета — образцами с ΔE, размеры — с разницей в пикселях, и для каждого значения видно, по какой ссылке оно пришло.
• Последствия: для каждого изменённого токена — токены, которые изменились из-за него через ссылки, на схеме графа.
• Проверки новой версии: битые ссылки, ссылки по кругу, старый синтаксис, совпадающие имена. Одинаковые замечания сгруппированы, так что 300 одинаковых предупреждений занимают одну строку.
• Ваш код, если вы его добавили: места, которые каждое изменение сломает или изменит, доля значений на токенах и что написать вместо значений, вписанных вручную.
• Выгрузки: Markdown для changelog или pull request, полный список изменений в JSON и карточка 1200 × 630 для поста.

Граф

Токены ссылаются друг на друга. В JSON запись "value": "{color.blue.500}" значит, что токен берёт значение у color.blue.500; в CSS то же самое — var(--color-blue-500). dsgraph представляет каждый токен точкой, а каждую такую ссылку — линией между двумя точками. Граф строится отдельно для каждой темы: тема может заменить ссылку собственным значением.

Именно граф позволяет Token Diff отличить изменение от его последствий. Когда меняется color-blue-500, вместе с ним меняется color-accent, хотя его никто не трогал. Token Diff показывает color-accent под изменением, которое его вызвало, а не отдельной строкой, и рисует цепочку: сверху — откуда токен берёт значение, снизу — какие токены его используют. Изменившиеся токены обведены цветом своего уровня; щёлкните по такому, чтобы открыть его изменение.

Как читать результат

Итог над списком — это самый высокий уровень среди всех изменений. В примере релиз ломающий: один токен удалён, один переименован.

Список сгруппирован по тому, что изменение значит для тех, кто пользуется токенами: «Сломается», «Выглядит иначе», «Новое», «Устарело» и «Почти незаметно» — последнее свёрнуто, если таких изменений много. То, что сломается, идёт первым. У удалённого токена видно значение, которое у него было. Переименование распознаётся по одинаковым значениям во всех темах и похожим именам; уверенность ниже 80 % значит «проверьте вручную».

Изменения значений показывают оба значения и разницу словами: светлее · заметно, +2px. Для цветов слова берутся из ΔE — расстояния в OKLab, отмасштабированное так, что 1 — примерно минимальная разница, которую замечает человек; всё, что меньше 1, считается патчем. Через ссылки значит, что сам токен не трогали, но изменилось то, на что он ссылается.

Темы. Выберите тему в строке фильтров, чтобы видеть только то, что меняется в ней. Изменения, которые касаются всех тем, остаются на месте.

Проверки запускаются на новой версии. Одинаковые проблемы сгруппированы, так что файл в формате до 2025 года даёт несколько строк, а не сотни. Пояснения к проверкам — на русском, а исходные сообщения движка остаются на английском, как в CLI.

Как поделиться

• Скопировать Markdown (⌘ ⇧ C) — раздел для changelog, сгруппированный по уровням. Это тот же текст, что пишет dsgraph CLI, поэтому он без правок подходит для комментария в pull request. Отчёт выгружается на английском.
• Скопировать ссылку — поделиться самим сравнением. Для npm и GitHub ссылка — это просто адрес страницы. Ваши файлы помещаются в часть ссылки после #, которую браузер никогда не отправляет на сервер; большие файлы так передать нельзя — поделитесь Markdown или JSON.
• Карточка для поста — PNG с итогом, цифрами и изменившимися цветами.

Клавиатура

В Windows и Linux вместо ⌘ — Ctrl.

Приватность

Всё работает во вкладке браузера. Перетащенные файлы никуда не загружаются. Пакеты скачиваются с jsDelivr, репозитории — с GitHub, причём напрямую вашим браузером. Ни регистрации, ни хранения данных.

В CI

На GitHub action сравнивает каждый pull request с базовой веткой и обновляет в нём один комментарий с тем же отчётом:

- uses: actions/checkout@v4
- uses: specsure/dsgraph-action@v1
  with:
    path: tokens
    fail-on: major

С fail-on: major проверка падает на ломающих изменениях, и выпустить их под видом минорной версии не получится. В других CI то же самое делает CLI:

npx @dsgraph/cli diff npm:@scope/tokens@1.4.0 ./tokens --format markdown --fail-on major

В вашем приложении

Если приложение использует чужой пакет токенов, проверьте обновление до того, как его взять. В Token Diff поставьте рядом вашу версию и новую и добавьте приложение в строку Ваш код — папкой или репозиторием на GitHub. В терминале, в папке проекта:

npx @dsgraph/cli upgrade-check @scope/tokens

Команда сравнит вашу версию с последней и покажет места в коде, которые сломаются или будут выглядеть иначе, с файлом и строкой: CSS, SCSS и Sass, объекты стилей и CSS-in-JS в JSX и TSX, классы Tailwind, Vue, Svelte и Astro. На GitHub то же самое делает action с package: '@scope/tokens': он пишет этот список в pull request, который поднимает версию.

Что дальше

• Плагин для Figma. Проверка переменных и стилей Figma по вашим токенам прямо в Figma. Скоро.
• Палитра и отступы самого Tailwind (bg-blue-500, p-3) в проекте со своей дизайн-системой: значения мимо системы с токеном на замену.