Claude Design to Claude Code: the handoff bundle explained

Every other design handoff in this series has the same structural weakness: something renders the design to an artefact, and something else reads that artefact back. Between those two steps sits an interpretation, and interpretations lose things. A PNG loses structure. An HTML export loses grouping and responsive intent. Even a live MCP connection sends what a node contains rather than why it contains it.

A handoff bundle avoids that step entirely. It is assembled by the tool that made the design, while the reasoning behind the design is still in context. Nothing is re-derived from pixels or markup, because the thing doing the packaging is the thing that made the decisions. Of the three transport shapes in how to export a UI design to a coding agent, this is the one that loses the least.

When a design is ready to build, Claude packages it into a handoff bundle you pass to Claude Code with a single instruction. By default that bundle carries three things.

• The design files: The project's designs themselves, in a form the coding agent can download and read.
• The chat: The conversation that produced the design. This is the part no export format has an equivalent for — the discussion of why a layout changed, what was tried and rejected, what a section is for.
• A README: Instructions telling the model how to interpret the designs, plus a prompt you can paste into Claude Code — or another coding agent — that includes the bundle's URL.

That last detail is worth noticing: the bundle is addressable by URL and comes with its own prompt, so it is not locked to one agent. The handoff is most valuable when your codebase is linked, because Claude Code already understands the components and patterns the prototype was built against and continues from your existing work rather than rebuilding from a screenshot.

The design does not have to come first. From the terminal, /design creates, edits and syncs design projects without leaving Claude Code — importing a design into the codebase, turning existing code into a live prototype, or carrying a project through end to end.

# Create, edit and sync design projects from the terminal
/design

# Pull your existing design system into Claude Design,
# so new work starts from your real components
/design-sync

/design-sync is the more interesting of the two for anyone with a shipped product. It pulls your design system in, so what you build on the design surface starts from your existing components instead of inventing parallel ones that later have to be reconciled. If you have a component library, run it before you design anything.

Within a single screen, the bundle holds up well. Visual decisions survive, structure is coherent, and the code that comes out reads like it was written against your components rather than around them. This is genuinely the best handoff currently available, and it is not close.

The gap opens across sessions. Ask for a settings page on Monday and a billing page on Thursday, and the two will not necessarily agree. The heading scale may shift. The accent may land on a different element. The microcopy may change register. Nothing went wrong in either session — the problem is that the system was re-derived each time rather than consulted.

The fix is not a longer prompt. It is recording the decisions somewhere an agent consults on its own, every session, without you remembering to attach anything. What belongs there:

• Typeface assignments, including the restrictions: Which face owns headings, which owns body, and which sizes exist in the scale — stating what is not in the scale prevents the invented in-between size.
• Colours with functional labels: Not a list of hex codes but a set of roles: this is the accent and it appears only on primary actions; this is the surface; this is the destructive state.
• Specific spacing and motion values: The numbers, not adjectives. "Snappy" is not a duration and no two sessions will resolve it the same way.
• The audience, by name: Copy tone follows from who is reading. Name them and the register stops sliding between screens.
• The non-negotiables: Negative constraints work hardest of anything on this list. Each "never" closes off an entire family of plausible-but-wrong outputs before the agent explores it.

A markdown file in the repository is a reasonable first move and costs nothing. It stops scaling at the second repository, and stops working entirely at the third client — an argument we make properly in why your agent never got the rules.

Find two screens the same agent built for you weeks apart, in different sessions. Put them side by side and check three things: the accent colour and where it lands, the heading size, and the tone of the microcopy. If all three agree, your system is being consulted from somewhere stable. If they diverge, it is being re-derived every session — and the bundle, however good, was never the thing that could fix that.