design-sync-upload

design-sync-upload — Claude Design 업로드 (자동 + 수동 폴백)

개요

디자인 시스템 자산을 Claude Design에 올리는 방식은 환경에 따라 두 가지입니다. 이 스킬은 자동(DesignSync MCP)을 먼저 시도하고, 인증·가용성 조건이 안 되면 **수동 폴백(UPLOAD-GUIDE.md + 스테이징 폴더)**으로 자연스럽게 강등합니다. 어느 경로든 사용자가 손으로 파일을 흩뿌리지 않고 한 번에 업로드할 수 있게 만드는 것이 목표입니다.

이 SKILL.md는 인증 감지·자동(DesignSync MCP) 경로·수동 폴백·사용 예시를 모두 포함합니다. DesignSync는 method로 디스패치하는 단일 MCP 도구이며(파라미터 상세는 §자동 경로 참조), 미인증·미가용 시 조용히 수동 폴백으로 강등합니다.

트리거 키워드

Claude Design 업로드, DesignSync MCP, design-login, 디자인 시스템 동기화, UPLOAD-GUIDE, 자산 스테이징, write_files, register_assets

입력

입력	형태
DESIGN.md	design-system-prep 산출물
토큰	design-tokens-transformer 산출물(DTCG/CSS/shadcn)
자산	로고 변형(가로/정사각/마스코트/WH), 폰트, 이미지

경로 선택 — 인증 감지 분기

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

감지 신호

신호	확인 방법	판정
DesignSync MCP 도구 존재	현재 세션 도구 목록에 DesignSync가 로드됐는지	없음 → 즉시 수동
/design-login 인증됨	무해한 read 메서드(list_projects) 호출 시 인증 에러 미발생	정상 반환 → 자동 가능
미인증 에러 시그니처	관측된 문자열: DesignSync needs design-system authorization. Run /design-login to authorize it with your claude.ai account	이 문자열 감지 → 미인증 확정 → 수동

감지 순서(부작용 최소화): ① 도구 존재만 사전 확인 → ② 무해한 read 메서드(list_projects/get_project)로 인증 상태 판별(쓰기 없음) → ③ 여기서 미인증 에러가 나오면 폴백. 쓰기 메서드로 인증을 떠보지 않는다(부분 업로드 위험).

감지 실패 시 기본 강등 정책: 감지 자체가 모호하면(도구는 있으나 인증 상태 불명, read 호출이 애매한 에러 반환 등) 수동 폴백을 기본값으로 강등한다. 인증됨을 관측 없이 가정하고 자동을 강행하면 부분·중복 업로드 위험이 있으므로, 애매하면 항상 수동이다(미관측 상태를 성공으로 가정 금지).

자동 경로 — DesignSync MCP

/design-login 인증 상태에서 DesignSync MCP 도구로 자산을 직접 등록합니다.

DesignSync는 method로 디스패치하는 단일 도구다. 순서 의존성이 강제된다: read → finalize_plan → write. finalize_plan이 먼저 경로 집합을 잠근 뒤에야 write가 허용된다(플랜 밖 경로/planId 없는 write는 거부).

1. read (list_projects/get_project/list_files/get_file) — 대상 프로젝트 확인(쓰기 가능 + type: PROJECT_TYPE_DESIGN_SYSTEM) 후 원격 구조로 컴포넌트 단위 diff 구성. 전량 교체가 아니라 증분.
2. 승인 게이트 — finalize_plan 호출 전. 아래 §쓰기·삭제 승인 게이트. finalize_plan이 띄우는 런타임 권한 프롬프트가 이 게이트를 대신하지 못한다 — 그 프롬프트는 경로만 보여주고 그 경로에 무엇이 들어가는지는 보여주지 않는다.
3. finalize_plan — 승인된 경로 집합(writes/deletes, 글롭 허용)과 읽기 소스 디렉토리(localDir)를 확정 → planId 반환. 권한 프롬프트 발생.
4. write_files (+ delete_files) — planId로 파일 업로드. 각 파일은 localPath(디스크에서 직접 읽어 업로드 — 내용이 컨텍스트에 유입되지 않음, 권장) 또는 소량 인라인 data. 콜당 최대 256개(초과 시 같은 planId로 분할).
5. register_assets (레거시) — Design System 카드는 이제 preview HTML 첫 줄 <!-- @dsCard group="…" --> 마커에서 자동 인덱싱(앱이 _ds_manifest.json으로 컴파일)되므로 명시 등록 불필요. @dsCard 마커가 없는 수기 프로젝트에서만 사용.