I've recently started a major redesign for a large web-based financial tool. To aid future development, I'm planning on generating a UX style guide that outlines best practices for things like forms, page layouts, animations, etc...

The existing application is a big jumble of forms with little grouping or organization. I can see a few major categories, (Object CRUD forms, static data, user session management controls, etc...) but there's a lot of very custom functionality that doesn't fit the mold.

The company I'm working with does it's development overseas, and this documentation is intended to support future development. I'm not looking to design the most amazing UX ever, I just want things to be functional. What's the best way to communicate designs to remote teams?

Here's my question:

What's the best way to approach a big messy project like this? (Major groups first, then focus on each custom function? Do you even include the custom functions in the documentation?)

  • 3
    Hi Loren. I've edited your question to remove the request for examples. It's fine for answers to include an example and explain why it's appropriate, but for a question to just request examples means you'll potentially get lots of answers consisting of just links - none of which would be constituted as a Correct answer. As a Q&A site questions need to be focussed on drawing explicit answers that could be deemed correct. Any example style guide, regardless of how good it is couldn't be considered the 'correct' answer to this question.
    – JonW
    Sep 26, 2012 at 8:38
  • 1
    Thanks @JonW -- I'll keep this in mind for future questions. Sep 27, 2012 at 15:43

5 Answers 5


Example Style Guides

For example style guides applicable to applications, you can leaf through with the usual platform style guides (e.g., Windows, Apple, Gnome) for the organization, issues, and topics you may want to have. Many topics in these guides are not relevant to form-oriented UIs, but most of the guidelines for controls, messages, and dialog boxes have compliments for forms. There’s also guidelines for web sites, (e.g., usability.gov), but these will generally be less useful for applications.

What to Include

For the basic approach, see answers to How did you create design guidelines for your organization? To answer your specific question, I make a distinction between “elements,” or pieces of a UI (records, fields, layout, forms, command, and feedback), and “functions” (what some might call “patterns”), which assemble multiple elements into a standard UI for a common step in the user’s tasks (e.g., login, query, reports, undo, sort, zoom, help). I cover both in a style guide.

The idea of a style guide is to avoid you having to design everything yourself, so if a custom function only exists in one form, don’t include it in the style guide. However, you may want to include components or abstractions of the function that are commonly used throughout the tool or suite.

The Deliverables

Ideally, the ultimate form of the style guide should be what works best for your users –not the tool/suite users, but the developers and designers that will use the styled guide to make the tool. A style guide should make their job easier, not harder. If it’s too hard for your users to find the right guidelines for a particular case, or learn and understand them, or implement them, they’re not going to. You can apply your UX skills to making the guideline deliverables by interviewing and observing your designers and developers to find out what will work for them (in your case, you may be limited to phone interviews with your developers; better than nothing).

This implies the product may employ multiple media. Chances are the “main” product will be some sort of hyperlinked document, which has obvious advantages for reference material. However, there may also be a summary quick reference guide or checklists, printable posters to promote the guidelines and highlight key features, a library of style-guide-compatible templates / patterns / CSSs, and seminars and workshops (possibly conducted remotely) for you to personally introduce the guidelines and show their advantages for the designers and developers. Frankly, creating the guidelines is only the start. Most of the work is promoting and enforcing the guidelines. Try to get the time, budget, and organizational support for that.

  • 1
    Thanks Michael, I hadn't thought to look at OS style guides. Also thanks for the reference -- it answers the majority of my question. Sep 24, 2012 at 20:25
  • 1
    Could you elaborate on how you typically deliver documentation for projects? PDF? Website / wiki? Something else? I like the idea of creating a wiki, and I think it may work well for my purposes. Do you think this may be the right path? Sep 24, 2012 at 20:33
  • 1
    See added paragraphs above for the ideal case. In my cases, usually my audience is small, so I’ve used hyperlinked Word .doc format. For a large audience, we once made a website. Wiki technology may make building a website easy. However, normally you’re going to want more control over the product than one usually associates with Wikis. In most organizations, you simply meet personally with just two or three others to decide what the guidelines will be. Sep 25, 2012 at 12:51
  • Thanks @Michael! That's awesome. I really appreciate the updates. Very helpful! Sep 25, 2012 at 13:36

