@su-record/vibe 2.9.1 → 2.9.3

package/skills/vibe.figma.extract/SKILL.md

@@ -1,179 +1,219 @@
 ---
 name: vibe.figma.extract
-description: Figma REST API로 코드 생성 데이터 확보 — 트리(primary), 이미지, 스크린샷(검증용)
+description: Acquire code generation data via Figma REST API — tree (primary), images, screenshots (for validation)
 triggers: []
 tier: standard
 ---
 
-# vibe.figma.extract — 코드 생성 데이터 확보
+# vibe.figma.extract — Acquire Code Generation Data
 
-Figma REST API(`src/infra/lib/figma/`)를 사용하여 **구조적 코드 생성에 필요한 모든 데이터**를 추출.
+Uses the Figma REST API (`src/infra/lib/figma/`) to extract **all data needed for structural code generation**.
 
 ```
-추출 우선순위:
-  1순위: 노드 트리 + CSS (코드 생성의 PRIMARY 소스)
-  2순위: 이미지 에셋 (fill 이미지 + 아이템 노드 렌더링)
-  3순위: 스크린샷 (Phase 6 시각 검증용 — 코드 생성에 사용하지 않음)
+Extraction priority:
+  1st: Node tree + CSS (PRIMARY source for code generation)
+  2nd: Image assets (fill images + item node rendering)
+  3rd: Screenshots (for Phase 6 visual validation — not used for code generation)
 ```
 
 ---
 
-## 1. 노드 트리 + CSS — 코드 생성의 원천
+## 1. Node Tree + CSS — Source of Truth for Code Generation
 
 ```
 Bash:
-  node "[FIGMA_SCRIPT]" tree {fileKey} {nodeId} --depth=10
+  node "{{VIBE_PATH}}/hooks/scripts/figma-extract.js" tree {fileKey} {nodeId}
 
-반환 (FigmaNode JSON):
+Returns (FigmaNode JSON):
   {
     nodeId, name, type, size: { width, height },
     css: { display, flexDirection, gap, ... },
-    text: "텍스트 내용" (TEXT 노드만),
-    imageRef: "abc123" (이미지 fill),
+    text: "text content" (TEXT nodes only),
+    imageRef: "abc123" (image fill),
     imageScaleMode: "FILL" (FILL/FIT/CROP/TILE),
     layoutSizingH: "HUG" (FIXED/HUG/FILL),
     layoutSizingV: "FILL",
-    fills: [...] (2개 이상일 때만),
-    isMask: true (마스크 노드만),
+    fills: [...] (only when 2 or more),
+    isMask: true (mask nodes only),
     children: [...]
   }
 
-→ /tmp/{feature}/tree.json 에 저장
+→ Save to /tmp/{feature}/tree.json
 ```
 
-### Figma 속성 → CSS 직접 매핑표
+### Figma Property → CSS Direct Mapping Table
 
-트리 추출 도구가 자동 변환하는 속성. **이 값들이 SCSS에 직접 매핑된다:**
+Properties automatically converted by the tree extraction tool. **These values map directly to SCSS:**
 
-**레이아웃:**
+**Layout:**
 
-| Figma 속성 | CSS | vw 변환 |
+| Figma Property | CSS | vw conversion |
 |-----------|-----|---------|
-| `layoutMode=VERTICAL` | `display:flex; flex-direction:column` | ❌ |
-| `layoutMode=HORIZONTAL` | `display:flex; flex-direction:row` | ❌ |
-| `primaryAxisAlignItems` | `justify-content` | ❌ |
-| `counterAxisAlignItems` | `align-items` | ❌ |
-| `itemSpacing` | `gap` | ✅ |
-| `layoutGrow=1` | `flex-grow: 1` | ❌ |
-| `padding*` | `padding` | ✅ |
-| `absoluteBoundingBox.width/height` | `width/height` | ✅ |
-| `layoutPositioning=ABSOLUTE` | `position: absolute` + `top/left` (부모 상대 좌표) | ✅ |
-| `layoutSizingHorizontal=HUG` | width 삭제 (auto) | — |
-| `layoutSizingHorizontal=FILL` | 메타데이터 `layoutSizingH` (converter가 flex:1/100% 결정) | — |
-| `layoutSizingVertical=HUG` | height 삭제 (auto) | — |
-| `layoutSizingVertical=FILL` | 메타데이터 `layoutSizingV` (converter가 결정) | — |
-| `clipsContent` | `overflow: hidden` | ❌ |
-
-**비주얼:**
-
-| Figma 속성 | CSS | vw 변환 |
+| `layoutMode=VERTICAL` | `display:flex; flex-direction:column` | No |
+| `layoutMode=HORIZONTAL` | `display:flex; flex-direction:row` | No |
+| `primaryAxisAlignItems` | `justify-content` | No |
+| `counterAxisAlignItems` | `align-items` | No |
+| `itemSpacing` | `gap` | Yes |
+| `layoutGrow=1` | `flex-grow: 1` | No |
+| `padding*` | `padding` | Yes |
+| `absoluteBoundingBox.width/height` | `width/height` | Yes |
+| `layoutPositioning=ABSOLUTE` | `position: absolute` + `top/left` (relative to parent) | Yes |
+| `layoutSizingHorizontal=HUG` | remove width (auto) | — |
+| `layoutSizingHorizontal=FILL` | metadata `layoutSizingH` (converter decides flex:1/100%) | — |
+| `layoutSizingVertical=HUG` | remove height (auto) | — |
+| `layoutSizingVertical=FILL` | metadata `layoutSizingV` (converter decides) | — |
+| `clipsContent` | `overflow: hidden` | No |
+
+**Visual:**
+
+| Figma Property | CSS | vw conversion |
 |-----------|-----|---------|
