madsouris/sketch-design-from-reference

Sketch MCP to Design (Sketch MCP로 디자인하기)

참조와 일치하도록 Sketch 디자인을 구축하거나 개선합니다. 이 스킬은 Sketch에서 디자인 작업을 위한 것이며, 역방향 워크플로는 sketch-design-to-code입니다.

Fidelity first (정확성 우선)

목표는 참조와의 시각적 패리티(일치)입니다. 비슷한 섹션이 있는 그럴듯한 페이지가 아닙니다. '비슷함'은 완료가 아닙니다. 콘텐츠가 있을 때 멈추지 말고, 나란히 스크린샷 비교가 references/validation.md의 완료 기준을 통과할 때 멈추세요.

필수 Sketch 가이드

• get_guide with topic: "mcp" — 항상; MCP 전제 조건, run_code 규칙, 실패 처리 및 시각적 검증.
• get_guide with topic: "use" — Sketch 편집, 스택, 기호, 스타일, 재정의, 자산 및 프로토타이핑.
• get_guide with topic: "layout" — 프레임, 그룹, 스택 생성 또는 재구성 전; 페이지 배치, 크기 조정, 핀, 컨테이너 유형.

작업에 필요할 때마다 가이드 하위 주제를 요청하여 가져오세요: troubleshooting, layout, styling, symbols, assets, prototyping.

전제 조건

• Sketch가 MCP가 활성화된 상태로 실행 중이어야 함 (설정 → 일반 → AI 도구가 열린 문서와 상호 작용하도록 허용).
• 대상 문서가 열려 있거나, 사용자가 새 문서를 만들거나 사용할 것으로 예상해야 함.
• URL, 스크린샷 또는 소스 코드 형태의 참조가 있어야 함.
• 작업 범위가 충분히 명확해야 함: 전체 페이지 대 단일 프레임, 대상 너비, 다크/라이트 모드, 여러 후보가 있는 문서의 대상 페이지/프레임.

MCP를 사용할 수 없으면 중단하고 get_guide를 topic: "troubleshooting"로 호출하세요. MCP에 연결할 수 없는 동안 기억에 의존하여 레이아웃을 추측하지 마세요.

단계

다음 단계를 순서대로 따르세요. 일반적인 작업에는 기본 흐름으로 충분합니다. 단계에 더 많은 세부 정보나 예제가 필요할 때만 참조 파일을 로드하세요.

1단계 — 컨텍스트 및 참조 확인

1. 필수 가이드를 가져옵니다.
2. get_document_info로 대상 문서를 확인합니다.
3. 참조 유형을 분류합니다:
   • URL — 페이지 제목, 뷰포트 너비, DOM 구조, 소스 HTML, 연결되거나 번들로 제공된 JavaScript/CSS(가능한 경우), 계산된 색상/글꼴, 텍스트, 자산 URL을 수집합니다.
   • 스크린샷 — 크기, 영역, 텍스트 내용, 정렬, 주요 색상을 수집합니다.
   • 코드 — 테마 토큰, 글꼴 스택, 간격 척도, 컴포넌트 이름, 인라인 SVG, 자산 가져오기를 수집합니다.
4. 정확성 사양을 추출하고 레이아웃 변형 전에 대상 너비에서 참조 앵커 스크린샷을 캡처합니다. 사양에는 영역(위에서 아래로), 원본 텍스트, 색상, 타이포그래피, 레이아웃 너비, 자산 소스가 포함되어야 합니다. references/reference-extraction.md 참조.

참조별 추출은 references/reference-extraction.md를 읽으세요. 비교 및 완료 게이트는 5단계 전에 references/validation.md를 읽으세요.

2단계 — 재사용 가능한 Sketch 콘텐츠 발견

변형 전에 검사합니다. 읽기 전용 MCP 도구로 시작하세요:

1. get_document_info를 호출하여 페이지, 최상위 프레임/그래픽, 레이어 수, 기존 레이아웃 후보를 확인합니다.
2. 후보 프레임 또는 관련 페이지에서 get_layer_tree_summary를 호출하여 계층 구조, ID, 이름, 크기, 텍스트 조각, 심볼 인스턴스 재정의 개수, 스택 힌트를 확인합니다.
3. get_design_assets 및 get_libraries를 호출하여 재사용 가능한 심볼/컴포넌트와 라이브러리 자산을 확인합니다.
4. 요약이 필요한 세부 정보를 제공하지 않을 때만 대상 run_code를 사용합니다.

