AI design tools
Claude Design to Claude Code: How the Hand-off Works and Where Design Intent Gets Lost
What the Claude Design to Claude Code bundle contains, how /design and /design-sync differ from it, and a loss map of what design intent survives the trip.
· Diagram Studio Editorial
Direct answer
Claude Design hands work to Claude Code from its Export menu. By default the bundle holds the project's design files, the chat that produced them, and a README, plus a prompt containing the bundle's URL (Anthropic tutorial). No source documents a guarantee for states you never designed, responsive rules, accessibility or your token names. As of October 1, 2026, specify those before the hand-off and verify them after.
The short answer: a bundle, a prompt and a README
Claude Design is Anthropic's design tool for prototypes, slides and one-pagers, launched on April 17, 2026 as an Anthropic Labs product (Anthropic). When a design is ready to build, you open its Export menu and choose the hand-off to Claude Code. Anthropic's own tutorial describes what happens next: "By default, we bundle the project's design files, chat, and a README" and give you a prompt that includes the bundle's URL (Claude Academy).
That sentence is the whole documented mechanism. The bundle has three parts, the prompt tells a coding agent where to fetch it, and the README tells the agent how to read the designs. Nothing in that description says the bundle carries a test suite, an accessibility audit, a list of every state, or a mapping onto your design tokens.
So the useful framing is not "does the hand-off preserve design intent". It preserves what was drawn and what was said in the chat. The risk sits in everything that was neither. The rest of this article maps that risk category by category, labels each claim by how well it is supported, and ends with a protocol you can run before and after the hand-off.
Everything below is as of October 1, 2026, and Anthropic has changed this feature several times since April (see the next section). The editorial team has not run the hand-off. Every claim is labelled **documented** (an Anthropic page), **reported** (a named person or site describing their own use) or **inference** (our reading of the first two).
What the hand-off actually sends
Anthropic's help article lists the hand-off as an Export menu entry with two choices: "Send to local coding agent" and "Send to Claude Code Web" (Claude Help Center). The local choice picks up Claude Code on your machine against your repository. The web choice runs in the cloud. The same menu also offers a .zip download, PDF, PPTX and standalone HTML; those formats, and what each one loses, are covered in Getting Work Out of Claude Design.
Two details matter for how well the hand-off works. First, the tutorial says it is "especially valuable when your codebase is linked", because Claude Code then already understands the components and patterns the prototype was built with. A project designed against a linked codebase starts from your real components; a project designed from nothing hands over a prototype with invented ones.
Second, the chat travels with the files. The tutorial tells designers to name components clearly, because those names carry through, and to state decisions in the conversation, because that reasoning "becomes context for implementation". That is the only mechanism Anthropic documents for carrying rationale, so the quality of the chat is the quality of the rationale.
Third-party descriptions of the bundle differ from this. A Substack review reports that the bundle arrived as a tar archive whose README told the agent to read the files and match the visual output in whatever technology the codebase used (Victor Dibia). Another site describes a manifest, React components and interaction recordings (ClaudeLab), which Anthropic's pages do not mention. Treat bundle internals beyond "design files, chat, README" as reported, not documented, and as likely to change.
Three ways the tools connect
Search queries such as "can Claude Code use Claude Design" mix up three separate routes. They move different things in different directions, and two of them are newer than the original hand-off.
| Route | Direction | How you start it | What it moves | Label |
|---|---|---|---|---|
| Hand-off | Design to code | Export, then hand off to Claude Code | Design files, chat, README and a prompt with the bundle URL | Documented (Anthropic tutorial and help center) |
| /design-sync | Code to design | Run /design-sync in Claude Code | Pulls your design system in so new Claude Design work starts from your existing components | Documented (help center and June 17 blog post) |
| /design | Starts in code | Run /design with a brief in Claude Code | Publishes a canvas of editable artboards you pick from, tweak, then ask Claude to implement; research preview, Claude Code v2.1.234 or later | Documented (Claude Code what's-new, week 34) |
The June 17, 2026 update is what made the second route possible. Anthropic's announcement says Claude Design can now take design systems from a GitHub repo, design files or raw uploads, build with those components and check its output against them before you see it (Claude blog). The same post says usage is now shared with the rest of Claude, including Claude Code. For how that pool behaves, see what Claude Design costs in usage.
The /design command is different in kind. According to the Claude Code release notes for August 17 to 21, it brings the artboard workflow into the CLI and desktop app, built on artifacts (Claude Code Docs). It starts in code, so no hand-off bundle is involved. If your question is whether Claude Code can use Claude Design, the answer is yes through all three routes, but only the first produces the bundle this article is about.
One practitioner quoted by The New Stack describes the split these routes support.
My ideal workflow is: design exploration in the web UI, then engineering-grade handoff in Claude Code with the actual repo context.
The one first-hand failure report, and what it teaches
The best-documented problem with the hand-off is not about design at all. On June 18, 2026, a user filed anthropics/claude-code issue 69246: the default prompt from "Send to local coding agent" asked Claude Code to import the project "using the Claude Design connector", and the local session could not fetch the design. The same export dialog offered a zip download for agents without that connector.
The reporter closed the issue the next day with a different diagnosis. Local Claude Code does ship the connector, which is the built-in /design-sync mechanism, but in their setup an environment variable that restricts nonessential network traffic, CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC, stopped it from registering. They quote a message from the 2.1.183 build saying DesignSync is unavailable while that variable is set. Claude Code then fell back to fetching an authenticated URL, which failed with no explanation. Removing the variable and restarting made the hand-off work for them.
Label this **reported**: it is one user's diagnosis, and the thread shows no Anthropic reply confirming it. It still gives three usable lessons. A hand-off can fail before any design intent is at stake. A privacy setting you chose for another reason can disable it silently. And the zip route is a legitimate fallback rather than a lesser one, because the README inside tells the agent how to read the designs.
The loss map: which design intent survives
Design intent here means the decisions a designer made that a build must respect: the values, the behaviours and the reasons. The table sorts eight kinds of intent by what the sources support. The third column is our inference about where each can leak; where a reported failure exists, it is named.
| Intent | What sources support | Where it can leak (inference) | Label |
|---|---|---|---|
| Colour, type and spacing tokens | Claude Design reads a linked codebase for its colour system, spacing scale and typography (tutorial). The bundle list names no separate token file. | Values arrive inside design files; mapping them onto your token names is left to Claude Code. A PM-written guide warns against hard-coded hex values, and one site reports unused token definitions left beside live ones. | Documented for design-time reading; reported for build-time leaks; inference for the mechanism |
| Layout and spacing | The design files carry the layout. A vendor post says visual decisions hold up within one screen (Flowpoint). | Pixel values that sit between steps of your spacing scale. | Reported (vendor with a commercial interest); inference |
| Component states | Anthropic tells designers to ask Claude for empty, error and loading states and different data volumes before hand-off. | A state nobody asked for is not in the bundle, so the engineer or agent invents it. | Documented advice; inference about the gap |
| Responsive behaviour | Anthropic advises saying early whether the design must work on mobile, tablet and desktop (help center). | Breakpoints left unspecified. One developer reports mobile overlap when responsive breakpoints were not specified (ClaudeLab). | Documented advice; reported failure |
| Interaction and motion | Prototypes can be interactive. Nothing documents how durations, easing or an animation library are conveyed. | The agent reproduces the motion with whatever mechanism it picks. A public checklist lists CSS keyframes used where the project standard was a motion library (toolkit). | Inference, with a reported example |
| Copy | Text sits in the design files. | Strings hard-coded where your project uses a translation function; the same checklist flags this. | Reported checklist item; inference |
| Accessibility | Anthropic mentions refining accessibility through comments and chat. No page documents an accessibility check as part of the bundle. | Contrast, focus order and labels are unverified until you test the build. | Inference |
| Rationale | The chat is bundled, and the tutorial says decisions stated there become context for implementation. | Reasons buried in a long chat, or rejected alternatives the agent reads as requirements. A reviewer reports still having to decide what to aggregate, hide and place (Dibia). | Documented mechanism; reported residual; inference |
Read the table as a priority list, not a score. Rationale is the best-served category because the chat travels. Tokens and states are the two where a short statement in the chat changes the outcome most, and accessibility is the one where nothing in the documented bundle helps.
A hand-off protocol: before, during, after
The protocol below turns the loss map into actions. Steps one to three come from Anthropic's tutorial; the rest are our inferences from the reported failures. It is a proposal, not something the editorial team has run.
- Link the codebase before designing, and link the package that holds the components, not the whole monorepo or the .git and node_modules folders. Anthropic notes that very large repositories can cause lag or browser instability.
- Name components the way your repo does. The tutorial says names used in the design conversation carry through.
- State decisions and their reasons in the chat as you make them, in one sentence each, for example why tabs were chosen over a sidebar.
- Ask for empty, error and loading states and a large and a small data volume, and name the breakpoints you will ship. Anthropic documents the first part; the breakpoints are our addition.
- Write down your token and component rules where Claude Code reads them every session, such as a CLAUDE.md file. One site reports that without this, bundle tokens merged with existing ones.
- Check the path before you start: if "Send to local coding agent" fails, look for settings that restrict nonessential traffic, or download the zip and point Claude Code at the unzipped folder.
- Ask Claude Code to list what it could not determine from the bundle before it writes code, then answer those items in writing.
The protocol costs minutes before the hand-off and removes the guesses the agent would otherwise make quietly.
The review step: checking what the build lost
A reviewer can check this in the pull request without reading the bundle. The goal is to compare the build against the intent, category by category, and to send back only the differences that matter.
- Tokens: search the diff for raw hex, pixel and font-size values that your token files already define.
- Components: confirm the build reuses your library components instead of new ones with similar names.
- States: open each state listed in the design chat and force it, including the empty and failed ones.
- Responsive: resize to every breakpoint you named and check for overlap and clipped text.
- Motion: compare durations and easing with the prototype and with your motion standard.
- Copy: check that strings go through your translation function if you have one.
- Accessibility: run an automated audit and tab through the screen; automated tools do not cover everything, so do both.
- Rationale: for each decision recorded in the chat, find the line in the diff that honours it.
Keep a human in the loop for decisions that change meaning. Victor Dibia, who handed a feature to Claude Code after designing it in Claude Design, found that the generated output still needed his judgment.
Claude Design sits at the center mass of generation, but the sensitive decisions around the generated output are still yours — when to aggregate vs. show raw numbers, what to hide for privacy, and where to place things on a conversion-sensitive page.
The New Stack's reporting adds the team-level view. A lead AI product designer at ABM Industries told the publication she does not think Claude Design has meaningfully reduced the back-and-forth between departments, and that token cost remains a concern (The New Stack). That is one practitioner's opinion, but it matches the logic here: a better bundle shrinks the gap without removing the review.
What to expect, and what is still unknown
The hand-off is the most direct path Anthropic documents from a Claude Design project to Claude Code, and it carries more than a screenshot would: files an agent can read, the conversation behind them, and instructions for interpreting both. A vendor analysis argues this makes it the lowest-loss option among design-to-code transports, but that source sells design-to-code tooling, so weigh it accordingly. For a comparison of mechanisms across tools, see design-to-code tools and their four mechanisms.
Several things remain unknown as of October 1, 2026. No Anthropic page we found states how tokens are encoded in the bundle, whether per-state screenshots are included, or how conflicts with existing tokens are resolved. The bundle format has changed since April and may change again; Anthropic's own pages describe availability differently (the help center calls Claude Design a beta on paid plans, while the product page says it is included in all paid plans), so check the current wording before planning around it. The independent evidence is thin: a handful of single-author reports and one closed issue, none of them a controlled study.
The answer to the question in the title is therefore specific. The hand-off carries the design files and the conversation. Intent that exists only in the designer's head, such as the empty state nobody drew, the breakpoint nobody named and your own token vocabulary, does not travel unless it is put in the chat or the repo first, and nothing in the build proves it arrived until someone checks. Put it in before, check it after, and the bundle does its job.