Design Handoff to Developers for Mobile Apps

Design handoff to developers starts with a versioned screen package: name every colour, spacing, and type role; provide default, pressed, disabled, loading, error, and empty states; export assets at the exact iOS and Android scale required; and annotate navigation, validation, keyboard, and network behaviour. Add edge-case frames for the longest approved string, no data, offline use, and a slow response. An engineer should be able to trace every visible element and transition to a named token, asset, state, or rule.

Key takeaways

•Android raster assets use mdpi, hdpi, xhdpi, xxhdpi, and xxxhdpi density buckets.
•iOS image asset variants use @1x, @2x, and @3x scale slots when raster variants are required.
•Material Design 3 defines interaction states including enabled, hovered, focused, pressed, and disabled.
•A handoff must show default, pressed, disabled, loading, error, and empty states for each interactive screen region.
•WCAG 2.2 AA requires a 4.5:1 contrast ratio for normal-size text.

This guide is for mobile UI/UX designers, founders, and engineers who already work with iOS and Android screen flows.

Time: 45 minutes per complete screen flow · You'll need: floow.design project with the approved mobile screen set, Figma or an equivalent design-file inspector with token and asset export access, Xcode asset catalog or iOS asset manifest requirements from the engineering team, Android Studio resource folder conventions or Android asset requirements from the engineering team, A list of supported locales, authenticated states, and network assumptions

What's on this page

•Replace local values with named tokens
•Add states to the developer handoff mobile flow
•Export assets for the design spec handoff
•Annotate behaviour beyond the static frames
•Test edge cases in the design to development handoff
•Reference table

•Common mistakes
•FAQs

Preparing a design handoff to developers

1. Replace local values with named tokens

Create a token page before you annotate individual frames. Replace values such as #1769E0, 16 px, and 20 px with roles such as color.primary, color.onPrimary, space.16, and type.titleMedium. Keep the role name independent of one screen: color.error can serve an invalid field, an inline alert, and an error icon; checkout-red cannot. Include the resolved value and platform mapping beside every token. For example, map color.primary to an iOS named color in the asset catalog and an Android Material 3 color role.

Define type by role, not by a single font size. Record the font family, weight, line height, tracking, and role for type.body, type.label, and type.title. Check text colours against WCAG 2.2 AA: normal text needs 4.5:1 contrast. The delivered file should contain no unlabelled one-off spacing or colour values unless the team has explicitly approved a new token.

Tip: Do not force an iOS 16-point text role and an Android 16-sp role to share a token if their platform typography systems require different line metrics.

2. Add states to the developer handoff mobile flow

For every control and screen region that changes, create a state matrix with six required rows: default, pressed, disabled, loading, error, and empty. A primary button, for example, needs its normal label, its pressed treatment, its disabled rule and the condition that causes it, plus its loading rule. State whether loading replaces the label or appears alongside it; never leave both implementations plausible. Material Design 3 documents enabled, focused, hovered, pressed, and disabled interaction states, so map your visual choices to those named states rather than supplying one static button.

Show validation at the field level and at the submit action. Annotate the error trigger, error message position, focus destination after submit, and recovery action. For empty content, specify the title, supporting text, illustration asset if present, primary action, and whether pull-to-refresh remains available. Keep the state matrix next to the component and link each screen instance to that component.

Tip: A disabled submit button is not a substitute for validation guidance when users cannot discover which required field is incomplete.

3. Export assets for the design spec handoff

Give every exported file a stable, implementation-safe name such as ic_receipt_24, img_empty_orders, or logo_wordmark. State the file format, pixel dimensions for raster files, transparency requirement, and intended placement. Do not hand engineers a folder named final-icons or a file named Group 481.svg; those names cannot be safely referenced in source code or reviewed after an update.

For Android raster resources, export the same artwork to drawable-mdpi, drawable-hdpi, drawable-xhdpi, drawable-xxhdpi, and drawable-xxxhdpi. Those buckets correspond to 1x, 1.5x, 2x, 3x, and 4x baseline density. For iOS raster image sets, populate the @1x, @2x, and @3x slots when the asset requires raster variants. Prefer a single vector source where the platform and asset type support it, but test that its strokes remain clear at the smallest intended size. Name the asset in the screen annotation exactly as it appears in the exported package.

Tip: Export icons with their intended visual bounds, not only their vector path bounds; a 24-unit icon can still need internal padding to align with adjacent icons.

4. Annotate behaviour beyond the static frames

Place numbered callouts on the flow and write one implementation rule per callout. Name the trigger, result, destination, and reversal. For example: “Tap Save: validate all required fields; on success, dismiss the keyboard, return to Profile, and show a confirmation message.” Add the back behaviour, cancellation behaviour, retry behaviour, and what happens if a request finishes after the user leaves the screen.

