Первый компонент мы собирали два дня, пятнадцатый занял у нас пятнадцать минут. Всё, что появилось между ними, — это файл DESIGN.md, набор правил и понимание, в каких местах нейросеть сочиняет алиасы, которых в системе никогда не было.

Привет, Хабр! Меня зовут Екатерина, я продуктовый дизайнер и развиваю дизайн-систему «Сова» в ИТ-экосистеме «Лукоморье».

Нам нужно было связать дизайн, токены и код на уровне компонентов. Для этого пришлось описать каждый компонент до мелочей: размеры, варианты, состояния, отступы, цвета. Руками такое делать можно долго, поэтому механическую часть мы отдали нейросети. Всё получилось не с первого раза.

Ниже — весь процесс целиком: как мы выгружали компоненты из Pixso, что писали в markdown-файлах с правилами и шаблонами и как потом проверяли, что нейросеть не насочиняла лишнего.

Что такое компонентные токены

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

Базовые токены — это исходные значения системы: цвета, размеры, отступы, радиусы, типографические параметры и другие примитивы.

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

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

Проще всего показать разницу на кнопке.

Семантический токен задаёт роль значения: например, error.default используется для ошибки или опасного действия.

Компонентный токен уточняет: в кнопке в состоянии ошибки используется фон с цветом error.default.

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

Звучит как отличный способ тихо возненавидеть задачу. Первые пару компонентов ощущаются именно так: много ручной проверки и сомнений. Но потом появляется база из понятных паттернов, правил для агента и примеров, на которые она может опираться.

JSON как способ описать компонент

Ещё один важный термин для этого процесса — JSON-экспорт компонента. В нём можно формально описать компонент: его имя, тип, размеры, состояния и настройки цвета, обводки и других свойств. Это удобно, когда данные нужно передать агенту из Pixso, а затем превратить в структуру компонентных токенов.

По ходу статьи я буду постоянно различать два файла — их легко перепутать:

  • JSON-экспорт компонента — техническое описание исходного компонента из Pixso. То, что мы отдаём агенту на входе.

  • Итоговый JSON компонентных токенов — структура токенов, которую мы создаём для компонента. То, что мы отдаём разработчикам на выходе.

Зачем нужен компонентный слой

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

Они не отвечают на вопросы:

  • какой алиас использовать для фона кнопки;

  • какой алиас поставить на текст внутри кнопки;

  • какой цвет должен быть в состоянии disabled;

  • какой отступ нужен для размера m;

  • какое скругление должно быть у контейнера;

  • что меняется при hover, pressed или disabled.

Из-за этого между семантическими токенами и реальным компонентом остаётся пустое место. Дизайнер может выбрать нужные стили в макете, но его решение не становится правилом системы на уровне кода и логики компонента.

Компонентные токены закрывают этот разрыв. Они описывают, какие значения должен использовать компонент в каждом размере, варианте и состоянии. У дизайнера появляется возможность зафиксировать правила компонента в форме, которую можно использовать и в дизайне, и в коде.

С одной стороны, это даёт больше контроля: компонент перестаёт быть набором слоёв в макете и становится описанной моделью с понятными правилами.

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

Как выглядит процесс целиком

Чтобы не описывать компонент вручную, мы собрали процесс вокруг JSON-экспорта из Pixso. Семь шагов:

  1. Выбрать компонент в Pixso.

  2. Сформировать JSON-экспорт компонента через плагин.

  3. Передать в ИИ JSON-экспорт, базовые и семантические токены, token_rules.md и пример-шаблон.

  4. Получить черновик компонентных токенов.

  5. Проверить структуру: оси, состояния, алиасы, вложенность и лишние свойства.

  6. Доработать результат вручную.

  7. Передать итоговый JSON компонентных токенов разработчикам.

ИИ берёт на себя механическую часть: разбирает JSON-экспорт, собирает повторяющуюся структуру и предлагает алиасы. Финальное решение остаётся за дизайнером. Нужно проверить архитектуру токенов, смысл алиасов, спорные случаи и соответствие реальному поведению компонента.

С какими вводными мы стартовали

Не буду лукавить, лабораторного кейса с дизайн-системой в идеальном состоянии у нас не было.

