Writing better handoff notes

I used to annotate everything. Spacing, colours, font sizes, hover states, all in little purple notes around every screen. Developers were polite about it, and then built something slightly different anyway, because the notes answered questions they never had.

What they needed was the reasoning, so they could make the hundred small calls I hadn’t thought of.

Write the decisions, not the measurements

Measurements live in the design file and the tokens. A good handoff note explains decisions: why the list paginates instead of scrolling, why the error message sits above the field, what should happen when the name is forty characters long. Each decision gets one or two sentences and, when it helps, a link to the research behind it.

My notes for a feature now fit on a single page. They are easier to write, and developers actually read them.

List the edges

Most bugs live at the edges: empty states, one item, a thousand items, slow networks, long translations. I keep a short checklist and go through it for every screen before handoff. If a state isn’t designed, the note says so plainly and suggests a sensible default, so nobody has to guess.

Review the build, not the file

The handoff isn’t finished when the note is sent. I book thirty minutes with the developer once the first build is running, and we go through it together on a real phone. Most of the fixes take seconds when we are both looking at the same screen, and the note gets better for next time.

Good handoff is a conversation that happens to have a document attached. Keep the document short and keep the conversation going. If you want help with this on your team, get in touch.