Style Guide Driven Development

Below is the transcript and supplement to my WordCamp Philly 2015 talk on Style Guide Driven Development.

Link to Slides:

I like working fast and I like working efficiently. My ideal work environment is that of a continuous deployment model where there are tests and metrics and reporting for nearly every aspect of a team’s day to day.

I like defined processes and workflows and tooling.

I like when those processes and workflows and tooling are under constant scrutiny and refinement.

I like to be rigid but also flexible. This means that I like to be rigid to a set of ideals so it’s possible to test if those ideals are working or not. Then to be flexible to be able to pivot and attempt something different.

Dev Ops culture has had a lasting impact on our industry in this way. Metrics, testing, monitoring, etc are now conversations we are having at all levels of the stack.


Test driven and behavior driven development are now standard practices in the dev community. And we as designers and front end developers can utilize these practices in our own level in the stack with style guide driven development.

CSS and HTML are often viewed as fleeting and disposable. Without proper foresight, documentation and planning, refactoring HTML and CSS is much like test driven development where all development begins within the test framework. So too should our HTML and CSS begin in the style guide.

How did we get here?

Responsive web design was a paradigm shift in our industry. It was in response to the explosion of screen sizes that were coming into the market with smart phones, tablets, etc. It was no longer feasible be able to maintain separate code bases for each new devices that presented itself.

Along with the advent of RWD came changes to processes as well. The post-waterfall, post-Desktop, post-PSD era of building websites.

Ideals like Mobile First Design and Style Tiles challenged the status quo. Both concepts seek to move away from presenting high fidelity homepage desktop designs to the client in static Photoshop files, and move to something more independent to lay out.

Agile processes push us further away from the old methodologies of being handed a completed “final” design folder from the design team. As we all know that word “final” is rarely ever that.

Components and Style Guide Driven Development

Modular, extendable, reusable, flexible. These concepts are at the core of components and components are that the core of Style Guide Driven Development.

Websites are not pages. Websites are complex systems of modular components architected together to build cohesive user experiences in order to deliver content and achieve goals.

Picture a chair in your head.

This chair that you now have in your mind has certain properties that make it a chair. It probably has a certain form, that makes it distinct from other things like a table or a cat.

Now let’s imagine a button. Much like the chair, it has its own form that makes it distinct from a paragraph or a heading. You may begin to think of how it functions and its interaction characteristics as well.

Let’s code that button.

As you can see, the button has some properties that make it what it is and separate it from what it is not. This is a component.

Now let’s say we have a page with several buttons on it, let’s say it’s a multi page form. We need a way to separate the buttons that moves you forward in the form from the button that clears the form. So we need to introduce some modifications to our original button component.

Now we have two buttons that are both very similar. In fact, the “primary” button inherits from the original button, but it serves a much different purpose.

This is Style Guide Driven development. Creating components, documenting their use and purpose, and testing their utility within the UI.


Let’s take a look at some examples

These first two style guides are for sites I developed as a freelancer for Ink and Mortar, headed by Sharon McMullen in Philadelphia.

This was a redesign of the Ink and Mortar portfolio site. The buttons at the top list the different components and sections of the style guide.

Separating the style guide into different sections allows you to more easily focus on one area at a time. These sections also more closely mimic the structure of my Sass files.

Each of these sections of the style guide also act as a unit test for the components and styles of the site.

WordPress offers theme developers sample data for unit testing as well. The sample data includes various user generated content that is possible within the CMS. Galleries, image alignments, and different lengths of text strings attempt to break your theme forcing you to write improved code.

I’ve borrowed some of this sample data from WP Test and added it to the style guide so I’ll always have it, even when I’m off system.

Now, whenever a change is made to the CSS, we can easily go through each section and make sure these unit tests pass and other components weren’t unintentionally affected by our change.

Finally, the style guide acts as documentation for the website owner as well as future developers. If new content is created, the style guide can be referenced and components can be chosen to present that new content that will be consistent with the rest of the site.

This next Ink and Mortar site was for a local Philly seamstress, photographer, and blogger named Madalynne.

I had a really big win recently with Maddie.

She got inspired by a grid layout on another site and she wanted something similar for her own.

Her next step was to reference the style guide and begin to draft out her idea in the WYSIWYG.

What she was tried was the grid layout, but the text wasn’t wrapping around the images like she wanted it to.

Next, we tried the alignment classes that WordPress provides for us, but the images she wanted to use were too large and were preventing the text from wrapping.

Lastly, we ended up utilizing the classes from the grid component in combination with the alignment classes to finally get what she wanted.

Based on the content and images she had, I needed to help her with some minor HTML changes, but she got most of the way from concept to implementation all on her own with the help of the style guide. And throughout the troubleshooting process we used the style guide to communicate and view different examples.

Lastly is my favorite style guide. The Lonely Planet style guide.

One of the biggest challenges when working with a style guide is keeping it up to date. With a living style guide, the CSS is shared by both the application and the style guide. However, if the HTML of the component needs to change, the style guide can easily be overlooked.

Lonely Planet’s solution to this problem was a layer of abstraction for their HTML. The templates they use accept data and format that data into HTML. These templates can be used anywhere in the application including the style guide.

Now anytime they want to update a component throughout the entire site, they can do so in one place and it will be updated everywhere.

Another strategy for keeping your style guide up to date is to use a style guide generator.


There are several options out there. Some run on node, some on ruby, but their syntax and implementation are largely similar. Most use the KSS syntax.

KSS is formatted comments at the top of your CSS file. The generator will then parse these comments, and generate your style guide automatically.

You can also tie the style guide build process into an automation tool like Gulp or Grunt, or some custom shell script.

So now we have a development guide/playground that will be generated from the comments we write, and this process will run occur in the background with from our automation tool. Now what?

The answer to that is, keep going. Documentation is rarely ever done and hard to complete. Starting documenting the style of your code and the logic behind them.

Like me, if you’re using a combination of OOCSS with BEM, document that, explain how to maintain that style, and why that style is important.

Linting and Editorconfigs are also an important item to cover. Ideally, a new developer that opens your code should know exactly what goes where, and you should make it hard for them to fail.


Some great examples for this level of detail are CSS Guidelines and Sass Guidelines. Adopting these guides outright might be a good way to put an end to internal arguments regarding white space and style.

In the WordPress space, 10Up did a great job documenting their guidelines as well.

If you’re not familiar with 10up they do some really great work around the community. Check out VVV for local development environment as well.

Traditionally, brand guidelines for large well known companies are all encompassing. They define what colors you should use when, grammar styling like oxford commas, even how mascots would react to certain scenarios.

MailChimp has a great style guide and they provide examples for what their mascot, Freddie, would say to their users.


The pinnacle of everything that I’ve gone over thus far and what I strive to achieve is Google’s Material Design.

In the end we’re building a visual language to interact with our users. Keeping that language consistent and predictable is critical in creating a great user experience. Style guide driven development can help you achieve this goal.

Thank you.

posted in: Community, design, Front End Development, WordPress
tagged: , , , , ,