@su-record/vibe 2.8.11 → 2.8.12

package/commands/vibe.figma.md

@@ -5,76 +5,84 @@ argument-hint: ""
 
 # /vibe.figma
 
-Figma 디자인 + 스토리보드 → 프로덕션 코드. 인터랙티브 방식으로 URL을 입력받아 처리.
+Figma 디자인 + 스토리보드 → 프로덕션 코드. **뷰포트별 점진적 빌드** 방식.
 
 ## Usage
 
 ```
-/vibe.figma                  # 인터랙티브 모드 (URL 입력 프롬프트)
+/vibe.figma                  # 인터랙티브 모드 (단계별 URL 입력)
 /vibe.figma --new            # 새 피처 모드 (기존 디자인 시스템 무시)
 /vibe.figma --refine         # 보완 모드 (기존 코드 + Figma 재비교 → 수정)
 ```
 
-커맨드 실행 시 아래 순서로 사용자에게 질문:
+## Incremental Build Flow (핵심 플로우)
 
-```
-1. 📋 스토리보드 URL이 있나요? (선택)
-   → 브레이크포인트, 인터랙션, 애니메이션 스펙 추출
-   → 없으면 Enter (디폴트 브레이크포인트 사용)
+한번에 전체를 만들지 않고, **뷰포트별로 점진적으로 쌓아가는 방식**:
 
-2. 🎨 디자인 URL을 입력해주세요. (필수, 복수 가능)
-   → 1개: 단일 디자인
-   → 2개 이상: 반응형 (프레임 width로 mobile/desktop 자동 감지)
-   → 각 URL은 줄바꿈 또는 공백으로 구분
+```
+Step A: 스토리보드 URL 입력
+  → 브레이크포인트, 인터랙션, 스펙 추출
+  → base 레이아웃 & 컴포넌트 구조 설계 + 파일 생성
+        ↓
+Step B: 모바일 디자인 URL 입력
+  → 모바일 스타일 반영, 이미지 추출
+  → 컴포넌트 리팩토링 (모바일 기준)
+  → 🔄 검증 루프 (Figma vs 코드 비교, P1=0까지)
+        ↓
+Step C: PC 디자인 URL 입력
+  → PC 스타일 반영 (반응형 clamp/breakpoint 추가)
+  → 이미지 추출 (PC용 에셋)
+  → 컴포넌트 리팩토링 (PC 대응)
+  → 🔄 검증 루프 (Figma vs 코드 비교, P1=0까지)
+        ↓
+Step D: 최종 공통화 리팩토링
+  → 모바일/PC 스타일 공통 토큰 추출
+  → 중복 코드 통합
+  → 유사 컴포넌트 variant 통합 (80% rule)
+  → 🔄 최종 검증 루프 (양쪽 뷰포트 동시 검증)
 ```
 
-### 입력 예시
+### 단계별 URL 입력 (AskUserQuestion — options 사용 금지, 자유 텍스트만)
 
 ```
-📋 스토리보드 URL (선택, 없으면 Enter):
-> https://www.figma.com/design/ABC/Storyboard?node-id=1-109
+각 Step에서 AskUserQuestion으로 하나씩 입력:
+  ⚠️ 절대 선택지(options)를 제공하지 않는다. 순수 텍스트 입력만.
+  ⚠️ 각 질문의 응답을 받은 후에만 다음으로 진행.
+
+Step A: "📋 스토리보드 Figma URL을 입력해주세요. (없으면 '없음')"
+  → ⏸️ 응답 대기
+  → URL 또는 "없음"
+
+Step B: "📱 모바일 디자인 Figma URL을 입력해주세요."
+  → ⏸️ 응답 대기
+  → URL 저장 + 추출 + 스타일 반영 + 검증
 
