Transformer

Transformer (@sxl-studio/token-transformer, версия 3.4.1): утилита командной строки, которая превращает JSON-файлы токенов из плагина в код. Она работает на компьютере разработчика и в CI, настраивается одним YAML-файлом и пересобирает только то, что изменилось. Нужен Node.js 20 или новее.

Для разового экспорта без терминала подойдёт сам плагин, см. Токены в код. Transformer читает те же файлы и тот же config.json.

#Быстрый старт за 5 минут

Понадобятся Node.js 20 или новее и папка с JSON-файлами токенов и config.json из плагина. Откуда берётся эта папка, описано в разделе Источники токенов и синхронизация.

1. Установите пакет в проект: npm install --save-dev @sxl-studio/token-transformer. pnpm add -D и yarn add -D работают так же.
2. Создайте стартовый конфиг: npx sxl-transform init. В текущей папке появится файл sxl-transform.config.yaml с примерами для всех платформ.
3. Откройте файл. Укажите в source.tokenDir папку с токенами и замените имена коллекций и режимов в tokenSets на те, что есть в вашем config.json. Удалите ненужные outputs.
4. Проверьте конфиг: npx sxl-transform validate-config.
5. Соберите: npx sxl-transform sync.

npm install --save-dev @sxl-studio/token-transformer
npx sxl-transform init
npx sxl-transform validate-config
npx sxl-transform sync

Сгенерированные файлы появятся в outputDir каждого output. Рядом с конфигом утилита записывает sxl-transform.config.state.json: с ним следующий sync пересобирает только те outputs, чьи токены изменились. Файл состояния можно не хранить в Git: без него следующий запуск сделает полную пересборку.

#Команды

#Параметры sync

#Стратегии sync: smart, force и preserve

У команды sync есть два режима пересборки: smart и force. Preserve — отдельная политика объединения с уже созданными файлами.

# Обычная синхронизация: JSON остаётся источником истины
npx sxl-transform sync --config ./sxl-transform.config.yaml --mode smart --issue-action debug-stop

# Полная пересборка всех настроенных outputs
npx sxl-transform sync --config ./sxl-transform.config.yaml --mode force --issue-action debug-stop

# Миграция: сохранить старые объявления, обновить совпавшие и добавить новые
npx sxl-transform sync --config ./sxl-transform.config.yaml --mode smart --preserve-existing --issue-action debug-stop

Один нейтральный набор scripts для проекта:

{
  "scripts": {
    "tokens:sync": "sxl-transform sync --config ./sxl-transform.config.yaml --mode smart --issue-action debug-stop",
    "tokens:force": "sxl-transform sync --config ./sxl-transform.config.yaml --mode force --issue-action debug-stop",
    "tokens:preserve": "sxl-transform sync --config ./sxl-transform.config.yaml --mode smart --preserve-existing --issue-action debug-stop"
  }
}

Например, раньше в выходных файлах существовали --color-action и --color-legacy. После рефакторинга значение color.action изменилось, color.legacy удалён из JSON, а color.accent добавлен. Обычный smart и force обновят action, добавят accent и удалят legacy. Preserve обновит action, добавит accent и оставит legacy. Если токен переименован, preserve сохранит прежнее имя и добавит новое; обычный smart при следующей пересборке удалит прежнее.

Preserve читает старые объявления из output-файлов, поэтому перед ним нельзя очищать выходную папку. Для точечного запуска добавьте те же --only-output и --only-file, которые перечислены выше. Изменения за пределами выбранной области останутся ожидающими следующего полного sync.

# только два outputs
npx sxl-transform sync --only-output css-app --only-output swift-app

# только файл тёмной темы из output css-app
npx sxl-transform sync --only-file "css-app:modes/dark.css"

# CI: не ждать ввода, пропускать сломанные токены
npx sxl-transform sync --issue-action skip

#Как preserve сопоставляет объявления

Для CSS, SCSS, Swift, UIKit, Kotlin, Android XML и manifest совпадение определяется по публичному имени и области объявления:

Старые объявления, заменённые актуальными в другом файле той же области, не дублируются. Разные Sass-модули и native namespaces остаются независимыми: изменение NewTokens.size не изменяет OldTokens.size. Сохраняются устаревшие выходные файлы и их подключения через indexes.includeGenerated. Native namespace и общие вспомогательные типы получают одного владельца в пределах области компиляции.

