A guide to collaborating on design systems

This is an excerpt from Design Systems for Developers, the guide to design systems published by the team behind design systems component developer Storybook. Read the book for free here.

In chapter 4, we’ll learn professional workflows for making design system improvements while mitigating inconsistencies. This chapter covers techniques for gathering UI feedback and reaching consensus with your team. These production processes are used by folks at Auth0, Shopify, and Discovery Network.

Single source of truth or single point of failure

Previously, I wrote that design systems are a single point of failure for front-end teams. In essence, design systems are a dependency. If you change a design system component, that change propagates to dependent apps. The mechanism for distributing changes is unbiased—it ships both improvements and bugs.

Bugs are an existential risk for design systems so we’ll do everything to prevent them. Small tweaks end up snowballing into innumerable regressions. Without an ongoing maintenance strategy design systems wither.

Continuous integration

Continuous integration is the defacto way to maintain modern web apps. It allows you to script behavior like tests, analysis, and deployment whenever you push code. We’ll borrow this technique to save ourselves from repetitive manual work.

We’re using CircleCI here, which is free for our modest usage. The same principles apply to other CI services as well.

First, sign up for CircleCI if you haven’t already. Once there, you’ll see an “add projects” tab where you can set up the design system project like so.

Add a .circleci directory at the top level and create a config.yml file inside of it. This will allow us to script how our CI process behaves. We can simply add the default file that Circle suggests for Node for now:

At the moment, this runs yarn test, which is a basic React test that was set up by create-react-app for us. Let’s check that it runs on Circle:

Note that our build failed, as we currently don’t have any tests defined for our project. We’ll add some soon, for now, let’s keep moving.

Visual review UI components with your team

Visual review is the process of confirming the behavior and aesthetics of user interfaces. It happens both while you’re developing UI and during QA with the team.

Most developers are familiar with code review, the process of gathering code feedback from other developers to improve code quality. Since UI components express code graphically, visual review is necessary to collect UI/UX feedback.

Establish a universal reference point

Delete node_modules. Reinstall packages. Clear localstorage. Delete cookies. If these actions sound familiar, you know how tough it is to ensure teammates reference the latest code. When folks don’t have identical dev environments it’s a nightmare to discern issues caused by the local environment from real bugs.

Fortunately, as front-end developers, we have a common compile target: the browser. Savvy teams publish their Storybook online to serve as a universal reference point for visual review. This sidesteps the inherent complications of local dev environments (it’s annoying to be tech support anyways).

When living UI components are accessible via a URL, stakeholders can confirm UI look and feel from the comfort of their own browsers. That means developers, designers, and PMs don’t have to fuss with a local development environment, pass screenshots around, or reference out of date UI.

Publish Storybook

Build the visual review workflow using Netlify, a developer-friendly deployment service. Netlify is free for our use case, but it’s straightforward to build Storybook as a static site and deploy it to other hosting services as well.

Now, find your design system’s GitHub repo that we created in the last chapter.

Enter the storybook-build command for Netlify to run whenever you commit.

All going well, you should see a successful build in Netlify:

Browse your published Storybook by clicking on the link. You’ll find that your local Storybook development environment is mirrored online. This makes it easy for your team to review the real rendered UI components just as you see them locally.

Netlify runs a build command on every commit that deploys your Storybook. You’ll find a link to it in GitHub’s PR checks (we’ll see that below).

Congratulations! Now that you set up the infrastructure to publish Storybook, let’s demo gathering feedback.

While we are at it, let’s add the storybook-static directory to our .gitignore file:

And commit it.

Request visual review from your team

Every time a pull request contains UI changes, it’s useful to initiate a visual review process with stakeholders to reach a consensus on what’s being shipped to the user. That way there are no unwanted surprises or expensive rework.

We’ll demo visual review by making a UI change on a new branch.

First, tweak the Button component. “Make it pop” – our designers will love it.

Commit the change and push it to your GitHub repo.

Navigate to GitHub.com and open up a pull request for the improve-button branch.

Go to the Netlify URL in your PR checks to find your button component.

For each component and story that changed, copy the URL from the browser address bar and paste it wherever your team manages tasks (GitHub, Asana, Jira, etc) to help teammates quickly review the relevant stories.

Assign the issue to your teammates and watch the feedback roll in.

In software development, most defects stem from miscommunication and not technology. Visual review helps teams gather continuous feedback during development to ship design systems faster.

Test your design system

Visual review is invaluable; however, reviewing hundreds of component stories by hand can take hours. Ideally, we want to see only the intentional changes (additions/improvements) and automatically catch unintentional regressions.

Continue reading Design Systems for Developers here.