The Design-to-Dev Handoff Workflow

A good design-to-development handoff comes down to three things: a source file organized around real components and states rather than one-off screens, explicit documentation of spacing, type, and interaction rules instead of relying on a developer to eyeball them, and a shared checklist both sides agree on before any code gets written. Skip any one of these and the build will drift from the design in ways that only show up after launch. This guide walks through the workflow in order, from file setup through the last review pass, using our Figma theme collection as a concrete reference for what a handoff-ready file looks like.

Most handoff problems are not caused by a bad designer or a careless developer. They are caused by a handoff that treats the Figma file as the deliverable, when the real deliverable is a shared understanding of how the interface behaves. A static screen can look finished and still leave a dozen open questions: what happens when this button is disabled, what happens when this card has no image, what happens when this list has one item versus fifty. The workflow below is built to surface those questions before a single line of code is written, not after a sprint of guesswork.

Step 1: Structure the Figma File Like a Component Library, Not a Mockup

The single biggest lever for a smooth handoff is how the design file itself is organized. A file built as a sequence of full-page mockups forces a developer to reverse-engineer the underlying components by comparing screens against each other. A file built around a proper component library — buttons, cards, form fields, navigation, each with their variants — hands the developer the actual building blocks they need to write reusable code.

• Build every repeating element (product card, badge, price display, nav item) as a Figma component with variants for its real states, not a flat shape you copy and re-edit each time it appears.
• Name layers and components in plain language that matches what the code will call them — ProductCard, PriceBlock, AddToCartButton — rather than default names like Group 14 or Frame 212.
• Keep one source page for the design system (colors, type scale, spacing units, component variants) separate from the page-by-page screen designs that consume it.
• Use auto-layout consistently so spacing and alignment are expressed as real, inspectable rules rather than something a developer has to measure with a ruler tool on every screen.

This is exactly how the templates in our Figma theme collection are structured, and it is worth studying that structure even if you are not using one of our themes directly — the underlying discipline (components before screens, a documented system before page layouts) transfers to any ecommerce build.

Step 2: Document States, Not Just Happy Paths

A mockup typically shows the ideal case: a product with a great photo, a short title, and a price that fits neatly on one line. Real stores are messier. Titles run long, images are missing, prices carry a strikethrough compare-at value, and stock runs out. If the design file only shows the happy path, the developer either has to guess at these states or come back to you mid-build with questions that stall the sprint.

• Empty states — no products in a collection, no results in search, an empty cart.
• Overflow states — long product titles, long variant names, many badges on one card at once.
• Loading and transition states — what shows while a collection page fetches, what happens on add-to-cart before confirmation.
• Error states — a failed checkout step, an out-of-stock variant, a form validation error.
• Density extremes — how a grid looks with one product versus a full page of fifty.

You do not need a polished screen for every single one of these, but you do need at least a rough annotation or a note in the file. Even a simple sticky-note comment ("if title exceeds two lines, truncate with ellipsis") saves a developer from making that call themselves, inconsistently, screen by screen.

Step 3: Write Down the Rules the Screens Cannot Show

Some decisions live in the designer's head and never make it into the file: the exact breakpoint where a layout switches from grid to list, whether a hover effect should be a subtle scale or a color shift, how many pixels of spacing separate a section from the one below it. A handoff document does not need to be long, but it should make these rules explicit rather than leaving them to be inferred from a single static frame.

A minimal handoff document should cover

• Breakpoints — the exact widths where layout changes, and what changes at each one.
• Spacing scale — the small set of spacing values used throughout (for example 4/8/16/24/32/48px) rather than ad hoc numbers per screen.
• Type scale — heading and body sizes, weights, and line heights as a short table, not something read off each individual layer.
• Interaction rules — what animates, what does not, and roughly how fast (a snappy 150ms micro-interaction reads very differently from a lazy 500ms one).
• Accessibility notes — minimum contrast expectations, focus-state treatment, and anywhere color alone is used to convey meaning (like a sold-out badge) that also needs a text label.

