< back to all blog posts

How We Document Deep Dive: Starting Design Systems

Article title

Out of over 500 respondents, we learned quite a lot about design systems and documentation for our How We Document (HWD) 2023 report. (If you haven’t seen the report, it’s available for free on our website.) Some of our insights surprised us. While design systems have been around for a while, we learned that many design systems that people working on them are relatively new.

In some ways, this makes sense – especially if you’re working at a new startup, on a new product, or are finally aligning to one overarching system. Even if you have experience working on design systems, the landscape continues to change with new tools, technologies, and best practices. So it can feel like you’re almost starting all over again.

Let’s look at the report and what this means for you and your team. We’ll also mention highlights from our companion webinar, How We Document: Starting design systems: Navigating the Beginning. Our webinar, hosted by our Design Advocate Jules Mahé, featured Julien Vanière, Senior Director at Sage, and Lily Dart, Group Design Director at Photobox. They both had excellent advice for starters!

It’s not too late to be a design system maker

If you haven’t worked on or created a design system yet, it’s not too late! Most of our respondents (44%) have worked on design systems for only 1-3 years. You’re in good company if you haven’t started by now or are just starting. There’s no need to feel that you’ve missed out by not starting sooner. As mentioned, the tools and technology keep changing, so everyone continuously adapts and learns.

Page 9 of how we document showing that 44% have 1-3 years of design system experience

Starting ALL THE THINGS sooner

All the things meme - crazy character yelling with their fist in the air

We found that most design systems (39%) and most documentation (49%) were under a year old. We learned that 51% of respondents use design tokens in some manner. This indicates that, from the start, teams see design systems as comprehensive ecosystems of design, code, documentation, and new methods like tokens. As opposed to years ago when the priority was to make a UI library, then in a few years write documentation, then eventually add in tokens.

While it’s great to see the recognition of a comprehensive ecosystem, where does one start? In the webinar, Lily mentioned clearly understanding the expectations and defining the scope with stakeholders. That will help you figure out what you should focus on. Sometimes an audit can help baseline where things currently stand and can help inform the scope and expectations.

Lily recommends thinking of things holistically rather than atomically. So, your team should ask, “Do we know what it will look like when everything is all together?” When you can identify the North Star and key principles of the experience, you can then decide what to support. Depending on your product, company, or use case, you might want to support documentation, example pages, or content.

Julien also mentioned he has his team consider the Pareto Principle or the 80/20 rule, where you can achieve 80% of your commitment with just 20% of your time. Conversely, he mentioned you could spend 80% of your time and only make a 20% impact. For example, if a designer continuously refines a button to the point where the changes are so minor and unnoticeable, they have spent 80% of the time making a  20% impact. Meanwhile, several other components need to be made. If that designer doesn’t focus on absolute perfection, with only 20% of their time, they can make an 80% impact—getting a whole set of “good enough” components in the hands of designers.

When starting, think of how to make the most impact with the least effort. That could mean documenting component usage guidelines as bullet points—enough for the team to keep moving confidently.

Create a team

We learned from the report that most (61%) companies have a design system team. About half of those have a team with dedicated employees, and the other half comprises of partially-resourced teammates. When you have some semblance of a team with allocated time for the design system, you can get the work done better.

Julien and Lily both mentioned not having a developer on their team immediately. Lily built enough trust and bartered front-end dev work in exchange for design work. Even though you might not be able to get a dedicated team, you may have to get creative in your approach to building that team. As you build your team, consider following what our respondents reported for their team makeup. On average, teams under a year old had three designers, three developers, one product manager, and one content writer.

Working on documentation

Based on our survey, the most popular documentation tools were:

  • The design tool itself (Adobe XD, Figma, Sketch) – 54%
  • Storybook – 47%
  • zeroheight (try it for free) – 41%

Page 30 - the most popular documentation tools

We allowed respondents to select multiple tools for their responses because documentation can live in multiple places. We also found that Storybook and zeroheight were the most popular documentation tool combination. We’re not entirely surprised since zeroheight plays nicely with Storybook. 😉

