How to Do a Proper Figma Design Handoff to Developers

A Figma design handoff to developers is the process of transferring not just design files, but everything developers need to build what was designed: component specifications, interaction behavior, state documentation, breakpoints, and the intent behind design decisions. Most handoffs deliver the first and miss the rest — which is why implementations routinely diverge from designs and revision cycles extend timelines. Poor UX costs businesses $1.4 trillion globally in lost productivity per year (IDC), and a broken handoff process is one of the most common sources of that waste inside product teams.

The goal of a good handoff is not to share a Figma link. It's to equip a developer with enough understanding that they can make good decisions independently when they hit constraints during the build. A developer who understands what you designed and why can adapt intelligently. One who only has the spec cannot. The ROI of doing this well is substantial: every $1 invested in UX design returns $100 on average (Forrester Research), and a large portion of that return comes from reducing the back-and-forth between design and engineering that a poor handoff causes.

This step-by-step guide covers what a complete handoff includes and how to structure it.

Step 1: Structure Your Figma File for Handoff

A Figma file built for design exploration is structured for iteration. A file built for handoff is structured for clarity and navigation. These are different requirements, and the best practice is to maintain a separate, clean handoff file from your working file.

The handoff file should contain:

A cover frame with the feature name, date, status (Ready for Development), and a one-line summary. Developers working across multiple features need to quickly identify what each file is.

A numbered happy path flow showing the primary user journey in order, one frame per screen or state. Number frames explicitly (1.0, 1.1, 1.2) — never make developers guess the sequence.

A state documentation section showing every meaningful state for every interactive element. Buttons: default, hover, focus, active, loading, disabled. Form fields: empty, focused, filled, error, disabled, success. Tables: default row, hover, selected, loading. This section is the most skipped and the most consequential.

Edge case frames showing specifically how the design handles: empty states, long content, truncation, error states, zero-data states, and mobile overflow. Developers build for real data; designers often design for ideal data. Bridge that gap explicitly.

Responsive frames showing the layout at each breakpoint (typically desktop at 1440px, tablet at 768px, mobile at 375px) for any screen with meaningful layout differences.

Keep the handoff file free of exploration frames, rejected directions, and work-in-progress. A cluttered file wastes developer time and creates uncertainty about what's final.

Step 2: Set Up Figma Dev Mode Correctly

Figma's Dev Mode is the baseline for spec delivery — colors, spacing, font sizes, and component properties are available automatically. But Dev Mode is useful only if your file is built correctly.

Before handing off, verify:

Design tokens are applied consistently. Colors, spacing, and typography should reference design tokens (library variables) rather than hardcoded values. When a developer sees --color-brand-primary in Dev Mode rather than #1A73E8, they can use the correct token in code without having to check whether the hex matches. Hardcoded values create translation errors. If your team is building out a shared token library, our guide to design system for SaaS covers how to structure tokens for scale.

Components match their code counterparts. If your codebase has a Button component with variant: primary | secondary | ghost | destructive and size: sm | md | lg, your Figma component should have those exact properties with those exact names. A developer who sees variant=primary in the Figma inspect panel can write that directly in code. A mismatch requires a translation step that introduces errors.

Layers are named, not left as "Frame 1234." Developers navigating the layer panel to understand structure need legible layer names. NavigationBar, UserAvatar, NotificationBadge is navigable. Group 47, Rectangle, Frame 1234 is not.

Auto layout is used rather than absolute positioning where possible. Dev Mode reads auto layout as flex layout, which is directly translatable to CSS. Absolute positioning creates pixel-perfect specs that break when content is dynamic.

Step 3: Annotate Intent, Not Just Appearance

Figma Dev Mode handles appearance. Your annotations should handle everything Dev Mode doesn't: why things work the way they do, what happens in each state, and what the decision logic is.

Annotations that create the most value:

Interaction annotations. On every interactive element, note what happens: "→ Opens confirmation modal" or "→ Navigates to /settings/billing" or "→ Triggers async API call, shows loading state, then success toast." Developers need to know what events to handle, not just how the element looks.

Conditional display rules. "Only visible when user has admin role" or "Shows only when the count exceeds 10" or "Hidden after user completes onboarding step 3." These are implementation instructions that don't exist in the spec. Missing them means incorrect conditional rendering.

Animation and transition. If something animates, specify it. "Fade in, 200ms, ease-out" is sufficient for most cases. Reference your motion tokens if your design system has them. Specifying nothing leads to either no animation or animation that doesn't match what was designed.

Content rules and constraints. Maximum character lengths before truncation. Minimum image dimensions. Alt text requirements. What renders when an image fails to load. These details prevent visual bugs that only appear with real content in production.

Third-party component references. "Uses the Select component from Radix UI" or "This is a Recharts bar chart" tells developers what to reach for rather than asking them to build from scratch.

Keep annotations concise — one question per annotation. Group interaction notes in a separate annotation layer that can be toggled on and off so the design frames stay clean.

Step 4: Document Responsive Behavior Explicitly

Stating your breakpoints at the top of the handoff file establishes the shared vocabulary. "We use sm (640px), md (768px), lg (1024px), xl (1280px) — matching Tailwind defaults" is more useful than expecting developers to infer from frames.

For each responsive frame that differs from desktop, annotate what changed:

"Sidebar collapses to icon-only at 1024px, hides completely at 768px"
"Table converts to card list at 640px"
"Navigation becomes a hamburger menu at 768px, opens a full-screen overlay"
"Two-column layout becomes single-column at 768px, with the image moved below the text"

Notes about what doesn't change are also useful: "Typography scale is identical across all breakpoints" or "Card padding reduces from 24px to 16px on mobile, all other internal padding stays the same." This prevents developers from guessing about elements that weren't shown at every breakpoint.

