Writing an Interface Style Guide
Issue № 260

Writing an Interface Style Guide

Take a look at any CSS-based website design gallery, and you’ll see it’s obvious that beautiful interfaces are being designed and developed in amazing quantities. I frequently look to these sites for inspiration and, beyond a nice design and beautiful code, there’s usually something common about these sites: they’re new.

Article Continues Below

Unfortunately, it’s also common that beautiful interfaces don’t stay beautiful. An interface’s design disintegration can be frustrating to deal with, especially for the designer and developer of that interface; it can be particularly frustrating for the designer and developer who can no longer access the site to fix the issues.

If you have ever designed a beautiful interface only to find it ugly five months later because gaudy graphics, unpleasant colors, and distasteful fonts appeared over time, then you understand how maddening design disintegration can be. Similarly, if you have ever developed a clean, web standard, and accessible interface but later found the site littered with invalid, inaccessible, and presentational markup, then you understand this frustration as well.

Documentation can help avoid these issues—it provides guidance on how to maintain and update the interface, and keep it beautiful at the same time.

Design and brand standards#section2

Interface design standards enable brand stewardship. Commonly documented in a design “style guide,” these standards inform clients and content editors of branding guidelines for typography, whitespace, color, etc. The design style guide provides a reference in which developers can describe the way the interface is intended to look, and helps designers to be consistent as the interface is updated so that, in turn, the interface continues to feel consistent.

Some design style guides are simple and straightforward, including only basic typography and color styles; others are informative and somewhat complicated, and go into great detail in defining all aspects of brand guidelines. Like the interface itself, a great design style guide should be straightforward, intuitive, and informative. It should provide detailed information, yet be clear and concise. The following are important elements and relevant details to include.

Layout and composition#section3

Define all the layout variations that are used for the interface, and when and how they are used. Show wireframes to illustrate these variations (such as different column configurations and where they are used).


Explain the guidelines for acceptable use of typography. Use illustrations to show examples for the main text, the headline styles and their hierarchy, list styles, etc. It is also a good idea to define the typography standards in promotional graphics, as well as list the alternate typefaces that can be used for hypertext (in the event that the user does not have the font you have declared).

Color palette#section5

Provide a color palette to illustrate the standard colors that must be used throughout the interface. This reference should include exact color codes (you can list hex color values or RGB values). It is good to show where these colors are used. For example, you can include a screenshot that shows the color used for links.


Define the standard image sizes that may be used throughout the interface. This should include any graphic banners (such as promotional banner advertisements) as well as images that are used within content. Show how they may be styled and aligned, and how captions should appear (if used). You can also include what type of imagery that may be used (such as illustration or photography, as well as allowable styles or “mood”). Finally, if you use any icons in the site, set standards for them, such as how they look, where they are used, how they are styled, etc.

Brand guidelines#section7

Beyond typography and color, brand guidelines can include other standard design elements. These standards might define the amount of space allowed around the logo, how the logo appears depending on the background it sits on, or how the organization’s name should always appear in text.

Some style guides include supplementary information beyond the look and feel (for example, you can include standards for copywriting, advertising, and other elements that influence the interface and user experience). When defining design standards, you can even include the related markup and CSS needed to create the visual appearance expected. However, it might be better to create a separate section or document for these front-end development standards.

Front-end development standards#section8

If there is more than one developer on the interface, it is extremely important that everyone is aware of the development standards. It is likely that each developer has his or her own way of doing things. Getting everyone synced on (X)HTML, CSS, JavaScript, and other aspects of front-end development can help avoid any confusing issues down the road. While a design style guide outlines design and brand standards, a development style guide is important to keep development efficient. This can be a separate document, or included with the design style guide.

(X)HTML, CSS, and JavaScript#section9

Delineate how (X)HTML, CSS, and JavaScript should be used when developing the interface. Address the standards that developers should follow, which DOCTYPE to use, as well as class and ID attribute naming conventions. Include the code used to create certain layouts, forms, widgets, etc. Outline formatting and commenting standards, and define how the framework is set up (if a framework exists). (X)HTML, CSS, and JavaScript standards can be discussed together, as they all play together, but it can be helpful to go in-depth for each one, in their own sections.

Accessibility and usability#section10

Identify the accessibility guidelines that must be followed, and include any usability mandates. Document any localization and internationalization standards that exist.

Files and directories#section11

Define how the directory structure is set up for files (images, style sheets, JavaScript files, etc.), and where these files go (according to their types or purpose). Explain file naming conventions and how they are used.

Quality assurance testing#section12

Walk through the steps that should be taken for quality assurance: validation, link checking, accessibility testing, proofreading, etc. Include a graded support chart for browsers and devices.

When discussing standards in your development style guide, it should be clear that the standards outlined are not only industry-wide standards—they are also organizational standards that all developers should follow. Keeping development consistent goes hand in hand with keeping the design consistent, and should help make work more efficient and improve maintainability.

Keep style guides current and useful#section13

Interface style guides are extremely useful to define best practices for design and development. However, keeping that information updated and functional is imperative. A glossary, an index, references, acknowledgments, etc., are among some of the supplementary details you can add to make the style guide as helpful as possible.

You’ll want to have this style guide easily accessible for designers and developers. While a printed version is great to have on hand, an online version can be easier to access, maintain, and keep current. If you do not wish to keep track of both a printed and online version, you can opt for print style sheets on the online version, so you only have to update the information one time.

Finally, provide information on how someone can get help, in case the style guide is unable to provide certain answers. List contact information for the person or team(s) that manage this documentation.

With proper documentation for clients and content editors to follow, you have a better chance at seeing your interface stay beautiful. Future designers and developers who work on the interface will have an easier time adapting, thus making their lives easier and potentially saving time and money.

About the Author

Jina Bolton

Jina Bolton is a Senior Designer on the Design Systems team at Salesforce. She is passionate about style guides, Sass, and whisky. She organizes The Mixin, a San Francisco Sass & front end meet up, and she also leads the brand & website design for Sass.

41 Reader Comments

  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.

  2. 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.

  3. 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?)

  4. 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.

  5. 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.

  6. 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.

  7. 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…

  8. 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.

  9. 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.

  10. @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!

  11. 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.

  12. 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.

  13. 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/

  14. 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.

  15. 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!

  16. 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.

  17. 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.


    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.

  18. 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

  19. 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…

  20. 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.

  21. “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.

  22. 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

  23. 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.

  24. 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.

  25. 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.

  26. 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!


  27. 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.


  28. 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.

  29. 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.

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