SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsdesign-sync-upload

design-sync-upload

Design & creation

View repository

Updated 10-15 23:41

About this skill

design-sync-upload — Claude Design upload (automatic + manual fallback)

Overview

There are two ways to upload design system assets to Claude Design depending on the environment. This skill first attempts automatic (DesignSync MCP), and if authentication/availability conditions are not met, gracefully degrades to the **manual fallback (UPLOAD-GUIDE.md + staging folder)**. The goal of either path is to let the user upload in one go without manually scattering files.

This SKILL.md includes authentication detection, the automatic (DesignSync MCP) path, the manual fallback, and usage examples. DesignSync is methoda single MCP tool that dispatches to (see §Automatic Path for parameter details), and silently degrades to the manual fallback when unauthenticated or unavailable.

Trigger keywords

Claude Design upload, DesignSync MCP, design-login, design system sync, UPLOAD-GUIDE, asset staging, write_files, register_assets

Input

Input Form
DESIGN.md design-system-prep output
Tokens design-tokens-transformer output (DTCG/CSS/shadcn)
Assets Logo variants (horizontal/square/mascot/WH), fonts, images

Path selection — authentication detection branching

자산 준비
  → [감지] DesignSync MCP 가용 AND /design-login 인증됨?
      ├─ YES → 자동 경로 (DesignSync MCP)
      └─ NO  → 수동 폴백 (UPLOAD-GUIDE.md + 스테이징 폴더)

Detection signal

Signal How to check Verdict
DesignSync MCP tool presence Whether DesignSyncis loaded in the current session's tool list None → immediate manual
/design-login authenticated No authentication error when calling a harmless read method (list_projects) Normal return → automatic possible
Unauthenticated error signature Observed string: DesignSync needs design-system authorization. Run /design-login to authorize it with your claude.ai account This string detected → unauthenticated confirmed → manual

Detection order (minimize side effects): ① Pre-check only for tool presence → ② Determine authentication status via a harmless read method (list_projects/get_project) (no writes) → ③ If an unauthenticated error occurs here, fall back. Do not probe authentication with a write method (risk of partial upload).

Default degradation policy on detection failure: If detection itself is ambiguous (tool present but authentication status unknown, read call returns an ambiguous error, etc.), default to the manual fallback. Forcing automatic while assuming authentication without observation risks partial or duplicate uploads, so when in doubt, always go manual (never assume an unobserved state is success).

Automatic path — DesignSync MCP

/design-login In the authenticated state, register assets directly with the DesignSync MCP tool.

DesignSync는 methodIt is a single tool that dispatches to. Order dependency is enforced: read → finalize_plan → write. finalize_planOnly after this locks the path set is write allowed (writes outside the plan or without a planId are rejected).

  1. read (list_projects/get_project/list_files/get_file) — verify the target project (writable + type: PROJECT_TYPE_DESIGN_SYSTEM) then build a component-level diff against the remote structure. Incremental, not a full replacement.
  2. Approval gate — finalize_plan before calling. See §Write/Delete Approval Gate below. finalize_planThe runtime permission prompt raised by this does not substitute for this gate — that prompt shows only the path and does not show what goes into that path.
  3. finalize_plan — confirm the approved path set (writes/deletes, glob allowed) and the read source directory (localDir) → return planId . A permission prompt occurs.
  4. write_files (+ delete_files) — planIdto upload files. Each file is localPath(read directly from disk and uploaded — contents do not enter the context, recommended) or a small inline data. Up to 256 per call (if exceeded, split with the same planId).
  5. register_assets (legacy) — Design System cards are now automatically indexed from the <!-- @dsCard group="…" --> marker on the first line of the preview HTML (the app compiles it to _ds_manifest.json), so explicit registration is unnecessary. @dsCard Use only for manual projects without the marker.

Schema of each method's parameters (key fields)

Method Required Main parameters Notes
finalize_plan — projectId, writes[](glob, max 256), deletes[], localDir(default cwd) planId Returns. Expose the path list and source directory to the user
write_files planId projectId, files[]={path, localPath|data, mimeType} localPath는 localDir must be. 256 per call
delete_files planId projectId, paths[] Only paths included in the plan's deletesonly paths included in
register_assets(legacy) planId assets[]={name, path, group, viewport, subtitle} pathmust be included in the plan's writesmust be included in
create_project — name list_projectsis empty or the user makes a new selection

Order dependency: read → Approval gate → finalize_plan(planId issued) → write_files/delete_files → (if needed) register_assets. Calls to write/delete/register without a planId or with paths outside the plan are rejected.

Write/Delete Approval Gate

