User Interface Style Guides: Component Base vs Screen Based

Question

We are in the process of updating some of our creative processes and outputs within our company and one of the items we have been experimenting with is the way we generate our UI Style Guide for the developers and partners.

In the past we have built really extensive documents for each screen in the application or website. Your typical screen shot with pixel perfect dimensions and call outs that everyone has seen before. There have been a pain to create for a long time and in most cases become out dated very quickly.

We want to start implementing a Component Base Style Guide that specifies how UI component and/or patterns should be implements vs having to apply specific instructions on every single UI screen. We think this will create more efficiencies and provide a better documentation for the development teams and make it easier for us to keep updated (especially with Responsive Design).

Our goal is to eventually stop producing the static PDF style guides and build HTML version. But our first step is to produce the PDF version and slowly phase into an HTML.

We have tried this with one major project and it was pretty successful. We built the static PDF component base style guide and we had our UI developers build an HTML version of each component. Than our second development team used the HTML document when building out pages. There were a few minor issues but mostly due to the developers not following the style guide and doing their own thing.

However, we tried this on a smaller project and it was hard for the developers to comprehend. I would say it was 70% successful but required the designers to spend more time with the developers to provide feedback or direction on some pages. This could possibly be a skill set issue on the developers part we are just not sure.

There are many links talking about this particular topic but I wanted to see what other folks in the same situation are experiencing. Is it helping? Are you seeing improvements? Any issues you have encountered?

Answer 1

Why not create a PSD of your UI elements. For example this is the UI Guide created by Teehan+Lax for the site Medium.

Answer 2

My development team produces a living style guide that serves both of the purposes you mention. We don't bother with anything like a Photoshop file or a PDF guide because these fall out of date quickly and require work to translate to your production medium (HTML).

Using HTML, you can produce a living template that shows off the proper usage of all your components as well as being an example of your overall page styles. We use ours as both a showcase and a jumping off point for all of our development projects. The best part of using your production medium as your style guide is that it's easy for developers to just inspect the template to see the proper way to do things. Making your style guide implement your style guide gives you the benefit of "dogfooding" and validates that your styles are production-ready.

A great example of a living style guide (albeit being more focused on components than overall style) is the Bootstrap documentation site.

Answer 3

One thought is audience. You mention developers, but do you have a QA Team as well? How about the people writing the requirements?

The reason I mention the other audience members, or users of the 'documentation' is that their needs can differ.

We use to use a word/ .chm file, text based, when I started. For my team, I took key elements and turned them into visuals via visio (psds are great for this though), building custom components, and annotating details to address styles, standards, and visual identity.

This allows the BAs/ Product Managers and QAs, as well as developers, a visual comp for what they design.

Eventually, we will migrate to all HTML and produce some representative static annotated guides. So no matter how you get there, if you have people whose purpose is not to reuse the code but to understand the design standards, there is benefit in some static output.

Answer 4

I would not suggest doing a screen-based style guide, but I would recommend doing a visual .png comp of each view - one image with notation and one without. The notation points to customized elements, but mostly the view can be built by referencing a central online style guide.

I have been phasing in a component-based, living (HTML) UI style guide at our company. It is arranged by element type (with an anchor menu for quick access) and each element has corresponding HTML code.

Having a senior front-end developer has been crucial in bridging the gap between design and development.

As I design the interfaces, I isolate and notate the components, which are then built by the front end developer, and the completed components go into the style guide online. We have a single, "starter" style sheet that all teams can use, including QA.

I have meetings with QA and team leads to make sure they know about new developments. I also pair with front end developers at times to hone and craft the components together. I make sure to draw up new interfaces from existing styles instead of creating new ones (We have 16 text styles (made from 2 custom fonts), 7 main colors, 6 shades of gray, and a system red, green and blue. )

Even though our first draft has just font styles, colors, and a handful of elements, this process and the living, online style sheet have streamlined many processes, and the visual quality and consistency across products is very noticeable. My visual notation step has become very simple, and in some cases unnecessary.