Living Design System

An approach for delivering a consistent design cross-platform.

Scaling a design across all form factors and platforms has become the new challenge in the software industry. From watch to phone to tablet to desktop, teams must also consider iOS, Android, Win8 and HTML5 implementations. Opinions on native vs. HTML5 aside, most companies use a mix of both to balance the best user experience with time to market and reusability cross-platform.

So, how the heck do you apply the same design principles to a heterogeneous environment like this? And even more importantly, how can you keep changing the design in the future without causing major work for the development teams?

Design Tokens

At Salesforce we face this very challenge and we came up with an agnostic solution: we define our design in a single location and use a system to cascade it down to all platforms. We call it our Single Source of Truth. It’s basically a set of JSON files which contain name-value pairs describing our design tokens. These tokens are of different categories like text colors, background colors, border colors, font sizes, spacing, border radiuses, etc. The Salesforce1 Design Tokens are open sourced on GitHub.

To translate this raw JSON data into a platform specific format we have developed Theo. Theo is built on top of Node.js and the code is open sourced on GitHub. It is published as an NPM module so it can be easily used in a Grunt or Gulp script or executed via command line.

Theo generates different output formats like variables for the common CSS preprocessors like Sass, Stylus and Less. But it also generates an XML version for Android or a JSON version for iOS. Within this process it’s transforming the raw data into a format which is compatible with any platform. Colors, for instance, might be hex values for CSS preprocessors but are RGBA for iOS and 8-digit hex values for Android (#AARRGGBB). Units for spacing and font sizes, as another example, are converted to px, em or rem for web; iOS gets pt (points) and Android gets sp (scale-independent pixels) or dip (density-independent pixels).

So what makes this a Living Design System? We store our Single Source of Truth JSON files in a Git repository. This Git repository can be integrated into the build process, which points to a branch or tag. So when you build your web application or a native mobile app, the design tokens are being pulled from Git via NPM. Run Theo and build your products on top of what Theo generates.

This workflow allows designers to modify design tokens without necessary reaching out to a developer to implement them. This leads to no more emails like: “Hey, can you please bump up the font size from 14px to 15?”. Developers must use the design tokens and not hard code values anymore, as a best practice. Hard coding makes future design changes extremely tedious and does not scale. With the design system in place, you get true consistency across all your various platforms. Just imagine you have a product with versions on the web, iOS and Android and you want to change the color across the board.

Changing design is now as simple as editing the value in one place, your JSON file. You can create a new version or tag in your Github repository. Then the development teams have their projects point to the new tag. This beats tracking down developers for affected areas and hoping they find all occurrences.


Design tokens defined in JSON and Theo only make up a small part of a design. There is also management of assets (icons, fonts, graphics, etc.). At Salesforce, we manage these in a Git repository as well, which gives us versioning, commit messages, branches, and other useful history. Our raw data in this case are mainly SVGs. We developed another Node.js script called Blender to rasterize the SVGs to PNGs as a fallback. The way it works is that we use a bunch of NPM packages which use Phantom.js under the hood to display the SVG in the headless browser and then takes a screenshot to rasterize it to a PNG. For more information please read the instructions on Github.

Living Style Guide

For documenting the design tokens and an overview of available assets we have sections in our Living Style Guide. This part of the Style Guide is totally dynamic and basically a front end for the design tokens and assets checked into our Git repositories. The Style Guide points to these the same way a development team is actually consuming it. This way it’s also easy to create multiple Style Guides for each version of your product(s).

What’s next?

I really hope that our workflow and tools might help others. I would think that many teams face very similar challenges. Both, Theo and Blender, are open sourced and contributions are more than welcome. Whenever fragmentation increases due to new hardware or new software we will try to update the tools to streamline the workflow. The important thing that matters is that there is a manageable Single Source of Truth around the design tokens and assets which accommodates all needs. The tooling on top is designed to eliminate all manual steps and to hide the actual implementation details of either platform.

For any feedback please ping me on Twitter (@soenkerohde) or create an issue on the GitHub repositories.

Follow us at @SalesforceUX.
Want to work with us? Contact
Check out the
Salesforce Lightning Design System