-🎨 디자인 URL (필수, 복수 시 줄바꿈):
-> https://www.figma.com/design/ABC/Design?node-id=10-200
-> https://www.figma.com/design/ABC/Design?node-id=10-500
+Step C: "🖥️ PC 디자인 Figma URL을 입력해주세요. (없으면 '없음')"
+  → ⏸️ 응답 대기
+  → URL 또는 "없음" (없으면 single viewport mode)
+
+디자인 URL이 1개만이면: 단일 뷰포트 (Step B만 실행, Step C 스킵)
+디자인 URL이 2개이면: 반응형 (Step B + C + D)
 ```
 
-### Generation Mode
+### Mode
 
 | Mode | 조건 | 동작 |
 |------|------|------|
 | **Project integration** | 기본값 | 기존 디자인 시스템/토큰 활용, 프로젝트 컨벤션 준수 |
 | **--new** | 플래그 지정 시 | 자체 완결 토큰 + 컴포넌트, 기존 디자인 시스템 무관 |
-| **--refine** | 플래그 지정 시 | 기존 생성 코드를 Figma 원본과 재비교하여 부족한 부분만 수정 |
-| **Responsive** | 디자인 URL 2개 이상 | 자동 감지, fluid clamp() + @media 생성 |
+| **--refine** | 플래그 지정 시 | 기존 코드를 Figma 재비교 → 부족한 부분만 수정 |
 
 ### 스토리보드에서 추출하는 정보
 
-| 항목 | 활용 Phase |
-|------|-----------|
-| 브레이크포인트 / 해상도 가이드 | Phase 3 (breakpoints 오버라이드) |
-| 인터랙션 스펙 (호버, 클릭, 스크롤) | Phase 6 (이벤트 핸들러 + CSS states) |
-| 애니메이션 스펙 (타이밍, 이징) | Phase 6 (transition/animation) |
-| 상태별 UI (로딩, 에러, 성공, 빈 상태) | Phase 6 (조건부 렌더링) |
-| 반응형 동작 설명 | Phase 6-3 (responsive 코드) |
-| 컬러/타이포 가이드 | Phase 4 (토큰 생성) |
-| 컴포넌트 명세 | Phase 5 (마크업 구조) |
-
-### File Reading Policy
-
-**스토리보드 있을 때:**
-1. 스토리보드 `get_metadata` → 전체 프레임 목록 파악
-2. 관련 섹션별 `get_design_context` → 스펙 정보 추출
-3. 디자인 URL별 `get_design_context` + `get_screenshot` → 비주얼 + 코드
-
-**스토리보드 없을 때:**
-1. 디자인 URL별 `get_design_context` + `get_screenshot` → 비주얼 + 코드
-2. 디폴트 브레이크포인트 적용
-
-**항상:**
-- `.claude/vibe/config.json` → 프로젝트 스택
-- `.claude/vibe/design-context.json` → 브랜드, 토큰, 테마
-- 기존 코드 스캔 → 컴포넌트 패턴, 디자인 시스템
+| 항목 | 활용 |
+|------|------|
+| 브레이크포인트 / 해상도 가이드 | base 레이아웃 설계 |
+| 인터랙션 스펙 (호버, 클릭, 스크롤) | 이벤트 핸들러 + CSS states |
+| 애니메이션 스펙 (타이밍, 이징) | transition/animation |
+| 상태별 UI (로딩, 에러, 성공) | 조건부 렌더링 |
+| 반응형 동작 설명 | responsive 코드 |
+| 컬러/타이포 가이드 | 토큰 생성 |
 
 ## Context Reset
 
@@ -88,16 +96,17 @@ Figma 디자인 + 스토리보드 → 프로덕션 코드. 인터랙티브 방
 
 ## Model Routing
 
-| Phase | Claude | GPT (Codex) | 이유 |
-|-------|--------|-------------|------|
-| Phase 0 (추출) | **Haiku** | — | MCP 호출 + 데이터 수집 |
-| Phase 1-2 (분석) | **Sonnet** | — | 이미지 비교 + 구조 파악 |
-| Phase 3 (감지) | **Haiku** | — | 파일 읽기 + 패턴 매칭 |
-| Phase 4-5 (토큰/마크업) | **Sonnet** | — | 토큰 매핑 + 시맨틱 판단 |
-| Phase 6 (코드 생성) | **Sonnet** | **gpt-5.3-codex-spark** (병렬) | 섹션별 컴포넌트 병렬 생성 |
-| Phase 7-8 (매핑/리포트) | **Sonnet** | — | 토큰 매핑 + 보고서 |
-| Phase 9 (검증 루프) | **Sonnet** | — | 이미지 비교 + diff 판단 + auto-fix |
-| Post (코드 리뷰) | — | **gpt-5.3-codex** | 생성 코드 품질 검증 |
+| Step | Claude | GPT (Codex) | 이유 |
+|------|--------|-------------|------|
+| Step A (스토리보드 + 구조) | **Haiku → Sonnet** | — | MCP 추출 → 구조 설계 |
+| Step B (모바일 추출) | **Haiku** | — | MCP + 이미지 다운로드 |
+| Step B (모바일 코드 생성) | **Sonnet** | **gpt-5.3-codex-spark** (병렬) | 섹션별 컴포넌트 생성 |
+| Step B (모바일 검증) | **Sonnet** | — | 이미지 비교 + auto-fix |
+| Step C (PC 추출) | **Haiku** | — | MCP + 이미지 다운로드 |
+| Step C (PC 반응형 반영) | **Sonnet** | — | 기존 코드에 반응형 레이어 추가 |
+| Step C (PC 검증) | **Sonnet** | — | 양쪽 뷰포트 비교 |
+| Step D (공통화) | **Sonnet** | — | 리팩토링 + 최종 검증 |
+| Post (코드 리뷰) | — | **gpt-5.3-codex** | 전체 코드 품질 검증 |
 
 ### GPT 모델 선택 기준
 
@@ -123,155 +132,177 @@ Post — 코드 리뷰:
 Codex 미설치 시 자동 스킵 — Claude만으로 순차 생성.
 ```
 
