Google Stitch UI 프로토타이핑 및 변형 스킬 (stitch-design)
이 스킬은 기존 컴포넌트 설계 사양(design-spec.md)을 사용하여 Google Stitch(StitchMCP) 를 통해 화면 레이아웃을 스캐폴딩하고, 공간 변형을 생성하며, 고해상도 시각 자산(JPG 스크린샷 및 원시 HTML 내보내기)을 코드베이스에 다운로드하고, 구체적인 레이아웃 벤치마크로 설계 사양을 업데이트하는 전체 워크플로우를 정의합니다.
[!IMPORTANT] 입력 사전 조건: 이 스킬을 사용하려면
docs/design/components/[page name]/[component name]/design-spec.md에 완성된 설계 사양이 필요합니다(일반적으로component-design에 의해 생성됨). 사양이 없으면 먼저/component-design을 실행하세요.
[!CAUTION] 바이너리 다운로드 안전 규칙: Stitch JPG 스크린샷이나 HTML 내보내기를 다운로드할 때
read_url_content를 절대 사용하지 마세요.read_url_content는 텍스트 전용이며 응답을 마크다운으로 변환하여 바이너리 이미지를 손상시키고 HTML 구조를 망가뜨립니다. 모든 다운로드는run_command와 PowerShellInvoke-WebRequest -Uri <url> -OutFile <path>를 사용해야 합니다. 서명된 다운로드 URL은 빠르게 만료되므로 Stitch 응답을 받는 즉시 다운로드하세요.
[!TIP] 스킬 내 이미지 생성 금지 (토큰 보존 규칙): 토큰을 보존하기 위해 이 스킬은
generate_image를 직접 호출해서는 안 됩니다. 화면에 사용자 정의 배경 이미지, 일러스트레이션 또는 아이콘이 필요한 경우, 구조화된 프롬프트를 사용자에게 출력하여 프로젝트 파일에 생성하고 배치할 수 있도록 안내하세요.
1. 핵심 산출물 및 워크플로우 개요
flowchart TD
Start["/stitch-design 호출<br/>(대상: docs/design/components/[page]/[component]/design-spec.md)"] --> Step1["단계 1: 설계 사양 읽기<br/>(design-spec.md 및 docs/project.json 읽기)"]
Step1 --> Step2["단계 2: Stitch 프로젝트 유지 및 토큰 시드<br/>(docs/project.json에서 stitch.project_id 확인/재사용, 디자인 시스템 시드)"]
Step2 --> Step3["단계 3: StitchMCP를 통한 화면 및 변형 생성<br/>(generate_screen_from_text + 1개 변형에 대한 generate_variants)"]
Step3 --> Step4["단계 4: 바이너리 안전 자산 다운로드<br/>(PowerShell Invoke-WebRequest → stitch/screen.jpg, screen.html, variant-1.jpg, variant-1.html)"]
Step4 --> Step5["단계 5: 설계 사양 벤치마크 통합<br/>(stitch/screen.jpg 및 변형 벤치마크를 design-spec.md에 포함)"]
Step5 --> Step6["단계 6: 독립 하위 에이전트 검증<br/>(invoke_subagent가 파일 크기, 메타데이터 및 사양 일치 확인)"]
Step6 --> Finish["시각적 프로토타입 준비<br/>(Stitch JPG + HTML이 코드베이스에 저장됨)"]
산출물: Stitch 자산 하위 폴더
각 Stitch 실행은 컴포넌트의 디자인 디렉토리 내에 stitch/ 하위 폴더를 생성하거나 채웁니다:
docs/design/components/[page name]/[component name]/
├── design-spec.md # Stitch 벤치마크 및 포함된 스크린샷으로 업데이트됨
└── stitch/ # 다운로드된 Google Stitch 디자인 파일
├── screen.jpg # Stitch로 생성된 기본 화면 JPG 스크린샷
├── screen.html # Stitch로 생성된 기본 화면 원시 HTML 내보내기
├── variant-1.jpg # Stitch로 생성된 변형 JPG 스크린샷
├── variant-1.html # Stitch로 생성된 변형 원시 HTML 내보내기
└── stitch-meta.json # Stitch 프로젝트 ID, 화면 ID, 변형 ID 및 생성 프롬프트
2. 단계별 실행 워크플로우
단계 1: 설계 사양 및 프로젝트 컨텍스트 읽기
- 대상 컴포넌트 찾기:
- 컴포넌트 경로 식별:
docs/design/components/[page name]/[component name]/. design-spec.md를 읽어 다음 정보 추출:- 요약, 사용자 페르소나 및 감정적 톤.
- 시각적 계층 구조(1차, 2차, 3차 초점).
- 레이아웃 그리드 및 중단점 동작.
- 디자인 토큰(색상, 반경, 입체감).
- 로케일별 타이포그래피 페어링.
- 컴포넌트 경로 식별:
- 프로젝트 컨텍스트 읽기:
docs/project.json을 읽어 표준 디자인 시스템을 확인하고 기존 Stitch 구성을 확인합니다.
단계 2: Google Stitch 프로젝트 유지 및 디자인 시스템 시드 (StitchMCP)
[!IMPORTANT] 저장소당 단일 프로젝트 규칙 (중복 프로젝트 금지): 모든 저장소는 모든 컴포넌트 및 화면 디자인에 대해 정확히 하나의 공유 Google Stitch 프로젝트 컨테이너를 유지해야 합니다. 동일한 저장소에 대해 여러 Stitch 프로젝트를 절대 생성하지 마세요.
- 먼저
docs/project.json확인:docs/project.json에서project_id가 있는 기존"stitch"객체 검사.
- 기존 프로젝트 재사용:
stitch.project_id가 존재하는 경우, 모든 화면 스캐폴딩, 변형 및 디자인 시스템 업데이트에 해당projectId를 항상 재사용하세요.create_project를 호출하지 마세요.
- 생성 후 즉시 저장 (없는 경우에만):
docs/project.json에stitch.project_id가 없는 경우:StitchMCP에서call_mcp_tool을list_projects와 함께 호출하여 저장소 제목과 일치하는 프로젝트가 이미 있는지 확인합니다.- 없으면
title: "[Project Title] Design System & Components"로create_project를 호출합니다. - 프로젝트 속성을 즉시
docs/project.json의"stitch"아래에 저장합니다:"stitch": { "project_id": "<projectId>", "project_name": "projects/<projectId>", "title": "<title>" }
- 디자인 토큰 시드:
- Stitch에
upload_design_md또는create_design_system_from_design_md를 통해 프로젝트의 표준 디자인 시스템(docs/project.json에서)을 제공하여 글로벌 색상, 글꼴 및 반경 일관성을 확립합니다.
- Stitch에
단계 3: StitchMCP를 통한 화면 및 변형 생성
- 상세 디자인 프롬프트 합성:
design-spec.md의 컴포넌트 목적, 사용자 페르소나, 감정적 톤 및 레이아웃 요구 사항을 결합합니다.docs/project.json에서 시각적 토큰을 명시적으로 지정: 배경 캔버스, 표면 카드, 기본 강조, 보조 강조, 상태 색상 및 타이포그래피.- 대상 뷰포트 지정:
deviceType: "DESKTOP"(또는 모바일 우선 컴포넌트를 대상으로 하는 경우"MOBILE"/"TABLET").
- 기본 화면 생성:
StitchMCP에서generate_screen_from_text호출:projectId: 활성 Stitch 프로젝트 ID.prompt: 합성된 디자인 프롬프트.deviceType:"DESKTOP".
- 생성된 화면 ID 및 리소스 이름(형식:
projects/{projectId}/screens/{screenId}) 추출.
- 하나의 변형 생성:
- 생성된 화면 ID를 사용하여
StitchMCP에서generate_variants를 호출하여 설계 사양 파일의 공간적/시각적 변형을 하나 생성합니다(예: 대체 레이아웃 밀도, 카드 대 전체 너비, 비대칭 시각적 흐름 탐색). - 변형 화면 ID를 기록합니다.
- 생성된 화면 ID를 사용하여
단계 4: 바이너리 안전 자산 다운로드 프로토콜
[!CAUTION] PowerShell
Invoke-WebRequest필수: 각 다운로드 명령을 개별 단일 작업으로 실행하세요. 각 다운로드 파일의 바이트 크기가 0이 아닌지 확인하세요(JPG의 경우 > 10KB).
- 디렉토리 존재 확인:
- 대상 디렉토리:
docs/design/components/[page name]/[component name]/stitch/.
- 대상 디렉토리:
- 기본 화면 JPG 다운로드:
- 기본 화면 응답에서
screenshot.downloadUrl추출. - 실행:
powershell -Command "Invoke-WebRequest -Uri '<screenshot.downloadUrl>' -OutFile 'docs/design/components/[page]/[component]/stitch/screen.jpg'"
- 기본 화면 응답에서
- 기본 화면 HTML 다운로드:
- 기본 화면 응답에서
htmlCode.downloadUrl추출. - 실행:
powershell -Command "Invoke-WebRequest -Uri '<htmlCode.downloadUrl>' -OutFile 'docs/design/components/[page]/[component]/stitch/screen.html'"
- 기본 화면 응답에서
- 변형-1 JPG 다운로드:
- 변형 응답에서
screenshot.downloadUrl추출. - 실행:
powershell -Command "Invoke-WebRequest -Uri '<variant.screenshot.downloadUrl>' -OutFile 'docs/design/components/[page]/[component]/stitch/variant-1.jpg'"
- 변형 응답에서
- 변형-1 HTML 다운로드:
- 변형 응답에서
htmlCode.downloadUrl추출. - 실행:
powershell -Command "Invoke-WebRequest -Uri '<variant.htmlCode.downloadUrl>' -OutFile 'docs/design/components/[page]/[component]/stitch/variant-1.html'"
- 변형 응답에서
- Stitch 메타데이터 저장 (
stitch-meta.json):docs/design/components/[page]/[component]/stitch/stitch-meta.json작성:{ "projectId": "<stitchProjectId>", "screenId": "<screenId>", "screenName": "projects/<projectId>/screens/<screenId>", "deviceType": "DESKTOP", "generationPrompt": "<synthesizedPrompt>", "variantIds": ["<variantScreenId1>"] }
단계 5: 설계 사양 벤치마크 통합
Stitch 결과로 docs/design/components/[page name]/[component name]/design-spec.md 업데이트:
- Stitch 기본 화면 및 변형 포함:
## Google Stitch 레이아웃 아키텍처 및 벤치마크 ### 기본 화면 디자인  ### 변형 1 탐색  - 레이아웃 아키텍처 관찰 내용 문서화:
- Stitch 화면에서 보여주는 공간 그리드, 시각적 무게, 여백 리듬 및 타이포그래피 계층 구조를 기록합니다.
- 기본 화면과 변형 1을 비교하여 각 구성의 장점을 강조합니다.
단계 6: 시각적 자산 프롬프트 (해당하는 경우)
[!NOTE] Stitch 레이아웃을 검사한 결과 맞춤형 시각 자산(예: 앰비언트 배경, 사용자 정의 아이콘 또는 다이어그램)이 필요한 것으로 확인되면,
generate_image를 호출하지 마세요. 대신 구조화된 프롬프트를 사용자에게 출력하세요:
### 권장 시각 자산: [자산 이름]
- **대상 파일 경로:** `docs/design/components/[page]/[component]/[filename].png`
- **권장 종횡비:** `16:9` 또는 `1:1`
- **생성 프롬프트:**
> "[Stitch 레이아웃과 일치하는 시각 자산을 설명하는 상세 프롬프트]"
단계 7: 독립 하위 에이전트 검증 루프 (invoke_subagent)
[!IMPORTANT] 하위 에이전트 검토 프로토콜: 완료를 보고하기 전에 항상 독립 하위 에이전트를 통해 다운로드된 자산과 사양 업데이트를 검증하세요.
1. 검증 하위 에이전트 생성
invoke_subagent 호출:
TypeName:"self"Role:"Stitch 자산 및 다운로드 감사"Model:"inherit"Prompt:
당신은 독립적인 Stitch 자산 감사관입니다. Google Stitch 자산이 깨끗하게 다운로드되어 컴포넌트 디렉토리에 통합되었는지 확인하는 것이 임무입니다.
대상 컴포넌트 디렉토리:
docs/design/components/[page name]/[component name]/
감사 대상 산출물:
1. docs/design/components/[page name]/[component name]/stitch/screen.jpg (존재해야 하며, 바이트가 0이 아니어야 함)
2. docs/design/components/[page name]/[component name]/stitch/screen.html (존재해야 하며, 원시 HTML이어야 함)
3. docs/design/components/[page name]/[component name]/stitch/variant-1.jpg (존재해야 하며, 바이트가 0이 아니어야 함)
4. docs/design/components/[page name]/[component name]/stitch/variant-1.html (존재해야 하며, 원시 HTML이어야 함)
5. docs/design/components/[page name]/[component name]/stitch/stitch-meta.json (projectId, screenId, generationPrompt, variantIds를 포함하는 유효한 JSON)
6. docs/design/components/[page name]/[component name]/design-spec.md (stitch/screen.jpg 및 stitch/variant-1.jpg를 포함해야 함)
다음 엄격한 기준에 따라 감사:
1. 바이너리 파일 무결성: screen.jpg 및 variant-1.jpg가 비어 있거나 손상되지 않았는지 확인(크기 > 10KB).
2. HTML 무결성: screen.html 및 variant-1.html이 유효한 HTML 파일이고 손상된 마크다운이 아닌지 확인.
3. 메타데이터 무결성: stitch-meta.json에 유효한 필드가 있는지 확인.
4. 사양 통합: design-spec.md에 포함된 스크린샷 링크와 Stitch 레이아웃 벤치마크 노트가 있는지 확인.
5. 토큰 보존: generate_image가 직접 호출되지 않았는지 확인.
정확히 다음 형식으로 응답:
VERDICT: PASS | ISSUES_FOUND
ISSUES (있는 경우):
- LOCATION: {file:line or section}
- PROBLEM: {비준수 또는 손상된 내용}
- FIX: {수정하기 위한 구체적인 지침}
SUMMARY: {간단한 전체 평가}
2. 검토 평가 및 해결
ISSUES_FOUND가 발견되면, 실행을 완료하기 전에 즉시 해결하세요(예: 실패한 자산 재다운로드 또는 메타데이터 수정).
3. 실행 확인 체크리스트
실행을 완료하기 전에 다음을 확인하세요:
-
design-spec.md가docs/design/components/[page]/[component]/에서 읽혔습니다. - Stitch 프로젝트 ID가
docs/project.json에서 확인/재사용되었거나(또는 생성되어 즉시 저장됨). - 디자인 토큰이
upload_design_md또는create_design_system_from_design_md를 통해 Stitch에 시드되었습니다. -
generate_screen_from_text를 통해 기본 화면이 생성되었습니다. -
generate_variants를 통해 정확히 하나의 변형이 생성되었습니다. - 모든 자산이 PowerShell
Invoke-WebRequest -OutFile을 사용하여 다운로드되었습니다(read_url_content사용 없음). -
screen.jpg,screen.html,variant-1.jpg,variant-1.html이stitch/에 0이 아닌 크기로 저장되었습니다. -
stitch/stitch-meta.json이 완전한 메타데이터와 함께 저장되었습니다. -
design-spec.md가 포함된 스크린샷과 Stitch 레이아웃 벤치마크로 업데이트되었습니다. -
generate_image가 직접 호출되지 않았으며, 필요한 경우 이미지 프롬프트가 사용자에게 출력되었습니다. - 독립 하위 에이전트 감사가
invoke_subagent를 통해 호출되어 통과했습니다.