We use a living frontend styleguide to document our brand’s visual style and commonly used HTML, CSS, and JavaScript components. This styleguide includes functional examples and sample markup, and acts as an entry point for both product prototyping and development.

This is the first of a series of posts that will explore the evolution of the styleguide since its inception in March 2013, and the ways it has changed our approach to development.

The beginnings of our styleguide

Sometime in early 2013, a group of Eventbrite designers and engineers gathered during lunch for “UI Hour,” a weekly meetup where we watch interesting videos and discuss ways to improve the Eventbrite user experience. That week we were viewing Julie-Ann Horvath’s HTML5DevConf talk Open Source Tools and Libraries for Designers, where she discusses how tools like pattern libraries and styleguides can make developing user interfaces easier for everyone.

At that time, the only guides we had were static PSDs living in on our designers’ laptops, so we decided to investigate how a shared living styleguide might improve our current process. What were pain points for designers, our UX team, and engineers? Was our development status quo flawed?

Initially, the styleguide was a skunkwork effort started by two engineers and a lone designer. Today, the styleguide is a huge collaboration between our engineering, design, and UX teams, and plays a major role in how we design and code our features.

What is a living styleguide?

There are many different kinds of styleguides. Some guides help teams stick to agreed-upon code conventions, while others teach how to communicate with users using the appropriate tone and language. Our styleguide is an inventory of our site’s basic building blocks, such as our responsive grid and other layout helpers, and any reusable HTML, CSS, and JavaScript components, like buttons, forms, pagination, etc.

Our styleguide “lives” by using the same code as the live site. When a component’s style or behavior changes in the styleguide, it also changes in production – including breaking changes that need immediate attention.

How does it work?

We accomplish this tight styleguide-as-reality-as-styleguide loop with KSS, which automagically generates the sample markup, live examples, and helpful notes on usage from comments in our CSS. We can commit this:

// Small Buttons
//
// Compatible in IE7+, Latest Chrome, Safari, Firefox
//
// :hover - Normal with hover
// :active - Normal active
// .btn--secondary - Secondary button
// .btn--secondary:hover - Secondary button hover
// .btn--secondary:active - Secondary button active state
// .btn--action - Action button
// .btn--action:hover - Action button hover
// .btn--action:active - Action button active
// .btn--disabled - Disabled button
//
// Markup:
// <button class="btn btn--small {$modifiers}">Button Tag</button>
// <a href="#" class="btn btn--small {$modifiers}">Anchor Tag</a>
// <input type="submit" class="btn btn--small {$modifiers}" value="Input Submit"></a>
//
// Styleguide 3.2.1.1
.btn--small {
    font-size: $btn--small-font-size;
    padding: 9px $horizontal-unit * 2;
    line-height: 18px;
}

and see this:

All our reusable styles and components are bundled into the same CSS file, which we call our styleguide CSS, and get included on every page of our site. This ensures that our styleguide styles are accessible and ready to use for all projects. This also creates a clean separation between styleguide CSS and “non-modular” CSS, or styles that are page-specific and can’t be reused.

Why use a styleguide?

In many cases, as your site and team grows, so do your lines of CSS – unnecessarily. Over time, code left unchecked becomes bloated and complex, and starts to manifest as visual inconsistency on your site. This happens for a number of reasons:

• If your CSS is poorly architected to begin with, bad decisions become hard to undo and inevitably compound (i.e. specificity battle royales that end with the final !important).

• Non-frontend experts need to write HTML and CSS for the features they build, and copy and paste from old, outdated code (it’s not their fault – how are they supposed to know which examples to use?).

• It’s not easy enough to update old components with new visual styles, leading to multiple variations when there could be only one.

• There’s no channel for shared knowledge so code and effort gets duplicated when new designers and engineers join your team, or you have designers and engineers working on separate parts of the product.

• There’s no single source of truth when design needs conflict with engineering resources.

We care a lot about design and we care a lot about our code. Without a clear contract of consistency and reusability, and without a system for managing both design and engineering priorities, it becomes difficult to scale as a product and an organization.

Styleguides help solve these problems by acting as common ground for how a site should look and feel, and how it should be built. Visual Design, UX, and Engineering can start projects with a shared understanding of which components already exist and can be reused, and what needs to be created.

Not only does this prevent miscommunication and duplicated work across teams, it keeps our codebase small and our brand’s visual language consistent with the love and care we give our users every day.

Styleguides also encourage designers and engineers to make sound architectural decisions from the beginning. Every style and component gets sifted through a collaborative sieve. Is this styleguide-worthy, or is it a one-off? Are we adding unnecessary complexity to both our site’s visual language and our code? Will this be easy for non-frontend experts to use and understand?

For more on the numerous other benefits of styleguides, I would recommend reading Anna Debenham’s book Front-End Style Guides, or her blog post on the same subject. Susan Robertson’s article Creating Style Guides on A List Apart is also a great read.

Up next

Creating the styleguide was just the first step. Next we had to tackle integrating it with our existing codebase and development culture. In the post to follow, I’ll discuss how we made the transition, and the ways our styleguide encouraged us to rethink our development practices.