Nicholas Swanson • Design style guide

In order to improve our product development workflow, the design team built out a living design system.

Getting started

For our users, the primary issues with not having a style guide were inconsistencies of experience and longer loading times. For the design team, those inconsistencies were leading to churn in the design and development phases, as we attempted to reconcile styles and struggled to push new components forward. To address this, we set out to

  1. Pull together our front end into a single repository, consistent with our deployment needs (QA process and versioning, primarily)

  2. Refactor our base styles, utilities, and components

  3. Build out our style guide for a mobile first product

How things looked before


Hello, world

The style guide took several months of iterative improvements. Fortunately, each improvement could be deployed to production within a day, so our users could see improvements often. Over this time, we re-evaluated how we structured our base styles (less Bootstrap), utilities (fewer, more thoughtful), and components (cross-platform conscious). The result was a team effort, and gave clear guidance for not only front end styles, but in-product brand, a writing guide, and email styles.

Looking back

Having a clear, live design system that we were proud to work on together had several benefits beyond the front end code. The effect of working as a design team on a single artifact, over time and with purpose, brought the team together in a way that standard product work cannot. The style guide was a forum for going really deep into topics and needs that only we as a design team could solve, and that brought camaraderie. We had a space to discuss problems like style guide systems (we went with KSS), went way too deep on color naming conventions (we chose @gray with an 'a' over @grey with an 'e'), and broke up into working teams to tackle refactoring.

Once the guide was live, we were all working on projects that touched the style guide, and it kept us honest. We iterated where we needed more, and had hard conversations about how to improve the style guide without adding bloat. A living style guide is a practice I appreciate more now, even more so for the team effects than the literal output.