Technote

Development workflow Practical

Series From design file to WordPress — the handoff Part 6 of 8

Hand over a spacing scale, not a list of numbers

"37px here" solves exactly one spot. "Spacing is chosen from these twelve steps" solves every screen you never drew as well.

The most common form of a handoff document is arrows and numbers: 24 here, 32 there, 37 in between. It looks precise, but it has two problems. First, where those numbers came from does not travel with them. Second, anywhere you did not draw an arrow is still undecided.

A developer handed the number 37 will use 37. Then, building a similar spot on the next screen, they will not know what to use and will ask again. Every number you hand over only defers one question.

What a scale actually is

A scale is the complete list of values you are allowed to use. Building it from a base of four is the most common approach — 4, 8, 12, 16, 24, 32, 48, 64 — dense at the small end and sparse at the large one. A one or two pixel difference is visible in a small gap; eight pixels barely register in a large one.

One scale used at three densities — a single list of values, different ranges in use

The usual mistake is too many steps. If 20, 24 and 28 all exist, whoever is choosing hesitates every time, and hesitation shows up as a different answer on every screen. Around ten steps is plenty for most sites.

A scale covers the screens you never drew

This is where a scale earns its keep. Building a new screen without one, a developer copies values from a nearby screen. If the copied value was itself an exception, the exception propagates, and after a few rounds an off-scale value has become the de facto default.

A scale hands over the method for choosing a value, not the value

In a WordPress theme the scale can live as variables in the style layer. Once named spacing steps exist in the stylesheet, building a new component means calling a name rather than typing a number. From that point on, using an off-scale value is a deliberate act — and deliberate acts get caught in review.

Handling the exceptions

There will always be places the scale does not solve: aligning a logo by eye, optically correcting an icon. Mark those as explicit exceptions. One line does it — “off-scale, optical correction”.

A declared exception is safe. What is dangerous is a value nobody can tell apart from a mistake, because the next person will copy it.

Getting tokens and scales genuinely into a theme is covered further in the development workflow archive, and the tools we build and use ourselves are available from our free tools page.

Next part

With the rules handed over, it is time to look at the build. The next part is reviewing an implementation — citing broken rules instead of asking for pixel nudges.

More on this topic

All technotes

Development workflow Advanced

The design QA checklist to run before release

Most design problems found after release are catchable before it, in order. Here is the pass, in three stages: rules, states and real devices.

Designers 6 min read

Development workflow Advanced

Never deploy without a way back

A rollback is not one button. It is two tracks — code and database — with an order to reverse them in, written down before you deploy.

Designers 9 min read

Development workflow Advanced

Adding your own hooks: extension points instead of edits

Code with no extension points gets forked or edited in place. Where you put do_action and apply_filters — and how many — decides how long that code survives.

Developers 7 min read

₩270,000 · Join the program