I know there's an accepted answer, and I usually do quite agree with Michael, but still this does bug my mind for two days.

As a developer, I hated the Apple HIG

It just didn't tell me what to do, how to do things in practice.

The Windows Guideline was felt as "empty", but it could be that it did because it seemed, on Windows, actually noone follows them.

Bear in mind, that I actually had to have a really intimate relationship with the Windows GUI: we were required to be able to write short Windows programs even on paper.

I knew every single widget, how it works, what's its purpose, and how can it be called. By heart, literally.

It was like a forced marriage.

Still, I didn't know how to create stunning stuff, and neither the HIG told me how to do that.

If it's not the HIG, what made OS X applications so uniformly good?

Of course, the Apple products themselves were designed marvelously, and everyone just tried to copy them. When one copy succeeded well, they copied the good parts from there as well. But devs understood the patterns because they used the apps themselves. Whenever a Windows user developer was required to do mac apps, the result was close to a complete disaster.

(If the devs aren't using the system - like, you mentioned elsewhere it's a banking software - prepare for some bad stuff)

Perhaps the good metaphors helped as well: well-designed widgets were connected to each other just like lego bricks.

But also: they had templates: you could say: it's a document based web app. It's a core data web app. I'm pretty sure the web is full of CoreData + WebView tutorials somewhere as in 2006-2007, we've just seen literally a plethora of such apps.

Design Patterns in their original 70s sense are recipes: "If you have this problem, do this": once you establish how to approach the problem, you are on a winning path.

A visual language is still a language

And the widgets are its vocabulary.

For me, bootstrap looks like this:

enter image description here

The developer is asked to write a complete letter written in this language.

Worse: the developer isn't interested in this language.

He isn't learning this for fun, he's told to use it. Some rationalization would help, but in case of a webpage's language, outsourcing, with a separate domain, no user contact, devs just won't care.

So usually what happens here is that the dev opens the vocabulary, patches things together, and submits code.

You need a complete phrasebook instead of a simple vocabulary.

Again, here, letters are to be written. In Chinese.

You need to tell, when a phrase is to be used. You need to show examples, most probably from existing applications written in the same language for the same problem domain.

Every visual language has an underlying pattern language, even if it's implicit

Alexander's classic is a good read. He was the one who introduced patterns into Engineering thinking, and through Software Engineering, it landed in UX as well. A bit off topic, but it's worth to read his IEEE talk.

What you try to achieve with a UX style guide is very-very similiar to what Alexander tried to achieve with his pattern languages: he tried to define the generics, and put the decisions into users' hands.

(Note: into the users' hands, not into the developers' hands)

But I still think recipes are important: a design pattern catalog is still a catalog of phrases. It might be that it's more like the Oxford Dictionary (containing definitions, when-to-uses and examples) rather than a simple vocabulary.

That was completely missing from the HIGs. You stood there, there were general guidelines, and you were like, "OK, so, how do I start?"

An OS HIG is not your guide, exactly because an OS HIG is written to the general case: from drawing apps to mp3 players, from mail readers to hospital catalog systems, everything could be run on an OS in theory.

The same goes for Twitter Bootstrap: it's a generic design language.

You need to find your specifics: where can you tailor the content?


What I am talking about when saying specifics?

First,you'll surely identify the patterns of the applications.

There'll be generally two kind of patterns:

  • Architectural patterns, that is, what kind of applications are there mostly (you mentioned most of them are CRUD)
  • Widget patterns, that is, you'll actually find some specific UX design patterns which can be defined either as widgets or interplay of widgets, and you'll define an according widget library to them.

