Should you document your design system in Notion?
Jules Mahe
Previously, we explored documentation directly within designer and developer tools to better understand the pros and cons of documenting with Figma and Storybook, respectively. In this article, we’ll focus on using a documentation tool like Notion for your design system. Notion is a powerful tool for notetaking, documentation and task management. It includes many features to build good information architecture, embed rich content, and collaborate easily, etc. Even though it isn’t primarily a design system documentation platform, it’s easy to see why people might use it that way.
Is it enough for your design system? Is it powerful enough to scale? Are there any limitations and blockers you might encounter? Let’s explore the possibilities of using Notion as your design system documentation.
A very affordable solution at first sight
Notion offers multiple plans to suit different needs and team sizes. This includes a robust free plan that provides attractive features for design system documentation. This plan allows unlimited page creation and organization, making it ideal for anyone. Users can structure design system guidelines and component libraries using various content formats. Additionally, the free plan allows up to 10 guests for collaboration, a valuable benefit for involving stakeholders and contributors without additional costs.
Leveraging Notion for design system documentation becomes even more advantageous if an organization already uses the tool for other purposes. Integrating it into the existing workflow streamlines processes, promotes consistency, and minimizes the learning curve for team members, ensuring cost-effectiveness.
However, as the design system scales, it’s crucial to consider Notion’s limitations, which may hinder performance and efficiency. The need for design-specific features and seamless integration with design and dev tools will quickly become essential. Consequently, migrating to a specialized solution like zeroheight will eventually be necessary, incurring potential costs and disruptions.
While Notion is an excellent entry-level option, teams should anticipate the long-term expenses of transitioning to a more comprehensive platform to effectively accommodate a growing design system.
A flexible and rich solution
Notion’s flexibility allows design teams to create and structure their design system documentation to suit their unique needs. The ability to use various content formats, including text, images, tables, and more, makes it possible to present guidelines, component libraries, and design principles in a visually appealing manner. Various resources have customizable templates and layouts to enhance user experience and promote efficient knowledge sharing.
Moreover, Notion’s hierarchical organization system and intuitive interface simplify the navigation of complex design system documentation. Nested pages, tags, and folders enable users to categorize and locate specific components or sections easily. With its subfolders and pages organized neatly in the left-hand navigation menu, you can easily reorganize, locate, add, remove, and alter the design system. This user-friendly organization enhances the usability of the design system documentation. It becomes easy to quickly find and reference the information they need, enhancing productivity and collaboration.
However, it’s essential to be mindful that Notion might have limitations regarding high-level customization, especially for branding purposes. While it offers some customization features, teams shouldn’t expect to be super flexible and make their Notion documentation aligned with their brand. Balancing the trade-off between customization and ease of use is crucial for harnessing the full potential of Notion for design system documentation.
A good collaboration solution
Notion’s collaborative features facilitate seamless teamwork within design projects. Multiple team members can simultaneously edit, comment, and provide feedback on design system documentation, fostering open communication and idea-sharing. This real-time collaboration streamlines the design process and ensures everyone is on the same page. Designers, developers, stakeholders, and more can collaborate effectively, reducing communication gaps and promoting a cohesive design vision.
Centralizing design system documentation in Notion creates a single source of truth for the entire team, enhancing consistency, enabling efficient onboarding, and minimizing confusion. This centralized knowledge base allows everyone to access and contribute to the documentation easily.Â
A very simple tool
Notion remains a remarkably user-friendly and straightforward tool for developing a design system documentation platform. Its intuitive interface and drag-and-drop functionality make organizing design guidelines, components pages, and best practices a breeze.
One of Notion’s standout features is its ability to easily transform this documentation into a public website. By selecting the “Publish” option, you can convert your Notion pages into public websites, sharing essential information with stakeholders, developers, and other team members and making it public seamlessly.
This WYSIWYG (What You See Is What You Get) approach allows design system creators to visualize their documentation as they build it, providing a convenient and efficient solution to showcase and manage the design system effectively without the need for extensive coding or technical expertise.
Integration with design and tech tools
Notion offers a wide variety of integrations for many different tools: analytics, communication, design, engineering, productivity, project management, etc. Integrations of particular interest to us for design systems documentation are mainly those on the design and tech sides.
On the design side, there is a large offer with integrations of Figma, Sketch, Adobe XD and more. These design integrations allow for the synchronization of design system assets, ensuring the documentation reflects the latest components and patterns. It may, however, require manual efforts for certain tasks such as updating all assets in Notion one by one. Indeed, since the view of the design does not automatically sync and you can‘t upload a package of design elements at once, you need to manually go into each embed design to update them. Something that can be very time-consuming if you need to make changes for a whole icon library or a component with all its states, themes, sizes, and variations, for example. A smooth and efficient process is crucial, as many teams have limited resources to update their design system; so a manual update process could result in their documentation falling behind quickly.
Moreover, the design integration doesn’t provide much more information about your design upload, such as styles used, nested components, name of the component, version history, etc. As a result, it’s only good for having a view of your design, but you can’t expect much more of it.
On the dev side, there are fewer possibilities as you’re limited to GitHub and GitLab integrations only. Notion can sync and display pull requests, issues, and code snippets from GitHub or GitLab repositories, streamlining workflows and centralizing collaboration. Real-time updates ensure that documentation remains up-to-date with the latest development progress. However, Notion’s version control lacks the granularity of dedicated code versioning systems, and for complex code collaboration, developers may prefer using GitHub or GitLab’s native features. Integration setup may require configuration and familiarity with Notion and GitHub/GitLab settings. Teams should carefully consider their specific needs and workflows to strike the right balance between leveraging Notion’s documentation capabilities and utilizing the comprehensive collaboration features of GitHub or GitLab.
There is also no Storybook integration right now, which is a bummer since it is a very popular solution used by many developers in design systems teams. One way to achieve this is to do a workaround by “hacking” the Embed option to render a Storybook component. However, it requires having public access to this Storybook link and you may not have the possibility to use the knobs and actions Storybook offers. Therefore, similar to design integrations, it’s only good for viewing your coded elements, but you can’t do more with it.
Performance and Scalability
As the design system documentation grows, Notion’s performance may be affected, particularly with larger file sizes and complex layouts. Slow loading times and navigation difficulties may occur, impacting the efficiency of design workflows for more extensive design systems. Teams with large-scale design systems should assess Notion’s performance capabilities and consider dedicated design system management tools (like zeroheight 😉) that can handle scalability needs.
Conclusion
Notion proves to be a powerful tool in general. For design system documentation, its affordability, flexibility, and rich collaboration features make it an attractive choice for smaller teams and entry-level projects. Centralizing design system documentation in Notion enhances team collaboration, consistency, and knowledge sharing.
However, as the design system scales, it’s crucial to be aware of Notion’s limitations, including potential performance issues and the need for design and dev-specific features. As the design system landscape evolves, teams must carefully assess their needs, anticipate growth, and select the most suitable tools for building and maintaining a successful design system documentation platform. Organizations should identify which problems Notion can solve with documentation and which issues are more appropriately solved by another tool or process before committing Notion. Migrating to a specialized solution like zeroheight will become necessary for larger design systems to ensure seamless scalability and robust functionality.
We’re eager to hear from those who have tried building their documentation on Notion and invite them to share their experiences with us on Twitter (X?) and our zheroes Slack community.