The style guide nobody opened
Two weeks I enjoyed more than anything else that year, and three buttons that showed up anyway.
I spent about two weeks last fall building a style guide for a client site. Every component on its own page, live and interactive instead of screenshots, the markup sitting underneath each one ready to copy, a color palette with the hex values, the type scale, the spacing units, the whole nine yards. It was the most fun I had on that project.
I checked the site in January. There were three button variants in production that weren’t in it.
Building is the easy part
I think the reason we keep making these is that building one is genuinely pleasant work, and it’s pleasant for reasons that have nothing to do with whether it will be used.
It’s self-contained. It has no client in it, nobody has an opinion about the padding on your documentation page, and you can finish it. Compared to the actual project, which is a negotiation, a styleguide is a craft object you get to make properly. So of course we make them. I’d make another one tomorrow.
And then the thing gets deployed to /style-guide or a subdomain, and everyone agrees it’s great in the meeting where you show it, and that is the last time anybody looks at it.
Failure to launch
Watching a few of these, the failures were pretty consistent:
It’s somewhere else. This is the big one and it’s structural. The style guide lives at a URL, and going to a URL is a decision you have to make, in advance, about a question you might not know you have. Nobody thinks “I wonder if there’s an existing component for this” and then goes and checks. They think “I need a button here,” and there’s a button two files over that they can copy and that only takes a minute. You are competing with copy and paste and you will lose.
I wrote something about view source a while back that I keep coming back to, which is that the tools that actually teach are ambient rather than destinations. A style guide is a destination: same failure, different year.
It drifts. If any part of it is maintained by hand, some of it is wrong within a month. And the moment somebody finds one thing in it that’s wrong, the whole document goes in the trash mentally, because they now have to verify everything they read in it and verifying is more work than just looking at the site.
An out-of-date style guide isn't neutral. It's a second source of truth, and it's lying.
It answers the wrong question. Mine documented what every component looked like and what classes it took. What it did not do, anywhere, was say which one to use. There were three card variants on that site and the style guide showed all three, beautifully, with no opinion at all about when you’d pick each. So a person arriving with an actual decision to make got an exhibit and no help, and the exhibit is the part they could already see by looking at the site.
Still alive
The one that’s still alive is the ugliest, and I think it’s alive for three boring reasons.
It’s generated from the source. The documentation for a component lives in a comment directly above the CSS for that component, and a build step scrapes those comments into a page. That means the docs and the code are the same file so they can’t drift apart, because to make them disagree you’d have to be actively editing the comment while changing the code and choosing to lie.
// Button
//
// The standard action. One primary per screen.
//
// .button--primary - The main thing you want them to do
// .button--ghost - Secondary actions, sits next to a primary
// .button--danger - Destructive only. Never as an accent.
//
// Markup: button.html
//
// Styleguide Components.Button
.button { }What matters is that the documentation is in the file you already have open. It lives in the repo. It’s not on a subdomain that needs its own deploy and its own explanation. It’s built alongside the site by the same command, so if it breaks then the build breaks, and a broken build is a thing that gets fixed. Documentation that can’t fail is documentation nobody notices has failed.
And it’s where the components get built. This is the one that actually changed the behavior. New component gets developed on the /style-guide page first, in isolation, before it goes anywhere near a template. Not for purity reasons, but because it’s genuinely nicer: no bells and whistles, no CMS, no needing three levels of navigation to see the thing in a hover state. Once building there is the convenient option, people are in there daily and they see what already exists, and I stopped having the “we already have that” conversation almost entirely.
Know your audience
The part I’ve only recently admitted is that I built all four of these for developers, and developers were not the problem.
The three random buttons weren’t added by a developer. They were added over half a year by the client’s marketing team, in the CMS, using an editor that will happily let you make text bold and blue and centered, because nothing in that editor knows anything about the style guide. They were just doing their job. There was a campaign, it needed a button, and the tool in front of them offered them a way to make one.
No amount of documentation was going to reach them. They are never going to visit /style-guide. Why would they? They don’t write CSS and the document is written for people who do.
What actually constrains that is the editing interface itself. If the only buttons available in the editor are the two you specifically allowed, and they come out correct because they’re inserted as a component rather than typed as markup, then you’ve got a style guide with teeth and the marketing team never has to read a word of it. That’s much less satisfying to build than a beautiful component library. It’s also the only version I’ve seen work on a site I wasn’t personally maintaining.
A change of perspective
I think the honest summary is that I kept treating the style guide as the deliverable, when the deliverable was the agreement about what the site is made of, and the document was just one way of carrying it. A document is a fairly weak way of carrying an agreement. A build step is stronger. A constrained editing interface is stronger still, because it doesn’t require anybody to remember anything.
I’d still build one. I’d just stop measuring it by how good it looks in the meeting where I show it, and start measuring it by whether anything on the site disagrees with it a few months later. By that measure I’m 1 for 4, and the winner is the one I put the least care into which I’m choosing to find funny rather than uninspiring 🙃