@su-record/vibe 2.9.2 → 2.9.3

package/skills/vibe.figma/SKILL.md

@@ -1,59 +1,59 @@
 ---
 name: vibe.figma
-description: Figma design to code — 트리 기반 구조적 코드 생성
+description: Figma design to code — tree-based structural code generation
 triggers: []
 tier: standard
 ---
 
 # vibe.figma — Structural Code Generation
 
-## 핵심 원칙
+## Core Principles
 
 ```
-Figma 트리가 코드의 원천이다. 스크린샷은 검증용이다.
+The Figma tree is the source of truth for code. Screenshots are for verification only.
 
-✅ Figma Auto Layout → CSS Flexbox 1:1 기계적 매핑
-✅ Figma CSS 속성 → SCSS 직접 변환 (추정 없음)
-✅ Claude는 시맨틱 판단만: 태그 선택, 컴포넌트 분리, 인터랙션
-✅ 스크린샷은 생성이 아닌 검증에만 사용
+✅ Figma Auto Layout → CSS Flexbox 1:1 mechanical mapping
+✅ Figma CSS properties → SCSS direct conversion (no guessing)
+✅ Claude handles semantic decisions only: tag selection, component splitting, interactions
+✅ Screenshots are used for verification only, not generation
 ```
 
-## ⛔ 불변 규칙
+## Immutable Rules
 
 ```
-1. screenshot으로 콘텐츠를 이미지화 금지
-   ✅ BG 렌더링 (TEXT 자식 없는 배경), 벡터 글자 GROUP, 섹션 스크린샷(검증용)
-   ❌ TEXT 자식 프레임, INSTANCE 반복, 버튼/가격, 섹션 통째 렌더링
+1. Do NOT render content as images via screenshot
+   ✅ BG rendering (backgrounds with no TEXT children), vector-text GROUPs, section screenshots (verification only)
+   ❌ Frames with TEXT children, INSTANCE repetitions, buttons/prices, rendering entire sections
 
-2. BG는 CSS background-image만. <img> 태그 금지.
+2. BG must use CSS background-image only. <img> tag is forbidden.
 
-3. Phase 4 코드 생성 중 새 screenshot 호출 금지.
-   Phase 2 재료만 사용. 복잡해도 HTML+CSS로 구현.
+3. No new screenshot calls during Phase 4 code generation.
+   Use only Phase 2 materials. No matter how complex — implement with HTML+CSS.
 ```
 
-## 전체 플로우
+## Full Flow
 
 ```
-입력: 모든 URL을 한번에 받는다
-  Storyboard: figma.com/...?node-id=aaa (있으면)
+Input: receive all URLs at once
+  Storyboard: figma.com/...?node-id=aaa (if present)
   MO Design:  figma.com/...?node-id=xxx
-  PC Design:  figma.com/...?node-id=yyy (있으면)
+  PC Design:  figma.com/...?node-id=yyy (if present)
 
 → Phase 0: Setup
-→ Phase 1: 스토리보드 분석 → 기능 스펙 문서
-→ Phase 2: 재료 확보 (→ vibe.figma.extract)
-→ Phase 3: 리매핑 (MO↔PC 매칭 → remapped.json)
-→ Phase 4: 순차 코드 생성 (→ vibe.figma.convert)
-→ Phase 5: 컴파일 게이트
-→ Phase 6: 시각 검증 루프
-
-작업 디렉토리:
+→ Phase 1: Storyboard analysis → functional spec document
+→ Phase 2: Gather materials (→ vibe.figma.extract)
+→ Phase 3: Remapping (MO↔PC matching → remapped.json)
+→ Phase 4: Sequential code generation (→ vibe.figma.convert)
+→ Phase 5: Compile gate
+→ Phase 6: Visual verification loop
+
+Working directory:
   /tmp/{feature}/
   ├── mo-main/tree.json, bg/, content/, sections/
   ├── pc-main/tree.json, bg/, content/, sections/
-  └── remapped.json ← Phase 4의 유일한 입력
+  └── remapped.json ← sole input for Phase 4
 
-코드 출력: 프로젝트 디렉토리에 직접 배치
+Code output: placed directly in the project directory
   components/{feature}/, styles/{feature}/
 ```
 
