Help Center

How to define and document patterns in your design system

Michelle Chin

Your design system team created components UI libraries for design and code, wrote some documentation, and life is good. But now people are asking about patterns or patterns are on the roadmap anyway.

But where do you get started? What are patterns anyway? How do you even begin to start documenting them? If questions like those are spinning in your mind, keep reading this article. We’ll dive into the basics of patterns, what they mean for your products, and how to document and maintain them.

Understanding patterns

Component vs. Patterns

What are patterns? Before defining the term “pattern,” let’s look at the word “component.” Components are very prescriptive UI elements that don’t have much flexibility around their look, interaction, or usage.

For example, buttons have very prescriptive details, including specific:

• Colors
• Typography – font family, size, weight
• Border thickness
• Radius
• Sizing – padding, height, etc.
• Usage guidelines – primary vs. secondary, types of buttons, etc.

Patterns, on the other hand, are vague elements. They include guidelines that allow for more flexibility and decision-making by the designer. Patterns can also have prescriptive aspects, too.

For example, an empty state as a pattern includes

• Prescriptive details around the order of information, illustration, and components
• Flexibility with layouts (e.g., a description is optional, background depends)

The main difference between patterns and components is the level and flexibility provided within a UI element. For example, a pop-up modal can be a pattern if there’s complete flexibility in its sizing. Or it’s a component because it has explicit dimensions. In the latter case, that could be considered a complex component. Complex components are components consisting of smaller components. But we’ll help you determine what’s suitable for your product in a little bit.

Pattern types

With patterns there are two types:

• Layout patterns
  Layout patterns guide how things display on a screen (e.g., modals, empty states, address form, main menus).
• Workflow patterns
  Workflow patterns are the sequence of typical steps for a workflow (e.g., a login or forgot password flow, adding an item, completing an install wizard).

Defining what a pattern is

Now that you understand the idea of patterns, let’s talk about what patterns mean for your design system. A clear definition allows the team to align and have the right expectations. In terms of what the actual definition is, that depends on several factors. And ultimately, it’s something only your design system team can define. But we can help you navigate that!

Here are a few questions you want to consider:

1. Do you want patterns to include only layout or workflow patterns or both?
   You can also say it’ll only have layout patterns for now and eventually include workflow patterns.
2. Do you want fairly prescriptive and complex elements included as patterns or complex components?

   For example, a modal might be fairly prescriptive in all design and usage details, and the only flexibility might be in what the heading, body copy, and button labels say. The team might consider this a complex component instead of a pattern.

   On the other hand, a pattern with prescriptive and complex elements could be an empty state. An empty state might have prescriptive details on heading styles, spacing, and buttons. But because empty states can appear in various areas (blank screen, blank data table, blank dashboard squares, etc.) and come in different sizes, the team might consider it a pattern.

3. What constitutes a pattern? Think about location, frequency of use, or age.
   Beyond the typical definition, is a pattern established when three or more products use it? Is it a pattern if it’s in the flagship product (because all other products should align with the flagship product)? Is a pattern established after it’s lived in a product for six months and has proven usability?

Consider vetting your answers with what you see and experience with your products. This can help you tweak your definition. Your definition doesn’t have to be permanent, but instead, it should be long-term and ready to evolve as the need arises.

Determining where patterns live

For design tools

Regarding design tools, some of your patterns might live there as UI components. But it also depends on the team’s definition of a pattern. If options have a lot of flexibility, you might not want to create a component that’s too prescriptive that people must detach their instance from the component.

For more flexible patterns, you may only want to include more prescriptive components and leave the rest of the layout for the designer to create using existing styles and pattern guidelines.

For development tools

In terms of patterns in code, work with your engineering teams to see if anything can or should live in a UI code library. Depending on the teams, products, codebases, etc., engineering might want to avoid having a code library with patterns that offer a lot of flexibility because it would be best to have it coded on an as-needed basis.

In the documentation site

Regardless of your definition of patterns, their details should live in your design system documentation. Many design system documentation sites will have a separate section for patterns. If your patterns live in a primary or flagship product’s design system and other products should leverage them, consider using synced pages or shortcut tiles to reference them in their design systems.

Documenting patterns

For the most part, documenting patterns is similar to documenting components. But as your team documents patterns, remember that patterns should prescribe details when necessary and allow for flexibility to accommodate a variety of situations.

Prescriptive elements could include details around UI aspects such as:

• Color
• Line weight
• Spacing
• Specific language (e.g., “This field is required.”)

Guidelines are general rules or advice that offer more flexibility in areas. For example, with

• Voice and tone, the guidance could be, “If there’s an error, sound positive.”
• Guidance for UI elements might sound like, “For this pattern, you can include up to two buttons.”
• Workflow patterns, the guidance could be, “Install wizards should have at least three steps, but no more than seven.”
• When to use them, for example, “Use the compressed dashboard layout for IT admins, but not everyday employee users.”

As you document guidance, focus the information on what pattern details exist today. Avoid making guidelines or rules for things that don’t exist. It’ll just lead to documentation bloat.

