Design teams are discovering that a well-built design pattern library makes the user interface development process substantially easier. A quality library means team members have the information they need at their fingertips. Choosing usable components that work smoothly for users becomes the developer's path of least resistance. Innovation, while not prohibited, is reserved for those times when it's really necessary, allowing the team to leverage the work already done by others.

Our research suggests one difficulty in building out the design pattern library is starting to catalog the current set of elements. It takes a push from the library creators, but once it's completed, the value seems to be immediate: teams can start to discuss what works and what doesn't in current designs, laying out a vision for future development.

What do teams put into their design pattern descriptions? Here's what our research has turned up:

'Pattern Name' Section

If we were talking about a component to log a user into the password-protected portion of the site, we might name it the "Username and Password Widget", the "Two-line Sign-in Elements", or the "Login Component".

Choosing the name carefully is quite important. Traditionally, many components appear in designs without having a name, leading to discussions which contain statements like, "You know, those little box thingies we always have on the left." The goal of the pattern name is to encourage clear communication in meetings, design documents, and other places where people may want to call this component out on its own.

We've seen that naming a pattern takes skill, creativity, and a little bit of luck. Teams may start out with one name, only to find later another name has become the common parlance.

For example, one team officially named their application's object attribute editor the "Infobox" only to find that nobody on the team every referred to it as that. They all were calling it "Properties" instead.

Some teams add a list of nicknames, synonyms, and also-known-as names (aka "aka") to the pattern's description. This helps team members know what they're talking about. What we call things change over time, so keeping the pattern name updated to reflect the current lexicon turns out to be helpful.

'Description' Section

Teams find the description is essential for a good pattern. It allows team members, who may be unfamiliar with the component, know exactly what we're talking about.

Pictures are worth a thousand words, so we've seen that screenshots can be very valuable here. When a given pattern may have different manifestations, multiple images can help.

Our login component might have this description (along with appropriate screenshots):

"A two-line form component we use to collect the user's user ID and password, so they can gain access to the password-protected portions of the web site."

Descriptions don't have to be major literary works, but it does help to have enough information to explain why the element exists and how to distinguish it from other elements found around the site.

'Context of Use' Section

One of the key benefits of a design pattern over a style guide or guideline document is the heavy emphasis on the context of use of each element in the library. Designers, when considering a new design, use the context description to determine if a particular pattern is appropriate.

The context for our login component might say:

"We use this whenever a user might wish to transition from the public-facing portion of the site to access their private information. This pattern will appear on public facing sites when there is enough real estate for a 155-pixel by 210-pixel block."

Part of the context needs to talk about when it's not used:

"On public-facing pages where there isn't available vertical space, we use the 'Single-Line Login Component' in the banner bar.

"We don't use a login component on pages in the password-protected portion of the site."

Contexts are living creatures. As the team builds more components, develops new applications, and discovers new user requirements, this section will require frequent updating. Ideally, at any point in the pattern's life time, a designer can read through this section and immediately know that this element is right (or wrong) for the job at hand.

'Where Used' Section

Another living portion of the document, the Where Used section is updated every time the pattern makes it into a production system. Team members can look at existing implementations of the pattern and see it in action.

'How It Works' Section

In the How It Works section, teams describe the mechanics of the component:

"Users enter their user ID into the type-in box labeled 'Username'. They enter their password into the type-in box labeled 'Password' (which obscures what they type). If they choose, they can click the 'Remember me' checkbox, which will pre-fill the username on the next visit. When ready, the user presses the button labeled 'Login'. If the username and password is valid, their personal welcome page is displayed. If not, an error message is displayed. (See the Login Error pattern.)"