@@ -62,99 +62,122 @@ Figma 트리가 코드의 원천이다. 스크린샷은 검증용이다.
 ## Phase 0: Setup
 
 ```
-1. 스택 감지: package.json → react/vue/svelte, next/nuxt, scss/tailwind
-2. 피처명: Figma 파일명 → kebab-case
-3. 디렉토리: components/{feature}/, public/images/{feature}/, styles/{feature}/
-4. 컴포넌트 인덱싱 → /tmp/{feature}/component-index.json
-   (50개 이하 스캔, props/slots/classes 추출, 2분 이내)
+1. Stack detection: package.json → react/vue/svelte, next/nuxt, scss/tailwind
+2. Feature name: Figma filename → kebab-case
+3. Directories: components/{feature}/, public/images/{feature}/, styles/{feature}/
+4. Component indexing → /tmp/{feature}/component-index.json
+   (scan up to 50 components, extract props/slots/classes, within 2 minutes)
 5. Hooks/Types/Constants → /tmp/{feature}/context-index.json
-6. 디자인 토큰 스캔 → /tmp/{feature}/project-tokens.json
+6. Design token scan → /tmp/{feature}/project-tokens.json
    (SCSS > CSS Variables > Tailwind > CSS-in-JS)
 ```
 
 ---
 
-## Phase 1: 스토리보드 분석
+## Phase 1: Storyboard Analysis
 
 ```
-사용자 입력: URL 또는 PDF/이미지를 줄바꿈으로 입력
+User input: enter URLs or PDF/images separated by newlines
 
-URL 분류 (자동):
-  fileKey 다름 → 스토리보드 vs 디자인
-  ROOT name에 "MO" → 모바일, "PC" → 데스크탑
+URL classification (automatic):
+  Different fileKey → storyboard vs design
+  ROOT name contains "MO" → mobile, "PC" → desktop
 
-스토리보드 분석:
-  depth=3으로 프레임 수집 → name 패턴으로 분류
-  SPEC(기능정의서) → CONFIG(해상도) → PAGE(메인 섹션) → SHARED(공통)
-  PDF/이미지도 동일 구조 추출
+Storyboard analysis:
+  Collect frames at depth=3 → classify by name pattern
+  SPEC (functional definition) → CONFIG (resolution) → PAGE (main sections) → SHARED (common)
+  PDF/images follow the same structural extraction
 
-❌ Phase 1에서 코드 파일 생성 금지
+❌ No code file creation during Phase 1
 
-출력 (텍스트만):
-  1. 섹션 목록 테이블 (이름, Figma name, 높이, 설명)
-  2. 각 섹션 기능 정의 ([기능] + [인터랙션] + [상태])
-  3. 공통 컴포넌트 목록
-  4. TypeScript 인터페이스 초안
+Output (text only):
+  1. Section list table (name, Figma name, height, description)
+  2. Functional definition per section ([Function] + [Interaction] + [State])
+  3. Common component list
+  4. TypeScript interface draft
 ```
 
 ---
 
-## Phase 2: 재료 확보 ← Research (병렬)
+## Phase 2: Gather Materials ← Research (parallel)
 
-**→ vibe.figma.extract 스킬의 규칙을 따른다.**
-**코디네이터 패턴: MO/PC 추출을 워커로 병렬 실행.**
+**→ Follow the rules of the vibe.figma.extract skill.**
+**Coordinator pattern: run MO/PC extraction as parallel workers.**
 
 ```
-# [FIGMA_SCRIPT] = ~/.vibe/hooks/scripts/figma-extract.js
+# [FIGMA_SCRIPT] = {{VIBE_PATH}}/hooks/scripts/figma-extract.js
 
-MO/PC 동시 추출 (각각 독립 워커):
-  워커-MO: screenshot → tree → images → 에셋 렌더링 → sections/
-  워커-PC: screenshot → tree → images → 에셋 렌더링 → sections/
-  → 두 워커의 결과가 모두 도달한 후 Phase 3 진행
+Simultaneous MO/PC extraction (each as an independent worker):
+  Worker-MO: screenshot → tree → images → asset rendering → sections/
+  Worker-PC: screenshot → tree → images → asset rendering → sections/
+  → Proceed to Phase 3 only after both workers have completed
 
-단일 BP: 워커 1개로 순차 실행
+Single BP: run sequentially with 1 worker
 
-멀티 프레임 (같은 BP, 다른 페이지):
-  순차 추출 (500ms 간격), 부분 실패 허용
+Multi-frame (same BP, different pages):
+  Sequential extraction (500ms interval), partial failure allowed
 ```
 
 ---
 
