Figma Variables для AI кодогенерации — зачем они нужны и что делать без них

Figma Variables появились в 2023 году как давно ожидаемый ответ платформы на токены дизайна. Функциональность мощная: именованные коллекции примитивных значений — цветов, чисел, строк, булевых — которые можно привязывать к любому свойству любого компонента. Измените переменную — каждый экземпляр обновится. Добавьте коллекцию тёмного режима — каждая привязка переменной автоматически меняется.

Для AI кодогенерации Variables — это не просто полезный инструмент. Они являются механизмом, превращающим Figma-файл из пиксель-перфектного макета в спецификацию, которую ваш агент может реализовать правильно. Когда цвет имеет имя — color/brand/primary, а не #7F5CFE — агент может отобразить его на токен кода, правильно реализовать тёмный режим и произвести вывод, участвующий в вашей реальной дизайн-системе.

Вот проблема: большинство Figma-файлов в активном использовании сегодня не имеют настроенных Variables. figmascope работает в обоих случаях. Этот пост объясняет как.

Что такое Variables на самом деле

Figma Variable — именованный скаляр, привязанный к коллекции. Коллекции организуют переменные по режиму — «Light» и «Dark» — каноничный пример. Каждая переменная в коллекции может иметь разные значения на режим: color/surface/background — #FFFFFF в Light и #0D0D0D в Dark. Привязка распространяется: каждая заливка, ссылающаяся на color/surface/background, обновляется при переключении режима.

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

Figma предоставляет Variables через REST API как коллекцию localVariables. Каждая переменная имеет ID, имя, тип и значения на режим. Свойства компонентов, ссылающиеся на переменные, несут поле boundVariables с ID переменной. Это структурированные данные, которые чисто проходят через пайплайн извлечения.

Счастливый путь: Variables присутствуют

Когда Figma-файл имеет Variables, figmascope читает их из API и строит tokens.json по структуре, совместимой с W3C Design Tokens Community Group. Каждый токен имеет $value и $type. Цветовые токены получают hex-значения с опциональным альфа-каналом. Токены отступов получают числовые значения с подсказкой единицы px. Имя токена следует пути коллекции и имени переменной:

{
  "color": {
    "brand": {
      "primary": { "$value": "#7F5CFE", "$type": "color" }
    },
    "surface": {
      "background": { "$value": "#FFFFFF", "$type": "color" }
    }
  },
  "spacing": {
    "4": { "$value": 4, "$type": "number" },
    "8": { "$value": 8, "$type": "number" },
    "16": { "$value": 16, "$type": "number" }
  }
}

Когда строится постраничный IR, каждая заливка с ссылкой boundVariables получает имя токена вместо разрешённого hex. Узел несёт:

"fills": [{ "type": "SOLID", "tokenRef": "color/brand/primary" }]

Не #7F5CFE. Имя токена. Агент читает это и генерирует background-color: var(--color-brand-primary) или Color.brandPrimary или что соответствует паттерну потребления токенов целевого фреймворка. Вот какой вывод вам нужен: код, связанный с вашей дизайн-системой, а не код, который сломается при изменении дизайнером цвета.

Семантическое именование — это разница между кодом, который хорошо стареет, и кодом, который дрейфует. Hex-значение в исходнике — ответственность; ссылка на токен — контракт. Variables — то, что делает Figma-файлы способными выражать контракты, а не только пиксели.

Реальность: в большинстве файлов нет Variables

Variables требуют тарифного плана Figma Professional или выше. Они требуют дизайнера, который их настроил — то есть создал коллекции, назвал переменные и вручную привязал их к каждому свойству компонента. В зрелом, хорошо поддерживаемом файле дизайн-системы это сделано. В Figma стартапа, файле клиента фрилансера или любом файле до появления функциональности Variables — как правило, нет.

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

Резервный вариант: вывод по частоте

Алгоритм вывода работает так:

Обход каждого листового узла в каждом экспортированном фрейме.
Сбор всех цветов заливок, значений отступов и border radii.
Подсчёт вхождений каждого уникального значения.
Значения, встречающиеся выше порога частоты, продвигаются в выведенные токены.
Каждый токен получает имя, производное от значения: color.7f5cfe, spacing.16, radius.8.

Итоговый tokens.json структурно похож на путь через Variables, но имена производны от значений, а не семантические:

