Write more effective design system documentation with top tips from Dan Mall, Design Systems Leader & Coach.
Design system documentation is a vital part of any design system. It provides a comprehensive guide for product designers, developers, and other stakeholders to understand how to create and maintain a consistent visual language across all digital touchpoints.
However, the process of creating effective design system documentation can be overwhelming, especially if you’re not sure where to start. That’s why we’ve created this guide to help you understand the key elements of design system documentation, best practices for creating it, and tools to help you get the job done.
Whether you’re creating a new design system or looking to improve an existing one, this guide will provide you with the knowledge and tools you need to succeed!
Design system documentation is a collection of guidelines, rules, and best practices for creating consistent, high-quality, and on-brand user interfaces. It provides a guide for designers, developers, and other stakeholders to understand how to create and maintain a unified visual language across all digital touchpoints.
What is design system documentation?
Design system documentation is a collection of guidelines, rules, and best practices for creating consistent, high-quality, and on-brand user interfaces.
The purpose of design system documentation is to ensure that all products and services are visually consistent, easy to use, and accessible to all users. By having centralized documentation, product teams can work more efficiently and effectively, without having to worry about inconsistencies in design and development.
When it comes to creating design system documentation, there are a few key elements that you should include to ensure that it is comprehensive and useful for your team. Here’s an overview of what you should include:
- Components: A detailed breakdown of each component that makes up your design system, including components like buttons, forms, typography, spacing, and more.
- Patterns: An overview of the common design patterns used throughout your system, including navigation, search, and error handling.
- Guidelines: A set of design guidelines and best practices for using your design system, including color palettes, accessibility standards, and coding practices.
- Best Practices: Best practices for using your design system in specific contexts, such as mobile devices, desktop applications, or web pages.
- Examples: Real-world examples of your design system in action, including wireframes, prototypes, and final designs.
By including these key elements in your design system documentation, you’ll be able to provide a comprehensive guide that ensures consistency across all of your digital touchpoints.
What should design system documentation include?
Effective design system documentation should be clear, concise, and comprehensive. It should provide a unified guide for designers, developers, and other stakeholders, ensuring that all digital products and services maintain a consistent visual language.
To be effective, design system documentation should include the following elements:
- Clear: The documentation should be clear and concise, making it easy for team members to find the information they need.
- Consistent: Your documentation should maintain consistency in terms of design principles, style, and language.
- Accessible: Consider the accessibility of your documentation. It should be accessible to all team members, regardless of their level of experience or ability.
- Comprehensive: Documentation should be comprehensive and cover all relevant design system elements, including components, patterns, guidelines, and best practices.
- Flexible: The documentation should be flexible enough to accommodate changes or updates to the design system over time.
- Collaborative: The documentation should facilitate collaboration among team members, allowing them to share and gather feedback, suggest improvements, and work together effectively.
What makes good documentation?
“Good documentation serves its purpose, and the purpose should be designated at the beginning of writing documentation: What do you want this documentation to do? Who is it for? How are they going to use it?” — Afiya Smith, Design Manager @ Epic Games
We know that design system documentation is important for several reasons: It promotes collaboration, reduces design debt, and helps create a scalable and flexible design system. However, writing effective documentation that’s easy to follow can be a challenge. To help you improve your documentation efforts, design systems Educator, Dan Mall, suggests changing your approach — don’t document, chronicle.
With over a decade of experience developing design systems for world-renowned brands like United Airlines, ExxonMobil, Nike, and Eventbrite, Dan Mall is considered a product design pioneer whose expertise has been imparted at conferences, private client engagements, higher education, and more.
Watch Dan’s top tip for improving your design system’s documentation.
How to improve your design system documentation
Don’t document, chronicle.
Dribbble – DS Tips – Chronicle 16×9.mp4
Dan Mall: There are usually two big things that make design system documentation difficult. First, writing it is really hard. Secondly, even when you do write it, people don’t follow it anyway. So what do you do instead? Don’t document, chronicle.
Most people write documentation first before they do anything, which is kind of like a spec, and people don’t like following specs because it’s usually unfamiliar to their workflow. That’s the key.
Instead of documenting what should be done, chronicle what has been done. This will make it much easier for people to follow your design system because you’re giving them insight into something that already works.
“Instead of documenting what should be done, chronicle what has been done.” — Dan Mall
Design system documentation can be created using a variety of tools. Here are some of the most popular options:
- Figma — Figma is a popular design tool that can be used to create design tokens, style guides, and other documentation. It also has collaboration features that make it easy for teams to work together on design system documentation.
- Zeroheight — Zeroheight is a design system documentation tool that helps increase the adoption of your design system by creating a central hub for designers, engineers, product, and marketing teams. It syncs design and code to create a single source of truth for all aspects of your design system, and allows for easy collaboration and iteration on content.
- Storybook — Storybook is a development environment for UI components. It can be used to create a living style guide that can be shared with other teams.
- Github — Github is a platform that developers use to manage and collaborate on code. It can also be used to store design system documentation, code examples, and code snippets.
When choosing a tool for creating design system documentation, it’s important to consider the team’s needs and workflow. Some tools may be more suitable for teams that work in a more design-focused environment, while others may be better for developers.
Design System Documentation Tools
There are many great use cases and examples of design system documentation available online. Here are some examples of design systems that stand out:
- Salesforce Lightning Design System – The Salesforce Lightning Design System is a comprehensive design system that includes design tokens, a living style guide, and code examples. It is well-organized and easy to navigate.
- Carbon Design System by IBM – The Carbon Design System by IBM is a great example of a well-documented design system. It includes clear guidelines, code snippets, and design assets that can be used by designers and developers.
- Atlassian Design System – The Atlassian Design System is a comprehensive design system that includes design guidelines, design tokens, and a living style guide. It also includes detailed documentation for developers.
What makes these examples stand out is their attention to detail, clarity, and comprehensive approach to component documentation. They offer a starting point for teams that are looking to create their own design system documentation.
Design System Documentation Sites
Effective design system documentation is essential for creating a cohesive and consistent user experience. By using the right tools and following best practices, teams can create documentation that is easy to use and maintain.
To get started with creating or improving your own design system documentation, consider taking Dribbble’s online Design Systems Course led by Dan Mall. This course covers everything from creating a design system to documenting it in a way that is easy for teams to use.
Become an expert in design systems
FAQ
Design system documentation should be a collaborative effort between designers, developers, and other product team members who are responsible for creating and maintaining the design system. It’s important to involve all stakeholders in the documentation process to ensure that everyone has a clear understanding of the design system and how it should be used.
Who should write design system documentation?
The primary purpose of design system documentation is to provide a reference guide for consistent design and development of a software product. The documentation outlines the design elements, principles, and patterns that make up the system, ensuring that all components are cohesive and have a consistent look and feel. Additionally, documentation helps to improve collaboration and communication among team members and stakeholders by providing a shared understanding of the design decisions made in the project.
What is the main purpose of design system documentation?
A design system is a collection of reusable components, patterns, and guidelines that are used to create a cohesive and consistent user experience across different products and platforms. A style guide is a component of a design system that focuses specifically on visual design elements such as typography, color, and imagery. While a style guide is a key part of a design system, it is just one element of a larger system that includes other components such as design tokens and guidelines.