The remote design system is a shared asset that others are using. The previous contents of overwritten files and deleted files do not remain on the remote — this MCP has no atomic rollback (see §Partial Failure Policy below). So it stops before locking paths with finalize_plan.

  • [HARD] Approval is obtained via the paths in the §Approval Request Contract. finalize_planIt is not replaced by the runtime permission prompt of — that prompt shows only the path list and does not show the digest, semantic diff, or snapshot location. That prompt exposes only the path list and source directory, and localPath paths are it is by design that contents do not enter the context, so the user approves without seeing what is being overwritten.
  • [HARD] Globs are expanded and shown before approval. writes[]/deletes[]allows globs. Unexpanded globs can match far more than the user intended, and the difference is not visible at approval time. List the actually matched paths one by oneand write the count alongside them.
  • [HARD] Do not summarize; show the following as-is:
What to show Why it is needed
Target project name, ID, and type Prevents accidents of writing to the wrong project
Expanded path list — new / overwrite distinction New has nothing to lose; overwrite does
Deletion path list (separate section) Because it is the hardest item to undo, do not mix it in
Per-file size and digest (hash) — not optional but required Even if the content cannot be seen, scale and identity can be confirmed. planIdWhat locks is pathsonly, so what binds the content is this digest
For overwrite targets, semantic diff summary see rules below
No-copy notice The fact that content lost by this operation cannot be recovered
  • [HARD] This MCP has no safe recovery snapshot means. The skill does not create one instead. The only path to fetch remote content is get_filebut that response passes through the model context. Even if credentials, customer assets, and unreleased designs are mixed in, they pass through as-is, and the local copy received has no permissions, retention period, or repository exclusion rules. Creating an exfiltration path while trying to make a backup is worse.
  • [HARD] Instead, inform the user of the facts. While showing the list of paths to overwrite or delete, "The current contents of these files will be lost by this operation, and the skill does not create copies" state this explicitly. If a copy is needed, guide the user to download it themselves before proceeding.
  • The targets are only overwrite and deletion paths. New paths have nothing to lose, so exclude them from this notice — this is why new and overwrite are shown separately.
  • Later, if the server exports directly to a restricted-permission directory without responding with the content provides such a feature, then reconsider automatic snapshots at that time. Until then, do not promise "we will keep a recovery copy."
  • [HARD] Do not fetch the remote original text to create a semantic diff. To compare content, get_filemust receive the entire remote, and that is precisely the exfiltration path blocked above. On the approval screen, only what can be known without the original is written — path, new/overwrite distinction, size and digest of the local file, deletion targets.
  • If a content-level diff is truly needed, only when the user hands over a copy they downloaded themselves is it created. The skill does not pull from the remote.

The approval options are composed as follows:

Options 뜻
Execute according to this manifest (recommended) Exactly the set of paths shown finalize_plan → write/delete
Writes only, excluding deletions deletes[]empty and re-establish the plan
Narrow the paths Reduce the manifest and re-
Cancel finalize_planexit without calling. No remote changes
  • [HARD] planIdis bound to that approved manifest. To add paths or widen globs after approval, re-approvalmust be obtained and finalize_planmust be run again. Do not sneakily add to the existing planId.
  • [HARD] write_files Immediately before, recompute the digest and compare it against the value at approval time. write_filesis, after approval, localPath를 read again — if a file changes between approval and upload, content the user never approved goes up under the same path. This is the interval where concurrent edits, build artifact refreshes, and file replacements actually occur.
  • If even one thing mismatches, discard that planIdand obtain re-approval. Do not proceed with only the mismatched file excluded — because the state is one in which what changed and why is unknown.
  • [HARD] This comparison only narrows the window; it cannot close it. Do not hide that limitation from the user. write_files The schema has no expectedDigest, and the point at which the server opens the file is 뒤the point at which the skill measured the hash. If the file changes in between, there is no way to prevent it under the current contract. Therefore, do not guarantee that "the approved bytes go up unchanged" — what is guaranteed is only up to "there was no trace of change right up to that point."
  • Practical ways to narrow the window: do not insert other work between digest recomputation and the write_files call . If a build, formatter, or sync tool is running, start after it finishes. The longer the time from the approval screen to upload, the greater the risk.
  • If the server provides a feature that receives expectedDigestand verifies immediately after opening the file, then raise the guarantee level. Do not write contracts premised on features that do not exist.
  • [HARD] Do not bundle deletion into the same approval as writing. Always include "writes only, excluding deletions" among the above options, so that deletion alone can be rejected separately. Do not let it take the form of passing deletion along with writing in order to get writing approved.

Partial failure retry/rollback policy

  • write_files Failure: overwriting the same path is idempotent, so retry up to 3 times. If it keeps failing, notify the user of the already recorded files and fall back.
  • Some of the splits exceeding 256 fail: retry only the failed batch, keep the successful batches (same planId).
  • MCP does not provide atomic rollback → partial write state Do not report as fake completion. Continue writing only the remaining files or move to manual fallback (for calls with side effects, resume after checking state — prevent duplicate uploads).

