Transformer

Transformer (@sxl-studio/token-transformer, version 3.4.1) is a command-line tool that turns the token JSON files exported by the plugin into code. It runs on a developer's computer and in CI, is configured with one YAML file and rebuilds only what changed. It needs Node.js 20 or newer.

For a one-off export without a terminal use the plugin itself, see Tokens to code. Transformer reads the same files and the same config.json.

#Quick start in 5 minutes

You need Node.js 20 or newer and a folder with the token JSON files and config.json from the plugin. Where that folder comes from is described in Token sources and synchronization.

1. Install the package in the project: npm install --save-dev @sxl-studio/token-transformer. pnpm add -D and yarn add -D work the same way.
2. Create a starter config: npx sxl-transform init. The file sxl-transform.config.yaml appears in the current folder with examples for every platform.
3. Open the file. Point source.tokenDir to the token folder and replace the collection and mode names in tokenSets with the ones from your config.json. Delete the outputs you do not need.
4. Check the config: npx sxl-transform validate-config.
5. Build: 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

The generated files appear in the outputDir of every output. Next to the config the tool writes sxl-transform.config.state.json: with it the next sync rebuilds only the outputs whose tokens changed. The state file is safe to leave out of Git: without it the next run is a full rebuild.

#Commands

#Options of sync

#sync strategies: smart, force and preserve

The sync command has two rebuild modes: smart and force. Preserve is a separate policy that merges generated data with existing output files.

# Normal synchronization: JSON remains the source of truth
npx sxl-transform sync --config ./sxl-transform.config.yaml --mode smart --issue-action debug-stop

# Rebuild every configured output
npx sxl-transform sync --config ./sxl-transform.config.yaml --mode force --issue-action debug-stop

# Migration: retain old declarations, update matches and add new ones
npx sxl-transform sync --config ./sxl-transform.config.yaml --mode smart --preserve-existing --issue-action debug-stop

A neutral scripts setup for a project:

{
  "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"
  }
}

For example, an output used to contain --color-action and --color-legacy. After a refactor, the value of color.action changes, color.legacy is removed from JSON and color.accent is added. Normal smart and force update action, add accent and remove legacy. Preserve updates action, adds accent and retains legacy. If a token is renamed, preserve keeps the previous name and adds the new one; a later normal smart rebuild removes the previous name.

Preserve reads old declarations from output files, so do not clean the output directory before using it. For a scoped run, add the same --only-output and --only-file options listed above. Changes outside the selected scope remain pending for the next full sync.

# only two outputs
npx sxl-transform sync --only-output css-app --only-output swift-app

# only the dark theme file of the css-app output
npx sxl-transform sync --only-file "css-app:modes/dark.css"

# CI: never wait for input, skip broken tokens
npx sxl-transform sync --issue-action skip

#How preserve matches declarations

For CSS, SCSS, Swift, UIKit, Kotlin, Android XML and manifests, matching uses the public name and declaration scope:

Old declarations replaced by current ones in another file within the same scope are not duplicated. Separate Sass modules and native namespaces remain independent: changing NewTokens.size does not update OldTokens.size. Stale output files and their imports through indexes.includeGenerated remain available. Native namespaces and shared helper types have one owner within each compilation scope.

The flag is invocation-only; it has no YAML setting. It works with --mode smart, --force, --watch, --only-output and --only-file. Running without it restores normal source-based generation for the selected outputs; retained values are removed when those files are rebuilt. options.removeStaleOutputs: false separately controls retention of entire stale files.

Without a state file, existing files are recovered through configured generation paths and split patterns. Arbitrary files outside those patterns are not discovered. Values already lost from existing outputs cannot be recovered. Retained outputs do not replace JSON sources during alias resolution.

Malformed or unsupported files stop the run before any outputs are written. The handlers support Transformer-generated structures; arbitrary custom formatter code may require adaptation. CSS anonymous @layer blocks cannot be merged because they lack stable identities. Source-token warnings still follow --issue-action. An empty glob caused by confirmed removal of previous sources becomes informational when existing outputs are retained.

