@su-record/vibe 2.8.37 → 2.8.39

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@su-record/vibe",
-  "version": "2.8.37",
+  "version": "2.8.39",
   "description": "AI Coding Framework for Claude Code — 56 agents, 45 skills, multi-LLM orchestration",
   "type": "module",
   "main": "dist/cli/index.js",

package/skills/vibe.figma/SKILL.md

@@ -1,32 +1,34 @@
 ---
 name: vibe.figma
-description: Figma design to code — 시각 기반 퍼즐 조립 방식
+description: Figma design to code — 트리 기반 구조적 코드 생성
 triggers: []
 tier: standard
 ---
 
-# vibe.figma — Visual Puzzle Assembly
+# vibe.figma — Structural Code Generation
 
 ## 핵심 원칙
 
 ```
-스크린샷이 정답이다. Figma 데이터는 재료일 뿐이다.
+Figma 트리가 코드의 원천이다. 스크린샷은 검증용이다.
 
-❌ Figma 트리 구조를 HTML로 변환하지 않는다 (이 방식은 실패한다)
-✅ 스크린샷을 보고 "무엇을 만들어야 하는지" 파악한다
-✅ Figma 데이터(이미지, 색상, 수치)를 정확한 재료로 사용한다
-✅ 사람 개발자처럼: 디자인 보고 → 에셋 받고 → 만들면서 비교
+✅ Figma Auto Layout → CSS Flexbox 1:1 기계적 매핑
+✅ Figma CSS 속성 → SCSS 직접 변환 (추정 없음)
+✅ Claude는 시맨틱 판단만: 태그 선택, 컴포넌트 분리, 인터랙션
+✅ 스크린샷은 생성이 아닌 검증에만 사용
 ```
 
 ## 금지 사항
 
 ```
-❌ Figma 레이어 트리를 그대로 div 구조로 변환
+❌ 스크린샷을 보고 CSS 추정 (범용 LLM의 약점)
+❌ Figma 레이어를 무분별하게 div soup로 변환
 ❌ CSS로 이미지 재현 (gradient/shape으로 그림 그리기)
 ❌ 이미지 다운로드 없이 코드 생성 진행
 ❌ placeholder / 빈 src="" 남기기
-❌ 색상·크기를 추정 (재료함에 정확한 값이 있음)
+❌ tree.json에 없는 CSS 값을 추정하여 작성
 ❌ 컴포넌트 파일 안에 <style> 블록 / 인라인 style=""
+✅ tree.json의 CSS 속성을 SCSS에 직접 매핑
 ✅ 외부 SCSS 파일에만 스타일 작성
 ```
 
@@ -34,11 +36,12 @@ tier: standard
 
 ```
 /vibe.figma
-  → Phase 0: Setup (스택 감지, 디렉토리 생성)
+  → Phase 0: Setup (스택 감지, 디렉토리 생성, 기존 자산 인덱싱)
   → Phase 1: Storyboard (스토리보드 → 레이아웃 + 컴포넌트 + 기능 정의)
-  → Phase 2: 재료 확보 (디자인 URL → 스크린샷 + 이미지 + CSS + 텍스트)
-  → Phase 3: 퍼즐 조립 (스크린샷 보면서 Phase 1 컴포넌트에 디자인 입히기)
-  → Phase 4: 검증 루프 (빌드 → 스크린샷 → 비교 → 수정 → 반복)
+  → Phase 2: 재료 확보 (디자인 URL → 트리 + 이미지 + 스크린샷)
+  → Phase 3: 구조적 코드 생성 (트리 → HTML+SCSS 매핑 + 시맨틱 보강)
+  → Phase 3.5: 컴파일 게이트 (tsc → build → dev 확인)
+  → Phase 4: 시각 검증 루프 (렌더링 vs 스크린샷 비교 → 수정)
 ```
 
 ---
