Style guides — especially living ones — are useful in many aspects of development and maintenance, so it’s little wonder that developing them has become a highly recommended and a popular practice. But even with the clear benefits, taking the necessary steps to create and start using them is easier said than done, as quite often the challenge is cultural, requiring changes in people’s mindsets.

In order to make the transition as painless as possible, equipping yourself with the most helpful tools and automating as many steps as possible become important. These living style guides promote a systematic approach to composing layouts, which used to be just a task within the user interface development process. Incorporating style guides into the development process places importance on the tools used to build the component catalogue.

Style guides come in many forms and shapes, but in this article we’ll concentrate on style guides that are generated directly from the style definition sources — i.e. CSS and its modern variants.

Time Passes, Development Changes

We used to practice the old-school type of web development workflow that starts with the designer creating a bunch of Photoshop mockups of all the pages and then handing them over to the UI developer, who then translates what he sees into HTML, CSS and JavaScript, and after some fine-tuning and checking, things eventually go into production. When a design lacked consistency, the problems with modelling grew even more complex and development started taking more time than it should have, particularly when the requirements changed.

Modifying an existing interface was the most challenging part, as it demanded actions from everyone in the chain: The designer would edit the PSD, the UI developer would change the code, and the outcome had to be meticulously verified again. Rinse and repeat. In some cases the whole user interface had to be rewritten from scratch. Adding pages to an existing website held similar problems: The team received PSD mockups of the whole interface, which then needed to be reconciled with the existing UI.

Long story short, the old-school process was difficult, time-consuming and prone to error, and it did not yield maintainable results.

Like many others in the web community, we took the “divide and rule” approach and started to modularize our interfaces. Thinking of them as sets of components instead of rigid pages increased the speed of development and made them more consistent and easier to maintain. With that, we realized that living style guides, built from the actual code, served as a much better summary than the PSD or PDF files.

Benefits Of Style Guides


“Process changes are much more profound than the technology that enables them.”

– John Albin Wilkins

The history of web development already contains examples of the ways tools and technologies can change the development process. Usually the change is indirect, as new tools shift the focus and challenge the old ways of thinking. The same holds true for automatic style guide generation: Every feature provided can trigger significant changes to your workflow when its full capacity is utilized.

Accurate Overview Of The UI

A style guide visualizes your code and represents it as a UI component toolkit. The list of components may be used as a checklist for all of the things that may have been forgotten or overlooked in the design and implementation. Being able to see each component in every possible state helps to ensure that everything is visually correct and that all the necessary states are present.

Such a UI component catalogue also serves as excellent documentation of the work that has already been done and is a good starting point for further development. Because it is generated from the source code itself and thus shows the components in their current state, any non-coding team member or customer representative can get a nice overview of the whole interface.

Development Playground

The very same living style guide web page can be used as a development playground as well. A developer running a local server can start working on a component and then afterwards tune and tweak the styles with a designer. Having each component displayed separately suits the idea of modular development perfectly and encourages the creation of independent building blocks for the interface.

This is also helpful when refactoring and especially when doing some maintenance work, because any change affecting the components and their states can be easily checked visually, decreasing the chance of something breaking accidentally.

Kickstart For New Pages

A predefined set of components aids in the building of new pages or even in the start of a fresh project based on the same code to ensure a coherent style across all products. Besides promoting code reuse, it automatically results in greater UI conformity. It’s easy to see right from the start whether the existing UI kit is enough for the upcoming page or whether some components or their states need to be implemented first. So, the time and resource needs can be estimated with greater accuracy.

Simplified Testing

Component-based development nicely reveals the power behind “divide and rule.” Even very complex systems can be developed and maintained more easily if they are represented as a combination of simple and small pieces. It also helps when testing a web interface; if something breaks, pinpointing the exact spot with the style guide is easy.

Component Culture

When developers start practicing style guide-driven development, their mindsets begin to change towards breaking an interface down into its components rather than thinking of it as a set of pages. From a technical perspective, it helps by reducing the mental context required down to the single component that is currently being developed and freeing the developer from having to worry about the rest of the system. In addition, it changes the process, giving each piece of the interface its own development cycle, which is iterated as the developer provides changes. This makes it easier to distribute work amongst the team, manage the process and even introduce another developer into the project. Who takes responsibility of updating the style source documentation required for the style guide will depend on the team’s composition, but in general it could be anyone who works with CSS, regardless of role.

