Our Design System with React Components, Figma, and Storybook.
Reasoning
When we started building our Design System at ORFIUM, I was hard-pressed to gather information from other companies that had gone through the process or colleagues with this kind of experience. I hope that you will find answers in our story to some of the questions you’ll face when you go about creating a design system of your own.
Start of everything and the big Q
Big Bang — The start of everything
Over the past couple of years, we’ve seen more and more companies adopt the idea of a Design System into their core business. Creating and using a design system can help to solve a number of problems for design and frontend teams collaborating. As the design system handbook defines, it helps teams to:
- iterate quickly
- manage debt
- prototype faster
- design consistency
- improve usability
- focus on accessibility
But what happens when you want to sync those two departments together and have that system stand as middleware? This is the point in our research where we had a hard time finding information. Turns out, it’s pretty challenging to find a one-solution-fits-all kind of answer.
At ORFIUM, the need for a DS came up as our products grew and we had to work on different projects that focused on different user flows. Furthermore, the nice problem of rapidly growing two departments (front-end and design) led us to the need for centralized information about our user journey and a more rapid and solid solution for building components. This is where the Design System comes in.
To do that we decided to implement two different tools.
- The first one would be a collection of design components, processes, style guides, and rules placed by the design team. These would be the one source of truth for any product design. So if we had one search page on a product every component used in that page would come for the design system’s components.
- The second tool is for the frontend team, which has to be in total sync with the design team. The components, dev standards, and rules that will be applied here will come mainly for the first tool and ensure that everything is in place. All components served by the design team to products will be available from the frontend team.
Our Design System
How we did it — Front-End
Initial analysis
The first step was to identify what we were about to build. One of our primary considerations was to not waste resources, to ensure that no extra work would be put in for unnecessary outcomes. So the first question on the team’s mind was “ do we really need to make everything from scratch”?
There are many well-known, well-structured, and open-source design systems out there, such as Material Design or Ant Design. So, why don’t we use that kind of a tool? We spent a decent amount of time considering our v1 designs of all the products. This exercise led us to the conclusion that we couldn’t use any other system. Here’s why:
- As our products grew we weren’t sure if we wanted certain rules for each system. Having a system and constantly trying to avoid fundamentals wouldn’t be a great fit.
- We didn’t want to kill the design team’s creativity.
- We wanted to keep our system lean. And carrying a package from a library that contained mostly elements we’d never use didn’t make any sense for Orfium.
Furthermore, it was time to establish how it was going to be used within the team. As we don’t currently use any sort of monorepos, we wanted to make sure that this library would have its own roadmap. We chose the use of npm and made it a public package. This way the team would have to use it as a public package contribution and we have to stick with many good processes. This move allowed us to pull Request labeling and procedures, automate our changelog and release system, and, importantly, to show our work to the world and be proud of what we deliver.
First Baby Steps
Our implementation was broken up into 3 steps.
- We started by defining all style guides and what we’ll need for the future with our design team. Margins, paddings, typography, colors, and grid definitions, all of these are crucial inner parts of the system that are going to be used in many places and have to be constant.
- We focused on the atomic design system for building all of our components, based on the style guides defined earlier. These parts, which we call components, were buttons, text fields, icons, chips, avatars, list items, etc. As we finished with the atom parts we moved to the molecules, which is what we call combinations of the previous atoms. Examples of those components are icon buttons, select, lists, etc.
Pro Tip: I suggest that you do that early and define it with the team. - We moved into mostly visual testing. We started by using snapshots. With that, we knew every time we changed something, that visual part had changed. It was crucial, as the library will grow and everything is linked under the hood, that a small change doesn’t affect components negatively.
Pro Tip: A visual comparison of any external tool doesn’t hurt.
Team Arrangement
We defined several ways of communication between the Product, Design, and Frontend teams to provide a solution that will be built once and will help all products in the way.
It is important to note here that we see the design system team as a non-product team and our two teams (design and frontend) maintain it.
Use of a Federated team
Each product has its team. This team consists of people from all departments: Frontend, Backend, Design, Product, and QA. The need usually comes from the Product team and grows there.
The flow of requests, from request to implementation and release.
So if there is a new feature, let’s just say a select input that does only filtering, it is the responsibility of the frontend engineers and designers to raise that need of a new component to the DS moderators to discuss.
You can learn more about team structures and dynamics in a great article here.
Federated team flow based on Nathan Curtis article.
Furthermore, because there is no specific team for the design system, the request will be created as a task and can be handled by either the first developer available or the first product team member that needs to serve this in their roadmap.
This way we built it once and use it when there is a need. We always have a “Design System First” rule.
Roles
We have two roles defined to smooth out our communication.
Moderators make document decisions, provide guidelines, do the technical review, and communicate updates. They also create space for doers to get the job done.
As our DS consists of two departments, Frontend and Design, there are two moderators: a technical mod and a designer.
Moderators communication between teams
Doers are the system contributors and builders. They execute on proposals or requests, and set priorities based on the design’s needs.
Planning
Yeah, it’s not what you think it is. Or maybe it is. The DS is not a product, so we don’t have scheduled events, velocity, or retros. But we an agreed meeting every two weeks. This is mainly driven by the moderators to discuss new requests. They are the main members who need to attend, but both teams can join optionally as their input is important. This meeting is also where we vote on story points. Remember when we said that Product Managers who serve requests first are going to have them built? Well, story points help here for the team to know what it can create for the Design System.
Problems we encounter
Of course, all the above didn’t work out of the box from day one! The first version was in beta mode. All the communication between us was unshaped. Let’s take a look at the issues we faced while setting up our Design System and its processes.
Versioning
As we have many products and different roadmaps, we need to keep different versions for breaking changes. Having different versions allowed us to run at different speeds. So if we had 3 products that had 3 different roadmaps, we didn’t need to force anyone to always be up to date with the latest design system changes.
Representation of versioning
At first, we were manually fixing versions and keeping track of everyone. This took a lot of time and energy and, as we try to keep our DevOps mentality, we had to automate it. If we have a version for our library, the design team has to do the same.
Now the system has automated releases (semantic) that we track. We introduce branches for the next release (major — breaking change release) that we have in the roadmap and we also have different versions in Figma, which match what we have and what is in the next version. Design and Frontend teams must be fully aligned with these versions, otherwise QA will fail.
Wrong tools for the job
We also needed to find the perfect tool for the job. We tried a couple until we found Figma ❤.
We started out with Zeplin, where we had all of our design screens. But it didn’t help our design team to keep track of their changes as their team grew. So we moved to Abstract. That tool solved the problem of version tracking, kinda. But that was right when our design system took off, and the point where we needed to split all of our product designs into smaller components. So the key that changed everything was this word, “components”. That’s when Figma comes in. With Figma, we now had the power for different versions and component-based designs. Our teams need to understand each other. Figma gave us this in a simple way.
Pro Tip: we went through 3 tools to end up at Figma because we only discovered the growing needs as we used the Design System. Learn from our experience and use Figma for Design/Frontend collaboration.
Lack of communication
Oh boy, two different worlds under the same roof, you can imagine. We had (and we still have) miscommunication. It’s one of the main ingredients of teams with different worldviews working together, we know it. The first and main problem was the main responsibility at the two ends. As the teams were working on the Design System, we were all questions like:
- what should we work on next?
- why is that there?
- who will say this is approved to continue to develop?
We discovered that we were tripping over our shoelaces! Thus, we assigned what we call “the Gatekeeper” a.k.a the Moderator on each team. The Moderator is the go-to person for all of these questions. That person is not responsible to run all the tickets, is a member of the team but has to align with both teams to solve any problems and communicate with the other moderators for issues and features.
These two people now held the single source of truth, but we also have to make our decision-making more transparent. The solution was pretty simple: we started a Slack group where we shared our decision-making while we wrote it down on documentation.
As these things started to work well and we gained a good speed, we had to plan ahead. Our tasks, according to our federated system, must be visible to everyone to handle. We came to a place also when we wanted to have a rough calculation of how this affects all the other products. We know that we do well and all, but wouldn’t it be awesome if we could say that we spent 10 hours building one thing that we used in 5 places? That’s 40 hours saved!
For this, we agreed that we had to create a “planning” event where the moderators will attend and all other members optionally can join. At this event, we are voting for each task and creating rough planning for the upcoming weeks. On the completion of each task, we also count the hours that it took to complete. This way we know what we planned and how long it took. Sounds familiar, agile people?
Lastly, as our process of doing things was
planning -> coding -> code review -> QA -> completion
We decided that we need to change things a bit to avoid doing code reviews on the wrong things. So for this case and only we switched to
planning -> coding -> Design QA -> code review -> QA -> completion
This way we give developers the sanity to review a finished solution.
So, the solutions that are in place:
- Moderators for each team
- Specific chat to let both teams in on the decision-making
- Planning and time tracking
- Design QA before code QA
What’s next
Enough with the past. What does the Orfium Design System, Ictinus, have in its future?
Every decision we make is based on a need. Also, any change in previous decisions we make is for the same reason, a new need. Right now there are 2 of them that we need to solve.
Documentations link
Lately, we see that our two documentations (technical + design) need to be compared or be visually linked. This will help us develop, as we could visually compare in real-time with the design itself. Also, it can help any QA or viewer compare the actual outcome which adds extra value.
The planned solution for this is to link the storybook with Figma in two-way communication.
Enhanced QA
We have much room to expand here as we only scratched the surface. The plan is to add more QA to UX and UI. Also, as per our DevOps nature, we can add a solution to automate in any release to check if something changed as per documentation from any side and show exactly what changed.
Conclusion
Building a design system is challenging, literally. It will challenge the way the teams work and communicate, collaborate with each other and how the org as a whole thinks about more abstract solutions. It’s a long road that requires constant fixes in both tech and processes. But it will pay off all the hard work when you see it in action. When one small UI or UX change suddenly affects 5 products and their users.
Of course, your design system doesn’t have to match our story, because every company’s DS may be bigger. Even a standalone product.
If you wanna have a glance at our project check it at npm or Github.
*Credit for all of this hard work must go to both of the teams, Frontend and Design. Plus, thanks for all the assets for this article!
References
Team Models for Scaling a Design System
Evolving Past Overlords to Centralize or Federate Design Decision-Making Across Platformsmedium.com
Defining Design System Contributions
Time to Separate the Small-and-Quick from Larger Thingsmedium.com
