AWS Open Source Blog

Style Dictionary: An Open Source Tool for Building Customer Trust Through Design Consistency


“Leaders start with the customer and work backwards. They work vigorously to earn and keep customer trust.”

These are the first sentences of Amazon’s Leadership Principles – which, yes, we really live by as a company. Everything we do starts from an expected customer benefit, and we work continuously to earn customer trust across every touchpoint.

How can user experience design benefit customers and help earn their trust? Danny Banks, a senior UX designer at Amazon, cites Jakob Nielsen: “Consistent experiences create trust in the organization. Each interaction is part of the overall user experience with a company. If the user experience isn’t consistent across channels, users will question the organization’s credibility.”

“Throughout my years designing, I’ve seen a lot of organizations have problems with creating consistency across apps and platforms,” says Danny. “Details really, really matter. Customers don’t know why something looks good, but they know that something looks good or bad. Small blemishes and inconsistencies – colors that aren’t exactly the same, spacing that’s off by a pixel or two – may not seem like a big deal, but they add up to design dissonance: the feeling that something isn’t quite right. As UX designers, it’s our job to notice that, and to fix it so the customer doesn’t see it.”

Danny works on design for apps that need to look consistent across desktop browsers, iOS, and Android. The typical workflow started with a product manager coming up with a feature or improvement to an app. A UX designer would work with them to decide how to design and build the feature in the app. The designer would then create a design in Sketch, and work with the product manager to finalize it. The final Sketch file would be handed to development, along with a business requirements doc for the feature.

During coding, developers would have to come back to the design team to ask for details on font size, background color, etc. In the fast-moving, DIY culture of Amazon, some devs would take shortcuts, such as using an eyedropper tool to find the hex value of a color, which could lead to colors being slightly different. These values, as well as other attributes of a UI component, would need to be hand-copied into the code in dozens of places for each feature – another vector for inconsistencies to creep in.

An obvious improvement is to work in Sass. It permits the use of variables for design attributes, which Sass can then compile into standard CSS. But Sass only solves the problem for web pages. iOS and Android development tools each have their own methods to create style variables and specify style values for those variables (e.g., iOS uses RGB decimals for colors, Android wants hex). That’s a lot of detail to manage and, as the vision for Danny’s team states: “We hold ourselves accountable to get these details right.”

Jeff Bezos has famously said: “Good intentions never work, you need good mechanisms to make anything happen.” With a strong background in both front-end development and design, Danny saw a way to solve the larger problem of design consistency, and he was given the opportunity to do so: “My manager is awesome, and encourages projects like this that aren’t necessarily part of our team’s roadmap.”

The result is Style Dictionary, a build system for creating cross-platform styles.

A Style Dictionary allows you to define styles one time, in a way that any platform or language can consume. It provides a single place to create and edit styles, and a single command that exports these rules to all the places you need them: iOS, Android, CSS, JS, HTML, Sketch files, style documentation, etc. Written in node.js, it is available as a CLI through npm, but can also be used like any other node module if you want to extend its functionality.

Danny chose to develop Style Dictionary in node.js “for familiarity and ease of development, mostly. node.js has the benefit of fitting in nicely with web build systems like Grunt, Gulp, and Webpack. With React and React Native, we are seeing node.js start to make its way into mobile development as well. But you can also use Style Dictionary as a CLI tool, without writing any node code at all.”

The project includes an easily extensible template and formatting system that can be used to bring Style Dictionary to systems beyond desktop, iOS, and Android: “We don’t know exactly how everyone will want to use style dictionaries in their project, which is why we made it easy to create custom transforms, templates, and formats.”

Charles Dorner is a Design Technologist in another part of Amazon. He saw Danny’s presentation about Style Dictionary at an internal summit, and asked: “Could you put this out into the wild, so that it’s open and available? This is something that, in my experience, is missing from the outside development world.” Charles wanted to make sure that everyone had access to a simple tool for ensuring that styles were accurately reflected across platforms.

As it turned out, it was not difficult to release Style Dictionary as open source: there’s an internal process in place managed by the Open Source team. There weren’t many Amazon dependencies in the code, so not much effort was needed to clean up, add comments, and put all the files in place to make the project open source-ready. Then the GitHub repo was made public, and the package was made available via npm.

Style Dictionary has changed the design workflow for Danny’s team. Developers don’t need a pixel-perfect mockup, Sketch file, or design doc – just a wireframe and components, and the Style Dictionary values for those components. New font sizes or icons can be added to the dictionary at any time. For most projects now, Danny doesn’t even open Sketch or Photoshop. With Style Dictionary, it’s easy to generate real apps to test, instead of using mockups. Style Dictionary can also be used to automatically build and update style documentation.

Style Dictionary was released on GitHub in the summer of 2017. Danny and Charles continue to work on it, and would love to have your input and contributions.

“The most important next item,” says Charles, “includes the ability to import from existing styles, e.g. CSS or Android, and import and export from Sketch for designers. We want people to submit requests for new functionality that would empower them in their existing workflows. Maybe we should build an editor as well. In general, we’d love to have more users filing tickets, making contributions, and providing feedback and ideas for additional features.”

Do you have a design consistency problem to solve? Get Style Dictionary here!

Deirdré Straughan

Deirdré Straughan

Deirdré has been communicating about technology, and helping others to do so, for 30 years. She has written one book (so far); edited two more (so far); produced and delivered technical training; produced hundreds of videos and live streams of technical talks; written, edited, and managed blogs; and managed events. She has been applying this skill set to cloud computing since 2010, and to open source for even longer. She joined AWS in 2017. You can find her at @deirdres on Twitter.