You also have to specify a third category, usually strongly connected to the first:

  • Layouts

Designing Web Interfaces did an excellent job on collecting what are the typical layouts for web applications. I'd recommend the book anyway.

You need to distill this to your own cases. Especially, you'll have to find application modules which would actually benefit from these layouts, and design them fully.

Then, make developers a choice: What kind of application are you building? A Dashboard? A form system? This is the layout of a form system, these are the required elements, these are the optional elements (+when to use), this is how they should work together.

It'd be a good idea to teach devs to actually think in user flows, but I doubt it'd be an easy case to devise a full UX-oriented process, esp. if you're outsourcing.

The devs will use these if it's less effort to use it and make up something on their own than to mess it completely. That is, if you have full boilerplate codes to use, which they can just grab, it'll work fine.

Also, provide them with a set of rule of thumbs: instead of telling that "accessibility is important for people with visual impairments and contrast and color blindness and blahblah", it's much easier to follow that: "all pages must be white on black, no red paired with blue is allowed".

Sure, less fantasy, but I mean, are we building good-enough solutions, or try to make full-blown UX designers out of devs?

The downside will be that devs will echo these rules-of-thumb even after years, and they won't hear about it debunked. Examples are the 7+-1 rules (they still teach it at University!), and basically antyhing which you'll find at UX Myths No, they won't read the descriptions and constraints.

But I guess these would be someone else's problem...

  • 1
    This is a really great answer -- I appreciate the time / effort you put into it. I particularly liked the comment about devs actually using it. That's 100% dead on. The current product has no consistency because requirements are just thrown over the fence and 'product' is thrown back. Sep 27, 2012 at 13:37
  • 1
    But I'm still a bit confused about how you would approach it. Are you suggesting that a guideline isn't the right way to go? What direction would you take? Sep 27, 2012 at 13:38
  • @LorenRogers edited
    – Aadaam
    Sep 27, 2012 at 21:21

Overseas development is often code for 'poor' development. I've found no amount of style guides will resolve those issues. But that's a different topic.

As for what works, it varies wildly from team to team, project to project. As we build more complex web applications, with more complex interactions and the like, I'm finding the better path to go down is pattern/component libraries.

These are living documents and are designed as a central repository for UX, Dev and the Business. The idea is to create a central hub that everyone can pull from.

You'd identify a component that needs documenting. You mention Forms in your example, which may then have a large number of individual components. Let's take an Option Select, for instance. Your document may then contain information including:

  • Name of pattern
  • uses (when to use it, when not to use it)
  • Visual styles (colors, fonts, sizes)
  • Interaction documentation (describes the behaviors of the component)
  • alternate versions
  • sample HTML/CSS/JS (for dev team)
  • sample wireframe patterns (for UX team)
  • error states
  • accessibility requirements

The drawback? I have yet to find a product that can manage a pattern library well. I've seen it tried with SharePoint, with Axure, with Word, but all have drawbacks. The best option in terms of online tools I've seen is patternry.com which seems to have potential, but is also lacking in areas.

