The developer’s guide to design systems

A note from the author: I’m thrilled to introduce Design Systems for Developers, a free nine-chapter guide about building and maintaining design systems with Storybook. Learn production-ready techniques and tooling as you build a design system from scratch. Follow along with real code commits. 

You’ve probably heard of design systems. How could you not? From large software companies to modest startups, teams across the design maturity spectrum are recognizing the utility of reusable UI patterns.

However, ubiquitous as design systems have become, when looking for tactical guides to building them I was disappointed at the lack of options. Tom (Design Systems for Developers co-author) and I recently built a design system of our own for 750+ global open source contributors—and when planning the technical architecture, we were at a loss for information on how to make it happen.

Design Systems for Developers is the guide Tom and I wished we’d had, written for professional developers about how to engineer a design system from scratch and based on researching leading front-end teams. The book is a natural result of our passion for design systems, which we’ve also channeled into our work on Storybook, an open-source tool for developing design systems used by Twitter, Slack, and Salesforce.

Let’s get into some highlights from the book, including a design system’s worth and whether the investment makes sense for your team.

Why build a design system now?

Design systems aren’t for everyone and every team. They help teams efficiently scale UI patterns, but require ongoing investment to realize any value. For small teams building tightly-scoped products, that can demand more energy than it’s worth.

Design systems are most productive when used across many projects and with a dedicated maintenance team. The focus on widespread adoption and investment in infrastructure allows you to reap the benefits of the upfront setup cost.

Design systems have similar infrastructure

Take a look at the most popular design systems from Shopify, Airbnb, Microsoft, IBM, and GitHub. In each one, you’ll find varying constraints, tactics, and goals, making it tough for the average developer to discern best practices.

Check out how Apartments.com built their design system using InVision’s Design System Manager.

Tom and I observed the front-end workflows from Storybook’s massive community of over 20,000 GitHub projects. Because design systems are so diverse, I thought there would be a lot of conflicting practices—but I was pleasantly surprised to find most design systems rely on similar set of front-end tools such as a continuous integration service, package manager, and component explorer.

The importance of front-end infrastructure

The day-to-day job of a design system developer involves building UI components, writing usage documentation, and working with stakeholders spread across an organization.

The work doesn’t end there. Additional tasks include maintaining a local development environment, setting up a static site, deploying that site, testing, release management…and the list goes on.

Simplify your design system maintenance with InVision’s Design System Manager.

Teams can get so bogged down by mind-numbing maintenance tasks that they’re unable to focus on UI component development and engaging with stakeholders. We found that successful design systems are built atop a reliable front-end infrastructure that prioritizes communication, automation, and regimented workflows.

Reduce communication overhead

Design systems have many stakeholders: designers, developers, client apps, and end-users. It’s hard enough to keep a group this size engaged with UI patterns—never mind aligned. That’s why techniques that help folks reach consensus fast are so important.

Avoid ambiguity

Components are the building blocks of design systems. Catalog every component so they can be discovered using Storybook, and then articulate each component’s supported UI states (e.g., primary, secondary, tertiary) to prevent ambiguity on how to use a component.

For instance, here’s a “Histogram” component, something you might find in Google Analytics, Mixpanel, or Chartbeat. There are three supported states: default, empty, and normalize. You can avoid ambiguity by recording each state as a “story” in Storybook.

When your colleagues visit Storybook, they can immediately see how to use the component.

Collaborate often

Streamline gathering feedback by frequently publishing works in progress to the cloud. Your team can review the real UI implementation without touching code or a development environment.

Design system teams often run into unforeseen UI development challenges ranging from styling quirks to the idiosyncrasies of web layout. Increased communication makes it easier to course correct and prevent expensive rework.

Automate manual work

Teams automate manual repetitive tasks to build more with less and save themselves from mind-numbing work.

Test the right things

Since design systems are a dependency of many apps, minor UI bugs can snowball into organization-wide catastrophes. Visual tests help you catch unintended UI bugs by comparing screenshots of components to previous versions (e.g., Chromatic). Unit tests validate nuanced behavior to ensure UI functionality (e.g., Jest).

Generate documentation

Everyone agrees that documentation is important, but it’s often the last priority when creating a design system. Luckily, tools like Storybook Docs automatically generate documentation based on component code. The process looks like this:

This easy documentation gives pragmatic developers “minimum viable docs” for free, plus the freedom to customize further.

Integrate workflows

The way tools work together significantly impacts the user experience for stakeholders. When done well, teams are free to be productive without stumbling over the handoff between tools.

Continuous integration

Continuous integration tools allow you to script tasks like testing, analysis, and deployment whenever you push code (e.g., CircleCI). Use this technique to orchestrate ongoing design system maintenance. Teams save time and avoid onerous manual quality assurance.

Distribute seamlessly

Design systems are shipped via a package manager like NPM. You can empower your team to ship regular updates by integrating with open source release management tools like Auto. That enables folks to publish design system updates without touching the command line (i.e., in GitHub).

Over the life of your design system, you’ll ship countless package versions. Small development experience tweaks to common workflows compound over time to yield large time savings.

We researched leading design systems to uncover how they’re built. Individual developers can set up the same tooling themselves today. Learn how by reading our nine-chapter guide that walks through setting up the production infrastructure with code samples.

Read Design Systems for Developers.

Take a peek at the table of contents:

1. Introduction: A guide to the latest production-ready tools for design systems
2. Architecture: How to extract a design system from component libraries
3. Build: Set up Storybook to build and catalog design system components
4. Review: Collaborate on design systems with continuous integration and visual review
5. Test: How to test design system appearance, functionality, and accessibility
6. Document: Drive design system adoption with documentation
7. Distribute: Learn to package and import your design system into other apps
8. Workflow: An overview of the design system workflow for front-end developers
9. Conclusion: Thriving design systems save time and increase productivity