Answer 42 of 50
Common Communication Problems Between Designers and Developers During Handoff
Handoff problems are gaps in what the design file says: states nobody drew, widths nobody showed, motion described as a feeling, assets in the wrong format, measurements that fall between agreed values, accessibility details a picture cannot carry, versions nobody marked, and content nobody tested at its extremes. Each gap forces a developer to guess. The fix is a handoff package that answers those questions before the build starts, and the checklist near the end of this page is one version of it.
Missing states
A mockup shows a button. The build needs that button hovered, focused, pressed, disabled, and loading while it waits for a response. If only the default state is drawn, a developer who does not know the intended hover color picks one, and across dozens of interactive elements those choices add up to behavior nobody designed.
Component variants in the design tool make states explicit. Figma’s help article on creating and using variants gives the example that “the state property could have default, hover, pressed, and disabled values.” When time is short, document states by how likely they are to be built wrong: hover, focus, and disabled for interactive elements; empty, loading, and error for components that depend on data; collapsed and expanded for anything that toggles.
Responsive behavior between the drawn widths
Suppose the design shows desktop at 1440 pixels and a phone layout. The build also has to work at 1200, at tablet widths, and everywhere in between. What happens to a three-column layout at 900 pixels: two columns, a single stack, or something else, and at what width does it change? The answer exists in the designer’s head; if it is not written down, different developers can guess differently.
Specify what changes at each breakpoint, and show at least one width between breakpoints, not only the endpoints.
Motion described as a feeling
“This slides in” is not a specification, and neither is “it should feel smooth.” A developer needs duration, easing, direction, and whether other content moves or the element overlays it. For example, “300 ms, ease-out, from the right edge to its final position, overlaying the content” can be built as written. A short interactive prototype can carry timing better than a description.
The spec should also say what happens when a user has asked their system to reduce motion. WCAG 2.2 includes a Level AAA criterion, Animation from Interactions, under which “Motion animation triggered by interaction can be disabled, unless the animation is essential to the functionality or the information being conveyed.” Micro-interactions count too: the focus ring, the loading spinner, and the way an error message appears all need enough detail to build consistently.
Assets in the wrong format
When developers ask for 2x PNGs and receive 1x JPGs, someone re-exports, and then again for the next screen. Agree on formats, resolution multipliers, and file names up front, and use export presets that produce them. Decide who compresses images and who converts formats, because a task nobody owns can fall through the gap between the two roles. Icons need their own decision: SVG or PNG, inline or external files.
Which format suits which image is covered in when to use SVG instead of PNG and other formats, and resolution for sharp screens in optimizing images for high-resolution displays.
Spacing that falls between values
A developer measures 24 pixels of padding, measures again, and gets 26.5. Is it 24, 26, or something else? Visual adjustment in a design tool does not always land on clean numbers, and a developer working from measurements has to pick one.
Agree on a spacing scale, for example 8, 16, 24, 32, and 48, and publish it as named design tokens such as space-300 = 24px, in the design tool’s variables and in code. Designers pick tokens, not raw numbers, and developers use the same token names. A measured value that is not on the scale, such as 26.5px, is a question for the designer, not a value to build. Where no tokens exist yet, a stated value (“the padding is 24px”) beats a measurement. How tokens are stored and shipped across platforms is covered in the long-term benefits of design systems.
Accessibility details a mockup cannot show
Some of what a developer needs cannot be measured from a picture and has to be written down:
| Annotate | Why it has to be written | WCAG 2.2 criterion |
|---|---|---|
| Focus order on each screen | The visual layout does not tell the developer the order keyboard focus should follow | 2.4.3 Focus Order (Level A) |
| Heading levels | A large, bold line may or may not be a heading in the code | 1.3.1 Info and Relationships (Level A) |
| The accessible name of every icon-only button | An icon has no text a screen reader can announce unless one is provided | 4.1.2 Name, Role, Value (Level A) |
| Alt text for each image, or a note that it is decorative | What an image is for on this page is a design decision the code cannot infer | 1.1.1 Non-text Content (Level A) |
| Which field each error message belongs to | The connection between a message and its field is not visible in a static frame | 3.3.1 Error Identification (Level A) |
The criteria are worded in W3C’s Understanding documents. Focus Order asks that “focusable components receive focus in an order that preserves meaning and operability.” Info and Relationships asks that structure conveyed through presentation “can be programmatically determined or are available in text.” Name, Role, Value asks that “the name and role can be programmatically determined” for user interface components. Non-text Content and Error Identification cover the last two rows.
Version confusion
Design keeps iterating while development builds, and someone builds a version that has already changed. Keep one canonical location for designs and mark status plainly, such as “in progress” and “approved for build,” so nobody implements work in progress. When an approved design changes, tell the developers directly; a silent edit in a shared file is one way old versions get built.
Edge cases nobody tested
A design shows cards with three-word titles; real content may have thirty-word titles, and the layout breaks. Run each component through the extremes before the build: very short and very long text, missing images, zero items, one item, and a thousand items, a failed request, a validation error, and a slow load. Designing with real or realistically extreme content shows fragility while it is still cheap to fix.
The handoff checklist
A handoff is ready when a developer would not have to guess about any of these:
- Every interactive element has default, hover, focus, active, and disabled states.
- Components that depend on data have empty, loading, and error states.
- Layouts are shown at each breakpoint plus at least one width in between.
- Animations list duration, easing, direction, and the reduced-motion behavior.
- Assets have agreed formats, resolutions, and names, and someone owns optimization.
- Spacing and color use named tokens, not measured values.
- Focus order, heading levels, accessible names for icon-only buttons, alt text, and error-to-field connections are annotated.
- The file has one approved version, a visible status, and a note of what changed.
- Long text, missing images, and zero, one, and many items are shown.
The process around the package
Treat handoff problems as process problems first: a better process can reduce friction even when the people change. Relationships still matter, because designers and developers who know each other can ask questions sooner. Review the package together instead of sending it and walking away, so questions get answered while the designer is still in the room. Design QA needs one named owner: the designer who wrote the spec knows the intent best, and a QA specialist or a designated developer can own it when that designer is not available. Record the reasons behind decisions, such as why a gap is 24px and not 32px, so the same question does not come back.
The working relationship behind a good handoff, from kickoff to decision rights, is covered in optimizing collaboration between designers and front-end developers.
Questions teams ask
Our designers use Figma, but developers don’t check it. How do we change that?
Make the design file the single source for specifications and assets, and stop sending them through other channels. Before you do, check seats: Figma’s help center lists code snippets in Dev Mode as requiring a Full or Dev seat, so budget one for every developer who implements from the file. Then show developers where to find what they need.
Design keeps changing during development. How do we manage this?
Set change windows: some phases accept design changes, others are frozen. Urgent changes go through an exception process that states the rework cost, so whoever asks for a late change sees what it costs before deciding it is worth it.
Our team is small, or one person does both jobs. Do we need a formal handoff?
Less formal, but still written. Conversation covers a lot when people sit together, but in six months it is easy to forget why a decision was made. A short note of states, values, and reasons keeps the build consistent and answers the question when it comes back.
Before any build starts, run the package through the checklist: if a developer would have to guess about a state, a width, a motion, an asset, a value, an accessibility detail, or a version, the handoff is not finished.