Style guides and UI implementation

User and Social Experience Design

Why good, readable style guides are so vital for translating wireframes to final web user interface screens to ensure consistency, quality and reduce the number of defects.

Handing over a wad of wireframes to the development team is the same as an architect sketching a house on the back of a napkin and handing it over to the builder. Sure both the development team and the builder can take that and build a house and it could be a good house – but know that design decisions will be made on the fly. Most likely those decisions will be made without you – which isn’t neccessarily a bad thing but as a user experience designer you are meant to be the resident expert on user experience design and thus best placed to decide how your wireframes should be realised as fully-functional, rendered web user interfaces.

Without clear directions on how wireframes should be translated from mockup to HTML and CSS, it’s likely that stylesheets will become bloated, full of hacks and overrides, littered with !important and difficult to maintain. The HTML will be similarly messy with no logical templating or structure. Absurd amounts of time will be spent after the primary development effort resolving defects, inconsistencies and flaky behaviour … all because there was no initial investment in preparing a good style guide.

A good style guide is like assembly instructions. The wireframes are the pieces, the guide tells you how to put it all together and how to interpret the plans. Wireframes should not dictate exact positioning, colours, whitespace etc – but your style guide sure should.

A CSS developer should be able to take a style guide and literally write a stylesheet based just off that document encoding style guide component names into CSS classes, although I don’t suggest that a CSS developer work in the absence of a HTML template.

A CSS developer should never be required to work off Photoshop screen mockups – they lack the information needed to translate design decisions into semantic and logical page structure and class names. A good CSS developer will name classes by what components of a page mean rather than what they look like. There is rarely any meaning embedded in a graphic designer’s mockups. There is in a good style guide, however.

Have a look at this sample snippet of a wireframe prepared in Balsamiq:

The purpose of a wireframe is to describe screen layout, elements and interaction/behaviour. Developers should not be holding a ruler on the screen against a wireframe to measure margins and coordinates … and if you’re meticulously positioning everything in your wireframes to be consistent and with the intended spacing and font sizes then you’re wasting your time. Leave all that to the CSS, because one change in the CSS will be reflected in every screen immediately. That’s its purpose.

So we look at this wireframe of a dialog box. The dialog box has a header, form field labels, form field input boxes, text under the boxes etc. The style guide should therefore describe a dialog box. Here are some ideas of what the style guide might cover relating to the example dialog box:

• Is it fixed width or relative to the width of the browser; ie 500px or 70% wide?
• Should the header style inherit from the normal page header style or does it have its own special dialog header?
• Should action buttons be aligned to the left or right and how should the order be determined?
• How should single-line text fields, multi-line text areas, checkboxes, selects and radio buttons be styled? Do they inherit or have their own style?
• Should the dialog box be positioned in-place where activated or at the top of the screen (this might seem obvious but it’s often implemented incorrectly)
• What happens if the hanging tip text beneath a text field is longer than the text field?
• If the user prints their screen with the dialog activated should it print just the contents of the dialog, the screen behind, both screen and dialog or the data contained in the dialog but in a different format?
• How should the dialog look with JavaScript disabled?
• Where should feedback be displayed and should it be styled (this is important because feedback is not part of the initial page state and thus hard to display in wireframes)

It can be hard to predict the edge cases, the unexpected results when the wireframes meet the database and functionality such as long text, different screen resolutions etc so the style guide will probably need to be maintained and updated throughout the development process but if you know what you’re doing then it should be possible to capture most possibilities and variations or structure the style guide in a way that provides general rules to cater for things such as overflowing text; ie “If text is longer than allocated space, wrap and push down the following row unless fixed height dialog in which case scroll”.

Also with the points about printing and JavaScript, if you care at all about progressive enhancement and accessibility then these are vital to get right. Retrofitting a visual screen design for printing or to work without JavaScript is a nightmare. You might want to consider a layered approach to your styleguide to describe the base first then components, components within that template and then the relationship between components.

Describing behaviour and interaction should be handled predominately by your wireframes and hopefully you’ve broken up your wireframes into generic shared components in addition to all your screens and states thereof, however don’t leave behaviour out of your style guide if it helps interpret, understand and implement the user interfaces.

Another important thing about style guides is that they must be readable. It frustrates me that we invest so much time (hopefully) into designing usable web applications with readable, comprehensible content text for users and customers … but we don’t spare a thought for the development team and everyone involved on the project. I would like to see more effort expended on directing our user experience design skills inwards, developing documentation and processes that make sense to everyone, that suit team members’ workflows and operating environments.

I have written a sequel to this article, Part 2.

// purecaffeine.com is a user interaction and UX design, social media and Government 2.0 blog run by professional Canberra, Australia web user interaction designer Nathanael Boehm, licensed under a Creative Commons Attribution-Noncommercial-Share Alike 2.5 Australia License.

Related posts:

1. Style guides and UI implementation: Part 2
2. Keyboard navigation testing with Selenium IDE
3. Interactive Sketching Notation