Scrum Agile Project Management

Lessons Learned from Building a Design System

Although it has been among the trending topics for a few years, the Design System subject doesn’t seem it’s vanishing from discussions between designers and developers anytime soon. And there is a reason for that.

Author: Rhanna Andrade, Labcodes,

Building a Design System involves much more than just creating a library of UI elements. It’s a process that must consider many other factors, such as the purpose, the tools and the people who will use that library. It’s like being able to reflect all the values of the company, whose Design System will serve, in a documentation that must be intelligible to whom it’s intended. Knowing that there is the possibility of making products and experiences more cohesive, and more consistent flows is one of the main reasons why this is still a hot topic and with many referenced cases out there.

Here at Labcodes we believe that, to achieve successful results, we need to master the process. We use agile methodology on a daily basis, as well as design and development best practices, so this project was no different. We cherish that both the Design and Development teams, who would be involved with this task, participated in all the stages and were 100% aware of each decision. As the designers also participated in the implementation of the UI, the need for communication between the two teams was irrefutable.

Lessons Learned from Building a Design System

When we started our own DS, we thought about what steps we would follow to ensure that our result was not just another component library, after all, what would be our differential if that was the case? Then, we started by defining our principles.

When you have guidelines that are in conflict, then you have to go back to the principles and decide which are more important.

Lori Kaplan – Atlassian

This was an important step for us not to get lost during the activity. Having these guidelines so tightly tied was our guide for many decision-making moments. And yes, it would have been very easy to get lost when we started to grow the list of components that we would like to build for the alpha1 version. Still, in many ways we ended up learning from our mistakes (a very effective way to learn, right?) and I would like to share 5 lessons we learned from the creation of our early Design System.

A square for me is a square for you.

I believe that design and development work better together when our namespace, tools, and models are in sync. When we reduce mental overhead, teams don’t have to compromise on quality, even while they build and ship features fast.

John Choura – Designer and developer

Documentation is one of the most important things in a project like this, often separating it from a simple component’s library. If we want to facilitate the use of assets, we must give a clear indication of what their purpose is and how it should be used.

Since we don’t want the documentation getting lost in the variety of proper terms of each party involved in the project, we think it’s important that everyone speaks the same language. When we were thinking about buttons, for example, what we were calling Primary did not bring the same understanding to the Developers team. It’s amazing how a simple term can change the context and interpretation of a documentation, so making sure that everyone is on the same page in relation to nomenclatures is a good start for the documentation to fulfill its purpose.

Prioritization: If it isn’t going to be used, why bother creating it?

It’s very easy for us to get excited when we start working on a new task. We spent weeks embracing that content and envisioning the thousand possibilities that can be generated. In this context, wanting to start by doing something robust seems like a seductive path.

Knowing how to prioritize tasks can be difficult when this means giving up activities we like. Defining the scope at the beginning can be the turning point between having a first deliverable that, like any Design System, will grow and go through iterations, or having a project that never leaves the paper.

Clients, colleagues, and stakeholders should embrace the pliable nature of the digital world to create living design systems that adapt to the ever-shifting nature of the medium, user needs, and the needs of the business.

Brad Frost – Author, Atomic Design

It’s difficult to end something if we try to predict all the hypothetical situations that we want to contemplate. Spoiler alert! You will never guess all the scenarios, and the sooner you test what you already have, the sooner you will discover this.

There’s no Magic bullet tool

At Labcodes, we use Figma to develop the UI for our products, so the decision to use it for the Design System was easy. In this tool, the files created are in the cloud, allowing the entire team to have live access to the most updated version of the project. There are numerous advantages to using Figma, but version control is not one of them. Believe me, for a system that is expected to grow constantly, this is the type of control that is essential.

For our version management, we thought it was better to create our own internal flow, which will be the subject of a next post.

For building and documentation, we chose the Storybook, which is already very popular and hosts many other Design Systems. The tool that helps to organize in a practical way the visual, the code, and the component’s usage information, comes in handy to test what was created in a playground environment. This was an option in which we were able to have a single place to build, review, test, document and later disseminate our results.

Although it’s popular, we had a lot of difficulties styling the tool, realizing that there is a deficit of more specific documentation on some topics. At first, we thought that the problems came to light because we were “subverting” its function, but the truth is that the tool proposes to do everything we demand from it. Despite the love-hate relationship with Storybook, we decided to stand by our choice and make the most of what it can offer us. The truth is that no tool will be perfect. It’s important to know what’s really necessary and what’s only desirable when making these choices and deal with the limitations with serendipity.

Rules must not be written in stone

Design System should be a team’s empowerment and synchronization tool, not a way of creating absolute truths. While much is said that DS documentation should be the “source of truth of the company”, that source can and should be challenged whenever necessary. That’s why people say that this is a living project, changing whenever something points out that it should be changed.

I’m not saying that one should suggest changing something just because. Considering that what was created must adapt to the most diverse scenarios, it is OK not to take into account a specific context and to have to revisit some decisions for the components being more versatile and reusable.

Remember: the decisions made in the project must be made in order to facilitate the work of Designers and Devs, not to make them prisoners of them.

Is front-end also Design?

During much of my experience as a Designer, I worked with prints. The more experienced I became, the more I understood that it was useless to have crazy ideas if there was no way to execute them graphically. Knowing papers, methods and printing costs was essential.

Working with digital products is not that different. Why propose something, if it will hardly be implemented, or if the cost of implementation does not justify its gains in user experience? Knowing how to communicate with the Developers team can help a lot when managing the Design System project. This is probably a premise that is valuable in all contexts of digital products, but it’s worth remembering that DS drinks from the functional nature of programming.

Programming by nature is functional, reusable, extensible, and version controlled. Modern design systems aim to accomplish much of the same and more, and therefore can take direction from how programming already functions. John Choura – Designer and developer

Having said all that, it’s important to remember that each scenario has its peculiarities. These were some lessons that I had and that made sense to me and my team, being part of a personal experience. Anyway, I have a hunch that many teams involved in a Design System project, whether in large or small companies, found themselves in very similar situations. I hope these lessons learned can serve you as much as they served me :).


* A comprehensive guide to design systems
* Stack mirroring: Designing for code and coding for design
* Building your design system

About the Author

Rhanna Andradeis a Graphic Designer, UI Designer and Art Director currently based in Brazil. This article was originaly published on under the Creative Commons Attribution 4.0 International license.