design-sync

# 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):

| Uploaded artifact | Consumed by | For |
|---|---|---|
| `_ds_bundle.js` + `_vendor/` | the design agent's runtime | every design it produces renders these real compiled components from `window.<globalName>.*` |
| `styles.css`, `fonts/`, `tokens/`, `_ds_bundle.css` | every rendered design | the look - tokens, fonts, and component styles, all reachable from `styles.css`'s `@import` closure (designs receive only that closure) |
| `<Name>.d.ts` (`<Name>Props`) | the design agent | the API contract it codes against |
| `<Name>.prompt.md` | the design agent | its usage reference - how to compose the component, with examples |
| `<Name>.html` preview card | humans in the component picker | how they find components and trust the sync |
| `_ds_sync.json` | future syncs | the sync anchor - content hashes that let a re-sync (any machine) skip re-verifying unchanged components AND compute exactly what to upload/delete |

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:

- **Pinned**: `.design-sync/config.json` has a `projectId` -> that's the target. `DesignSync(get_project)` to confirm it still exists and is `PROJECT_TYPE_DESIGN_SYSTEM`, mention which project you're syncing to, and re-ask only if it's gone or the user redirects.
- **Fresh - the first-time default**: no pin -> **create a new project**. A fresh project is the only target whose entire contents this run owns; that ownership is what makes the incremental upload (§3) safe to approve in one shot, and it's why existing projects are never offered here - pouring a first import into a project that already has files would show a half-imported mix to anyone using it, with no sync anchor to tell its files apart from this run's. Use `DesignSync(list_projects)` to pick