For example, in your products, empty states contain a heading and a call to action. Some products have empty states that include a description. For your documentation, you’d note that empty states should contain at least a heading and a call to action, but a description is optional. Because illustrations currently don’t exist in the product’s empty states, you wouldn’t write guidance about including them, regardless of how nice they might be. (Eventually, you could add that as an update to your documentation. And how that works would depend on your team’s governance process.)

Things to include in your documentation

Here’s a high-level list of what to consider when documenting your patterns. Not all items will apply to all patterns or your products. (Let us know if you thought of others we could add to this list!)

• Usage guidelines
  • Why and when to use the pattern
  • Do’s and don’t’s of using the pattern
• Writing guidelines
  • Voice and tone for messaging if specific to the pattern
  • Prescriptive messages, if applicable
  • Writing patterns such as “[Error code] means that [definition]”
• Interaction behaviors
  • Description of the interaction with the pattern or flow
  • Prototype or animation of the interaction (e.g., gif, video, etc.)
  • Do’s and don’t’s for interacting with the pattern
• “In the wild” examples
  • Screenshots and links to areas using the pattern – They are especially helpful for people to see where the patterns are uniform and how they vary.
• Accessibility
  • Details on tab order, navigation controls, etc., work with the pattern
  • Other considerations, UI elements, etc., that are in place for accessibility
• Localization, responsiveness
  • Expectations on how the pattern adjusts when the text is longer, the screen is narrower, there’s more content, or it’s translated to a different language.
• Edge-case scenarios
  • If there are specific edge cases for using or not using the pattern, include the details and the reason for why. Avoid making up edge cases for unlikely situations. Instead, document them when the product comes across them.
• Reference to user research
  • Adding any information or links to usability studies for the pattern – this is helpful for additional context.
• Developer-specific information
  • When possible, add dev-specific information within these categories
  • Depending on implementation or other factors, a separate section might be necessary. This is especially true if they can’t have a code library because of the flexibility a pattern can have. Work with your dev teams to see what would be helpful for them.
• Historical context for decisions
  • Because of the flexibility offered, it’s helpful to provide some context with how the team arrived at this pattern or the decisions made in this pattern. If a team needs to deviate from the pattern, they’ll know what to consider, or they can avoid running into the same issues the original pattern resolved.

Who should document patterns?

Depending on your design system’s governance and contribution model can affect who documents patterns. Since we recommend documenting existing patterns first, consider collaborating with the designers and engineers who worked on those screens. They might have additional insight into prescriptive and flexible guidance that can inform the documentation.

Examples of pattern documentation

Here are some examples of pattern documentation that we love. If you have others, please let us know. We’d love to expand this list!

• IBM’s Carbon Design System (example of their Empty state)
• Salesforce’s Lightning Design System – see the items under Design Guidelines (example of their Empty state)
• Gov.UK’s patterns
• NewsKit’s Design System
• Orbit by Kiwi.com

Implementing patterns

Because of the flexibility available in patterns, it can be daunting to figure out what patterns to include in your design system. We have some approaches you can take to help provide focus when it comes to implementing patterns.

Audit and prioritize patterns

Based on your definition of what makes a pattern, look at the relevant products and see if you can find some patterns that form naturally. Take screenshots of them and put them in a whiteboard tool like Miro or Figjam. Once you have a handful of patterns roughly identified, start to prioritize which ones you’ll document first.

When prioritizing, consider how frequently designers include the pattern in design work. This isn’t the same as how often a pattern appears in the products. For example, the login pattern appears whenever a user accesses your app. But the design team rarely works on updating those screens, so they wouldn’t need the pattern immediately. If your organization creates new features frequently, you might want to prioritize the new-feature tutorial pattern.

Pilot your pattern pages

As you start creating your pattern documentation, document one or two patterns and seek feedback from design system designers, developers, and product teams that consume your design system. This way, you can see what’s helpful or missing from the documentation.

Balance pattern definition and existing inconsistencies

You may notice that you can create some pattern guidelines but that some existing screens won’t follow the guidelines you’re establishing. Depending on your goal and scenario, that might be OK. For example, the outlier is in a legacy product that will be retired at the end of the year. However, if you’re working toward alignment, you might decide that, at some point, that outlier screen needs updating. In that case, consider tracking those and adding them to the backlog.

Maintaining patterns

As you define and document your patterns, continue to seek feedback from the people that use your design system. They can provide feedback on the helpfulness of the guidelines, if there’s an opportunity to be more strict or flexible, etc. They can also help identify new patterns, too.

Consider how often you need to revisit patterns. For the most part, pattern guidelines can have long lifespans. (The BBC’s Gel Design System’s pattern page has some patterns that are several years old!) However, some of your pattern’s prescriptive details might need updating as design trends change.

Share your thoughts

Have you documented patterns already? We’d love to hear your thoughts and if we missed anything. We’d love to see your pattern documentation, too. Many teams are in the process of documenting their patterns, and it can be tough to find good examples. So we’re more than happy to share them to help inspire others.

If you’re in the process of documenting patterns, let us know how it’s going or if you have questions. We’re happy to chat because we love nerding out about this stuff! Say hello on zheroes, our zeroheight Slack community.