-## Phase 0: URL 입력 + Figma Data Extraction
-
-### 0-0. 사용자 입력 수집
+## Step A: 스토리보드 + Base 구조
 
-AskUserQuestion으로 하나씩 순서대로 **자유 텍스트 입력**을 받는다.
-**선택지(options)를 제공하지 않는다. 반드시 자유 입력(freeform text)만 받는다.**
-각 질문 후 반드시 사용자 응답을 받은 다음에만 다음 Step으로 진행.
+### A-1. 스토리보드 URL 입력
 
+AskUserQuestion (options 사용 금지, 자유 텍스트만):
 ```
-Step 1: 스토리보드 URL (선택)
-  → AskUserQuestion 호출 (options 파라미터 사용 금지):
-      question: "📋 스토리보드 Figma URL을 입력해주세요. (없으면 '없음')"
-  → ⏸️ 사용자 응답 대기
-  → figma.com URL 포함: storyboardUrl 저장
-  → "없음" 또는 URL 미포함: storyboardUrl = null
-
-Step 2: 디자인 URL (필수)
-  → AskUserQuestion 호출 (options 파라미터 사용 금지):
-      question: "🎨 디자인 Figma URL을 입력해주세요."
-  → ⏸️ 사용자 응답 대기
-  → URL 저장: designUrls = [url]
-
-Step 3: 추가 디자인 URL (반응형)
-  → AskUserQuestion 호출 (options 파라미터 사용 금지):
-      question: "🎨 추가 디자인 URL이 있으면 입력해주세요. (없으면 '없음')"
-  → ⏸️ 사용자 응답 대기
-  → figma.com URL 포함: designUrls에 추가 → responsive mode
-  → "없음" 또는 URL 미포함: single mode
-
-Step 4 (--new 미지정 시):
-  프로젝트에 기존 디자인 시스템이 있는지 자동 감지
-  → 있으면: default mode (기존 토큰 활용)
-  → 없으면: 자동으로 --new mode
-
-⚠️ 절대 Step 1~3을 한 번에 호출하지 않는다.
-⚠️ 절대 선택지(options/choices)를 제공하지 않는다. 순수 텍스트 입력만.
-   Step 1 응답 → Step 2 호출 → Step 2 응답 → Step 3 호출 순서 엄수.
+question: "📋 스토리보드 Figma URL을 입력해주세요. (없으면 '없음')"
+→ ⏸️ 응답 대기 (응답 받기 전 다음 진행 금지)
+→ figma.com URL → storyboardUrl 저장
+→ "없음" → storyboardUrl = null
 ```
 
