The Spacing Scale Behind Quillfold

Every gap in Quillfold, from the space between a tag and its count to the margin around a whole note, is one of eight numbers. We didn't pick them cleverly. We picked them so that nobody has to pick again.

Why four

The smallest step is four pixels because anything smaller reads as a hairline rather than a gap, and anything between four and eight tends to look like a mistake. Four is also the unit that divides cleanly into the sizes we already used: our text lines sit on a grid of four, and so do our icons.

Linnea made the case for a base of four rather than eight. An eight-pixel base is easier to remember, she said, and it forces everything to feel generous. It also makes the tight places, such as the line between a title and its subtitle, impossible. We use four for those and don't apologise for it.

The scale

Here is the whole thing, generated from the multiples rather than typed by hand.

const base = 4;
const steps = [1, 2, 3, 4, 6, 8, 12, 16];

for (const [i, multiple] of steps.entries()) {
  console.log(`--space-${i + 1}: ${multiple * base}px;`);
}

It prints eight lines, from --space-1: 4px; to --space-8: 64px;, with 8, 12, 16, 24, 32 and 48 in between. Those are the custom properties our stylesheets use. We generate them because a typed list drifts. Someone adds a twenty-pixel step in a hurry, and a year later there are three versions of "a bit more".

Why it stops being even

The first four steps climb by four. After that, the jumps grow: eight, then eight, then sixteen, then sixteen.

The reason is perception. Between a four-pixel gap and an eight-pixel gap, the eye sees a real difference. Between forty-four and forty-eight, it doesn't. At large sizes, small steps give you choices that look identical and mean different things in the code, and that's the worst kind of choice. So the scale spends its resolution where people can notice it.

What each step is for

We write down a job for each, so nobody has to guess.

1. Space 1 and 2 hold things together: an icon and its label, a tag and its count.

2. Space 3 and 4 separate things that belong to the same group, like rows in a list.

3. Space 5 and 6 separate groups from one another, and set the padding inside panels.

4. Space 7 and 8 are for the edges of the window and the gaps between major regions. A day-to-day screen rarely uses either one.

The one rule

Nobody in review is asked whether the spacing looks right. That question starts arguments that nobody wins. The rule is narrower: every gap is a token. If a pull request contains a raw pixel value in a margin or a padding, it doesn't merge, and the reviewer links this post.

It sounds strict. In practice it removes about half of the design discussions we used to have, because the answer is already on the page. When someone does think the scale is wrong, they propose a change to the scale, and the whole product moves together.

Step five, twenty-four pixels, gets overused. It's the right size so often that it's become the default, and some screens would benefit from the courage of a thirty-two. We haven't found a rule for that yet, and we'd rather admit it than invent one.