4 min read

·

Aug 21, 2024

At Visibuild, our team’s design system is gradually becoming a backbone of our projects, ensuring consistency, efficiency, and collaboration. However, when documentation isn’t easily accessible, it can create roadblocks, slow down progress, and frustrate everyone involved. That’s why we’ve made a significant shift in how we manage our design system documentation. By moving everything into Figma, we’re streamlining our workflow, reducing confusion, and better supporting our team’s daily needs.

Before we made the switch to Figma, our design system docs lived in Notion. We thought it would be a great central resource for the team, but it turned out that wasn’t the case. To figure out why, we ran a survey and the results were pretty clear.

Many of our designers and developers weren’t even aware that the Notion docs existed, and those who did know found it too much of a hassle to leave Figma to access them. Since Figma had naturally become the central hub for all our design work, switching over to Notion felt like an unnecessary extra step. Because of this, our documentation was largely ignored, and the team kept coming to system maintainers for answers.

It wasn’t just our gut feeling, either. Our survey findings were backed up by industry reports like Supernova’s State of Components and Tokens, which showed similar trends across other teams. The message was loud and clear: if your documentation isn’t where people are already working, it’s likely to get overlooked.

This disconnect set off a frustrating cycle. The design system maintainers were getting bombarded with the same questions over and over, and team members were left without easy access to the info they needed. It became obvious that, no matter how thorough our docs were, they weren’t hitting the mark because they weren’t in the right place.

It’s important to recognise that the approach we’ve taken is tailored specifically to Visibuild’s needs. In our case, the team’s preference to remain within Figma was clear, and moving our documentation there addressed a critical pain point. However, this approach might not be universally applicable. Other companies might have different tools or workflows where their team members are more comfortable and effective. For instance, some organisations might use tools other than Figma for documentation or have limited access to Figma. The key takeaway here is to adapt the solution to fit your team’s needs and the tools they primarily use.

Seeing that Figma was the team’s go-to tool, we knew we had to meet them where they were. So, we made the call to shift all our documentation directly into Figma. This move wasn’t just about convenience; it was about making our documentation more useful, more accessible, and ultimately, more effective.

Our Figma-first documentation now includes:

Status Indicators: We’ve added clear status indicators for each component, showing whether a component is healthy and ready to use, if there are known issues, if it’s deprecated, or if it’s still in the design phase without a code counterpart. This helps the team quickly understand the state of each component and plan their work accordingly.

Cross-System Links: Where applicable, we’ve linked out to other resources like Storybook, providing a seamless connection to our broader ecosystem of tools and documentation.

Component Types: We’ve created detailed documentation for each component type, ensuring that users can easily identify and understand the different variations available.

Component Properties: Each component’s properties are clearly outlined in Figma. This includes information on how each property works, any configurable options, and how they affect the design.

Usage Guidelines: Detailed instructions on how to properly use each component in Figma, including tips for navigating any complexities, ensure that our designs are implemented correctly and consistently.

Shifting our design documents to Figma, we’ve seen a significant drop in the number of questions coming to the design system maintainers. The team is now more self-sufficient, finding the information they need directly within the tool they’re using. This shift has allowed the maintainers to redirect their focus toward more strategic work, such as refining the design system, developing new components, and enhancing overall user experience.

As a result, the team is empowered to make informed design decisions more independently, leading to a smoother, more efficient design process that benefits everyone involved.”