When's the right time to start documenting your design system?

Amy Hupe
Written by Amy Hupe
Oct 1, 2025

As a design systems consultant who specializes in documentation, organizations often ask me, “When is the right time to start documenting our design system?”.

The content designer in me wants to yell, “Right away!”, but the reality is a little more nuanced.

In this article, I’ll explain the different shapes that documentation can take, and what you should expect to have in place at each stage of your design system’s lifecycle. 

What do we mean when we say documentation?

In the world of design systems, the word “documentation” often means different things to different people. 

What one team refers to as its documentation could be a Figma library, depicting specifications for common components and design patterns. For another team, documentation could mean written guidelines, hosted on a dedicated website, explaining how and when to use the things the system contains.

“Documentation” could, in fact, mean any or all of the following things, depending on who you’re asking:

  • Written usage guidance for designers or developers
  • A summary of the research and testing carried out on components and design patterns
  • A style guide giving values for brand colors, spacing scales, and typography
  • A Figma library of shared design assets
  • Component README files
  • Technical documentation explaining how to install or update the design system

When we plan documentation, it’s important to get a shared understanding of which types we intend to create. To decide on the best approach, we also need to consider where we are in our design system journey. 

Abstract illustration depicting an infinity symbol intertwined with gears and arrows, representing continuous processes and interconnected systems on a vibrant red background.

The type of documentation we need changes with each stage of our design system’s lifecycle

The very first thing we should do when beginning work on our documentation is to understand what stage of maturity our design system is at and what needs we have to meet at each particular point in time.

If we’re just starting to think about shared solutions, the goal of our documentation may be more about creating visibility and providing a space to find and add existing components and design patterns.

As our design system becomes more formalized and mature, we’ll likely need to provide more explicit guidance on using the system itself and the individual things it contains. 

Let’s take a look at three high-level stages of a design system and explore what kind of documentation we might need at each one. 

Stage 1: “We don’t have a formal design system, but we want to start reducing duplication of effort and creating shared solutions.”

Most design systems I’ve encountered begin life as informal, side-of-desk efforts to reduce duplication of effort and create consistency across an organization’s digital landscape.

At this stage – especially without an official, central design system team – the main goal of any documentation is to stem the flow of wheel-reinventing design work by making teams’ existing UI more visible.

For example, before the GOV.UK design system was created, teams across the UK government shared component and pattern examples and research findings in Hackpad – a collaborative wiki that was subsequently acquired by Dropbox. 

The specific tool we use to do this should be guided by what our organization already uses. If all of the designers in our organization work in Figma, for instance, it may make sense for us to create a shared space there. If we already keep a research library or style guide in Dropbox or Confluence, that might be a better place to start. 

The bottom line is that it’s about meeting people where they are – the more we can do to reduce the number of new tools and spaces we’re asking teams to use, the better.

Wherever we end up collating our examples, it’s a good idea to document similar information for each component or design pattern we add. This helps teams to compare solutions and choose the right one for their context. Broadly speaking, it’s helpful to provide:

  • An image or screenshot of the component or pattern in question
  • A brief description of what it does and how it’s used
  • Details of any research and testing done to validate the approach, including any obvious gaps
  • Links to relevant Figma and code files to help other teams use or at least recreate the solution in their context

Once we’ve agreed on what information we’ll aim to provide for each example we collect, we can either proactively retrieve that information by talking to the relevant teams or individuals, or create a template that allows teams to submit it to us in a consistent format. 

Stage 2: “We’re starting to create reusable components and design patterns to use across our organization.”

This is the point in our journey where we’re intentionally creating common solutions for teams to use. At this stage, each reusable asset our design system contains needs to be documented with:

  • A common name (I recommend using conventional names where they exist, and naming things as descriptively as possible otherwise)
  • A brief description of the component or pattern and its use case
  • Links to Figma instances and code packages
  • Guidance on when to use it (and when not to, where relevant)
  • Design and technical specifications 
  • Guidance explaining how the component or pattern works, and how and when to use different configuration options or variants
  • Details of any research and testing done to validate the component or design pattern

Even at this early stage, it’s useful to capture this information in a consistent, predictable structure, so that users can find what they need more quickly and easily. 

Additionally, we’ll likely need to provide some information about the system itself, such as:

  • Contact information for the team or individual to get in touch with in case they have any questions or need support.
  • The system’s status – for example, is it relatively comprehensive or very much an early work-in-progress?
  • Expectations around who should use the system and how – for example, is it intended for everyone to use, or is it only available to some people within a private beta? 

At this stage, it’s helpful to have a centralized location – usually a dedicated website – to host this documentation. However, if funding or capacity doesn’t allow for that just now, using a shared space in something like Confluence, GitHub, or Dropbox Paper is better than nothing. 

Stage 3: “We’ve got a working design system, and we want teams in our organization to use it.”

Once our design system has reached a reasonable level of maturity, our documentation will become more of a fully fledged product that forms part of our overall system. 

In terms of the information we’ll need to include, it will likely cover everything mentioned at stage 2, as well as:

  • Clear onboarding guidance for new users – at this stage, it’s far less practical to rely on human-to-human support to get people set up.
  • Contribution guidelines – users of a more mature system will usually expect, at the very least, a way to provide feedback on the system’s efficacy and its contents.
  • Release notes, including how to install updates and migrate to new versions of the system.

At this point in our journey, it’s also useful to consider the functionality of our documentation. At stages 1 and 2, we may be able to manage everything manually. However, once we have a mature system, we’ll likely want to consider enlisting the support of automated solutions. For example, to pull color tokens in from their source and display their names and swatches on our docs site or to pull through component demos from our codebase. 

Obviously, if you're using zeroheight, this is all baked in, whether it's referencing tokens in the documentation, pulling up token tables, or importing storybook. I've heard from a little bird that they're also working on some exciting documentation automation features as well to make this process even smoother and more automated.

Finally, once we have a mature design system, it’s critical that we incorporate documentation into our wider processes for making additions and updates. Documentation, when treated as an afterthought, is at risk of falling behind and creating confusion for our users. Ensuring documentation is updated and reviewed as an essential part of our release process helps to avoid any discrepancies.

Illustration of a person in a striped shirt holding an envelope, gazing out at a pink-hued sea with a distant lighthouse on the horizon. The artwork conveys themes of communication and longing.

So… when’s the right time to document your design system?

In short, it’s never too early to start documenting a design system, but the way in which we do that can and should take into account where we are in our journey.

In the beginning, some basic information captured in informal, collaborative spaces can help to curb duplication of effort and begin a practice of sharing and reusing solutions.

As our system matures, our documentation needs to keep pace, becoming more thorough, more directive, and leaning on smart solutions to help us keep on top of our maintenance overhead. 

However, if you’re worried your documentation is falling behind, fear not – any effort to improve your docs, at any point, is worthwhile. Take encouragement from the old Chinese proverb: “The best time to plant a tree was 20 years ago. The second best time is now.”

Amy is currently on the hunt for new clients. Need support with your design system documentation? Get in touch with Amy.

Amy Hupe
Amy Hupe
Amy Hupe is a UK-based design systems and content design consultant. Over the past 8 years, she's worked on design systems for some of the biggest names around, including GOV.UK, BT, Springer Nature, the BBC, and the Wellcome Trust.
Try zeroheight
The design systems platform that keeps teams and agents in sync
Start for free
Share this post