DEV Community: Laura Žumbakytė

Deep dive into the Design System @ CGTrader

Laura Žumbakytė — Thu, 02 Feb 2023 13:20:47 +0000

Previously I wrote about the challenges we faced while working on the design system, and you can find that article on my profile. In this article, I will go deeper into some technical approaches we took and the technologies we used.

👉 Storybook

We used Storybook to develop and test our components. It is an excellent tool for developing UI components in isolation.

Atomic design structure

We chose to use atomic design methodology for our components. That means that we started with the smallest components and built them up to more complex ones. The beauty of this approach is that anytime you need to update your button atoms across the site, you can just update that one atom, and that update can then be applied to the rest of your design system.

By 2013, Brad Frost officially coined the term "atomic design".

Brad understood that when you build a website from the ground up, from the atoms, to the molecules, to the organisms,
and eventually, the templates and pages, you are afforded maximum flexibility. You are able to maintain cohesion in
code and visual design while also still maintaining the modularity to quickly extend your components to various sections of the website.

Here is the structure of our Storybook:

Primitives - the smallest things, like Colors & Effects, Typography, Icons, etc.
Elements (Atoms) - the smallest components, like Buttons, Inputs, Tags, etc.
Components (Molecules) - more complex components made of several atoms, like Cards, Search, Dropzone, etc.
Utils - utility functions, like pluralize, useBreakpoint, etc.
Miscellaneous - all the components we already had in the UI library but not in the new Design System. Those components should be updated or removed at some point, if they are not used in the Design System.

MDX documentation

We used MDX to write documentation for our components. That allowed us to write our documentation in Markdown but also use React components in it.

A cool feature of these docs is that props are automatically listed from the component's propTypes. This way, you don't have to write them down manually, and you can be sure that they are always up to date. Also, they are interactive, so you can change them and see how the component changes. 🎉

You can even go a step further with your documentation and add comments before each prop, like this:

/**
  The avatar's size.
*/
size: PropTypes.oneOf(['small', 'medium', 'large']),

This will show up in the docs as a description for the prop. We didn't use this feature a lot, but it's an excellent option
to have if you need to add more details to your docs.

What we did use was the argTypes option, which allows you to customize the props table. For example, we used it to split the props into categories and add custom controls for some of them. Here's a code snippet of how we did it for the Avatar component:

<Meta
  title="Elements/Avatar"
  component={Avatar}
  argTypes={{
    size: {
      table: {
        category: 'Style',
      },
    },
    color: {
      table: {
        category: 'Style',
      },
      control: {
        type: 'select',
        options: colorsListArray,
      },
    },
    username: {
      table: {
        category: 'Content',
      },
    },
    ...
  }}

👉 Figma

We used Figma to design our components. We had separate files for our components, where we could see all their variations, how they looked, and how they behaved.

Here is an example of a Toggle component in Figma, where you can see all the different variations of its size, width, and styles:

Everything listed like this made it easier for the developers to see all the variations they had to create.

👉 Prop naming

We used the same naming for our props in the code as in Figma. Because docs were created on Figma first, developers just had to copy the names from there and use them in the code.

For example, if we had a Tab component with a leadIcon property, we would name the prop the same in code and Figma.

Having the same (or as close as possible) naming made it easier for developers and designers to communicate and understand each other.

👉 Utility classes

We have created some utility classes that we could use for easier styling. For example:

.cgt-text-caption - for text with caption style
.cgt-text--align-center - for centering text
.cgt-heading-#{$size} - for headings, where #{$size} is a size variable from our design system (e.g., h1)
.cgt-color-#{$color} - for setting text color, where #{$color} is a color variable from our design system (e.g., brand-primary-100)
.cgt-back-color-#{$color} - for setting the background color, where #{$color} is a color variable from our design system (e.g., white-100)

👉 className prop for custom styling

In an ideal world, we would have all the styling in our design system, but sometimes we needed to add custom styling - it was just unavoidable in how our product was built. For that reason, we added a className prop to all our components so that developers could easily add custom styling. It was never made for major styling changes but only for minor tweaks or better positioning.

Result 🎉

Even though I see some room for improvement, I'm happy with the result. What we achieved with limited time and resources is amazing and for the "first version" of our design system, I think it's pretty good.

We have a consistent and accessible product that benefits our designers and developers. Having a unified look and feel across the whole product is important, so I'm happy that we have built a design system that will help us achieve that.

Thank you for reading, and I hope you learned something new today! For more updates, you can follow me on Twitter.

Building a Design System: Lessons Learned

Laura Žumbakytė — Fri, 06 Jan 2023 15:55:09 +0000

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.