Design Token Transformation

The base of the design system — the layer that connected the design and engineering teams — was a formalized set of design values commonly called design tokens. At its core this design value or design token is a single key/value pair. It can have meta data associated with it (like a comment for context) but its essence is the name and value. E.g. color.primary = #f00. They are like atoms: the smallest units with which to build the components which make up the parts that comprise the application.

This token value never changes no matter which platform is using it. Red is red in Figma just as much as it is red on the web or in a mobile app. But what does change from platform to platorm is the syntax for how this red is represented.

Let’s say this red is stored in a library in JSON format as a hex value: #f00. This same hex value can be used in Figma or Sketch, in web platforms, and even in Android apps. However, for iOS apps it needs to be stored as a UIColor: UIColor(red: 1.000, green: 0.000, blue: 0.000, alpha: 1).

Or take a font size. Let’s say a token with the name body is stored in JSON format as a human-friendly unitless pixel value of 18. However, for the web it needs to be in rem format (1.125rem), for React Native remain as a unitless pixel value (18), for Android a scale independent pixel (18.00sp), and for iOS, well, iOS gets complicated, stored as a unitless pixel value but accessed as part of a group of functions or other potential methods.

Now we have three formats and an alien representation for one value. What if this value changes? That’s a lot of room for human error.

Instead of storing all potentially-needed formats for all potentially-available values, an extensive and formal system was implemented to transform and deliver these design tokens to all engineers across all platforms (e.g. web, iOS, Android) and technologies (JavaScript, React Native, Tailwind CSS, etc.).

This is not a new idea and in many ways we sought to model emerging best-practices already out in the world. But as we began transforming simple values like color, spacing, and typography values we found that there were other aspects of the design system that could participate in this automated transformation process like converting SVG icons to React and React Native components (web/mobile), Vector Drawable XML files (Android), and PDFs stored in an Asset Catalog (Swift/iOS); creating a Cocoapod with each dynamic build to house the iOS tokens as well as a Kotlin-ready folder for Android with the Vector Drawable assets and other token transformations in XML; and creating Tailwind plugins to quickly and easily integrate the tokens into that CSS library as several examples.

(Note: If you glossed over that prior paragraph you’ll want to read it again!)

Style Dictionary handled the majority of the token transformations with custom processes plugged in to the workflow as needed. The end result of the transformations were platform-specific groups of design tokens that were published as packages so they could be added to development environments programmatically.

The basic transformations made the project practicable and the more advanced transformations accelerated its usefulness even more. But the true key to the success and adoption of the token transformation project across the company was the focus on developer experience.

1. First, the standard set was to document every aspect of the token system and ensure that the documentation was always up to date with the latest version of the tokens. No release ever went out without corresponding documentation.

2. Second, the delivery of the tokens was prioritized as the core part of the developer experience. Continuous integration was set up to publish controlled versions of the tokens as private enterprise packages so engineers could use any standard package manager to add them to their projects just like every other package they were using.

3. Third, a release protocol and formalized process to handle changes, additions, and removals of design token values was established and implemented with tooling to version each design token release so that versions.

All in all, engineers access the tokens directly from their code environments with ease, can reference documentation on any of the design tokens or platform setup instructions, and use design tokens with confidence knowing that any change will be managed with thought to the consequences of such a change.

Conclusion

The token transformation project brought a much-needed synchronization to the design and engineering teams that eliminated unnecessary blocks to feature implementation, reduced confusion, and facilitated a more systemitized and effective collaboration resulting in faster and better product development.