Lessons Learned from Working on a Design System as an Engineering Manager

In 2018, I got involved with design systems, being the engineering manager on Base UI, Uber’s new design language. It was a new area for me to jump into, and I’ve learned a lot during the past months. In this article I’d like to share my lessons learned with you, focusing on design-engineering collaboration as well as building a successful React component library.

Before jumping to those lessons learned, let’s start with what design systems are. A design system is a set of reusable components that in combination with a set of rules and design tokens (named entities that store visual design information, like colors or spacing) enable you to build consistent and accessible applications quickly. To read more on design systems, I recommend checking out the Design Systems Handbook.

Introduction to Base UI

At its core, Base UI is a foundational set of reusable React components, with an architecture that enables teams to create new design languages on top of it. By default, these components use the Base UI design language which, as the name suggests, acts as a base design language you can further customize. You can learn more about the architecture by reading David‘s Better Reusable React Components with the Overrides Pattern on the topic.

Base UI overrides in action

Design-Engineering Collaboration

One of the biggest challenges was and still is, to improve the collaboration between the design and the engineering teams. To that end, currently we have the following practices, channel to communicate:

Demo meetings

We hold demo meetings for design and engineering every two weeks. During these sessions, both teams showcase what kept them busy, and what’s next for them. We also assign action items to their respective owners, if anything needs a follow-up.

Figma is the tool the design team uses to work on the design system components. What’s really handy about the tool is that you can add comments/mention folks on the designs themselves — so if you choose to, you can comment on each pixel. We often use this to point out inconsistent spacing and typography or clarify how interaction is supposed to work

Collaborative Visual Regression Testing

We have adopted a tool called Screener that does visual diffs for the components we build. Through GitHub integration, pull requests are blocked if the visuals of a component are changed or a new is added, and the design team is notified to accept or reject the changes. Until that happens, the PR is blocked from being merged.

Common chat channels

Maybe stating the obvious here, but wanted to point out the need for a common channel for your design system, where engineering and design can discuss topics.

Documentation

Originally, we started out with Storybook for our documentation site. As it turned out, most folks did not find it effective enough, so we’ve started rolling our own documentation site, with these most important features:

• Copy-pasteable examples, and editable code snippets through CodeSandbox
• Auto-generated API documentation from the Flow type definitions

You can find the work in progress documentation site at baseui.design/beta.

Inner-sourcing and Open-sourcing

We’ve worked on Base UI from day zero as a project we wanted to open-source. Historically, whenever Uber open-sourced a project with UIs, we had to recreate some kind of a minimal design system that can be open sourced along with the project. Examples include the amazing visualization projects Uber has.

Now that Base UI is open-sourced and has a flexible overrides architecture, we can start internal projects that build upon the open source release of Base UI, where we can utilize inner-sourcing, and let folks from different teams working on internal design systems contribute.

Versioning, release management

In order to create stability for Base UI, we’ve opted to create a public versioning policy. We wanted everyone who depends on Base UI to know when and how new features are added, and to be well-prepared when obsolete ones are removed.

Support

Chat is unsurprisingly our most popular support channel, so we’ve started with a dedicated chat room for Base UI internally, and a Slack organization externally, to help folks with any incoming question. To make sure we do not miss questions, we have a support rotation (we only cover 8 hours a day during working hours). We also have a Google group for our team to let folks write emails to the whole team using an alias, without missing anyone.

Ideally, folks post either external or internal Stack Overflow questions — that way we can have a public knowledge sharing platform. If that’s not the case, someone from our team will create the Stack Overflow question, and answer it.

As an open source project, we also have to deal with GitHub issues, while internally we use JIRA for our scrum processes. As of today, we manually keep the two issue trackers in sync, by duplicating GitHub issues in JIRA and referencing them. This process is super error-prone and time-consuming, so if you have any recommendations to improve it, please let me know!

Roadmap, communication

When building a design system, communication is super important — product teams with deadlines depend on the components you are building.

To make sure we keep everyone in the loop, we have a Base UI newsletter that we send out every second week, that provides an easy-to-digest summary of recent releases, a shoutout to all the external contributors that helped us during those two weeks, provides links and instructions on how one can start contributing to Base UI and a list of components and features that will keep us busy in the next couple weeks.

Impact

We measure our impact by collecting statistics on how many projects adopt Base UI internally using Sourcegraph, as well as through developer happiness by NPS surveying. Once we had these baselines, we set out goals to improve — the reworked documentation site is one of the action items we’ve started working on after the feedback we had received from the last survey we’ve sent out.

Getting involved in design systems was definitely an exciting journey, and I’ve learned a lot. Please share in the comments below any lessons learned you had that I’ve missed from this list! Also, we are hiring so if you’d like to join the team, ping me on Twitter, my DMs are open!

Originally published at nemethgergely.com.