Миграция из Tokens Studio

Overview

В SXL Studio есть управляемый flow Migration TS для команд, которые переходят с Tokens Studio. Он конвертирует token JSON в нативный DTCG-формат SXL Studio, может преобразовать $themes.json в SXL config.json и оставляет результат на review через Git Sync до того, как вы сделаете Push.

Шаг	Что происходит
Preview	Сканирует workspace; показывает изменённые файлы, сконвертированные токены, сводку типов, коллекции `$themes` и warnings
Apply Migration	Переписывает token JSON на месте в SXL DTCG; workspace становится dirty (Push не делается)
Push	Вы проверяете Git-diff и коммитите, когда JSON корректен

Миграция устроена явно: сначала preview, потом apply, затем проверка diff перед Push.

Где находится

Нажмите шестерёнку Sync settings в футере, на вкладке Git Sync нажмите Migration TS в левом нижнем углу. Кнопка доступна в Figma Design Mode, когда активен Git-источник с выбранным подключением. В режимах Plugin Local и Local Workspace миграция недоступна: переключитесь на Git.

В диалоге три основных переключателя:

Переключатель	Что делает
Convert to W3C / DTCG format	Переписывает `value/type/description/extensions` → `$value/$type/$description/$extensions`
Migrate Tokens Studio types to SXL types	Маппит типы TS в типы SXL; ниже раскрывается список типов (по умолчанию выбраны все)
Convert $themes.json to SXL config	Преобразует состояние themes/token sets в коллекции, modes и статусы файлов SXL `config.json`

Сначала нажмите Preview. Preview сканирует workspace и показывает изменяемые файлы, количество сконвертированных токенов, сводку типов, коллекции/моды из $themes, warnings и невалидные JSON-файлы, которые были пропущены. Нажимайте Apply Migration только после проверки preview.

Миграция никогда не делает Push автоматически. После apply workspace становится dirty, а момент Push выбираете вы.

Безопасный процесс миграции

Создайте отдельную ветку или убедитесь, что текущая ветка предназначена для миграции.
Выполните Pull, чтобы в плагине были актуальные token-файлы.
Откройте Git Sync → Migration TS.
Оставьте все маппинги включёнными, если нет точной причины исключить конкретный тип.
Нажмите Preview и проверьте warnings.
Нажмите Apply Migration.
Откройте Push, проверьте diff и закоммитьте изменения, когда JSON выглядит корректно.
Перед первым Export variables & styles в существующую библиотеку Figma прочитайте предупреждение про уже существующие переменные. Обычный экспорт сам подключает переменную или стиль с тем же именем и типом, если совпадение единственное; дубли и неоднозначные совпадения нужно устранить вручную до экспорта.

Что конвертируется

Миграция читает managed token JSON files из активного Git Sync workspace. Она конвертирует Tokens Studio token-файлы из legacy value/type/description/extensions или частично DTCG-похожего JSON в SXL DTCG ($value/$type/$description/$extensions).

Уже валидные SXL-токены проходят без изменений. Повторный запуск той же миграции стабилен: неизменённые файлы остаются неизменёнными.

Составные значения нормализуются вместе с типом:

слои boxShadow с ключами Tokens Studio вроде $x, $y, $blur, $spread, $color, $type становятся SXL-слоями shadow с offsetX, offsetY, blur, spread, color, type;
значения typography с $fontFamily, $fontWeight, $fontSize, $lineHeight и похожими prefixed-полями становятся SXL typography-полями без $;
значения Tokens Studio composition становятся SXL template. Вложенные style props boxShadow сохраняют форму template/composition (x, y, blur, spread, color, DROP_SHADOW / INNER_SHADOW), чтобы apply template работал корректно.

SXL Studio не считает каждый файл в репозитории token-файлом. Он пропускает SXL config.json, Tokens Studio $metadata.json, Markdown, README и другие unmanaged-файлы.

Маппинг типов токенов

Каждый поддерживаемый тип Tokens Studio маппится в канонический тип SXL. Множественные и legacy-алиасы нормализуются.

Tokens Studio	SXL Studio
`color`	`color`
`typography`	`typography`
`fontFamilies` / `fontFamily`	`fontFamily`
`fontWeights` / `fontWeight`	`fontWeight`
`fontStyles` / `fontStyle`	`fontStyle`
`fontSizes` / `fontSize`	`fontSize`
`lineHeights` / `lineHeight`	`lineHeight`
`letterSpacing`	`letterSpacing`
`paragraphSpacing`	`paragraphSpacing`
`paragraphIndent`	`paragraphIndent`
`textCase`	`textCase`
`textDecoration`	`textDecoration`
`dimension`	`dimension`
`number`	`number`
`border`	`border`
`boxShadow`	`shadow`
`borderRadius`	`borderRadius`
`borderWidth`	`borderWidth`
`spacing`	`spacing`
`sizing`	`sizing`
`opacity`	`opacity`
`boolean`	`boolean`
`text` / `string`	`text`
`asset` (строка-URL)	`img`
`asset` (объект/blob)	чистый custom `$type: "asset"`
`composition`	`template`
`other`	чистый custom `$type: "other"`
`fontFallbacks`	чистый custom `$type: "fontFallbacks"`
любой неизвестный `$type`	сохраняется как чистый custom `$type`