요청된 디자인에 매핑된다고 확신하는 경우에만 기존 프레임 편집을 선호하세요. 그렇지 않으면 새 프레임을 만드세요.

3단계 — 픽셀 전에 구조 계획

그리기 전에 레이어 계획을 정의하세요:

• 최상위 영역과 순서.
• 부모/자식 관계 및 형제 그룹.
• 영역 너비, 콘텐츠 최대 너비, 전체 너비 대 열 내 섹션.
• 고정/고정된 영역 대 스크롤 콘텐츠.
• 심볼 후보, 스택 후보, 자산 후보, 재사용 가능한 스택 패턴.

기본 페이지 템플릿을 강요하지 마세요. 참조의 정보 구조와 일치시키세요.

모든 구조화된 영역에 대해 그리기 전에 Sketch 스택 모델을 결정하세요: 방향, 간격, 패딩, 정렬, 크기 조정, 줄 바꿈, 의도된 시각적 순서. 영역이 자유 형식이어야 하는 특별한 이유가 없는 한, 행, 열, 탐색 모음, 툴바, 카드, 목록, 양식, 버튼 그룹 및 반복 콘텐츠에 스택을 사용하세요. 페이지 수준 배치, 고정된 크롬, 오버레이, 마스크 또는 진정한 자유 형식 아트워크에는 수동 좌표를 사용하세요.

4단계 — 토큰 및 기본 프레임 설정

배경, 테두리, 텍스트, 브랜드, 흐릿한 텍스트 및 중요한 표면에 대한 문서 견본/공유 스타일을 만들거나 일치시키세요. 페이지/프레임 배경을 의도적으로 설정하고 구조적 그룹에서 우발적인 채우기를 제거하세요. 심볼 세부 정보는 get_guide를 topic: "symbols"로 호출하세요.

참조의 값을 사용하세요: 계산된 CSS, 샘플링된 스크린샷 색상 또는 코드 토큰. 스타일링 세부 정보는 get_guide를 topic: "styling"로 호출하세요.

5단계 — 레이아웃을 점진적으로 구축

작고 되돌릴 수 있는 run_code 편집을 적용하세요. 하나의 스크립트는 하나의 작은 작업을 수행해야 합니다.

전체 페이지, 최상위 영역 또는 여러 섹션 레이아웃을 하나의 스크립트로 절대 구축하지 마세요. 프로빙, 생성, 스타일링 및 재정렬을 같은 실행에서 결합하지 마세요. 스크립트를 평평하게 유지하세요: 부트스트랩, ID로 대상 찾기, 하나의 변형 수행, JSON 로그. 깊은 헬퍼 함수, 중첩된 IIFE, 긴 제어 흐름 트리를 피하세요.

외부에서 내부로 구축하세요:

1. 페이지 프레임 및 배경.
2. 레이어 계획의 최상위 영역 컨테이너.
3. 세부 자식 전에 각 영역에 대한 스택 설정.
4. 각 영역 내부의 텍스트, 도형 및 심볼 인스턴스를 작은 형제 배치로.
5. 부모 구조가 올바른 후 고정/고정된 영역.

한 번에 하나의 최상위 영역을 구축하세요. 각 영역의 콘텐츠 배치 후:

1. 참조 앵커 너비에서 프레임의 get_screenshot을 캡처합니다.
2. 해당 영역 밴드를 참조 앵커와 비교합니다. references/validation.md의 분류를 사용하여 차이점을 나열합니다.
3. 다음 영역을 시작하기 전에 주요 불일치를 수정합니다.

구조적 편집 후 get_layer_tree_summary 또는 스크린샷으로 프레임을 다시 쿼리합니다. 안전한 재정렬/재부모 패턴은 references/editing-patterns.md를 읽으세요.

6단계 — 심볼, 자산 및 재정의

반복적인 일회성 레이어 그룹을 그리기 전에 기존 문서/라이브러리 심볼을 사용하세요. 반복되는 UI는 일반적으로 인스턴스와 재정의가 있는 하나의 심볼 마스터가 되어야 합니다.

세부 도형을 그리기 전에 각 비텍스트 시각적 요소를 분류하세요. 사진, 스크린샷, 일러스트레이션, 복잡한 SVG, 제품 이미지, 브랜드 마크, 세부 아이콘, 그라데이션 및 노이즈는 SVG/PNG/이미지 자산으로 내보내기/가져오세요. Sketch에서는 간단한 UI 기본 요소, 간단한 편집 가능한 벡터, 구분선, 알약 및 기본 도형만 다시 만드세요.

