How we built a component library that people actually enjoy using

Chase McCoy
Jun 27 · 12 min read
  1. A website, built on Create React App, that acted as a local development environment for our developers and a documentation website for stakeholders across the company.

Separate development and documentation

Today, Racine lives on as our component library. But no longer does it try to do the job of development tool and documentation site. The documentation now lives in our design system, and our component library is just a tool for building, testing, and using components in web projects at Sprout.

Our component library now lives right inside our design system, at
  1. We added a separate local development environment based on Storybook.
  • For a few high-value projects, we created internal landing pages with Seeds that serve as hubs for information about the projects and their teams.
  • We are currently exploring the idea of a series of “sponsored” Slack posts that highlight our component recipes. These recipes are short snippets of code that demonstrate how to use our components to solve a common UI problem or create a pattern often seen in our app. We want to drip these out to our developers in the form of small, well-designed Slack messages that get shared in common channels as a way not only educate, but also to drive excitement.

Empower authors

Being able to focus on documentation in isolation from development has proven to be crucial for us, and it has allowed us to discover that the key to facilitating really great documentation for a design system is to focus on two key areas of the experience:

  1. Interactivity. People don’t like writing documentation and they don’t like reading it either, especially when they are trying to get their jobs done. We didn’t want our documentation to feel like a manual that needs to be read from cover-to-cover, but instead like a tool that can be used.
```jsx live 
This content will be centered within the box.
<Youtube id='abc123' />
<PropTable component='Button' />

Delight the consumers

Great documentation should be less like a document and more like a workshop. Not only does interactivity make the experience more enjoyable, but it also lets us communicate more information to our consumers.

Interactive code blocks

Every Markdown code block in our component pages turns into a fully editable sandbox for the component. Being able to try out different combinations of props is huge for both our developers and designers. Each code block is like a mini prototyping tool that makes writing code seem as simple as changing a few values.

Token tags

At the core of our design system are our design tokens — the atomic values that represent our color palette, typography scale, motion guidelines, etc.

This Token Tag is for the 700 shade of our purple color palette.

Typography playground

Another great example where breaking out of the usual format allowed us to deliver a better experience is on our Typography page.

Type some text, pick your options, and then copy the tokens for Sass, JavaScript, and CSS.

System props

All of our components are built with Styled Components, and we use the excellent Styled System to attach “system props” to our component. Here’s how we describe these props in our documentation:

This component gets the COMMON and LAYOUT system prop groups.

What’s next

Getting our component library integrated with our design system is really just the beginning for us. If we were thinking in terms of version numbers, we would say that our system is now at version 1.0.0, which means there is plenty of room to grow. Here are some things we are focusing on next:

  • Reliability in the form of visual snapshot testing for our components. We want to be able to release updates to our component library with confidence that we aren’t breaking anything for anyone. We already unit test our components, but we will be working to integrate visual tests so we can ensure our components stay pixel perfect when we make changes.
  • Expanding our offering by adding more components and continuing to document existing ones. We are just getting started with what our library offers, and we want to increase contribution to our system from engineers who are not directly involved with the projects. In addition, we are updating documentation as we go in response to commonly asked questions and use cases presented by our users.

💅 styled-components

Visual primitives for the component age. Use the best bits of ES6 and CSS to style your apps without stress 💅

Chase McCoy

Written by

Enthusiast. Designer, writer, and developer. But who isn’t these days?

💅 styled-components

Visual primitives for the component age. Use the best bits of ES6 and CSS to style your apps without stress 💅