Исходная веб-дизайн-система жила в Pixso. Готовой библиотеки с переменными, уже привязанными к компонентам, не существовало. На тот момент Pixso не поддерживал переменные, поэтому внутри компонентов использовались цветовые и типографические стили, а размеры, отступы и другие параметры часто оставались сырыми числовыми значениями.

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

Наша задача была завайбкодить поверх этого слой компонентных токенов. И сразу возникла проблема: как перенести все настройки компонента в формат, который поймёт ИИ?

Описывать вручную нереально. Кнопка из примера выше — малая часть того, какие нюансы может содержать компонент. Если в инпут вложены другие компоненты, то эту иерархию и зависимости нужно корректно отразить в реализации компонента.

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

Что агент поймёт по такому экспорту кнопки:

  • структуру компонента, варианты и состояния, скрываемые слои и настройки в Pixso;

  • размеры каждого элемента, настройки типографики и всех вложенных элементов;

  • логику работы компонента при переключении состояний и вариантов.

Как устроен компонентный токен

Шаг первый: оси

Для удобства дальше я буду называть размер, вариант, цветовую схему и состояние осями нашей структуры компонентных токенов. Они формируются из вариантов и состояний компонента. На верхнем уровне свойства разделяются на две независимые ветки: size и variant.

Ветка size хранит геометрию. Размер сильнее всего влияет на остальные свойства и значения внутри компонента. В случае нашей кнопки свойство size становится одной из осей, а xl, l, m и s — её значениями.

Визуальная ветка variant строится в порядке variant → colorScheme → state. Ось colorScheme не меняет устройство кнопки, только цветовую схему уже выбранного варианта, поэтому идёт следующей, уже внутри оси варианта. Последняя ось state изменяет конкретную комбинацию варианта и цветовой схемы.

Именно от порядка осей зависит итоговое имя токена:

button.size.m
button.variant.accent.primary.default

Размерная ветка отвечает за геометрию, вариантная — за внешний вид. Вместе они формируют одну кнопку.

Что не становится осью? Скрываемые слои вроде iconLeft и iconRight, а также замена конкретной иконки — они отдельные оси не создают. Они управляют видимостью и содержимым компонента.

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

Шаг второй: наполнение свойствами

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

На этом этапе важно записать всё, чем команда действительно хочет управлять через компонентные токены.

Логика такая: оси отвечают на вопрос «для какой комбинации действует правило», а содержимое — «какое именно свойство и значение мы в ней задаём».

Шаг третий: наполнение значениями

После того как ветки и свойства определены, каждому конечному токену нужно присвоить значение. Каждый токен содержит три поля:

  • value — непосредственное значение или ссылка на другой токен;

  • type — тип данных;

  • description — понятное описание роли токена.

В поле value мы обязательно указываем существующий алиас, например interactive.accent, а не исходный цвет или число. Если поставить сырое HEX-значение, при изменении алиаса настройки в компонент не притянутся. Помните про цепочку зависимостей: компонентный токен хранит ссылку на семантический, а тот — на базовый.

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

На вашей стороне остаётся ответственность продумать список значений, которыми требуется управлять, и корректно выгрузить данные.

Шаг четвёртый: перепроверка

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

Что смотрю в первую очередь:

  • читается ли итоговый JSON;

  • не конфликтуют ли имена;

  • корректно ли подтягиваются алиасы;

  • корректно ли разрешаются ссылки между токенами;

  • не воспринимает ли инструмент какое-то имя как служебное.

Силы нашей среды вайбкодинга здесь были быстрым помощником, который за пару минут накидает структуру, но также быстро добавит пять лишних осей, если его не остановить 😄

На первых генерациях ошибок было много, но после четвёртого-пятого компонента структура устаканилась, и правок стало значительно меньше.

4. Как настроить работу с ИИ

Минимальный набор входных данных:

  • компоненты в Pixso или Figma с правильными настройками;

  • сгенерированный и установленный плагин для создания JSON-экспорта;

  • готовый JSON базовых и семантических токенов;

  • умение работать в Tokens Studio. Там легче править и проверять, чем в VS Code, особенно если опыта работы с кодом не было.

Как настроен проект

В агентской среде мы создали проект с загруженными документами, на который чат ссылается постоянно:

  • JSON базовых и семантических токенов;

  • пример-шаблон компонентного токена самого сложного компонента;

  • token_rules.md с правилами создания компонентных токенов и ограничениями.