For complex responsive behaviors that are hard to annotate visually — dashboards with multiple layout changes, navigation patterns that transform significantly — a short written spec in a text frame is often clearer than visual annotations alone.

Step 5: Document Every Interactive State

State documentation is the step most often skipped and the step most often responsible for the gap between a designed experience and a shipped experience. The happy path design shows one state; the implementation needs to handle all of them.

Mandatory states for common elements:

Buttons: Default, hover (visual feedback that it's interactive), focused (keyboard focus ring — this is an accessibility requirement, not optional), active/pressed, loading (spinner for async operations), disabled.

Form fields: Empty with placeholder, focused (active state), filled with content, error (with accompanying error message below the field), disabled, read-only.

Data tables: Default row, hover row, selected row (if selectable), loading (skeleton state), empty (no data to display), with overflow content.

Modals and drawers: Default open state, with long content (to specify overflow/scroll behavior), loading state (if content loads async after open), and the close/dismiss behavior.

Navigation items: Default, hover, active/current, disabled (if applicable).

If a state is not designed, the developer either builds their own interpretation or asks you. Their interpretation is a guess; your answer delays the build. Design all states up front.

Step 6: Review the Handoff Before Sharing

Before sharing the handoff file, walk through it from the developer's perspective — reading only what a developer would see in the Figma inspect panel, layers, and annotations.

Check for:

Every interactive element has all its states
All text layers have specified truncation/overflow behavior for long content
All empty states are designed with guidance
All error states are designed with specific error messages
Responsive behavior is specified at each breakpoint
No components are bespoke — everything is from the component library
All colors and spacing reference tokens, not hardcoded values
Annotations cover all non-obvious behavior

This review takes 30–60 minutes for a typical feature. The investment pays back in fewer developer questions, fewer implementation surprises, and shorter revision cycles after build.

Teams working with a product design for SaaS startups studio will have these handoff conventions built into the workflow — but even if you're managing design in-house, the checklist above is the difference between a build that goes smoothly and one that generates two weeks of back-and-forth.

Component Naming That Matches Engineering

Every component in your Figma file should have a name that matches its counterpart in code. This sounds obvious but is rarely done well, because designers name things intuitively ("card with image," "big blue button") while engineers name things precisely — ImageCard, PrimaryButton.

Before finalising component names in Figma, align with engineering. For a new design system this means a naming conversation before building the library. For a handoff to an existing codebase, it means checking what components already exist and what they're called.

The naming match serves two purposes. When an engineer looks at a Figma frame, they can read the layer name — Button/Primary — and immediately know which component with which variant to use. No translation step. And when a designer mentions DataTable with sorting enabled in Slack, the engineer understands immediately without opening Figma.

This extends to prop names. If the Button in code has variant: primary | secondary | ghost | destructive, your Figma component property should use the exact same names and values. When props match, an engineer reading the inspect panel can write that directly into code.

Handling Design Feedback During Engineering Build

Even a thorough handoff will produce feedback during the build. Implementation reveals things Figma doesn't — how layout responds to real content, how animations feel at actual speed, how form behavior works under real constraints.

Distinguish between spec-incorrect and design-incorrect. If the engineer implemented exactly what was designed and it doesn't work, that's a design problem. If the engineer didn't follow the spec, that's a communication problem. Treating both the same creates resentment.

Batch feedback, don't drip it. Sending Slack messages with individual design notes throughout the build is disruptive. Set up a structured review: engineering builds to staging, designer reviews staging and compiles all feedback into a single pass. One review session beats twenty asynchronous messages.

Separate blocking from non-blocking. Label feedback clearly: "This button state is wrong — blocking" vs. "I'd prefer 2px more spacing here — non-blocking, can batch." Engineers who can't tell what's urgent either do everything (inefficient) or deprioritise everything (suboptimal).

Accept tradeoffs during build. When engineering constraints genuinely prevent implementing the exact Figma spec — a layout that requires significant browser-specific workarounds, an animation that doesn't perform on lower-end devices — trust the engineer's read on the constraint and collaborate on an alternative rather than insisting on the original spec.

Frequently Asked Questions

What's the most important thing to include in a Figma handoff?+

State documentation — the complete set of states for every interactive element. It's the most commonly skipped and the most consequential gap. Happy path screens show one state; the implementation needs to handle loading, error, empty, disabled, and focus states for every component. Developers who don't have state designs either implement their own interpretation or create tickets for designs they're missing, both of which cost time.

Should I use Figma Dev Mode for handoff?+

Yes — it handles the baseline spec layer well. Spacing, typography, colors, and component properties are surfaced automatically in Dev Mode. Your job is to annotate what Dev Mode can't capture: interaction behavior, conditional display logic, animation specs, and content rules. Set up your file correctly (design tokens, named layers, aligned component naming) to make Dev Mode as useful as possible.

How should I handle responsive design in a handoff?+

State your breakpoints explicitly at the top of the file. Show separate frames for desktop, tablet, and mobile (or whatever breakpoints are relevant to your product). On non-desktop frames, annotate what changed and why. Notes about what stayed the same are also useful. For complex responsive behavior, a written spec is often clearer than visual annotations.

What's the right way to annotate Figma files without cluttering the design?+

Use a dedicated annotation layer that can be toggled on and off. Keep annotations concise — one question answered per annotation. Use a consistent visual format (arrows + label for interactions, callout boxes for conditional logic) so developers know what kind of information to expect in each annotation format. Keep interactive annotations visually distinct from design elements by using a contrasting color (a bright annotation orange or a specific annotation component from your library).