Turning a Figma design into code means handing off more than pictures of screens: design tokens, component structure, responsive rules and interaction states all have to travel too. A healthy handoff rests on a shared token system, Figma components mapped to their code counterparts, measurements delivered through Dev Mode and missing states designed before development starts.
Why does the designer–developer handoff go wrong?
The designer–developer handoff goes wrong because static Figma screens cannot fully describe dynamic behaviour in a browser. In Figma every card title is the same length, every form is filled in correctly and the frame is exactly 1440 pixels wide. Once real content, real data and different devices arrive, every undefined decision lands on the developer.
- —A long product name overflows its card and breaks the layout.
- —A developer picks their own colour and font size for an error message that was never designed.
- —At tablet width the menu behaves like neither the desktop nor the mobile version.
- —The same grey appears in seven slightly different values and nobody knows which is correct.
Related services
What are design tokens and why define them first?
Design tokens are visual decisions such as colour, typography, spacing, corner radius and shadow stored as named variables, for example color-primary-600 or space-4. Design tokens should be defined first because when design and code share the same vocabulary, changing a colour means updating one value instead of fixing hundreds of screens one by one.
- —Primitive tokens: raw values, such as a specific hex code for blue-600 or a 16-pixel spacing unit.
- —Semantic tokens: names that describe intent, such as primary background colour or error text colour.
- —Component tokens: values tied to a single component, such as primary button background or card padding.
Tokens defined in Figma with Variables and modes (for example light and dark themes) can be mirrored one-to-one in CSS custom properties or a configuration file such as Tailwind's. When token names match on both sides, a designer saying 'this gap should be space-6' leaves the developer nothing to guess.
How do you map Figma components to code components?
Figma components are mapped to code components by sharing the same name, the same variants and the same property logic. If the Figma Button component has size and variant properties, the React Button component should accept size and variant props with identical values. That mapping lets developers assemble ready-made parts instead of coding every screen from scratch.
- —List the code name and file path for every component in the Figma library.
- —Match variant properties (size, variant, state) one-to-one with prop names.
- —Merge pieces that are split in Figma but can be a single component in code.
- —Keep one-off, screen-specific designs at page level rather than in the library.
- —When a new component is needed, add it to the Figma library first, then build it.
Figma's Code Connect feature shows the team's real code usage example, instead of auto-generated CSS, when a component is selected in Dev Mode. Setting it up takes extra effort, but with a large component library and several developers it noticeably improves consistency.
How should responsive breakpoints be handed off?
Responsive breakpoints are handed off not as mobile and desktop mockups but as rules describing the behaviour in between. The designer should draw at least three widths, for example 375, 768 and 1440 pixels, and the developer should be able to read from Auto Layout which elements flex and which stay fixed. In-between widths like 1024 pixels cause most bugs.
- —Define breakpoint values as tokens and match them to the values in code.
- —Use fill and hug correctly in Auto Layout; fixed widths only where truly needed.
- —Specify maximum content width and side margins for every breakpoint.
- —Note the width at which the grid column count changes.
- —Document how images are cropped and which images are hidden on mobile.
What does Figma Dev Mode add to the handoff?
Figma Dev Mode lets developers inspect measurements, spacing, colour tokens and typography values directly, copy CSS or platform-specific code snippets and export assets. Marking screens as 'ready for dev' makes it clear which designs are final and stops developers from building a draft that is still going to change.
The CSS Dev Mode generates is a starting point, not production code. It can include absolute positioning, fixed widths and class names derived from layer names. The right approach is to read measurements and tokens from Dev Mode and build the layout with the project's own components and utility classes. Use version comparison to see what changed after a frame was marked ready.
For your project
Why must hover, empty and error states be designed separately?
Hover, empty and error states must be designed separately because users spend much of their time outside the 'happy path'. Every undesigned state gets filled by a developer's snap decision and drifts from the brand language. Every interactive component needs defined default, hover, focus, active, disabled and loading states.
- —Hover and focus: a visible focus ring is essential for keyboard users.
- —Loading: skeleton screen or spinner, and after how long it appears.
- —Empty state: what appears when there is no data yet, and which action is suggested.
- —Error state: separate messages and styling for field errors, server errors and lost connections.
- —Success state: what the user sees after a form is submitted.
- —Edge content: very long titles, missing images, single-item lists.
What gets lost in the handoff?
The information most often lost in a handoff is animation timing, behaviour with real content lengths, accessibility requirements and the reasoning in the designer's head. A Figma file shows what was drawn but not why it was drawn that way. A short handoff meeting and notes in component descriptions close most of that gap.
- —Animation durations and easing values (for example 200 ms, ease-out).
- —Accessibility rules such as colour contrast and tap target size.
- —Alt text for images, and which images are purely decorative.
- —When text should truncate and when it should wrap.
- —The business reason behind a decision, such as why the call-to-action sits where it does.
A practical Figma-to-code handoff checklist
A practical Figma-to-code handoff checklist quickly tests whether a design is ready for development. Starting to code before every item below is ticked usually comes back as a long revision list at the end of the project. The checklist works best when the designer and developer walk through it together in the handoff meeting.
- —Colour, typography, spacing and radius tokens are defined as Variables.
- —All components live in the library and variant names match code props.
- —At least mobile, tablet and desktop widths are drawn.
- —Auto Layout is used and fixed widths are deliberate.
- —Hover, focus, disabled, loading, empty, error and success states are designed.
- —Screens are tested with realistic content (long titles, missing images).
- —Animation durations and easing values are documented.
- —Assets have export settings and SVG icons are clean.
- —Final screens are marked 'ready for dev' in Dev Mode.
- —Open questions are left as comments on the component with an owner assigned.