Platform-Specific Token Transforms

Platform-specific token transforms convert universal token definitions into formats that each target platform can consume natively. Different platforms have different requirements for value formats, naming conventions, and file structures. Transforms bridge these differences, allowing a single token source to generate outputs for web, iOS, Android, and other platforms.

What Are Platform-Specific Token Transforms

Platform-specific token transforms are operations that modify token values, names, or structures to match the requirements and conventions of particular platforms. A color token stored as a hex value might transform to CSS rgb() syntax for web, UIColor for iOS, and Color for Android Compose.

Transforms operate at multiple levels. Value transforms modify the token’s stored value. Name transforms adjust how the token is identified. Attribute transforms add platform-specific metadata. Format transforms determine output file structure.

How Platform-Specific Token Transforms Work

Token transformation tools like Style Dictionary apply transforms in a configurable pipeline. Each platform configuration specifies which transforms to apply.

For CSS output, common transforms include:

Value: #3B82F6 → #3B82F6 (unchanged or converted to rgb)
Name: color.background.primary → --color-background-primary
Format: CSS custom properties file

For iOS Swift output:

Value: #3B82F6 → UIColor(red: 0.231, green: 0.510, blue: 0.965, alpha: 1.0)
Name: color.background.primary → colorBackgroundPrimary
Format: Swift extension file

For Android Compose:

Value: #3B82F6 → Color(0xFF3B82F6)
Name: color.background.primary → ColorBackgroundPrimary
Format: Kotlin object file

Transforms chain together, with each transform operating on the output of the previous. A color value might first resolve references, then convert to the target format, then adjust precision.

Configuration specifies transform sets per platform:

{
  platforms: {
    css: {
      transformGroup: 'css',
      files: [{ destination: 'tokens.css', format: 'css/variables' }]
    },
    ios: {
      transformGroup: 'ios-swift',
      files: [{ destination: 'Tokens.swift', format: 'ios-swift/class.swift' }]
    }
  }
}

Transform groups bundle commonly needed transforms for each platform, providing sensible defaults while allowing customization.

Key Considerations

• Source tokens should store values in a platform-neutral format
• Transforms should be pure functions without side effects
• Transform order matters and should be documented
• Edge cases in value conversion need explicit handling
• Platform SDK updates may require transform updates
• Testing should verify transformed values on target platforms
• Custom transforms should follow the same patterns as built-in transforms
• Transform configuration should be version controlled

Common Questions

What value formats work best as source?

Source values should use formats that preserve full information without platform bias. For colors, hex values with optional alpha (#3B82F6 or #3B82F680) or standardized color formats work well. Dimensions should use a consistent unit (pixels) that transforms can convert as needed.

Avoid source values in platform-specific formats. A color stored as UIColor(...) in the source cannot cleanly transform to CSS. Starting with hex and transforming to UIColor is straightforward; reversing is problematic.

Modern token specifications like the W3C Design Tokens format define standard value formats that transforms can reliably process. Adopting these standards improves interoperability with token tooling.

Complex values like shadows or gradients benefit from structured storage that transforms can parse:

{
  "shadow": {
    "offsetX": "4px",
    "offsetY": "4px",
    "blur": "8px",
    "spread": "0px",
    "color": "{color.shadow}"
  }
}

Transforms assemble these components into platform-specific syntax.

How should naming conventions vary by platform?

Each platform has idiomatic naming conventions that transforms should respect. Following platform conventions makes tokens feel native rather than foreign.

CSS uses kebab-case with double-hyphen prefix: --color-background-primary. This matches CSS custom property conventions.

JavaScript uses camelCase: colorBackgroundPrimary. This aligns with JavaScript variable naming conventions.

Swift uses camelCase for properties and PascalCase for types: Token.colorBackgroundPrimary or ColorToken.backgroundPrimary.

Android XML uses snake_case: color_background_primary. Android Compose uses PascalCase for objects: Color.BackgroundPrimary.

Name transforms handle these conversions automatically. The source token name color.background.primary serves as the canonical identifier, with transforms generating platform-appropriate variations.

What about platform-specific tokens?

Some tokens apply to specific platforms only. CSS-specific transitions, iOS-specific haptic patterns, or Android-specific ripple effects have no cross-platform meaning.

These platform-specific tokens can exist in the source with platform markers:

{
  "animation": {
    "transition": {
      "duration": { "value": "200ms", "platforms": ["css"] }
    }
  }
}

Transform configuration filters tokens based on platform markers, including them only in relevant outputs.

Alternatively, platform-specific tokens live in separate source files that only process for their target platform. This keeps the main token set platform-neutral while allowing platform extensions.

The boundary between universal and platform-specific tokens reflects design decisions. Duration values might apply universally even if implementation differs. Hardware-specific interactions typically remain platform-specific.

Summary

Platform-specific token transforms convert universal token definitions into native formats for each target platform. Value transforms handle format conversion, name transforms apply platform conventions, and format transforms produce appropriate file structures. Configuring transforms per platform while maintaining platform-neutral source tokens enables efficient multi-platform design system delivery.