-## Phase 3: 데이터 정제 ← Synthesis (BP별 독립)
+## Phase 3: Data Refinement ← Synthesis (independent per BP)
 
-**각 BP의 tree.json을 섹션별로 분할 + 정제한다.**
-**MO↔PC 매칭(반응형)은 이 단계에서 하지 않는다.**
+**Split and refine each BP's tree.json by section.**
+**MO↔PC matching (responsive) is NOT done at this stage.**
 
-### 핵심 원칙
+### BLOCKING Command — Writing custom refine scripts is strictly forbidden
+
+```bash
+# MO
+node {{VIBE_PATH}}/hooks/scripts/figma-refine.js \
+  /tmp/{feature}/mo-main/tree.json \
+  --out=/tmp/{feature}/mo-main/sections.json \
+  --design-width=720 \
+  --bp=mo
+
+# PC
+node {{VIBE_PATH}}/hooks/scripts/figma-refine.js \
+  /tmp/{feature}/pc-main/tree.json \
+  --out=/tmp/{feature}/pc-main/sections.json \
+  --design-width=2560 \
+  --bp=pc
+```
+
+⛔ **Phase 4 is blocked until these commands are executed.**
+⛔ **Do NOT write custom refine scripts** (refine-sections.mjs, refine.js, etc. — all forbidden)
+⛔ **Do NOT parse tree.json directly with Python/Node to produce sections.json**
+✅ Use only the output of figma-refine.js. If the output is unsatisfactory, modify figma-refine.js.
+
+### Core Principles
 
 ```
-⛔ BP별 독립 정제. MO와 PC를 섞지 않는다.
-⛔ 정제된 JSON은 Phase 4의 유일한 입력이다.
-⛔ 섹션별 전체 하위 트리(children 재귀)를 반드시 포함해야 한다.
+⛔ Refine each BP independently. Do NOT mix MO and PC.
+⛔ The refined JSON is the sole input for Phase 4.
+⛔ The full subtree (recursive children) for each section must be included.
 ```
 
-### 출력
+### Output
 
 ```
 /tmp/{feature}/
   mo-main/
-    sections.json    ← MO 정제 결과
+    sections.json    ← MO refinement result
   pc-main/
-    sections.json    ← PC 정제 결과
+    sections.json    ← PC refinement result
 
-sections.json 구조:
+sections.json structure:
   {
-    meta: { feature, designWidth, bp(해당 BP) },
+    meta: { feature, designWidth, bp (the corresponding BP) },
     sections: [
       {
         name: "Hero",
         nodeId, name, type, size, css,
-        text,          // TEXT 노드만
-        imageRef,      // 이미지 fill
-        fills,         // 다중 fill (2개 이상)
+        text,          // TEXT nodes only
+        imageRef,      // image fill
+        fills,         // multiple fills (2 or more)
         layoutSizingH, // HUG/FILL/FIXED
         layoutSizingV,
-        children: [    // ⛔ 전체 하위 트리 재귀 — 잎 노드까지
+        children: [    // ⛔ full recursive subtree — down to leaf nodes
           { nodeId, name, type, size, css, children: [...] }
         ],
         images: {
@@ -166,118 +189,175 @@ sections.json 구조:
   }
 ```
 
-### 노드 정제 규칙
+### Node Refinement Rules
 
 ```
-tree.json → sections.json 변환 시 정제:
-  1. 크기 0px 노드 → 제거
-  2. VECTOR 장식선 (w/h ≤ 2px) → 제거
-  3. isMask 노드 → 제거
-  4. BG 프레임 → children에서 분리, images.bg로 이동
-  5. 벡터 글자 GROUP → children에서 분리, images.content에 추가
-  6. 디자인 텍스트 (fills 다중/gradient, effects 있는 TEXT) → images.content에 추가
-  7. 나머지 노드 → children에 유지 (CSS 포함, 재귀)
+Refinement applied when converting tree.json → sections.json:
+  1. Nodes with size 0px → remove
+  2. VECTOR decorative lines (w/h ≤ 2px) → remove
+  3. isMask nodes → remove
+  4. BG frames → separate from children, move to images.bg
+  5. Vector-text GROUPs → separate from children, add to images.content
+  6. Design text (TEXT with multiple/gradient fills or effects) → add to images.content
+  7. Remaining nodes → keep in children (with CSS, recursive)
 ```
 