-| `fills[].SOLID` | `background-color` | ❌ |
+| `fills[].SOLID` | `background-color` | No |
 | `fills[].IMAGE` | `imageRef` + `imageScaleMode` (FILL/FIT/CROP/TILE) | — |
-| `fills[].GRADIENT_LINEAR` | `background-image: linear-gradient(...)` | ❌ |
-| `fills[].GRADIENT_RADIAL` | `background-image: radial-gradient(...)` | ❌ |
-| `fills[] (2개 이상)` | `fills` 배열 (type, color, imageRef, gradient, blendMode, filters) | — |
-| `fills[].blendMode` | `background-blend-mode` | ❌ |
-| `fills[].filters.saturation` | `filter: grayscale(X%)` / `saturate(X%)` | ❌ |
-| `fills[].color` (TEXT) | `color` | ❌ |
-| `strokes[] + strokeAlign=INSIDE` | `border` + `box-sizing: border-box` | ✅ (width만) |
-| `strokes[] + strokeAlign=OUTSIDE` | `outline` | ✅ (width만) |
-| `individualStrokeWeights` | `border-top/right/bottom/left` 개별 | ✅ (width만) |
-| `strokeDashes` | `border-style: dashed` | ❌ |
-| `effects[].DROP_SHADOW` | `box-shadow` | ✅ (px만) |
-| `effects[].INNER_SHADOW` | `box-shadow` (inset) | ✅ (px만) |
-| `effects[].LAYER_BLUR` | `filter: blur()` (누적) | ✅ |
-| `effects[].BACKGROUND_BLUR` | `backdrop-filter: blur()` | ✅ |
-| `cornerRadius` | `border-radius` | ✅ |
-| `opacity` | `opacity` | ❌ |
-| `rotation` | `transform: rotate(Xdeg)` | ❌ |
-| `blendMode` (노드 레벨) | `mix-blend-mode` | ❌ |
-
-**텍스트:**
-
-| Figma 속성 | CSS | vw 변환 |
+| `fills[].GRADIENT_LINEAR` | `background-image: linear-gradient(...)` | No |
+| `fills[].GRADIENT_RADIAL` | `background-image: radial-gradient(...)` | No |
+| `fills[] (2 or more)` | `fills` array (type, color, imageRef, gradient, blendMode, filters) | — |
+| `fills[].blendMode` | `background-blend-mode` | No |
+| `fills[].filters.saturation` | `filter: grayscale(X%)` / `saturate(X%)` | No |
+| `fills[].color` (TEXT) | `color` | No |
+| `strokes[] + strokeAlign=INSIDE` | `border` + `box-sizing: border-box` | Yes (width only) |
+| `strokes[] + strokeAlign=OUTSIDE` | `outline` | Yes (width only) |
+| `individualStrokeWeights` | `border-top/right/bottom/left` individually | Yes (width only) |
+| `strokeDashes` | `border-style: dashed` | No |
+| `effects[].DROP_SHADOW` | `box-shadow` | Yes (px only) |
+| `effects[].INNER_SHADOW` | `box-shadow` (inset) | Yes (px only) |
+| `effects[].LAYER_BLUR` | `filter: blur()` (accumulated) | Yes |
+| `effects[].BACKGROUND_BLUR` | `backdrop-filter: blur()` | Yes |
+| `cornerRadius` | `border-radius` | Yes |
+| `opacity` | `opacity` | No |
+| `rotation` | `transform: rotate(Xdeg)` | No |
+| `blendMode` (node level) | `mix-blend-mode` | No |
+
+**Text:**
+
+| Figma Property | CSS | vw conversion |
 |-----------|-----|---------|
