Summary: The process of building a living style guide can help you refactor your prototype code in preparation for hand-off from designer to developer.

Designing a new product is a very iterative process, evolving from wireframes to interactive prototypes. The process of rapid prototyping is extremely beneficial however you can be left with a Prototype UI that is hacked together under the hood. Although this is the best way to get to where you are, you are now left in a predicament - what is the best way to move forward? How do you transform your prototype into clean and tidy markup ready for the development team? When designing our new Analytics product I discovered building a living style guide, at this stage in the process, to be a solution worth considering.

First things first, what is a Style Guide?

Some style guides simply outline the aesthetics of an interface - design guidelines, colour palette, typography etc. However, I also wanted to address behavioural and technical specifications by creating an interactive living document linking to the actual application’s CSS. It’s a space for the designer to define and consolidate all visual styles, interactive components and corresponding markup / styling.

Fig. 1: Specifies the Poppulo Analytics colour palette, with .less variables, hex colour codes and associated CSS helper classes.

Fig. 2: An interactive example of the wizard component used in Poppulo Analytics.

Benefits of Creating a Living Style Guide

The advantage of having a style guide is obvious but when built at the right time the advantage can be twofold:

  • One obvious advantage is that it defines the style and provides the foundation and building blocks upon which the UI can grow. It works as a point of reference for designers and developers. It ensures visual and behavioural consistency within the interface and expresses a shared understanding amongst the entire team.

  • Secondly, I used the process of building the style guide as a tool to refine and refactor my prototype code. Building the style guide helped provide a smooth transition between design and development. In turn, the act of building the style guide at this stage in my workflow became a very beneficial step in the design handover process.

Using a Style Guide to go from Prototype to Production

At first I went back through the early prototype attempting to refactor the code, but I found this approach to be inefficient and above all inaccurate. Building the style guide from scratch forced me to pick apart each individual component and attempt to reproduce it in its simplest form. By the time I was finished I had identified any issues in the code and fixed them along the way. It helped me to create markup that is a lot more reusable, maintainable and extendable. In a single exercise I not only began the work on a living style guide but produced a lot cleaner markup, now ready for hand-off to the development team.

Tools to Help Building a Style Guide

I decided to add in this last section because I found myself confronted with an array of tools. A lot of the automation tools (like KSS) are quite cool but would not have helped me refactor my code. After some experimentation I also felt they would be too restraining and unnecessarily bloating my markup. The most important thing is to decide what kind of style guide you are building and what you want to get out of it before jumping in and committing to any particular tool.

For this particular project I found it lot more flexible and beneficial to simply create a HTML document and insert my sample components. There are many resources out there to help you even when building a style guide from scratch. I would highly recommend the following:

X-rayHTML automatically generates code snippets. Simply wrap your HTML source code in a div and X-rayHTML will insert the code snippet under the component on your style guide. This gives everyone easy access to reusable source code and allows you to show both styles, behaviours and code all in one place.

Prism.js is a syntax highlighter. Used on top of X-rayHTML it makes the automatically generated code snippets easier to read and follow.


When built at the right time the advantage of a style guide can be two fold. Firstly, it acts as a source of truth for the UI and ensures design consistency. Secondly, even if you don’t maintain the style guide in the long term the process of building it can be a vital tool in helping you refactor your prototype code in preparation for production and ensuring a smooth hand-off from designer to developer.