It is often argued that this approach is more time-consuming, and we’re not going to disagree with that, but besides getting the application ready and deployed into production in time, one should also consider how it’s going to be maintained in the long run, and how much time and effort the maintenance will require. Nowadays it has become clear that this approach has its benefits, so if it seems expensive time-wise, it’s time to make use of the helpful tools and practices that will alleviate the pain, rather than dismiss the concept without trying.

Communication Benefits


“The roles of designer and developer are increasingly blurred, yet all too often we work in isolation.”

– Anna Debenham

With a living style guide, the whole team has the same representation of the UI, and a common vocabulary begins to emerge as everyone has a chance to watch each component evolve and to better understand its functionality and purpose. Magically, a bridge appears between the designers and developers. Collaboration usually improves quality greatly, and, similarly to pair programming, brilliant ideas and new use cases start to blossom and corner cases such as different screen sizes and component combinations are covered more efficiently.

If your designers prefer to work with graphical tools instead of prototype in the browser, you can still take steps towards the style guide-driven and component-based methods. Empower designers and bring them closer to the implementation phase by finding and providing suitable tools for them. By the time the design has been turned into interface components that are represented in the style guide, the PSD mockups will have become obsolete and making small adjustments will have become trivial.

Vision Of A Style Guide Generator Emerges

Our company in Helsinki, SC5 Online, has started the transition from Photoshop mockups to a style guide-driven process. We started out by documenting our customers’ web systems with Knyle Style Sheet (KSS) syntax and generating visual representations of them. That worked great for build-savvy developers, but in order to bring the UI developers and designers closer together we needed to find more suitable tools.

During our search we found some useful and nifty tools, but the same problem remained: Most of them were still incomprehensible to the designers, who quickly retreated to the familiar safety of Photoshop. We initially identified the following use cases as requirements for the tool:
•provide a living, always up-to-date representation and documentation of our websites’ user interfaces;
•allow us to work with all the popular style formats, such as CSS, Sass and LESS;
•be compatible with Knyle Style Sheets (KSS);
•allow us to view and search the styles related to a certain component;
•allow style definitions to be easily editable by non-technical people;
•allow us to easily find where a style variable is used;
•enable us to work with templates as well as with CSS representation;
•improve the testing and verification workflow;
•improve communication between designers, developers and customers.

We couldn’t find one, so we decided to build our own open-source tool that tackles the technical challenges, while the developers and designers strive to overcome the cultural ones.

From the technical point of view, we envisioned the generator to be a module that could be easily used in any new or existing project. So, the logical choice for distribution was to package it as an npm module, as most web projects already utilize npm in one way or another. We also felt that in order to maximize its benefits, the style guide generator should be an integral part of the project it is being used in and, thus, should be easy to embed in any project’s codebase and workflow.

Despite its young age, it has already proven to be successful. It is being used by our customers, who have provided valuable feedback and ideas and have conveyed feature needs for further development.

Overview Of The SC5 Style Guide Generator

The SC5 Style Guide Generator builds a living style guide from style source code. It provides a command line interface and both Gulp and Grunt build tasks wrapped in a single npm package. In the simplest use case, the user defines which files are to be processed and to which directory the generated files should be written.
(View large version)
The documentation syntax is based on KSS, so it can even be used in projects with bare HTML and CSS, but some of the most beneficial features, such as variable live editing, apply only to projects that utilize a style preprocessor with support for variables.

The resulting style guide itself is an AngularJS application that provides useful functionality, but your project doesn’t need to have anything to do with AngularJS. The generator does support using AngularJS directives as your component markup, however.

Installation is as easy as this:
npm install sc5-styleguide

Running The Demo

Before you start documenting your own project, seeing an example of what the result would look like might be useful, so we have provided a demo. The demo is a style guide generated from the style guide web application itself. You can check the interactive online demo or run the demo locally from the npm module’s directory:
cd node_modules/sc5-styleguide
npm run demo

This starts a local web server, which you can access at [localhost].

By Varya Stepanova & Juuso Backman
Source: [www.smashingmagazine.com]