Как отдать переменные Figma разработчикам без тарифа Enterprise

Переменные Figma хранят решения, которые нужнее всего коду: цвета, отступы, а за ними значения для светлой и тёмной темы. Достать их из Figma сложнее, чем кажется. Единственный официальный API, который их читает, доступен только на тарифе Enterprise.

В этой статье мы сравним три пути экспорта переменных Figma, которые есть сегодня, покажем, как выглядит хороший файл экспорта, и объясним, как плагин закрывает пробел на других тарифах. Мы делаем FISYCO, и наш плагин для Figma идёт третьим путём. Поэтому честно покажем, где упирается каждый из них.

Коротко

• REST API переменных Figma доступен только на тарифе Enterprise (Figma plans and features).
• Figma умеет экспортировать режим в DTCG JSON, но только вручную, из панели Variables.
• Плагин читает локальные переменные открытого файла через Plugin API, поэтому не зависит от REST API, доступного только на Enterprise.
• Какой бы путь вы ни выбрали, коммитьте токены DTCG с сохранёнными ссылками: Figma умеет их импортировать, а Style Dictionary v5 собирать.

Почему до переменных трудно добраться

Стили и переменные в интерфейсе Figma выглядят похоже, но доступ к ним устроен по-разному. В сравнении тарифов Figma Variables REST API стоит только в колонке Enterprise (Figma plans and features). Даже на Enterprise эндпоинтам нужно полное место (full seat) в организации и scope file_variables:read, а гостям они недоступны (Variables REST API).

Режимы (modes) тоже зависят от тарифа. По тому же сравнению на Starter режимов нет, на Professional их до 10 на коллекцию, на Organization до 20, на Enterprise без ограничений. Команда на Professional может собрать в переменных полноценную светлую и тёмную тему и всё равно остаться без скрипта, который бы её читал.

С этого пробела и начинается расхождение. Если разработчик не может прочитать источник, он переносит значения руками, и продакшен незаметно расходится с дизайном.

Три способа достать переменные из Figma

REST API

GET /v1/files/:file_key/variables/local возвращает все локальные переменные с ID, именем, типом, valuesByMode, scopes и синтаксисом для кода, а ещё коллекции с их режимами (Variables endpoints). Эндпоинт опубликованных переменных отдаёт меньше: без режимов и только то, что лежит в основном файле библиотеки.

Если у вас Enterprise, это самый сильный путь: задачу можно запускать по расписанию или по вебхуку публикации библиотеки. Но на выходе формат самой Figma. Алиас приходит как ID переменной, а не как читаемая ссылка, так что преобразование в код всё равно пишете вы.

Встроенный экспорт

Справочный центр Figma описывает экспорт из панели Variables: щёлкните правой кнопкой по режиму и выберите Export mode или щёлкните правой кнопкой по коллекции и выберите Export modes (Modes for variables). На выходе получается JSON в формате Design Tokens Community Group (DTCG).

С форматом всё в порядке. С запуском хуже: документированного API у экспорта нет, поэтому каждый раз человек прокликивает режимы и коммитит файлы. Если закладываете этот путь в процесс, сначала проверьте, что в вашей панели Variables есть пункт Export mode.

Плагин в открытом файле

Плагин работает внутри открытого файла. Plugin API читает локальные переменные этого файла через figma.variables.getLocalVariablesAsync(), включая valuesByMode и алиасы на другие переменные (figma.variables). Запрос не идёт через REST API, поэтому ограничение Enterprise здесь не действует.

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

Как выглядит хороший файл экспорта

Формат важнее пути. Format Module 2025.10 от Design Tokens Community Group стал первой стабильной версией формата. Это отчёт группы сообщества W3C, а не стандарт W3C, и в статье мы опираемся именно на эту версию. Вот файл светлого режима для небольшой условной темы в том виде, в каком его пишет экспортёр FISYCO (с сокращениями):

