Creating Style Guides

by
Published in Design, Graphic Design, Layout & Grids, Typography & Web Fonts

Several years ago, I was working on a large, complex application. It was a bit of a legacy project: many different designers and front-end developers had come and gone, each appending a new portion to the sprawling application. By the time I arrived, the CSS was huge, the styles were varied, and it took a lot of effort to find out if anything was reusable.

Article Continues Below
Article Continues Below

During all this, I discovered style guides—a way to control markup and CSS so neither veered out of control or ballooned. In jobs since, I’ve seen firsthand how style guides save development time, make communication regarding your front end smoother, and keep both code and design consistent throughout the site. It has been a revelation, and in this article, I want to show you how to build and maintain them, too.

What is a style guide?#section2

To me, a style guide is a living document of code, which details all the various elements and coded modules of your site or application. Beyond its use in consolidating the front-end code, it also documents the visual language, such as header styles and color palettes, used to create the site. This way, it’s a one-stop place for the entire team—from product owners and producers to designers and developers—to reference when discussing site changes and iterations. Several companies have even put their guides online; Starbucks is the most well known of the bunch, but others exist.

Starbucks style guide.

(I should also mention that what I call a style guide, some people call a pattern library. Many of the guides I reference use the term style guide, but pattern library is gaining in popularity.)

When I started working at Editorially, one of the first things I did was tackle the style guide. Creating the guide was probably the most useful thing I’ve ever done when settling into a new job: it forced me to go through every single line of CSS and read it, digest it, understand how it was used, and then document it for my own, and the team’s, future reference. In addition to catching inconsistencies and errors by poring through the CSS, if I didn’t understand how certain pieces of code were being used, I annotated the guide with questions (which my teammates graciously answered).

Why should I use a style guide?#section3

As your team grows and changes over time, your style guide will help you in several ways. First, creating your guide will take some time up front, but I’ve found that this pays off with faster build times for new sections and pages, because anyone joining an ongoing project can refer to the guide for the exact styles to use.

Imagine starting a page build with information like this from the South Tees Hospital guide; a donation box would be done in seconds.

Second, a guide allows us to standardize the CSS, keeping it small and quick to load. By using the guide as an inventory of modules and code, both designers and developers can quickly see if new designs deviate from established standards, and decide as a team if it’s worth expanding the codebase or if something already written is easily extended. When you have no guide, this is impossible, which in my experience usually means that new styles are written—resulting in bloated CSS.

Third, design consistency is easier to maintain, as the designer can look in one place to reference the site’s components and ensure a cohesive look and feel throughout. This is especially helpful on larger teams and at enterprise-level companies where you may have an entire team of designers working on the site. And when design consistency is maintained, the codebase is also kept smaller.

Yelp clearly states how buttons are used, keeping button styles consistent across the site.

Fourth, communication becomes clearer as well. When I built out pages in a large-scale project and passed them off to the designer, she used the language of the various classes in the guide to ask for changes. This meant that we didn’t have any confusion on either of our parts as we sped through revisions. It also gave the entire team a shared vocabulary, like the names of modules, to use in talking about the designs once they were coded.

The final benefit I’ve found is that you can use your guide to do a quick QA pass. The guide may not be identical to the pages you eventually build out, but it can point out issues you may have in various browsers. By tackling these early on, you’ll avoid them in later testing.

Steps to build out your guide#section4

Below, I’ll take you through starting your own guide, based on my first few weeks at Editorially. (Because when I work on a project without a guide, I’m soon jonesing to make one—just ask my colleagues).

Assemble your site’s basics#section5

Start your guide with some of your site’s foundations. A foundational element may include the color palette, your grid layout system, or the basic type styles for headers and body text: whatever you feel are the very basic elements to create a page. For Editorially, the most foundational part of our site was the color guide, so I began with that and went from there. I created an HTML document with the markup, linking to the application CSS, so any CSS changes would be automatically reflected in the style guide.

