Design handoff when AI writes the code: hand over rules, not pictures

When an AI coding agent builds the front end, the handoff that works is a set of rules, not a finished picture. In practice that means a design system that lives in code, with semantic tokens and component names that match your design file, plus a written spec for every state and breakpoint, and (if you can get repo access) a design branch that engineers review like any other pull request.

Below is how to get there from wherever your team is today, with a copy-paste checklist at the end.

What changed: agents fill gaps with guesses

The old handoff assumed a human developer on the other end. You shipped screens and redlines, and when something was missing (the empty state, the error message, what happens at 400px) the developer used judgement or walked over and asked. A coding agent does neither. It fills the gap with whatever is most common in its training data.

Figma says as much in its announcement of the Dev Mode MCP server: without design context, an LLM's output "likely won't match the patterns found in the rest of your codebase." Nielsen Norman Group's study of AI prototyping in real design contexts found the same weak spots from the design side: missing hierarchy and grouping, inconsistent spacing, a generic look, and patterns misapplied when the brief was vague. Their conclusion is that much of the design work "has already happened before AI enters the picture."

Designers on Reddit describe the squeeze from both ends. In an r/UXDesign thread titled Suddenly we became the bottleneck, people describe being seen as the slow step, while the AI-built screens that skip them come back with missing states and edge cases that have to be specified all over again. In an r/FigmaDesign discussion on how teams handle handoff now, one designer sums it up as the handoff doc changing from a picture of the screen to the rules for building it. That is the shift this whole article is about.

Pick one source of truth and stop mirroring both

The hardest decision comes first. In an r/UXDesign thread from designers whose design system lives in Figma but who don't touch code, the recurring experience is that code quietly becomes the source of truth, and keeping the Figma library in lockstep turns into a losing battle. People still want Figma for exploration. They just stop pretending it is the spec.

My view: once agents write most of the UI, code should be the source of truth for anything that already exists (tokens, components, layout primitives), and the design tool is where you explore what doesn't exist yet. Figma can remain the source of truth, but only if you pay for the plumbing: Code Connect, a token export pipeline, and someone who owns the sync. The option that fails is the unspoken one, where both drift and the agent picks whichever it sees first.

Make the design system readable by a machine

Semantic tokens, in a standard format

Name tokens by purpose, not value. color.text.danger tells an agent when to use it; red-600 only tells it what it looks like. The Design Tokens Community Group format reached a stable Final Community Group Report (version 2025.10) in October 2025. It is plain JSON: each token has a $value and an optional $type, and one token can point at another with {group.token} aliases. Most token tools can read or write it, so you can keep one file and generate CSS custom properties from it.

This also pays off inside Figma. According to Figma's blog, if you give a variable its code syntax, the MCP server can hand that exact name to the model instead of letting it guess among several valid options.

The same component names in both places

If the Figma component is called Card/Promo and the React one is MarketingTile, the agent has to guess that they are the same thing. Name them identically, and keep variant properties aligned with component props (size=sm|md|lg in both).

Figma's Code Connect makes the mapping explicit. It shows real code snippets from your design system in Dev Mode instead of generated ones, and those connections feed the MCP server so an agent gets the path to the actual component file. It is available on Organization and Enterprise plans with a Full or Dev seat, and the developer docs list React, React Native, HTML (web components, Angular, Vue), SwiftUI and Jetpack Compose. No Code Connect on your plan? Matching names still get you most of the way.

Layer names matter too. Designers in an r/FigmaDesign thread on handing off to vibe coding point out that a model can't tell a deliberate detail from "Frame 247" leftovers, so an unnamed group of three rectangles may come back as three divs.

Docs next to the code

Storybook builds documentation from the stories you write, so each story doubles as a documented state of the component. The GOV.UK Design System is a good model for what each page should hold: when to use the component, how it works, and working code for every variant, including disabled.

Then write the rules the agent should always follow into its instructions file. Claude Code reads CLAUDE.md (and can read AGENTS.md), and its memory docs note that the more specific and concise the instructions, the more consistently they're followed. Keep it short: use tokens, never raw hex; reuse components from the UI folder before creating new ones; every list needs an empty state.