@@ -199,78 +202,56 @@ URL에서 fileKey, nodeId 추출
   → 또는 depth 높여서 하위 분할 조회
 ```
 
-### 1-2. 레이아웃 + 컴포넌트 구성 (코드 생성)
-
-```
-스토리보드에서 파악한 섹션 구조로 실제 파일을 생성한다.
-
-1. 루트 페이지 파일 생성 (Write):
-   pages/{feature}.vue (또는 app/{feature}/page.tsx)
-   → 모든 섹션 컴포넌트 import + 순서대로 배치
-   → 팝업/모달 조건부 렌더링
-
-2. 섹션 컴포넌트 파일 생성 (Write):
-   components/{feature}/HeroSection.vue
-   components/{feature}/DailyCheckInSection.vue
-   components/{feature}/PlayTimeMissionSection.vue
-   ...PAGE 프레임 수만큼
-
-   각 컴포넌트에 반드시 포함:
-
-   <template>:
-     - 섹션 제목 <h2> (스토리보드에서 추출한 실제 텍스트)
-     - 설명 텍스트 <p>
-     - 리스트 렌더링 (v-for + 목 데이터)
-     - 버튼/CTA (실제 라벨 + @click 핸들러)
-     - 조건부 렌더링 (상태에 따른 v-if)
-     → 빈 template 금지. 브라우저에서 텍스트가 보여야 함.
-
-   <script setup>:
-     - JSDoc 주석으로 기능 요구사항 작성:
-       /**
-        * 일일 출석 미션 섹션
-        *
-        * [기능 정의]
-        * - 매일 출석 시 스노우 토큰 즉시 지급
-        * - 누적 3/5/7일 달성 시 추가 보상
-        *
-        * [인터랙션]
-        * ① 출석하기 클릭 → API호출 → 토큰지급 표시
-        * ② 누적 보상 클릭 → 보상 수령
-        *
-        * [상태] default, checked, reward-claimed
-        */
-     - TypeScript 인터페이스
-     - 목 데이터 (빈 배열 금지, 3~7개 아이템)
-     - 이벤트 핸들러 stub (body는 // TODO:)
-
-   <style> 블록 없음 — 스타일은 Phase 3에서 외부 파일로.
-
-3. 공통 컴포넌트 (SHARED에서 파악):
-   → 프로젝트에 이미 있으면 import 재사용
-   → 없으면 새로 생성 (GNB, Footer, Popup)
-
-4. 스타일 디렉토리 구조 생성 (빈 파일):
-   styles/{feature}/index.scss
-   styles/{feature}/_tokens.scss
-   styles/{feature}/_mixins.scss
-   styles/{feature}/_base.scss
-   styles/{feature}/layout/
-   styles/{feature}/components/
+### 1-2. 기능 스펙 문서 작성 (파일 생성 없음)
+
+```
+❌ Phase 1에서 코드 파일을 생성하지 않는다.
+   → Phase 1 HTML 구조와 Phase 3 트리 매핑이 충돌하면 이중 작업
+   → Phase 3에서 tree.json 기반으로 코드를 생성
+
+✅ Phase 1의 출력물은 기능 스펙 문서 (텍스트):
+
+1. 섹션 목록:
+   | # | 섹션 이름 | Figma 프레임 name | 높이 | 설명 |
+   |---|----------|------------------|------|------|
+   | 1 | Hero | Hero | 1280px | 키비주얼 + 이벤트 정보 |
+   | 2 | DailyCheckIn | Daily | 3604px | 출석 미션 |
+   | 3 | PlayTime | Frame 633371 | 11363px | 플레이타임 미션 |
+
+2. 각 섹션의 기능 정의:
+   /**
+    * 일일 출석 미션 섹션
+    *
+    * [기능 정의]
+    * - 매일 출석 시 스노우 토큰 즉시 지급
+    * - 누적 3/5/7일 달성 시 추가 보상
+    *
+    * [인터랙션]
+    * ① 출석하기 클릭 → API호출 → 토큰지급 표시
+    * ② 누적 보상 클릭 → 보상 수령
+    *
+    * [상태] default, checked, reward-claimed
+    */
+
+3. 공통 컴포넌트 목록:
+   → 프로젝트에 이미 있는 컴포넌트 (GNB, Footer 등)
+   → 새로 만들 공통 컴포넌트
+
+4. TypeScript 인터페이스 초안:
+   interface RewardItem { id: string; name: string; tokenAmount: number; status: 'locked'|'available'|'claimed' }
 ```
 
 ### 1-3. 검증
 
 ```
 Phase 1 완료 조건:
-  □ 브라우저에서 열면 각 섹션의 텍스트/리스트/버튼이 보인다
-  □ 클릭하면 핸들러가 실행된다
-  □ 모든 컴포넌트에 [기능 정의] + [인터랙션] + [상태] JSDoc
-  □ 빈 배열 0개, 빈 template 0개, <style> 블록 0개
-  □ 빌드 성공
+  □ 모든 섹션이 목록에 포함되어 있다
+  □ 각 섹션에 [기능 정의] + [인터랙션] + [상태] 가 정의되어 있다
+  □ TypeScript 인터페이스 초안이 작성되어 있다
+  □ 공통 컴포넌트가 식별되어 있다
+  □ 파일을 하나도 생성하지 않았다
 
-빈 화면 = Phase 1 미완성. Phase 2로 넘어가지 않는다.
-스타일/이미지는 없어도 됨 — Phase 3에서 채움.
+Phase 3에서 이 스펙 + tree.json을 합쳐서 코드를 생성한다.
 ```
 
 ---
@@ -313,6 +294,16 @@ URL에서 fileKey, nodeId 추출
   node "[FIGMA_SCRIPT]" images {fileKey} {nodeId} --out=/tmp/{feature}/images/ --depth=10
   → 모든 이미지 에셋 확보. 누락 0건, 0byte 0건.
 
+3.5단계 — 아이템/아이콘 노드 렌더링 (추가 시각 재료):
+  tree.json에서 INSTANCE/COMPONENT 타입 중 아이템 후보를 식별:
+    - name에 "item", "icon", "reward", "token", "coin", "badge" 포함
+    - 크기 50~300px 범위의 독립 요소
+    - fill 이미지가 없지만 시각적으로 의미 있는 노드
+  해당 노드를 개별 렌더링:
+    node "[FIGMA_SCRIPT]" images {fileKey} {nodeId} --render --nodeIds={id1},{id2},... --out=/tmp/{feature}/images/
+  → 이미지 fill이 아닌 벡터/인스턴스 에셋도 PNG로 확보
+  → Phase 3에서 목 데이터의 image 경로에 연결
+
 4단계 — 섹션별 스크린샷 (부분 정답):
   트리의 1depth 자식 프레임 각각:
     node "[FIGMA_SCRIPT]" screenshot {fileKey} {child.nodeId} --out=/tmp/{feature}/sections/{child.name}.png
@@ -542,40 +533,40 @@ Phase 1에서 생성한 빈 SCSS 파일에 기본 내용 Write:
   ❌ 90% 유사한데 새로 만들기 금지
 ```
 
-### 3-1. 섹션 조립 프로세스
+### 3-1. 트리 기반 구조적 코드 생성
 
 ```
-각 섹션에 대해:
-
-1. 정답 확인 — 섹션 스크린샷을 Read로 본다
-   /tmp/{feature}/sections/{section}.png
-   → "이 화면처럼 만들어야 한다"
+각 섹션에 대해 (vibe.figma.convert 참조):
 
-2. 재료 확인 — 이 섹션에 필요한 재료 목록 확인
-   - 이미지: /tmp/{feature}/images/ 에서 해당 파일들
-   - CSS 수치: tree.json에서 해당 노드의 정확한 값
-   - 텍스트: TEXT 노드의 characters
+1. 트리 구조 읽기 — tree.json에서 해당 섹션 노드를 Read
+   → Auto Layout 속성(flex, gap, padding)이 코드의 기반
+   → 스크린샷은 검증용으로만 참조
 
-3. Phase 1 컴포넌트에 디자인 입히기
+2. 기계적 매핑 (추정 없음):
    a. 이미지 복사: images/ → static/images/{feature}/
-   b. template 업데이트:
-      - Phase 1의 기능 요소(v-for, @click, v-if, $emit) 보존
-      - 스크린샷을 보고 시각 구조에 맞게 HTML 재구성
-      - Figma 레이어 구조를 HTML로 변환하지 않음 (시각 기반)
-      - 재료함의 정확한 이미지 경로 사용
-      - 재료함의 정확한 텍스트 사용
-   c. script 보존:
-      - Phase 1의 JSDoc, 인터페이스, 핸들러 유지
-   d. SCSS 작성: 재료함의 정확한 CSS 수치 사용 (scaleFactor 적용)
-      - layout/_{section}.scss ← 포지션, 사이즈, 플렉스
-      - components/_{section}.scss ← 폰트, 색상, 보더
-      - _tokens.scss에 새 토큰 추가
-
-4. 즉시 검증 — 스크린샷과 비교
-   - 이미지 빠진 거 없나?
-   - 텍스트 빠진 거 없나?
-   - 레이아웃 구조가 스크린샷과 맞나?
-   - Phase 1의 기능 요소가 보존되었나?
+   b. 노드 → HTML 매핑:
+      - Auto Layout 있음 → <div> + flex (direction/gap/padding 직접)
+      - Auto Layout 없음 → <div> + position:relative (자식 absolute)
+      - TEXT 노드 → <span> (Claude가 h2/p/button으로 승격)
+      - imageRef 있음 → <img src="다운로드된 파일">
+      - 반복 패턴 (동일 구조 3+) → v-for
+   c. CSS 직접 매핑:
+      - node.css의 모든 속성을 SCSS에 1:1 매핑
+      - scaleFactor 적용 (px 값만)
+      - tree.json에 없는 CSS 값은 작성하지 않음
+   d. Phase 1의 JSDoc, 인터페이스, 핸들러 보존
+
+3. Claude 시맨틱 보강:
+   - div → section/h2/p/button 태그 승격
+   - 컴포넌트 분리 + props 설계
+   - 접근성 (alt, aria)
+   - 인터랙션 (클릭, 상태)
+
+4. 자가 검증:
+   - template 클래스 ↔ SCSS 클래스 1:1 일치
+   - 모든 img src가 static/에 실제 존재
+   - Auto Layout 노드 → SCSS에 flex 속성 존재
+   - 스크린샷과 비교 (시각 확인)
 ```
 
 ### 3-2. 코드 작성 규칙
@@ -583,11 +574,10 @@ Phase 1에서 생성한 빈 SCSS 파일에 기본 내용 Write:
 ```
 컴포넌트 (Vue 예시):
   <template>
-    스크린샷에서 보이는 시각 구조대로 작성.
-    Figma 레이어 구조 무시.
+    tree.json의 Auto Layout 구조를 HTML flex 레이아웃으로 직접 매핑.
+    Claude가 시맨틱 태그로 승격 (div → section/h2/p/button).
     Phase 1의 기능 요소(v-for, @click, v-if) 보존.
-    시맨틱 HTML 사용 (<section>, <h2>, <ul>, <button>).
-    이미지 경로: /images/{feature}/파일명.png
+    이미지 경로: /images/{feature}/파일명.png (실제 파일 존재 확인)
     텍스트: tree.json의 TEXT 노드 characters 값 그대로.
 
   <script setup>

package/skills/vibe.figma/templates/figma-handoff.md

@@ -40,11 +40,11 @@ Breakpoint threshold: `@media (min-width: {{BP_PC}}px)`
 
 ## Sections
 
-| # | Section Name | Component File | Mode | Height (design) |
-|---|-------------|---------------|------|----------------|
-| 1 | {{SECTION_NAME}} | `components/{{FEATURE_KEY}}/{{ComponentName}}.vue` | {{MODE}} | {{HEIGHT}}px |
+| # | Section Name | Component File | Tree Nodes | Height (design) |
+|---|-------------|---------------|-----------|----------------|
+| 1 | {{SECTION_NAME}} | `components/{{FEATURE_KEY}}/{{ComponentName}}.vue` | {{NODE_COUNT}} | {{HEIGHT}}px |
 
-**Mode key:** `normal` = external SCSS | `literal` = scoped CSS (non-standard layout)
+**Generation:** tree.json → HTML+SCSS 구조적 매핑 (external SCSS)
 
 ---