What I Know

How to Create a Live Style Guide That Won’t Be Dead on Arrival

Are you thinking about creating a live style guide, or trying to revive the one you have? Read this first.

Tune in to product development conversations online and the topic of design systems and live style guides will undoubtedly find its way in front of you. It’s easy to feel like your organization is the only one left working without one. A sense that there is greener grass out there can seed doubt about your own process.

Live style guides are a critical tool for some product teams. For others, it still suggests the style guide of yesteryear—dusty, irrelevant documentation that someone once put together only to have it go unused.

Traditional, static style guides have earned a reputation for being cumbersome to produce, difficult to maintain, and falling very quickly out of date, particularly in an Agile world. They can at turns clarify and confuse.

A live style guide—which defines the components of a website or app with actual code—is a tool of choice for today’s product team.

So what is a live style guide? Do you need one? And if you do, how can you prevent it from being dead on arrival and ensure that it warrants the effort you spent to create it?

What Is a Live Style Guide?

Let’s start with what they are not: They’re not static style guides or brand guidelines, PDFs, or written descriptions of what code should be.

Live style guides are living documents that evolve over time with your product. Perhaps you’ve heard reference to them as “design systems” or “pattern libraries” (it’s true that the nomenclature may differ from one company to another). What is consistent about these tools is their purpose. They’re resources for coders, designers, and/or content creators that define a product’s user interface with working examples of all or some combination of the following elements:

  • The atoms, or building blocks, such as typography, color palettes, icons, buttons, and badges
  • The components, or reusable interface elements, such as navigation bars, list views, form fields, modals, and alerts
  • Grid systems for composing layouts
  • The rules for third-party plugins
  • The interactive states and animations for all of the above

Why People Love Them

There are a lot of good reasons for both developers and designers to love live style guides. Philosophically they align with both the Atomic approach to design and the Agile methodology, creating shortcuts that save time, and capturing tested best practices. They are highly collaborative yet they ensure consistency, which is invaluable when you are working in large or dispersed teams or with outside vendors or contractors. They also bridge gaps between disciplines—such as between designers and developers—and allow you to hand off specifications more easily between individuals or groups.

A live style guide reduces reliance on word-of-mouth definitions and serves as a central point of record. It becomes the source of truth for your team.

Typically live style guides produce clean, tested code components and templates to pull from that will play nicely together. Some teams will choose to use them as repositories that you can copy and paste easily from. For others, the style guide referenced internally will be the very same code base that powers the live site or app.

Why People Are Skeptical of Them

Not everything is all sunshine and butterflies in the world of live style guides, as the title of this blog suggests. Typically a team might set out to create the sort of guide I describe above, and end up with something that feels confusing, immediately out of date, or creatively restrictive. Worse still, they’ll feel like they’re wasting precious resources on a deliverable they can’t quite define. Here are a few of the ways live style guides can go off the rails:

  • The audience is not inclusive. Your style guide was created for a particular team, for example developers, without attention to how other collaborators will use it. The lack of consideration gives people a reason to ignore it with impunity.
  • Too narrow a focus. Your style guide focused on documenting an initial subset of features but your team lacks a process for expanding it when the use cases you need aren’t there.
  • Lack of ongoing attention. Your team creates an initial version and thinks of it as a set it and forget it document. The information quickly becomes unreliable, out of date, or abandoned.
  • Ongoing contribution lacks structure. Your lack of process may suppress a group’s ability to contribute or you may be too wide open, allowing uncurated editing by everyone and their cousin Greg. In either case, you’re stifling the usefulness of the style guide.
  • Creating a trophy piece. The style guide is meant to support product development, not become the primary product. Too much attention and over-documentation will lead to the style guide being a precious, but unjustifiable, artifact.

All of these issues can be potential deal-breakers for even the best-intentioned or supported live style guides, so it can be easy to see why some companies are yet to adopt them or have abandoned attempts at creating them. But life without a style guide can be just as rough. You lose the opportunity to bring everyone into consensus before things go off the rails. You create a rat’s nest of practices—none of which can be considered “best”—that make it nearly impossible to train new designers or work with contractors or outside vendors (or even sometimes other groups within your company.)

The Recipe for a Kick-Ass Live Style Guide

Step #1: Plan it

Start as you would with any product—by talking to all stakeholders and creating requirements for your live style guide (or whatever you end up calling it). If you don’t get their buy-in now, you’ll miss the chance to create broad ownership in the resource. You need to realistically define a scope for this work. After all, you’re about to embark on creating what amounts to a second product—albeit an internal one.

Understanding who will use it and how, and soliciting their thoughts, will make the guide more useful to everyone and decrease the chances of conflict down the line. Not sure might be using it? Here are a few ideas:

Step #2: Document it

If you want people to adopt and use your live style guide, you need to treat it will the same care you do any of your other products.

That means allocating design and engineering resources and taking the time to define what elements of your product need to be documented and to what degree. If you’re going to use the same codebase for the style guide and your live product, your style guide will technically have everything and the kitchen sink included in it. But you still have the opportunity to decide what to surface and document in order to provide your team with information without overwhelming them.

Step #3: Use it

Once you’ve created a beautiful, inclusive style guide, don’t let it die on the vine. Your intention is for this guide to become the backbone of your design and development, so treat it as seriously as you do any other tool.

Allocate resources to keep the style guide current, with constant iterations, additions, revisions, and reviews. Define when the style guide is updated in relation to the live product.

Enforce the guide but don’t enshrine it. Guides that are not allowed to grow (or are too carefully guarded by gatekeepers) will stagnate, so build a reliable, easy way to incorporate new code into your canon.

Want More? We Gathered Expert Perspectives

You’ve heard our perspective. Now learn how other companies are approaching their live style guides. Check out Let’s Talk: Live Style Guides, where we chat with three product experts about best practices and lessons learned.

If you’re embarking on creating a live style guide for your product, we applaud you. Be considerate—apply our advice above in the context of your product and your organization. It’s going to be an exciting journey.