Миграция из 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.

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

Откройте Git Sync, активируйте подключение и нажмите Migration TS рядом с New Sync. Кнопка доступна в Figma Design mode, когда выбрано активное 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-библиотеку проверьте предупреждение про существующие Figma-ссылки. Если в файле уже есть подходящие Variables/Styles, используйте Bind existing by name или ваш обычный rebind/adoption-процесс.

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

Миграция читает 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:

включите Bind existing by name, если имена уже совпадают;
сделайте inspect/rebind вручную, если в библиотеке legacy naming;
не экспортируйте сразу в production library без проверки diff и warnings.

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

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

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

Troubleshooting

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

Проверьте, что вы в Figma Design mode, выбрано активное Git-подключение, а build плагина актуален.

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

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

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

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

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

Сама миграция не создаёт Figma Variables. Если дубли появились после export, проверьте diff-id/adoption state и используйте Bind existing by name или rebind существующих Variables/Styles перед повторным export.

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

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

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