Best Practices for Documenting Design Systems

Why is it that more and more teams and businesses are creating and documenting design systems? Having a comprehensive Design System is not a momentary trend but one of the best practices design and development teams should follow in order to create consistent products, improve team collaboration, and improve communication.

Design Systems 101

A design system is, or should be, the one source of truth for rules, standards, and reusable components that will help any member of the team build applications that are cohesive, stick to branding, and work well together.

It is not enough to create separate components, save some color and typography assets, and call it a day. We need to think bigger and expect great things from our product. And for that product to eventually keep growing and be used by other designers and developers we need to - from the very beginning - set ourselves up for success.

Let us review some tips and tricks to create and document design systems that will help everyone in your team.

Best Practices

Know your users

All our products are designed based on our user's needs and wants and thinking of them when building the screens, which is great! When working on our documentation we should also consider those who will participate and interact with our Design System.

Who interacts with a design system? Not just UI/UX designers, but also UX writers, Developers, Project Managers, even people in Marketing or Sales might need to see what this documentation looks like. We do not need to create different files for documentation based on each potential user, of course, but we can have a hand in organizing elements in a way that any team member will be able to go through them and understand them.

Write an introduction page

The introduction page is always the first page we see and often the last page that we refer back to. Therefore, the introduction page of our documentation must be concise and use short sentences that are clear and to the point.

It should inform all users about the structure and include an outline of elements and dev implementations that are part of the Design System. The best introduction pages also include rules for each role in the team so that each member knows exactly how or if they can interact with the rest of the document.

Think of scalability

We are always asked to be one step ahead of user needs, wants, you name it. When documenting, we can also think ahead and plan for the project's growth. This is not necessarily a one-person task, it can be done as part of a group effort and done over time, but it is never too late (or too early) to consider how our product and its components might look and function in assorted sizes, devices, or systems.

Organize documentation

A Design System should be a living entity that never stops growing, changing, and adapting. As such, it should be concise, clear, and easy to use by all team members. All the time spent documenting will be a total waste if no one uses it.

How we organize and structure our Design System will allow others to work with it successfully across projects. We should only create components that are necessary for the project's needs, and following iterations, remove all of those that are no longer in use. Remember, our documentation must be easily accessible and understood by others.

Even though many people might take part in making changes to components and other assets, there should always be someone appointed to make sure that libraries are updated and working correctly.

Plan for accessibility

More and more, accessibility is becoming part of daily life for designers and developers. When a design is thought to be accessible it is beneficial not only for those with specific needs, but it will help everyone, and it will make our product even better.

How can we plan for accessibility? Is this even possible? Yes, it is. Making our designs accessible is not only about button sizes and color ratios. Our documentation can, of course, include those visual rules that create a path for accessible design. We can also include (in our mockups or UX writing) the necessary documentation for some specifics such as alt-text or screen readers’ information.

Design System DON'Ts

Use one document for all mocks and libraries

"The project is too small" or "we don't have time for that" are among the most common things people think or say as an excuse to not separate libraries. When working on an exceedingly small project this might work, but for large or potentially large projects we should never keep our libraries in the same document as our mockups, even worse, have components for different devices or systems in the same document.

Having all-in-one documentation will be chaos when the project grows or if it needs to be edited by other team members for other projects or devices or systems. One document will not only confuse team members such as designers or developers, but it will also slow the team down and open the door for mistakes that will affect the entire project.

Best practice: Separate Design Systems by operating systems, devices, and specific projects. And you could also separate elements in projects for handoffs with specific changes and flows (to avoid miscommunication)


Forget to name elements correctly

UI Design 101 is to name our layers, elements, and components correctly. Naming elements with titles like "submit button" or "switch" can create confusion among the team and complicate workflows when prototyping.

Remember two important things.

First: Components can and should be reusable, so a "submit button" could also be a "save button". Second: There are guidelines and rules for each operating system such as Material Design and Human Interface about name elements and those names are common knowledge.
For you it might be easy to call an element "switch," but people on the team might not know what that refers to if the standard name is "toggle".

Best practice: Learn and use correct naming based on the platform or system you are designing for; this will help everyone on the team working on the project. Designers will know which elements are created or missing from the library and Developers will know the type of element they need to create.


Forget to create components with variants

Many design tools have the option to combine components and create variants. If we name our components and variants correctly, at the time of use, it will be a lot easier to work with them.
It will be easier to find the assets we are looking for when building screens.

Best practice: You could name components like this: Component/Type/State/Size/Icon/Split. When combining them, management will be easier.


Not expect collaboration

Not documenting correctly, not naming correctly, not organizing elements could work for us if we work alone, 100%. But if someone else on our team needs to use our files, our "organized chaos" will just be chaos for them.

If we expect the project to grow, or if we know that it will move to another department at some point (development for example), it is imperative that we keep collaboration in mind when creating our libraries and screens.

Best practice: Document, name and organize assets, mockups, and flows.


We hope these tips and tricks will help you and your team create more cohesive design systems that help to improve productivity and communication all around. Contact us to grow and improve the UX/UI of your products.

About Encora

Fast-growing tech companies partner with Encora to outsource product development and drive growth. Contact us to learn more about our software engineering capabilities.


Share this post

Table of Contents