← Back Home

Creating a Styleguide from Scratch

More than just rules about style, a good styleguide paints a picture about where a brand is headed, especially if you are redesigning. The more context designers provide as to where, when, how and why a particular style should be used, the less confusing it will be anyone who ends up needing to understand a design concept down the road.

Engineers traditionally have the most to gain from these guidelines, but creating a clear and concise style guide will help other designers have less confusion about a how a particular component / style should look and behave. It is also beneficial for product managers and anyone who is dealing with the overall strategy of a brand or product to see how we speak to our users via our interface. How do our users know what they should do next? How do they get more immediate information?

Inconsistencies are Hard to Maintain

One of the biggest problems in modern application design, and especially when you work at a company driven by data, is the problem of consistency. In the current suite of products I am designing, I concurrently work with 4-5 different squads, each of which have their own goals and user types. We have identified at least 6 very different users, who are spread out between squads. It is complex.

No matter how organized we are, there always seems to be someone who gets left out, whether that is a particular type of user, or even up to an entire squad or business line. Because of this complexity, creating a visual language is challenging. One of my overarching goals is to keep the style guide as small and consistent as possible, and to only add a new component once there is a specific need from more than one party. This way, every component ends up being used at least twice, and is therby doesn’t fall under the definition of custom element.

Oh yes, these buttons will be consistent across our products.

What We Did First

Being there was no legacy styleguide, I started by cranking out a number of designs for a bunch of different views of the application with Sketch. This was a good first step, because it allowed me to be a little creative, and simultaneously affect the UI and branding elements. We did some testing of both company and users to find some basic preferences.

A quick look at the old app on the left verses the new look and feel on the right.

Next I created a high fidelity prototype of these pages and shared them with stakeholders. We received very positive feedback, and after a few more iterations the team felt confident that this was the correct direction. It was time to dissect the individual components from the designs and put them all on a page

A few elements from the Sketch file.

Transferring Ideas To Code

We had a great start, but to make these concepts useful to the entire organization, we needed to present the styleguide as a living document. I took the concepts from the svg style guide and translated them to a code version which was then hosted on a CDN. It also pulled the CSS from our current live application, which is nice because it meant we had reached our goal of creating a living styleguide.

This first version uses Styledown a markdown based styleguide generator.

It was very useful in portraying the vision of the redesign to everyone, especially for those teams who were working to reduce the number of diffs through the applications.

The biggest use was that of debugging the CSS. Because we had all of the elements on one page, we could easily demonstrate the issues that come along with the cascade.

This first version of the styleguide was immediately useful to most everyone, but it was obvious to me that this was a stop gap solution. To get a styleguide that was truly powerful, it would need to be included in the actual build process of the app. It needed to eventually turn into a pattern library.

What I Learned

It is very easy get out of sync if you aren’t paying attention. I think there are currently too many variables that make this current styleguide somewhat unstable.

If an engineer is unaware that there are existing styles and then creates his/her own solution, it could potentially carry over to other parts of the application.

If a designer doesn’t understand the intended UX of a particular element, their designs weaken the system as a whole.

Maintenance is slightly painful. I really enjoy working on style guides, but when updating or adding a component, I have to manually change a few files and then update the version on the CDN.

Research is crucial, it is important that I continue to ask questions, such as who will be using this style guide? What do they need to complete their tasks? Are there other groups that could benefit from this information?

Version 2: The Future

The immediate future of this version of the style guide is to make sure that is portable and shareable. Creating a github repo would be a good first place to create a history. Also, the application's CSS files have become programmatically versioned, which means we need to update our current styleguide to keep in sync. This is a little tricky because the current styleguide lives outside of build process.

The bigger future goal would be to use React as our main source of style guiding. Currently, 1/4 of our products are using React, but that number is projected to go higher. When we hit 50% of React based products, it will be time to use React to render our styles for us during the build process.

This is better for a lot of reasons, the most important being that the styleguide will always be in sync because it will only render available components. This would be nice for me personally because I could spend less time implementing the style guide and more time crafting the language of the design system.

The first inklings of the React Styleguide.

Check out another case study:

The Orchard Mobile Analytics

Vice News Android

Styleguide from Scratch

Waka Flocka Rebrands

Intel & Wearables