ClassPass’ Design System
A couple of months ago we launched a total refresh of the ClassPass brand. Today I’m going to talk about some of the technical implementation details, but you can read more about the motivation from our Creative Director here.
To enable our developers to adopt this design system we turned to an open source tool called Theo, written by the good folks at SalesForce. It allows us to define our system as a single set of “tokens” in JSON or YAML format, and then generates source code for multiple platforms. It generates CSS stylesheets for our website, Swift code for our iOS app, XML resources for our Android app, and JavaScript for our React Native codebase (shared between our iOS and Android apps).
Let’s walk through an example of getting set up with Theo. It’s written in JavaScript, so the first thing we need to do is create a package.json file and add Theo as a dependency:
Next run npm install to install our dependencies locally.
Then we can create a YAML file defining some shared tokens; in our example we’re going to use colors:
Now that we have our tokens we can start generating platform specific code. Our web frontend uses SCSS, so let’s add a script to generate SCSS variables to our package.json
Now we can run npm run web and see the results in colors.scss
Now it’s time to go cross-platform! Let’s add another script for generating some JavaScript, and one for generating for all platforms.
Next we runnpm run all and colors.js will contain some lovely JavaScript that we can use in our React Native codebase
Theo has lots of “transforms” that help with converting font sizes between pixels and points, and colors between hex and rgb, and with lots of “formats” like .scss, .sass, .xml and .json. It’s also very extensible and allows you to write your own custom formatter. At ClassPass we use this to generate Swift source code for our iOS app.
To do this we first need to give Theo a JavaScript module to run at setup time that registers our custom formatter. Let’s put this in a new file calledsetup.js
Now we need to tell Theo to run this module before running transforms on our tokens. To do that we instruct Theo using the--setup parameter (upstreamed by our design team) so our iOS entry in package.json will look like this:
Let’s start fleshing out our formatter. We want to generate an extension on UIColor to make things as easy as possible for our iOS developers.
Here we have set up the boilerplate for our UIColor extension, next we need to figure out how to populate our colors array. We can do this using the result parameter passed into our function. It’s an Immutable.Map of the tokens we defined in our YAML, and we can pull data out of it like so:
However, this just prints out the raw hex codes into our Swift file, instead we need to convert them into UIColor objects. To simplify color conversion we’ll use a library called tinycolor. Once we convert our color into its constituent red, green and blue parts we can then transform it into a Swift color literal:
This gives us some output that looks really great in Xcode:
Now that we know how to write our own formats the possibilities are endless. For example, as we were migrating to our new branding we began to deprecate some old colors. Our system is codified which allowed us to map a deprecation warning in YAML…
…into a deprecation warning right in Xcode with a handy “Fix” button!
As stated in the beginning of this article, our underlying goal is to create a design language shared by developers and designers. We looked at how Theo can help integrate the design system in our code. Theo also helps us generate our design documentation from the same token files. To do that Theo outputs a JSON token dictionary that is consumed by Jekyll, which in turn generates a static website that we host on Github Pages.
We’ve really only begun to scratch the surface of what we can do with our design system, we’d love to hear your ideas and talk to other teams working on similar projects. We truly believe that this type of tooling can help bring designers and developers closer together and enable us to build better products.
The example code from this article can be found at https://github.com/classpass/design-system-example
