Sync a design system to claude.ai/design

Sync a design system to claude.ai/design

What this is for

Claude Design (claude.ai/design) is Claude's design tool: users prompt a design agent and it builds working UI - screens, flows, prototypes - rendered live in the browser from real React code. Out of the box it designs with generic components. This skill changes that: it converts the user's design-system repo into the format Claude Design consumes and uploads it, so from then on the design agent builds with the customer's actual components - every design it produces is on-brand, made of their real parts, and maps 1:1 onto code their engineers can ship.

That framing should drive every judgment call in this skill, because each uploaded artifact is an input to that agent (or to the humans steering it):

This is why fidelity is the whole game: a component that renders wrong here renders wrong in every design the agent ever builds with it, and a wrong .d.ts or misleading .prompt.md makes the agent misuse the API everywhere. The verification loops in the sub-skills exist because of this - they are not bureaucracy.

The converter builds all of the above deterministically from the repo's own dist/. With a Storybook, previews come from the repo's stories and are verified against its own storybook render (kept as a local reference, never uploaded). Without one, every component still ships fully functional, and rich previews are authored from the repo's own usage examples for the components the user scopes in, graded on an absolute rubric. Core principle: ship what the customer already built - the bundle is their compiled dist/, never a reimplementation.

You have a DesignSync tool that reads and writes the user's claude.ai/design projects. If a tool call fails with an authorization error, relay its guidance to the user verbatim - the tool's message is environment-aware (in an interactive terminal it names /design-login; in headless sessions like claude.ai/code it points at a path that works there) - and retry after they've acted on it.

0. First sync? Set expectations before any work

A completed sync always leaves .design-sync/config.json holding both a projectId and a pkg. If both are present, this is a re-sync - skip this section (§2 covers honoring prior state). (If design-sync.config.json exists instead - the config's old name and location - move it: mkdir -p .design-sync && mv -n design-sync.config.json .design-sync/config.json, commit the move, then apply the same test.) Anything less - no config at all, or a partial one left by a run that never finished - gets first-time treatment: tell the user up front, before doing anything else:

• No completed sync was found - this is a first-time import.
• This skill attempts a high-fidelity import of their design system: by default that means iterating on the build and visually verifying the quality of every component preview, which can take up to a few hours on a large repo.
• They can interrupt at any time - a message mid-run to check progress or redirect the effort is welcome and won't break anything.
• A first-time import goes into a new Claude Design project created for it (§1). Everything that needs their approval happens near the start - creating that project, and one approval that covers this run's uploads into it. After that, verified components appear in the project as the run progresses: they can open the project at any time and watch it fill in, and nothing waits on their approval at the end.
• The run records config and notes as it goes, so future syncs are faster and mostly deterministic.

(If §1 routes this run into an existing project - the user re-adopting one, or a projectId left pinned by an aborted run - parts of this won't apply; scale the expectations to what §1 routes them to.)

Then confirm they want to proceed - this process can use a significant number of tokens (AskUserQuestion: proceed with the full high-fidelity sync, or adjust scope first). If their request already acknowledged the time/cost, note that and continue without re-asking.

1. Pick the target project

If DesignSync isn't already in your tool list, load it via ToolSearch(query: "select:DesignSync") first. A target gets picked one of three ways, in precedence order: