Most design-to-code handoffs die the same death: a Figma link, a Slack message that says "let me know if you have questions," and a generated code preview that everyone assumes is correct because it compiled. The engineer opens it, finds three places where the AI conversion drifted from the design, files no ticket because there is no place to put the finding, and quietly rebuilds the component their own way. The design intent is lost not because anyone was careless but because nobody wrote down what mattered, what the AI got wrong, and what the engineer was actually being asked to trust. This lesson teaches you to write the handoff doc that survives a code review - a single page that pairs a Figma frame, an Anima or Locofy code preview, and an explicit list of the edge cases the AI got wrong, structured so an engineer reads it, signs it, and builds from it without redrawing your work. The artifact is a handoff doc, an engineer sign-off, and - when teardown is part of the job - a one-page appendix that uses html.to.design to reverse-engineer a competitor's site ethically, as a teardown artifact and never a copy artifact.

Why Most Handoffs Fail at the Code Review

The handoff is the seam where design-to-code tools have made things worse before they made them better. In 2025 and 2026, a designer can run a Figma frame through Anima - the most-installed Figma design-to-code plugin at over 1.5 million installs - or Locofy, and get a code preview in under a minute. The preview looks like the design. It compiles. And that is exactly the trap, because "looks like the design and compiles" is not the same as "behaves like the design intended," and the gap between those two is precisely the set of things an engineer will discover during review and silently fix with their own judgment instead of yours.

Here is what actually happens without a handoff doc. The engineer opens the generated code, tabs through the component, and finds the focus ring missing because the conversion stripped the outline. They notice the primary button's hover state has no keyboard equivalent. They see the empty state is a placeholder string the AI invented. None of these are written down anywhere, so the engineer makes a decision: either they raise each one as a separate question (slow, and it makes you look like you handed off broken work) or they fix each one the way they think is right (fast, and now the shipped component drifts from your intent in ways you will not discover until QA). Both outcomes are failures, and both are caused by the same absence: there is no document that says "here is the design, here is the generated code, here is exactly where the generated code is wrong, and here is what I am asking you to trust."

The senior move is to write that document. Not a longer Figma file, not more redlines - a handoff doc whose entire job is to make the design intent legible and the AI's failures explicit, so the code review is a conversation about the three things that matter instead of a scavenger hunt through everything that might be wrong.

What Engineers Actually Read, and What They Skip

Before you can write a doc engineers read, you have to be honest about what they skip. Engineers skip prose. They skip the paragraph explaining your design rationale, they skip the moodboard, they skip the eleven-bullet list of "design principles," and they very reliably skip anything that reads like it was written for a design review rather than a build. What they read is anything that tells them what to do, what to watch for, and what they are accountable for. An engineer reads a numbered list of edge cases. An engineer reads a token mapping table. An engineer reads "the AI got this wrong, do not trust it." An engineer reads a sign-off line with their name on it.

So the handoff doc is built entirely from the things engineers read and contains almost nothing of the things they skip. It is not a design artifact dressed up for engineering; it is an engineering artifact that happens to encode design intent. The difference is structural. A design artifact leads with the vision and buries the constraints; an engineering handoff leads with the contract and the known failures and trusts the engineer to infer the vision from a correct, complete spec. If your handoff doc would be at home in a design crit, you wrote the wrong document.

The Anatomy of the Handoff Doc

The handoff doc has five parts, and it fits on one page because the discipline of one page forces you to cut everything that is not load-bearing. Each part exists because its absence causes a specific, predictable failure in review.

Part One: The Frame and the Preview, Paired

At the top, side by side, the Figma frame and the generated code preview from Anima or Locofy. Not the frame alone, and not the preview alone - both, paired, because the whole point of the doc is to make the difference between them visible. The frame is the intent. The preview is what the AI produced from that intent. Pairing them turns the rest of the doc into an annotated diff: every edge case you list below is a statement about where the preview departs from the frame. A handoff that ships only the Figma link asks the engineer to imagine the code; a handoff that ships only the generated code asks them to trust it; pairing them asks them to compare, which is the only honest request.

Part Two: The Token Mapping

A short table mapping the visual properties in the frame to the design-system tokens they should resolve to: this surface is color.surface.raised, this text is color.text.primary, this gap is space.4, this radius is radius.md. This table exists because design-to-code tools are where token fidelity goes to die. The AI sees a color and emits a hex value; it sees a gap and emits 16px; it has no idea your system calls that gap space.4 unless you tell it, and the generated code will hardcode raw values that look identical and are systemically wrong, because the moment your space.4 changes from 16 to 14 pixels, every hardcoded 16 stays 16 and the component silently drifts off-system. The token mapping is how the engineer knows to replace the AI's hardcoded values with token references, and it is the single highest-leverage table in the doc.

Part Three: The Edge Cases the AI Got Wrong