Как облегчить чату работу

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

Например, не всё, что решено на дизайне, должно точно так же решаться в коде. Состояние loading я сделала в компоненте через отдельный вариант loading: true/false, чтобы дизайнеры быстрее включали его в макете. В принятой нами структуре токенов мы описываем loading как состояние. Прочитав скрин, агент сопоставит логику настройки макета с данными из JSON-экспорта и учтёт этот нюанс.

Основные ошибки и пограничные случаи

Ниже самые показательные ошибки, с которыми мы столкнулись. Полный список правил, исключений и проверок собран в token_rules.md, его можно использовать как инструкцию для агента и как чек-лист при работе с новыми компонентами.

Не добавлять искусственную сложность

Если у компонента один размер, не нужно добавлять группу m в оси size. Структура без глубокой вложенности легче читается. Расширить токен и добавить новые размеры можно всегда.

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

Проверять вложенные зависимости

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

Например:

  • input использует label и hint;

  • select использует label, hint, chevron;

  • segmented control состоит из tab;

  • avatar может содержать counter, status indicator и action button.

Не превращать каждое свойство в ось

Не все свойства из Pixso или Figma должны попадать в структуру компонентных токенов. Свойства вроде iconLeft и iconRight, а также замена конкретной иконки управляют только видимостью и содержимым. Архитектуру компонента они не меняют, поэтому отдельные оси для них создавать не нужно.

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

Не переносить в токены всю выгрузку целиком

JSON-экспорт содержит как полезные свойства, так и технические данные Pixso или Figma. Агент может добросовестно перенести всё, что увидит, и создать огромную структуру, которой никто не будет пользоваться.

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

Не придумывать алиасы, которых нет в системе

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

Выбирать алиас важно и по совпадению значения, и по смысловой роли. Два алиаса могут ссылаться на один цвет и использоваться в разных сценариях. Такое значение не стоит молча принимать или заменять сырым HEX. Если точного алиаса нет или подходящих вариантов найдено несколько, такое решение отправляется на ручную проверку.

Осторожно сопоставлять типографику

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

Мы проверяли параметры в таком порядке:

  1. fontWeight

  2. fontSize

  3. lineHeight

  4. letterSpacing

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

Что лежит в token_rules.md

token_rules.md — главный артефакт всего процесса. Это файл правил, который читает агент перед каждой генерацией.

Итоги

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

Часть правок на этом этапе может быть уже не про дизайн-логику, а про совместимость: где-то нужно переименовать ветку, где-то уточнить тип токена, где-то оставить сырое значение как временное решение до появления нового алиаса. Поэтому важно передавать не просто «готовый JSON», а структуру, в которой понятно, почему токен появился, к какому компоненту он относится и какое решение за ним стоит.

Первый компонент — кнопка — занял примерно один-два рабочих дня, потому что большую часть решений мы принимали с нуля. Дальше взяли инпут. После третьего компонента появилась база правил и готовые примеры, на которые мог опираться ИИ. Следующие компоненты занимали уже около 5–20 минут, в зависимости от сложности и количества состояний. Всего сделали 45 компонентов.

Больше всего ускорилась механическая работа. Агент помогал:

  • разбирать JSON-экспорт компонента;

  • собирать повторяющуюся структуру;

  • находить подходящие алиасы;

  • заполнять value, type и description;

  • проверять нейминг и лишние уровни вложенности.

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

В процессе появился общий набор правил: как разделять размерную и визуальную ветки, что считать осью, как работать с единственным размером, скрываемыми слоями и вложенными компонентами. Эти правила мы собрали в файл, чтобы следующие генерации не начинались с нуля. Вместе с JSON компонентных токенов файл можно передавать разработчикам и использовать как единый источник договорённостей между дизайном, кодом и ИИ.

В итоге процесс стал выглядеть так:

Главный вывод эксперимента: агенту нужны качественные исходные данные, понятный шаблон и зафиксированные правила. Без этой базы он легко создаёт лишние оси, путает уровни и предлагает убедительную, но неподходящую для системы структуру.

JSON помогает формально описать компонент и передать его устройство агенту. DESIGN.md объясняет, как собрать итоговую структуру: что считать осью, как выбирать алиасы, где не нужна лишняя вложенность и какие решения стоит проверить вручную.

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