Writing an Interface Style Guide

by Jina Bolton

42 Reader Comments

Back to the Article
  1. In our cms we have disabled all functions to change typefaces, font-sizes and font-colours.
    All type is set in the central CSS, our clients understand this and never ask to have the possibility to change the typograpgy.

    Copy & paste the code below to embed this comment.
  2. Great article Jina,
    Are there any great style design guides that could be used as examples?

    Copy & paste the code below to embed this comment.
  3. A good resource, though admittedly needs updated, is our own guidelines which cover accessibility and style and tone – http://acc.nics.gov.uk/

    Copy & paste the code below to embed this comment.
  4. Agreed, a good example would really be nice to have along with the article, even if the sensitive info is stripped out.

    Copy & paste the code below to embed this comment.
  5. Duke Law has a basic style guide for the 20+ non-technical users of their CMS. It has worked well thus far at limiting design disintegration.

    Copy & paste the code below to embed this comment.
  6. Jina, great article and the timing could not be any better! Finding a good reference for style web style guides proved to be pretty difficult. We’re currently in the process of creating a one for our site. I was surprised to see that much of what we decided to include was listed here, so that provided some much needed reassurance.

    One additional aspect that we are going to include will be downloadable photoshop templates with the guides in in place. Since we have a few different people creating graphics (full and part-timers) this will help preserve our design grid.

    Copy & paste the code below to embed this comment.
  7. Style guides are an excellent idea. Another consideration should be weather or not Flash, Shockwave, SVG or other alternatives to HTLM are permitted.

    Wouldn’t you think by now we’d have design and content tools which would make it easy or automatic to follow these standards. The first thing needed to enable this would be a new version of CSS with variables. (I will never understand how the creators of CSS could have left out so many simple and fundamental capabilities … that they failed to build on the most rudimentary principles used in programming known to any first year student of the practice. And, yes, I am a bit bitter about this. Does that make me a wood nymph?)

    Copy & paste the code below to embed this comment.
  8. I just started working on team websites and this will be great to communicate what should and should not be on the site. I created a website for one of the departments in our company and we are going to re-design (or re-align) the other departments to mirror this site.

    Jared- great tip on PSD templates. Definitely going to make a no-brainer for others who will be making sites.

    Copy & paste the code below to embed this comment.
  9. I absolutely love the idea of this. We all feel this pain. But when I think about the time involved in creating something like this for clients, it becomes painfully clear that it is unrealistic. Alas.

    Copy & paste the code below to embed this comment.
  10. Another this to consider is defining the charset used on the site. I’ve run into many problems with users copy/pasting something encoded as UTF-8 (often from Word) into a page that is ISO-8859-1, or vice-versa.

    Copy & paste the code below to embed this comment.
  11. good job on the article Jina. How about you write a book on the topic.

    Copy & paste the code below to embed this comment.
  12. In my current job, I have encountered 4 style guides, 3 of which were turned over as greatly profitable deliverables by well-known design firms. They are very pretty. They are worthless.

    An essential part of the problem is not content but rather medium. Web site and Web application style guides should be done in Web technology—not PDF or Word. An HTML style document should follow every rule and guide given in the content. This not only makes the advice visual, it practically invites maintenance teams to grab code directly from source—rather than try to translate pretty pictures into a new modification.

    The 4th style guide I work with was done completely in the structural HTML, CSS, JavaScript and allowed images and palettes discussed in the content. Developers and maintainers find this approach saves them time. This guide has passed the test of practical usage while the others are on shelves somewhere, ineffective because never opened. Harried developers and content maintainers are like that…

    Copy & paste the code below to embed this comment.
  13. Nice article. One of the best styleguides I have come across is from the book “CSS Mastery” by Andy Budd with Cameron Moll & Simon Collison. The style guide is part of the Chapter 1 download.

    Copy & paste the code below to embed this comment.
  14. I’ve worked with plenty of clients who have their own styeguide, and produced plenty more myself. They’re a good idea, but it’s very advisable to do the whole thing as a site, and not try and make a PDF or printed styleguide. Imagine there are 30 different people in 10 different companies using the guide, and you don’t know who they all are. This is pretty common on big sites. And then you change something. By the time everyone’s got the latest version, you’ve changed it again. With an online styleguide you can not only easily notify everyone of changes, but you can also use the styleguide itself as an example of the rules it describes.

    Copy & paste the code below to embed this comment.
  15. @Robert Shaver: variables would be cumbersome and are unneeded in CSS – it’s not a programming language. If you want CSS with variables then process your css files with PHP or another language. XHTML doesn’t have variables either, as it should be.

    Plus – Microsoft would never get around to implementing it in everyone’s favorite browser!

    Copy & paste the code below to embed this comment.
  16. I’m a tech writer, so I work a lot with style guides, and have had to create them. One of the problems I’ve found is that it can be difficult to actually get people to use them.

    Copy & paste the code below to embed this comment.
  17. I share your frustration of seeing your work disintegrate, but my experience is that it is extremely hard to get a client to pay for the time it takes to make a good, thorough and useful styleguide/manual for a site. It should be mandatory, but to many clients it looks like some documentation that they don’t think they need, and therefore do not want to pay for either.

    Copy & paste the code below to embed this comment.
  18. As many of us have already stated, the ‘locked down’ web page templates that often come with a CMS (or even Dreamweaver driven site) that isnt enough.  That darn content area is open and available for mischief.  As mentioned in the arcticle, by giving editors that ability to upload/replace images you run the risk of the ‘gaudy images’ ruining the site.

    One solution that I believe in is to provide template photoshop files that are cropped, layered and filtered in a manner consistent with the established look-and-feel where its almost fool-proof to create the correct images for some one who has rudimentary experience with photoshop.  Just open the file, replace the source image, and save out the “styleguide approved” image.

    I agree with the use of a website to act as a styleguide instead of primarily a print piece, but there should be an easy way to print the styleguide website content so designers can read through them, make notes, pin pages to their walls, etc.  Most large corporations have taken to placing their brand guidelines online for world-wide consumption.  The website should be no exception.

    As far as an example, I have a PDF example posted of an old project at: http://jd3.net/itec/894/assets/04_styleguide_sample.pdf.  Its outdated in some ways but it may be helpful to those who have never seen one.

    Its part of a larger tutorial that i made on agency methods of website design: http://jd3.net/itec/894/

    Copy & paste the code below to embed this comment.
  19. There are far too many free style guides out there. I caution designers and developers against “throwing in the style guide as part of the process”. It is not an easy or quick piece to the project; it’s work that requires time and attention to detail. Make sure that if you do provide this to a client that you include a section in your proposal (or statement of work) that outlines how you’ll deliver and what it will cost.

    I have two reasons for this:

    1. If you are getting paid for the work, you’ll do a better job.

    2. Getting paid for it will more than likely get the client to enforce it since they hate “paying for nothing”.

    For internal folks, make sure that you go through a proper chain of command for the style guide. It’ll help you use it as a policing mechanism.

    Copy & paste the code below to embed this comment.
  20. I am in the midst of creating my very first official style guide and feel reassured by this article and also I have found something I maybe should add to it.

    On top of that I think I must admit that while writing the style guide I went back and fro’ and made corrections to some of my code.

    That’s the thing of creating a guide: you yourself should at least adhere to it!

    Copy & paste the code below to embed this comment.
  21. I’ve found that when setting up a style guide it is best to design for every type of HTML that they could possibly used within the areas of the CMS that aren’t “locked down”.

    Sometimes grabbing an example HTML file from css frameworks like blueprint can be used as a base for a CSS style guide – to make sure you cover everything.

    Also, if you aren’t going the PDF route and you are giving them HTML, it can be handy to provide sections of pasteable code that will accomplish a particular “look” or micro layout.  People are more used to pasting embed code and things like that after using sites like YouTube.

     

    Copy & paste the code below to embed this comment.
  22. It was a great article and a job well done, Jina.

    Copy & paste the code below to embed this comment.
  23. Thank you everyone for the fantastic comments. :)

    To everyone who asked for examples: Unfortunately, I can’t show you any of my real-world examples, because, well, I’m not allowed to. :) I’ll get a sample version up (hopefully in the very near future), and update everyone in the comments here when that happens). In the meantime, here are a few online elsewhere that I have used as inspiration in the past.

    - http://webstyleguide.com/
    – http://nypl.org/styleguide/
    – http://alistapart.com/contribute/styleguide/

    The others I use for inspiration are printed, so unfortunately, can’t share them. Thanks for the examples shared in the comments. To those discussing CSS variables, I think it’s an interesting idea, but I’ve never had the opportunity to use them. I can’t really give an opinion on it.

    @Niek — disabling the ability to make changes would appear to be the ideal route, especially if you are the one to continue maintaining the site. However, if the site is commissioned over to the client, in that it is now in their care, that method seems a bit restrictive. I guess it depends on the situation.

    @Robert — Indeed. The more detailed you can make the documentation, the better. No worries on being bitter (regarding lack of tools to make this more streamlined). I want that very badly, and have even been thinking up some ideas… ;)

    @Mark — It might be unrealistic for some projects, but I encourage you to make it a part of the project. Some clients might not see the need for it, but I think it’s a good idea to sell them on the benefits. It’s like a handbook or manual for their product you just built for them. :)

    @Brian — Thanks. A book? One day. ;)

    @Brett — Worthless? I think that’s a matter of opinion. I have always found web style guides to be very useful (even if in print). Especially if I’m a new developer/designer joining the team on a project — I have something to refer to. I do agree that for the web, it makes more sense to document on the web — I already stated in the article that doing this online would be beneficial.

    @Matt — I agree, an online style guide is preferable than a printed style guide. It’s also better for the environment! However, sometimes I need stuff in print to jot down notes or pass around. Simple print style sheets should do the trick.

    @Todd — Unfortunately, that is a problem I am faced with as well. However, I find that when people come to me with questions, I refer them to where the documentation is each time. It reinforces the idea that the documentation is the best source.

    @Bjarke — Time is certainly an issue. In my experience, making it part of the project has helped, though I agree, not every client sees the value in this. Perhaps a reusable template would work to help save time.

    @John — You’ve read my mind. :) Thanks for the resources.

    @Christen — Yes. This would be a good thing to “templatize” so you can reuse it.

    Copy & paste the code below to embed this comment.
  24. I think style guides are a must, a bible – for content writers, producers, developers, designers and agencies to refer to.

    One important piece to include is info about the target audience of the website. the style guide is a great place to incorporate Personas if you have them.  The idea is that anyone touching the site or creating content, should refer to the style guide and will be reminded of who their audience is.

    Other items to include:
    – rules on copy, eg When to use Upper/Lower case, acronyms
    – linking – guidance on link text
    – guidelines on video

    Copy & paste the code below to embed this comment.
  25. I think this is a great idea. Plus as well as something useful for our clients imagine how much easier it would be for our lives if the client already has one. How often have you all had to build sites based on a clients logo and then when you ask them for the font used and the exact colours all you get back is a blank stare?

    Man, the time I’ve spent trying to find out what a font is…

    Copy & paste the code below to embed this comment.
  26. I like the idea but my main concern would be that the documentation would not be used and overlooked by many.

    Lets say you develop a nice looking site for X Corp. and they want to change something. If their developers (Who may not be up to par with HTML and CSS) might not understand the documentation and instead do as they please.

    I am not going against you, i always create style guidelines for clients but i have had the clients ignore them.

    If your using a CMS such as Joomla! than its best to cut of access to the presentation and inner workings of the site and leave that to the people who know what they are doing.

    Copy & paste the code below to embed this comment.
  27. “Show wireframes to illustrate these variations…” I heard this term “wireframes” a lot but I can’t seem to find wireframe examples on the Web. I have always wondered what does a wireframe look like and how it’s being done.

    Do you have any recommendations on industrial standard wireframe software for PC users? I appreciate it.

    Copy & paste the code below to embed this comment.
  28. unrealistic? not really. although i understand mark’s comment, i don’t agree. at the same time i don’t agree with the author’s idea of a style guide.

    typography, color, brand, whitespace, are all things most publishers don’t care about or understand. trying to define them in ways they can grasp and use is a futile act. when you build a site or interface you are doomed to fail unless ALL the caretakers of your design completely understand it. that will never happen in a one pager that talks about brand styles and typography.

    to build a bullet proof design you need a complete arsenal of design standards, you need to create a design language that everyone can understand.

    i own the guidelines, css, and html standards for literally tens of thousands of pages on over 34 country sites in just about any language. i do this with a team that consist of one designer and two designer/technologist (there were times when it was just me). how do we succeed? we bake in style in the css, and instead of trying to explain style nuances we cook up html components for people to plug and play. then we focus documentation on the components.

    this system isn’t perfect, but it creates a common language and tool set that we can use in wireframes, html, css, and js. for us documentation is easy, it becomes a minor step in the process of realizing new designs. the more design decisions you take away from publishers the less chance you have of things going wrong.

    is it easy? no. we rely on several key elements for our success. the first is that engineering will not enable any design in our CMS system unless it is documented in our documentation. this creates a checks and balances that keeps publishers and content owners from inventing. the other key is that we traffic all front end coding through one group. this ensures maximum efficiency and keeps a short leash on html, css and js.

    i think i’m just unclear as to who the target audience of the style guide is. is it just anyone? or is it engineers, publishers, or other designers? i think with web design you need to break away from tradition notions of design systems. i see your concept as a carbon copy of a brand style guideline for printed material. if you want to do your client a true service build them a design system they can expand on. a design systems that can be communicated to other designers so that they can contribute to what you’ve done to give the client more tools they need to succeed.

    btw, we keep all of our documentation external so all vendors have no excuse to use our components. feel free to check it out here… http://www.sun.com/webdesign/ check out the “Explore Components” to get an idea of our component system. Here’s a preso i did for a Cisco a while ago that show’s an overview of our design system and how it plays out from wireframes to css namespaces… http://www.odometer.org/misc/under_the_hood_v1.pdf

    Copy & paste the code below to embed this comment.
  29. While style-guides are useful for those who use them, when you are using a CMS there will always be users that haven’t read the style-guide, don’t understand the style-guide or think they can do a better job. Reading the comments, most of us here have he same experience with editors.

    In principle it is a good idea: a style-guide should be part of every decent or large website. However knowing that editors are not keen on following the guidelines, I think it is better to enforce the stylguide to make sure people understand what it means by giving them visual clues when they make a mistake.

    I like the idea of Andrew, using components and cutting out any access to the code, but that is not what I can do at the moment.

    I “enforce” the guidelines, by adding another stylesheet and additional JavaScript that points out unnecessary elements, wrong elements, css rules that aren’t allowed, font tags, … everything I don’t want to see on the website is surrounded by a big red border.

    div#content font, div#content blockquote{
    display: block ! important;
    border: 3px solid red;
    }

    That way the editor knows when they are crossing the line.

    I have written about it: “QA with stylesheets”:http://blockquote.be/2006/07/17/quality-control-with-style-sheets/ (http://blockquote.be/2006/07/17/quality-control-with-style-sheets/) and it works pretty well as CMS editor will call me to get that annoying red border of the page.

    Copy & paste the code below to embed this comment.
  30. Awesome post thank you for sharing. Perhaps we are biting the hand that feeds us but an example would be great. 

    http://www.law.duke.edu/edtech/style_guide this is nice but would be interesting to see a more comprehensive example.

    Copy & paste the code below to embed this comment.
  31. Gina, great article.
    Developing guidelines can be tricky and keeping them up to date can be challenging – any suggestions or examples on how to ensure the value of the document persists? Thanks.

    Copy & paste the code below to embed this comment.
  32. It’s a very interesting article. I’ve always felt frustrated too when my designs got messed up. Most of the time I think a style guide is necessary. I always include it in my proposals, but most of the time the clients decline it, even though I try to convince them about its importance. However, sometimes too I question it’s utility when developping it. I always feel myself a bit confused about how to do it, because the CSS is exactly that, isn’t it? I feel myself repeating something that’s already there, and wasting my time too :). Wouldn’t it be preferable to make a very well commented and written css instead? I mean, who’s the style guide for?  If it’s meant for developers, them I think they should take sometime to study and understand the CSS. Isn’t it?
    Anyway, I loved the idea of an online style guide like the blueprint html example.

    Copy & paste the code below to embed this comment.
  33. Great article Jina!

    I’m an art director & user interface/experience designer for web and I’m constantly trying to push the style guide forward. It’s so important to keep a website looking & behaving consistent in terms of the brand. Usually it’s the first thing to be dropped from our clients’ budget, as the style guide does take a wee bit of time to create.

    However, I’ve recently found that a short style guide can be just a useful. As long as you sum up all of the key components and visuals you’ve listed, it can be helpful. The person/team responsible for maintaining the website would much rather flick through a concise guide, rather than having to sift through a 20 inch thick bible! That’s what I’ve found anyway.

    Thanks for the great article!

    Stu.

    Copy & paste the code below to embed this comment.
  34. I think creating too much of a process for anything eventually leads to paralysis from analysis.

    Copy & paste the code below to embed this comment.
  35. Here are a few screen shots from a very large and comprehensive visual design style guide that I lead while working on the redesign of the AARP Bulletin (http://bulletin.aarp.org) at Behavior Design.

    Yes, clients seem to ignore these very often, but that’s their choice. I find it more useful to use style guides as an internal tool to use to lock down the design language before moving an interface design project into multiple page production. This better allows you to stick to one style and maximize effort and budget.

    http://tinyurl.com/66yu7f

    Copy & paste the code below to embed this comment.
  36. Thanks good articls..

    Copy & paste the code below to embed this comment.
  37. My expirience is that when you deal with customers, as an webdesigner, its good to tell and show them a design guide. it is more comfortable to realise project with them together without having a crappy layout because of the customer ideas and changes they want.

    Copy & paste the code below to embed this comment.
  38. Every one thinks they can control the circumstances ‘if we would just… (fill in the blank).’

    History has taught us that optional guidelines are rarely followed. Rules must have a notable reward and a dire consequence. That way you appeal to both personality types; those that avoid pain and those that pursue pleasure.

    The caveat in all of this is that a good looking site is singular in perspective thus rendering the reward mute and… only the finest web designers appreciate really good design.

    In short, without sufficient motivation, manuals will not be read, guidelines will not be followed and the appearance of your masterpiece will eventually degrade.

    The only option is to eliminate the ability to alter the design or consign yourself to the idea that your control is temporary at best.

    But write that manual if it makes you feel as though you have more control.

    Copy & paste the code below to embed this comment.
  39. Thanks for alerting me to the fact that when I get more clients into CMS that they are going to need a style guide.

    Copy & paste the code below to embed this comment.
  40. Just caught this in a Lynda.com tutorial on how to design / build an online styleguide. Though the tutorial is rudimentary, the reference site is quite nice:

    http://www.monash.edu.au/staff/web/

    Copy & paste the code below to embed this comment.
  41. this video may help you and other to same purposes of writing CSS Guide

    http://www.lynda.com/home/DisplayCourse.aspx?lpk2=758

    thank you ..

    Copy & paste the code below to embed this comment.
  42. Copy & paste the code below to embed this comment.