Флаг задаётся только в команде, в YAML его нет. Он работает с --mode smart, --force, --watch, --only-output и --only-file. Запуск без флага возвращает обычную генерацию из JSON для выбранных outputs; сохранённые значения будут удалены при пересборке. options.removeStaleOutputs: false отдельно управляет сохранением целых устаревших файлов.

Если state отсутствует, прежние файлы восстанавливаются в учёте по настроенным путям генерации и split-шаблонам. Произвольные файлы вне этих шаблонов не подхватываются. Уже потерянные значения без прежнего output восстановить нельзя. Сохранённые outputs не заменяют JSON-источники при разрешении алиасов.

Повреждённый или неподдерживаемый файл останавливает запуск до записи outputs. Обработчики рассчитаны на генерируемые Transformer структуры; произвольный код custom formatter может потребовать адаптации. CSS с анонимными слоями @layer не объединяется, потому что у слоя нет устойчивого имени. Предупреждения об исходных токенах по-прежнему обрабатываются согласно --issue-action. Пустой glob после подтверждённого удаления прежних источников при сохранённых outputs становится информационным сообщением.

#Smart-режим и файл состояния

sync сравнивает содержимое файлов токенов с файлом состояния и пересобирает только те outputs, которые зависят от изменившихся файлов. Сгенерированные файлы тоже проверяются: файл, удалённый или отредактированный вручную, записывается заново. Файлы, чьи токены исчезли, удаляются, если только options.removeStaleOutputs не равен false.

В 3.4.1 smart записывает только действительно отличающиеся файлы, в том числе после изменения конфига или переключения preserve. --mode force заново генерирует и записывает все выбранные outputs. --mode smart --preserve-existing сохраняет отсутствующие в JSON объявления; при переименовании остаются прежнее и новое имена. Предварительная очистка папок не требуется и удалит данные, которые preserve должен сохранить.

Чего ожидать:

• Первый запуск и запуск без файла состояния пересобирают всё. Обновления, меняющие генерацию, включая 3.4.1, однократно сбрасывают старое состояние; следующие прогоны без изменений снова пропускают генерацию.
• Запуск, ограниченный --only-output или --only-file, не скрывает остальные изменения: их подхватит следующий полный запуск. При --only-file устаревшие файлы вне выборки не удаляются.
• Пока идёт sync, файл <state>.lock не даёт запустить второй параллельный прогон. Блокировка старше 10 минут снимается автоматически.
• Если ваш скрипт переписывает сгенерированные файлы после sync, следующий запуск пересоберёт их: содержимое больше не совпадает с состоянием. Запускайте такие скрипты до sync или пишите в другую папку.
• --watch следит за папкой токенов, YAML-конфигом и config.json, игнорирует выходные папки и никогда не задаёт вопросов: при проблемах записывает debug-отчёт и продолжает.

#Какие токены конвертируются

CSS, SCSS, Swift, UIKit и Kotlin распознают следующие группы токенов. Допустимые формы значений и генерируемые поля зависят от платформы; ограничения перечислены ниже.

Остальные типы:

• glass распознаётся и сохраняется в манифесте. У типизированных outputs нет отдельного представления стекла; самостоятельные значения glass не поддерживаются, а слои стекла внутри эффектов сопровождаются диагностикой.

• Токены custom сохраняются как есть. Манифест экспортирует их $value дословно; остальные платформы пропускают их с предупреждением, потому что у значения нет фиксированной формы.

• template, composition и grid описывают структуры Figma, а не значения, и не конвертируются никогда. options.unsupportedTypes решает, будет это ошибкой, предупреждением или молчаливым пропуском.

Токены, скрытые в Figma ($extensions["figma.hide"]), по умолчанию экспортируются: на них часто ссылаются видимые токены. excludeHidden: true у output убирает их.

Ссылки ({color.brand}), числовые выражения и поддерживаемые цветовые модификаторы figma.modify вычисляются перед генерацией. Математика работает только для числовых типов; токен text вида "37-37" никогда не вычисляется. Исходный формат описан в разделе JSON-формат токенов; наличие поля Figma не означает, что любой output умеет его воспроизводить.

