Как контролировать токены: поиск ошибок, версионирование и графы в едином дашборде

Как только дизайн-система разрастается больше, чем на 10-20 кнопок, а брендов у вас становится несколько — JSON-файлы с токенами превращаются в кошмар. Дизайнеры экспортируют токены из Figma, разработчики получают пулл-реквест на 5000 строк измененного кода, и никто в здравом уме не может сказать: «А что именно поменялось и ничего ли мы не сломали?»

А если вместо английской буквы «c» в коде будет русская? А что если токен зациклился сам на себя? А если у одних токенов более 3-х уровней вложенности, то как поведет себя система? А если нужного токена нет в одном из модов? Да и вообще, как узнать, какие токены можно вынести в примитивы, а какие в семантику и отдельные файлы для брендов?

Чтобы решить эти проблемы, я написал веб-интерфейс Tokens Dashboard — ты кидаешь в него скучный JSON (архив, папку, файл, несколько файлов — не важно), а он выдает красивую и понятную аналитику. И сегодня мы разберемся, как это работает.

Программа полностью бесплатная и доступна как для пользователей Mac OS, так и Linux / Windows. Она портативна и не мусорит в системе — вы просто удаляете папку, если она вам больше не нужна.

✴️ Установка и запуск

Для начала нужно скачать с GitHub архив с программой — вот прямая ссылка, кому лень кликать два раза.

Затем архив нужно распаковать в любую удобную папку, после чего запустить либо run-mac-linux.sh, если у вас Mac OS или Linux, либо run-windows.bat, если у вас Windows.

После этого в вашем браузере автоматически откроется вкладка с программой, после чего нужно будет импортировать ваши токены. Как я уже говорил, можно импортировать архив, папку, просто файл формата JSON, либо сразу несколько файлов.

Вы можете как нажать кнопку импорта посередине, так и сверху справа.

Далее рассмотрим функционал и метрики качества токенов дизайн-системы.

✴️ Метрики качества токенов

Чтобы хотя бы первично понимать, что вообще происходит в токенах, особенно если их за 10 тысяч, я решил внедрить метрики, о которых ниже:

1. Архитектурные метрики — это общая информация о кол-ве токенов

   1. Total Values — это сколько в принципе токенов в JSON-файле

   2. Unique tokens — сколько токенов в каждом моде (бренде / теме)

   3. Varying — это количество токенов, которые меняют свое значение в зависимости от мода (например, цвет кнопки черный в светлой теме и белый в темной)

   4. Static — это кол-во одинаковых токенов в каждом из модов, т.е. это те значения, которые перегружают файл и указывают на легаси или переизбыток компонентных значений

2. Метрики ошибок и предупреждений — система показывает, что может сломать прод!

   1. Orphans — это значения, которые есть в одном моде, но отсутствуют в другом. Грозит это смертью приложения при переключении мода, так как компоненту неоткуда будет взять значение

   2. Broken — это семантические токены, которые ссылаются на пустоту! Т.е. им неоткуда подтянуть реальные значения, ссылка битая

   3. Errors — это разного рода ошибки. Например, русская «c» вместо латиницы, зацикливания, конфликт типов (в одном моде colors, в другом numbers)

3. Метрики производительности — показывают, насколько система будет быстро работать

   1. Chain depth — это максимальное количество слоев токенов. Если больше 3-х, то готовьтесь к тормозам!

   2. Hardcoded — это семантические токены, значения в которых вписаны напрямую без ссылки на примитив! Грубое нарушение…

   3. Unused — это примитивные токены, которые не используются в семантическом слое. Т.е. просто мертвый груз

4. Health Score (Индекс здоровья системы) Программа не просто собирает ошибки, она высчитывает глобальную оценку вашей дизайн-системы. Из идеальных 100 баллов вычитаются штрафы: за каждую битую ссылку, хардкод или слишком глубокую вложенность алиасов.

✴️ Режимы работы дашборда

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

Режим Explorer — тут собраны все токены и значения, между которыми можно переключаться посредством древовидной структуры в сайдбаре.

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

В режимах Compare и Static мы можем посмотреть, какие значения у токенов схожи во всех режимах, а какие отличаются.

Режим Diff показывает нам, что поменялось в новой версии относительно предыдущей. Что добавилось, удалилось или изменилось.

Для его работы нужно импортировать новую версию токенов, и она будет сравниваться с предыдущей.

Режимы Orphans, Broken, Errors, Hardcoded и Unused наглядно отображают токены и значения по правилам метрик, к которым они относятся. Метрики я описывал в разделе выше.

Остался последний режим отображения — High usage. В нем можно посмотреть, какие токены и значения самые популярные в системе.

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

Еще раз продублирую ссылку на репозиторий и буду рад вашей обратной связи! Видите ли вы для себя использование этого инструмента? Что бы добавили или улучшили?