For the first few years of my career, I measured a handoff by how many screens were in it. Forty screens felt thorough. Eighty felt generous. Every state, every breakpoint, every hover, drawn out and lined up in neat rows.
Then I watched a developer work from one of those files. He opened it, zoomed out until the screens were the size of postage stamps, and scrolled around for a while looking for the one he needed. When he found it, he squinted at a button, measured its padding with a tool, and built it. He didn’t look at the other seventy-nine.
The screens hadn’t been useless, but they’d been answering the wrong question. They showed what things looked like. What he needed to know was why, and what should happen when the real data didn’t match my tidy examples.
Fewer screens, more sentences
These days my handoff files are smaller. A typical feature has the key screens, one of each important state, and a lot of short notes pinned right next to the thing they describe. Not in a separate document, not in a ticket: next to the button.
After a few years of trying different approaches with different teams, I’ve found that developers reliably read four kinds of note.
1. What happens at the edges
“Names longer than 24 characters truncate with an ellipsis; the full name shows on hover and in the detail view.” “If there are no spends yet, show the empty state below, not an empty list.” Real data is messy, and the edges are where developers are otherwise forced to guess.
2. What’s deliberate
“The amount is in ink, not red, on purpose: we tested red and people read it as an accusation.” Without that note, the first helpful person to touch the code will change it back. A one-line reason protects a decision for years.
3. What’s flexible
“Spacing here can follow whatever the component library already does.” Telling a developer where they don’t need to be precise is just as useful as telling them where they do. It frees their attention for the parts that matter.
4. What I don’t know yet
“Not sure how this behaves with more than 200 items. Let’s look at it together once there’s real data.” Admitting a gap invites a conversation. Hiding it guarantees a surprise in the middle of a sprint.
Notes are cheaper than screens
A note takes thirty seconds to write. A screen showing the same edge case takes twenty minutes to draw, and then it has to be kept up to date every time the design changes. Most of my old eighty-screen files were out of date within a fortnight of handoff; the notes in my current files tend to stay accurate because there’s so little to maintain.
A drawing shows one answer. A sentence can describe a rule, and rules are what developers actually build.
The handoff call
None of this replaces talking. Every project ends with an hour on a call with the people building it, walking through the file together. I ask them to interrupt whenever something looks odd. The questions they ask in that hour become new notes, so the file gets better for whoever opens it next.
I also stay in the project’s chat for a month after handoff, at no extra cost. It’s rarely busy. When it is, it’s usually a sign that a note is missing, and I add it.
Try it on your next file
Pick one feature you’re about to hand off. Delete the screens that only differ by a hover state or a breakpoint, and replace each with a sentence. Then add one note of each kind above. Ask the developer afterwards which version they’d rather work from.
I’d love to hear how it goes. Write to hello@ddtxv.xyz, or bring the file to critique night.