#Формы значений и ограничения платформ

• Размеры и длительности принимают объекты DTCG {value, unit}. Цвета DTCG принимают числовые компоненты в srgb, display-p3, hsl, oklch и lch либо поддерживаемый резервный hex. Другим цветовым пространствам и компонентам none нужен резервный цвет; некорректная явно заданная альфа отклоняется.
• CSS/SCSS принимают строковые градиенты, включая повторяющиеся, сокращённую запись теней и URL изображений. Полной конвертации видео, паттернов Figma и отдельных значений glass нет. Spring easing передаётся приближённо и сопровождается предупреждением.
• SwiftUI, UIKit и Kotlin экспортируют значения и типизированные спецификации. Строковые линейные градиенты сохраняют направление и двойные позиции стопов. Сложная геометрия радиальных/конических градиентов, повторяющиеся градиенты, автоматический интерлиньяж и заливки Figma video/pattern/glass остаются неподдерживаемыми формами значений.
• Фильтры и трансформации изображений, геометрия прогрессивного размытия, слои эффектов noise/texture/glass и оси вариативных шрифтов не воспроизводятся генерируемыми значениями/спецификациями. Диагностика называет поля, которые иначе были бы пропущены незаметно.
• Манифест сохраняет авторские данные разрешённых типов токенов, включая custom. Он не отрисовывает эффекты. Сохраняйте его рядом с типизированными outputs, если нужны исходные детали.

Неподдерживаемые значения сопровождаются диагностикой и не считаются успешно преобразованными. По умолчанию ошибки останавливают генерацию. Выбирайте описанную политику предупреждений/пропуска только тогда, когда потребитель может намеренно обойтись без этих значений.

#Типографика

Токену typography нужны fontFamily, fontWeight, fontSize и lineHeight. CSS и SCSS получают одно сокращённое значение в порядке свойства font: начертание, вес, размер/интерлиньяж, семейство; поля за пределами этой записи вызывают предупреждения. Swift, UIKit и Kotlin получают типизированную спецификацию с полями, включая letterSpacing, textCase, textDecoration и verticalTrim. Отступы абзацев и оси вариативных шрифтов не выводятся. XML раскладывает поддерживаемые поля на ресурсы: <name>_font_family, <name>_font_weight, <name>_font_size, <name>_line_height, <name>_letter_spacing, <name>_text_case, <name>_text_decoration.

#Android XML

XML ограничен нативными ресурсами. output у файла XML задаёт папку, например values; drawable попадают в соседнюю папку drawable.

Тени, размытия, стекло, эффекты, переходы, кривые easing, border и strokeStyle не имеют аналога среди ресурсов: они попадают в диагностику и пропускаются.

#Справочник конфигурации

Конфиг только в YAML, version: 1. Относительные пути считаются от файла конфига. Неизвестные ключи считаются ошибкой, поэтому опечатку поймает validate-config.

#Верхний уровень

#source

projectConfig повторяет структуру config.json: collections с name и modes, а в каждом режиме name и files (карта «путь к файлу: enabled»). Для выбора токенов по коллекции и режиму нужен один из этих двух источников.

#options

#tokenSets[]

Селектор выбирает файлы либо по collection и mode из config.json, либо по glob-шаблонам:

tokenSets:
  - id: app-root
    selectors:
      - collection: Core
        mode: Default
      - collection: Themes
        mode: Light
        refModeMap:
          Core: Default
  - id: components
    unresolvedAliases: warn
    selectors:
      - files: ["components/**/*.style.json"]

#outputs[]

Output должен содержать хотя бы одно из files, bundles, bundlesFromCollections или indexes.

#outputs[].files[]

splitBySourceFile:

Плейсхолдеры: {sourceFile} (относительный путь), {sourceDir}, {sourceBase} (имя с расширением), {sourceName} (без расширения), {sourceStem} (ещё и без .style), {component} (папка после components/, иначе stem), {fileName} (то же, что {sourceStem}). selector принимает те же плейсхолдеры.

#bundles[] и bundlesFromCollections[]

