A custom Style Dictionary transformer for Unity UI-Toolkit.

---

Installation

npm install style-dictionary-unity-transformer style-dictionary

Roadmap

• Add publish workflow for npm releases
• Add unit tests for all transforms and formats
• Add example project demonstrating usage with Unity
• Figure out handling variables that use CSS calc()

Usage

Basic Usage

import StyleDictionary from 'style-dictionary';
import { registerUnityTransforms } from 'style-dictionary-unity-transformer';

// Register all Unity transforms with Style Dictionary
registerUnityTransforms(StyleDictionary);

// Configure and build
const sd = new StyleDictionary({
  source: ['tokens/**/*.json'],
  platforms: {
    unity: {
      transformGroup: 'unity',
      buildPath: 'Assets/Styles/',
      files: [{
        destination: 'tokens.uss',
        format: 'unity/uss-variables'
      }]
    }
  }
});

await sd.buildAllPlatforms();

Using the Config Helper

import StyleDictionary from 'style-dictionary';
import { registerUnityTransforms, getUnityConfig } from 'style-dictionary-unity-transformer';

registerUnityTransforms(StyleDictionary);

const sd = new StyleDictionary({
  source: ['tokens/**/*.json'],
  platforms: {
    unity: getUnityConfig({
      buildPath: 'Assets/UI/Styles/',
      fileName: 'design-tokens',
      selector: ':root',
      outputReferences: true
    })
  }
});

await sd.buildAllPlatforms();

Input Token Format

This transformer supports the Design Tokens Community Group (DTCG) format:

{
  "color": {
    "primary": {
      "$value": "#3366FF",
      "$type": "color"
    },
    "secondary": {
      "$value": "{color.primary}",
      "$type": "color"
    }
  },
  "spacing": {
    "small": {
      "$value": "8px",
      "$type": "dimension"
    },
    "medium": {
      "$value": "16px",
      "$type": "dimension"
    }
  },
  "shadow": {
    "card": {
      "$value": {
        "offsetX": "0px",
        "offsetY": "4px",
        "blur": "8px",
        "color": "rgba(0, 0, 0, 0.1)"
      },
      "$type": "shadow"
    }
  }
}

Output USS Format

The transformer generates Unity Style Sheets with CSS custom properties:

/**
 * Unity Style Sheet (USS) Design Tokens
 * 
 * Auto-generated by Style Dictionary
 * Do not edit directly
 */

:root {
  /* color */
  --color-primary: #3366FF;
  --color-secondary: var(--color-primary);
  
  /* spacing */
  --spacing-small: 8px;
  --spacing-medium: 16px;
  
  /* shadow */
  --shadow-card: 0px 4px 8px rgba(0, 0, 0, 0.1);
}

Transforms

color/uss

Converts color values to USS-compatible format:

• Opaque colors → #RRGGBB hex format
• Colors with alpha → rgba(r, g, b, a) format
• Supports hex, rgb, rgba, hsl, hsla input formats

size/uss

Converts dimension values to USS-compatible px units:

• rem/em → px (assumes 16px base)
• pt → px (1pt ≈ 1.333px)
• % → kept as-is (USS supports percentages)
• Unitless numbers → px

shadow/uss

Converts shadow tokens to USS text-shadow format:

• Format: <offset-x> <offset-y> <blur> <color>
• Supports multiple shadows (comma-separated)
• Note: USS only supports text-shadow, not box-shadow

Transform Group

The unity transform group applies these transforms in order:

1. attribute/cti - Adds category/type/item attributes
2. name/kebab - Converts to kebab-case variable names
3. color/uss - Color value transformation
4. size/uss - Dimension value transformation
5. shadow/uss - Shadow value transformation

Formats

unity/uss-variables

Outputs USS files with CSS custom properties (variables).

Option	Type	Default	Description
selector	string	':root'	CSS selector for the variable block
outputReferences	boolean	true	Use var() references for linked tokens
showFileHeader	boolean	true	Include auto-generated file header comment
fileHeader	string	-	Custom file header text

unity/tss-theme

Outputs TSS (Theme Style Sheet) files for Unity theming. TSS files can import other USS/TSS files and the default Unity theme.

Option	Type	Default	Description
selector	string	':root'	CSS selector for the variable block
outputReferences	boolean	true	Use var() references for linked tokens
showFileHeader	boolean	true	Include auto-generated file header comment
fileHeader	string	-	Custom file header text
importDefaultTheme	boolean	true	Import the default Unity theme
imports	string[]	[]	Additional USS/TSS files to import

TSS Example

import StyleDictionary from 'style-dictionary';
import { registerUnityTransforms, getUnityTssConfig } from 'style-dictionary-unity-transformer';

registerUnityTransforms(StyleDictionary);

const sd = new StyleDictionary({
  source: ['tokens/**/*.json'],
  platforms: {
    unityTheme: getUnityTssConfig({
      buildPath: 'Assets/UI/Themes/',
      fileName: 'CustomTheme',
      importDefaultTheme: true,
      imports: ['/Assets/Styles/base.uss']
    })
  }
});

await sd.buildAllPlatforms();

TSS Output

/**
 * Unity Theme Style Sheet (TSS)
 * 
 * Auto-generated by Style Dictionary
 * Do not edit directly
 */

@import url("unity-theme://default");
@import url("/Assets/Styles/base.uss");

:root {
  /* color */
  --color-primary: #3366FF;
}

USS/TSS Limitations

Unity Style Sheets have some limitations compared to CSS:

• Units: Only px and % are supported (no rem, em, vw, vh)
• Shadows: Only text-shadow is supported (no box-shadow)
• Variables in functions: var() cannot be used inside functions like rgb()
• Math: No calc() or mathematical operations on variables

API Reference

registerUnityTransforms(sd)

Registers all Unity USS/TSS transforms, formats, and transform groups with Style Dictionary.

getUnityConfig(options)

Returns a pre-configured platform configuration object for USS output.

getUnityTssConfig(options)

Returns a pre-configured platform configuration object for TSS theme output.

Individual Exports

For advanced usage, you can import individual components:

import { 
  colorUssTransform,
  sizeUssTransform,
  shadowUssTransform,
  ussVariablesFormat,
  tssThemeFormat,
  unityTransformGroup
} from 'style-dictionary-unity-transformer';