This is the heart of the doc and the part that earns the engineer's trust. A numbered list of every place the generated code departs from the design intent, stated plainly, with the correct behavior named. Not "check the focus states" - that is a chore you are delegating. Instead: "The generated code has no focus ring on the primary button; the design uses focus.ring at 3:1 minimum contrast per WCAG 2.4.11 - add it." Each entry names the defect, names the criterion or token it violates, and names the fix. You are not asking the engineer to find the problems; you found them, and you are handing over a remediation list. This inverts the usual dynamic where the engineer discovers your AI handoff is broken. Instead, you arrive having already audited the AI's output, which is exactly the senior-IC posture: you do not hand someone an AI artifact and hope; you hand them the artifact and the list of everywhere it lies.

Part Four: What Is Explicitly Out of Scope

One short section stating what this handoff does not cover, because an unbounded handoff invites the engineer to assume you forgot something. "This component covers the default, hover, focus, disabled, and loading states. It does not cover the error state, which is tracked separately in ticket X." Naming the boundary is what separates a complete handoff with a known edge from an incomplete handoff with a hidden gap. The first is trustworthy; the second gets you a Slack message at 5pm asking where the error state is.

Part Five: The Sign-Off

A single line at the bottom: the engineer's name, the date, and "Reviewed and accepted for build." The sign-off is not bureaucracy - it is the mechanism that converts the doc from a suggestion into a contract. When an engineer signs, they are stating that they read the edge cases, understood the token mapping, and accept the scope. It changes the conversation from "the designer threw something over the wall" to "we reviewed this together and agreed what gets built." The sign-off is also your protection: if the error state ships broken three weeks later, the doc says in writing that the error state was out of scope and tracked separately, and the conversation is about the ticket, not about whether you handed off bad work.

A handoff that ships only the Figma link asks the engineer to imagine the code. A handoff that ships only the generated code asks them to trust it. The handoff doc asks them to compare - and hands them the list of everywhere the two differ, already found.

A Worked Handoff: The Settings Card

Make it concrete. You have designed a settings card - a raised surface with a title, two toggle rows, a primary "Save" button, and a secondary "Cancel" link. You run the frame through Anima and get a React component preview in forty seconds. It looks right. Now you write the handoff.

The pairing. Top of the doc: the Figma frame on the left, the Anima preview embedded on the right. At a glance they match. The doc exists to surface the places they do not.