#Smart mode and the state file

sync compares the content of the token files with the state file and rebuilds only the outputs that depend on changed files. The generated files are checked too: a file that was deleted or edited by hand is written again. Files whose tokens disappeared are deleted, unless options.removeStaleOutputs is false.

In 3.4.1, smart writes only files whose actual content differs, including after config or preservation-policy changes. --mode force regenerates and writes all selected outputs. --mode smart --preserve-existing retains declarations absent from JSON; a rename keeps both old and new names. Preliminary directory cleanup is unnecessary and removes the data that preserve needs to retain.

What to expect:

• The first run and a run without a state file rebuild everything. Upgrades that change generated output, including 3.4.1, invalidate older state once; later unchanged runs skip generation again.
• A run limited with --only-output or --only-file does not hide the other changes: the next full run picks them up. With --only-file stale files outside the selection are kept.
• While sync runs, the file <state>.lock blocks a second parallel run. A lock older than 10 minutes is taken over automatically.
• If your own script rewrites the generated files after sync, the next run rebuilds them, because their content no longer matches the state. Run such scripts before sync or write to another folder.
• --watch watches the token folder, the YAML config and config.json, ignores the output folders and never asks questions: when problems are found it writes the debug report and continues.

#Which tokens are converted

CSS, SCSS, Swift, UIKit and Kotlin recognize the following token groups. The accepted value shapes and generated fields depend on the target platform; see the limitations below.

The remaining types:

• glass is recognized and retained in the manifest. Typed outputs do not have a glass-specific representation; standalone glass values are unsupported, and glass layers inside effects produce diagnostics.

• custom tokens are kept as they are. The manifest exports their $value verbatim; the other platforms skip them with a warning, because the value has no fixed shape.

• template, composition and grid describe Figma structures, not values, and are never converted. options.unsupportedTypes decides whether they produce an error, a warning or are skipped silently.

Tokens hidden in Figma ($extensions["figma.hide"]) are exported by default, because visible tokens often reference them. excludeHidden: true on an output drops them.

References ({color.brand}), numeric expressions and supported figma.modify colour modifiers are resolved before generation. Math runs only for numeric types; a text token such as "37-37" is never calculated. The source format is described in Token JSON format; support for a Figma field does not imply that every output can render it.

#Value shapes and platform limits

• Dimension and duration tokens accept DTCG {value, unit} objects. DTCG colours accept numeric components in srgb, display-p3, hsl, oklch and lch, or a supported hex fallback. Other colour spaces and none components need a fallback; invalid explicit alpha is rejected.
• CSS/SCSS accept gradient strings, including repeating gradients, shadow shorthand and image URLs. Figma video and pattern fills and standalone glass values have no complete conversion. Spring easing is an approximation and produces a warning.
• SwiftUI, UIKit and Kotlin export values and typed specifications. Linear gradient strings retain direction and double-position stops. Complex radial/conic geometry, repeating gradients, automatic typography line height and Figma video/pattern/glass fills remain unsupported value shapes.
• Image filters and transforms, progressive blur geometry, noise/texture/glass effect layers and font variation axes are not reproduced by the generated value/spec formats. Diagnostics identify fields that would otherwise be omitted.
• A manifest retains the authored data for allowed token types, including custom. It does not render effects. Keep it alongside typed outputs when you need the original details.

Unsupported values produce diagnostics; they are not proof of a successful conversion. The default policy stops on errors. Use a documented warning/skip policy only when your consumer can intentionally omit those values.

#Typography

A typography token needs fontFamily, fontWeight, fontSize and lineHeight. CSS and SCSS get one shorthand value in the font order: style, weight, size/line-height, family; fields outside that shorthand produce warnings. Swift, UIKit and Kotlin get a typed spec with fields including letterSpacing, textCase, textDecoration and verticalTrim. Paragraph spacing, paragraph indent and font variation axes are not emitted. XML splits supported fields into resources: <name>_font_family, <name>_font_weight, <name>_font_size, <name>_line_height, <name>_letter_spacing, <name>_text_case, <name>_text_decoration.