-### 멀티 프레임 (같은 BP, 다른 페이지)
+### Multi-frame (same BP, different pages)
 
 ```
-공통 요소 식별 → 공유 컴포넌트 추출
-공통 토큰 합집합 → 공유 _tokens.scss
+Identify common elements → extract shared components
+Union of common tokens → shared _tokens.scss
 ```
 
 ---
 
-## Phase 4: BP별 스태틱 구현 ← Implement (BP별 순차)
+## Phase 4: Per-BP Static Implementation ← Implement (sequential per BP)
+
+**→ Follow the rules of the vibe.figma.convert skill.**
+**⛔ Implement MO fully first → pass verification → then implement PC. No responsive conversion.**
+**⛔ CSS values must use Figma original px as-is. vw conversion, clamp, @media are forbidden.**
+
+### BLOCKING Command — SCSS must only use script output
+
+```bash
+# Step A: Auto-generate SCSS skeleton (run once per BP)
+node {{VIBE_PATH}}/hooks/scripts/figma-to-scss.js \
+  /tmp/{feature}/{bp}-main/sections.json \
+  --out=/path/to/project/assets/scss/{feature}/
 
-**→ vibe.figma.convert 스킬의 규칙을 따른다.**
-**⛔ MO 먼저 전체 구현 → 검증 통과 → PC 구현. 반응형 변환은 하지 않는다.**
-**⛔ CSS 값은 Figma 원본 px 그대로. vw 변환, clamp, @media 금지.**
+# Step B: Per-section validation (after writing each section's code)
+node {{VIBE_PATH}}/hooks/scripts/figma-validate.js \
+  /path/to/project/assets/scss/{feature}/ \
+  /tmp/{feature}/{bp}-main/sections.json \
+  --section={SectionName}
+```
+
+⛔ **Writing SCSS files directly without calling figma-to-scss.js invalidates Phase 4.**
+⛔ **Do NOT write custom SCSS generation scripts** (to-scss.mjs, generate-scss.js, etc. — all forbidden)
+⛔ **Do NOT proceed to the next section without a figma-validate.js PASS.**
+⛔ **Do NOT write CSS values directly inside scoped style blocks** — only @import of external SCSS files is allowed.
+✅ Use figma-to-scss.js output as-is. If unsatisfactory, modify figma-to-scss.js.
 
 ```
-Phase 4A: MO 스태틱 구현
-  입력: /tmp/{feature}/mo-main/sections.json
-  ⛔ 병렬 금지. 한 섹션씩 순차:
-    1. sections.json에서 해당 섹션 Read
-    2. 이미지 vs HTML 판별 테이블 작성 (BLOCKING)
-    3. figma-to-scss.js → SCSS 골격 자동 생성 (px 그대로)
-    4. Claude: HTML 구조 + 시맨틱 태그 + 레이아웃 + 인터랙션
-    5. figma-validate.js → SCSS vs sections.json 대조
-       ├─ PASS → 다음 섹션
-       └─ FAIL → 불일치 수정 → 5번 재실행 (P1=0 까지, 횟수 제한 없음)
-  → Phase 5 (MO 컴파일) → Phase 6 (MO 시각 검증)
-
-Phase 4B: PC 스태틱 구현
-  입력: /tmp/{feature}/pc-main/sections.json
-  MO와 동일한 프로세스
-  → Phase 5 (PC 컴파일) → Phase 6 (PC 시각 검증)
-
-Phase 4C: 반응형 통합 (MO+PC 모두 검증 통과 후)
-  → 별도 플로우로 수립 (TODO)
-
-Claude의 역할 (제한적):
-  ✅ 이미지 분류: BG / 콘텐츠 / 장식 / 벡터 글자
-  ✅ HTML 시맨틱: section/h1/p/button 태그 선택
-  ✅ 컴포넌트 분리: v-for 반복, 공유 컴포넌트
-  ✅ 인터랙션: @click, 상태 변수, 조건부 렌더링
-  ❌ SCSS CSS 값 수정 금지 (figma-to-scss.js 출력 그대로 사용)
-  ❌ vw 변환, clamp, @media, 커스텀 함수/믹스인 생성 금지
-
-SCSS Setup (첫 섹션 전):
+Phase 4A: MO Static Implementation
+  Input: /tmp/{feature}/mo-main/sections.json
+  ⛔ No parallelism. Process one section at a time:
+    1. Read the target section from sections.json
+    2. Write an image vs HTML classification table (BLOCKING)
+    3. figma-to-scss.js → auto-generate SCSS skeleton (px as-is) — Step A once
+    4. Claude: HTML structure + semantic tags + layout + interactions (Vue/React files only)
+       ⛔ No CSS written directly in <style> blocks — only @import or @use allowed
+    5. figma-validate.js → compare SCSS vs sections.json — Step B
+       ├─ PASS → next section
+       └─ FAIL → fix discrepancies → re-run step 5 (repeat until P1=0, no round cap)
+  → Phase 5 (MO compile) → Phase 6 (MO visual verification)
+
+Phase 4B: PC Static Implementation
+  Input: /tmp/{feature}/pc-main/sections.json
+  Same process as MO
+  → Phase 5 (PC compile) → Phase 6 (PC visual verification)
+
+Phase 4C: Responsive Integration (after both MO+PC pass verification)
+  → Separate flow to be established (TODO)
+
+Claude's role (restricted):
+  ✅ Image classification: BG / content / decoration / vector-text
+  ✅ HTML semantics: section/h1/p/button tag selection
+  ✅ Component splitting: v-for repetition, shared components
+  ✅ Interactions: @click, state variables, conditional rendering
+  ✅ Execute figma-to-scss.js / figma-validate.js commands
+  ❌ Do NOT modify SCSS CSS values (use figma-to-scss.js output as-is)
+  ❌ Do NOT write CSS directly in <style> blocks
+  ❌ Do NOT use vw conversion, clamp, @media, or create custom functions/mixins
+  ❌ Do NOT write custom refine/generate scripts (refine.mjs, to-scss.mjs, etc.)
+
+SCSS Setup (before the first section):
   index.scss, _tokens.scss, _base.scss
-  토큰 매핑: project-tokens.json에서 기존 토큰 참조 → 매칭 안 되면 새 생성
+  Token mapping: reference existing tokens from project-tokens.json → create new ones if no match
 
-컴포넌트 매칭 (각 섹션 전):
-  component-index.json과 대조 → 매칭되면 import, 안 되면 새 생성
+Component matching (before each section):
+  Compare against component-index.json → import if matched, create new if not
 
-멀티 프레임 시:
-  1단계: 공유 컴포넌트 먼저 → components/shared/
-  2단계: 프레임별 고유 섹션
+Multi-frame:
+  Step 1: shared components first → components/shared/
+  Step 2: unique sections per frame
 ```
 
 ---
 