This does not have to be a separate 20-page spec. A single page in the same Figma file, or a short README alongside the export, is enough as long as it is written down somewhere both sides will actually look at.

Step 4: Use Real Content Before You Call It Done

Lorem ipsum and placeholder product names hide problems that only appear with real content: titles that wrap awkwardly, descriptions that run past the space allotted for them, product images with wildly different aspect ratios. Before a design goes to development, swap in a sample of real or realistic store data — actual product names, actual price formats, actual image dimensions from the merchant's catalog. It is far cheaper to catch a layout problem in Figma than to catch it after the section has been built and populated with a live catalog.

Step 5: Run a Joint Walkthrough, Not a File Drop

The handoff moment itself matters as much as the file. Dropping a Figma link in a message and moving on invites the developer to make dozens of small, invisible interpretation calls over the course of the build — each individually minor, but adding up to a result that feels subtly off from what was designed. A short walkthrough call, even 20 to 30 minutes, where the designer talks through the component structure, the states, and any tricky interactions, catches misunderstandings while they are still cheap to fix.

• Walk through the component library first, before any individual screen, so the developer understands the vocabulary of the system.
• Point out anything unusual or non-obvious explicitly — an interaction that is easy to build wrong, a spacing rule that looks inconsistent but is intentional.
• Agree on how questions get handled during the build — a shared thread, a recurring short check-in, whatever keeps small questions from turning into silent guesses.

Step 6: Review Against the Design, Not Against Memory

Once a section is built, review it side by side with the Figma file rather than from memory of what was discussed. Overlay tools, or simply opening the build and the design in adjacent windows at the same viewport width, catch drift that a quick glance misses: spacing that is close but not exact, a font weight that shipped as regular instead of medium, a hover state that got skipped. This review is far faster when Step 1 through Step 3 were done properly, because there is an actual spec to check against instead of a vague shared impression of what was agreed.

If you are starting a build rather than reviewing one already underway, choosing a source file that was built with this discipline in the first place removes most of this friction. Our Optics Figma theme is one example of a file organized exactly this way — structured components, documented states, and a system page separate from individual screens — so a developer working from it is handed a real specification rather than a set of static pictures to reverse-engineer.

Putting the Workflow Together

In practice the workflow above is not a rigid sequence you run once — it is a small set of habits repeated on every section you design and build. Structure components before screens. Document the states a static frame cannot show. Write down the rules living only in the designer's head. Test with real content. Walk through the file together instead of dropping a link. Review the finished build against the actual design rather than a memory of the conversation. Teams that build these habits into their normal process spend far less time on handoff rework, because most handoff problems are really documentation problems wearing a different name.

If you are choosing a starting point for a new store build, it is worth browsing our Figma theme catalog with this workflow in mind — look specifically at how a file is organized into components and system pages, not just how the final screens look, since that structure is what determines how smooth the eventual handoff to a developer will be.

Frequently Asked Questions

Who should own the handoff document — the designer or the developer?

The designer is usually best placed to write the first draft, since they know the intent behind spacing and interaction choices, but the developer should review and add to it before the build starts. Treat it as a shared document that both sides edit, not a one-way memo.

How much detail is actually necessary for a small store build?

Scale the documentation to the size of the project. A small single-page build might need only a short states list and a quick verbal walkthrough. A full multi-template storefront benefits from a proper component library and a written spacing and type scale, since the cost of drift compounds across many more screens.

Does starting from a pre-built Figma theme replace the need for this workflow?

No, but it removes most of the setup work. A well-structured theme like our Optics Figma theme already gives you the component library and documented states — your remaining job is customizing content, adjusting the system to your brand, and running the same joint-review discipline on whatever you change.

What is the single highest-leverage step if a team can only adopt one?

Structuring the file around real components and their states, rather than one-off screens. Nearly every other handoff problem — missing states, inconsistent spacing, unclear interactions — becomes far easier to catch once the file itself is organized the way the code will actually be built.