Tokens to Code

#Overview

Tokens to Code преобразует token JSON в готовые выходные файлы для разработки. Доступны два пути:

#Поток в плагине (Download -> Tokens to Code)

Поддерживаемые платформы в плагине

• css
• scss
• swiftui (выходной файл .swift)
• uikit (выходной файл .uikit.swift)
• kotlin (выходной файл .kt)
• xml (бандл Android XML ресурсов)

Настройки в плагине

Структура вывода из плагина

Плагин формирует ZIP-архив: tokens-transformed.zip.

Warning (XML): Android XML вывод намеренно ограничен нативными ресурсами. Эмитятся простые ресурсы и поддерживаемые drawable; сложные runtime-only структуры токенов пропускаются с диагностикой.

#Именование и code syntax

Базовое именование

• CSS: custom properties (--token-path)
• SCSS: Sass variables ($token-path)
• Swift: Swift identifiers
• Kotlin: Kotlin identifiers
• Android XML: имена ресурсов (@color/..., @dimen/..., @string/..., drawable XML-файлы)

Swift, SwiftUI и UIKit output включают Sendable support types для проектов на Swift 6 strict concurrency.

Поддержка $extensions.figma.codeSyntax

Если поле задано, имена могут быть переопределены по платформам:

• Web для CSS
• iOS для Swift
• Android для Kotlin / XML

Пример:

{
  "$extensions": {
    "figma.codeSyntax": {
      "Web": "var(--color-primary)",
      "iOS": "Color.primary",
      "Android": "@color/primary"
    }
  }
}

#Поведение алиасов

Resolve Aliases = OFF

• Предпочтительно для CSS-каскада.
• Алиасы сохраняются как ссылки, где возможно (например var(--other-token)).

Resolve Aliases = ON

• Предпочтительно для mobile-целей, где обычно нужны финальные literal-значения.
• Цепочки алиасов резолвятся до эмита.

#Покрытие типов

Кодогенерация поддерживает simple и composite семейства токенов, используемые в token packs SXL Studio, включая:

• colors, dimensions, spacing, radii, widths, opacity, text/string/boolean
• typography
• shadows, blur/backdrop blur, effects, glass
• fills и gradients
• duration и cubic-bezier значения

Важные заметки рантайма:

• template, composition, grid и custom пропускаются в дефолтной конфигурации Transformer.
• Неподдерживаемые токены дают diagnostics (warning/error в зависимости от политики конфига).

#Разбиение эффектов в CSS

Когда включён Split Effects, effect-like токены могут выводиться как несколько CSS-переменных, а не как одно агрегированное значение.

Это полезно, когда в кодовой базе тени/blur/backdrop обрабатываются раздельно.

#Transformer CLI (@sxl-studio/token-transformer)

Используйте CLI для воспроизводимых локальных прогонов и CI/CD.

Установка

npm install --save-dev @sxl-studio/token-transformer
# или
pnpm add -D @sxl-studio/token-transformer
# или
yarn add -D @sxl-studio/token-transformer

Команды

# smart incremental transform (команда по умолчанию)
npx sxl-transform sync --config ./sxl-transform.config.yaml
# или через pnpm
pnpm exec sxl-transform sync --config ./sxl-transform.config.yaml

# full rebuild
npx sxl-transform sync --config ./sxl-transform.config.yaml --force

# только валидация конфига
npx sxl-transform validate-config --config ./sxl-transform.config.yaml

# создать стартовый конфиг
npx sxl-transform init --path ./sxl-transform.config.yaml

Возможности CLI

• Только YAML-конфиг (.yaml / .yml)
• Инкрементальные stateful-сборки (smart mode)
• Режим полного пересбора (force)
• Режимы обработки проблемных токенов (ask, debug-stop, debug-continue, autofix, skip)
• Генерация debug-report для разбора проблем

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

• css
• scss
• swift
• uikit
• kotlin
• xml (Android resources)
• manifest (JSON metadata для документации, Storybook token viewers, devtools, аудита и миграций)

#Формат конфигурации Transformer (YAML)

Обязательные верхнеуровневые секции:

Минимальный валидный пример

version: 1
source:
  tokenDir: ./tokens
  configFile: config.json
  include: ["**/*.json"]
  exclude: ["config.json", "**/diff-id*.json"]

options:
  remBase: 16
  collisionStrategy: error
  unsupportedTypes:
    default: warn
    types:
      template: skip
      composition: skip
      grid: skip

tokenSets:
  - id: root
    selectors:
      - collection: Core
        mode: Default

outputs:
  - id: css-root
    platform: css
    outputDir: ./design-system/css
    resolveAliases: false
    splitEffects: true
    showDescriptions: true
    files:
      - tokenSet: root
        output: root.css

  - id: tokens-manifest
    platform: manifest
    outputDir: ./design-system/manifest
    files:
      - tokenSet: root
        output: tokens-manifest.json
        options:
          includeResolvedValue: true
          includeReferences: true

#Рекомендуемые проверки

В product repository сначала проверьте конфиг, а затем добавляйте transform в CI:

npx sxl-transform validate-config --config ./sxl-transform.config.yaml
npx sxl-transform sync --config ./sxl-transform.config.yaml --mode smart

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

• Token JSON format
• Token types
• Scopes & Code Syntax
• Export Variables & Styles
• Composition