By Mehdi HassanWhat should be in a Figma file before handing it to developers?
Before handing a Figma file to developers, it should contain every decision they need to build without guessing: a clear structure, tokens on every value, auto layout components, all states, responsive rules, final copy, ready assets and behavior notes. A file that only shows the happy path at two widths isn't ready, however polished it looks.
This checklist is written from the developer's side of the table, by a team that both designs and builds. Each item is something that, when missing, makes a developer stop, ask or invent. It's one part of the wider process in our design handoff guide. Work through the 30 items below in order; the groups follow the order a developer meets them.
Group | Checks | What breaks if it's skipped |
|---|---|---|
Structure and naming | 5 checks | Developers can't find the right frame or build the wrong version |
Tokens and styles | 5 checks | Hard-coded values, broken dark mode, drift from the system |
Layout and components | 5 checks | Layouts that don't stretch, wrap or align like the design |
States | 6 checks | Invented loading, empty and error screens |
Responsive | 3 checks | Guesswork at every width between your two frames |
Copy, assets and accessibility | 6 checks | Overflowing text, blurry images, inaccessible controls |
How should you structure and name a Figma file for developers?
Structure the file so a developer opening it for the first time finds the ready designs in seconds and knows what's final. Naming matters because frame and layer names often end up in conversations, tickets and generated code.
- Separate pages for ready work and exploration. Put work in progress, old versions and ideas on their own pages, never next to final screens.
- Mark ready-for-dev sections clearly. Use Figma's ready-for-dev status or an obvious label, and only on frames that won't change.
- Name frames by feature and state. Billing / Invoices / Empty is useful; Frame 482 is not.
- Name layers that matter. Containers and repeated elements should have names that hint at the component, like InvoiceRow or Sidebar.
- Add a cover or index. One frame that lists flows, links to them and says who to ask.
Our guide to Figma file organization covers page structures and naming conventions in more depth.
How do you check tokens and styles before handoff?
Check that every visual value in the design comes from a variable or style, and that each one has a name the codebase recognizes. If a developer has to sample a color with an eyedropper, the file isn't ready.
- No raw hex values. Every fill and stroke uses a color variable, ideally semantic (color/text/muted, not gray/500).
- Spacing and radius use variables. Gaps, padding and corner radius come from the spacing and radius scales.
- Text uses text styles. No loose font sizes. Each style matches a step in the type scale.
- Code syntax is set on variables. Developers see the CSS variable name in Dev Mode, not just a Figma label.
- Modes work. Switch the page to dark mode, or another theme, and check nothing stays hard-coded.
Are your layouts and components built like the code will be?
Layouts and components should behave in Figma the way they'll behave in CSS: stretching, hugging, wrapping and aligning by rule rather than by manual positioning. If a frame breaks when you resize it, the developer can't tell what the intended behavior is.
- Auto layout on every container. Cards, lists, forms, nav and page sections all use auto layout, so gaps and padding are explicit. See auto layout in Figma.
- Correct resizing rules. Each element is set to fill, hug or fixed deliberately, matching how it should behave in the browser.
- Instances, not copies. Screens use library components. Detached instances are reattached or flagged as intentional one-offs.
- Component properties match code props. Variant and property names line up with what the codebase uses.
- A consistent grid. Page layouts sit on one column grid with defined margins, and the grid is documented.
Which states do developers need to see?
Developers need to see every state a user can reach, not just the ideal screen. Missing states are the most common reason a build looks different from the design, because the developer had to invent them.
- Interactive states. Hover, focus, active and disabled for every interactive component.
- Loading states. What the screen shows while data loads, including partial loading when parts arrive separately.
- Empty states. First-use and no-results versions, with real copy and an action.
- Error states. Form validation, failed requests and permission errors, each with a written message.
- Extreme data. Very long names, large numbers, many items, one item and zero items.
- Success and confirmation. What happens after the main action: a toast, a redirect or an updated view.
Why focus states matter more than they seem
Focus states are what keyboard users see when they move through a page with the Tab key. If the design doesn't show them, developers often remove the browser's default outline because it clashes with the design, and nothing replaces it. That makes the product unusable without a mouse. Draw a visible focus style as part of each interactive component, and check it against our WCAG 2.2 checklist, which covers focus visibility and appearance.
How do you hand off responsive behavior?
Hand off responsive behavior as rules plus a few key frames, not a frame for every device. Developers build fluid layouts, so they need to know what changes, at what width and why.
- Key breakpoints drawn. At least mobile, tablet or small laptop, and desktop for complex screens.
- Rules written for in-between widths. Which columns stack, what collapses into a menu, what truncates and what wraps.
- Maximum widths defined. How wide content gets on a large monitor, and what happens to the space around it.
Are copy, assets and accessibility ready?
Copy, assets and accessibility are the last group, and the one most often left for later. They shouldn't be, because each one changes the build: real copy changes layouts, assets need the right formats, and accessibility shapes the markup.
- Final copy everywhere. No lorem ipsum or draft headlines. If copy isn't final, say which parts will change.
- Error and helper text written. Every message in every state, in the product's voice.
- Icons as components, exportable as SVG. On a consistent frame size with color set by a variable.
- Images marked for export at the right sizes, or linked to the source, with notes on cropping and focal points.
- Contrast checked. Text and controls meet WCAG contrast requirements in every theme.
- Behavior annotated. Animations, transitions, keyboard behavior and anything a static frame can't show, written next to the design. See annotating designs for developers.
How do you run the handoff once the Figma handoff checklist is done?
Once the checklist is done, walk a developer through the file instead of sending a link. Thirty minutes covering the flow, the states and the edge cases will surface the questions the checklist didn't catch. Add the answers to the file as annotations.
Run the checklist yourself
Go through all 30 items before the walkthrough, and list anything deliberately left open.
Walk through it live
Show the main flow, then each state, then the responsive rules. Let the developer interrupt.
Capture answers in the file
Every question answered in the call becomes an annotation, so the next developer doesn't ask again.
Stay reachable during the build
Answer questions within hours, not days, so the developer doesn't fill gaps with guesses.
Dev Mode makes inspecting a prepared file easier; our Figma Dev Mode review covers whether it's worth the seats. If you're building on Framer or Webflow rather than in code, see preparing Figma files for a Framer or Webflow build. And if handoffs keep breaking despite good files, why design handoffs fail explains the structural causes.
We use this checklist on our own files, even though our designers and developers are one team. If you want a brand refresh or redesign explored in Figma, our brand and design sprint is $3,000, fixed: a refresh or redesign plus 10 website or product explorations, delivered as Figma files. See what's included on our pricing.
