Which documentation tool for your design system?

Building a design system is a large project involving multiple complex steps. One of the most important ones requires where your documentation should live. There are different ways to host your documentation and we recently covered the main ones: in the design or dev tool directly with Figma and Storybook. But we also analyzed some documentation tools like Notion or Confluence to see how they could fit with the design system requirements. While they all have solid pros and cons, they all led to a similar conclusion: a design system is rich and complex and requires dedicated and specific solutions. 

Even if some of those tools can do the job for a design system, it’s often because you found a hacky workaround, tolerate inefficiencies, or had to build new heavy processes to make it work. But in the end, when your design system needs to scale, you’ll likely reach the limitations of each tool and need to migrate to another solution. What you thought was a time and money-saving solution turned out to be the opposite with a costly migration effort.

If you’re not convinced, let’s look at what’s needed for successful design system documentation and how well those tools fare.
Spoiler alert: zeroheight is what we suggest, obviously 😉. Still, this article is also an opportunity to compare options and help you make the best choice for your design system.

A design system is for everyone

Before delving into the specific features and technical limitations of each solution, one of the most important things to consider is how teams will access the design system.

Providing everyone access to your design system documentation

Despite being primarily used by designers and developers, it is crucial to consider your design system as a product (or an infrastructure) for your entire organization. Your design system affects many different areas, including marketing, brand, communication, product managers, high-up stakeholders, etc., and you should involve all of them in its development. 

So, if you need to train your team to edit the documentation or expect them to master some specific skills, you’re adding friction in the process and not helping with design system adoption. For example, to work with Storybook, you must be familiar with Git, have access and permission to contribute to a code repository, and know some technical concepts, such as markdown.

The same applies to Figma since non-designers without the expertise to navigate the tool effectively may struggle and feel excluded. 

Considering these requirements, anyone who wants to edit a Storybook or Figma file must have solid technical or design knowledge.

A design system shouldn’t look like this for the whole organization

You may have the best design system, but without adoption from everyone, it’s pointless and may even die because no one will use it enough to make a meaningful difference. To ensure people use the design system, teams need a simple and easy tool to document, edit, and maintain without special skills. zeroheight includes a no-code editor that’s just like using Word or Google Docs. You can try it out for free if you don’t believe us. 😉

Getting everyone to collaborate on your design system

As adoption is the key to success for your design system, having the right tools to let everyone collaborate and contribute to it is crucial. While Storybook and Figma require some specific skills to master the editing of their documentation, other tools like Confluence and Notion might be better at it. 

Those solutions offer powerful features such as inline and page comments, @-mentions, and simultaneous editing are just a few of the features to streamline communication and facilitate collaboration. However, remember that it’s usually for internal teams only, as those solutions have strictly restricted access behind a login, an SSO, or VPN authentication, especially with Confluence. This means that when you need to scale your design system and ask for external help from an agency, contractors, or freelancers, you’ll hit the limitations of these solutions. 

At zeroheight, we anticipated this need and offer you the ability to invite guest viewers to contribute to your design system, even if they’re not part of your organization. You can even choose the level of visibility for your design system: entirely private, both private and public pages or completely public.

Structuring your design system content

Even before delving into the content of your documentation, it’s essential to consider the information architecture of your system to make it easily accessible for your users. Having simple and straightforward navigation with multiple levels of hierarchy, a homepage, a footer, etc., is a good starting point. It’ll help you organize your content so it’s more structured and readable. 

While Figma lets you organize your content the way you want –even though you’re limited to the left panel navigation– it can quickly lead to a lack of structure and organization, making it more difficult to maintain and update documentation as the system expands. 

The nested folder tree navigation gives Storybook multiple levels but that can also make navigation difficult and finding what users need challenging. Because of this, developers often find themselves spending extra, valuable time organizing and categorizing their stories.
Both solutions lack advanced features such as categorizing, tagging, and searching content, which are essential in allowing users to find the information they need faster.

Solutions like Confluence and Notion are more interesting as they offer better flexibility and options to structure the content through their native navigation systems and search options. But the freedom these tool offer can easily cause you to spend hours over-architecting your system. We caution you to consider only adding a manageable amount of complexity. 

