Transforming Your Tokens to JSON and Any Development Language Using Style Dictionary

Transforming Your Tokens to JSON and Any Development Language Using Style Dictionary

As design systems grow more complex and teams increasingly rely on design tokens to ensure consistency, the need to transform these tokens into various development languages becomes essential. This is where tools like Style Dictionary come into play. Style Dictionary is a robust framework that enables you to convert your design tokens into code tailored to different platforms, such as web, iOS, Android, and more.

In this module, we’ll walk you through the process of transforming your tokens into JSON and then into a specific development language using Style Dictionary. If you are new to design tokens or have not read our previous post in this series, check out our overview here.

Step 1: Preparing Your Tokens as JSON

To begin the transformation process you must first ensure your design tokens are organized in a JSON format. This structure is crucial because it serves as the foundation for converting tokens into other formats. If you’re using Figma or another design tool with Tokens Studio, you can easily export your tokens as a JSON file. Alternatively, if you’re starting from scratch, you can manually define your tokens in a JSON file.

Here’s a simple example of what a design token JSON might look like:

{
    "color": {
        "primary": {
            "value": "#FF5733",
            "type": "color"
        },
        "secondary": {
            "value": "#33FF57",
            "type": "color"
        }
    },
    "font": {
        "base": {
            "value": "Arial, sans-serif",
            "type": "font"
        }
    }
}

This JSON structure categorizes tokens by their purpose, such as color or font, and assigns each a value and type.

Step 2: Installing Style Dictionary

With your tokens prepared in JSON, the next step is to install Style Dictionary. Style Dictionary is a tool that takes your JSON tokens and transforms them into platform-specific code. To get started, you’ll need Node.js installed on your system. Then, you can install Style Dictionary using Node Package Manager (NPM).

Open your terminal and run the following command:

npm install style-dictionary

This command installs Style Dictionary globally, making it accessible for transforming your design tokens.

Step 3: Configuring Style Dictionary

Once Style Dictionary is installed, the next step is to configure it to transform your design tokens into the desired output formats. The configuration file, typically named config.json or style-dictionary.config.js, defines how the tokens should be transformed and what formats they should be output in.

Here’s a basic example of a configuration file:

{
  "source": ["tokens/*.json"],
  "platforms": {
    "web": {
      "transformGroup": "web",
      "buildPath": "build/web/",
      "files": [{
        "destination": "variables.css",
        "format": "css/variables"
      }]
    },
    "ios": {
      "transformGroup": "ios",
      "buildPath": "build/ios/",
      "files": [{
        "destination": "StyleDictionaryColor.h",
        "format": "ios/colors.h"
      }]
    },
    "android": {
      "transformGroup": "android",
      "buildPath": "build/android/",
      "files": [{
        "destination": "colors.xml",
        "format": "android/colors"
      }]
    }
  }
}

In this example, the configuration file specifies that the source tokens are located in the tokens/ directory. The tokens are then transformed into CSS variables for web, Objective-C headers for iOS, and XML files for Android.

Step 4: Running the Transformation

With the configuration file in place, you can now run Style Dictionary to transform your tokens. From your terminal, navigate to the directory containing your configuration file and run:

npx style-dictionary build

This command processes your tokens according to the configuration file and outputs the transformed code into the specified directories. Step 5: Customizing Your Transformations While Style Dictionary provides a wide range of pre-built transforms, you may need to customize these to fit your project’s specific needs. This can be done by creating custom transforms or modifying existing ones. Tokens Studio offers official transforms in a package called @tokens-studio/sd-transforms, which you can use as a starting point.

For example, if you need to output custom CSS properties instead of standard CSS variables, you can define a custom transform in your configuration file. Here’s a snippet showing how you might configure a custom CSS transform:

{
  "transform": {
    "name": "custom/css",
    "type": "value",
    "matcher": function(prop) {
      return prop.attributes.category === 'color';
    },
    "transformer": function(prop) {
      return `--${prop.name}: ${prop.value};`;
    }
  }
}

This custom transform checks if the token’s category is color and then outputs it as a custom CSS property.

Step 6: Using Style Dictionary Configurator

If you prefer a more visual approach, you can use the Style Dictionary Configurator—a web-based tool that allows you to transform your design tokens directly in your browser. This tool uses Style Dictionary under the hood and is perfect for experimenting with transformations without needing to install anything on your computer.

Simply upload your JSON file, configure the output formats, and let the tool handle the rest. This is especially useful for quick prototyping or testing different transformation setups.

Conclusion

Transforming design tokens into various development languages is a crucial step in maintaining a consistent design-to-code pipeline. By leveraging tools like Style Dictionary, you can ensure that your design tokens are not only easily managed but also seamlessly integrated into your development workflow across multiple platforms. Whether you’re working with web, iOS, Android, or custom platforms, Style Dictionary provides the flexibility and power needed to transform your design tokens into the formats your development team requires.

Stay tuned for the final installment of our series, and if you want to learn more and truly master design tokens, sign up for our upcoming workshop.