The Journey to Design Consistency

From creating a static UI Library in Sketch to implementing a living pattern library in React.

Mason Lee
6 min readMay 16, 2017


Preparing for redesign

With multiple product teams building UI for different applications, maintaining consistency between products isn’t easy. Ever since we shared our design team’s process of creating a UI library, we have made significant progress and we’re in the middle of collaborating with different teams to redesign all of our applications. Although our product teams are usually looking to the future, us designers managed to work a retroactive redesign into the product roadmaps. In here, I’d like to share what we’ve prepared and learned along the way before pitching the idea of application redesign to the rest of organization.

These are the steps that led to our redesign:

  • Create a UI library in Sketch
  • Write new base stylesheets
  • Upgrade our React UI components to a new design
  • Build a pattern library site

Sketch UI Library — Setting the groundwork

As we shared in our previous article, we’ve built our UI library in Sketch and it allowed us to achieve the following:

  • Talking about UX debt more seriously — We have talked about UX debt internally for a while but it wasn’t clear to anyone how to tackle this. Now that we had visual guidelines of how our product should look in the future, we could actually talk about it more seriously and come up with clear next steps.
  • Everyone started using Sketch — Previously, our designers were using different design tools such as Omnigraffle, Axure and Sketch. We can now ship faster by putting existing components together while spending more time solving real problems surfaced by our users.
  • Achieving design consistency between designers — Since we now share the same source of truth UI library in Sketch, our designs look more consistent than ever before.
  • Designing for bigger scope — When we are designing a new UI, we distill an interface into a set of atomic pieces. When there’s a new component, we consider different contexts and requirements in order for the component not only solve a problem in one product but in other products as well. It pushes the boundaries of our design feedback since the scope is larger now.

In the end, the UI library laid a groundwork to actually achieve consistency in different products.

New Base Stylesheet — Transfer design in Sketch to SCSS file

Our engineering team has an internal project of building a UI library in React (codenamed “Rollup”). One part of Rollup is a set of base styles that all of our React UI components and applications inherit from.

Since the shared base style component was first created for our new reporting application project, it didn’t have enough styles defined for other applications to use. For example, styles for form elements, modals and spinners weren’t defined, which resulted in each Rollup component and applications adding their own custom styles of those elements that should have been added to the base style for applications to share.

Once we had a clear visual direction to the future of our UI components, our next step was to actually transfer them into SCSS files in our base stylesheet component to make it scalable and robust. Before writing any code in SCSS, we focused on getting two things right: coming up with legitimate SCSS variable names and a file structure that goes along with our modular approach to UIs.

Below is an example of our SCSS variables:

Our SCSS variable names not only represent function and purpose but also have a good convention that makes it easy to use these variables.

“The color that gets applied to the background when there’s an error.”

For example, having this convention makes it easy to find a color variable by narrowing down the specificity of the variable names.

Our designers share the same SCSS variable names via shared style names in Sketch. It helps communication between engineers and designers.

We also introduced a new folder structure that mimics pages and artboard structures in our Sketch UI library:

Having a modular structure for SCSS files allows us to consolidate each element’s style in one place and it’s a scalable solution as the style file gets larger.

React UI library — Make React UI components to work with new stylesheets

We needed to come up with a way to make UI components work with new stylesheets while not breaking the current style.

Supporting both styles gave our application teams a chance to upgrade to the new base styles at a time that’s suited to their roadmap.

Luckily, we could use if .. else statement with SCSS. We’ve defined a new variable called $ar-style-base-version: 1 in the legacy version of the style base package and $ar-style-base-version: 2 in the new base style component. And in individual UI component stylesheet, we separated out UI component styles using if .. else statement like following:

This allowed us to look at our React UI components with two different styles.

For complete technical detail, when we included these conditional styles, we also modified the npm peer dependency for these components to indicate support for both v1 and v2 of the style base package.

Running our date picker component with 2 different styles

Pattern Library Site — Documenting and assembling a reference site of our patterns

Once we upgraded all of our React UI components to a new design, we put together all of them into a site, forming a living pattern library. By documenting and assembling a reference site of our UI patterns, we were able to speed up our process and solve some internal communication problems.

For example, each component section has a deep link that can be used for context in issue trackers and when talking about specific components.

Example JIRA ticket

An internal version of the pattern library site has a documentation for the options developers can use for React components.

A table for React props

This project helped different teams to build apps more consistently and let each team focus more of their energy on solving usability issues in our products instead of writing stylesheets to implement UIs that match the specs from our designers.

Check out our pattern library site here.

AdRoll is hiring! Check out all of our open positions here.



Mason Lee

Product Design at Facebook