-### 0-1. 스토리보드 추출 (storyboardUrl이 있을 때)
-
-스토리보드에서 **구현 스펙**을 먼저 추출. 이후 Phase에서 참조.
+### A-2. 스토리보드 추출 (storyboardUrl이 있을 때)
 
 ```
 URL에서 fileKey, nodeId 추출:
   https://www.figma.com/design/:fileKey/:fileName?node-id=:nodeId
   → nodeId: 하이픈을 콜론으로 ("1-109" → "1:109")
 
-1. get_metadata(fileKey, nodeId) → 전체 프레임 목록 (섹션 파악)
+1. get_metadata(fileKey, nodeId) → 전체 프레임 목록
 2. 관련 섹션별 get_design_context:
    - "해상도 대응" / "Media Query" → 브레이크포인트
    - "인터랙션" / "Interaction" → 호버/클릭/스크롤 스펙
    - "애니메이션" / "Animation" / "Motion" → 트랜지션 스펙
    - "상태" / "State" → 로딩/에러/성공 UI
    - "컬러" / "Color" / "타이포" / "Typography" → 디자인 가이드
+```
 
-결과 → storyboardSpec 객체에 저장:
-  {
-    breakpoints: { ... },       // 브레이크포인트 오버라이드
-    interactions: [ ... ],      // 인터랙션 목록
-    animations: [ ... ],        // 애니메이션 스펙
-    states: [ ... ],            // UI 상태 목록
-    colorGuide: { ... },        // 컬러 가이드
-    typographyGuide: { ... }    // 타이포 가이드
-  }
+### A-3. 프로젝트 스택 감지 + Base 구조 설계
+
+```
+1. 프로젝트 스택 감지 (Phase 3 참조)
+2. 디자인 시스템 감지 (--new 미지정 시)
+3. 브레이크포인트 로드 (Phase 3-3 참조, 스토리보드 우선)
+4. 피처명 결정 (Figma 파일명에서 추출)
+5. 파일 구조 생성:
+   - 루트 페이지 파일 (빈 shell)
+   - 컴포넌트 디렉토리 (빈 폴더)
+   - 토큰 파일 (스토리보드 기반 초기값)
 ```
 
-### 0-2. 디자인 추출 (MCP)
+---
+
+## Step B: 모바일 디자인 반영
 
-각 디자인 URL에 대해 MCP로 추출:
+### B-1. 모바일 디자인 URL 입력
 
+AskUserQuestion (options 사용 금지):
+```
+question: "📱 모바일 디자인 Figma URL을 입력해주세요."
+→ ⏸️ 응답 대기
+→ URL 저장: mobileUrl
 ```
-URL에서 fileKey, nodeId 추출 (동일 방식)
 
-각 URL에 대해:
-  1. get_design_context(fileKey, nodeId) → 코드 + 스크린샷 + 메타데이터 + 에셋 URL
-  2. get_metadata(fileKey, nodeId) → 레이어 구조 (XML)
-  3. get_screenshot(fileKey, nodeId) → 프레임 이미지
+### B-2. 모바일 디자인 추출 (MCP)
 
