Most build delays do not come from hard code. They come from a Figma file that answers 80% of the questions and leaves the other 20% to Slack messages. A developer opens a screen, sees a button, and has to ask: what happens on hover? What is this gap, 14px or 16px? Where is the empty state? Is this shadow a token or a one-off?
Each of those questions costs a context switch for two people. Multiply by 40 screens and you have lost a week. This design handoff checklist exists to kill that back-and-forth before it starts, by structuring the file properly the first time.
What is a design handoff, in one paragraph
A design handoff is the moment a design file becomes a build specification. It includes the screens, the measurements, the exported assets, the interaction behaviour, the responsive rules and the edge cases. A handoff is complete when a developer who was not in a single design meeting can build the feature without asking you anything. That is the standard we are aiming for here.
The 12-point design handoff checklist at a glance
| # | Checklist item | Question it prevents |
|---|---|---|
| 1 | File structure and naming | “Which frame is the final one?” |
| 2 | Spacing and sizing tokens | “Is this 14 or 16?” |
| 3 | Colour and typography variables | “Is this a new grey?” |
| 4 | Auto layout on everything | “Does this stretch or stay fixed?” |
| 5 | Every component state | “What does hover look like?” |
| 6 | Responsive breakpoints | “What happens on tablet?” |
| 7 | Edge cases and data limits | “What if the name is 60 characters?” |
| 8 | Empty, loading and error states | “What shows before data loads?” |
| 9 | Export-ready assets | “Can I get this logo in SVG?” |
| 10 | Motion and transition notes | “How fast should this slide in?” |
| 11 | Accessibility annotations | “What is the alt text and tab order?” |
| 12 | Content, copy and microcopy source | “Is this real copy or placeholder?” |
The full checklist, item by item
1. File structure a developer can navigate in 30 seconds
Developers do not know your file. They open it cold, usually on a deadline. Structure it so the entry point is obvious.
- One page called Ready for Dev containing only approved, final frames.
- Explorations, rejected options and old versions moved to an Archive page, not deleted (developers sometimes need to see why a decision was made, but they must never confuse it with the build).
- Frames named the way the feature is named in the ticket system:
Checkout / Step 2 / Payment / Desktop, notFrame 447. - A cover frame with the file purpose, the owner, the last updated date and a link to the relevant tickets.
- Mark sections with Figma’s Ready for development status so nothing ambiguous slips through.
Rule of thumb: if a frame is on the dev page, it is a contract. If it is not final, it does not belong there.
2. Spacing tokens instead of eyeballed gaps
This is the single biggest source of handoff friction. When spacing is arbitrary, a developer measures pixel distances, rounds them, and produces a UI that is close but never right. Then QA opens tickets about it.
Define a spacing scale as variables and use nothing outside it:
| Token | Value | Typical use |
|---|---|---|
| space-1 | 4px | Icon to label |
| space-2 | 8px | Inside small chips |
| space-3 | 12px | Form field padding |
| space-4 | 16px | Card padding, stacked fields |
| space-6 | 24px | Between component groups |
| space-8 | 32px | Section separation |
| space-12 | 48px | Page block rhythm |
Apply them as variables in auto layout gap and padding fields, not as typed numbers. When the developer inspects the element, they see the token name and can map it straight to the CSS variable or Tailwind class. That single habit removes the majority of “is this 14 or 16” questions.
3. Colour, type and radius as named variables
Raw hex codes are a red flag. If a developer sees #3B4A5F they cannot know whether it is text-secondary, a one-off, or a mistake.
- Every colour applied through a variable with a semantic name:
surface-default,text-muted,border-subtle,action-primary. - Light and dark modes handled as variable modes, so the developer sees both values in one place.
- Type styles defined with font family, weight, size, line height and letter spacing baked in. Never a manual override on a text layer.
- Border radius, shadows and blur values tokenised too. Shadows are the most commonly re-invented style in any file.
Before handoff, run a plugin that scans for detached styles and local overrides. Fix everything it finds. It takes 20 minutes and saves days.
4. Auto layout on every frame that will ever resize
Auto layout is not a designer convenience, it is documentation. It tells the developer which element is fixed, which fills the space, which hugs its content and what happens when text grows. See uxpin.com for their take.
- Set Fill or Hug deliberately on each layer and explain unusual choices in a note.
- Set min and max width on containers that have limits, for example a text column that caps at 720px.
- Use absolute positioning only when the element genuinely floats, such as a badge on an avatar.
- Nest layouts the way you would nest markup. If your layer tree resembles the DOM, translation is nearly mechanical.
5. Every component state, visible in the file
A button is not one design. Ship the full matrix, laid out on a states page so nobody has to hunt through variants.
| Component | States required |
|---|---|
| Button | Default, hover, active/pressed, focus ring, disabled, loading |
| Input | Empty, placeholder, focused, filled, error with message, success, disabled, read-only |
| Checkbox / radio | Unchecked, checked, indeterminate, focus, disabled variants of each |
| Card / list row | Default, hover, selected, dragging, skeleton |
| Nav item | Default, hover, current page, expanded, collapsed |
| Modal | Open, scrolled content, mobile full screen variant |
Focus states are the most frequently forgotten and the most frequently flagged in accessibility audits. Design them once as a token and reuse everywhere.
6. Breakpoints, not just a desktop and a phone
Delivering one 1440px frame and one 390px frame leaves everything between them to guesswork. Specify the behaviour, not only two snapshots.
- Declare your breakpoints explicitly, for example 640, 768, 1024, 1280, 1536.
- Show the layout at the breakpoint where it changes structure, for instance when a 3-column grid becomes 1 column.
- Note reflow rules in plain language: “sidebar collapses to a bottom sheet below 768”, “table becomes stacked cards below 640”.
- State the max content width and the outer page gutters per breakpoint.
7. Edge cases documented next to the happy path
The happy path is the easy part. Everything that breaks a build lives in the extremes, so document them right beside the main frame.
- Long content: a 60-character product name, a user with three surnames, a 12-word button label in German. Show whether it wraps, truncates with an ellipsis or shrinks.
- Zero content: no avatar uploaded, no description entered, no results found.
- Too much content: 200 rows in the table, 15 tags in a chip list, a comment thread 40 deep.
- Numeric extremes: negative values, prices over 1,000,000, percentages above 100, counters that must show 99+.
- Permission variants: what the same screen looks like for an admin, a member and a logged out visitor.
- Slow or failed network: partial data, timeout, retry.
A short annotation frame with these six scenarios per complex screen removes more developer questions than any other item on this list.
8. Empty, loading and error states as first class screens
Every screen that fetches data needs four versions, and they should be delivered together, not requested later:
- Loading: skeleton shapes or a spinner, with a note about which one and after how many milliseconds it appears.
- Empty: the illustration, the headline, the explanatory line and the primary action.
- Error: the message wording, whether it is inline or a toast, and the retry mechanism.
- Populated: the normal state, with realistic data rather than “Lorem ipsum”.
Write the actual error copy. “Something went wrong” written by a developer at 6pm is how brand voice dies. Design Handoff Best Practices: Beyond Static Mockups tackles the same question from another angle.
9. Assets exported and export settings preconfigured
Do not make developers slice your artwork. Set export settings on the layers themselves so they can grab everything in one action.
| Asset type | Format | Notes |
|---|---|---|
| Icons | SVG | Outlined strokes, uniform 24px canvas, no clipping masks, fill set to currentColor where possible |
| Logos | SVG | Full, compact and monochrome versions, plus clear space rules |
| Photography | WebP or AVIF | Provide 1x and 2x, note the crop focal point and the aspect ratio |
| Illustrations | SVG or PNG | Flatten complex gradients that bloat the SVG file size |
| Favicon / app icons | SVG + PNG set | 16, 32, 180, 192, 512 as a minimum |
| Fonts | WOFF2 | Include the licence and the exact weights actually used |
Name exports in kebab case, matching what will exist in the repo: icon-arrow-right.svg, not Arrow Right Copy 3.svg.
10. Motion specified in numbers
“Make it smooth” is not a spec. Give values a developer can type:
- Duration in milliseconds, for example 150ms for hover, 250ms for a drawer, 400ms for a page transition.
- Easing curve by name or cubic-bezier value.
- The property that animates: opacity, transform, height.
- Stagger delays for lists, if any.
- A note on
prefers-reduced-motionbehaviour.
A short prototype or a screen recording alongside the numbers removes any remaining ambiguity.
11. Accessibility annotations
Accessibility is far cheaper to design than to retrofit. Annotate directly on the frames:
- Heading hierarchy: which text is H1, H2, H3 semantically, not just visually.
- Tab order for forms and modals, plus where focus goes when a modal opens and closes.
- Alt text intent for meaningful images, and which images are decorative.
- Labels for icon-only buttons.
- Contrast ratios checked, with the failing pairs already fixed rather than flagged.
- Minimum touch target of 44 by 44 px on mobile, shown as a bounding box where the visual icon is smaller.
12. Real copy, from a single source of truth
Placeholder text creates two problems: layouts that only work with fake content, and developers inventing wording. Before handoff:
- Replace all dummy text with the approved copy.
- Keep the master copy in a shared doc or CMS and link it from the cover frame, so a wording change does not require a design update.
- Document pluralisation, date and currency formats, and truncation rules.
- If the product is localised, show the longest supported language in at least one frame per template.
Before, during and after: who does what
| Phase | Designer | Developer |
|---|---|---|
| Before handoff | Run the 12 points above, clean the file, mark frames ready for dev | Share technical constraints and existing component inventory early |
| Handoff session (30 to 45 min) | Walk the flow, explain intent, point to the edge case frames | Flag anything expensive to build while it is still cheap to change |
| During build | Answer in the file comments, keep decisions in one thread | Ask in the file, not in DMs, so answers stay searchable |
| Design QA | Review the staging build against the file, log issues with screenshots | Fix and confirm token usage rather than hard-coded values |
| After ship | Update the design system with any new pattern | Update the component library so it stays the source of truth |
The five mistakes we see most often
- Handing off the whole file. If everything is shared, nothing is final. Curate a dev-ready page.
- Designing screens instead of components. Developers build components. If your file is 40 unique screens with no shared parts, you have created 40 bespoke builds.
- Changing the file silently after handoff. Version the file, and post a comment describing what changed and why. A silent 4px change costs a rebuild and trust.
- Skipping the walkthrough. Fifteen minutes of context prevents a week of assumptions. Async video works fine if calendars do not align.
- Treating the dev tooling as documentation. Inspect mode tells a developer what a layer is, never why it is that way. Intent has to be written down.
Copy and paste: the pre-handoff final pass
Run this list the day before you hand anything over. If you cannot tick a line, the file is not ready.
- Dev-ready page contains only approved frames, everything else archived
- All frames named to match the tickets
- Zero detached components, zero local style overrides
- All spacing values come from the spacing scale
- All colours and type applied through variables and styles
- Auto layout applied, with fill/hug set intentionally
- Full state matrix present for every interactive component, focus included
- Breakpoints defined and structural changes shown
- Edge case frame per complex screen: long, empty, overflow, permissions
- Loading, empty and error states delivered with final copy
- Assets exportable in one click with correct formats and names
- Motion values written as duration, easing and property
- Accessibility notes on heading order, focus order, labels and contrast
- Real copy in place, linked to its source document
- Cover frame with owner, date, ticket links and open questions
Why this matters commercially
On the projects we run at Zach’s Web Designs, a structured handoff typically removes a large share of build-phase clarification requests and cuts design QA rounds roughly in half. The work does not disappear, it simply moves to a cheaper place: a designer spending two hours tidying variables is far less expensive than two developers stalled for two days, plus a QA cycle, plus a client review that surfaces problems everyone can see but nobody specified.
The goal of a design handoff checklist is not bureaucracy. It is making your intent so unambiguous that the build matches the design on the first attempt.
FAQ
What should be included in a design handoff?
Final screens marked ready for development, design tokens for spacing, colour, type and radius, every component state, responsive behaviour per breakpoint, edge case documentation, empty, loading and error states, export-ready assets, motion specifications, accessibility annotations and final copy with its source link.
How long should preparing a handoff take?
For a medium feature of 8 to 15 screens, budget half a day if you have been designing with components and variables from the start. If the file was built with detached layers and manual spacing, allow one to two full days for cleanup. That gap is the strongest argument for working with tokens from day one.
Do I still need documentation if developers can inspect the file?
Yes. Inspect tools report measurements and code snippets, they do not explain behaviour, priority, conditional logic or intent. Inspect answers “what is this”, your notes answer “what should happen when”.
Should designers deliver a prototype as well as static screens?
For anything with multi-step flows, conditional logic or noticeable motion, a clickable prototype is worth the effort. For simple content pages, annotated static frames plus written interaction notes are enough. The topic gets a thorough treatment elsewhere.
What happens when designs change after handoff?
Never edit the shipped frames silently. Duplicate them into a versioned section, mark clearly what changed, comment in the file and notify the developer with the ticket reference. Treat design changes with the same discipline as code changes.
Is there a free design handoff checklist template?
You can turn the copy and paste section above into a Figma cover frame, a Notion database or a pull request template. The format matters far less than the habit of running it every single time before the file leaves your hands.
Need a team that builds exactly what was designed? Get in touch with Zach’s Web Designs and we will review your current file structure and show you where the handoff is leaking hours.