


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.

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:
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.

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.
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:
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.

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:
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:
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.
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:
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.

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.
