TL;DR
/design-syncdoes not upload your design system, it compiles it. It turns your component library into a bundle the Claude Design agent executes in the browser, which forces a requirement the official docs never mention: React. A React package with a publisheddist/, or a Storybook, gets in. Vue, Angular and Svelte do not, and your road is the MCP.
Claude Design does not hand back mockups. It builds working screens and prototypes, rendered live in the browser from real React code. Out of the box it builds them with generic components. The screen may look good, but it is not yours, and converting it into your real components costs more than building it by hand.
/design-sync closes that gap. From the moment you run it, every screen the agent produces is made of your parts and maps onto code your team can ship.
What it is not
I got two things wrong before reading the skill's own source, and I suspect most people will.
It is not a copy of your repo in the cloud. It compiles. It takes your built dist/ and produces a package the agent can load and execute, like a plugin. Moving files up as they are does exist, but that is /design export, a different road.
It does not sync your application. It syncs your component library. Whether your product is Nuxt, Laravel or a PHP monolith makes no difference, because the application never travels. The question is not what your product is built with, it is what your reusable components are written in.
What it uploads, and who reads it
Several artifacts travel per component, and each one has a different reader:
- The compiled bundle from your
dist/, with its dependencies. The agent's runtime loads it and mounts the components from it. - CSS, tokens and fonts, reachable from
styles.css. This is the one that breaks, and it gets its own section below. - A
.d.tsper component, the API contract the agent codes against. - A
.prompt.mdper component, its usage reference with examples. - An
.htmlpreview, and this one is for you: it is the card you see in the component picker. - A
_ds_sync.jsonof content hashes, so the next sync skips whatever has not changed.
The principle the skill repeats in its own text is that it ships what you already built, never a reimplementation. That is why it visually verifies every preview before uploading it, and why a first sync can take hours on a large repo.
Who gets in and who does not
| Your components | Does /design-sync take them? |
|---|---|
React shipped as a package with dist/ |
Yes, the "package" shape |
| React with Storybook | Yes, and previews come from your own stories |
| Vue, Angular, Svelte | No, there is no road today |
| Blade, Twig or server-side templates | No |
This is not the command being difficult. The Claude Design renderer runs React, and your components have to mount inside it. The support article presents /design-sync as the way to bring your design system in and never mentions the requirement anywhere.
If your components are not React, you are not locked out of Claude Design: you design there, pull the .dc.html artboard down with the MCP and ask Claude Code to implement it against your repo. The translation still happens, but the agent does it with your components in front of it.
How to run it
1. Start in your design system repo
Not your application repo. The command needs the package that ships the components.
2. Run the command
/design-sync
Only you can launch it: the skill is marked as not model invocable, so Claude cannot start it on its own no matter how you phrase the request.
3. Confirm what it warns you about
On a first sync it tells you this is a high-fidelity import, that it can take hours on a large repo, and it asks you to confirm the token cost explicitly. You can interrupt at any point without breaking anything.
4. Approve the upload once
It creates a fresh project, asks you to name it, and raises one approval labelled with how many files it will upload and how many it will delete. After that, components show up as they are verified, so you can open the project URL halfway through and watch it fill in.
What broke when I ran it
I synced a four-component design system whose tokens live in dist/tokens.css, pulled into styles.css by a sibling @import. The converter cannot reach that, because tokensPkg and tokensGlob only look inside node_modules/<package>. Validation flagged [CSS_IMPORT_MISSING] and [TOKENS_MISSING] with 19 undefined custom properties: the bundle would have shipped without a single token while the cards still looked fine.
The way out was a one-line file wired through extraEntries, so esbuild inlines the whole @import chain into the bundle's CSS:
// .design-sync/ds-styles-entry.mjs
import "../dist/styles.css";
The second snag was the browser. Visual verification needs one, and without Playwright's cached build that is a 200 MB download, or you point DS_CHROMIUM_PATH at the Chrome you already have.
What it writes into your repo
When it finishes, .design-sync/ holds config.json with the project pinned, a NOTES.md of what it learned, one preview per component and a conventions.md. That last one is not decorative documentation: it is prepended to the README and ends up inside the design agent's system prompt, so it is where you tell it how your library composes. All of it gets committed, and it is what makes the second sync fast instead of creating a duplicate project.
The Claude Design commands, and which one needs the MCP
None of these commands come from the MCP. Slash commands belong to the client; the MCP only contributes tools.
| Command | What it does | What it acts on |
|---|---|---|
/design-sync |
Compiles and uploads your design system | The native DesignSync tool |
/design-login |
Authorizes design-system access for /design-sync |
The native DesignSync tool |
/design-consent |
Grants Claude access to your Design projects | The permission the MCP tools need |
/design-revoke |
Takes that permission back | The permission the MCP tools need |
/design (hub) |
Routes sync, login, consent and revoke, and adds import, export and status |
The four commands above |
/design (canvas) |
The editable canvas skill, a different thing under the same name | A local Artifact |
Two details explain why they are so hard to find. /design-consent and /design-revoke are flagged as hidden, so they never show in the command menu however long you stare at it. And there are two separate registrations named design, the hub and the canvas skill, each with its own enablement condition, so which one you get depends on your account.
Where this fits
If what bothers you is that the UIs come out generic and you have no design system, your tool is the Frontend Design Skill, which raises the aesthetic floor from nothing. That tip tells you not to use it once you have an established design system, and this is exactly what goes in that gap: instead of improving the agent's taste, you replace its parts.
And if your source of truth is Figma rather than a repo, the loop is Figma plus Chrome MCP.
Official docs: Get started with Claude Design
Requirements
- A React design system, either a package with a published
dist/or a Storybook - A browser for the visual verification, Playwright's or your own
- A first-party claude.ai account (not API key, Bedrock or Vertex)
- An organization policy that allows Claude Design
- Tested on Claude Code v2.1.234