I didn't open my own style guide
A page on a client site needed a button last week. So I opened a template three folders over, copied one out, and dropped its padding a few pixels because the layout was tight. Took a couple minutes.
I built that site’s style guide in January. It has a button page, live and interactive, with the markup sitting right underneath ready to copy. I didn’t open it. It never crossed my mind to open it, and that second half is the part I’ve been thinking about since.
Two weeks went into that thing and they were the best two weeks I had on the project. I had Atomic Design open the entire time. Every component on its own page, live instead of screenshots. The markup under each one. A palette with the hex values, the type scale, the spacing units. I presented it on a call, everybody said it was great, and as far as I can tell that call is the last time it was open in anybody’s browser, mine included.
No notes on the documentation page
I think we keep building these because building one is genuinely pleasant work. It’s pleasant for reasons that have nothing to do with whether anyone will ever use it.
It’s self-contained. There’s no client in it, which is most of the appeal tbh. Nobody in the history of this industry has had a note about the padding on a documentation page, which is a strange feeling when the rest of your week is a negotiation over a hero image. And you can finish it. Actually finish it, which is not a thing the project itself is ever going to let you do. So of course we build them, and I’d build another one tomorrow and have a great time doing it.
Then it goes up at /style-guide, and everyone agrees it’s great on the call where you show it, and the call is where it stops.
Two files over
Going to a URL is a decision you have to make in advance, about a question you don’t yet know you have. Nobody thinks “I wonder whether there’s already a component for this” and then goes and checks. They think “I need a button here,” and there’s a button two files over they can copy without deciding anything. That’s the actual competition. A style guide is up against copy and paste. It loses, and it loses even when the person holding the mouse is the one who wrote it.
I wrote something about view source back in January, and the part that stuck with me is that everything which actually taught me anything was ambient. It was already on the screen. I never had to decide to go and look at it. A style guide is a destination. Same failure, different year.
The one I can account for
So I went and counted, which took ctrl+f and a slow afternoon.
There are three button variants live on that site that aren’t in the style guide. Three variants that ostensibly couldn’t exist, since the document listing every button we have was sitting right there the whole time. One of them is mine, from last week. The other two I can’t explain at all.
None of the three was a decision. Nobody sat down and designed a fourth button. Somebody needed the existing button to be a little different in one place, had nowhere to put “a little different” except a new class name, made one. There it sits. I did precisely that, and I’m the person who is supposed to care about this.
So which one do I use?
The other failure is more squarely mine, since I had complete control over it.
The guide documented what every component looked like and which classes it took. It never said which one to pick, anywhere. There are three card variants on that site and the guide shows all three, beautifully, side by side, with no opinion at all about when you’d want each. So somebody turning up with a real decision to make gets an exhibit, and the exhibit is the part they could already see by looking at the site.
I’d written down the inventory. An opinion is what anybody actually needed.
The one in the other repo
There’s a style guide in another repo here, on a project that predates me. It’s ugly. Default fonts, no layout to speak of, every component stacked one after another down a single column. People open it constantly, which took me a while to notice and longer to be honest about.
The documentation for a component lives in a comment directly above the CSS for that component, and a build step scrapes those comments into the page.
// Button
//
// The standard action. One primary per screen, and if you want two,
// the screen is asking two questions and should be split.
//
// .button--primary - the thing you actually want them to do
// .button--ghost - secondary, sits next to a primary
// .button--danger - destructive only, never as an accent color
//
// Markup: button.html
//
// Styleguide Components.Button
.button { }Go and look at what that comment does that my whole style guide didn’t. One primary per screen. Never as an accent color. Three lines of opinion, written by somebody who was plainly tired of having the conversation, and worth more than every page I built.
The other thing about it, and I suspect this is the whole trick, is that it’s in the file you already have open. You’re in _button.scss because you’re changing the button, and the documentation is right above your cursor. Nothing had to be decided. Nobody had to remember a URL or keep a bookmark alive. The tab you’d have needed is the tab you’re already in.
Then there’s where the components get built. New ones go on that page first, in isolation, before they go anywhere near a template. Not out of any principle, it’s just nicer to work that way: no bells and whistles, no navigating three levels deep to get the thing on screen so you can see it in a hover state. And once building there is the convenient option, people are in there daily. They see what already exists in passing.
Which is the ugly version that exists beating the beautiful one again, except this time the beautiful one is mine and I built the entire thing myself.
The call went great
I think what I did was treat the document as the deliverable, when the deliverable was the agreement about what the site is made of, and a document turns out to be a weak way to carry an agreement. A comment above the code is stronger. Documentation you’re standing in front of when the question arrives is stronger still, mostly because it asks nobody to remember anything.
I’d build another one. I’d enjoy it every bit as much, which is worth being suspicious about (and I say that as the person who just spent two weeks on one!) I’d only stop measuring it by how the call goes, since that measures the two weeks and not the document, and start measuring it by whether anything on the site disagrees with it a few months later. On this one the count so far is three buttons to nothing, and one of those three went in last week, put there by the only person who has read every word of it.