Экспорт переменных и стилей

Export variables & styles создаёт и обновляет переменные и стили Figma по файлам токенов. Простые токены становятся переменными: Color, Number, String, Boolean, Timing и Easing. Составные токены становятся стилями: заливки, эффектов, текста и сеток. Экспорт можно повторять сколько угодно: плагин помнит, какая переменная какому токену принадлежит, и обновляет её, а не создаёт заново.

#Перед первым экспортом: коллекции и режимы

Переменные Figma живут в коллекциях, у коллекции может быть несколько режимов, например Light и Dark. Какие файлы токенов попадают в какую коллекцию и режим, задаёт config.json в папке токенов. Редактировать его удобнее в окне Collection Settings, кнопка внизу дерева файлов.

Collection Settings: группы, список коллекций с числом режимов и файлов, кнопки создания группы и коллекции.

В окне можно:

• создать коллекцию кнопкой Collection и режим внутри неё, назначить режиму файлы;
• перетаскивать коллекции и режимы, меняя их порядок в конфигурации; существующие объекты в Figma от этого не перемещаются;
• отключить коллекцию, режим или файл, не удаляя его из конфигурации;
• добавить ссылку на другую коллекцию или библиотеку для разрешения алиасов;
• объединить коллекции в группы: группа соответствует отдельному файлу Figma, в который экспортируется своя часть токенов, например Core и Components.

Тот же config.json в JSON:

{
  "$schema": "sxl-studio/config",
  "$version": "1.0",
  "settings": { "remBase": 16, "autoExportOnPull": false },
  "collections": [
    {
      "name": "Primitives",
      "hiddenFromPublishing": true,
      "modes": [
        { "name": "Default", "files": { "colors.json": "enabled", "spacing.json": "enabled" } }
      ]
    },
    {
      "name": "Semantic",
      "ref": [{ "type": "local", "collection": "Primitives" }],
      "modes": [
        { "name": "Light", "files": { "semantic-light.json": "enabled" } },
        { "name": "Dark", "files": { "semantic-dark.json": "enabled" } }
      ]
    }
  ]
}

Файл со статусом source участвует только в разрешении ссылок: его токены могут быть целями алиасов, но сами переменными не становятся. Так оформляют базовые наборы, на которые ссылаются семантические файлы.

Файлы разных режимов содержат одни и те же пути токенов с разными значениями: text.primary в semantic-light.json и в semantic-dark.json. Если в каком-то режиме токена нет, переменная всё равно создаётся, а значение для этого режима подставит Figma; в отчёте экспорта такие пропуски перечислены.

#Как экспортировать

1. Внизу дерева нажмите Export variables & styles. Откроется окно Export to Figma с четырьмя сворачиваемыми блоками: Collections, What to export, Export settings и Delete variables & styles. Список и кнопка Export появляются после загрузки сохранённых настроек, обычно мгновенно.
2. В блоке Collections отметьте коллекции. Галочка в заголовке выбирает все, поле Filter by name… ищет по имени, переключатель Show selected only оставляет в списке только выбранные. Над списком закреплена строка Selected: N of M с именами выбранных коллекций.
3. В блоке What to export оставьте включёнными нужные типы переменных и стилей.
4. При необходимости измените Export settings, для обычного экспорта менять ничего не нужно.
5. Нажмите Export. В строке внизу окна указано, сколько коллекций и типов выбрано.

Во время экспорта уведомление показывает ход: полоса прогресса, счётчик «N / всего» и текущую стадию. Кнопка Cancel export останавливает экспорт: плагин дописывает текущую переменную, сохраняет служебный файл для уже записанного, пропускает удаления, сортировку и стили и показывает Export cancelled с числом созданных и обновлённых переменных. Повторный экспорт после отмены продолжает с того же места.

Окно Export to Figma: секция Collections с поиском и группами коллекций.

Типы переменных и стилей, начало настроек экспорта.

После экспорта откройте панель Variables в Figma: коллекции, режимы и переменные появятся там, стили в панели стилей. Повторный экспорт обновляет только то, что изменилось в JSON.

#Типы

Все переключатели включены по умолчанию. Выключите тип, чтобы пропустить его целиком, например экспортировать только переменные без стилей.

#Export Settings

Готовые сочетания:

• Ежедневный экспорт: всё по умолчанию. Быстро, обновляются только изменённые значения.
• Навести порядок: Sort включён, остальное по умолчанию.
• Синхронизировать удаления: Delete orphaned variables & styles включён на один запуск.
• Полное обновление: Force update all включён на один запуск, затем выключите.

Sort не удаляет и не пересоздаёт объекты. Figma позволяет плагинам перемещать существующие стили и их папки, но не даёт способа переставить существующие коллекции, моды или переменные. Поэтому изменение их порядка в Collection Settings или JSON не переставляет их в Figma. Итоговый порядок отображения определяет Figma. Порядок существующих коллекций, модов и переменных задавайте вручную в Figma.