Если снять checkbox типа в диалоге Migration TS, этот тип не будет мигрирован. Используйте это только для контролируемой частичной миграции.

Composition → Template

В Tokens Studio токен composition — это набор style-свойств. В SXL Studio это соответствует Template, а не file-level генератору Composition.

Миграция конвертирует Tokens Studio токены $type: "composition" в $type: "template" — как при типе на самом токене, так и при наследовании от родительской группы.

Файл, который уже является SXL composition-генератором (на корне есть блок structure и/или styles), распознаётся по форме и не трогается.

Extensions

Метаданные Tokens Studio маппятся в namespace figma.* SXL. Поддерживаются и плоские, и вложенные Figma extension-формы.

$extensions["studio.tokens"].modify → $extensions["figma.modify"]
$extensions["com.figma.scopes"] → $extensions["figma.scopes"]
$extensions["com.figma"].scopes → $extensions["figma.scopes"]
$extensions["com.figma.codeSyntax"] → $extensions["figma.codeSyntax"]
$extensions["com.figma"].codeSyntax → $extensions["figma.codeSyntax"]
$extensions["com.figma.hiddenFromPublishing"] → $extensions["figma.hide"]
$extensions["com.figma"].hiddenFromPublishing → $extensions["figma.hide"]
studio.tokens.id → $id (если $id отсутствует)

Цветовые modifiers из Tokens Studio конвертируются в SXL figma.modify, когда они соответствуют поддерживаемой форме. Неподдерживаемые формы сохраняются как инертные метаданные с warning, а не записываются как невалидный SXL modifier.

Если SXL-native значение уже задано, оно выигрывает, и фиксируется warning.

Custom-токены

Типы без SXL/Figma export target (other, fontFallbacks, неизвестные типы, non-URL asset) становятся Custom токенами.

авторский $type: исходный тип по возможности сохраняется как чистый $type
совместимость: старые файлы с $type: "custom" и sxl.studio.declaredType продолжают читаться
значение: сохраняется без преобразования
export: безопасные формы $value распознаются и экспортируются через существующий pipeline Variables/Styles; нераспознанные значения остаются internal

Custom-токены можно смотреть и редактировать в редакторе токенов: Other → Custom. Сохранение из визуального редактора пишет чистую форму $type.

Config и `$themes.json`

Когда включён Convert $themes.json to SXL config, данные themes из Tokens Studio становятся коллекциями и modes SXL config. Каждый token set в теме получает статус файла:

enabled — экспортируется (создаёт переменные/стили) и участвует в резолве алиасов
disabled — игнорируется
source — resolve-only: участвует в резолве алиасов/типов (для примитивных наборов вроде base-unit или palette, на которые ссылаются другие наборы), но сам не создаёт переменные/стили

Сгенерированный config мержится в существующий SXL config, а не пушится сразу. Перед коммитом проверьте Push diff.

Существующие Figma variables и styles

Миграция конвертирует JSON. Она не подхватывает автоматически существующие Figma Variables/Styles по ссылкам из Tokens Studio.

Если вы мигрируете проект, где Variables или Styles уже существуют в Figma, проверьте warning после Apply Migration и внимательно спланируйте первый export:

если имена уже совпадают, обычный экспорт подключит существующие переменные и стили сам;
если в библиотеке старые имена, переименуйте токены или переменные так, чтобы они совпадали, либо уберите лишние дубли;
не экспортируйте сразу в рабочую библиотеку без проверки diff и предупреждений.

Так вы снижаете риск случайного создания дублей Variables или Styles при первом SXL export.

Что Migration TS не делает

Не делает Push в Git.
Не мутирует Figma Variables или Styles.
Не переписывает unmanaged-файлы вроде README или Markdown.
Не делает auto-adopt существующих Figma ID из ссылок Tokens Studio.

Troubleshooting

Кнопки не видно

Проверьте, что плагин открыт в Design Mode, а в футере активен Git-источник с подключением. При активном Local Workspace или Plugin Local кнопка неактивна.

Preview не показывает изменений

Сначала выполните Pull, затем проверьте, что Tokens Path указывает на папку с token JSON files. Если файлы уже мигрированы, отсутствие изменений может быть корректным.

Невалидный JSON пропущен

Исправьте JSON-файл и запустите Preview ещё раз. Миграция пропускает невалидный JSON вместо частичной перезаписи файла.

После export появились дубли Variables

Сама миграция не создаёт переменные Figma. Если дубли появились после экспорта, значит для токена нашлось несколько совпадений: удалите лишние переменные в Figma и повторите экспорт. Проверить связь токенов с переменными можно командой diffid на вкладке Diagnostics.

Связанные разделы

Git-интеграция — Pull, Push и расположение Migration TS
Export Variables и Styles — первый export после миграции
Формат Token JSON — DTCG-структура SXL токенов
Все типы токенов — канонические типы SXL

#Overview

#Где находится

#Безопасный процесс миграции

#Что конвертируется

#Маппинг типов токенов

#Composition → Template

#Extensions

#Custom-токены

#Config и $themes.json

#Существующие Figma variables и styles

#Что Migration TS не делает

#Troubleshooting

#Связанные разделы