Error → fallback switch condition

Error Switch
Unauthenticated string (signature above) Automatic give-up → immediate manual fallback
DesignSync Tool not loaded Manual fallback
write_files Failure after 3 retries Manual fallback (notify user on partial write)
Network/temporary error If successful after retry, keep automatically
planId expired/path outside plan rejected finalize_plan Re-execute to re-establish plan

Approval request contract (runtime-neutral)

[HARD] This skill's gate is not tied to a specific tool name. AskUserQuestionis merely a means of the Claude runtime, and other runtimes including Codex do not have that tool. If the contract is written in terms of tool names, then in runtimes without that tool the gate becomes a permanent blocker, and every task requiring approval simply stops. That is not safety, it is a breakdown.

Approval is obtained in the following order. From the top, use the first one that is actually possible.

The definition of approval is the result, not the means: showing the approval form to the user as is and receiving an explicit response to it. Below are the paths that produce that result, and from the top, use the first one that is possible.

Rank Path Condition
1 The runtime's structured question tool (AskUserQuestion 등) When that tool is exposed in the current session
2 Present the approval form in normal conversation and receive a response in the next turn When in direct conversation with the user. Even without the tool, this path is always open
3 Return a structured blocker → the upper-level orchestrator asks When running as a subagent

[HARD] The runtime's tool execution permission prompt is not approval. That prompt only asks "may I call this tool," and does not display the arguments, estimates, or consent items that the gate is supposed to show. It is recognized as path 2 only when the entire approval form and options are actually displayed.

[HARD] Because path 2 exists, the situation of "having no means to ask" effectively does not exist. Wherever conversation is possible, the approval form can always be presented in writing. fail-closed is Fully unattended execution where neither dialogue nor blocker return is possibleapplies only to that — only in that case does it stop without executing.

[HARD] When using path 3, the blocker must itself be an approval request. If the upper level does not know what to ask, it cannot ask back, and then it deadlocks. It includes all of the following:

  • The action to be approved, in one line (what is irreversible / how much is going out)
  • All arguments required by the gate (unsummarized values)
  • List of options — in a form the upper level can present to the user as-is
  • How to resume — upon receiving which answer, what to continue executing

[HARD] In unattended execution where all three paths are impossible, do not execute (fail-closed). Having no means to ask does not mean approval was obtained. In this case, record "could not proceed because there is no means of approval" and stop — do not proceed silently. Conversely, stopping because there is no tool even though dialogue is possible is also wrong. Use path 2.

This contract is CLAUDE.local.md the gate-side application of §Generality Principle (identical behavior across 2 OSes × 2 runtimes). A gate that runs on only one runtime is considered incomplete.

Manual fallback — UPLOAD-GUIDE.md + staging folder

If MCP is absent or unauthenticated, produce artifacts the user can upload directly.

  1. Staging folder composition — by default, ./design-sync-staging/place DESIGN.md + tokens + cleaned asset copies in
  2. Generate UPLOAD-GUIDE.md — state upload priorities, cautions, and the Published toggle procedure
  3. User guidance — instruct to upload the entire folder to claude.ai/design
## Claude Design 업로드 가이드 (수동)

### 업로드 우선순위
1. DESIGN.md — 가장 먼저
2. 토큰 세트(DTCG/CSS/shadcn)
3. 로고 변형(SVG 우선)
4. 참고 자산

### 주의
- 모노레포 전체 X → 정리된 폴더만
- 민감 자산(고객 데이터·매출) 익명화 후 업로드
- 폰트 라이선스 확인

### Published 토글
1. 업로드 후 5-15분 대기(분석)
2. 테스트 프롬프트로 검증
3. 브랜드 일치 시 Published ON, 어긋나면 Remix

Staging folder layout

./design-sync-staging/
├── DESIGN.md                    # 최우선
├── tokens/
│   ├── 02-tokens.json           # L1 DTCG SSOT
│   ├── colors_and_type.css      # L2 원시 CSS 변수
│   └── globals.css              # L3 semantic/shadcn + .dark
├── assets/
│   ├── logo/                    # 로고 변형(아래 매트릭스)
│   ├── fonts/                   # 라이선스 확인된 폰트
│   └── reference/               # 참고 이미지·캡처
└── UPLOAD-GUIDE.md              # 업로드 절차

UPLOAD-GUIDE.md full template

# Claude Design 업로드 가이드 (수동)

## 업로드 순서
1. DESIGN.md — 가장 먼저(디자인 시스템 요약)
2. tokens/ — L1 DTCG → L2 CSS → L3 globals.css 순
3. assets/logo/ — 변형별(가로/정사각/마스코트/화이트 녹아웃)
4. assets/fonts/ — 라이선스 확인된 것만
5. assets/reference/ — 톤 비교용 참고 자산

