A design system for one
The literature is all about somebody else's company. Three habits survive at any team size, including one.
There’s a lot of good writing about design systems at the moment and I’ve read most of it. It’s genuinely useful and I’ve taken things from all of it.
It is also, almost without exception, written by people at organizations that employ more designers than my agency employs humans. The case studies are a bank, a government, a company with a platform team and a contribution model and a governance document. The problems being solved are coordination problems: 40 people, six product areas, keeping them from diverging.
I have a six-week storefront build for a company that sells industrial fasteners, and I am the only person who will ever open the stylesheet.
So the question isn’t whether any of this applies. It’s which half.
One of me, four months apart
The reason a big team needs a system is that people diverge from each other. Two designers, two buttons, and by month four there are nine buttons and nobody can say which is right. Everything in the literature about governance and contribution and single sources of truth is aimed squarely at that, and it’s aimed well.
I don’t have that problem. There is exactly one of me.
What I have instead is the same problem stretched along a different axis. I built the card component in week two, I come back to it in week five having been on another project in between, and I have forgotten every decision I made. So I build a second card that’s nearly the same. Then the client asks for a change in month nine and there are two of them and I’ve forgotten there are two.
A team diverges from each other. One person diverges from themselves, four months apart, and nobody's there to notice.
Which means the practice transfers and the apparatus mostly doesn’t, because the apparatus is built for the coordination problem and I’ve got the memory problem.
The three that survive
A scale, decided once, for spacing and type. This is far and away the highest value per minute of anything in this post. Not a system, a short list of numbers. The moment you have one, “how much space goes here” stops being a judgment call 40 times a project and becomes a choice between four options, and the site gets visibly more coherent without anyone doing anything clever.
$space: (0: 0, 1: 0.25rem, 2: 0.5rem, 3: 1rem, 4: 2rem, 5: 4rem);
$type: (small: 0.875rem, base: 1rem, lead: 1.25rem, h2: 1.5rem, h1: 2.25rem);
:root {
--space-3: #{map-get($space, 3)};
--space-4: #{map-get($space, 4)};
}The reason both halves are there is the thing I worked out last fall: the Sass map is for build-time math and generating utilities, and the custom properties are for anything that needs to change per breakpoint or per theme after the CSS has shipped. Same numbers, two lifetimes.
Named colors, never a raw hex in a component. Same argument. If every rule says var(--brand) then the client’s inevitable “can we try it in the darker green” is one line, and if 40 rules say #2f6f4e then it’s a find-and-replace and you will miss the one in the SVG.
One place per component. Not a package, not a repo, just: the card exists in _includes/card.html and every page includes it, and there is nowhere else that card markup can be. Jekyll include, WordPress partial, Twig block, doesn’t matter. The discipline is that if you catch yourself copying markup you stop and make it a partial, right then, even though it takes 11 minutes and you’re busy.
That’s it. That’s the whole system, and none of those three requires a tool.
Built from the same parts
Last year I built a proper style guide for a client site and wrote a fairly bleak post about how nobody opened it. Part of that was distribution, which I still think is the main failure. But there was a second problem underneath, which is that it was a separate thing that had to be maintained, so within about three months it described a site that no longer existed.
The fix turns out to be embarrassingly simple, and I’ve done it on every project since.
Make a page in the actual site, at a real URL, that includes the same partials the real pages include, with sample content.
<h2>Cards</h2>
{% include card.html title="A short title" meta="Category" %}
{% include card.html title="A considerably longer title that wraps onto three lines because someone will do that" %}
<h2>Spacing scale</h2>
{% for step in (0..5) %}<div class="swatch mb-{{ step }}">{{ step }}</div>{% endfor %}Because it’s built from the same includes, it cannot drift. If I change the card, the page changes. If I delete the card, the page breaks the build and I find out immediately, which is a feature.
And the second thing it gives you, which I didn’t anticipate and now rely on, is a place to put the ugly cases. The title that wraps to three lines. The card with no image. The button with a word in it that’s longer than the button. Those are the states that break in production two months after launch, and having them all on one screen means I see them while I’m building rather than when a client emails a screenshot.
Things I skip
A separate style guide tool. There are several good ones now and I’ve tried two. For a team they look like a nice way to work. For me they’re a second build, a second set of dependencies to update, and a second thing that gets stale the week the project goes quiet. The cost lands on the person with the least capacity to absorb it, who is me in month nine on a retainer.
Publishing anything as a package. Versioning is a coordination mechanism between people who ship on different schedules. I ship on one schedule.
Writing down principles. I did this once, four paragraphs about clarity and restraint, and I have never read them again and neither has anyone else. The scale is the principles. It just happens to be executable.
Two jobs, one phrase
The honest summary is that “design system” is doing two jobs in the way people use it. There’s a set of habits about not repeating yourself and deciding things once, which is free and works at any size including one. And there’s an apparatus for keeping a large group of people aligned, which is expensive and solves a problem I haven’t got.
The literature is mostly about the second, because the second is where the hard and interesting problems are, and because nobody writes a conference talk called “we agreed six numbers for margins.”
Six numbers for margins, though. Genuinely, if you do one thing.