.svg){kind=logo}
Menu
Close
Lots of companies don’t have design systems. Even more frustrating, they do and people aren’t using them.
According to the 2023 DesignOps Benchmarking Report, 68% of product teams blame design-to-dev inefficiency on poor design system adoption. So yes, it’s a problem.
Building excellent design system documentation is critical to getting teams to adopt your design system. Everyone needs to access it, and everyone needs to understand how to use it.
The first and most important decision that designers, developers, and product owners have to make is where the documentation should live. In this article, we’ll look at the following:
But let’s start by addressing why design systems are often misunderstood, which can lead to product teams choosing the wrong tool. What even are they?
A design system is set of standards and assets to help guide, manage, and scale design work. It provides a common language between designers and developers, and a shared understanding of how design and development should be approached across different teams and projects.
Most design systems include some or all of the following:
The principal goal of a design system is to satisfy users and protect your brand by helping you keep the look and feel of your digital products and experiences consistent.
Design systems also increase the speed and efficiency of how teams design and build software. First, they make design handoff easier by eliminating the need to provide extensive technical information about every design, such as tokens and components. Second, they reduce redundancy at the implementation stage because devs don’t have to recreate elements and patterns if they’re already there in the design system.
A design system is not a user interface (UI) kit.
A UI kit is a much more focused and specific resource. It concentrates specifically on UI elements and provides tokens, components, and patterns for streamlining the design of individual screens or pages. It’s primarily concerned with “what”, not “why”.
A design system is more comprehensive, comprising the “what”, the “why”, and the “how”. It includes tokens, components, and patterns for a company’s entire product suite. But it also explains when and why they are used. Basically, it governs the entire experience users have with your products.
Frankly, your design system is the documentation. It’s not a “system” if it isn’t documented, or if parts of it are recorded in different places, or if some of the fundamentals live only in your designers' heads.
Without design system documentation, designers and developers will do as they please, and it will be difficult to maintain a consistent and coherent user experience. Here are a few of the problems likely to arise:
The other thing is that, to make sure everyone’s working from the same guidelines, a design system has to have a single source of truth. This means the design system documentation should be centralized in a tool that everyone can access and knows how to use.
Some have argued that design systems shouldn’t have a single source of truth because everyone’s working in different places. You’ve got designers defining components in Figma, writers and marketers making documentation in Confluence, quality assurance (QA) engineers checking functionality in test management tools, and developers working on the codebase. They all have different access points for the system, and shouldn’t be forced to a single destination. Rather, you should design a system to meet people where they are.
In other words, just accept that it’s going to be all over the place, and centralized documentation is impossible.
However, this kind of acceptance that a single source of truth for design systems is too difficult is exactly why they fail: because a system of disconnected parts isn’t a system. By extension, it’s why design handoffs become such a chore, and why developers and designers have a hard time getting on the same page.
So, design system documentation is necessary for your design system to work. Since your design system is supposed to function as a shared language, your people need to learn it—which they only do if it’s properly documented.
In the last section, we emphasized that design system documentation should have a single source of truth, which is why choosing the right tool to document it is so important. Here are the five main things we think you should consider when choosing a tool.
Designers and developers work in different tools and have different objectives when it comes to building apps. Therefore, a design system should live in a neutral tool that doesn’t favor one team’s experience over the other. And other teams will need to use it too, since your design system affects many areas and departments, from QA and product owners to marketing and brand to senior management.
Therefore, you should consider your design system as crucial infrastructure for your entire organization and build it in a central place that all teams have access to.
Consider how easy it is to embed designs, code, and downloadable assets, and to connect pages. If there are basic features missing, or you have to master specific skills to edit the documentation, you’re adding friction to the process that won’t help with design system adoption.
Your design system documentation should have a logical and navigable structure. Content should be predictable and discoverable, so that it’s easy to skim through the documents and find what you need.
You want your design system documentation tool to connect easily to the tools your designers and developers are using. From their respective tools, designers and devs need to be able to update components without manual duplication.
Accessibility, integrations, and ease of use all help make design system documentation scalable. So does being simple to update and maintain as the system evolves. Your chosen tool should have version control so you can track changes and revert to previous versions, along with built-in features for copying, moving, deleting, and archiving pages, and a user-friendly editing interface.
The primary thing to remember when choosing a design system documentation tool is that your design system is for everyone.
Many companies will resort to documenting their design system in a developer tool like Storybook, or a design tool like Figma.
And although Figma is great for storing Figma components, and Storybook is great for building them, is either tool suitable for documenting a design system? No. Because they fail the first test. They’re not for everyone.
Figma is for designers and a lot of non-designers don’t have the expertise to navigate the tool effectively. Storybook is for developers and, if you want to use it, you have to be familiar with Git, understand some technical basics like markdown, and be able to contribute to a code repository. Most non-devs won’t have a clue.
The last thing you want is for the barrier to adopting your design system to be the tool it lives in. But if you use Figma or Storybook, that’s exactly what you’ll get.
Figma is a design-first tool and Storybook is a code-first tool. Neither is focused on creating static written content because their true power lies in designing and rendering components.
The best design system documentation tool is a writing-first tool. In other words, a tool that’s all about creating, collaborating on, and storing static text documents and doesn’t require specialist skills to do it—like Confluence.
Confluence provides a what-you-see-is-what-you-get (WYSIWYG) rich-text editor that anyone can use. It has a hierarchical page structure, powerful search capabilities, and extensive formatting features, including headings, tables, lists, panels, expandable sections, code blocks, and the ability to embed images and videos. It also offers full version control and page history, internal linking, and collaboration features such as comments, @mentions and simultaneous editing. Its focus is on collaboration through text, designed to make it easy for teams to contribute and share written knowledge.
Importantly, Confluence integrates easily with design and development tools. For example, there are Atlassian Marketplace add-ons that enable you to embed links from Storybook, GitHub, and others.
And with CollabSoft’s Figma for Confluence, you can embed design assets from Figma in a Confluence page with a simple link. Figma itself lets you do this, but anyone working in Confluence will also need to log in to Figma. With CollabSoft’s app, Confluence users don’t need a Figma license to view Figma designs.
Using Figma links in Confluence means your components, patterns, and brand assets can live in Figma, with updates propagating to the Confluence page via a live sync. You can also download the files in whichever format you wish, directly from Figma.
A further benefit of CollabSoft’s app is that you can pin a specific version of a design to your Confluence page if you want your design system documentation to show fixed assets. This is often preferable; design system users don’t want assets to be constantly changing while they’re trying to use them. It would defeat the point of a single source of ‘truth’. However, you can only embed locked-in designs with CollabSoft’s app. With Figma’s embed option, assets are always live and will change the moment anyone tweaks them in Figma.
Basically, Confluence’s structure, formatting, collaborative features, and integration options make it well-suited for documenting your design system in an organized and scalable way.
A design system that everyone actively uses is the key to smoother design handoffs and better collaboration between designers, developers, and stakeholders. But getting everyone to use it starts with the documentation and, first and foremost, the tool you choose to make it.
Poor design system adoption is likely because so many companies resort to documenting them in tools that favor one team over another, like Figma, which is for designers, or Storybook, which is for devs. If you really want to increase engagement with your design system, you’re better off using a platform designed for everyone, like Confluence.
In our next article, we’ll explore how to build a design system in Confluence with the help of a design system documentation template.
In the meantime, learn more about improving developer-designer collaboration and simplifying design handoffs in Jira and Confluence.
You can also get some early insights from our survey about how designers like to work with developers.
A former lawyer, Berry loves theme parks, has published a sci-fi conspiracy thriller trilogy called Million Eyes to rave reviews, and is a specialist in writing content for tech companies.
