A useful design handoff is more than a Figma link, a folder of exports, or a set of screenshots. Developers need to know what a person can do, how the interface responds to different content and screen sizes, and which existing code components the design represents.
This guide lays out a practical handoff workflow for a freelancer, a small product team, or a designer and developer working together. It focuses on details that can be recorded and reviewed in a design file, issue, or pull request. For broader team coordination, see our guide to how designers and developers can collaborate effectively.
Agree on the handoff before polishing screens
Start with a short shared brief. Record the feature or route, the person it is for, the states that are in scope, and any project constraints that affect implementation. Include a link to the ticket or project issue and identify which design file or version is the source of truth.
Agree on what “ready for development” means for your team. A practical definition might require the main flow, responsive behavior, key interaction states, asset links, and open questions to be recorded. Keep unfinished options visibly separate from the approved design so an implementation does not accidentally treat an exploration as a decision.
Design files can show presentation, but they do not always specify behavior. Discuss technical constraints early: an existing component library, supported browsers, content-management fields, form validation, or a deadline that rules out a complex animation. This avoids treating a design as a fixed picture when the implementation needs to work with real content and data.
Make the design inspectable
Use descriptive names for pages, frames, layers, components, and variables. Names such as Checkout / Payment error or Button / Primary / Disabled communicate more than Frame 47 or Blue rectangle. Group related screens in the order a user encounters them, and link the design to its issue or implementation notes.
Where the design tool supports it, use annotations or a handoff status to mark decisions and questions. For example, note whether a menu closes on Escape, whether a field error appears on blur or submit, and what should happen when a user has no saved items. Keep the note beside the relevant component or screen rather than in a chat message that will be hard to find later.
Figma’s Dev Mode guide documents inspection of properties, styles and variables, asset downloads, version comparisons, annotations, and handoff statuses. It also describes developer integrations. Check the current plan and seat requirements before making Dev Mode a required part of a client or team workflow.
Specify responsive behavior, not just screen sizes
A desktop mockup and a mobile mockup do not explain what happens between them. Record the layout rules that matter: when columns stack, whether navigation collapses, how long text wraps, which elements become full-width, and whether a control moves or disappears.
Use the project’s actual content and breakpoints when possible. A long product name, translated label, validation message, or empty state can change a layout more than a small viewport-width difference. If the precise breakpoint is not important, describe the behavior instead of inventing a number that the code must follow.
Our examples of responsive web design patterns can help when the handoff needs to explain how a layout adapts rather than provide another fixed-size screenshot.
Document states and accessibility expectations
For each interactive component, include the states a developer needs to implement and review. A form field might have default, focused, filled, invalid, disabled, and submitting states. A data view might include loading, empty, populated, and error states. Add a short behavior note for keyboard input, validation timing, dismissal, or confirmation where it is not obvious.
Specify intent as well as appearance. For example, say whether an element is a link or a button, whether an icon is decorative or meaningful, and what a screen reader should announce when an operation succeeds or fails. Include visible focus, sufficient text and control contrast, and a usable keyboard path in the acceptance criteria. The W3C WCAG overview explains the accessibility guidelines; a design file alone cannot confirm that the implemented page conforms.
For a broader implementation checklist, see our guide to testing website accessibility as a developer. Test the actual page with keyboard and assistive-technology checks appropriate to the feature, not only the design preview.
Treat assets and design tokens as implementation inputs
Provide the original asset or a clear source link, not an image copied out of a screenshot. Identify the intended format and any variants, such as an SVG icon, a responsive image, or a light and dark logo. Say whether an asset is decorative or conveys information; that distinction affects alternative text and how it should be included in the page.
Agree on names for shared values such as colors, spacing, typography, and border radius. Map those names to the project’s code tokens or CSS custom properties. For example, a design value named color-text-muted is easier to maintain when it maps to a similarly named code token than when every component receives an unrelated hex value.
Figma and Penpot both offer ways to inspect design values and assets. Penpot’s Dev tools documentation describes measuring designs, inspecting properties, copying CSS properties, and exporting assets. Generated snippets can help you understand a value, but they are not a substitute for using the project’s components, styles, and accessibility patterns.
If the team already has a component library, map designs to those components instead of rebuilding them from scratch. Figma’s Code Connect documentation describes connecting design components with components in a codebase; availability and setup depend on the team’s plan and workflow. For a smaller project, a short mapping in the issue or component documentation may be enough.
A simple handoff workflow
- Create one implementation task. Link the approved design and summarize the user outcome, routes, constraints, and owner. Keep drafts and approved designs distinct.
- Review the flow together. Walk through the happy path and the non-happy paths, including errors, loading, empty content, and keyboard interactions. Resolve high-impact questions before implementation.
- Annotate responsive rules. Describe layout changes and content behavior at the sizes that matter to the product. Include unusual long or translated content where it could affect the design.
- Map reusable parts. Identify the existing code components and tokens that correspond to the design. Record what is genuinely new rather than silently creating a second version of an existing button or field.
- Prepare assets and acceptance criteria. Link source assets, note their purpose, and write observable checks for the behavior, responsive layout, and accessibility requirements.
- Review the running implementation. Use a preview or local build to check real content, states, keyboard behavior, and responsive transitions. Capture unresolved differences as issue comments or design annotations, then update the approved source rather than letting two conflicting specifications persist.
For teams that already maintain a component catalog, Storybook can complement the design file. Its documentation describes rendering components in isolation and recording variations as stories, which makes it useful for reviewing coded states. Storybook also documents accessibility tests; these are automated checks, not proof that every interaction is accessible.
Choose tools based on the workflow you already have
| Workflow | Useful when | Keep in mind |
|---|---|---|
| Figma Dev Mode | The approved design already lives in Figma and developers need inspectable values, assets, annotations, or links to code and tickets | Check current plan and seat requirements. Treat generated snippets as references, then implement with the project’s real components and tokens. |
| Penpot Dev tools | Your team uses Penpot and wants measurements, property inspection, CSS references, and asset export in the same design workflow | Agree on the source of truth and token names with the codebase; an inspect panel does not define your application architecture. |
| Storybook beside either design tool | You need a code-side catalog for component states and a place to review implemented variants | It complements design handoff; it does not replace the approved design or a written interaction requirement. |
| An issue plus the existing design file | You are a solo developer or a small team without a dedicated handoff platform | A concise checklist and one canonical link are better than adopting another tool before the process needs it. |
The right setup is usually the one your designer and developer will keep current. A tool can expose measurements and connect files, but it cannot decide which version is approved, whether an element should be a button, or what should happen when a request fails.
A handoff note you can reuse
Add a compact note to the issue, project README, or design file:
- Outcome and scope: Which user flow or route is changing?
- Source of truth: Which design file and version are approved?
- Responsive rules: How should the layout adapt to real content and screen sizes?
- States and behavior: What happens on focus, submit, error, empty results, and dismissal?
- Components and tokens: Which existing code components and shared values should be used?
- Assets: Where are the source files, and what purpose does each asset serve?
- Acceptance checks: What must work with keyboard input, narrow screens, and assistive technology?
- Open questions: What still needs a decision, and who will make it?
This keeps implementation decisions close to the code review and makes a handoff useful even when one person fills both the design and development roles. Start with the details that affect behavior, reuse, and accessibility; add more annotation only when it prevents a real misunderstanding.