아이콘/로고/이미지의 경우 먼저 간단한 자리 표시자로 레이아웃을 설정한 다음, 형상과 스택 순서가 안정되면 실제 이미지 자산을 가져오거나 할당하세요. 반복되는 자산에는 전용 레이어에 심볼 이미지 재정의를 선호하세요.

심볼 재정의 패턴은 references/symbols.md를 읽으세요. 가져오기/내보내기 세부 정보는 get_guide를 topic: "assets"로 호출하세요.

7단계 — 대상 수정만

사용자가 문제를 보고하거나 스크린샷 비교가 불일치를 보여줄 때:

1. 변형 전에 get_layer_tree_summary 또는 대상 프로브로 현재 레이어를 검사합니다.
2. 보고된 속성만 변경합니다: 하나의 프레임 값, 텍스트 스타일, 색상, 레이어 순서, 스택 속성 또는 재정의.
3. 다시 스크린샷을 캡처하고 삭제가 의도적이지 않은 한 자식 수가 변경되지 않았는지 확인합니다.

레이아웃이 깨지거나 레이어가 손실되면 즉시 말하고 계속하기 전에 사용자에게 실행 취소/되돌리기를 요청하세요.

8단계 — 최종 검증 및 인계

완료 기준이 통과될 때까지 완료되었다고 말하지 마세요. references/validation.md → 완료 기준을 참조하세요.

1. 참조 앵커 너비에서 전체 프레임 get_screenshot을 캡처합니다.
2. 참조 앵커 스크린샷에 대해 정확성 사양의 모든 밴드에 대한 영역 게이트를 실행합니다.
3. 주요 차이가 남아 있으면 7단계로 돌아가 반복합니다. "거의 비슷한" 레이아웃으로 인계하지 마세요.
4. 사용된 심볼, 생성된 토큰/스타일, 대상 아트보드/프레임 이름 및 ID, 확인된 영역, 남아 있는 사소한 차이점을 요약합니다.
5. 작업이 완료될 때까지 zoomToFitCanvas를 실행하지 마세요.

규칙

Sketch → 디자인 방향별 규칙. 일반 MCP/스크립트 규칙은 get_guide with topic: "mcp"에서, Sketch 콘텐츠 규칙은 get_guide with topic: "use"에서 제공됩니다.

1. 재구축하지 말고 패치하세요. 콘텐츠가 있으면 주요 영역을 삭제하고 다시 만드는 대신 프레임, 스타일, 재정의 또는 순서를 수정하세요.
2. 재정렬, 재부모, 추가 또는 제거 작업 전후에 기본 자식 수를 확인하세요.
3. 절대 parent.layers = [...]를 할당하지 마세요. 재정렬에는 layer.index를, 재부모에는 child.parent = newParent를 사용하세요.
4. 참조의 영역 구조와 일치시키세요. 동일한 시각적 콘텐츠는 의도적으로 다른 이유가 없는 한 동일한 부모/형제 관계를 가져야 합니다.
5. 각 의미 있는 배치 후에 스크린샷을 캡처하고 스크린샷 차이점을 사용하여 다음 편집을 선택하세요.
6. 구조적 레이아웃은 기본적으로 스택을 사용합니다. 참조에서 형제가 flex, grid, 목록, 양식, 탐색 또는 카드 콘텐츠처럼 동작하면 모든 자식을 수동으로 배치하는 대신 Sketch 스택을 만들거나 유지하세요.
7. 자산은 자산입니다. 복잡한 아트워크, 사진, 스크린샷 또는 브랜드 마크를 저품질 벡터 근사치로 다시 그리지 마세요. 이미지/SVG 자산을 내보내기/가져오거나 할당하세요.
8. 추측하지 마세요. 기억이나 일반 UI 패턴에서 레이아웃, 텍스트, 색상, 간격 또는 자산을 만들지 마세요. 참조에서 추출하세요. 값이 누락되면 다시 가져오거나 사용자에게 물어보세요.
9. 항상 참조 앵커를 사용하세요. Sketch 출력을 페이지에 대한 기억이 아닌 캡처된 참조 스크린샷과 비교하세요.
10. 완료 게이트. 섹션이 있거나 페이지가 "비슷해 보인다"고 해서 멈추지 마세요. references/validation.md의 완료 기준이 통과될 때 멈추세요.

함정