The styleguide switcher feature on zeroheight

At zeroheight, we like helping you make fewer decisions so you can focus on what matters the most: your design system content. That’s why we offer four levels of hierarchy and consistent layouts that include a header, a sidebar with categories, pages, and tabs to organize all your content. You can even create and switch between multiple styleguides if you have more complex products or multiple brands.

Design and development integrations

One of the most important features of a design system documentation platform is how it connects and synchronizes with the designers’ and developers’ tools. It’s important to consider how simple it is to upload elements, update them and kind of information the integrations provide.

Figma and Storybook are the best tools for these “integrations” since they are the direct sources, there is no debate on this topic. However, regarding documentation tools like Confluence and Notion, you have some options with benefits and drawbacks. 

Notion benefits from its native Figma embed feature, utilizing iframes to showcase UI library artboards or frames. However, there’s a limitation, this design integration doesn’t sync automatically, and bulk uploading of design elements isn’t supported. Manual updates are needed for each embedded design, which proves time-intensive for multiple elements like icons and component states. And the design systems we’ve seen easily have hundreds of components and variants!

On the development side, the limitations are even greater, mainly because it’s a lacking Storybook integration. GitHub and GitLab integrations offer syncing and displaying pull requests, issues, and code snippets. Yet, Notion’s version control lacks the precision of dedicated code versioning systems. For intricate code collaboration, developers may lean towards GitHub or GitLab’s built-in features.

Confluence’s integration for design system documentation faces challenges due to heavy reliance on external-party integrations. While Figma’s Confluence integration smoothly displays prototypes and design files, it struggles with mapping to specific components and lacks automated Figma library uploads. Non-uniform integration experiences include login prompts and rendering issues for non-Figma users. Automating uploads from Figma libraries—colors, icons, hex values—remains unaddressed, burdening the documentation process with repetitive manual work.

On the development side, while offering native code block macros for code examples with syntax highlighting, comprehensive development integration leans heavily on Atlassian Marketplace add-ons. Integrating GitHub, GitLab, or Storybook mandates this layer of third-party tools, paralleling the challenges faced in design integrations.

As a result, both design and dev integrations share a common theme: dependence on external add-ons poses risks out of your control—maintenance complexities, costs, and a lack of updates—all of which threaten documentation stability. 

Integrations with designers’ and developers’ tools are crucial for design system teams. That’s why we strive to provide the best experience for zeroheight users when uploading, syncing and maintaining styles, components and patterns in their documentation. Whether you are on Figma, Sketch or Adobe XD, we have a way to sync your design uploads with zeroheight. For our Figma users, zeroheight quickly scans your library and allows you to quickly add or update components and styles to your documentation. For Sketch and Adobe XD users, we provide our own plugins to make adding and updating elements just as easy. 

Similarly for developers our native or embedded Storybook integration that lets you connect your stories to zeroheight, display the layout you want, and update your components in a seamlessly. 

Not to mention we have several other integrations to enhance your documentation: Trello, Google Slides, YouTube, GitHub, Whimsical, Typeform, Miro and so much more!

Customizing your documentation to fit your brand

Customizing your documentation can be challenging. We have some opinions about how much time and detail your documentation platform should be customized, and the short answer is: not so much. What matters most is your content and we believe too many customization options can needlessly distract you from working on the content. But in the end, it’s all about finding the right balance between customizing and writing content. That’s why zeroheight gives you some flexibility and provides customization features to allow people customize the things that matter the most such as colors, fonts, logo, cover page, and more. You can even have your own custom domain!

Other documentation tools like Notion or Confluence don’t provide much more customization possibilities either. Notion may have more flexibility at first sight, but in the end, you mainly rely on their layout and structure unless you’re ready to invest in supercharging your Notion with paid templates.

Customizing Confluence documentation’s appearance requires coding skills. The predefined templates, layout constraints, and styling options can limit design system teams in seeking branded design system documentation. 

