Figma handoff: what a developer actually needs from you

Most handoff problems are not design problems. The file looks right, the build takes a week longer than quoted, and the reason is always the same: the file describes one perfect moment, and a website has to survive every other moment too.

This is the list of what fills that gap, ordered by how much time it saves.

The states that are always missing

Every interactive element has more than one appearance. A layout file usually shows one.

For each form, each list, and each piece of content loaded from somewhere else, decide:

• Empty. No results, no items, nothing written yet. What does the user see, and what do they do next?
• Error. A required field left blank, an address that is not an address, a payment refused. Where does the message sit, and does the layout move when it appears?
• Loading. What is on screen in the second before the content arrives?
• Too long. A product name of ninety characters. A person named Wolfgang-Maximilian. A heading that wraps to four lines on a phone.
• Too many and too few. Three cards designed, one supplied. Or nine.

That last pair causes more revisions than anything else on the list. A grid of three looks deliberate; the same grid with a single card in it looks broken, and somebody has to decide what it does instead.

Two widths, not one

A single desktop frame does not describe a website. It describes a screenshot of one.

Design the widest view, then design something around 390 pixels wide. With both, a developer can reason about everything in between. With only one, every row of four becomes a question: does it wrap, scroll, stack, or shrink?

Pay specific attention to three things at narrow width, because they break most often:

• Navigation. What replaces the menu, and what happens when it is open.
• Tables and anything in columns. Scroll sideways, stack, or hide some columns.
• Anything fixed to the screen. A sticky bar is fine on a laptop and eats a third of a phone.

A scale, not a collection of numbers

Developers build systems whether or not you hand them one. If your file uses 14, 15, 16, 17 and 18 pixel text, they will either reproduce all five, or quietly pick three and you will notice later.

Before sending, make two passes:

Type. How many distinct text styles are actually in use? If the answer is more than about seven, some of them are accidents. Consolidate them in the file, not in a conversation.

Spacing. Are the gaps multiples of one rhythm, usually four or eight pixels, or are they wherever the element landed? Consistent spacing is the single thing that makes a build match the design without anyone measuring.

This is also how you find out whether your file is finished. A file that resists this pass is a file still being designed.

Assets, exported by the person who knows the size

Export the files yourself. You know how large each thing appears; the developer does not.

• Photographs at twice the display width, no more. A hero that shows at 1200 pixels needs 2400, not 5000.
• Anything drawn — logos, icons, illustrations — as SVG, with text converted to outlines.
• Logos in every version that is actually used: full colour, single colour, and whatever appears on a dark background.
• Names that describe the thing, not the frame. logo-dark.svg, not Group 47.

One more: say which images are decorative and which carry meaning. That decides what the alt text says, and a developer guessing at alt text produces either silence or noise.

What to write down, and what not to

Annotate only what cannot be seen in the file.

Worth writing:

• Where each link goes, including the ones in the footer
• What happens after a form is sent — a message, a new page, an email
• Which content the client will edit, and which is fixed
• Field rules: required, maximum length, accepted formats
• Anything that animates, in one sentence of plain description

Not worth writing: colours, sizes, spacing, font weights. Those are in the file, and repeating them in a comment creates a second source of truth that will disagree with the first within a week.

The ten-minute check before you send

Open your own file as if you had never seen it.

1. Is there exactly one frame per page, and is it obvious which one is current? Delete or clearly park the rest.
2. Does every button and field have a hover and a disabled state somewhere?
3. Is there a narrow frame for every page, or at least every distinct layout?
4. Do the text styles in the file match the text styles in use?
5. Are assets exported, named, and in one folder?
6. Is there one note saying what the site is for and who it is for?

That last point sounds soft and it is the most useful. A developer who knows the page exists to get someone to request a quote will make better small decisions than one who is reproducing shapes.

Then talk for twenty minutes

No checklist replaces a call. Share the screen, walk three pages, and let the developer ask what happens when things are clicked, empty, wrong or very long.

Those questions arrive either in one call or in fifteen messages across two weeks, each one blocking the build until it is answered. The call is cheaper, and it is where you find out which parts of your design were decisions and which were defaults.

Why this is worth the hour

A clean handoff does not just save the developer time. It is the difference between a build that comes back matching your design and one that comes back approximately matching it, which is where the painful revision rounds live.

If you hand off regularly — to an in-house developer, a freelancer, or a white label partner — turn this into your own one-page list and run it every time. It takes an hour the first time and about ten minutes after that.