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.
How frontend tools work together has a significant impact on the ultimate value design and development teams can realize. When done well, it should be seamless to develop and reuse UI components.
This chapter showcases the five-step workflow by introducing a new component AvatarList.
Build
AvatarList is a component that displays multiple avatars. Like the other design system components, AvatarList started off being pasted into many projects. That’s why it warrants inclusion in the design system. For this demo, let’s assume that the component was developed in another project and jump straight to the finished code.
First, make a new branch on git where we’ll be tracking this work.
Download AvatarList component and story to your machine. Place it in the /src directory:
Storybook is setup to automatically detect files ending in \*.stories.js and show them in the UI.
Nice! Now let’s articulate each UI state supported by AvatarList. At a glance, it’s clear that AvatarList supports some of Avatar’s properties like small and loading.
Get posts like this in your inbox by signing up for our weekly email digest.
Given that it’s a list, it should show many avatars. Let’s add stories that showcase what happens with numerous list items and what happens with few list items.
Save your progress and commit.
Document
Thanks to Storybook Docs, we get customizable documentation with minimal effort. This helps others learn how to use AvatarList by referring to the Docs tab in Storybook.
Minimum viable docs! Let’s make AvatarList a bit more human by supplying additional context on how to use it.
Sprinkle in some additional details about the supported props.
Easy as pie! This level of detail is sufficient for now –we can always customize more using MDX later.
Documentation doesn’t have to be tiresome. With automated tooling, we removed the tedium to get straight to writing.
Commit the changes and push to GitHub.
Create a pull request
Let’s push our AvatarList branch to GitHub and create a pull request:
Then navigate to GitHub and open a pull request.
Review
At this point, AvatarList is a candidate for design system inclusion. Stakeholders must review the component to see if it meets expectations for functionality and appearance.
The design system’s Storybook is automatically published each pull request to make review dead simple. Scroll down to the PR checks to find a link to the deployed Storybook.
Find the AvatarList in the Storybook online. It should look identical to your local Storybook.
The online Storybook is a universal reference point for the team. Share the link to AvatarList with other stakeholders to get feedback faster. Your team will love you because they don’t have to deal with code or setting up a development environment.
Reaching consensus with numerous teams often feels an exercise in futility. Folks reference out of date code, don’t have a development environment, or scatter feedback across multiple tools. Reviewing Storybook online makes it as simple as sharing a URL.
Test
Our test suite runs in the background every commit. AvatarList is a simple presentational component so unit tests aren’t necessary. But if we take a look at the PR check, our visual testing tool Chromatic has already detected changes that need to be reviewed.
Since AvatarList is new there aren’t visual tests for it yet. We’ll need to add baselines for each story. Accept the “new stories” in Chromatic to expand visual test coverage.
Once you’re done, the build will pass in Chromatic.
Which, in turn, updates the PR check in GitHub.
The tests were successfully updated. In the future, regressions will have a tough time sneaking into the design system.
Distribute
We have an open pull request that adds AvatarList to the design system. Our stories are written, the tests pass, and documentation exists. At last, we’re ready to update our design system package with Auto and npm.
Want to read more? Sign up for our weekly email digest to get the next excerpt in your inbox.
Add the minor label to the PR. This tells Auto to update the minor version of the package on merge.
Now merge your PR, and navigate to your package on npm and hang tight for a few minutes while the package is updated.
Success! Your design system package was updated from the comfort of GitHub. No need to touch the command line or fuss with npm. Update the learnstorybook-design-system dependency in the example app to start using AvatarList.
Dominic Nguyen is the cofounder of Chroma, the company behind Storybook. Dominic built Storybook’s user interface, brand, and the design system. Previously, he had extensive experience in open source, launching popular tools like Apollo GraphQL (used by GitHub and Airbnb) and Meteor (the first full-stack JavaScript framework).