{
  "color": {
    "7f5cfe": { "$value": "#7F5CFE", "$type": "color" },
    "f6f2ea": { "$value": "#F6F2EA", "$type": "color" }
  },
  "spacing": {
    "16": { "$value": 16, "$type": "number" },
    "8": { "$value": 8, "$type": "number" }
  }
}

В IR узлы, использующие эти значения, получают ссылки на токены: "tokenRef": "color.7f5cfe". Не хардкодные литералы. Ссылки — просто на выведенные токены, а не именованные.

Агент всё равно генерирует токен-ссылочный код. var(--color-7f5cfe) не так читаем, как var(--color-brand-primary), но это всё равно токен — его можно найти и заменить, переименовать, аудировать использование. Это именованный дескриптор значения, а не магическое число.

Поле tokensSource

Каждый бандл figmascope включает _meta.json, документирующий содержимое бандла и способ его производства. Поле tokensSource имеет три возможных значения:

figma-variables — Variables присутствовали и были использованы. Имена токенов семантические.
inferred-from-frequency — Variables не найдены. Токены выведены по частоте значений. Имена производны от значений.
none — Токены не удалось извлечь или вывести. IR использует разрешённые значения напрямую.

Это важно, потому что сообщает потребляющему агенту (и разработчику, читающему бандл), насколько доверять именам токенов. Бандл figma-variables — источник истины для вашей дизайн-системы. Бандл inferred-from-frequency — полезный структурный скаффолд, требующий проверки именования дизайнером до канонизации. Бандл none — отправная точка с хардкодными значениями, требующими токенизации позже.

Честные метаданные недооценены. Инструменты, которые молча выводят без пометки этого как вывод, создают ложную уверенность. figmascope явно показывает цепочку вывода, чтобы вы знали, с чем работаете.

Почему вывод по частоте лучше, чем ничего

Альтернатива выводу по частоте — вывод разрешённых литеральных значений везде — #7F5CFE в каждом узле заливки, использующем этот цвет. Это производит код, который сложнее рефакторить, сложнее аудировать и сложнее соединять с дизайн-системой, когда она в итоге появится.

Вывод по частоте как минимум извлекает набор значений, которые дизайн действительно использует. Если #7F5CFE встречается 47 раз по всему дизайну — это сигнал: это основной цвет, не акцентный. Имя токена этого не знает — оно просто color.7f5cfe — но данные частоты рассказывают историю. Агент, получивший выведенные токены, может делать разумные предположения о том, какие значения основные, а какие разовые.

Более практично: вывод по частоте даёт вам tokens.json, который сравнивается между версиями. Если экспортировать один и тот же файл дважды после изменения дизайнером повторяющегося цвета, дифф показывает изменение значения токена. Без вывода вы бы отслеживали каждое отдельное изменение литерала, разбросанного по нескольким IR-файлам.

Что дизайнеры всё равно должны делать

Вывод по частоте — это слой совместимости, а не замена Variables. Правильный путь — дизайнеры должны принять Variables для всех значений, участвующих в дизайн-системе: фирменные цвета, нейтральная шкала, шкала отступов, border radii, elevation, типографика. Как только они появятся, бандл figmascope перейдёт от токенов скаффолд-качества к токенам производственного качества.

Variables также открывают темизацию в бандле: несколько значений режима на токен. Файл с режимами Light/Dark производит tokens.json со значениями на режим, которые напрямую питают CSS custom properties с переопределениями медиа-запросов или платформо-специфичные объекты тем. Это невозможно вывести из единственного снимка дизайна — это требует явного намерения дизайнера, выраженного через Variables.

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

Полный пайплайн токенов

Чтобы конкретизировать, вот полный порядок разрешения, который figmascope использует для каждой заливки в IR:

Есть ли у узла ссылка boundVariables.fills? Если да, разрешите до имени переменной и значения нулевого режима. Источник токенов: figma-variables.
Присутствует ли разрешённое значение в выведенных токенах частоты (выше порога)? Если да, отобразите на имя выведенного токена. Источник токенов: inferred-from-frequency.
Иначе: используйте разрешённый hex напрямую. Без ссылки на токен. Источник токенов: none.

Шаги пробуются по порядку. Побеждает источник наивысшего качества. Поле tokensSource в _meta.json отражает доминирующий путь для бандла в целом.

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

Экспортируйте ваш бандл из приложения figmascope, чтобы увидеть, какой tokensSource производит ваш файл. Затем используйте бандл с Claude Code или Cursor для точной, токен-ссылочной кодогенерации.