From Drizzle to Storybook

Written by Tyler Sticka on

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.

Why update at all?

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.

Why not a Drizzle update?

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.

Why Storybook?

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):

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.

How’s it going?

Showing off features of our work-in-progress Storybook.

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.

What’s next?

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.

Tyler Sticka

Tyler Sticka is Cloud Four’s VP of Design, allowing him to think about design systems every day. When he isn’t directing his team, sketching on sticky notes or nitpicking CSS, he enjoys reading comics, making video games and listening to weird music. He tweets as @tylersticka.

Never miss an article!

Get Weekly Digests


Solid choice. It seems like a logical switch given the flexibility it offers. I’ve used Storybook mostly with React projects, but recently incorporated it into a PHP-based (vanilla HTML) project as client-side companion to document CSS class usage (using the @storybook/html view layer). It’s obviously a great solution for documentation, but I also often suggest it as a development tool because the DX of building components (or even whole pages) in isolation is so nice out of the box.

This article is SO timely for me! Building my first Storybook (HTML version) as a starting point for designer and I to pre-build design system and components until engineering is ready for project. You’re spot on about the docs being a bit of an obstacle. Getting SASS inheritance and the design tokens addon to work with custom properties was confusing. We’ll use the design token addon for time being, but it doesn’t work for any calc() or var() values. We may end up switching to docs like you’re using.

In any case, the designer is stoked about being able to see FE work along the way, rather than months after submitting mocks.

Thanks for the writeup. Keep us posted!

Let’s discuss your project! Email Us