-| `style.fontFamily` | `font-family` | ❌ |
-| `style.fontSize` | `font-size` | ✅ |
-| `style.fontWeight` | `font-weight` | ❌ |
-| `style.lineHeightPx` | `line-height` | ❌ |
-| `style.letterSpacing` | `letter-spacing` | ✅ |
-| `style.textAlignHorizontal` | `text-align` | ❌ |
-| `style.textCase` | `text-transform` | ❌ |
-| `style.textTruncation` | `overflow: hidden; text-overflow: ellipsis` | ❌ |
-| `style.paragraphSpacing` | `margin-bottom` | ✅ |
-| `characters` | 텍스트 내용 | — |
+| `style.fontFamily` | `font-family` | No |
+| `style.fontSize` | `font-size` | Yes |
+| `style.fontWeight` | `font-weight` | No |
+| `style.lineHeightPx` | `line-height` | No |
+| `style.letterSpacing` | `letter-spacing` | Yes |
+| `style.textAlignHorizontal` | `text-align` | No |
+| `style.textCase` | `text-transform` | No |
+| `style.textTruncation` | `overflow: hidden; text-overflow: ellipsis` | No |
+| `style.paragraphSpacing` | `margin-bottom` | Yes |
+| `characters` | text content | — |
 
 ---
 
-## 2. 이미지 에셋 — 노드 렌더링 기반
+## 2. Image Assets — Node Rendering Based
 
 ```
-❌ imageRef 개별 다운로드 금지
-   → 텍스처 fill을 공유하는 경우 원본 텍스처(22.7MB)가 다운됨
-   → 노드 렌더링하면 해당 노드에 적용된 최종 결과물(364KB)이 나옴
+Do NOT download imageRef individually
+   → If a texture fill is shared, the original texture (22.7MB) will be downloaded
+   → Rendering the node produces the final result as applied to that node (364KB)
 
-✅ 모든 이미지는 Figma screenshot API로 노드 렌더링
+All images must be rendered as nodes via the Figma screenshot API
 ```
 
-### 2-1. BG 프레임 렌더링
+### 2-1. BG Frame Rendering
 
 ```
-BG 프레임 판별 기준:
-  - name에 "BG", "bg" 포함
-  - 또는 부모와 크기 동일(±10%) + 자식 이미지 3개 이상
+BG frame identification criteria:
+  - name contains "BG" or "bg"
+  - OR same size as parent (±10%) + 3 or more child images
 
-렌더링:
-  node "[FIGMA_SCRIPT]" screenshot {fileKey} {bg.nodeId} --out=/tmp/{feature}/bg/{section}-bg.webp
+Rendering:
+  node "{{VIBE_PATH}}/hooks/scripts/figma-extract.js" screenshot {fileKey} {bg.nodeId} --out=/tmp/{feature}/bg/{section}-bg.webp
 ```
 
-### 2-2. 콘텐츠 노드 렌더링
+### 2-2. Content Node Rendering
 
 ```
-대상 (tree.json에서 식별):
-  - 아이콘 (VECTOR/GROUP 크기 ≤ 64px)
-  - 아이템/보상 썸네일 (name에 "item", "reward", "token", "coin")
-  - 벡터 글자 GROUP (부모 아래 VECTOR 3개 이상, 각 <60px)
+Targets (identified from tree.json):
+  - Icons (VECTOR/GROUP size ≤ 64px)
+  - Item/reward thumbnails (name contains "item", "reward", "token", "coin")
+  - Vector text GROUPs (3 or more VECTORs under parent, each <60px)
+  - Design text (any of the following):
+    · TEXT node with 2 or more fills (gradient + solid overlap)
+    · TEXT node has effects (DROP_SHADOW, stroke)
+    · TEXT node fills contain GRADIENT type
+    · fontFamily not in project web fonts
+    → Must be included in rendering targets
+  - Decorative panels (wooden signs, metal plates, and other textured backgrounds)
+    → Render the same way as BG frames
 
-렌더링:
-  node "[FIGMA_SCRIPT]" screenshot {fileKey} {node.nodeId} --out=/tmp/{feature}/content/{name}.webp
+Rendering:
+  node "{{VIBE_PATH}}/hooks/scripts/figma-extract.js" screenshot {fileKey} {node.nodeId} --out=/tmp/{feature}/content/{name}.webp
 ```
 
-### 2-3. imageRef 다운로드 (폴백)
+### 2-3. imageRef Download (Fallback)
 
 ```
-노드 렌더링 불가 시에만 (API 실패, DOCUMENT 레벨):
-  파일 크기 5MB 초과 → 텍스처 fill 경고
+Only when node rendering is not possible (API failure, DOCUMENT level):
+  File size exceeds 5MB → texture fill warning
 ```
 
 ---
 