The token mapping. A five-row table: card surface is color.surface.raised (Anima emitted #FFFFFF - replace), card padding is space.6 (Anima emitted 24px - replace with token), toggle gap is space.4, Save button uses color.action.primary (Anima emitted a hex that is a shade off because it sampled the rendered pixel, not the token - replace), radius is radius.lg. Five replacements, each named, each a hardcoded value the engineer would otherwise ship.

The edge cases the AI got wrong. Numbered: (1) No focus ring on the Save button; add focus.ring, 3:1 minimum, WCAG 2.4.11. (2) The Cancel link is rendered as a second filled button at primary weight - it should be a text link; the AI saw two actions and made them both prominent, which is a competing-primary error. (3) The toggle's accessible label is missing; Anima emitted the visual label text but no programmatic association - the toggle announces nothing to a screen reader. (4) The loading state on Save is absent; the design specifies a spinner and disabled state during the save request, and the generated code has neither. (5) Target size on the toggle hitbox is 20 pixels; WCAG 2.5.8 requires 24 by 24 minimum - expand the hitbox. Five defects, each with the criterion and the fix, every one of them something the engineer would have either missed or fixed their own way.

Out of scope. "Covers default, hover, focus, disabled, loading. Does not cover the destructive 'Delete settings' action, which is a separate confirmation flow in ticket DES-412."

Sign-off. Empty line for the engineer's name and date.

That doc is one page. It took you fifteen minutes to write because the audit was the work and the writing was just transcription. And it changes the review completely: the engineer reads five concrete defects with five concrete fixes, signs, and builds a component that matches your intent - instead of discovering the focus ring is missing during QA two weeks later and wondering whether the designer knew.

Why the Doc Survives the Code Review

A handoff doc "survives a code review" when the engineer reviewing the implementation can hold the built component against the doc and confirm every edge case was handled, every token was mapped, and nothing in scope was missed. This is a higher bar than "the engineer accepted the handoff." It means the doc is precise enough to function as the acceptance criteria for the code review that comes after the build. The reviewer should be able to read entry three - "the toggle's accessible label is missing, add it" - and check whether the shipped code added it. If the doc is vague ("improve accessibility"), it cannot be checked, and a doc that cannot be checked does not survive review; it gets ignored.

This is why every edge case names a specific, verifiable fix. "Add focus.ring at 3:1 per 2.4.11" is checkable: tab to the button, inspect the ring, measure the contrast. "Make it accessible" is not. The discipline of writing only checkable edge cases is what makes the doc load-bearing in the review that decides whether the code ships. You are not writing a wish list; you are writing the test the implementation has to pass, and the engineer who signs it is agreeing to that test.

The Teardown Appendix: html.to.design, Done Ethically

Sometimes a handoff includes a teardown - a structured analysis of how a competitor or a reference product solves a problem you are now solving. The tool that makes this fast is html.to.design, a Figma plugin that imports a live website into Figma as editable layers, so you can inspect a real, shipped interface at the structural level: its spacing, its component composition, its interaction affordances, its responsive behavior. Used well, this is one of the most honest research tools available, because it lets you study how something actually works rather than how its marketing screenshots suggest it works. Used badly, it is a copy machine. The appendix exists to keep the line between those two uses explicit and on the record.

A Teardown Artifact, Not a Copy Artifact

The distinction is the entire ethics of the practice, and it is not subtle. A teardown artifact answers "how does this interface solve this problem, and what can we learn about the problem from how they solved it?" You import the competitor's checkout flow, you study how they sequence the steps, how they handle the address-validation edge case, how they treat the destructive "remove item" action, and you write down the principles you extracted. Then you design your own solution, informed by what you learned, expressed in your own system, your own tokens, your own brand. The imported layers are a research input you analyze and discard; what you ship is yours.

A copy artifact answers "how do I make mine look like theirs?" You import the competitor's screen, you re-skin it with your logo, and you ship a derivative of their work. This is what html.to.design makes technically trivial and what the appendix exists to forbid. The plugin will import pixel-faithful layers either way; the ethics live entirely in what you do next, which is why the appendix has to state the intent in writing rather than trusting that everyone understood the line.

The Ethical Guardrails, Written Down

The teardown appendix carries four explicit guardrails so the artifact's intent is unambiguous to anyone who finds it later, including legal. First, a stated purpose: "This is a teardown for competitive analysis and pattern learning, not a source for direct reuse." Second, a scope limit: you analyze structure, flow, and interaction principles, not visual assets - you do not lift their illustrations, their copy, their icons, or their exact color values, all of which may be protected. Third, a derivation statement: the design you ship is expressed entirely in your own design system and brand, and the appendix says so. Fourth, a retention note: the imported file is a research artifact, not a production asset, and it is stored as a teardown, labeled as such, and never promoted into your component library. These four lines are cheap to write and they are the difference between a defensible research practice and a document that, surfaced in a dispute, reads like a confession.

The reason this lives in the handoff context at all is that teardowns most often happen exactly when you are about to hand off a build - you are studying how the reference product solved the problem in order to inform the thing your engineer is about to construct. Attaching the teardown as a labeled, guardrailed appendix keeps the research transparent: the engineer, the design lead, and legal can all see what was studied, what was learned, and the explicit statement that what gets built is original. A teardown done in the open with its ethics stated is a professional research practice. A teardown done quietly with no statement of intent is the thing that, when discovered, looks like it was hidden because it should have been.

Putting It to Work on Your Next Handoff

The next time you hand off a generated component, do three things. First, run the AI audit before you write a word of the doc: open the generated preview, tab through it, resize it, check the tokens against the values the AI hardcoded, and write down every departure from intent. The audit is the work; the doc is transcription. Second, write the five parts - frame and preview paired, token mapping, edge cases with named fixes, out-of-scope boundary, sign-off line - on one page, cutting anything that would not survive an engineer's "what do I do with this?" Third, walk the doc through with the engineer and get the sign-off in the same session, so the handoff is a conversation that ends in agreement rather than a link that starts a scavenger hunt.

You will know it is working when the code review after the build is short, because there is nothing to discover - every defect was named, every fix was checkable, and the shipped component matches the doc. And if a teardown informed the work, attach the appendix with its four guardrails stated plainly, so the research that made the design better is visible and defensible rather than quiet and risky. The handoff doc is how a senior IC ships design-to-code work that an engineer trusts, a reviewer can check, and a legal team would not flinch at - which is the whole job at this level.

Key Takeaways

• Design-to-code tools like Anima (1.5M+ installs) and Locofy produce previews that look right and compile, which is the trap: "looks like the design and compiles" is not "behaves like the design intended," and the gap is what an engineer silently fixes their own way without a handoff doc.
• Engineers read what tells them what to do and what they are accountable for - numbered edge cases, token tables, "the AI got this wrong," a sign-off line - and skip prose, rationale, and anything that reads like a design crit. Build the doc entirely from the first set.
• The handoff doc has five parts on one page: the Figma frame and code preview paired (so the rest is an annotated diff), a token mapping (where AI fidelity dies), the edge cases the AI got wrong with named criteria and fixes, an explicit out-of-scope boundary, and an engineer sign-off that converts the doc into a contract.
• The doc survives a code review only if every edge case names a checkable fix ("add focus.ring at 3:1 per 2.4.11," not "improve accessibility"). A doc that cannot be checked gets ignored; one that can functions as the acceptance criteria for the build.
• You arrive having already audited the AI's output - the audit is the work, the doc is transcription. This is the senior-IC posture: never hand someone an AI artifact and hope; hand them the artifact and the list of everywhere it lies.
• When teardown is part of the job, html.to.design imports a live site into Figma for structural learning. The appendix keeps it a teardown artifact (study the problem, ship your own solution in your own system) and never a copy artifact, with four explicit guardrails - stated purpose, scope limit, derivation statement, retention note - so the research is transparent and defensible.