Communitygithub.com

craft-sync

디자인 시스템이 코드에 이미 존재할 때, 디자인 도구와 코드 간의 토큰 및 컴포넌트를 동기화합니다. (가져오기/내보내기)

craft-sync란 무엇인가요?

이 스킬은 코드 기반 디자인 시스템(UI 패키지, 디자인 토큰, 컴포넌트 라이브러리)을 디자인 도구(Paper, Figma 등)로 가져오거나, 도구에서 수정된 가이드를 코드로 다시 내보내는 양방향 동기화를 담당합니다. 프로젝트 루트의 `design-sync.json` 파일을 사용하여 마지막 동기화 상태를 기록하며, 코드를 항상 진실의 원천(source of truth)으로 유지합니다. 가져오기(Import) 시에는 먼저 인벤토리를 작성하고 충돌을 식별한 후 사용자가 선택한 컴포넌트만 그리며, 내보내기(Export) 시에는 차이점을 제안하고 사용자의 승인을 받은 후에만 코드에 적용하고 프로젝트 검사를 실행합니다. 주로 Claude Code, Cursor, Codex 등의 AI 에이전트 환경에서 `craft` 또는 `craft-setup` 스킬과 연동되어 사용됩니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/diego3g/craft/tree/HEAD/skills/craft-sync

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

디자인 시스템 동기화

개요

디자인 시스템이 이미 코드에 존재하는 경우, 디자인 도구는 이를 재발명하지 않고 반영해야 합니다.

  • 가져오기(Import) 는 코드의 토큰과 사용자가 선택한 컴포넌트를 동일한 이름으로 도구에 가져옵니다.
  • 내보내기(Export) 는 도구의 가이드에서 변경된 사항을 검토된 diff 형태로 코드에 다시 적용합니다.

프로젝트 루트에 있는 작은 파일 design-sync.json 이 마지막 동기화 상태를 기억합니다. 사용자가 달리 명시하지 않는 한 코드가 진실의 원천으로 유지됩니다. 변경 사항은 먼저 도구에서 그려지고, 승인된 내보내기를 통해 코드에 적용됩니다.

사용 시기

  • 코드에 디자인 시스템이 있고 도구에 가이드가 없는 프로젝트에서 디자인 작업이 시작되려 할 때. craft-setup 과 craft 가 이 스킬로 전달합니다.
  • "디자인 시스템(토큰, 컴포넌트)을 Paper / Figma / 디자인 도구로 가져와 주세요."
  • "가이드의 변경 사항을 코드에 적용/푸시/동기화 해주세요."

사용하지 말아야 할 경우

  • 코드에 디자인 시스템이 없는 경우: craft-system (생성 모드) 사용.
  • 해당 프로젝트의 검토, 옵션 또는 작은 수정: 그런 작업은 코드 그대로를 기준으로 하는 다른 스킬을 사용.
  • 사용자가 말로 지시한 단일 토큰 값 ("accent를 코드에서 #3d7f69로 만들어"): 직접 수정하고, 해당 이름에 대해 design-sync.json을 업데이트하며, 영향을 받는 내용을 설명.

시작하기 전에

  1. DESIGN.md (Brand 섹션에 시스템 위치 명시)와 design-sync.json이 있으면 읽습니다.
  2. references/adapters/ 에서 도구에 맞는 어댑터를 선택합니다(paper.md, figma.md, html.md). 일치하는 어댑터가 없으면 동일한 동사를 도구에 맞게 수행하고 수동으로 매핑했음을 명시합니다. 디자인 도구가 전혀 없으면 HTML(html.md)로 구축합니다. 이미지만 있는 경우, 이미지에서 읽은 값은 추정치임을 명시합니다.

design-sync.json