Barring all of that, and combining the fact that you are outsourcing development, if your team and organization can support it, really the best deliverable is the presentation layer code. No amount of paper documentation will result in a perfect translation once back from development overseas so the more you can do yourself, the more control you will end up having over the UX in the long run.

  • 1
    Overseas development depends on the sea and the side you're at. I'm surely biased towards classical European engineering, as I'm such a graduate myself, and as a former technical architect of the largest european outsourcing firm I see what's the problem with outsourcing yet it doesn't come from the talent of devs but rather the mindset which is part of outsourcing. Once they're told that their code won't be accepted unless perfect, and I'll keep them off from the stupid managers, and also from the client, quality reaches its levels where it should be at once.
    – Aadaam
    Sep 26, 2012 at 0:20
  • There are exceptions to every rule, of course, but in general 'overseas' is code for 'outsourcing' which is code for 'management is extremely cheap and cares little about quality and more about short term spreadsheets'. There ARE good outsourcing firms, of course. The big players, though, are really just puppy mills.
    – DA01
    Sep 26, 2012 at 0:37
  • 1
    EPAM is one of the world's largest ones. At the Budapest office, the interviewee dropout rate in my time was over 90% (mine, as "the" frontend interviewer was about 93%). And that is after a good CV and perfect English, and usually a VERY hard uni. Managers can sometimes switch to 'satisfy client at costs of quality' mode as code is always under the rug, but if one of our top architects were on the project, that meant quality without compromises. We did have the manpower to reach that, it's only you had to put the right incentives into force.
    – Aadaam
    Sep 26, 2012 at 0:49
  • 1
    Thanks for the good answer and interesting debate -- in my case, the overseas development is almost entirely focused on functionality. (It's a financial system, so it has to work.) I expect that our overseas office doesn't have a single 'front-end' dev, and that it's just back-end devs putting some controls on their work. In this case, would you still suggest a pattern library? (I really like the idea you've outlined, and I think that may be the direction I'll go in.) Sep 27, 2012 at 13:50
  • Ideally, you'd have a UI team building the UI...if it's part of UX, even better. But that's not always realistic. In your situation, I think the best you can do is document (pattern library) and just expect them to screw it up anyways. :)
    – DA01
    Sep 27, 2012 at 14:52

I suggest you use a framework. I use Twitter Bootstrap. It has its own style guide and guarantees a level uniformity with little effort.

  • 1
    This isn't really an answer to the OPs question about style guides. If it does have it's own style guide then you should summarize that, explain why it's suitable and link to that one. Just linking to the homepage of a framework doesn't really constitute an answer to the OPs question.
    – JonW
    Sep 26, 2012 at 8:40
  • 1
    I disagree. I think it's a valid point/answer. We've pushed for this ourselves at times.
    – DA01
    Sep 26, 2012 at 15:36
  • I see where you're going with this, but it's not practical for my particular project. This project needs a redesign on a much deeper level. Also, see @Aadaam's answer for more thoughts about bootstrap. Sep 27, 2012 at 13:40

I recently came across the one below and asked them permission to use it as an example to one I am writing myself. Permission granted:)


  • Actually, as for a UX guide, this is pretty bad. For a starter, the site itself has bad UX. It even starts with a tutorial: what am I using, a game or a website? In case you need to have a tutorial for your navigation, redesign navigation. Imagine if Amazon did tutorials... revenues would be down by 20%. Some of the advices are outright bad (error prevention), and the whole UX content is about 10% of the site, unfinished, more like a work of an enthusiastic novice than a professional. The dev part is full-fledged, it provides a twitter-bootstrap like library, but a widget is not a pattern
    – Aadaam
    Sep 26, 2012 at 0:12
  • 3
    For a UX guide, it's pretty good, IMHO. At least compared to what people usually have to work with--which is little-to-nothing.
    – DA01
    Sep 26, 2012 at 0:38
  • 2
    Granted, the guide is rough, young and iterative - but it's helping bring our government enterprise forward... The real work of UX is the day-to-day agile/iterative collaboration with project teams - we chose to let a UX Guide evolve from the daily issues encountered, regardless of how rough it started. Certainly UX folk could rip it apart, but as Loren noted in the question... it's a big messy project. Sep 26, 2012 at 2:47
  • 2
    Thanks for your answer, although can you summarize the content of this article? As this post on meta stackoverflow discusses "you haven't answered their question, you've deferred the answering to somewhere else.". If that link were to be taken down, we would lose all context. If you can summarize the article and provide the link as the citation source then you'll be providing a useful answer to the question.
    – JonW
    Sep 26, 2012 at 8:39
  • 1
    Jonw and Loren, you are both right, my answer was incomplete and not clear what the link was supposed to do. Instead, I should have written" you can write a guide, etc. ". Thank you.
    – user17508
    Sep 28, 2012 at 20:40

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.