Lesson 4: Document and manage your system

Welcome back!

In the previous lesson, we saw the Habitz team build out aspects of their design system in Figma.

In this lesson, let’s learn a few ways to support the ongoing success of your design system, like:

• Effective documentation
• Improving your system through testing, feedback, and contributions
• How to manage updates
• How to make sure people are using it

Chapter 1: Documentation

If you want to win the hearts of your design system consumers, effective documentation is a must.

What is documentation?

In the previous lesson, Kai and the Habitz team defined some naming conventions and wrote descriptions for styles and components. But documentation can go beyond this. For example, you could:

• Include examples for correct and incorrect uses of a pattern 
  
• Use a change log to track component updates
  
• Add code examples or links to developer implementation
  

Effective documentation anticipates the needs of its consumers and is presented in a way that speaks directly to them. For example, developers might need to cross-reference tokens and properties, while writers need guidance on crafting error messages.

Think about what parts of your system might need extra context. What might different audiences benefit from knowing?

Where should documentation live?

Where your documentation lives, and how easy it is to find it, can also impact how effective it is. We often see design systems living on dedicated websites, like Google’s Material Design or Atlassian’s Design System. 

Websites are great if you’re looking for something highly customizable, and can be necessary for larger companies with many products. However, they require resources to build and maintain. If you’re a small team, this may be a dealbreaker for you.

Instead, using tools like Storybook or Notion, or housing documentation in the same place as your design system, might get you up and running sooner.

Documentation in Figma

The Habitz team uses a modified version of an 8 point grid system. They want to explicitly communicate that information, outside of their styles and components.

They’ve created some elements that capture their common spacing values. This lets designers know which values to use, and better aligns designs with code.

You may have noticed that these spatial definitions aren’t components. That’s because these assets aren’t intended to be used in designs.

Rather, they are illustrations for people to visualize empty space, and exist to document system decisions and give consumers a reference point.

Spatial systems also set the basis for other things like layout grids, padding, and as this documentation suggests, nudge values in Figma.

Chapter 2: Improve your system

So you’ve built out solutions and created documentation. What’s next? It’s time to get it into the hands of your consumers to validate your design system and refine its solutions.

Testing and gathering feedback helps us understand what’s working and what needs improvement. This can be done at any point in your process, even while you’re building the system.

Remember that design systems will evolve over time. The information you gather will be valuable even if you don’t have a finished system in place.

Test with consumers

One of the most common testing methods is conducting user interviews, which can be done one-on-one or in a group; virtual or in person.

Before you start, determine what you want to evaluate and what you’d like to get from your participants. Knowing this helps you select people who will provide the most valuable insights.

If you have multiple groups of participants, pay attention to user flows and problems unique to each one. Turn them into tasks for participants to complete—like recreating screens and modals, or testing the search experience.

Ask for feedback

User testing is a proactive way to gather insights on design system performance. However, you may also benefit from establishing a channel for ongoing feedback, especially as your company grows.

Feedback can be collected in various ways. For example, surveys are great for asking targeted questions to gather the details you need. Or, people can drop comments in a design file, or vote on options in a FigJam file for asynchronous feedback.

Choose the approach that works best for you and your company’s workflow.

Keep in mind that change can be difficult. If people express frustration, use that feedback as an opportunity to evolve your design system. Keep listening for ways to improve and encourage people to share their thoughts.

Manage contributions

Feedback is great at identifying issues but who implements the fixes? If you want to empower your design system's consumers to make improvements themselves, establish a contribution process.

A contribution process establishes a path for contributors to take their suggestions from proposal to implementation. It includes timelines, guidance on what to do, and information on how to align your solution to design system goals, visual requirements, and more.

An effective contribution process benefits your team by handling the onboarding and knowledge sharing to ensure that contributions are consistent with the design system.

The process you develop will depend on your company’s size and the needs of your team. Every system should have an internal contribution process, intended for those already maintaining the design system.

You may also want a process for people who aren’t on the design system team. This requires more guidance and resources and any feedback may require a more rigorous review. Enabling participation from people who actually use the system on a daily basis is a great way to support its success.

Chapter 3: Updates and releases

Versions and changelogs

Your design system is bound to go through iterations from all the testing, usage, and feedback you’re getting! Changelogsare a great way to track these updates.

Each version update gets its own change log entry with what’s new, what’s changed, bug fixes, and a version number to help reference specific iterations.

Version numbers should follow a versioning scheme for consistency and to convey information about the update.

Semantic versioning

One of the most common schemes is semantic versioning, often recognized by its pattern of numbers separated by decimals: 1.6.2.

They’re structured in the Major.Minor.Patch pattern, which refer to types of changes. Each type is represented by its own version number that increases by 1 anytime a relevant change happens.

• Major changes refer to updates that break existing designs and are not backwards compatible. Like large changes in visual style, or removal of components. 
• Minor changes are updates without breaking changes that can flow seamlessly into existing designs
• Patches refer to bug fixes without breaking changes. This could be incorrect padding values, component names that don’t match code, or bug fixes.

Branching and merging

When we make improvements, we need to be mindful of the impact this will have on anyone using the system.

If you’re working with a small team, with only a few contributors, you could coordinate those updates within your group. But if you’re in a larger organization, there are likely more people using the design system who will be impacted by changes or updates.

In software development, developers branch off from the main code base into a controlled environment to experiment, test new code, and make updates. This allows developers to explore solutions without any downstream impact.

Changes from a branch go through a review process, where they can be accepted or denied. Approved changes are then merged into the main code base and then deployed as a single version or release.

We can follow this exact approach for our design system—make our changes in a separate environment so as to not disrupt those using the current version.

Chapter 4: Advocate for your system

If you want people to use a design system, advocate for it by sharing, raising awareness, and educating others on its value. Get people excited and invested in its success by showing how it can help them.

Advocating for a design system can happen at various stages of the process, even before the first version is complete. In fact, we recommend starting early!

Gather information from different teams on what pain points they run into. Present your work-in-progress at all hands to generate excitement and to get interested people involved.

You can also find low-effort ways of raising awareness like mentioning it in conversation with coworkers or dropping a message in a wider channel.

By the time you finish your design system, you’ll have an audience that is already eager to adopt and advocate for it.

What was your biggest take away? What do you want to learn about next? If you have an idea for another course you’d like to see, we’d love to hear that too.