Should you document your design system in Figma?
Jules Mahe
Documentation is the heart of a successful design system, but when it comes to deciding where to host the documentation, various options are available. Over the next few articles, we’ll review common tools that people try documenting with to help you understand the pros and cons of these solutions. This series should provide you with the necessary info to make your decision about your documentation process.
You may have considered using design tools to document your design system, and that is what we will discuss in this first article. While it may seem like an attractive option, let’s see why relying solely on a Figma file for documentation may bring some potential limitations and challenges for your design system.
A design system should be owned by everyone
Documentation access
One of the main drawbacks of documenting a design system within a Figma file is the limited access and collaboration options. Figma is primarily a design tool, and while it excels in enabling real-time collaboration among designers, its capabilities for non-designers are limited. Stakeholders, developers, product owners, brand, marketing, communication and content strategists who rely on the design system documentation may not have access to Figma (and might also mean acquiring additional licenses.) Typically, non-designers don’t have the expertise to navigate the tool effectively. This restricts their ability to explore and understand the design system fully.
Collaboration and adoption
Having access to the documentation isn’t the only issue, you may also face a big obstacle with collaboration and ultimately to adoption. If your team needs specific skills or training to access, edit and maintain your design system documentation, you’re creating a barrier to entry. This friction point will not help your design system get adopted. And adoption is the key to a successful design system, so limit the obstacles preventing this in your organization.
A design system is mainly about content
Content flexibility
Design system documentation often includes various types of content, such as guidelines, code snippets, best practices, dos and don’ts and usage examples. Storing all this content exclusively within a Figma file can make it challenging to structure and find specific information. Although Figma allows users to add text and comments, it lacks advanced features such as categorizing, tagging, and searching content, which are essentially in allowing users to find the information they need more quickly.
Content for everyone
Limiting your documentation to Figma also restricts your audience, as you don’t want your documentation to be only design-oriented. Your documentation should cover the needs of everyone in your organization: designers, developers, brand, communication, etc. Make sure you consider all the people involved in your design system and what kind of documentation they require. Moreover, design systems already suffer from the stigma of being only for designers. Refrain from fueling this idea by integrating your design system with a design tool.
Content versioning
Design systems evolve over time, with updates and refinements introduced to accommodate changing requirements and improved user experiences. Managing version control and documenting changes can be challenging within a Figma file. While Figma offers version history, branching and commenting features, they primarily focus on design iterations rather than maintaining a comprehensive changelog or version history for documentation purposes. Design system documentation benefits from a version control system that allows for clear tracking of changes, rollback options, different version levels (design system level, page level, component level) and easy collaboration among team members.
A design system needs to scale
Documentation architecture
As design systems grow and mature, so does the need for well-organized and scalable documentation. Relying strictly on a Figma file can lead to a lack of structure and organization, making it harder to maintain and update the documentation as the system expands. Without a dedicated documentation platform, it becomes difficult to ensure consistency, keep track of deprecated components, or provide detailed explanations for complex design patterns. A comprehensive documentation system allows for easy updates, cross-linking between related components, and efficient maintenance even as the design system evolves.
Performance issues
That’s not even taking into account the performance issues you may encounter if you create a particularly complex and heavy Figma file. As a result, it will be more challenging to access your documentation simply and efficiently, and only some have access to computers that can handle the most complex files but you need everyone to be able to access your design system, no matter their technical and performance requirements. See how the Microsoft Teams UI Kit with documentation takes up too much memory usage as soon as you install the file.
So, should you document your design system in Figma?
What it really costs
While centralizing your documentation in one place and limiting the number of tools can make sense at first sight, you need to think of the long term. Although Figma provides excellent tools for designing and prototyping, using it solely for documenting a design system can result in many limitations. It might be tempting when you start your design system, but as soon as you scale, you’ll face issues too big that Figma can’t solve. As a result, the savings you think you had with documenting in Figma will be short-lived once it becomes more effort to maintain at scale and when you’re eventually forced to migrate to a better solution. But the bigger risk isn’t just about money. If you take too long to upgrade, bad habits will form, and moving to a tool will come with collaboration issues and in the end, adoption friction, which might even condemn your design system to be forgotten. Moreover, it’s better to invest in a dedicated tool specializing in design system documentation (like zeroheight 😉) early on because you’ll eventually have to upgrade. This allows ample time for the team to form good habits and scale the design system easily when the time is right.
Use tools as intended
We are lucky to have many powerful tools to help us with our design system processes. Even though it’s easy to “hack” those tools and take them away from their original purpose, we encourage you to use tools as intended to benefit from their full potential. The lack of access for non-designers, content flexibility, versioning capabilities, and scalability concerns make all the notetaking, dev-focused and other tools less than ideal for comprehensive design system documentation. We’ll dive into more specific why in future articles. For design system documentation, use true design system documentation tools like zeroheight to provide all the things you and your colleagues need to use a design system successfully. Also, we’re always curious to see how people manage their design systems, so if you tried documenting your design system in a design tool, we’d love to hear your thoughts: have you struggled with it or have you been successful? Shout us on Twitter or our Slack community to share your experience!