Token Export Formats

Token export formats determine how design tokens are delivered to consuming applications. Different platforms require different formats: CSS custom properties for web, Swift constants for iOS, XML resources for Android. Understanding available formats and their characteristics enables effective token distribution across diverse technology stacks.

What Are Token Export Formats

Token export formats are the file formats and syntactic structures used to represent tokens for consumption by applications. A single token source definition might export to CSS, JavaScript, Swift, Kotlin, and other formats, each tailored to its target platform’s conventions.

Export formats bridge the gap between platform-agnostic token definitions and platform-specific implementation requirements.

How Token Export Formats Work

Token transformation tools generate various formats from shared sources.

CSS Custom Properties for web applications:

:root {
  --color-primary: #3B82F6;
  --spacing-md: 16px;
  --font-size-body: 1rem;
}

JavaScript/TypeScript ES Modules for JS-based applications:

export const colorPrimary = '#3B82F6';
export const spacingMd = 16;
export const fontSizeBody = '1rem';

JavaScript Object format for structured access:

export const tokens = {
  color: {
    primary: '#3B82F6'
  },
  spacing: {
    md: 16
  }
};

Swift for iOS applications:

public struct Tokens {
  public static let colorPrimary = UIColor(red: 0.231, green: 0.510, blue: 0.965, alpha: 1.0)
  public static let spacingMd: CGFloat = 16
}

Kotlin for Android Compose:

object Tokens {
  val colorPrimary = Color(0xFF3B82F6)
  val spacingMd = 16.dp
}

Android XML for traditional Android development:

<resources>
  <color name="color_primary">#FF3B82F6</color>
  <dimen name="spacing_md">16dp</dimen>
</resources>

Key Considerations

• Format selection depends on target platform and build tooling
• Some platforms support multiple viable formats
• Type information enhances some formats (TypeScript definitions)
• Custom formats can be created for specific needs
• Format consistency within a platform aids integration
• Documentation should accompany format choices
• Version information can be embedded in outputs
• Minification may apply to certain formats

Common Questions

How should format selection be made?

Format selection starts with platform requirements and developer ergonomics.

Web platform options:

• CSS custom properties: Native, runtime-capable, broad support
• SCSS variables: Preprocessor-based, compile-time only
• JavaScript objects: Programmatic access, dynamic usage
• CSS-in-JS: Direct integration with styled-components, Emotion, etc.

Most web projects benefit from CSS custom properties as the primary format, with JavaScript for programmatic needs.

Native platform options:

• iOS: Swift classes/structs are idiomatic
• Android: XML resources for Views, Kotlin objects for Compose

Team familiarity influences selection. If developers expect tokens in a particular format, matching that expectation reduces friction.

Build system integration matters. Formats that require additional processing add complexity. Native formats that work directly are simpler.

What about custom formats?

Custom formats address organization-specific needs that built-in formats do not cover.

Style Dictionary supports custom formatters:

StyleDictionary.registerFormat({
  name: 'custom/json-flat',
  formatter: ({ dictionary }) => {
    const output = {};
    dictionary.allTokens.forEach(token => {
      output[token.name] = token.value;
    });
    return JSON.stringify(output, null, 2);
  }
});

Custom format use cases:

• Documentation generation from tokens
• Integration with proprietary systems
• Specialized data structures
• Combined tokens with metadata

Custom formats should be documented and tested to ensure they continue working as token sources evolve.

How should format versioning work?

Format outputs may need version identification for consumer reference.

Embedded version comments:

/* Design Tokens v2.3.0 - Generated 2024-01-15 */
:root {
  --color-primary: #3B82F6;
}

Export metadata files:

{
  "version": "2.3.0",
  "generated": "2024-01-15T12:00:00Z",
  "hash": "abc123"
}

Package versioning in npm or other registries provides the primary version mechanism for distributed tokens.

Filename versioning for CDN distribution:

tokens.v2.3.0.css
tokens.latest.css

Consumers should understand which version they are using and how to update.

Summary

Token export formats deliver design tokens in platform-appropriate structures. CSS custom properties serve web applications, while Swift and Kotlin serve native platforms. Format selection balances platform requirements with developer ergonomics. Custom formats address specific organizational needs. Versioning through embedded information, metadata files, or package systems helps consumers track token versions.