From Drizzle to Storybook

In early 2016, we started redesigning our website in public. Along the way, we shared our pattern library and the tool we used to build it, Drizzle.

We’ve changed a few things in the four years since: We added offline support and other PWA features, made accessibility improvements, tweaked some typography. But we recently decided it was time for a bigger update.

There’s a lot I plan to share about the changes we’re making. For now, I thought I’d focus on why we’re replacing Drizzle with Storybook in our design system.

Drizzle helps us document our front-end patterns and provides a prototyping sandbox for our team. Our current ambitions and best practices demand some additional features:

• Support for more than just Handlebars templates. In a perfect world, we could use whatever source files our projects require: Twig templates for our WordPress theme, Stencil components for isomorphic JavaScript projects, etc.
• Accessibility testing tools: Color contrast, descriptive text, etc.
• Theme switching.

When we created Drizzle, there were few competitors. Pattern Lab and Fabricator were our favorites: They were stable, easy to use, not tied to a particular front-end framework or build process, and they allowed contributors to prototype and experiment with new and existing patterns. But we wanted to change enough of their structure and presentation to justify a separate project.

We still believe in Drizzle’s balance of patterns and prototypes. But it’s been challenging for our organization to maintain the tool, for three main reasons:

• Drizzle is, at its core, a static site generator. Static site generators are deceptively complex to author and maintain, especially when they aren’t your team’s day-to-day area of focus.
• While several of our clients benefited from and enjoyed Drizzle, they tended to fall in one of two camps: 100% okay with the tool as-is, or deviating so greatly that the path to reintegrating their improvements felt unclear to us. Normally our articles and open source contributions are natural byproducts of our work, but Drizzle never found that balance.
• Community contributions have been few and far between. I suspect that Drizzle was too evolutionary a step from Fabricator to inherit that project’s momentum, and not as ambitious as Fractal (which arrived the following month) to spark imaginations. Also, its decentralized structure (spread across four repositories) and incomplete documentation probably made it less approachable to newcomers.

Thankfully, we have a lot more options today than we did four years ago.

Our first instinct was to roll our own Eleventy site, a strategy we’ve used successfully for a few recent design systems (a topic we plan to write about one of these days). This would give us the freedom to tailor a pattern library experience to our exact wants and needs, something that’s critically important for many of our clients. But our own team’s needs are more focused, the end products far simpler. In our case, even a reduced amount of bespoke development seemed a bit overblown.

So we started reevaluating our web-based options (as we do for every design system tooling project we tackle):

• Catalog and Vue Design System dictate a specific front-end framework, which rules them out.
• Fabricator, Herman and Pattern Lab are limited to one or two template languages which don’t quite align with our current projects.
• Astrum, Ether and Fractal simply lack one or more features we’re looking for.

Storybook was the only option we tried that met all our requirements. It supports many front-end frameworks and anything that outputs HTML. Documentation pages, accessibility testing and theme switching are all supported via add-ons.

We’re enjoying it! By far our favorite aspect of Storybook so far has been its emphasis on add-ons. It feels pretty magical to have live parameter editing, colorblindness simulation, viewport resizing and theme switching built right into our UI without much configuration.

We’re also impressed by the pace of Storybook’s development, releasing new updates every week or two (which we automatically apply). That enthusiasm seems to extend to the project’s large community: An issue we opened on an unofficial add-on was resolved in less than a week.

It isn’t perfect. A few obstacles we’ve encountered:

• Storybook’s documentation seems to lag a bit behind its development. The project’s Medium posts and GitHub repo are often more reliable points of reference.
• Its UI isn’t as approachable as we’d like it to be. Pointer targets are a bit small, toolbar buttons frequently lack text labels, links lack adequate color contrast. We haven’t been able to address these issues via theming the way we’d expect to.
• Features added to the toolbar don’t always carry over to docs, which sometimes requires repetitive stories to document all available permutations of a pattern.
• It’s very easy for CSS from one story to leak into others.
• Source code display is frustrating to configure, though this should be improving in the next major version.

None of these are deal-breakers for this project, but they could be for others.

We aren’t making this change for the heck of it: We’re evolving our patterns to embody our current best practices. That means embracing design tokens, variable fonts, CSS grids, higher contrast and deeper integration with our site’s back-end. We’ll be sharing more as we go along, and you can preview our progress as it happens.