desinni.dev | Building a Design System: Lessons Learned

Challenge accepted 💪

This code seems familiar to you? Does it feel like with every new feature, you have to create a new, slightly different variation of the same component? Does it make you feel like you are repeating yourself and digging yourself into a hole?

.card {
  border-radius: 4px;
  padding: 8px;
}

.card--big {
  border-radius: 12px;
  padding: 16px;
}

.card--more-rounded {
  border-radius: 32px;
}

.card--biggest {
  border-radius: 24px;
  padding: 32px;
}

If you answered yes to any of these questions, you are not alone. We have been there too. 🙋‍♀️

At the company, we didn't have a design system. We had some reusable components that developers were putting in our UI library because they thought they could be reusable, but there were no official documentation or design guidelines. The Design System is a collection of reusable components, design patterns, and guidelines. It is a perfect tool for creating consistent and accessible products. And we were missing that.

After the company hired new designers, one started working on the guidelines and documentation for the design system. So the design part started moving, but the development side was not started yet - it needed a leader. That's where I came in - I was offered to take that role.

I knew it would be a challenge, but I accepted it.

So, what were the challenges? 🤷‍♀️

Here are some of the general challenges we faced while working on the design system:

1. Project had no structure

It was a brand-new project, so we had no structure or a plan of attack in advance. I had to think of meetings we would need, how to create and manage tasks, invite and onboard developers, etc. So the start of the project was a bit slow and rocky.

2. Low priority of this side project

Building a design system was not a priority for the company. As we do not have 1000s of developers, we couldn't just drop everything, separate some developers from their teams, and start working on the design system. So we struggled a bit with not having dedicated time to work on it. It was just a side project.

3. Lack of time and human power

As I mentioned, we didn't have enough developers to work on the project full-time as a dedicated team only for the design system. If there were some tasks with higher priority in the teams, we had to drop the design system and work on those tasks. So the workflow was not always smooth - some weeks we were delivering more, others we were not.

Because this was more like a side project, not all developers were interested in working on it. So we had to find people who were interested and motivated.

4. No previous experience

On top of all the previous challenges, I had no experience in either building a design system or leading a team of developers! So I had to learn a lot of new things, and I had to learn them on the go.

I tried searching for some resources online - I wanted to read about the challenges that other people faced and how they solved them, so I wouldn't make the same mistakes, but I couldn't find many articles about this topic that would be useful for me. So I decided to write my own blog post about my experience. I hope it will be useful for someone else. ✨

Things I learned and other random tips 🤓

Having to face all these challenges, I learned a lot of new things, and I want to share them with you as well as some other practices that I found helpful.

👉 Have meetings with developers and designers

These are the meeting that we had with the team:

With developers - what worked for us was having a regular weekly meeting with developers to discuss what we did last week, what the blockers are, answer any other questions, and pick up new tasks for this week.
With designers - I also had a weekly meeting with designers to discuss progress or other questions. After a while, we didn't need it anymore, but it was beneficial at the start of the project when we were still figuring out what we needed to do and how to do it. In this meeting, we were discussing things like what components we need to create next by priorities, what approach we should take to naming props, etc.
With the whole team - later, we also started having a meeting with the entire team - developers and designers - where we could resolve any questions from both sides. The first few times, it was helpful, but later we canceled it as we didn't have many questions to discuss. In this meeting we had a quick demo by our designers about Figma and how to use it.

As you can see, after some time, we didn't need most of these meetings, but at the start, they were very helpful. It's really important to recognize when meetings stop bringing value and cancel them. If no more questions are being asked and no more blockers are being resolved, I feel like it's a sign that the meeting could be happening less often or even canceled.

👉 As the leader, you don't have to know everything, but you have to know where to find the answers

As a fresh leader, I sometimes felt that I didn't know enough about the project or how to solve problems or do some things. And these doubts were blocking me mentally. But then, one day, I realized that I had a bunch of intelligent developers around me working with me on the project. I just had to ask for their help.

That's why I decided to have a Retro meeting with the developers, where I would get feedback from them about the project or suggestions for improvements. It's also helpful to even get some validation that your ideas are good and you are on the right track.

It's a shame that we haven't had a lot of Retro meetings, as this idea came a bit late. I would recommend having them from the start of the project.

👉 Decide in advance what will be the structure and the props

I would recommend deciding in advance what the structure of the components will be and what props they will have.

Having the same prop names in the component as in the design documentation.

We are using Figma for our design system docs, so we have the same names for the props in the Figma file as in the code. This makes the communication between different roles (designers and developers) easier when everyone is calling the same things by the same name.

Additionally, when developers get some feature designs in Figma where design system components were used, it makes it easier for them to understand what props to use.
Deciding the story's structure.

We are using Storybook for our design system docs, and we decided to go with the atomic design structure for our stories.

There is no right or wrong way to structure your stories, but I would recommend having some structure in place, so it makes it easier to find the components and decide where to put the new ones.

👉 Write things down

After explaining the same things multiple times, I realized I should write things down. These are the main documents that we have:

Short intro to the project
- What is this project about, and why do we need it;
- A list of all the main contact people (i.e., development lead, design lead);
- Our working agreements;
- Other short notes that might be useful for new people and links to other documents.

Detailed steps on how to approach different tasks
- When we are picking up new tasks;
- Different tasks' tags explained (tags we use: new component, update component, fix, cleanup);
- How to approach new components and update existing components;
- Testing with designers;
- Updating other company's projects that are using current components;
- Releasing changes.

These documents make it easier for new people to onboard and understand what they need to do. And it also makes my life easier - I don't have to explain the same things repeatedly.

👉 Don't forget about the performance

We didn't think much about the performance at the start of the project. We were more focused on functionality and design. But now, when we had to work on improving performance in one of the projects, we could see that our UI library was getting big and it's slowing things down, so we will have to do something about it.

So I would recommend considering the performance from the start of the project and looking into Treeshaking and/or other performance optimizations.

Performance is a big topic, I might write a separate post about it in the future.

Conclusion 🎉

Overall, building a design system was a challenging but rewarding experience. It required a lot of hard work, collaboration, and learning, but the end result was a valuable tool for our company. We now have a consistent and accessible product that benefits both our designers and developers.

If you're considering building a design system, I hope my experiences and lessons learned can be helpful to you. Don't be afraid to take on the challenge and learn along the way. It's definitely worth it in the end.

I hope you enjoyed reading this post! You can follow me on Twitter for more updates.

Stay happy, healthy, and curious! 🍀
- desinni