Design to Development Handoff Checklist
Every handoff checklist asks four state questions per screen. Your API contract and role model say the real number is far higher.
Free download · No account needed
Every design handoff checklist asks the same four state questions per screen. Empty, loading, error, disabled. The trouble is that error is a category rather than a state, and how many members it has is decided by your API contract. At the fictional Warminster, thirty-four screens produced 278 required states against a checklist's 136 questions. One screen could fail eleven distinct ways on its own, and a single tick cannot carry eleven different sentences.
So this pack generates the register instead of handing you one to fill in. The screen inventory is multiplied against the failures each endpoint contract already lists, the collections the data model lets a screen show empty, whether those can also be filtered to nothing, and the roles the permission model can refuse. Warminster's file covered 73 of the resulting 278 cells. Read by class that is loading 24 of 32, empty 38 of 40, error 9 of 128, and permission denied 2 of 78.
The design team had covered everything visible from inside the design and none of what the contracts enumerate, because nobody had ever shown them either. A cell counts as resolved when it is drawn, written, or deferred to a named default, and the pack ships that rule alongside the register. Deferring is a real answer rather than an escape hatch: it names the fallback the build will use, so an engineer knows the omission was a decision. It sits beside the design system's own documentation and the acceptance criteria these screens are answering to.
What is in the pack
Screen and State Register
One row per state the system permits, generated rather than listed. Screen, class, the specific cause or condition, which contract enumerated it, whether a frame exists, and how it resolved. The rows for states nobody drew are the point: they exist in the sheet before anybody notices them missing from the file.
Open Question Log
Every unresolved cell grouped into a question somebody can answer, with the register rows it closes, an owner who is a person, and a date. Sorted by what blocks the build rather than by screen order, because a question that changes the data model outranks one that changes a sentence.
Asset Checklist
Built from the register rather than from the file, so an asset attached to an undrawn state still gets a row. Partial exports are flagged separately from missing ones, since six of eight card marks looks finished and ships broken to whichever region uses one of the other two.
How Required States Are Derived
The Setup document every prompt reads first. Why a checklist cannot know how many states a screen has, and the four sources the taxonomy comes from instead. Also why the first-run empty state and the filtered-to-nothing state are different screens, and why coverage read in aggregate hides the whole finding.
Handoff Note and State Specification
The short document engineering opens first, carrying scope, the one thing that must work, coverage stated as a number, and who decides when reality disagrees with the design. Then the long one: six fields per state, including the actual words rather than a note to write some later.
Interaction Guidance, plus a weekly sweep
Behaviour no static frame carries. Where focus lands after every transition class, what gets announced and how politely, motion with its reduced-motion answer in the same line, and the reversal when an optimistic update turns out wrong. The automation re-derives the register weekly, because the denominator moves.
How it works
- 1
Send the file and the contracts
The design file or a description of the screens, the API specification or error catalogue behind them, the permission model, and the requirement set they answer to. Partial is fine, and a missing error catalogue is itself a finding.
- 2
The register generates itself
River builds the screen inventory, then multiplies it against the failures each endpoint can return, the collections that can be empty or filtered to nothing, and the roles that can be refused at screen, field or action level.
- 3
Frames get matched to cells
Coverage is computed from the register outward rather than from the file inward, which finds holes instead of frames, and it is reported per class because the aggregate hides where the gap actually is.
- 4
Open cells become questions
Every unresolved cell is grouped into a numbered question heading for one of three resolutions. The catch-all about what the build does with an unspecified state gets answered first, which is what makes deferral safe.
Frequently asked questions
Is this not just a longer version of the checklist everybody uses?
The opposite. A checklist has a fixed number of questions and your system has a variable number of states, which is the entire problem. Warminster's checklist asked 136 questions about a surface with 278 states, so 142 of them were never asked about at all.
Do we really have to draw a hundred error states?
No, and a team that tries stops by the second release. Most error cells should be written rather than drawn, because the layout does not change and a sentence carries everything a frame would. Warminster resolved 205 open cells as 47 to draw, 112 to write and 46 deferred. Those 112 sentences are copy, held to an error message standard rather than improvised.
What makes a deferral different from ignoring it?
A named default, written down. Warminster's was a generic error region taking its text from the problem detail the API already returns, with a retry where the request is idempotent. One sentence turned 46 deferrals from risk into policy.
Why split empty into two states?
Because they say opposite things. First-run means nothing exists yet and offers the action that starts it. Filtered means nothing matched and offers a way back. Show the first-run version to somebody with two hundred records and a narrow filter and you have told them their data is gone. That decision belongs in a review record, which is what the design critique framework keeps.
Our designers do not have the API contract. Is that normal?
It is the single most common cause of the gap. Warminster's team drew 38 of 40 empty states and 9 of 128 error states, which is not a skill difference. Error and denial cells are enumerated by documents designers are rarely shown, so the fix starts with sharing them.
Does this overlap with an accessibility audit?
They meet at the words. An input error has to be identified and described in text, and anything updating in place has to be programmatically determinable. Fixing findings after the fact is a different job.
What happens to the register after the handoff meeting?
It keeps a denominator that moves. A new endpoint, failure type, role or filterable collection adds cells after the fact, and none announces itself as a design question. The weekly sweep re-derives the register and separates coverage that moved from a denominator that grew. The screen list moves too, and path data is what shows a new step arriving.
Find out how many states you actually owe
Send the file, the endpoint contracts and the permission model. The first thing back is the denominator, and it is usually about double what the checklist implied.
Count the states you owe