When you look at the style guide created by Yelp, you can see how it starts with the basics: typography, grid, and colors, adding more patterns as it goes along.

Yelp.

Add in more patterns#section6

A pattern is any self-contained set of markup and styles to make some of your site’s basic objects, like a call-out box used repeatedly, buttons, or the way you lay out a list of links horizontally. At Editorially I documented all the variations possible of button and link styles. So go ahead and add the exact markup you need for each element to your guide.

For example, for a button in the Editorially guide, I simply put <label for="btn" class="btn" href="#">.btn <input type="submit" name="btn" value=".btn" /></label>. And because we link to the same CSS as the application does, the CSS shows correctly in the style guide. Should we change the .btn style, the style guide would change as well.

Keep going through your site and add in patterns as you see them; you may use particular layouts over and over, or a media-object pattern, or a vertical list pattern. Below is an another example from South Tees Hospital, showing some of their patterns for what they call feature blocks. Look for similar things on your own site to document in your guide.

South Tees Hospital.

This is also a good time to ask your team what else would be helpful to have in the style guide. Share it, let them take a look, and hopefully they’ll help you fill out all the patterns and modules needed. Don’t forget to have the entire team help you round it out, as it’s a resource for everyone.

Document interactivity#section7

If possible, add the bits of interactivity that your site uses, such as dropdowns, modals, or tooltips, which are small hovers with helpful text that gives the user more information. This lets your team see not just the static versions of these things, but the animations as well. So when you’re looking at the guide and hover over or click on items, they’ll actually act as they would on your site.

Tooltips in the Editorially guide.

Make maintenance easy#section8

If you have to do extra work to update your style guide when making changes to your look and feel, the likelihood of it staying up to date is pretty slim. I’ve said it a few times now, but that’s why we linked the Editorially guide to the same CSS as the application—that way, we didn’t have to manually update the guide ourselves. It can be difficult to make updating the guide a priority, but maintenance is critical. Depending on how quickly you iterate on your site or application, you should check up on the guide as a regular task, whether it’s weekly or monthly. When you’re making changes to your site, update your style guide as part of the workflow.

Iterate your guide#section9

Once you have the bulk of your site’s or application’s components listed in your guide, you’ve got a wealth of tools to make it even more handy. As I built out the style guide for Editorially, a colleague pointed out the fantastic tool by Filament Group, X-rayHTML, which is a small JavaScript library to help you build out documentation. X-rayHTML takes the styled objects on your page and generates a nicely formatted code block below them, without any further code from you. You can also add prism.js for syntax highlighting, which color-codes the code for greater readability.

A look at the Editorially style guide with X-rayHTML at work.

If you’re interested in automation, there are other tools that can make creating the guide even smoother. Two of these include KSS and Hologram. Both tools use things like commenting or YAML inside your stylesheets in combination with something like Ruby to automatically generate your style guide. It would take some work to go back and retrofit your stylesheets with the appropriate comments or YAML for these approaches, but you’d save time in the long run, as these tools make maintenance much, much easier. In addition, A List Apart has put their pattern library on GitHub and featured a blog post on its creation, demonstrating yet another method of building a style guide. The possibilities of what you can do are far greater than what I’ve outlined here; you might poke around to see what may be most helpful for you and your team.

Using the guide#section10

Phew. You’ve done all this work and you’ve created this guide, so now what? How do you get people to use it? The first step is to talk about it. If a new team member comes on board, introduce her to the guide as a way of orienting her with the site, since the guide encompasses so much of both the visual and code languages of your front end.

As long as you’re iterating on a site or application, your style guide will never truly be finished. But having something documented early on, and showing it to teammates and getting their feedback, is a huge help. Involving the whole team in building the guide also makes it feel more like the team’s guide—and gets everyone invested in maintaining and using it on a regular basis.