-## 3. 스크린샷 — Phase 6 검증 참조용
+## 3. Screenshots — Reference for Phase 6 Validation
 
 ```
-코드 생성에 사용하지 않는다.
+Not used for code generation.
 
-전체: screenshot → /tmp/{feature}/full-screenshot.webp
-섹션별: 1depth 자식 각각 → /tmp/{feature}/sections/{name}.webp
+Full: screenshot → /tmp/{feature}/full-screenshot.webp
+Per section: each 1-depth child → /tmp/{feature}/sections/{name}.webp
 ```
 
 ---
 
-## 4. 추출 데이터 정리
+## 4. Extracted Data Summary
 
 ```
 /tmp/{feature}/
-├── tree.json                    ← PRIMARY 소스
-├── bg/                          ← BG 프레임 렌더링
-├── content/                     ← 콘텐츠 노드 렌더링
-├── full-screenshot.webp          ← 검증용
-└── sections/                    ← 섹션별 검증용
-
-이미지 분류 요약:
-  | 분류 | 처리 |
+├── tree.json                    ← PRIMARY source
+├── bg/                          ← BG frame rendering
+├── content/                     ← Content node rendering
+├── full-screenshot.webp          ← For validation
+└── sections/                    ← Per-section validation
+
+Image classification summary:
+  | Category | Handling |
   |------|------|
-  | BG 프레임 | 프레임 렌더링 → bg/ |
-  | 벡터 글자 | GROUP 렌더링 → content/ |
-  | 콘텐츠 | 노드 렌더링 → content/ |
-  | 장식 | BG 렌더링에 포함 |
+  | BG frames | Frame rendering → bg/ |
+  | Design text | Node rendering → content/ |
+  | Vector text | GROUP rendering → content/ |
+  | Content | Node rendering → content/ |
+  | Decorative panels | Frame rendering → content/ |
+  | Decorations | Included in BG rendering |
 ```
+
+---
+
+## 5. Extraction Completion Validation (Required Before Entering Phase 3)
+
+```
+If any item is missing → re-extract (do NOT proceed to Phase 3)
+
+1. tree.json exists + root node children > 0
+2. BG for each section → file exists in bg/
+3. Design text check:
+   Traverse tree.json → generate list of TEXT nodes with 2 or more fills or effects
+   → All such nodes must have rendering files in content/
+4. Vector text check:
+   GROUP with 3 or more VECTORs → rendering file exists in content/
+5. Per-section validation screenshots → files exist in sections/
+6. File naming convention: all kebab-case (no hash filenames)
+```
+
+---
+
+## Error Recovery
+
+| Failure | Recovery |
+|---------|----------|
+| Figma API 401 (unauthorized) | Prompt user to set FIGMA_ACCESS_TOKEN in environment or ~/.vibe/config.json |
+| Figma API 404 (file not found) | Verify fileKey extracted from URL. Check if file is shared/accessible. |
+| Figma API 429 (rate limit) | Wait 60s, retry with reduced node scope (single page instead of full file) |
+| API timeout on large file | Split request by page — fetch one page at a time via nodeId parameter |
+| Screenshot download failure | Skip screenshot, proceed with tree.json only (mark visual verification as manual) |

package/skills/vibe.figma.extract/rubrics/image-rules.md

@@ -82,17 +82,29 @@ BG 프레임 = 다음 중 하나:
    - 웹폰트 없는 장식 타이틀 ("MISSION 01" 등)
    - VECTOR 타입으로 분해된 글자 → GROUP 렌더링
 
-2. 합성 배경 (BG 프레임):
+2. ⛔ 디자인 텍스트 (NEW — 그래디언트/스트로크/다중 효과 텍스트):
+   - TEXT 노드의 fills 2개 이상 (그래디언트+솔리드 중첩)
+   - TEXT 노드에 effects 있음 (DROP_SHADOW, stroke)
+   - TEXT 노드의 fills에 GRADIENT 타입 포함
+   - → 해당 TEXT 노드(또는 감싸는 GROUP)를 통째 렌더링
+   - → content/{section}-title.webp 등으로 저장
+   - ❌ CSS text-shadow/gradient로 근사치 구현 금지
+
+3. 합성 배경 (BG 프레임):
    - 눈, 나무, 파티클 등 장식 레이어 합성물
    - 텍스트 미포함 확인 필수
 
-3. 래스터 이미지 에셋:
+4. 래스터 이미지 에셋:
    - 게임 아이템 썸네일, 코인 아이콘 등
    - imageRef가 있는 개별 RECTANGLE/노드
 
-4. 복잡한 벡터 그래픽:
+5. 복잡한 벡터 그래픽:
    - CSS로 재현 불가능한 일러스트/아이콘
    - VECTOR/GROUP 조합의 복잡한 그래픽
+
+6. 장식 패널 배경 (목재 간판, 금속 플레이트 등):
+   - CSS로 재현 불가능한 텍스처/질감 배경
+   - → BG 프레임과 동일하게 렌더링 → background-image로 적용
 ```
 
 ## Format