{
  "color": {
    "blue": {
      "500": {
        "$type": "color",
        "$value": {
          "colorSpace": "srgb",
          "components": [0.1451, 0.3882, 0.9216],
          "alpha": 1,
          "hex": "#2563eb"
        },
        "$extensions": { "com.fisyco": { "id": "VariableID:1:10" } }
      }
    }
  },
  "bg": {
    "accent": {
      "$type": "color",
      "$value": "{color.blue.500}",
      "$extensions": { "com.fisyco": { "id": "VariableID:2:20" } }
    }
  }
}

Четыре детали делают такой файл полезным дальше по цепочке:

1. Ссылки остаются ссылками. bg.accent указывает на {color.blue.500}, а не повторяет #2563eb. Поменяйте базовый цвет, и за ним последуют все токены, которые на него ссылаются.
2. Один файл на режим. В Format Module нет понятия режимов. Темы вроде светлой и тёмной описывает отдельный Resolver Module, но тот же Style Dictionary 5.5.5 его пока не читает, поэтому у каждого режима свой файл: design-tokens.light.tokens.json и design-tokens.dark.tokens.json. В тёмном файле из этого примера bg.accent указывает на color.blue.300.
3. Каждый файл полный. Токен из коллекции с одним режимом попадает в файл каждого режима. Иначе ссылка в тёмном файле указывала бы в пустоту. У импорта в Figma то же правило: он создаёт переменные только для токенов, которые есть во всех импортируемых файлах (Modes for variables).
4. Вместе с токеном едет стабильный ID. В $extensions лежит ID переменной Figma. Если кто-то переименует bg/accent, ID останется прежним, и инструменты покажут переименование, а не удаление плюс добавление.

Формат просит инструменты сохранять расширения, которые они не понимают, так что ID никому не мешает. На стороне кода Style Dictionary v5 собирает такие файлы в CSS-переменные и JavaScript с декларациями TypeScript, хотя поддержка 2025.10 у него пока помечена как незавершённая (Style Dictionary and DTCG).

Как выбрать путь

• Enterprise и есть кому поддерживать скрипт: берите REST API и запускайте его по публикации библиотеки.
• Несколько обновлений в год: хватит встроенного экспорта. Коммитьте файлы через pull request, а не напрямую в основную ветку.
• Регулярные обновления на Professional или Organization: берите плагин и убедитесь, что он пишет DTCG с сохранёнными ссылками.

Как это делает плагин FISYCO

Плагин FISYCO опубликован в Figma Community. Первый запуск занимает несколько минут:

1. Подключите репозиторий к проекту в FISYCO. В него будут приходить pull request'ы с токенами.
2. Создайте библиотеку токенов и вставьте ссылку на файл Figma. На шаге с переменными FISYCO ждёт плагин.
3. В Figma откройте тот же файл, запустите плагин и нажмите Connect. В браузере откроется страница FISYCO: введите код, который показывает плагин, и подтвердите доступ. Сам плагин ваш пароль не видит.
4. Нажмите Send variables («Отправить переменные»). Плагин читает локальные переменные и их значения во всех режимах и отправляет их в FISYCO. Вернитесь в браузер и выберите группы и форматы: DTCG, CSS-переменные, TypeScript, JSON.

Дальше после каждой отправки в истории библиотеки видно, что изменилось. Pull request открывается кнопкой Create PR, а можно включить автоматические pull request'ы после каждой синхронизации. В панели свойств файла появляется ещё и кнопка Refresh tokens, так что следующее обновление запускается одной кнопкой. Стилям плагин не нужен: FISYCO читает их через REST API.

Мы выбрали этот путь, потому что REST API закрыт для всех команд ниже Enterprise. Цена та, о которой шла речь выше: каждое обновление запускает человек. А проверяют это обновление в pull request, как в нашем руководстве по переносу токенов из Figma в код.

Отправлять переменные в код без Enterprise — это и есть работа плагина.