The amount of detail necessary will depend on the complexity of the control and the familiarity team members can have. (If it's a component they personally use all of the time, it probably doesn't need as much description as one they've rarely encountered on their own.) One team showed us how they use a video capture utility to create short demonstration videos of the components in action, which they reference in this section.

Mentioning other patterns that interact with this one helps the designer understand what else they'll need to consider when they are putting their design together.

'Specifications' Section

The Specifications section contains everything a designer or implementer might need to add it to the design. Dimensions, fonts, text sizes, specific wording for labels and messages, colors, and line widths are all specified here. (A screenshot of the element with callouts listing all the details can be especially effective.)

'Co-requisites' Section

It's rare that a pattern stands alone. The presence of one pattern usually indicates that the designer will need other patterns to support it.

For example, if a design requires our login component pattern, then it will likely need:

  • A pattern for creating a new user id
  • A pattern for changing the password
  • A pattern for recovering a lost password
  • A pattern to logout of the password-protected portion of the site
  • A pattern to display an error message when the wrong username/password combination is entered

All of these patterns are listed in the Co-requisites section along with any explanations as to why they might be required (if it's not obvious).

'Related Patterns' Section

In addition to co-requisites, there may be other patterns that are similar to this one. Most will be patterns that have similar goals or behaviors, but are used in different contexts.

For example, a related pattern to our two-line login component would be a single-line login component that we use in "tighter" spaces.

'Competitive Approaches' Section

It's unlikely that we're the first ones to need the component described in the pattern. The Competitive Approaches details what others have done in their designs complete with screen shots.

Any time a team member discovers an interesting alternative, they just slip a description and a picture into this section.

'History' Section

This section serves as the official log of the pattern. It starts with the information about who created it and why. If the pattern is a derivation of another pattern, that's mentioned here.

As things evolve, this section helps designers understand the changes that the pattern has undergone. Detailed rationales help give new team members insight into the evolution of the pattern. This is most important when user feedback has proven the initial obvious design approach didn't quite meet all necessary requirements.

'Source Code' Section

Some teams have found that their architecture is modular enough to allow them to include the actual source code in the pattern description. This can shorten the translation time from design to implementation dramatically.

Unfortunately, not all patterns or architectures lend themselves to this ability. We expect to see more of this as reusable components become more of a reality in our development processes.

'Usability Results and User Feedback' Section

Something that seems like a good idea often needs refinement once real users interact with it. This section is where the team stores all the feedback they've received about the pattern's usage.

For example, we might see an entry such as this for a previous version of our design:

"Usability test (12/10/2005): 3 out of 8 users didn't realize that the 'Login' link was required to press to login to the system. All three mentioned they were looking for something that looked like a button. Recommendation: Make link into button. (Implemented 1/5/2006.)"

In addition to usability test results, this section can include feedback from customer support, sales, and any other sources that indicate how users might feel about the design. Tracking what's been addressed and what is still outstanding makes it easy to see the current status of the pattern.

'Discussion' Section

Teams tell us that one of the most exciting benefits of a pattern library is the discussion that takes place about design and using the various patterns. Facilitating that discussion in the pattern descriptions themselves is a great way to keep the process of design alive.

Make It Yours

As we looked at different team's libraries, we discovered no two teams took an identical approach. The pattern library has to reflect the culture of design in the organization.

In some organizations, the people implementing applications and web sites just "want to be told what to do". In these instances, the pattern library is more centralized and feels more like a corporate practices document.

In other organizations, the library takes on a more collaborative 'wiki' feel to it, with everyone contributing and working in a consensus-driven environment. Anyone can make changes and groups decide what they want to keep and what isn't going to make it.

The sections described in this article are just suggestions. If you're starting your own library, you'll want to decide what will work best for your team's needs.

The Path of Least Resistance

Our research shows that the most successful pattern libraries have one thing in common: using them is the path of least resistance when creating a new design. To do this, teams need to make each pattern description be detailed enough to plug into any new designs coming down the pike.

Design patterns are a very powerful approach to getting the all the designers in the organization on the same page. They have a heavy initial cost, but we've seen that many teams find the value returned from the investment to be quite worth it.

 Share this article with a friend/colleague.