Using tools that can help streamline your team’s workflow can make design system creation and adoption easier. But sometimes, you’re limited to only using approved software for your organization. If that’s the case, feel free to get creative and use what’s available to keep things moving.

From our report, the top 5 common items that documentation includes are:

  • Color
  • Atomic components (e.g., buttons, dropdowns, checkboxes)
  • Typography
  • Brand guidelines
  • Form details

If you need help prioritizing, consider those aspects as a starting point. We also have guidance on prioritizing componentsPage 33 of the HWD report lists other aspects you can consider when documenting.

While most people who contribute to the documentation are designers, engineers, content people, PMs, and others, all play a hand in documenting. This can provide a well-rounded perspective to make documentation easy to understand. To determine what your team needs in their documentation, you can host a workshop to help define it.

Get people into contributing and governance

Based on our report, about a third of respondents have a contribution model (with varying degrees of success), and about a third are working on starting one. We found similar results with a governance process. We encourage you to start thinking about contribution and governance processes sooner than later to avoid reaching a pain point where you desperately need them. When everyone can contribute, you can get an IKEA effect with more ownership, accountability, and adoption.

In the webinar, Lily mentioned that she tries to get people working with the design system as soon as possible. The more “business as usual” it becomes, the easier it will be to adopt into their workflows. When she worked at a highly form-based organization, her priority was creating form components so teams could get used to using them. This allowed her to continue to evolve the design system and introduce other processes more readily.

The sooner you can start getting people used to contribution and governance, the easier it will be for them to adopt into their everyday workflow. If you wait years or months until your library is complete, you risk teams forming habits you might not have intended – and it can be tough to change those habits. This isn’t to say you must have a well-defined contribution and governance process. Having “good enough” processes compatible with how teams work today can ease the transition. If you need help defining processes, consider working with a Design Program Manager (DPM) to help brainstorm solutions.

Do you want to scale over time? Measure and build trust

Most respondents don’t track metrics on their documentation, nor do they have key performance indicators for them. But repeatedly, our design advocates are asked for ways teams can measure the success of their design system. Metrics like adoption are a big interest in helping demonstrate value. To get buy-in from stakeholders for more resources, they like to see numbers and understand the value in terms of efficiency, money saved, etc.

We have a few articles to help get you thinking about measuring your design system, including considerations when measuring from a development perspective.

Additionally, Julien and Lily said that getting traction with a design system requires a lot of trust. Designers and developers won’t adopt the design system if they don’t trust you and your decisions. When you build that trust, they can understand your intent. While they might not be happy about the change, they will be willing to make it because they trust you. Trust can lead to having additional advocates for your design system efforts. Sometimes their voice can resonate more strongly with stakeholders to help you get what you need.

Making your case for design systems

If you need to make a case for design systems, our report has some data to help. We learned that respondents acknowledged that their design system:

  • Makes their product more consistent (86%)
  • Increases design efficiency (81%)
  • Increases the speed of product development (73%)
  • Makes their product portfolio more consistent (71%)
  • Increases developer efficiency (69%)
  • Makes collaboration seamless between designers and developers (66%)

We also learned that documentation is an excellent source of truth, onboarding, and confidence. Our report has specific percentages, and we encourage you to leverage this data when making your case.

Page 49 about documentation being great for truth, onboarding, and confidence

Proceed with caution

Starting a design system is an exciting time for any team. The idea of efficiency, consistency, and collaboration can motivate everyone to rush to the finish line. We asked Lily and Julien what advice they’d give to people starting a design system. Lily mentioned not to expect too much too fast because it makes getting burnt out easy. As you think of small things (like a component), they can lead to more and more questions.

Earlier Julien mentioned that he feels like, after three years of working on Sage’s design system, they’re just now evolving out of the starting phase. While these anecdotes don’t intend to discourage, it’s a reminder that design systems constantly evolve, so there’s no need to rush to the finish line. Julien’s advice included a quote from Mark Twain, “Continuous improvement is better than delayed perfection.” We think that’s wise advice for anyone starting design systems.

We invite you to check out the complete report for full insights and encourage you to view the webinar to hear other great advice from Julien and Lily.