For years I handed off Figma files the way most designers do: tidy frames, named layers, a component library that actually resolves. I thought that was the job. Then I worked with an engineer named Jonas Bekker on a scheduling tool called Tandem, and he asked me a question that changed how I work. Looking at a date picker, he said, “Why isn’t this a calendar grid? Did you try that?” I had. I’d spent two days on a grid version before scrapping it. None of that lived anywhere he could see.
The Handoff Problem
Design files are a record of conclusions, not reasoning. They show the door you walked through, never the three you tried first and shut. Engineers inherit the conclusion and have to reverse-engineer the reasoning, usually by asking you in a Slack thread three days later when they’ve already started building the wrong thing.
What Usually Goes Wrong
On a project for a logistics startup called Harbor Flow, I watched this cost us eleven days. A developer built a multi-select dropdown I’d rejected in week one because it broke on long labels. He had no way of knowing I’d rejected it. He just saw a clean spec with no dropdown and assumed I hadn’t considered one. We rebuilt it twice before anyone said the word “labels” out loud.
The Annotation Pass
Now, before I send any file out, I add a page called Reasoning. It’s not polish and it’s not a style guide. It’s a plain record of the decisions behind the screens, written in under half an hour, usually right after I’ve stopped looking at the work with fresh eyes and started looking at it with tired, honest ones.
What I Actually Write
The format is loose but the content is consistent. For every screen with more than one plausible solution, I note:
- The alternative I tried and a one-line reason it failed
- Any constraint that isn’t visible in the file itself, like a data limit or a legal requirement
- What I’m least confident about, flagged honestly rather than hidden behind confidence
- Where I expect the design to break first under real content or real usage
That last point matters more than the others. Designers are trained to defend their work. This pass asks you to attack it instead, in writing, before someone else gets the chance.
A Real Example
On Tandem, the Reasoning page for the booking flow ran to fourteen entries across nine screens. One read: “Tried showing all available slots in a single scrollable list. Killed it after testing with Mireille Ferrand’s calendar, which had 40+ daily events. List became unusable past slot 20. Switched to a filtered view with a manual ‘show more.’” Jonas read that note and skipped a conversation that, on the previous project, had taken us three meetings.
The Numbers
Across six months of using this habit with three different engineering teams, our average number of post-handoff clarification threads dropped from around nine per project to two. Build time didn’t change much. What changed was the shape of the delay: less waiting on me to remember why, more time spent actually building.
Pushback
Some designers I’ve shown this to think it’s overkill, a kind of defensive documentation for people who don’t trust their own instincts. I understand the suspicion. It does take time. It does feel, some weeks, like writing a legal brief for a decision about button spacing.
But the alternative isn’t that I skip the reasoning. It’s that I keep it in my head, where it’s unavailable to anyone but me, including the me who will have forgotten it in four months when someone asks why a feature works the way it does.
When It’s Not Worth It
I don’t do this for every file. A marketing landing page with one obvious layout doesn’t need a Reasoning page. I reserve it for flows with real ambiguity, places where a sensible person could have built it three different ways and gotten three different outcomes. If I can’t think of a second approach I rejected, there’s nothing to write down, and that’s a useful signal on its own.
What It Changes About the Work Itself
The unexpected effect has been on my own process, not just the handoff. Knowing I’ll have to write down why I rejected an idea makes me actually test the idea instead of waving it off. I’ve kept weaker options alive longer just because I knew I’d need a real sentence to justify killing them, and twice that extra half hour of testing changed my mind.
It’s a small habit. It adds maybe twenty minutes to a process that already has too many steps. But it’s the twenty minutes that used to leak out later as confusion, rebuilt screens and meetings that existed only because nobody had written down the thing I already knew.
