AI design tools
Claude Design to Claude Code: 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
You finish a prototype in Claude Design, the buttons look right, and you click the hand-off to Claude Code. Twenty minutes later there is a pull request. The layout matches. Then someone opens the screen with no data, or resizes the window, and finds a state nobody designed and a breakpoint nobody chose.
That gap is the subject here. Anthropic documents what the hand-off bundle contains, and it is less than people assume: design files, the chat that produced them, and a README. Everything else has to come from you.
If you are about to hand a real screen to Claude Code, this is for you. It explains what the bundle holds, how the three Design and Code connections differ, which kinds of intent are likely to leak, and what to add before and check after. We did not run the hand-off ourselves; this rests on Anthropic's pages and named people's reports.
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 tool for prototypes, slides and one-pagers, launched on April 17, 2026 (Anthropic). When a design is ready to build, you open its Export menu and choose the hand-off to Claude Code. Anthropic's tutorial says what happens next: "By default, we bundle the project's design files, chat, and a README", plus a prompt that includes the bundle's URL (Claude Academy).
That sentence is the whole documented mechanism. The prompt tells a coding agent where to fetch the bundle, and the README tells it how to read the designs. Nothing says the bundle carries a list of every state, an accessibility audit, or a mapping onto your design tokens.
So the useful question is not whether the hand-off preserves intent. It preserves what was drawn and what was said in the chat. The risk sits in everything that was neither.
Claude Design and Claude Code work together in both directions (rolling out today). Hand a design off to build, or start in Claude Code and sync design projects from your terminal. Export to PDF and PowerPoint, or send your work to more of the tools you already use.
— Claude (@claudeai) View on X
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. A Substack review reports 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).
Anthropic's pages mention none of those internals. Treat anything beyond "design files, chat, README" as reported, and as likely to change. For how this bundle compares with screenshots or structured data, see design-to-code tools and their four mechanisms.
Three ways the tools connect
"Can Claude Code use Claude Design" mixes up three separate routes. They move different things in different directions.
| 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 |
| /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 |
| /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 |
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.
This is one user's diagnosis, and the thread shows no Anthropic reply confirming it. It still teaches three things. A hand-off can fail before any design intent is at stake. A privacy setting chosen for another reason can disable it silently. And the zip route is a legitimate fallback, 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 build must respect: values, behaviours and reasons. The table sorts eight kinds by what the sources support. The third column is our reading of where each can leak.
| 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. For why token format matters to agents, see Markdown versus JSON design tokens. | 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 best served because the chat travels. Tokens and states are where one sentence in the chat changes the outcome most. Accessibility is the one where nothing documented helps.
A hand-off protocol: before, during, after
The steps below turn the loss map into actions. The first three come from Anthropic's tutorial; the rest are our reading of the reported failures. It is a proposal, not something we have 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 rules where Claude Code reads them every session, such as CLAUDE.md. One site reports that without this, bundle tokens merged with existing ones. The Claude Design skills guide covers teaching the tool your conventions.
- 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. A vendor analysis argues it is the lowest-loss transport, but that source sells design-to-code tooling, so weigh it accordingly.
Several things remain unknown as of October 1, 2026. No Anthropic page we found says how tokens are encoded in the bundle, whether per-state screenshots are included, or how conflicts with existing tokens are resolved. Anthropic's pages also describe availability differently: the help center calls Claude Design a beta on paid plans, while the product page says it is in all paid plans.
The independent evidence is thin: a few single-author reports and one closed issue, none a controlled study. Hand-offs also draw on the shared usage pool described in what Claude Design costs in usage, so a failed attempt is not free.
So 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 goes into the chat or the repo first. Put it in before, check it after. If you would rather feed Claude Code from Figma, the Figma MCP setup walkthrough covers the other route in.