#Android XML

XML is limited to native resources. The output of an XML file mapping is a folder, for example values; drawables go to the sibling drawable folder.

Shadows, blurs, glass, effects, transitions, easing curves, border and strokeStyle have no resource equivalent: they are listed in the diagnostics and skipped.

#Configuration reference

The config is YAML only, version: 1. Relative paths are resolved from the config file. Unknown keys are errors, so a typo is caught by validate-config.

#Top level

#source

projectConfig repeats the structure of config.json: collections with name and modes, and in every mode name plus files (a map of file path to enabled). Selecting tokens by collection and mode needs one of the two sources.

#options

#tokenSets[]

A selector picks files either by collection and mode from config.json, or by globs:

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[]

An output needs at least one of files, bundles, bundlesFromCollections or indexes.

#outputs[].files[]

splitBySourceFile:

Placeholders: {sourceFile} (relative path), {sourceDir}, {sourceBase} (name with extension), {sourceName} (without extension), {sourceStem} (also without .style), {component} (the folder after components/, otherwise the stem), {fileName} (same as {sourceStem}). selector accepts the same placeholders.

#bundles[] and bundlesFromCollections[]

A bundle collects several source files of one token set into one output file. It goes through the same pipeline as a regular file, so selector, filter, prefix, suffix and options work the same way.

#indexes[]

An index is an entry file that imports the generated files: @import "..."; for CSS, @use "..." as *; for SCSS. Other platforms report an error for indexes.

imports or includeGenerated must be set.

#Manifest options

Set them in options of a manifest output or of one of its files.

Every entry has name, cssVar, path, type, value, sourceFile, references and weight. level and weight are read from the extensions level, sxl.level and sxl.weight; without them they are null.

Reference names also respect the target token's Code Syntax when the target is emitted into another file. Targets are resolved within the selected mode and its configured dependencies, so references from different modes are not mixed.

#Naming

Names are built from the token path plus the output prefix and suffix. A token with Code Syntax in $extensions keeps its own name: the Web key is used for CSS, SCSS and manifest, iOS for Swift and UIKit, Android for Kotlin and XML. See Scopes and Code Syntax.

codeSyntax on an output sets a fallback template and the priority:

#Typical setups

#Root plus theme files (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"]

References stay as var(--...), so the theme switches with the selector alone.

#One CSS file per component

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}']"

A new components/WAccordion/WAccordion.style.json gets its own WAccordion/WAccordion.css on the next run without any change to the config.

#Custom formatters

When one token type must look different on one platform, attach a JavaScript module to the output:

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

The module exports an object with tokenTypeFormatters.<platform>.<type> functions. A formatter receives the token and returns undefined to keep the default, null to drop the token, or a replacement token. An optional platformEmitters.<platform> function replaces the rendering of the whole file. The CustomFormatterPlugin type is exported by the package.

#Problems and the debug report

When sync finds problems (a reference that points nowhere, a broken reference syntax, two tokens with one path, a file that does not parse), it asks what to do:

1. Create the debug file and stop.
2. Create the debug file and continue.
3. Try to auto-fix simple reference syntax and continue.
4. Skip broken tokens and continue.

--issue-action gives the answer in advance. Without a terminal, for example in CI, ask behaves as debug-stop; in --watch mode as debug-continue. The debug report <config-name>.debug.md lists every problem with the file and the token path, plus the generated files. It is always written when there are problems; --debug-report writes it for a clean run too.

Recommended package.json scripts:

{
  "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"
  }
}

#If something does not work

#Related pages

• Tokens to code
• Scopes and Code Syntax
• Token JSON format
• Collections
• Token sources and synchronization
• Storybook Addon