Bundle собирает несколько исходных файлов одного набора в один выходной файл. Он проходит тот же путь, что и обычный файл, поэтому selector, filter, prefix, suffix и options работают одинаково.

#indexes[]

Index: входной файл, который импортирует сгенерированные: @import "..."; для CSS, @use "..." as *; для SCSS. Остальные платформы отвечают на indexes ошибкой.

Нужно задать imports или includeGenerated.

#Параметры манифеста

Задаются в options output с platform: manifest или одного из его файлов.

У каждой записи есть name, cssVar, path, type, value, sourceFile, references и weight. level и weight читаются из расширений level, sxl.level и sxl.weight; без них они равны null.

Имена ссылок также учитывают Code Syntax целевого токена, когда он записывается в другой файл. Цели разрешаются в пределах выбранного мода и настроенных зависимостей, поэтому ссылки из разных модов не смешиваются.

#Именование

Имена строятся из пути токена плюс prefix и suffix output. Токен с Code Syntax в $extensions сохраняет своё имя: ключ Web используется для CSS, SCSS и манифеста, iOS для Swift и UIKit, Android для Kotlin и XML. См. Scopes и Code Syntax.

codeSyntax у output задаёт запасной шаблон и приоритет:

#Типовые схемы

#Root и файлы тем (CSS)

outputs:
  - id: css-app
    platform: css
    outputDir: ./ds/css
    files:
      - tokenSet: app-root
        output: root.css
      - tokenSet: app-dark
        output: themes/dark.css
        selector: "[data-theme='dark']"
    indexes:
      - output: index.css
        imports: ["./root.css", "./themes/dark.css"]

Ссылки остаются как var(--...), поэтому тема переключается одним селектором.

#Один CSS-файл на компонент

outputs:
  - id: css-components
    platform: css
    outputDir: ./ds/components
    files:
      - tokenSet: components
        splitBySourceFile:
          include: ["components/**/*.style.json"]
          outputPattern: "{component}/{component}.css"
          prefixPattern: "c-{component}-"
        selector:
          - ":root"
          - "[data-component='{component}']"

Новый components/WAccordion/WAccordion.style.json получит собственный WAccordion/WAccordion.css при следующем запуске без изменений в конфиге.

#Свои форматтеры

Когда один тип токена должен выглядеть иначе на одной платформе, подключите к output JavaScript-модуль:

outputs:
  - id: css-app
    platform: css
    outputDir: ./ds/css
    files:
      - tokenSet: app-root
        output: root.css
    options:
      customFormatters:
        module: ./transform-hooks.mjs
        exportName: plugin

Модуль экспортирует объект с функциями tokenTypeFormatters.<platform>.<type>. Форматтер получает токен и возвращает undefined, чтобы оставить поведение по умолчанию, null, чтобы убрать токен, или замену токена. Необязательная функция platformEmitters.<platform> заменяет вывод всего файла. Тип CustomFormatterPlugin экспортируется пакетом.

#Проблемы и debug-отчёт

Когда sync находит проблемы (ссылка никуда не ведёт, сломан синтаксис ссылки, два токена с одним путём, файл не разбирается), он спрашивает, что делать:

1. Создать debug-файл и остановиться.
2. Создать debug-файл и продолжить.
3. Попробовать автоматически починить простой синтаксис ссылок и продолжить.
4. Пропустить сломанные токены и продолжить.

--issue-action даёт ответ заранее. Без терминала, например в CI, ask ведёт себя как debug-stop; в режиме --watch как debug-continue. Debug-отчёт <имя-конфига>.debug.md перечисляет каждую проблему с файлом и путём токена, а также сгенерированные файлы. При проблемах он записывается всегда; --debug-report записывает его и при чистом прогоне.

Рекомендуемые скрипты в package.json:

{
  "scripts": {
    "tokens:validate": "sxl-transform validate-config --config ./sxl-transform.config.yaml",
    "tokens:build": "sxl-transform sync --config ./sxl-transform.config.yaml --issue-action debug-stop",
    "tokens:build:ci": "sxl-transform sync --config ./sxl-transform.config.yaml --issue-action skip"
  }
}

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

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

• Токены в код
• Scopes и Code Syntax
• JSON-формат токенов
• Коллекции
• Источники токенов и синхронизация
• Storybook Addon