{
  "source": "packages/ui/tokens.css",
  "tool": "paper: file 'Fieldnote', page 'Guide'",
  "naming": "CSS 사용자 정의 속성 이름을 소스에 작성된 그대로 사용",
  "synced": "2026-11-15",
  "tokens": { "--color-accent": "#2e6b57", "--radius-md": "10px" },
  "components": { "Button": "drawn", "Badge": "drawn", "Input": "in code only" }
}
  • tokens 는 마지막 동기화 시점에 양측이 합의한 값만 저장합니다.
  • 컴포넌트 가져오기는 해당 컴포넌트의 components 항목만 변경합니다.

가져오기 (코드 → 디자인 도구)

  1. 감지 시그널을 사용합니다. 값의 진실 원천(생성된 출력이 아닌 토큰 소스)과 도구가 사용할 명명 규칙을 찾습니다. 두 개의 UI 패키지 → 둘 다 나열하고 어느 것이 소스인지 질문합니다.

  2. 인벤토리 작성 후 중단. 인벤토리 형식을 사용합니다:

    • 역할별 토큰, 개수 및 경로 포함;
    • 컴포넌트 (약 15개 이상이면 그룹화하여 개수 포함);
    • 가이드라인 문서;
    • 차이점(gaps);
    • 충돌: 도구에 이미 존재하지만 값이 다른 이름, 도구가 보유할 수 없는 토큰 유형.

    지금 그릴 컴포넌트를 선택하도록 요청하며, 다음 화면을 위해 3~6개를 제안하고 각 충돌을 해결할 방법을 묻습니다. 기본적으로 모든 것을 그리지 마십시오.

  3. 도구에 구축 답변을 받은 후:

    • 명명 규칙에 따라 토큰을 등록합니다. 사용자가 해결하지 않은 도구 값을 덮어쓰지 마십시오;
    • 파운데이션 가이드 페이지를 만들고 가이드라인 문서를 범례로 추가합니다;
    • 컴포넌트 인덱스 생성: 이름, 코드 경로, 상태 (drawn / in code only), 그려진 후에는 변형(variants) 채움;
    • 선택한 컴포넌트를 상태 매트릭스와 함께 그리고, 코드의 값을 사용합니다. 코드에 정의되지 않은 상태는 그려서 "제안됨(proposed)" 으로 표시합니다.
  4. 자체 점검. 가이드를 렌더링합니다. 코드가 해당 컴포넌트를 렌더링할 수 있으면(Storybook, 데모 페이지) 동일한 크기로 비교합니다. 그렇지 않으면 값이 코드에서 읽혀졌으며 렌더링되지 않았음을 명시합니다.

  5. 기록:

    • design-sync.json 작성 (모든 토큰 값이 양측에서 동일해지고, 컴포넌트 상태 포함);
    • DESIGN.md에서 Brand 섹션에 "디자인 시스템 소스: <경로>; <도구> 가이드가 이를 반영함"을 추가하고, 결정 로그(Decisions log)에 날짜가 있는 가져오기 라인을 추가;
    • DESIGN.md가 없으면 첫 줄이 <!-- sync record only: run craft-setup for the brief --> 이고 Brand와 결정 로그만 있는 파일을 생성합니다. craft는 Product 섹션이 없는 DESIGN.md를 없는 것으로 간주합니다.

단일 컴포넌트 가져오기 (craft 에서)

사용자가 이미 시스템을 미러링하는 데 동의했으므로 인벤토리 중단이 없습니다:

  • 해당 컴포넌트를 그림;
  • components 항목을 drawn으로 설정;
  • tokens는 그대로 둠.

도구에 아직 가이드가 없거나 사용자가 가져오기에 동의한 적이 없거나(또는 거부한 경우), 한 번 질문합니다: "Input은 코드에만 존재합니다. 먼저 가이드로 가져올까요?"