• 작은 불일치를 수정하기 위해 페이지를 다시 만들면 조정된 작업이 낭비되고 새로운 버그가 발생합니다. 스크린샷 차이점에서 외과적인 편집을 하세요.
• 심볼 인스턴스에 이미지를 직접 배치하면 계층이 손상되거나 API에서 실패할 수 있습니다. 마스터에 이미지 레이어를 배치하고 인스턴스별 이미지 재정의를 구동하세요.
• 스크린샷을 건너뛰면 레이아웃, 순서 및 색상 오류가 숨겨집니다. 모든 배치마다 스크린샷을 캡처하세요.
• parent.layers = [...]로 재정렬하면 자식이 삭제되거나 개체 ID가 중복될 수 있습니다. 대신 안전한 재정렬 패턴을 사용하세요.
• 인덱스와 패킹 방향을 잘못 이해하면 스택 순서가 반전되어 보일 수 있습니다. get_guide with topic: "layout"를 사용하고 스크린샷으로 확인하세요.
• 전체 페이지 또는 영역 스크립트는 유효성 검사, 디버그 및 복구가 어렵습니다. 영역, 스택 설정 및 작은 형제 배치로 분할하세요.
• 수동 프레임으로 구축된 구조적 레이아웃은 간격이나 순서가 변경될 때 표류합니다. 행, 열, 목록, 양식, 탐색, 카드 및 반복 영역에는 Sketch 스택을 사용하세요.
• 기본 도형으로 재구축된 복잡한 아트워크는 저품질 근사치를 생성합니다. SVG/PNG를 내보내기/가져오거나 이미지 재정의를 사용하세요. 도형은 간단한 UI 기본 요소를 위해 남겨두세요.
• 첫 페인트 전용 페이지 스크린샷은 지연 로드 이미지 및 스크롤 트리거 UI 상태를 놓칠 수 있습니다. 브라우저 또는 에이전트 도구를 사용하고 스크롤하여 콘텐츠를 트리거한 다음 대상 뷰포트를 캡처하세요.
• 조기 완료: 에이전트가 일반 스타일링으로 헤더/본문/푸터를 추가하고 중지합니다. 영역 게이트 및 완료 기준을 실행하고 주요 차이가 사라질 때까지 계속 수정하세요.
• 즉석 텍스트 및 색상: 추출된 값 대신 의역된 제목, Lorem 스타일 채우기 또는 기본 회색/파란색. 정확성 사양을 그대로 사용하고 참조에서 색상을 다시 샘플링하세요.
• 자리 표시자 영구성: "로고" 또는 "히어로 이미지"로 남겨진 회색 상자. 사용자가 자리 표시자를 요청하지 않은 이상 인계 전에 실제 자산을 내보내기/가져오세요.

문제 해결

브리지/도구 호출 실패, 파서 오류, MCP 연결 문제 또는 스크린샷 실패의 경우 다시 시도하기 전에 get_guide를 topic: "troubleshooting"로 호출하세요.

문서 작업 실패의 경우:

• 레이아웃/스택/순서 문제 → get_guide with topic: "layout".
• 심볼 재정의 문제 → get_guide with topic: "symbols".
• 내보내기/가져오기/이미지 문제 → get_guide with topic: "assets".

디자인 구축 증상

• 스크립트 후 자식 수 감소: 사용자에게 실행 취소를 알린 다음 작업을 검사하세요. 대량 레이어 할당을 반복하지 마세요.
• get_screenshot이 비어 있거나 잘못됨: 프레임/레이어 ID를 다시 확인한 다음 필요한 경우 페이지 또는 부모 프레임을 스크린샷하세요.
• 심볼 재정의 효과 없음: get_symbol_overrides를 다시 가져오고 commonOverrideIDPrefix + '_' + property에서 재정의 ID를 재구축한 다음 스크린샷하세요.
• 행 스택에서 텍스트 겹침: 자식 순서와 간격을 검사하고 한 번에 하나의 스택 속성 또는 자식 인덱스를 수정하세요.

참조

• get_guide with topic: "mcp" — MCP 도구, run_code, 문제 해결, 시각적 검증 및 완료 규칙
• get_guide with topic: "use" — Sketch 편집, 스택, 심볼, 스타일, 재정의, 자산 및 콘텐츠 검증
• get_guide with topic: "layout" — 스택, 페이지 배치, 크기 조정, 핀, 컨테이너 유형, 재정렬/재부모 및 레이아웃 표류
• 참조 추출
• 안전한 편집 패턴
• 심볼 재정의 패턴
• 검증 루프
• Sketch JavaScript API
• StackLayout
• 심볼 재정의 (MCP에서 get_symbol_overrides로 확인)