A civic-minded citizen seeking the singularity

An entry


Date: 2014-12-23
Status: release
Tags: css livedocs

What is a Styleguide?

A Styleguide is a form of documentation. A blueprint, of sorts.

A Live Styleguide is an artifact that represents the visual design and interaction patterns of a web application.

What a Styleguide is not

In my opinion, Documentation is loaded term, and not all documentation is equal. Wikipedia has its description of Documentation. For me, documentation is an artifact (or group of artifacts) to convey information about a specific topic. In my line of work, documentation mostly about how to use or build software.

I've had a difficult time convincing modern developers of the value of documentation. I think the 1980-2000's era of thick, 3-hole punched, paper help-manuals for Enterprise software have made their indelible mark.

Somehow RDoc and all the handy auto-generated doc tools for software projects get overlooked as being documentation at all.

Understandably, traditionally help-manuals are of questionable value. Barely anyone I know admits to using them. And even when I've found one helpful, it is helpful for only a limited time - aka, I read it, I now know how, and I don't need this help anymore. So fickle.

But this seems to be inline with most things we do today as consumers. That item helped, it can be thrown out. I'd argue that being read once and thrown out is success, as far as that type of Documentation goes.

But, a Styleguide is not the type of Documentation.

A Styleguide is like a 3d blueprint tied to a modern building plan.

A Styleguide should both guide and reflect its Product.

Why is a Styleguide Helpful?

When building, iterating, and discovering a product, code (and thus UI) inevitably diverges.

A Live Styleguide provides a mechanism to iron out web components in neutral test-bed. Lists, paginators, navbars, sidebars, profile info, avatars, thumbnails, and basic HTML elements, etc.

The product may be working well enough. Specs are passing for the CRUD'ing of records in forms and such. The DRY'ness of the code may be good, yet sub-optimal. If people are writing UI components by hand each time, I'd guess that at least a few flavors of the UI element exists. Consist-ify that UI!

Where we did write basic HTML by hand, we can now hand-write components using Ember {{custom-ui-element value="this" key="that" id="123"}}. We can now compose interfaces from higher-order UI elements (Web Components). Having a Styleguide to build and display the Web Components makes sense. A Styleguide is a great place to ensure patterns are consistent and modular. It also happens to be a great for of Documentation.

The Goal of a Styleguide

In any case, our goal is to reduce the "airgap" between the live site and the style guide. The contents of the Styleguide should display real UI, with source code linked and available. The Styleguide should have meaningful coverage of the surface-area of the application's interface.

How to Reduce the cost of Maintaining the Styleguide

The Styleguide must be managed, and ideally, it will be in the natural flow of both Developers and Designers.

By chunking reusable blocks of UI, we have a sensible place to help ensure we stay aware and DRY of the detailed patterns in a large web application. Web Components are made from basic HTML elements, plus Javascript behavior.

Much like the value of writing tests after-the-fact diminishes their value, developing a Styleguide for a site after the fact, is less valuable than it could have been if more design/dev pairing work is done early.

The Cost of a Styleguide

The notion of a Live Styleguide is simple, but it can be difficult to realize a truly "Live" and complete styleguide from a technical perspective. It is highly dependent on how an application has been built, and it an vary greatly between web stacks.

Who Maintains a Styleguide?

Developers on the team own it. Collab with Designers often. Try hanging your UI on a wall in your workspace. Immerse yourself in it. Anybody should be able to mark up a screenshot and have a conversation with Design and the team about styles or interactions.


Make a habit of refactoring out to a Styleguide as a way to keep your UI design and interactions consistent.