How we built Matcha, Segment’s design system

In 2014 Google took the digital world by the storm with its release of Material Design. It allowed developers to create apps with consistent user experience across various platforms faster than ever. Since that revolution, many big tech players had been investing in design systems. One of those companies is Segment — and here's how we built their source of truth, Matcha.
Our collaboration with the leading customer data platform dates back to the summer of 2019, when they asked us to refresh their visual language. Once our designers settled on the direction, it was time for the development team to show 'em how it's done.

The challenge

We've been developing pixel-perfect landing pages for years. But this project was way more complex (I'm talking stacks of subpages) and we faced with new challenges.
Up until now, one developer was enough to handle a single project alone. In this case, we engaged our entire team. Everyone had their own assumptions, ideas and workflows. If they all went with their gut, we'd end up with an awful mess.
With more people involved the project management gets tricky. While it's faster to work together, collaboration requires extra effort to explain the context behind your work. And each one of us communicates a bit differently, which we had to standardize too.
Finally, don't even get me started on what could've happen if the client wanted to make an adjustment to an element already implemented on multiple pages. Without a design system, we'd have to update it one by one, hoping that it won't break anything.

Confirming the plan

I wouldn't make such a dramatic and self-deprecating intro if we went the wrong way, right? Of course we're smarter than this!
To avoid all these troubles, we created a little test library in Storybook before committing to a workflow. This playground included just the most useful components that we could build in under 2 months. And it did wonders! We got the green light from our managers, rolled up our sleeves and officially started working on Segment's design system.

The one to rule it all

There are many definitions of what a design system is, because it's an abstract term. For our needs, we focused on creating a set of reusable components, patterns and guidelines.
One of our goals was to reduce the time needed to create a landing page from 5–6 weeks to just 5 days (design included!). The design system would also allow us to build multiple pages simultaneously.

The benefits of a design system

Feel free to copy-paste this list to convince your manager.

Saves time

If some element, rule or principle is used in more than one place — it's from the design system. This means that the next time someone will think about the right solutions, they can reuse them from the library. This saves A TON of time and reduces the budget for each subpage. Plus it makes the work more fun, because you're focused on more creative problems.

Makes things consistent

With a centralized component library everyone uses building blocks from a single set. Their variables make them flexible to different content, but the fundaments stay the same. This creates an unbreakable consistency that can be easily updated if you wish.

Reduces complexity

Instead of battling with spaghetti code every time you want to add anything, you use neatly organized tags. This makes onboarding a new developer super easy, because once they explore the structure, they are ready to go.

Future-proofs

If you build your components well, it's easier to update them too. Every element that appears in multiple instances can be managed from a single file. Whether you want to add an item to the navigation or change the color of a button — it works so well that it feels like black magic.

How we got there

We went with React and Storybook. They are quite a standard pair of picks for such a project, which means that everyone was familiar with them thanks to the wide community support. Some companies — including yours — might need more custom tools, but these were just enough for us.
To keep track of our progress, we set up a kanban board and worked in one week sprints. This allowed us to split our goals into smaller pieces to be more accurate in our estimates.

How we used Agile

There's no need to bore you with a lecture on Agile, so here's an overview of how we make it work for us.

Sprint kick-off

Each sprint starts with a goal setting meeting, where the product owner gives a demo of what we created last week. Based on that, we can look at our velocity to plan the tasks for the current week. After the kick-off we dedicate about 30 minutes to go around and ask any questions that block us.

Grooming

One of the most important sessions, where product owner defines the issues and their acceptance criteria. Then, the developers can estimate how long each task will take with story points. Grooming is usually done asynchronously — unless we can't define more complex problems.

Daily

In the morning, when everyone takes the last sip of their coffee, we let each other know what we did the day prior and if we encountered any problems (blockers). Those quick syncs allow us to stay organized without the never-ending back-and-forths on Slack (so annoying!).

Sprint retro

Each sprint ends with a retro meeting, where everyone express their thoughts on the past iteration. We start by writing down positive and negative feedback, explain our choices and then vote on the most important points. We leave the meeting with action points assigned to their respective owners that will help us resolve those issues.

How we set up Storybook

Our Storybook has 4 major sections.

Getting started

It's the first section where you can read the instructions and information about the rules and usage. When a new developer joins, that's where they start their onboarding here.

Components

Here's where all the basic components live. We follow the Brad Frost's definition of atomic design, so think about inputs, buttons or cards.

Recipes

This also contains components but more complex ones. Navigation would be a great example, as it's built from multiple primitive elements.

Templates

Last but not least, templates are finished sections with their data. In addition, there are snowflakes — one-off components that are necessary but not reusable outside their first use case.

Inside the project folder

Here's how we created the folder structure of the project.

Inside apps, there are finished marketing pages (segment) with their components, local snowflakes and tests (e2e).
Generators contain scripts required to build icons from the SVG files.
Libs include the essence of Matcha — the API and the design system itself. In the latter, you'll find component docs and recipes, whereas API, assets and helpers live a level above.

What we added to Storybook

Storybook alone is awesome but we added a couple tweaks. The dark mode is an obvious choice for the after sunset sessions. And live coding with builder allow us to edit code directly in browser — so even a non-technical person can test different variants.

How we secured our workflow

To make sure we don't break anything, we used continuous integration (CI). With that practice even if someone made a pull request (PR) from a branch that had some bugs, CI won't let this PR merge into the main branch. Instead, it'll show you a specific error message — great way to reduce stress!

What we delivered

With Matcha, Segment can build landing pages in light speed. Everyone who joins the team can easily jump into the project without a lengthy onboarding process. Designers and the marketing team can shuffle Storybook on their own to see which components are already built and which variations are possible.

Based on how Segment uses Matcha, we're currently working on a side project that allows people to create PDF mockups from components living in Storybook. We'll let you know once we launch it!