The same goes with Storybook’s possibilities which can be large but can also time-consuming due to intricate configuration files and resolving potential style conflicts to modify visuals or add branding elements. Looking holistically, the extra effort only provides minimal value. Not to mention, this can create an incohesive and inconsistent appearance  that doesn’t align with the organization’s brand identity. Such customization hurdles impede providing a seamless Storybook integration into documentation, complicating the delivery of a polished experience.

How to use markdown to render your documentation in Storybook

If you think Figma is great for designing your documentation platform with it’s ultimate flexibility, beware of making your design system too complex, difficult to maintain, and bloated. It is the perfect example where you can lose yourself in too many details and, therefore, neglect the heart of your design system: its documentation.

Scalability and maintenance of your design system 

In the course of preparing your design system documentation, you might not consider its scalability or how the platform will evolve over time, but this is actually very important.

If tools like Notion might seem easy to use at first sight because they don’t require specific skills and have an easy-to-use WYSIWYG interface, they might reach performance limitations quickly when your design system needs to scale. With expanding design system documentation, larger file sizes and intricate layouts might impede Notion’s performance. This could result in sluggish loading and navigation, hampering efficiency, especially for extensive design systems. Viewers might get so frustrated that they stop using the documentation altogether. (Also, consider how powerful their computers are. Some people might have older models that can’t keep up.)
A solution like zeroheight is more suitable for large and complex design systems because it renders design components as images, benefits from third-party solutions to display the embedded content in iframes, and provides a seamless and intuitive interface.

Similarly, Figma’s large files can trigger performance issues, making documentation access less straightforward and efficient for everyone. 

Organizing your Figma files for your design system is a complex topic, but keeping your design files for what they are intended will help you to keep things simpler and more efficient. And if you’re curious to know more about optimizing your design files with a solution like zeroheight, we got you covered with this article!

Solutions like Confluence or Storybook are better suited for performance optimization but less for handling the complexity of growing design systems requiring more advanced architecture and processes. 

As powerful as Storybook is, it can be just as overwhelming to maintain it. It requires substantial time to support and update it as the design system evolves.

Teams can also have trouble maintaining simplicity and ease of use over time with Confluence because of its abundant features that can burden teams focused on efficient design system documentation. 

These are the many reasons that why zeroheight strives to provide the smoothest experience possible. Our goal is to ensure teams can update, maintain and scale their design system over time, without the need to start on one tool and then realize you’d need to migrate to a more appropriate solution. We want teams to focus on innovation, not wasting time, effort, and money refactoring and migrating their design system and documentation.

So, which documentation tool should you use for your design system?

In the realm of design system documentation, choosing the right solution is a pivotal decision, often determining your design system’s efficiency and scalability over time. 

Start by identifying a tool all team members can access to documentation for successful adoption. While Figma and Storybook require specific skills, tools like Confluence and Notion enable more inclusive collaboration but fall short on external input. Then consider integrations–integrations with design and development tools are crucial, with Figma and Storybook excelling as the direct sources. Yet, Confluence and Notion have pros and cons, both having design and dev integrations. However, those heavily relying on third-party add-ons, posing risks to documentation stability. 

Next, consider your customization needs. Balancing customization and content is a challenge and while solutions can overwhelm or be inflexible keep the focus on the essential: documentation. 

Lastly, think about your design system in the long term. As design systems evolve, scalability becomes crucial. When scaling, Notion’s user-friendliness wanes, while Figma’s robustness faces limitations. Conversely, even though Confluence and Storybook focus on optimization, they lack advanced scalability solutions for easy maintenance over time. 

We’re always going to promote using zeroheight, but it’s not just because we work here. zeroheight was born with the intent to serve as a user-friendly tool that serves any design system needs from simple systems to the largest, multi-brand complex systems. 

Ultimately, the perfect tool for every design system doesn’t exist. The right solution aligns with your needs and teams. While zeroheight suits many needs, your judgment is key. This article aims to guide your decision-making, helping you ask the right questions. 

Share your experiences with us on Twitter/X or our Slack community – what solution did you use for design system documentation? Did you run into issues training people to use more technical tools? Did you end up switching from one solution to another? We’re eager to hear from you. And if you haven’t tried us yet, sign up for a free account and play with some of our features.