Every freelancer learns the same lesson eventually: the quality of your design handoff to developers decides whether a build ships on schedule or bleeds three extra weeks of change requests. The mockups are rarely the problem. The problem is everything the file never said out loud.
This is the exact routine I run before marking a Figma file ready for development, what gets missed most often, and what each omission actually costs in rework hours. No theory, no “improve communication” platitudes. Just the artifacts a developer needs in front of them before writing the first line of code.
What a design handoff to developers really is
A handoff is not a link to a Figma file. It is a transfer of decisions. Every pixel on a screen represents a decision someone made: this gap is 24px, this button turns grey when disabled, this title truncates after two lines. If the decision is not documented, the developer makes it instead, usually at 2am, usually differently from what you intended.
Here is the test I apply to my own files. Open the file as if you had never seen the project. Can a developer build the first three screens without sending you a single message? If the answer is no, the file is not ready.
The cost of a vague handoff
Rework is the silent killer of freelance margins. A missing empty state costs ten minutes to design and four hours to retrofit once the component has already been built, styled and reviewed. Multiply that across a twenty screen product and you understand why so many projects quietly double in length.
| What gets missed | What the developer does instead | Typical rework |
|---|---|---|
| Spacing tokens | Eyeballs values, hardcodes 13px, 17px, 22px | Full CSS pass, 4 to 8 hours |
| Component states | Builds default only, invents hover and disabled | 2 hours per component |
| Error and empty states | Ships a blank container or a raw API error | New design round plus QA cycle |
| Responsive rules | Guesses the breakpoint behaviour | Layout rebuild on mobile |
| Asset exports | Screenshots from the canvas | Blurry assets caught at launch |
| Content limits | Assumes text always fits | Broken layouts in production data |
1. Spacing tokens and layout rules
Developers do not think in pixels pushed around a canvas. They think in variables. If your spacing is arbitrary, their code will be arbitrary too.
Define a scale and stick to it
- Pick a base unit (4px or 8px) and publish the full scale as Figma variables: space-4, space-8, space-12, space-16, space-24, space-32, space-48, space-64.
- Apply the scale through Auto Layout padding and gaps, never through manual nudging.
- Include container max widths, grid column counts and gutters per breakpoint.
- Document border radius and elevation as tokens too: radius-sm, radius-md, shadow-card.
The test: select any random frame in the file. If Dev Mode shows a padding of 17px, you have a token problem and the developer will inherit it.
Auto Layout is documentation
Auto Layout is the closest thing Figma has to describing flexbox behaviour. A frame with correct hug, fill and fixed settings tells a developer how the element should respond before you write a word. A frame of absolutely positioned layers tells them nothing. I rebuild any screen that is not fully in Auto Layout before handoff, because the hour I spend there saves the developer three.
2. Naming conventions that match the codebase
Naming is where most freelance files fall apart. “Rectangle 482” and “Frame 12 copy 3” are a direct tax on someone else’s time.
My naming rules
- Components: Category/Name/Variant, for example Button/Primary, Input/Text, Card/Product.
- Properties: use words a developer would use in props: size, variant, state, icon, disabled. Not “style 2” or “version B”.
- Pages: number them so the build order is obvious: 01 Cover, 02 Foundations, 03 Components, 04 Flows, 05 Archive.
- Frames: name screens after the route, not the mood: /checkout/payment, not “Payment final v4 FINAL”.
- Colours and type: semantic first, literal second. surface/primary and text/muted travel into code. “Blue 2” does not.
If the project already has a codebase, ask for the component names the developer uses and mirror them. A thirty minute conversation about naming before you design saves days of translation later.
3. Component states: the full matrix, not the happy path
This is the single biggest source of back and forth in a design handoff to developers. Designers present the default state because it photographs well. Developers need every state because the browser demands them.
For every interactive component, I ship this matrix:
| Component | States required |
|---|---|
| Button | Default, hover, focus (keyboard ring), active, loading, disabled |
| Input field | Empty, placeholder, focus, filled, error with message, success, disabled, read only |
| Select / dropdown | Closed, open, item hover, selected, multi select, no results |
| Card / list item | Default, hover, selected, skeleton loading, unavailable |
| Page / section | Loading, loaded, empty, error, partial data, offline |
| Modal | Open, closing, scrolled content, confirm pending |
Focus states are not optional
Keyboard focus rings get skipped more than any other state, and they are the first thing an accessibility audit flags. Design the focus ring once as a token, apply it everywhere, and note the minimum contrast ratio you are targeting. It takes fifteen minutes and removes an entire category of late stage fixes.
4. Responsive behaviour documented, not implied
Three artboards at three widths do not explain what happens between them. Write the rules next to the screens:
- Breakpoint values in pixels and what changes at each one.
- Which elements stack, which hide, which reorder.
- Navigation transformation (sidebar to drawer, tabs to select).
- Image behaviour: crop, contain, fixed ratio.
- Minimum supported width. If you support 320px, show 320px.
- Touch target minimums on mobile (44px is the safe floor).
What gets missed most: the tablet range. Almost nobody designs 768px to 1024px, and almost every project has a bug there in week one.
5. Typography, colour and theming
Deliver these as published Figma variables and styles, not as a static style guide image.
- Every text style with font family, weight, size, line height, letter spacing and the exact web font file source.
- Fallback font stack for when the web font fails to load.
- Colour tokens with hex plus semantic alias (text/primary, border/subtle, state/danger).
- Dark mode mapping if the product has one. If it does not, say so explicitly in the file so nobody assumes.
- Licensing details for paid fonts. Developers cannot ship a font they are not allowed to host.
6. Asset exports done properly
A developer should never have to ask you for a logo. Create an Assets page and set export settings before handoff.
Export checklist
- Icons: SVG, outlined strokes, consistent viewbox, no embedded colour if they need to inherit currentColor.
- Logos: SVG plus PNG fallback, light and dark variants, with clear space rules.
- Illustrations: SVG where possible, otherwise PNG at 1x, 2x and 3x.
- Photography: WebP or AVIF with the original source, plus intended crop ratios.
- Favicons and app icons: the full size set, including 180px and 512px.
- Naming: lowercase, hyphenated, no spaces. icon-cart.svg, not “Icon Cart Final.svg”.
Zip the folder and attach it to the handoff. Do not rely on the developer slicing assets from the canvas, because that is how blurry logos reach production.
7. Edge cases: where the real money is saved
This is the section that separates a professional handoff from a pretty file. I keep a dedicated Edge Cases page and I annotate directly next to the relevant screens.
Content extremes
- Longest realistic string for every text field, and the truncation rule (ellipsis, wrap, two line clamp).
- Shortest case: a one character name, a zero value, a missing avatar.
- Number formatting: currency, thousands separator, decimals, negative values.
- Dates and time zones, including relative formats like “2 hours ago”.
- Pluralisation: 1 item versus 0 items versus 1,248 items.
- Localisation headroom if the product will be translated (German strings run 30 percent longer).
System behaviour
- What loads first and what shows while waiting (skeleton, spinner, nothing).
- Pagination or infinite scroll, and what the end of the list looks like.
- Form validation timing: on blur, on submit, live.
- Every error message copy, written out. Not “error message here”.
- Permission variants: what a logged out, free tier or admin user sees.
- Destructive action confirmations and undo behaviour.
Each of these takes a sentence to write. Each one missing takes a meeting, a redesign and a redeploy.
8. Interaction and motion specs
Motion is frequently described as “make it smooth”, which means nothing to someone writing CSS transitions. Give numbers:
- Duration in milliseconds (150ms for micro interactions, 250 to 300ms for panels).
- Easing curve, ideally as a cubic bezier value.
- What property animates: opacity, transform, height.
- Trigger and direction (drawer slides from right, modal fades plus scales from 0.98).
- Reduced motion alternative for users with that preference enabled.
A short screen recording of a prototype attached to the handoff note beats three paragraphs of description.
9. Set up the file for Dev Mode
Figma Dev Mode is now the default inspection surface for most teams, so use it properly instead of assuming the developer will find things.
- Mark finished sections as Ready for development so the build queue is unambiguous.
- Use annotations directly on layers for behaviour notes instead of floating sticky notes nobody reads.
- Publish your variables so values appear as tokens in the inspect panel, not as raw hex codes.
- Archive old explorations on a separate page and label it clearly. Obsolete screens left in the main file are the most common cause of the wrong thing being built.
- Link related Jira or Linear tickets to the frames if the team uses them.
- Lock your foundation layers so nothing drifts after the handoff.
Handoff tool options
| Tool | Best for |
|---|---|
| Figma Dev Mode | Default choice, inspection, tokens, annotations, code snippets |
| Storybook | Teams with a live component library to compare against |
| Zeplin | Larger teams needing versioned, organised spec delivery |
| Notion or Confluence doc | Edge cases, copy, business logic that does not belong in a canvas |
| Loom recording | Walking through flows and motion in five minutes |
10. My actual handoff routine, step by step
Here is what I do the day before I send the file, in order. It takes roughly half a day on a mid sized project and it has never once cost me more than it saved.
- Clean the file. Delete or archive everything that is not final. One source of truth.
- Run a naming pass. Every layer, frame, component and style gets a name a stranger would understand.
- Audit tokens. Detach nothing, hardcode nothing, check every spacing and colour value maps to a variable.
- Build the state matrix. Every interactive component gets its full set of variants on the Components page.
- Write the edge case page. Content limits, errors, empties, permissions, loading.
- Export assets. Set export settings, zip, name sensibly.
- Annotate in Dev Mode. Behaviour notes, breakpoint rules, motion specs, links to tickets.
- Record a 5 to 10 minute Loom. Walk the flows, explain the intent, flag the three things most likely to be misread.
- Hold a 30 minute live handoff call. Developer asks questions, I answer, both of us take notes.
- Stay available for a defined window. I include a fixed number of support hours in the quote so questions during the build are expected, not awkward.
Why the live call still matters
No document covers everything. The thirty minute call is where a developer says “this animation will cost two days” or “this layout fights our grid system” and you adjust before any code exists. Written handoffs without a conversation are how teams discover feasibility problems in week four instead of hour one.
Mistakes I still see on most freelance projects
- Handing off a prototype as a spec. A clickable prototype shows intent, not rules. Both are needed.
- Designing in pixels that do not divide. A 37px gap tells a developer nothing is systematic.
- Leaving copy as lorem ipsum. Real copy changes layout. Ship real copy or clearly mark a placeholder with a character limit.
- Multiple versions of the same screen in one file. Guaranteed to produce the wrong build.
- No point of contact after handoff. Silence turns into assumptions, and assumptions turn into rework.
- Treating the handoff as an ending. It is the start of a collaboration that runs through QA.
A quick pre-handoff checklist
Copy this into your project management tool and tick it before every delivery.
- File cleaned, old versions archived
- All frames in Auto Layout
- Spacing, colour, type and radius published as variables
- Naming matches code conventions
- Every component has all states including focus and disabled
- Responsive rules written per breakpoint
- Loading, empty and error states designed
- Content limits and truncation rules documented
- All error and system copy written
- Assets exported, named and zipped
- Motion durations and easing specified
- Accessibility notes: contrast, focus order, alt text, touch targets
- Sections marked ready for development
- Walkthrough video recorded
- Handoff call booked
- Support window agreed in writing
FAQ
How long should a design handoff to developers take?
Budget 10 to 15 percent of your design time for handoff preparation. On a two week design sprint that is roughly one full day. If you are spending nothing, you are simply moving that cost to the developer and inviting it back as change requests.
Do I need a separate documentation tool, or is Figma enough?
Figma with Dev Mode annotations covers most of it for small projects. Once you have business logic, API behaviour, permission tiers or long form copy, move that into a written doc and link it from the file cover. Canvases are bad at prose.
What should I do when a developer changes my design during the build?
Ask why first. Nine times out of ten it is a technical constraint you did not know about, and the fix is a quick compromise. Then update the Figma file to match reality so it stays the source of truth instead of becoming fiction.
Should I include code snippets in my handoff?
You do not need to write code, but naming your tokens the way a developer would name variables gets you most of the benefit. Dev Mode generates snippets automatically from your variables, which is another reason to publish them properly.
What is the single most commonly missed item?
Error and empty states. Nearly every file includes the perfect scenario with perfect data and no file includes what happens when the list is empty, the request fails or the user has no permission. Design those three and you remove most of the post launch patch work.
How do I handle handoff when I am not involved in QA?
Negotiate a design review before launch, even a short one. Two hours of review at the end catches spacing drift and missing states while they are still cheap to fix. Price it into the proposal rather than offering it for free.
Final thought
A great design handoff to developers is not about control or about proving the design was right. It is about removing every question a developer would otherwise have to guess at. Tokens instead of pixels, named components instead of rectangles, full state matrices instead of happy paths, written edge cases instead of assumptions.
Do that consistently and the build gets faster, the result looks like the design, and your projects stop quietly swallowing unbilled hours.