내보내기 (디자인 도구 → 코드)

  1. 읽기 가이드의 값(어댑터 사용)과 코드의 값을 이름별로 읽습니다.

  2. 모든 이름 분류 design-sync.json과 diff 형식을 사용하여:

    • 지금 동일 → 동기화됨;
    • 가이드 변경됨 → 제안;
    • 코드 변경됨 → 가이드 새로고침 제안;
    • 둘 다 변경됨 → 세 값을 보여주고 어느 것이 승리할지 질문.

    design-sync.json이 없으면 모든 차이점을 나열하고 각각에 대해 방향을 질문합니다.

  3. 편집 제안 소스 파일에 대해 (생성된 출력이 아님): 파일과 라인, 각각이 영향을 미치는 내용, 색상의 대비(contrast)를 제시합니다. "제안됨" 상태와 대체 폰트는 내보낼 변경 사항이 아닙니다. 중단합니다.

  4. 적용 승인된 것만 적용하고, 코드 쪽으로 결정된 사항에 대해 가이드를 업데이트한 후 프로젝트의 검사를 실행합니다 (lint, typecheck, 테스트, 시각적 테스트). 또는 검사가 없음을 명시합니다.

  5. 기록:

    • design-sync.json을 업데이트하여 양측의 값이 동일해지도록 함;
    • DESIGN.md › 결정 로그(Decisions log)에 날짜가 있는 라인 추가;
    • 해결되지 않은 충돌을 열린 질문(Open questions)에 추가.

규칙

규칙이유
코드와 도구에서 하나의 작성된 명명 규칙으로 동일한 이름 사용결정당 하나의 이름; 표류할 매핑 없음
design-sync.json은 합의된 값만 기록마지막 합의 값이 없으면 "누가 변경했는지" 추측에 불과
그리기 전에 인벤토리 작성 및 선택; 충돌은 거기에 나열큰 패키지와 기존 도구 토큰은 사용자의 의견이 필요
코드에서 값 가져오기, 스크린샷에서 가져오지 않음스크린샷은 색상과 크기를 반올림함
누락된 상태는 "제안됨"으로 그리기가이드는 코드가 하지 않는 일을 한다고 주장해서는 안 됨
내보내기는 제안 후 중단; 소스 편집, 생성된 출력 아님코드는 사용자에게 제공됨; 생성된 파일은 다음 빌드에서 덮어쓰여짐
둘 다 변경됨 → 질문어느 한쪽을 덮어쓰면 누군가의 결정이 손실됨
사용자가 달리 명시하지 않는 한 코드가 진실의 원천"코드가 오래된 브리핑을 이긴다" 원칙과 일치

완료 조건

  • 가져오기: 인벤토리 및 충돌 해결됨; 선택된 컴포넌트가 그려짐; 가이드가 렌더링됨(또는 "렌더링되지 않음" 명시); design-sync.json 및 DESIGN.md 작성됨.
  • 단일 컴포넌트: 그려지고, 상태가 업데이트됨.
  • 내보내기: 승인된 편집이 적용되고, 검사가 실행됨(또는 "없음" 명시), design-sync.json이 업데이트되고, 충돌이 결정되거나 열려 있음.

일반적인 실수

생각현실
"코드에 시스템이 있으니 설정은 브리핑만 있으면 돼"가져오기를 제안하지 않으면 도구는 가이드를 갖지 못하고 화면이 코드에서 멀어짐
"파운데이션과 인덱스를 먼저 만들고, 컴포넌트는 나중에"인벤토리를 보여주고 지금 그릴 컴포넌트를 선택하도록 요청
"가져올 때 --sand-200을 역할 이름으로 바꾸겠어"코드의 이름을 유지하고, 역할은 열린 질문으로 제안
"도구에 이미 --color-accent가 있는데, 업데이트하겠어"이는 인벤토리 중단 시 처리할 충돌이지, 조용히 덮어쓸 사항이 아님
"가이드와 코드가 다르니 가이드가 오래된 거야"design-sync.json을 확인: 사용자가 내보내지 않은 변경일 수 있음
"diff가 아주 작으니 그냥 적용하겠어"제안하고, 중단하고, 적용한 후 프로젝트 검사 실행

Individual skills in this repo

This repo contains 2 individual skills — each has its own dedicated page.

관련 스킬