-디자인 URL이 2개 이상이면:
-  → 프레임 width로 viewport 자동 감지 (mobile/tablet/desktop)
-  → responsive mode 진입
+```
+1. get_design_context(fileKey, nodeId) → 코드 + 스크린샷 + 에셋 URL
+→ 스크린샷으로 전체 디자인 분석 (레이아웃, 타이포, 색상, 컴포넌트 구조)
 ```
 
-### 0-3. Image Asset Download (BLOCKING — 코드 생성 전 반드시 완료)
+### B-3. 이미지 에셋 다운로드 (BLOCKING)
 
-> **⛔ 이 단계를 건너뛰면 안 됨.** 이미지 다운로드가 완료되지 않으면 Phase 6 코드 생성으로 진행하지 않는다.
+> **⛔ 이미지 다운로드 완료 전 코드 생성 진행 금지.**
 
-`get_design_context` 응답에 포함된 이미지 에셋 URL은 **7일 후 만료**되는 임시 URL.
-**즉시 다운로드**하여 프로젝트에 저장해야 함.
+```
+1. get_design_context 응답에서 모든 이미지 URL 추출
+   (패턴: https://www.figma.com/api/mcp/asset/...)
+2. WebFetch로 각 URL 다운로드
+3. 프로젝트 에셋 디렉토리에 저장 (Nuxt: static/images/{feature}/)
+4. 파일명: 레이어 이름 기반 kebab-case
+5. URL→로컬경로 매핑 테이블 생성
+6. SVG: 작은 아이콘 → 인라인, 큰 SVG → 파일
+```
+
+### B-4. 모바일 코드 생성
+
+```
+1. 모바일 기준으로 컴포넌트 코드 생성 (Phase 4~6 적용)
+2. 이미지 에셋은 매핑 테이블의 로컬 경로 사용
+3. 스토리보드 스펙 반영 (인터랙션, 애니메이션)
+4. 모바일 전용 스타일 작성 (desktop 미고려)
+```
+
+### B-5. 모바일 검증 루프
+
+```
+🔄 Phase 9 검증 루프 실행:
+  - Figma 모바일 스크린샷 vs 생성된 코드 비교
+  - P1=0 될 때까지 수정 반복
+  - 이미지 에셋 전부 표시되는지 확인
+```
+
+---
 
-**Step 1: 에셋 URL 수집**
+## Step C: PC 디자인 반영 (반응형)
 
-`get_design_context` 응답에서 모든 이미지 URL 추출:
+### C-1. PC 디자인 URL 입력
+
+AskUserQuestion (options 사용 금지):
 ```
-패턴: https://www.figma.com/api/mcp/asset/...
-코드에 const xxxImage = 'https://...' 형태로 포함됨
+question: "🖥️ PC 디자인 Figma URL을 입력해주세요. (없으면 '없음')"
+→ ⏸️ 응답 대기
+→ URL → pcUrl 저장 (responsive mode)
+→ "없음" → single viewport mode (Step D로 직행)
 ```
 
-**Step 2: 다운로드 + 저장**
+### C-2. PC 디자인 추출 (MCP)
 
 ```
-각 URL에 대해:
-  1. WebFetch로 다운로드
-  2. 프로젝트 에셋 디렉토리에 저장:
-     - Nuxt: static/images/{feature}/ 또는 public/images/{feature}/
-     - Next.js: public/images/{feature}/
-     - React: public/images/{feature}/
-  3. 파일명은 레이어 이름 기반 (kebab-case):
-     - "Hero Background" → hero-background.webp
-     - "Product Photo 1" → product-photo-1.webp
+1. get_design_context(fileKey, nodeId) → 코드 + 스크린샷 + 에셋 URL
+→ 모바일 스크린샷과 side-by-side 비교 → viewport diff table 생성
 ```
 
-**Step 3: URL → 로컬 경로 매핑 테이블 생성**
+### C-3. PC 이미지 에셋 다운로드 (BLOCKING)
 
 ```
-다운로드 완료 후, 매핑 테이블을 메모리에 보관:
+모바일과 동일 프로세스.
+PC 전용 이미지가 있으면 추가 다운로드.
+동일 이미지는 스킵 (중복 방지).
+```
 
