디자인 시스템 동기화
개요
디자인 시스템이 이미 코드에 존재하는 경우, 디자인 도구는 이를 재발명하지 않고 반영해야 합니다.
- 가져오기(Import) 는 코드의 토큰과 사용자가 선택한 컴포넌트를 동일한 이름으로 도구에 가져옵니다.
- 내보내기(Export) 는 도구의 가이드에서 변경된 사항을 검토된 diff 형태로 코드에 다시 적용합니다.
프로젝트 루트에 있는 작은 파일 design-sync.json 이 마지막 동기화 상태를 기억합니다. 사용자가 달리 명시하지 않는 한 코드가 진실의 원천으로 유지됩니다. 변경 사항은 먼저 도구에서 그려지고, 승인된 내보내기를 통해 코드에 적용됩니다.
사용 시기
- 코드에 디자인 시스템이 있고 도구에 가이드가 없는 프로젝트에서 디자인 작업이 시작되려 할 때.
craft-setup과craft가 이 스킬로 전달합니다. - "디자인 시스템(토큰, 컴포넌트)을 Paper / Figma / 디자인 도구로 가져와 주세요."
- "가이드의 변경 사항을 코드에 적용/푸시/동기화 해주세요."
사용하지 말아야 할 경우
- 코드에 디자인 시스템이 없는 경우:
craft-system(생성 모드) 사용. - 해당 프로젝트의 검토, 옵션 또는 작은 수정: 그런 작업은 코드 그대로를 기준으로 하는 다른 스킬을 사용.
- 사용자가 말로 지시한 단일 토큰 값 ("accent를 코드에서 #3d7f69로 만들어"): 직접 수정하고, 해당 이름에 대해
design-sync.json을 업데이트하며, 영향을 받는 내용을 설명.
시작하기 전에
DESIGN.md(Brand 섹션에 시스템 위치 명시)와design-sync.json이 있으면 읽습니다.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항목만 변경합니다.
가져오기 (코드 → 디자인 도구)
-
감지 시그널을 사용합니다. 값의 진실 원천(생성된 출력이 아닌 토큰 소스)과 도구가 사용할 명명 규칙을 찾습니다. 두 개의 UI 패키지 → 둘 다 나열하고 어느 것이 소스인지 질문합니다.
-
인벤토리 작성 후 중단. 인벤토리 형식을 사용합니다:
- 역할별 토큰, 개수 및 경로 포함;
- 컴포넌트 (약 15개 이상이면 그룹화하여 개수 포함);
- 가이드라인 문서;
- 차이점(gaps);
- 충돌: 도구에 이미 존재하지만 값이 다른 이름, 도구가 보유할 수 없는 토큰 유형.
지금 그릴 컴포넌트를 선택하도록 요청하며, 다음 화면을 위해 3~6개를 제안하고 각 충돌을 해결할 방법을 묻습니다. 기본적으로 모든 것을 그리지 마십시오.
-
도구에 구축 답변을 받은 후:
- 명명 규칙에 따라 토큰을 등록합니다. 사용자가 해결하지 않은 도구 값을 덮어쓰지 마십시오;
- 파운데이션 가이드 페이지를 만들고 가이드라인 문서를 범례로 추가합니다;
- 컴포넌트 인덱스 생성: 이름, 코드 경로, 상태 (
drawn/in code only), 그려진 후에는 변형(variants) 채움; - 선택한 컴포넌트를 상태 매트릭스와 함께 그리고, 코드의 값을 사용합니다. 코드에 정의되지 않은 상태는 그려서 "제안됨(proposed)" 으로 표시합니다.
-
자체 점검. 가이드를 렌더링합니다. 코드가 해당 컴포넌트를 렌더링할 수 있으면(Storybook, 데모 페이지) 동일한 크기로 비교합니다. 그렇지 않으면 값이 코드에서 읽혀졌으며 렌더링되지 않았음을 명시합니다.
-
기록:
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은 코드에만 존재합니다. 먼저 가이드로 가져올까요?"
내보내기 (디자인 도구 → 코드)
-
읽기 가이드의 값(어댑터 사용)과 코드의 값을 이름별로 읽습니다.
-
모든 이름 분류
design-sync.json과 diff 형식을 사용하여:- 지금 동일 → 동기화됨;
- 가이드 변경됨 → 제안;
- 코드 변경됨 → 가이드 새로고침 제안;
- 둘 다 변경됨 → 세 값을 보여주고 어느 것이 승리할지 질문.
design-sync.json이 없으면 모든 차이점을 나열하고 각각에 대해 방향을 질문합니다. -
편집 제안 소스 파일에 대해 (생성된 출력이 아님): 파일과 라인, 각각이 영향을 미치는 내용, 색상의 대비(contrast)를 제시합니다. "제안됨" 상태와 대체 폰트는 내보낼 변경 사항이 아닙니다. 중단합니다.
-
적용 승인된 것만 적용하고, 코드 쪽으로 결정된 사항에 대해 가이드를 업데이트한 후 프로젝트의 검사를 실행합니다 (lint, typecheck, 테스트, 시각적 테스트). 또는 검사가 없음을 명시합니다.
-
기록:
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가 아주 작으니 그냥 적용하겠어" | 제안하고, 중단하고, 적용한 후 프로젝트 검사 실행 |