What a handoff contains now

A screen is the least useful part. Hand over these instead:

• The flow. Entry points, the exit after success, and where cancel goes.
• A state matrix. For each screen: empty, loading, error, populated and long content, at each breakpoint you support. One commenter in the r/UXDesign thread on handing off Claude Design work suggests exactly this per-screen matrix, including wrapping and focus, with acceptance checks attached.
• Content rules. Maximum lengths, truncate or wrap, plurals, and the exact error copy. Our guide to form error messages covers the copy side.
• Interaction and accessibility. Focus order, keyboard behaviour, what replaces hover on touch (see button hover states), and what a screen reader announces after an async action.
• Acceptance checks. Sentences a reviewer can test: "At 320px the filter bar collapses into one button." Why 320px? See the smallest screen size to design for.

Three workflows, depending on repo access

No repo access: spec plus prototype

You hand over the state matrix, a component map (which design component is which code component) and a clickable prototype. Several designers in the r/FigmaDesign handoff thread say this is where they started, and that getting access usually meant winning over one friendly developer first.

A shared design-system repo

You own the tokens and component docs in a repo, engineers own the product code. Some teams in the r/UXDesign version of the handoff discussion generate a markdown spec from Figma through the MCP server (tokens, interactions, motion, accessibility notes, node IDs) and turn it into Storybook stories before developers pick the work up.

Designer PRs on a design branch

You clone the product repo, build the screen with Claude Code or Cursor on top of the existing component library, and open a pull request. The Claude Design thread describes zip exports losing responsive behaviour, and this is the fix people keep landing on. Teams disagree on the next step: some engineers merge designer PRs after review, others treat them as a working reference and rebuild. Either is fine; agree which one before the first PR.

Getting Figma into the agent

The Figma MCP server lets tools like VS Code, Cursor and Claude Code pull a selected frame's code, variables, components and layout. The remote server is available on all seats and plans; the desktop one needs a Dev or Full seat on a paid plan. Figma's guide doesn't prescribe how to structure files, but the designers in the vibe-coding thread above found it worked best on files built with auto layout, variables and semantic tokens, sent one screen or flow at a time. Not everyone is sold: the r/UXDesign thread on code-first design systems includes complaints about MCP output hitting context limits on big files, which is one more reason to keep frames small.

Review on preview deploys, not redlines

Design QA moves to the pull request. Open the preview deploy at each breakpoint, walk the state matrix, check Storybook for the new or changed component, and leave comments on the PR where the engineer and the agent will see them. A screenshot with red arrows in Slack gets lost; a PR comment gets fixed.

Where it usually goes wrong

• Zip exports. They look right at one width and fall apart at the others.
• Happy-path prototypes. If the prototype has no error state, the build won't either.
• Invented components. The agent writes a new PrimaryButton2 because it didn't find yours. Point it at the component folder in its instructions and reject PRs that add near-duplicates.
• Token drift. Hard-coded hex values and pixel spacing creep in. A search for # in the PR's CSS catches most of it.

If you want to compare design tools for the exploration side of this, our UI design tools comparison is a good place to start.

Handoff checklist

HANDOFF: <feature name>        Source of truth: code | Figma

[ ] Flow: entry points, success exit, cancel path
[ ] Component map: design name = code name, new components flagged
[ ] Tokens only: no raw colour, spacing or font values
[ ] State matrix per screen:
    empty / loading / error / populated / long content
    x 320 / 768 / 1280
[ ] Content rules: max lengths, wrap or truncate, error copy
[ ] Focus order, keyboard, touch alternative to hover
[ ] Screen reader announcements for async results
[ ] Acceptance checks written as testable sentences
[ ] Agent instructions file updated if a rule changed
[ ] Review: preview deploy + Storybook, comments on the PR

Paste it into the ticket, fill in every line, and anything you leave blank is something the agent will decide for you.