Design handoff: from the layout to code without losses
The path of a decision from the layout to the page, what a complete handoff contains, a card the way a developer sees it, tools, files and a checklist — with live examples.
In short
Handoff is the moment a layout becomes code, and most of the losses between design and development happen here. A good handoff is not a link to a file with the words “everything is in there”: it is tokens in the repository with the same names as in the layout, components with all their states, layouts for three widths, edge cases — long titles, empty lists, errors — and a short specification for each component. Then the developer does not guess, the designer does not find “almost the same” on the site, and new pages are assembled from parts that already exist on both sides.
The path of one decision: from the layout to the page
When this chain works, a colour changed in the layout reaches the site through a build, not through a letter.
- 01LayoutFigma variables
- 02Tokenstokens.json in the repository
- 03BuildStyle Dictionary
- 04CSSvariables and themes
- 05Componentscode with all states
- 06Pageassembled from components
What a complete handoff contains
Ten things a developer needs besides the picture of the main screen.
| What | In which form | Without it |
|---|---|---|
| Tokens | a JSON file with the same names as in the layout | colours are copied by eye |
| Components | a library with variants and all states | hover and focus are invented |
| Three widths | phone, tablet, desktop | the phone is assembled by guesswork |
| Edge cases | long texts, empty lists, errors | the layout breaks on real data |
| Real texts | not “Lorem ipsum” | headings do not fit |
| Motion | durations and curves from tokens, a short video | animation is done by feel |
| Images | proportions, crops, formats | photos are stretched and heavy |
| Icons | SVG on one grid and line width | icons of different sizes and styles |
| Accessibility | contrast checked, focus order, alt texts | problems surface after launch |
| A spec per component | a few lines: tokens, states, widths | questions in chats for weeks |
A card the way a developer sees it
Not pixels but names: every distance and colour is a token, every element is a known component.
Oak table
Solid oak, 160 × 90 cm
Add to cart- card.bg → color.surface
- card.radius → radius.lg · 16
- title → font.step-2 · 600
- text → font.step-0 · color.text-muted
- button → Button / primary / md
- image → 4 : 3 · object-fit: cover
Tools that connect the layout and the code
-
Figma variables
Tokens inside the layout, with modes for themes.
-
Dev Mode
The developer sees variable names, not raw numbers.
-
Tokens Studio
Synchronises tokens between the layout and a repository.
-
Style Dictionary
Builds CSS, iOS and Android files from one set of tokens.
-
Storybook
A catalogue of coded components with all their states.
-
Visual tests
Screenshots of components compared after every change.
Handoff in files: 2 examples
A build of tokens for the site and the iOS app, and a short specification of one component.
One source, two platforms
Style Dictionary takes the tokens and writes CSS variables and a Swift file.
{
"source": ["tokens/**/*.json"],
"platforms": {
"css": {
"transformGroup": "css",
"buildPath": "build/css/",
"files": [{ "destination": "tokens.css", "format": "css/variables" }]
},
"ios": {
"transformGroup": "ios-swift",
"buildPath": "build/ios/",
"files": [{ "destination": "Tokens.swift", "format": "ios-swift/class.swift" }]
}
}
}A component specification
Eight lines that answer the questions a developer would otherwise ask in a chat.
# Card / product — what the developer gets together with the layout
Tokens bg color.surface · radius radius.lg · padding space.5
Image 4:3, object-fit: cover, lazy loading below the first screen
Title font.step-2, 600, at most 2 lines, then an ellipsis
Text font.step-0, color.text-muted
Button Button / primary / md — states from the library
States hover: shadow.md · focus: a ring around the whole card
Widths 1 column up to 600 px · 2 up to 1024 px · 4 from 1024 px
Edge cases no photo: placeholder · price on request: text instead of a numberA checklist before handing over a layout
-
01
Names match
Variables in the layout and in the code are called the same.
-
02
No raw values
Every colour and distance in the layout is linked to a token.
-
03
All states are drawn
Hover, focus, pressed, disabled, loading, errors.
-
04
Three widths
375, 768 and 1440 px — and what happens between them.
-
05
Real content
The longest title, the empty list, the missing photo.
-
06
Contrast is checked
Every pair of text and background is readable.
-
07
Motion is described
Durations and curves from tokens, plus a version without motion.
-
08
A review after the build
The designer checks the coded page before release, not after.
Where design gets lost on the way to code
-
Only the desktop
Most visitors come from phones, and their version is assembled by guesswork.
-
Perfect content in the layout
Real titles are longer, and photos are of another proportion.
-
A link instead of a handoff
“Everything is in the file” — and fifty questions in a chat.
-
Different names
In the layout “Primary/500”, in the code “--blue-main” — nobody knows they are the same.
-
Design ends at the handoff
Without a review of the built page, small differences pile up.
-
Edits only in the layout
The site lives on, the layout falls behind, and the next handoff starts from a lie.
Questions about design handoff
What does a developer need from a designer?
Tokens, components with states, three widths, edge cases, real texts and a short spec per component.
Is Figma Dev Mode enough?
It shows values and names, but states, edge cases and behaviour still have to be designed and described.
How to keep the layout and the code in sync?
Tokens in one repository, the same names on both sides and a build that generates the code.
Who checks the result?
The designer reviews the built page before release; visual tests catch regressions after.
How many widths should a layout have?
Three: phone, tablet and desktop — plus a note on how the layout behaves between them.
What if design and code are done by one person?
Fewer losses, but the same rules still help: tokens and states keep order as the project grows.
Online form
Design and code
in one hands
I design and build myself, so nothing is lost on the way from the layout to the site — and I prepare handoffs for your team by the same rules. Tell me about the project — I answer within one working day.