-## Phase 5: 컴파일 게이트
+## Phase 5: Compile Gate
 
 ```
-최대 3라운드 자동 반복.
+No round cap. Loop until compile succeeds (or stuck → ask user).
 
-0. 베이스라인 캡처 (Phase 4 전): tsc + build 기존 에러 기록
-   → Phase 5에서는 새 에러만 수정 대상
+0. Capture baseline (before Phase 4): record existing tsc + build errors
+   → Phase 5 only fixes NEW errors
 
 1. TypeScript: vue-tsc/svelte-check/tsc --noEmit
-2. Build: npm run build (120초 타임아웃)
-3. Dev 서버: npm run dev → 포트 감지 → 폴링
-
-에러 시: 파싱 → 자동 수정 → 재체크
-3라운드 실패: 에러 목록을 사용자에게 보고 (Phase 6 진행 불가)
-완료 시: dev 서버 PID 보존 → Phase 6에서 사용
-
-⛔ Phase 5 통과 후 반드시 Phase 6 진입. "완료 요약" 출력 금지.
-⛔ Phase 6 없이 작업 완료 선언 금지.
+2. Build: npm run build (120s timeout)
+3. Dev server: npm run dev → detect port → polling
+
+On error: parse → auto-fix → re-check
+Termination conditions:
+  ✅ Success: all checks pass → enter Phase 6
+  ⚠️ Stuck: same errors as previous round → ask user
+      1. Provide direct fix instructions → retry next round
+      2. "proceed" — record remaining errors as TODO, proceed to Phase 6
+      3. "abort" — halt workflow
+  ultrawork mode: on stuck, record TODO without prompting and proceed to Phase 6
+
+On completion: preserve dev server PID → used in Phase 6
+
+⛔ After Phase 5 passes (or user proceeds), must enter Phase 6. Do NOT output a "completion summary".
+⛔ Do NOT declare work complete without Phase 6.
 ```
 
 ---
 
