If you're on the zeroheight blog, you probably already know the value of a design system, and there are already a lot of articles out there outlining how you can go about creating a whole system, but once you've started, a lot of folks get stumped on what exactly they should be documenting at the individual component level.
Why Design Documentation Matters
You can create the most beautiful, accessible components in the world, but they won’t be much good if the developers you are working with don’t know how to implement it, or the designers on your team don’t understand which component they should use.
Good documentation takes effort and time, not just for the initial implementation, but also the upkeep to ensure your components stay fresh and work for their required use cases. But it is worth it, as information around a design shouldn't be siloed in one person or team's head, and designs within a system need to potentially outlast the person who created them. If you need more convincing, go and read this article from our CEO Jerome over on Adobe’s blog.
Principles for Component Documentation
No matter what component you are documenting, you need to know what good looks like before you can begin. Generally speaking, there are three basic rules, these state that your documentation should be:
Whatever you choose to include when you document a component it should be the same for all other components going forward. This means that the people who will be using the system, other designers and developers, will know exactly where to go to get the information they need, whether that is understanding the spacing or guidelines on the implementation. Keeping the documentation consistent also reduces the cognitive load for the person using the system!
Your documentation should be clear for everyone using it. Assuming others are at the same level of technical knowledge as you and using industry jargon may confuse new or junior staff members. Though you can absolutely use technical terms, you should do your best to explain what each element is in language any layperson would be able to understand.
Try not to go overboard and include loads of extraneous details around your component. Every piece of information included should have a reason as to why it was included. For example, you may not need to include the CMYK of your chosen colours within your design system if you don’t have any graphic or print designers working from that system.
What to Document
One of the hardest parts of documenting a component is deciding how strict you want to be when outlining the rules for a component. Some designers find it to be limiting creatively if a component is completely inflexible in how it can be implemented. Others find it freeing to not have to worry about the small details like spacing and padding, knowing these are already decided for them. This is one thing you’ll need to decide on, not only within your design team, but also with the engineers you’re working with who may want more details than you initially plan to include. In saying that, there are some base details that are common across most systems:
What It Is
The first and most obvious thing you’ll want to do is actually say what the component is and add a short description about it. The description is important here as not everyone may know what a component is by name (see the section above on documentation clarity).
The way you name your components is often not given much thought, most people think everyone will understand what they mean if they say ‘main navigation’. But there are some components that may have a few different names depending on who you’re asking. Take a ‘tag’ for example - to one person this may mean a hashtag but to another, it may mean a specifically designed component sometimes referred to as a ’chip’ or ‘pill’. Ensuring everyone is on the same page about what your component is called will help people find that component in the design system. This is especially true with engineers, to make sure that your naming conventions don't diverge and end up in two wildly different places.
Visual Representation and Breakdown
The main thing you will need to include in your components documentation will be visual styling guides. This will need to include not only colour and typographical guides but will also have to answer questions like:
- Does it have a border? If it does, what is the thickness and colour of that border? Does this change based on different states?
- Does it have a corner radius? If yes what is the radius and is it the same on all corners?
- Does it have a shadow or other visual effect?
- Are there any size guidelines? Are there set sizes for the component or does it adapt to things like viewport height or width?
- Are there any implementation rules around the distance between it and other elements?
You can include answers to a selection or all of these things – what you do include will depend on how much information is needed for the people who use the system.
You could also call this “How It Works”. This part of the documentation should be used to explain to your colleagues how the component or pattern functions, how it changes based on different events or interactions, and any transitions it has to go through to get to these stages. You may have things like animations outlined with their own documentation elsewhere, but here you will add guidance on which animation to apply if animation is required.
Buttons are a good use-case here, as they have multiple states depending on user interaction and whether or not they are active. You will need to outline the differences between the default, hover, disabled, focused, clicked and disabled hover styling. You should also highlight any specific transitions between these states, and if these are dependent on what the two states are.
When To Use It
The next best thing you can outline is more situational details. For example, if there are specific rules around when you should use a component, these should be added here. On the flip side of this, and often as part of the when to use it section, you should also outline when not to use it (if this is known) and what you should use in its place. You can then link to the other component for ease of use.
A good example of this is outlining when you should be using a dropdown input versus a list of selectable options. You may say that for lists of 4 or more, use a dropdown, but for lists of 3 or less use inline radio buttons as options. This clarifies how and when each component can be used, and once you have it written for one element you can flip the rule and apply it to the other component.
Nice To Haves
If you have time you could provide any supporting research for your component you have done. This doesn’t have to be in the form of usability testing, but instead could be as simple as linking to articles or research by others that outline why you have created the ruleset you have. A good example of this could be providing links to NNG articles on heuristics while explaining how your component meets the guidelines set out by Jakob Nielsen, or providing WCAG audits that were conducted on the accessibility of the component. Doing this can reduce the amount of second-guessing of components, as it provides an unbiased rationale and the supporting opinion of a third party.
Another nice-to-have when documenting a component are examples of how that component will be used within the platform. This adds context to a component and can help reduce ambiguity in how it will be implemented. These examples don’t have to be full-page mockups, but can be snippets of an interface. For example, if you are documenting a text input, you could provide mockups of a short form or a modal with a text input.
These examples can help developers understand how the element should sit within its surroundings. You can also add some additional documentation here if you feel it’s necessary. For instance, how the text input should float within the modal, or the spacing between related and unrelated text inputs.
The Value of Writing About Your Designs
You may notice a large part of documenting a component is actually writing about it and articulating your design decisions well. This is an invaluable skill as a designer and will greatly help you communicate to others the reasoning behind your choices. Whatever you choose to include, it is important that you understand who will be using this documentation and write for their understanding as well as your own.