Style Dictionary Platforms

Style Dictionary platforms are configuration blocks that define how design tokens transform and output for specific target environments. Each platform configuration specifies the transforms to apply, output file formats, and build destinations, enabling a single token source to generate appropriate outputs for web, iOS, Android, React Native, and other platforms.

What Are Style Dictionary Platforms

In Style Dictionary, a platform represents a target environment with its own requirements for token format and structure. The platform configuration tells Style Dictionary how to process tokens for that specific target. Multiple platforms can be configured in a single Style Dictionary configuration file, allowing one build command to generate outputs for all targets.

Platform configuration includes several key elements. Transform groups define the sequence of transforms that modify token names and values for platform conventions. Build paths specify where output files are written. File configurations define output file formats, names, and any filtering or formatting options.

Style Dictionary ships with predefined platform configurations and transform groups for common targets. The css transform group prepares tokens for CSS output. The ios-swift transform group handles iOS Swift conventions. Teams can use these defaults directly or create custom configurations for specialized requirements.

How Style Dictionary Platforms Work

Platform configuration begins with selecting or defining a transform group. Transform groups bundle individual transforms that apply sequentially to each token. The css transform group includes transforms for sizing values, color formats, and naming conventions appropriate for CSS custom properties.

module.exports = {
  source: ['tokens/**/*.json'],
  platforms: {
    web: {
      transformGroup: 'css',
      buildPath: 'build/css/',
      files: [{
        destination: 'variables.css',
        format: 'css/variables'
      }]
    },
    ios: {
      transformGroup: 'ios-swift',
      buildPath: 'build/ios/',
      files: [{
        destination: 'StyleDictionaryColor.swift',
        format: 'ios-swift/class.swift',
        filter: { type: 'color' }
      }]
    },
    android: {
      transformGroup: 'android',
      buildPath: 'build/android/',
      files: [{
        destination: 'colors.xml',
        format: 'android/colors',
        filter: { type: 'color' }
      }]
    }
  }
};

File configuration within each platform defines individual output files. A platform might generate multiple files, perhaps separating colors from typography or creating different files for different token categories. Filters select which tokens appear in each file based on token attributes or types.

Format configuration determines output file structure and syntax. Built-in formats cover common needs like CSS custom properties, SCSS variables, Swift classes, and Android XML resources. Custom formats enable specialized output structures for unique requirements.

Build execution processes each platform independently. The build process reads source tokens, applies the platform’s transforms, filters tokens for each file, and writes output using the specified format. Errors in one platform do not prevent other platforms from building successfully.

Key Considerations

• Transform group selection significantly affects output compatibility with target platforms
• File filtering strategies determine token organization in output
• Custom formats require understanding of Style Dictionary’s template system
• Build path organization affects integration with platform build systems
• Platform naming should clearly indicate target environment
• Configuration validation catches errors before build time

Common Questions

How do teams create custom platforms for specialized targets?

Custom platforms combine transform groups, build paths, and file configurations tailored to specific requirements. Teams might create custom platforms for proprietary frameworks, design tool exports, or documentation generation.

Custom transform groups register individual transforms in a specific sequence. Transforms can be built-in, community-contributed, or custom implementations. The transform registration API allows defining custom transforms that manipulate token names, values, or attributes.

Custom formats generate output in any required structure. Format functions receive processed tokens and configuration, returning string content for output files. Templates using mustache, lodash, or other templating approaches can generate complex output structures.

Organizations often start with built-in platforms and progressively customize as needs become clear. Adding custom transforms to handle edge cases or creating custom formats for specific integration requirements evolves configurations over time.

What challenges arise when configuring multiple platforms?

Token naming compatibility across platforms requires attention. Some platforms have naming restrictions that others do not. iOS Swift requires valid Swift identifiers while CSS custom properties accept broader character sets. Transform configurations must produce valid names for all targets.

Value format differences between platforms need appropriate transforms. Colors might need RGB values for one platform and hex for another. Dimension values might need unit suffixes for web but unitless numbers for native platforms. Platform-specific transforms handle these conversions.

File organization varies by platform convention. Web projects might expect a single CSS file. Android projects expect resources in specific directory structures. iOS projects might consume Swift files or asset catalogs. Platform configurations must produce outputs matching expected conventions.

Testing across platforms verifies correct output generation. Automated tests can compare generated output against expected baselines, catching regressions when configuration changes. Platform-specific validation ensures outputs are syntactically valid and correctly structured.

How does Style Dictionary handle platform-specific tokens?

Token filtering enables platform-specific inclusion or exclusion. Tokens can include platform metadata indicating which platforms should receive them. File filters select tokens based on this metadata, including only appropriate tokens in each platform’s output.

Separate source files can organize platform-specific tokens. Platform configurations can specify additional source paths beyond shared sources, adding platform-specific tokens to the build for that platform only.

Token value overrides allow platform-specific values for shared tokens. A token might have a base value with platform-specific overrides that transforms apply when building for that platform. This approach maintains shared token names while accommodating platform value differences.

Summary

Style Dictionary platforms configure how design tokens transform for specific target environments, enabling single-source token management across web, iOS, Android, and other platforms. Effective platform configuration requires understanding transform groups, file filtering, and output formats while addressing cross-platform challenges in naming compatibility and value formatting. Well-structured platform configurations enable reliable, automated token distribution across an organization’s technology portfolio.