-| Figma 임시 URL | 로컬 경로 | 레이어 이름 |
-|---------------|----------|-----------|
-| https://figma.com/api/mcp/asset/abc... | /images/winter-pcbang/hero-bg.webp | Hero Background |
-| https://figma.com/api/mcp/asset/def... | /images/winter-pcbang/hero-title.webp | Hero Title |
+### C-4. PC 스타일 반영 + 반응형 리팩토링
 
-→ Phase 6 코드 생성 시 이 매핑 테이블로 임시 URL을 로컬 경로로 교체
+```
+기존 모바일 코드에 PC 대응 추가:
+1. 공통 값 → clamp() fluid 토큰으로 변환
+2. 레이아웃 구조 변경 → @media (min-width: {breakpoint}px) 추가
+3. PC 전용 요소 → display toggle (.desktopOnly)
+4. 모바일 전용 요소 → display toggle (.mobileOnly)
+5. PC 전용 배경 이미지 → @media 분기
+6. 기존 모바일 코드는 가능한 보존하고 반응형 레이어만 추가
 ```
 
-**Step 4: SVG 처리**
+### C-5. PC 검증 루프
 
 ```
-- 벡터 에셋 (아이콘, 로고) → SVG로 다운로드
-- 작은 아이콘 (< 1KB) → 인라인 SVG 컴포넌트
-- 큰 SVG → 파일로 저장
+🔄 Phase 9 검증 루프 실행:
+  - Figma PC 스크린샷 vs 생성된 코드 (PC viewport) 비교
+  - P1=0 될 때까지 수정 반복
+  - 모바일 검증도 재확인 (PC 수정으로 모바일이 깨지지 않았는지)
 ```
 
-### 0-4. Extraction Gate (코드 생성 진행 조건)
+---
+
+## Step D: 최종 공통화 리팩토링
+
+### D-1. 스타일 공통화
 
-> **다음 조건을 모두 만족해야 Phase 1로 진행:**
+```
+1. 모바일/PC에서 동일한 값 → 공통 토큰으로 추출
+2. 중복 CSS/SCSS 규칙 통합
+3. 컴포넌트 내 중복 로직 제거
+```
+
+### D-2. 컴포넌트 통합
 
 ```
-✅ 디자인 URL 최소 1개의 get_design_context 성공
-✅ 디자인 스크린샷 최소 1개 획득
-✅ 이미지 에셋 전부 다운로드 완료 (0개 남은 미다운로드)
-✅ URL→로컬경로 매핑 테이블 생성 완료
-✅ (responsive) 최소 2개 뷰포트의 스크린샷 획득
+1. 유사 컴포넌트 (80% rule) → variant prop으로 통합
+2. 중복 sub-component → 공유 컴포넌트로 추출
+3. Fragment/template 활용하여 불필요한 래퍼 제거
+```
+
+### D-3. 최종 검증 루프
 
-❌ 하나라도 실패 시:
-  → 실패 항목 보고 + 재시도
-  → 이미지 다운로드 실패 시: 해당 URL 재시도 (최대 3회)
-  → 재시도 후에도 실패: 사용자에게 수동 다운로드 요청 후 계속
+```
+🔄 양쪽 뷰포트 동시 검증:
+  - 모바일 Figma vs 코드 (mobile viewport)
+  - PC Figma vs 코드 (desktop viewport)
+  - 양쪽 모두 P1=0, Match Score 95%+
+  - 이미지 에셋 전부 정상 표시
 ```
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@su-record/vibe",
-  "version": "2.8.11",
+  "version": "2.8.12",
   "description": "AI Coding Framework for Claude Code — 49 agents, 41+ tools, multi-LLM orchestration",
   "type": "module",
   "main": "dist/cli/index.js",