We’ve made the Editorially guide available as both a public repo on GitHub and online. This was very much a work in progress and an internal team document, so we’ve also got notes, patterns, and a lot of messiness. But the reason for showing it is to reinforce the fact that a style guide doesn’t have to look perfect to be useful. Despite the mess, all of this was incredibly helpful for me and other team members as we continued to work on the application.

So, are you convinced? Are you wishing you had a style guide for your site or application? It will be well worth the effort: make the time, get your team on board, start the build—and be rewarded with a document that speeds up the discussion and development of your site.

About the Author

Susan Robertson

Susan Robertson is a front end developer working with Fictive Kin who focuses on CSS, style guides, responsive, and accessibility. In the past, she has worked with clients such as FiftyThree, Imprint, Cloud Four, and worked for Editorially, The Nerdery, and Cambia Health. When not actually writing code, she can be found writing about a wide variety of topics on her own site as well as contributing to A List Apart and The Pastry Box. When not staring at a screen, she reads comics and novels, cooks lots of yummy food, and enjoys her Portland neighborhood.

40 Reader Comments

  2. Also check out my style guide: http://potatoguide.com/ Right now I’m still looking for a good solution for grid system. I’m using fixed grid system for most of my projects for the reason that fluid grid can’t maintain the consistent look and feel that I need.

  3. I could not imagine starting a new Web project without a styleguide/patternlibrary anymore. They save so much time in communication and provide one ‘canonical’ repository of both design and code. Also: with a modular, ‘atomic’ (or ‘OO’) approach to developing the various components, both developers, designers as well as content editors (even the client herself) can easily envision new website sections, making use of the components available.

    One issue with ‘static’ Styleguides is, of course, that editing these is a hassle. Soon we end up with the horror that is styleguide.v3.NEW.improved.html instead of _design.v3.UPDATED.psd.

    This is why there is a need for a simple dynamic system for generating these styleguides. I know of systems that parse the HTML in the CSS itself, such as KSS and other complete systems such as Pattern Lab

    Just today I have published a little Jekyll-based Styleguide generator at github.com/davidhund/jekyll-styleguide. It’s very beta —you should probably use PatternLab :)— but you can see an example of it at davidhund.nl/jekyll-styleguide/.

  5. Fantastic article! I am facing an enormous web redesign for a fortune 200 leading a medium sized team of designers/developers all needing to work consistently. Our existing style guide is a static document and while it has been greatly helpful, I love the idea of making the style guide a living document. This is going to make my goal of creating uniformity in code MUCH easier to accomplish!

    Thank you for sharing your experience and sparking some great ideas on how to make my project a success!

  6. Wonderful article Susan.

    We’re now giving pattern libraries to clients as a deliverable. We train the internal teams on building new pages with it and managing it for the long term.

    We’ve also created an app that allows designers and front-end developers to create, manage and search for patterns. Check out Tapestry Pattern Library App at http://www.pebbleroad.com/labs/tapestry

    Thanks again for writing this article.

  9. This article really hits the spot. For the organizationally challenged, getting all your “style ducks” in a row is one of the best ways to keep you sane.

    I had just begun to look into best practices for this topic when I found an interesting concept. Haven’t really walked the walk with it yet but wanted to add it to the discussion: Style Tiles

    http://styletil.es/

  11. @susan-

    “Style guide workflow” is something I’m sort of struggling with. Especially once one moves to “production” or a CMS. With Editorially did you have two versions of the style guide? A private one for QA/testing changes and one for sharing with the rest of the team that was linked to the app? Or did you only have one style guide where the QA use was only during initial development and then it was hooked to the production CSS once you went live?

    Thanks much for writing up your work. “Style guide” can have so many meanings and implementations. It’s good to see another 🙂

  12. @David Hund: we just used git for version control. The style guide changed continually and the markup as well, but we didn’t actually name different versions of an HTML document.

    @Dave Olsen: Thanks for the question. So for Editorially we just had the one guide and it was the one that changed as we changed the app. We iterated very quickly on the application since it was a start up in beta, so code went out daily to production. With that type of quick iteration, we just let the style guide be in sync as much as possible with the application. Does that make sense? Also, I created the guide after the application was already live, so it was built from the live CSS. Up until this article was published, our guide was not a public document, so it really was just for the team to keep tabs on what was in the application and use as a reference.

  13. Thanks Susan, now I do no need to solve a lot of things 🙂
    There is one question: How do you share a component with a UX guy to check (before you release it to the developers)?

    @Zhou Yuan: We had a similar problem with the “perfect” grid. In the end we wrote Emerald grid system. It is inline-block based (= no floats, clears or rows), fixed on most devices, and truly nestable (I am still excited about this).

  14. @susan-

    Makes complete sense 🙂 So it was more for documentation after changes happened. I read too much into the QA comment early on. To me that’s one of my big hopes for style guides. That they act as a front-end glance test suite before changes head out to production. CSS changes are easy enough to test with style guides before production… mark-up *and* CSS changes are a different story 😉

  15. @Robin: Since the style guide is available for everyone to see, you could do work on new components in it and work with the UX person to look it over there.

    @Dave Olsen: yeah, I would love to figure out a way to have QA be more a part of style guides. I mostly did QA in them when working in a waterfall style workflow, where I had all of the designs ahead of time, created a style guide to work out consistency and then did a quick QA before building out pages. But when you are iterating, that’s a different story and I haven’t really seen a great way to use them for QA in that process yet.

  16. As I reduce the amount of time I spend prototyping and designing in Photoshop, style guides have become an essential step in my design process.

    In addition to your tips, I’d recommend that version control should be a part of the living document (which is easy if you host on GitHub). If you use SASS, also include variables in the document, such as those used for colors or fonts.

  17. I’m a firm believer on that practice since I heard about it some years ago. I have been proliferating it to anybody who happened to touch the subject since then. In fact, it helped me a lot to go at the same speed as the backend developers. It means that, they could use my HTML patterns instead of crafting their own and duplicating efforts.

    While I think that static site generators is a nice thing, it may not be the “right tool for the right task”. Yet, it is better than committing to source control backend code that can be more “noise” than helpful.

    In addition, I believe that it is actually good to have a real separation between your style guide and the production code. In this way, you can have your preprocessor building toolchain, minification, tests with static JSON files, etc., as a part of that style guide. Therefore, your “living document” stays as the prime tool to use as a reference for everybody. Other point is that, production code should not take care of minifying and handling files, but merely be served as static files. The sysadmin will like your work and gladly have it served with a longer cache lifetime.

    Then, how to handle fake data without backend?
    There’s something for that, and its called RoughDraft.js. All you have to care is to add `data-*=””` attributes to say; I want you to loop `n` times, here’s a picture of AxB pixels, and etc.

    I have been using that since a while and I think it actually answer to that use case.

    Hope my comment is useful 🙂

  18. Apologies for the *shameless self plug*… But I’ve been trying to tackle styleguiding our web apps for a while.

    If you’re on a Ruby on Rails app, and use Sass, I’ve written a gem that lets you document your CSS in your CSS.

    Group and name your css, add markdown comments ‘asplainin it’s use, and add some HTML examples.

    Then, when your app renders production CSS, it strips out comments, leaving only nice minified CSS.

    Take a look. Very curious to see people’s opinions. https://github.com/markcipolla/vivus

  21. Great article! Style guides are one of the most important tool to communicate and share design across team. As other commenter, I prefer to automate the process, as keeping it a manual task could lead to outdated contents. Working with Grunt i use Sassdown for its flexibility.

  22. Thanks for the article Susan. Any evolving project should start with this step, it saves a lot of headaches in the long term. My first time as a Lead I quickly learned how quickly a project can fall apart without this essential step when you have multiple developers on board.

    SASS has been a great tool in refining that train of thought as it allows components to be extracted into their own files. I set up my main SASS file almost as a table of contents for my style guide and then list out components from there.

    @Marco Solazzi Thanks for the link to Sassdown! I’m definitely going to check that one out!

  23. We’re using the same practice with maintaining living Style Guides of our Front-end at OK.ru social network.

    Also, we have developed an open source engine/environment for developing new front-end blocks directly in our style guides – http://sourcejs.com.

  25. Susan, I would call this more a ‘technical documentation’ and not a style guide. Although, this naming convention and form of document has been used many times before, I believe it’s useless (it’s basically an illustrated CSS document). A ‘brand style guide’ should be made up of three parts at least: That is brand, brand communication and UX strategy. It must demonstrate how a product -or- brand communicates with it’s users visually, but also strategically …. and -not- just how building blocks are being built. Here is a great example of this: http://www.slideshare.net/MosBar/digital-branding-for-t-mobile-2

    Here is another example of elements used for a Brand Guide: https://www.behance.net/gallery/Design-Patterns-for-Live-Services-at-EA/3749587

  26. I’ve been working with style guides and pattern libraries for almost a decade, and I’m happy to see the concept has been rising in popularity in the last few years. In the past style guides were mostly designers’ tools and it was difficult to see how they could fit also in the developers’ process. Adding markup & code and making the style guide a living and lightweight document helps you get developers on board too which is the key to integrate the usage of style guides in the whole UI design & development process.

    There are a lot of style guide generators mentioned here. I thought you and your readers might be interested in an alternative tool for creating and sharing style guides and pattern libraries: Patternry. Patternry is a cloud based tool and it allows creating both “traditional” pattern libraries and live style guides. Let me know if you’d like a license for evaluating it properly.

    Thanks for a great article!
    -Janne

  31. Great discussion. Most everyone here seems willing to dive into the code to create great style guides. It’s always a balance between infinite control of coding from scratch, and the time/capabilities of a publishing system

    If any designers or coders are eager to have customizable way to create style guides like this one (http://publet.com/awesomebrand/) without getting into Git, let me know if you’d like a beta invitation to create HTML5 style guides with Publet (http://publet.com/). Basically: sign in, add text/images/video/audio, and style it. You’ve created a unique URL with a responsive style guide (and a downloadable PDF).

  33. I have been using style guides for many years. The biggest problem with them in my opinion is convincing a customer that they need to pay extra for this valuable service. I usually include one for free to avoid this.

  35. Thank you Susan for the well structured and reasoned article. In my opinion, the term “style guide” has it’s origin in design related work and “pattern library” is mostly used by developers. I assume, that most of the time, people don’t talk about the same thing when using either of these two terms. Nevertheless, I agree that it is very useful to have digital/interactive & living guidelines, especially the ones, that make life easy for frontend developers 🙂
    If you some day have a bit of time, you could take a short look at Frontify. We’re trying to bring the designers world together with the one of the frontend coders by connecting “styles” and “patterns” in one “design guideline” platform.

  36. Thanks for the great article Susan! My company is just getting started with a style guide and I’m interested in doing my own alongside for my freelance projects. This was a great intro article and I’ll be checking out your style guide on git for sure. Also I thought referring to your new employee as a she was a nice touch 😉

  37. I was not considering style guides in my workflow until I read this article. I now see the importance of building and maintaining one especially if building a WordPress theme. Time to get on-board. Thanks Susan!

  38. What a great article! There is an online tool that facilitates Style Guide creation if you want a hosted solution. Cleaved is in it’s early stages, though right out of the gate looks pretty good. https://cleaved.com/

  40. Pingback: A List Apart ? 393: Inventing & Documenting Design Patterns - Zeldman on Web and Interaction Design

Got something to say?

We have turned off comments, but you can see what folks had to say before we did so.

More from ALA

I am a creative.

by
A List Apart founder and web design OG Zeldman ponders the moments of inspiration, the hours of plodding, and the ultimate mystery at the heart of a creative career.
Career