#Destructive actions

Блок внизу окна удаляет коллекции переменных и группы стилей из файла Figma целиком. В обоих списках есть поиск и выбор нескольких элементов; кнопка называется Delete all … или Delete N selected …. Удаление необратимо: переменные, привязанные к слоям, теряют привязку. Перед массовым удалением сохраните версию файла Figma и закоммитьте токены.

#Читаем результат

Панель Variables в Figma после экспорта: коллекция с режимами Light и Dark и группами color, radius и space, как в файлах токенов.

После экспорта плагин показывает уведомление с заголовком:

Кнопка Copy all копирует весь отчёт, Retry повторяет экспорт. Ошибка одного токена не останавливает остальные: неверное значение, неразрешённая ссылка или несовместимый тип пропускают только этот токен, а в отчёте указан его путь.

Замечания и ошибки перечислены пунктами: значок серьёзности (красный крест — ошибка, жёлтый треугольник — замечание, серый «i» — справочная строка), сначала ошибки, затем замечания. У пункта могут стоять метка коллекции или пути и число затронутых переменных или стилей (×N), а под ним — рекомендация «→ что сделать»; одинаковая рекомендация для нескольких пунктов показана один раз над списком. Список длиннее восьми пунктов сворачивается кнопкой Show N more.

#Повторный экспорт без дубликатов

Если стиль (текстовый, заливка, градиент, тень, blur или сетка) ссылается на переменную, которой в Figma ещё нет (например, коллекция с ней ещё не экспортирована), стиль создаётся с литеральным значением, а в уведомлении появляется замечание с перечнем полей и переменных. Экспортируйте коллекцию с этими переменными и запустите обычный экспорт ещё раз: привязки восстанавливаются автоматически, ID стиля и его потребители сохраняются, Force update all не нужен.

Слой заливки, цвет которого привязан к переменной, может иметь свою opacity: экспорт проверяет записанное значение и при необходимости повторяет запись, поэтому прозрачность верна уже после первого экспорта. Blend mode у такого слоя Figma не хранит — экспорт оставляет NORMAL и добавляет замечание с именем слоя; чтобы сохранить blend mode, задайте цвет слоя литералом.

Плагин хранит связь между токенами и переменными этого файла Figma в служебном файле diff-id.<ключ файла>.json рядом с токенами. Благодаря ему:

• изменение значения обновляет ту же переменную;
• переименование токена в JSON переименовывает переменную, если замену можно доказать однозначно;
• удалённый из JSON токен не удаляет переменную, пока не включён Delete orphaned variables & styles;
• ссылки между переменными сохраняются.

Файл синхронизируется через Git вместе с токенами: не редактируйте его вручную и не удаляйте, а если используете Prettier, добавьте diff-id.*.json в .prettierignore. Если связь потерялась, например при копировании файла Figma, обычный экспорт сам находит единственную подходящую переменную с тем же именем и типом и подключает её. Неоднозначные совпадения плагин не выбирает наугад и сообщает о них.

Reset Diff-ID внизу дерева разрывает связь для всего файла или для одной коллекции в Collection Settings: следующий экспорт создаст переменные заново. Нужен редко, например когда файл Figma начинают с чистого листа.

#Ссылки между коллекциями и библиотеками

Токен может ссылаться на токен из другой коллекции: {color.blue.500} в семантической коллекции указывает на примитив. Чтобы экспорт нашёл цель, у коллекции должна быть ссылка ref:

{ "name": "Semantic", "ref": [{ "type": "local", "collection": "Primitives" }] }

Для переменных из подключённой библиотеки Figma указывается имя библиотеки и коллекции:

{ "ref": [{ "type": "library", "library": "Design System Core", "collection": "Primitives" }] }

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

Объявляйте ref для каждой коллекции, на токены которой есть ссылки, даже если она экспортируется в этом же прогоне. Без объявления цель, которой ещё нет в текущем экспорте, может найтись в опубликованной библиотеке по памяти diff-id других файлов: переменная сошлётся на библиотеку, а к локальной переменной её перепривяжет только следующий экспорт.

Совместимость ссылки проверяется по виду переменной Figma: number может ссылаться на borderWidth, потому что обе становятся переменными Number, а ссылка с number на color будет пропущена с предупреждением.

#Автоматический экспорт после Pull

Если в config.json задано "autoExportOnPull": true, плагин экспортирует токены сразу после каждого Pull из Git с настройками по умолчанию: все типы включены, настройки экспорта выключены, в том числе Apply codeSyntax & scopes.

#Если что-то не работает

#Связанные страницы

• Импорт из Figma
• Коллекции
• Режимы коллекций
• Scopes и Code Syntax
• Pull, Push и ветки