-## Phase 6: 시각 검증 루프 ← Verify (병렬) ⛔ MANDATORY
+## Phase 6: Visual Verification Loop ← Verify (parallel) MANDATORY
 
-**⛔ Phase 6은 선택이 아닌 필수. Phase 5 통과 즉시 자동 진입.**
-**⛔ Phase 6 미실행 시 전체 작업은 "미완료" 상태.**
-**코디네이터 패턴: 독립 섹션별 검증을 워커로 병렬 실행 가능.**
+**⛔ Phase 6 is mandatory, not optional. Enter automatically upon Phase 5 completion.**
+**⛔ If Phase 6 is skipped, the entire task is considered "incomplete".**
+**Coordinator pattern: independent per-section verification can be run as parallel workers.**
 
 ```
-최대 3라운드. P1=0 될 때까지.
-인프라: src/infra/lib/browser/ (Puppeteer + CDP)
+No round cap. Loop until P1=0 (or stuck → ask user).
+Infrastructure: src/infra/lib/browser/ (Puppeteer + CDP)
 
-1. 렌더링 스크린샷 캡처 → Figma 스크린샷과 pixelmatch 비교
+1. Capture rendered screenshot → pixelmatch comparison against Figma screenshot
    diffRatio > 0.1 → P1
-2. CSS 수치 비교: computed CSS vs tree.json 기대값
+2. CSS value comparison: computed CSS vs tree.json expected values
    delta > 4px → P1, ≤ 4px → P2
-3. 이미지·텍스트 누락 체크
-4. P1 우선 수정 (tree.json 참조, 추정 금지) → 컴파일 재검증 → 리로드
+3. Check for missing images and text
+4. Fix P1 issues first (refer to tree.json, no guessing) → revalidate compile → reload
+
+Narrowing scope (noise reduction):
+  Round 1: P1+P2+P3 all
+  Round 2: P1+P2
+  Round 3+: P1 only (continue until P1=0)
+
+Termination conditions:
+  ✅ Success: P1 = 0 AND no new findings → complete
+  ⚠️ Stuck: same findings as previous round → ask user
+      1. Provide direct resolution → retry next round
+      2. "proceed" — record remaining issues as TODO, complete
+      3. "abort" — halt workflow
+  ultrawork mode: on stuck, record TODO without prompting and complete
+
+Responsive: after MO verification, change viewport → same loop against PC screenshots
+Cleanup: shut down browser + dev server
+
+⛔ "Completion summary" output is only allowed after Phase 6 is complete (or user proceeds).
+```
+
+---
 
-반응형: MO 검증 후 viewport 변경 → PC 스크린샷과 동일 루프
-종료: 브라우저 + dev 서버 정리
+## Error Recovery
 
-⛔ Phase 6 완료 후에만 "완료 요약" 출력 허용.
-```
+| Failure | Recovery |
+|---------|----------|
+| figma-extract.js script error | Check Node.js version (>=18 required). Verify Figma API token in config. Retry once. |
+| figma-to-scss.js parse failure | Validate input tree.json structure. If malformed, re-run extract phase. |
+| figma-validate.js comparison failure | Skip automated validation, present screenshot side-by-side for manual review |
+| Puppeteer/CDP not available | Skip visual verification phase, rely on manual browser check |
+| Figma API rate limit (429) | Wait 60s and retry. If persistent, reduce node scope. |