## 업로드 방법
1. claude.ai/design 진입 → Organization settings → Design systems
2. 위 폴더를 통째로 업로드(모노레포 전체 X)
3. `/design-login` 후 Claude Code 터미널이면 다음부터 자동 경로 사용 가능

## 주의
- 민감 자산(고객 데이터·매출 박힌 덱)은 익명화 후 업로드
- 폰트 라이선스 확인 — 불명 자산 제외
- 누락된 로고 변형은 "미제공"으로 표기(임의 생성 금지)

## Published 토글
1. 업로드 후 분석 대기(5–15분)
2. 테스트 프롬프트로 검증("마케팅 랜딩 페이지 디자인해 줘" 등)
3. 브랜드 일치 → Published ON / 어긋나면 Remix 또는 자산 추가

Asset variant matrix mapping rules

Variant Filename convention (example) Intended use
Horizontal logo-horizontal.* Header/nav — where horizontal margins are secured
Square logo-square.* Favicon, app icon, social profile
Mascot mascot.* Hero, empty state, 404 (limited to emotional areas)
White-knockout logo-*-WH.* Solid white on dark/gradient backgrounds

Mapping rules: classify the original logo into the 4 variants above, assign a usage tag to each variant, and specify it in UPLOAD-GUIDE.md — so that after upload, Claude Design picks the correct variant for each context. Variants not provided are marked as "not provided" and are not arbitrarily generated.

Output format

## Claude Design 업로드 [자동 / 수동]

### 경로
- 선택: 자동(DesignSync MCP) / 수동 폴백
- 사유: [인증 상태 / MCP 가용성]

### (자동) 등록 결과
- finalize_plan: planId 발급 / writes N · deletes N
- write_files: N개 (localPath 업로드)
- register_assets: (레거시) @dsCard 자동 인덱싱 또는 N개 수동

### (수동) 산출물
- ./design-sync-staging/  (DESIGN.md + 토큰 + 자산 N개)
- ./design-sync-staging/UPLOAD-GUIDE.md

### 다음 단계
- (자동) 5-15분 분석 대기 → 테스트 프롬프트 → Published 토글
- (수동) 폴더 업로드 → 위 가이드 따라 진행

Usage examples

Example 1 — Authenticated → automatic registration

사전: DesignSync MCP 로드됨 + list_projects 정상 반환(인증됨)
동작: finalize_plan(writes=DESIGN.md+토큰+로고, localDir=./staging)
      → write_files(planId, localPath로 8개) → (@dsCard 자동 인덱싱)
출력: 자동 등록 완료 → 분석 대기
보고: finalize_plan planId 발급, write_files 8, 카드 자동 인덱싱

Example 2 — Unauthenticated → Manual Staging

사전: list_projects 호출 시 "DesignSync needs design-system authorization. Run
      /design-login to authorize it with your claude.ai account" 에러
동작: 자동 포기 → ./design-sync-staging/ 구성 + UPLOAD-GUIDE.md 생성
출력: 스테이징 폴더(DESIGN.md + tokens/ + assets/) + 가이드
안내: 폴더째 claude.ai/design 업로드. /design-login 하면 다음엔 자동 경로

Example 3 — Error After Auto Start → Fallback Switch

사전: 인증됨으로 자동 시작
동작: finalize_plan OK → write_files 진행 중 5개 중 2개 반복 실패
전환: 실패 배치 3회 재시도 후에도 실패 → 부분 기록 상태 고지 → 남은 자산 수동 스테이징
출력: (자동 부분: write_files 3개 완료) + (수동: 실패 2개 스테이징 + 재개 안내)
보고: 부분 성공을 완료로 보고하지 않음 — 미기록 파일 명시, 중복 방지 재개 안내

Precautions

Do

  • Try auto first, and if conditions aren't met, quietly demote to manual — without interrupting the user's workflow
  • Configure folders completely so that even in manual fallback the user doesn't have to scatter files by hand
  • Guide anonymization of sensitive assets before upload

Don't

  • /design-login Do not force the automatic path while unauthenticated — immediately fall back to manual
  • Do not report partial automatic success as complete — finalize_planmust be confirmed for completion
  • Do not include assets with unverified font licenses in the upload set

Related Skills

Skill When to Use
moai-designer:design-system-prep Prerequisite: DESIGN.md synthesis
moai-designer:design-tokens-transformer Prerequisite: Generate the 3-tier tokens to upload
moai-designer:design-handoff Alternative: When the handoff package is the deliverable
moai-designer:design-handoff-reader Reverse: Claude Design → Claude Code handoff analysis