Creating Style Guides

by Susan Robertson

34 Reader Comments

Back to the Article
  1. I’m neck-deep in style guides right now. Regardless of how big or small, a style guides is a vital component of your website. I’ve found the Barebones template a useful jumping-off point. https://github.com/paulrobertlloyd/barebones Thanks for this great write-up.
    Copy & paste the code below to embed this comment.
  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.
    Copy & paste the code below to embed this comment.
  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/.
    Copy & paste the code below to embed this comment.
  4. David, I would check out pixelapse. Or do versioning through git.
    Copy & paste the code below to embed this comment.
  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!
    Copy & paste the code below to embed this comment.
  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.
    Copy & paste the code below to embed this comment.
  7. Really that’s the way to a successfully workflow. I started to integrate documentation and ‘style-guideing’ in my work process and benefits are inmediate. Pattern Primer is my choice wich is easy and quick:
    https://github.com/adactio/Pattern-Primer
    Copy & paste the code below to embed this comment.
  8. We’ve started to make use of PatternLab to build our style guide. It has given us a platform to build off of without needing to get caught up in the setup. http://patternlab.io/
    Copy & paste the code below to embed this comment.
  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/
    Copy & paste the code below to embed this comment.
  10. For those looking for a list of ‘Living Styleguide Generators’: I’ve collected a whole bunch of them at Github. It’s probably incomplete, but—if you’re not yet using such a tool— there might be one for your preferred technology (PHP, Ruby, NodeJS, etc).
    Copy & paste the code below to embed this comment.
  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 :)
    Copy & paste the code below to embed this comment.
  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.
    Copy & paste the code below to embed this comment.
  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).
    Copy & paste the code below to embed this comment.
  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 ;)
    Copy & paste the code below to embed this comment.
  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.
    Copy & paste the code below to embed this comment.
  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.
    Copy & paste the code below to embed this comment.
  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 :)
    Copy & paste the code below to embed this comment.
  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
    Copy & paste the code below to embed this comment.
  19. Another plug that might be useful for those using Bootstrap:
    Bootstrap Style Guide Boilerplate . A fork of Brett Jankords Boilerplate aimed specifically at Bootstrap-based projects.
    Copy & paste the code below to embed this comment.
  20. Thanks for your guides,it is usefull to my website http://www.betopbags.com/
    Copy & paste the code below to embed this comment.
  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.
    Copy & paste the code below to embed this comment.
  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!
    Copy & paste the code below to embed this comment.
  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.
    Copy & paste the code below to embed this comment.
  24. Copy & paste the code below to embed this comment.
  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
    Copy & paste the code below to embed this comment.
  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
    Copy & paste the code below to embed this comment.
  27. Here’s a helpful “Style Guide Guide” http://vinspee.me/style-guide-guide/. It shows you different options based on technologies used in your project.
    Copy & paste the code below to embed this comment.
  28. What a great article! I’m just now realizing how important style guides are for front end design. Thank you!
    Copy & paste the code below to embed this comment.
  29. wonderfull post,i think it is very helpfull to improve my website http://www.replicabagsshoes.com
    Copy & paste the code below to embed this comment.
  30. Its real nice article thanks @Susan reading it is time well spent .. :)
    Copy & paste the code below to embed this comment.
  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).
    Copy & paste the code below to embed this comment.
  32. Solid article. However, you would have to have to have some very unique requirements to make reinventing the wheel worth it, as apposed to just using the existing Foundation framework. http://foundation.zurb.com/
    Copy & paste the code below to embed this comment.
  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.
    Copy & paste the code below to embed this comment.
  34. The Atlassian Design Guidelines are a very useful resources and example, particularly for building web applications. https://developer.atlassian.com/design
    Copy & paste the code below to embed this comment.