Breathe Life Into Your Style Guide

Much has been written about why consistency is important in the experience design (XD) community. However, far less has been written about how to actually make that principle a reality on your website. We’ll dive into the basics of a style guide methodology we’ve successfully implemented with several clients that do just that. And, by the time we’re done, you’ll have reaped the following benefits:

• Consistency across all apps (in design and implementation)

• Improved maintainability (fix once deploy everywhere)

• Improved agility (presentation components decoupled from core functionality)

Additionally, the benefits above can help increase conversion while reducing maintenance costs.

Style Guides Today

But first, we’ll have a brief look at the state of the style guide in the industry:

• Here’s a list of a designer’s top 50 picks

• Here’s Google’s coding style guides

• This one actually considers build systems, but is overly-complex

Each of these has solved the problem, but for only one part of an organization. And what about our system administrators? Business analysts? Project managers? QA?

We need a style guide that takes a more holistic approach that is simple enough for anyone from any part of the organization to understand, but remains equally effective for each specialization. Unfortunately, there’s no silver bullet framework that is going to work for everyone here. The good news is that there is a tried and true methodology to creating a truly living style guide that works for your organization.

Living Style Guide Fundamentals

The guiding principle for our truly living style guide is that it must be a single point of reference—for designers, coders, sys admins, BAs, PMs, QA, even our laptops and servers. Even marketing will appreciate getting a sense for the site’s new “look and feel.” Something magical happens when you get the entire organization’s eyeballs, literally, on the same page.

Now, the technologies at play will vary. But whether you’re a Java shop, a JavaScript shop, or anything in between, you will have the same key ingredients—the kitchen sink page, page templates, code examples, build tools, automated testing, and dependencies and deployments.

The Kitchen Sink Page

This is a static rendering of all of the design components in use on any of your sites or web applications. Basically, it’s a long list of examples of any widget, whatchamacallit, or whiz-bang that you might find in any interface across your digital empire. It should also include a brief description of when/where/why/how to use it. BAs, PMs, and QA will spend most of their time here. And at this point, this looks a lot like the designer’s style guide above, but please bare with me.

Page Templates

These are also static example pages. However, they group commonly used design components into reusable layouts for fast prototyping. Armed with your browser’s developer tools, your web developers will also be able to use these for reference. Though your non-technical folks will use this when they’re diving deep as well.

The rest of these ingredients are geared for the technical folks, however they are vital ingredients to breathing life into your style guide.

Code Examples

Remember the kitchen sink page? The secret I didn’t tell you was that each design component is included twice—one is rendered, while the other is escaped so that coders can read/copy/paste the examples. Since you’re probably using a templating language, you’ll want to include the source here as well, to avoid transcription errors. Now, the developers are thinking, “Great, we have a glorified Bootstrap,” but give me just a little longer to bring the ship home.

Build Tools

These scripts are the glue that hold all the pieces together. We all know what happens if you use too much or too little Elmer’s. These will need to be able to:

1. Build the source list of components into minified static assets (bonus points for Bower packages)

2. Run your automated cross-browser tests (required for consistency)

3. Bump the build/release number

4. Build/deploy the static kitchen sink page (GitHub pages works great for this!)

5. Deploy the release to your static CDN

Testing

Testing of some kind is important in any form of software development (that’s why the degrees are called computer science). However, testing is dramatically more important if one of the goals of your software is to promote consistency. There are many tools that can help with testing software, but fewer specifically designed for UX and cross-browser compatibility. WebdriverCSS is my current favorite, even though it takes some TLC. However, the style guide use case is a little non-standard. I typically pick a reference browser (Chrome) and manually verify that it looks as expected. Then I run the test suite, which takes a screenshot of Chrome, and then every other browser, and compares the difference. Now some of these technologies are still somewhat young, so I typically give them a tolerance to avoid making them too brittle, but you at least want a baseline.

Dependencies and Deployments

Dependencies and deployments are grouped because they’re related for our use case where our style guide code is in a different repository than our application code. We will deploy our minified build target to a web server and/or CDN that will be referenced by production applications using your style guide by a URL (like http://static.example.com). However, in your development environments, you will want to clone your style guide repo alongside your application repo and have your application code pull in your local style guide as a dependency (“bower link” is very good at this). This enables you to work on the two codebases side-by-side. Finally, you can use Semantic Versioning to differentiate between breaking and non-breaking API changes with major and minor versions respectively. In the style guide’s use case, the markup is the API, so any changes to its structure are considered “breaking changes.” Segmenting your deployed release directories by major version only (not minor version) enables you to seamlessly deploy minor updates without a coordinated deploy of your application code while forcing an explicit update of your application code in order to reference major version “breaking changes.” For example, you would override your 1.0.0 style guide release’s JavaScript that lived at http://static.example.com/1/styleguide.js with 1.0.1, 1.0.2, 1.1.0, etc. However, the 2.0.0 style guide release would live at the new http://static.example.com/2/styleguide.js URL.

Ready to Create a Style Guide

With all these pieces together, you will have a way to fix presentation bugs across your digital presence without having to redeploy your application code, a reference resource to help onboard and train employees in best practices, and most importantly a single point of reference on which your entire organization can iterate.

Hopefully by now you are getting a sense for how this approach to a truly living style guide can be transformational for your organization—or at the very least contribute to increased conversion and decreased maintenance costs for your digital presence by increasing the consistency, maintainability, and agility of your site’s look and feel.

Does your organization need a living style guide? Tell us how we can help.

• Testing
• User Experience
• UX
• Style Guide