Document platform-specific input behaviour. State the keyboard type for each field, whether the keyboard action advances focus or submits, and whether content scrolls to keep the focused field visible. Identify navigation as a push, modal presentation, bottom sheet, tab switch, or external system flow. For loading, specify whether the screen blocks interaction, whether existing content remains visible, and when a retry becomes available. Apple’s Human Interface Guidelines and Android’s platform patterns differ in navigation presentation, so give the intended iOS and Android behaviour where the designs intentionally diverge.

Tip: A prototype is evidence of motion, not a complete specification; its transitions still need written rules for interruption, failure, and cancellation.

5. Test edge cases in the design to development handoff

Add a final edge-case page containing real frames, not a note that says “handle errors.” Use the longest approved string from each supported locale for titles, buttons, tabs, validation messages, and account names. Show the chosen overflow rule for each: wrap, truncate, scale, or scroll. Do not assume English is the widest language, and do not approve a layout until the product’s actual localization set has been tested.

Include four network and data frames: no data for a new account, offline before a request starts, a slow request with loading visible, and a failed request with a retry action. For lists, show zero items separately from an unavailable response; an empty order history and a server error require different actions. Test accessibility text scaling using iOS Larger Text and Android font-size settings, then document whether a component grows vertically, reflows, or changes layout. Link every edge frame back to the same component and route as its standard counterpart.

Tip: Treat offline content as a product decision: label cached data with its freshness rule instead of presenting it as a current server response.

Reference table

Android raster asset density exports

Resource folder	Scale from mdpi	Example for a 24 px mdpi asset
drawable-mdpi	1x	24 × 24 px
drawable-hdpi	1.5x	36 × 36 px
drawable-xhdpi	2x	48 × 48 px
drawable-xxhdpi	3x	72 × 72 px
drawable-xxxhdpi	4x	96 × 96 px

Common mistakes

Handing over hex values and font sizes without semantic names.

Create named colour, spacing, and type roles first. A role such as color.error lets engineers update a theme without searching every screen.

Showing only a successful, populated screen.

Attach default, pressed, disabled, loading, error, and empty frames to each interactive component and data region.

Exporting Android artwork as one PNG file.

Provide the required density variants or a validated vector asset. Android resource qualifiers select assets for different device densities.

Using a clickable prototype as the only behaviour documentation.

Write trigger, destination, validation, cancellation, retry, and interruption rules next to the relevant transition.

Frequently asked questions

What should be included in a mobile design handoff to developers?

A mobile design handoff should include named tokens, screen states, export-ready assets, interaction rules, and edge-case frames. Give engineers a versioned screen list, component state matrix, asset manifest, and written rules for navigation, input, loading, validation, errors, and offline conditions. Include platform differences where iOS and Android intentionally behave differently.

How do I prepare assets for iOS and Android developer handoff?

Prepare iOS assets in named asset catalog entries and Android raster assets in the correct density buckets or as validated vectors. Android’s standard raster buckets are mdpi, hdpi, xhdpi, xxhdpi, and xxxhdpi; iOS raster image sets use @1x, @2x, and @3x slots. Record each exported filename in the screen specification.

Do developers need every button state in the design file?

Developers need a specified rule for every button state, including default, pressed, disabled, loading, and error outcomes. The visual state can live in a reusable component page rather than repeated on every frame, but each screen must identify the component variant and the condition that activates it. Also specify the empty state for the content the button controls.

How do I document a slow network state in a mobile app design?

Document a slow network state with a frame showing what remains interactive, what loading indicator appears, and when retry is offered. Distinguish a pending request from an offline request and from a failed response. If cached content remains visible, specify its freshness label and whether users can refresh it.

Where this leaves you

A useful handoff removes implementation choices that design has already made. Engineers should not need to infer whether a spacing value is reusable, whether an icon has a 3x variant, what a button does while saving, or how a screen behaves without data. The package can still leave technical architecture to engineering, but its visual and product rules must be testable from the file. Open your highest-risk mobile flow now and build one state matrix for it: default, pressed, disabled, loading, error, and empty. That single page usually exposes the unanswered questions before development does.

Design the screens first

Describe the screen you need in plain English and floow.design generates production-ready iOS and Android layouts you can iterate on by chat, then export to Figma or code. Design your mobile app screens in floow.design first, then build.

Start designing free →

•Color Picker from Image — Pull a palette out of any image, assign it to screen roles, and export it as tokens or native code.
•Aspect Ratio Calculator — Work out the missing width or height for any ratio, with the common phone and store ratios one click away.
•Accessible Color Generator: Mobile App Design Guide — Use an accessible color generator workflow to check contrast, targets, labels, text scalin
•Text to UI: Design App Screens From Prompts — Use text to UI prompts that produce usable iOS and Android first screens, with real copy,
•UI Design Prompts: 25 That Generate Usable Mobile Screens — Learn a practical formula plus 25 UI design prompts that create editable, usable mobile sc