Front-end Style Guides

34 Comments

Comments are ordered by helpfulness, as indicated by you. Help us pick out the gems and discourage asshattery by voting on notable comments.

Got something to add? You can leave a comment below.

  1. Chris Coyier

    I love that style guides and documentation has been more of a hot topic lately. Yay!

    I’ve been doing a lot of work in this area lately and have a few random thoughts to share.

    * Make a real, live, accessible-by-everyone-who-works-there page that is your style guide.

    * Make that page use the real HTML/CSS/JavaScript that the real production site uses.

    * Make it just one big long page. Put every single possible element and design pattern you intend to use on it. This will help weed out potential conflicts.

    * Break up resources by pattern
    tabs.html – tabs.css – tabs.js – tabs-sprite.png
    grids.html – grids.css
    accordion.html – accordion.css – accordion.js

    * Production resources serve 1) global assets that are concatenated/minified versions of the most common patterns 2) page specific assets that are concatenated/minified versions of less common patterns

    * Base all patterns on real developer needs, not perceived or theoretical needs.

    If you do it right, the end result is a site with good visual consistency that is easier and faster to develop for.

  2. Heather

    Drupal has a “style guide” module which will generate a guide for your own site similar to the examples above. It generates all the markup on your site, then pulls in your live styles.

    http://drupal.org/project/styleguide

    One benefit is that it also generates Drupal-specific markup which designers often overlook.

    Kinda handy!

  3. Matt Wilcox

    I mentioned on Twitter but forgot to post here: great article Anna :)

    I’d been doing the same think Paul has for years, but it never once crossed my mind to use my “all mark-up” template as a style-guide. I was using it as a reference for myself and that was all, in fact I’d recently stopped bothering with it. Time to bring it back and spruce it up! I’ll be putting a few of the ideas you’ve discussed into practice, and sharing them with the team at work. Thanks!

  4. Logospotter

    Loving that the style guide is not seen as a restrictive document, but something that aims to help raise standards for the people using it.

    It can be hard to get started and I’m liking how this article offers practical ideas to get going. Hopefully once I start then a bit of momentum might come.

    Good work.

  5. Nicolas Chevallier

    I never created this kind of guide, but I must say that the idea is excellent and that too many designers I know are somewhat lazy. Note also that some designers use tools that hide much of the presentation CSS, and suddenly the styles are whimsical, with names generated, or worse. There is still work!

  6. Kurt

    Thanks for this insight Anna.
    I think this post has a related message as the post of Paul on the 5th. It is important that different teams (developers and designers) work together and speak to each other so they can interact with each other and make something much more beautiful. But you have to have a guide. You can work with a style guide like you say, but I think putting them in the same room will give better results, because of the interaction.

    Or do you suggest that this style guide is made by brainstorming in advance with all the people who will work on the project?

  7. Sean Conaty

    I agree whole-heartedly. Style guides are one thing but code guides are even better. That way, a back end developer can go there and know what she needs to know to make something look the way it should look. Without it, she’d have to guess, possibly re-creating an existing style that looks somewhat the same but not quite.

    They’re easy to make too! You already have the code, it’s just a matter of adding an extra page.

  8. Mark Brown

    Thanks, I enjoyed the article :)

    I wrote a front-end standards document for our team recently, to share knowledge about front-end technologies and get more people across the issues that I think matter.

    http://www.yellowshoe.com.au/standards/

    It served it’s purpose in getting a few more people interested in the topics, it’s also helped as a refresher for me when I’ve needed it.

    I think a lot of these guides are really just trying to promote a shared appreciation of values that the authors hold.

  9. Yogee

    Thanks for that article!

    Last Week I started on a style and coding guideline for the company I work for now. It is a rather heavy traffic site, so to have some sort of documentation is a must! (status quo: there is none…).

    I had the idea of implementing all used (and new) elements with a code sample. Even Color and Font styles with sample, codesnippets and so on.
    But I wasn’t sure if that was a practice to go for.
    You encouraged me to go ahead!

  10. Rich

    I’d like to see styleguides, merged with code guides.

    This:
    http://www.bbc.co.uk/gel

    PLUS

    This:
    http://twitter.github.com/bootstrap/#

  11. Anna Debenham

    Thanks everyone, really glad you’ve found this useful and are thinking of making your own. I’ve put all the examples you’ve mentioned to the stash.

    Chris, these are really great points, and it’s encouraging to see you’re producing these. I’d love to see some examples if you have any that you can make public.

    Mark, I really like the example you’ve given and added it to the stash. It’s so helpful seeing how other people write code.

    Tom, I like the look of KSS and will definitely try it out.

    Rich, I’d been desperately looking for that bootstrap example. I’d heard about it but couldn’t remember what it was called or who made it. So thanks very much for linking to it!

    On Twitter, @steve_worsley linked to a primer document with content like headings and paragraphs that you can use to help give you a head start building your style guide.

  12. Paul Smith

    Style-guides and real front-end specifications are another promising step on the road towards higher level professional working practices for the front-end discipline.

    What makes it great is that the development of greater standards, more knowledge of writing reusable code and brilliant resources like GitHub we can share them easily and effectively.

    Twitter Bootstrap is great example: http://twitter.github.com/bootstrap/

    Early pioneers were people such as Nate Koechley (YUI), Nicole Sullivan (OOCSS – http://oocss.org) and more recently Jonathan Snook with his Scalable and Modular Architecture for CSS (SMACSS – http://smacss.com/)

    Part of what makes me love this industry and working at this time is how people are still sharing their knowledge passionately to make a better web. For years I’ve standing on the shoulders of giants such as Zeldman, Bowman, Cederholm and now people like Paul Irish and Jake Archibald and long may it continue.

  13. Aarron Walter

    Enjoyed the article. We’ve created a comprehensive pattern library at MailChimp that both acts as our style guide and as a litmus test when we make global design changes in the app. It’s just a really big HTML page that contains all elements we use in the app with code examples. It’s helpful when we add new people to our team as they’ve got a quick reference to refer to when building new interfaces.

    http://www.flickr.com/photos/aarronwalter/5579386649/

  14. Paul Randall

    I’ve been a massive fan of these. A few years ago I created an HTML Kitchen Sink, but have gradually been ramping up the elements that I included in it.

    Only today I was creating one for my workplace to use for all future internal and external projects.

  15. Dale Sande

    The concepts of styleguides have been a passion for me for years now. Building a site or an app without one now feels like cars without seat belts.

    I too have put out a styleguide/CSS framework written in LESS and am in the process of developing the same thing in SASS. http://axle.dalesande.com/

    For me, the greatest benefit and the most WIN for using a styleguide is the idea that UI developers are forced to address UI problems in the abstract versus developing that UI ‘widget’ in the screen from which it was first designed.

    All to often we develop markup and CSS from a single use perspective and when the time comes that we need to use that ‘widget’ again, we find ourselves writing lots of additional code.

    Concepts on OOCSS help us to do that better, but the styleguide concept enforces those principals.

    It is awesome that this concept is gaining momentum and is showing no signs of stopping.

  16. Jamie Neely

    Hi Anna. Great article.

    In our own work, we’ve found that getting off to a good start with something like Twitter Bootstrap and Mailchimp UI Pattern Library is half the battle.

    I’ve also been speaking to loads of design/front-end people over the past 6 months who’ve been describing handover as one of the prickliest parts a project. Most of those people know intuitively that a styleguide can help, but say it often becomes a casualty of project time constraints.

    (sad panda face)

    To help reduce effort, we recently built a styleguide feature for www.typecastapp.com. It creates a real time representation of any style decisions you make while designing in the app, including supporting code snippets. After just a few weeks of beta use, we are getting a really positive reaction to that one feature.

    You can see a screenshot here http://bit.ly/typecast_styleguide

    We’re always looking for good examples of this stuff, so thanks for creating the stash!

  17. Jeremy Caudle

    Thanks for writing this! I’ve been looking for examples of style guides, and I’m certainly going to keep an eye on that collection for future reference.

    Jeremy’s Pattern Primer is such a great idea and I can’t wait to build something that useful.

  18. Anna Debenham

    Kurt, you bring up an interesting point (and one I hoped someone would raise).

    I rarely get the opportunity to work directly with a designer on projects – usually just get sent static files to mark up without any contact with the designer, but I’ve found the projects where I’ve sat next to the designer, or at least been able to communicate throughout the process, are the most successful (and are much more enjoyable).

    Producing front-end style guides often go down well with the designer if you can work with them on it, because they’re so similar to design style guides. They’ll be able to make suggestions on ways to improve it too.

    It does depend on your processes though, and it isn’t always possible (or the norm) to be able to collaborate or brainstorm on this with all the people who will work on the project, but hopefully that’s changing as our roles bleed together more, and we think more about sites in terms of systems rather than pages.

    Also, I chatted with Paul about what he’d be writing, and we realised our topics would dovetail quite nicely, so the relation and placement is somewhat intentional. :)

  19. Mason Wendell

    Great article, Anna.

    I’ve been fascinated by html style guides for a while and not just as a tool for documentation. I often build one as one of my first tasks when designing a site. I’ve found that it’s a nice place to start making aesthetic decisions about the markup and content, before I get too deep into decorating the page.

    To that end I built a system I call the Survival Kit, which helps you make these in the context of designing in the browser.

    Survival Kit

  20. Guy Jeffries

    Excellent article and a generous batch of resources from you and the other contributors.

    Being a relative newbee to web development coming from another industry where nothing is shared, seeing articles like this reinforces that I made the right choice.

    We’ve been developing our in-house style guideline system on and off for about a year now and the article and the resources it shows will help us get it finished, thank you.

    We’ll get it up and published when we;re done.

  21. Russell Heimlich

    Bravo! I hope over time we develop more tools and systems to make this part of the design process easier.

    As for examples in the wild, I found this lovely coding standards document from nodewave.com

    http://www.nodewave.com/download/document/css-coding-style-conventions—standards-guidelines-rules

  22. Justin

    Style guides are brilliant, but please please please never deliver one like this <a href=“http://brianmay.com/siteguide.html”>http://brianmay.com/siteguide.html</a>

  23. Dale Cruse

    This article is so timely to me at my new job. We work on a web app that was built & “designed” by back-end engineers. After being in business for 10 years, I was brought in three or so weeks ago as the first front-end developer & designer. I’m in the process of revisiting literally every user interface element & how we display it so the list of resources in this article is going to be very valuable to me very quickly. Thanks!

  24. Anna Debenham

    Mason, your Survival Kit looks very interesting. I like that it uses Sass too. Thanks so much for publishing it, I’m looking forward to giving it a spin.

    Justin, that’s a… umm… intriguing style guide! Thanks for sharing it! :)

    Dale, I’m really glad you’ve found this useful. Let us know how you get on.

  25. Pete Schuster

    Really great article. I’ve been trying to create my own boilerplate, and a style guide is a really great idea to add to it. https://github.com/PeteSchuster/Pete-Schuster-Site-Boiler-Plate

  26. Corey Innis

    Wonderful article.

    I love this technique and have argued for it (and tinkered in kind) for a while now.

    I do have a point of concern when it comes to implementation: please, please, please… don’t through out the semantics.

    For example, any style guide (live/dynamic or not) which claims “all H1s are… and all H2s are… and all H3s are to be styled as such” — site wide and without regard to context — does, thereby, strip said heading elements of their respective semantic meaning and reduces them to style attachment elements.

    Better to use spans at that point.

  27. Gilles Gallico

    Excellent idea. Even though I do not use at the present time this kind of Front-end Style Guides, I am sure it’s quite easy and useful to begin a project with it. The most difficult would be to keep using it during the whole project lifetime and not add, by laziness or emergency, to many styles that make our guide maladjusted.

  28. Jared Williams

    Coding standards and style guides are definitely important for so many reasons. I don’t know what I’d do if my company didn’t have them for the projects we have going on.

    We have our own Front-end Coding Standards and Best Practices document which has been extremely useful for frontend development and has had several past and present employees contribute to it. We have made it publicly available and have put it up on github too for anyone looking to help contribute to it in any way. Check it out here:

    http://na.isobar.com/standards

  29. Larry Botha

    I’m growing a base styleguide over at http://larrybotha.github.com/styleguide/ which has proven immensely useful in building scalable sites.

    This post inspired me to create a styleguide a while back, and I’ve never looked back. In fact, I can’t imagine putting a site together without first building a styelguide.

  30. Simon Cox

    Love this article Anna! This is one of those subjects that I always mean to add into projects but never find the time – and as you say it celarly can save a great deal of time in life cycle of a site so shouldn’t be neglected. Your examples are inspiring.

  31. James Christie

    Great article and timely for me as I’ve just come off a project that had the “other” kind of style guide – a massive, InDesign + Fireworks produced PDF styleguide – a print mentality to showing HTML design.

    Needless to say, every page needed to be updated numerous times.

    Never again!

    The client would have been much better off with a one-page-everything-on approach.

    Thanks!

Impress us

Be friendly / use Textile