@su-record/vibe 2.8.45 → 2.8.47

package/hooks/scripts/figma-extract.js

@@ -15,6 +15,7 @@
 import fs from 'fs';
 import path from 'path';
 import os from 'os';
+import { execFileSync } from 'child_process';
 
 // ─── Config ─────────────────────────────────────────────────────────
 
@@ -22,6 +23,39 @@ const FIGMA_API = 'https://api.figma.com/v1';
 const MAX_RETRIES = 3;
 const INITIAL_DELAY_MS = 2000;
 
+// ─── WebP 변환 ──────────────────────────────────────────────────────
+
+let _cwebpAvailable;
+function hasCwebp() {
+  if (_cwebpAvailable === undefined) {
+    try { execFileSync('cwebp', ['-version'], { stdio: 'ignore' }); _cwebpAvailable = true; }
+    catch { _cwebpAvailable = false; }
+  }
+  return _cwebpAvailable;
+}
+
+/** PNG 버퍼를 webp 파일로 저장. cwebp 없으면 png 폴백. */
+function writeAsWebp(pngBuf, outPath) {
+  if (!hasCwebp()) {
+    // cwebp 없으면 png 폴백
+    const fallback = outPath.replace(/\.webp$/, '.png');
+    fs.writeFileSync(fallback, pngBuf);
+    return fallback;
+  }
+  const tmpPng = outPath + '.tmp.png';
+  fs.writeFileSync(tmpPng, pngBuf);
+  try {
+    execFileSync('cwebp', ['-q', '85', tmpPng, '-o', outPath], { stdio: 'ignore' });
+    fs.unlinkSync(tmpPng);
+    return outPath;
+  } catch {
+    // 변환 실패 시 png 폴백
+    const fallback = outPath.replace(/\.webp$/, '.png');
+    fs.renameSync(tmpPng, fallback);
+    return fallback;
+  }
+}
+
 function loadToken() {
   if (process.env.FIGMA_ACCESS_TOKEN) return process.env.FIGMA_ACCESS_TOKEN;
   const configPath = path.join(os.homedir(), '.vibe', 'config.json');
@@ -178,11 +212,10 @@ async function cmdImages(token, fk, nid, outDir, depth) {
   for (const ref of refs) {
     const url = urls[ref];
     if (!url) continue;
-    const out = path.join(outDir, ref.slice(0,16) + '.png');
+    const outWebp = path.join(outDir, ref.slice(0,16) + '.webp');
     dl.push(fetch(url).then(r=>r.arrayBuffer()).then(b=>{
-      fs.writeFileSync(out, Buffer.from(b));
-      const sz = fs.statSync(out).size;
-      if (sz > 0) imageMap[ref] = out;
+      const actual = writeAsWebp(Buffer.from(b), outWebp);
+      if (fs.statSync(actual).size > 0) imageMap[ref] = actual;
     }).catch(()=>{}));
   }
   await Promise.all(dl);
@@ -200,8 +233,14 @@ async function cmdScreenshot(token, fk, nid, outPath) {
       const url = data.images?.[nid];
       if (!url) continue;
       const buf = Buffer.from(await (await fetch(url)).arrayBuffer());
-      fs.writeFileSync(outPath, buf);
-      console.log(JSON.stringify({ path: outPath, size: buf.length, scale }));
+      let finalPath = outPath;
+      if (outPath.endsWith('.webp')) {
+        finalPath = writeAsWebp(buf, outPath);
+      } else {
+        fs.writeFileSync(outPath, buf);
+      }
+      const sz = fs.statSync(finalPath).size;
+      console.log(JSON.stringify({ path: finalPath, size: sz, scale }));
       return;
     } catch (e) {
       if (scale === 1) fail(`Screenshot failed: ${e.message}`);
@@ -301,7 +340,7 @@ function toSCSS(node, prefix, indent = 0) {
 function buildImageNames(node, prefix, result = {}) {
   if (node.imageRef) {
     const name = nodeName(node, prefix);
-    result[node.imageRef] = name + '.png';
+    result[node.imageRef] = name + '.webp';
   }
   if (node.children) {
     for (const child of node.children) {
@@ -339,12 +378,12 @@ async function cmdRender(token, fk, nid, outDir, depth, scale) {
     for (const ref of refs) {
       const url = urls[ref];
       if (!url) continue;
-      const fileName = imageNames[ref] || ref.slice(0, 16) + '.png';
+      const fileName = imageNames[ref] || ref.slice(0, 16) + '.webp';
       const filePath = path.join(imgDir, fileName);
-      const publicPath = `images/${fileName}`;
       dl.push(fetch(url).then(r => r.arrayBuffer()).then(b => {
-        fs.writeFileSync(filePath, Buffer.from(b));
-        if (fs.statSync(filePath).size > 0) imageMap[ref] = publicPath;
+        const actual = writeAsWebp(Buffer.from(b), filePath);
+        const actualName = path.basename(actual);
+        if (fs.statSync(actual).size > 0) imageMap[ref] = `images/${actualName}`;
       }).catch(() => {}));
     }
     await Promise.all(dl);
@@ -353,7 +392,7 @@ async function cmdRender(token, fk, nid, outDir, depth, scale) {
   // 4. 복합 BG 노드 → 스크린샷으로 렌더링
   for (const child of tree.children || []) {
     if (/^(BG|bg|배경)$/i.test(child.name) && child.children?.length > 3) {
-      const bgName = `${sectionPrefix}-bg-composite.png`;
+      const bgName = `${sectionPrefix}-bg-composite.webp`;
       const bgPath = path.join(imgDir, bgName);
       try {
         for (const s of [2, 1]) {
@@ -361,12 +400,12 @@ async function cmdRender(token, fk, nid, outDir, depth, scale) {
           const sUrl = sData.images?.[child.nodeId];
           if (!sUrl) continue;
           const buf = Buffer.from(await (await fetch(sUrl)).arrayBuffer());
-          fs.writeFileSync(bgPath, buf);
-          if (buf.length > 0) {
-            imageMap[`__bg_${child.nodeId}`] = `images/${bgName}`;
-            // BG 노드의 imageRef를 합성 이미지로 교체
+          const actual = writeAsWebp(buf, bgPath);
+          const actualName = path.basename(actual);
+          if (fs.statSync(actual).size > 0) {
+            imageMap[`__bg_${child.nodeId}`] = `images/${actualName}`;
             child.imageRef = `__bg_${child.nodeId}`;
-            child.children = []; // 하위 제거 (합성됨)
+            child.children = [];
             break;
           }
         }
@@ -375,14 +414,15 @@ async function cmdRender(token, fk, nid, outDir, depth, scale) {
   }
 
   // 5. 스크린샷
-  const screenshotPath = path.join(outDir, `${sectionPrefix}-screenshot.png`);
+  const screenshotPath = path.join(outDir, `${sectionPrefix}-screenshot.webp`);
+  let actualScreenshot = screenshotPath;
   try {
     for (const s of [2, 1]) {
       const sData = await apiFetch(`/images/${fk}?ids=${nid}&format=png&scale=${s}`, token);
       const sUrl = sData.images?.[nid];
       if (!sUrl) continue;
       const buf = Buffer.from(await (await fetch(sUrl)).arrayBuffer());
-      fs.writeFileSync(screenshotPath, buf);
+      actualScreenshot = writeAsWebp(buf, screenshotPath);
       break;
     }
   } catch { /* screenshot failed */ }
@@ -405,7 +445,7 @@ async function cmdRender(token, fk, nid, outDir, depth, scale) {
       html: `${sectionPrefix}.html`,
       scss: `${sectionPrefix}.scss`,
       json: `${sectionPrefix}.json`,
-      screenshot: `${sectionPrefix}-screenshot.png`,
+      screenshot: path.basename(actualScreenshot),
     },
     images: imageMap,
     imageCount: Object.keys(imageMap).length,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@su-record/vibe",
-  "version": "2.8.45",
+  "version": "2.8.47",
   "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

@@ -355,7 +355,7 @@ URL 개수에 따른 처리:
 URL에서 fileKey, nodeId 추출
 
 1단계 — 전체 스크린샷 (정답 사진):
-  node "[FIGMA_SCRIPT]" screenshot {fileKey} {nodeId} --out=/tmp/{feature}/full-screenshot.png
+  node "[FIGMA_SCRIPT]" screenshot {fileKey} {nodeId} --out=/tmp/{feature}/full-screenshot.webp
 
 2단계 — 전체 트리 + CSS (수치 재료):
   node "[FIGMA_SCRIPT]" tree {fileKey} {nodeId} --depth=10
@@ -377,7 +377,7 @@ URL에서 fileKey, nodeId 추출
 
 4단계 — 섹션별 스크린샷 (부분 정답):
   트리의 1depth 자식 프레임 각각:
-    node "[FIGMA_SCRIPT]" screenshot {fileKey} {child.nodeId} --out=/tmp/{feature}/sections/{child.name}.png
+    node "[FIGMA_SCRIPT]" screenshot {fileKey} {child.nodeId} --out=/tmp/{feature}/sections/{child.name}.webp
 ```
 
 ### 2-1-multi. 멀티 프레임 재료 확보 (2개 이상 URL)
@@ -399,7 +399,7 @@ URL에서 fileKey, nodeId 추출
 결과:
   /tmp/{feature}/
   ├── frame-1/           ← 메인 페이지
-  │   ├── full-screenshot.png
+  │   ├── full-screenshot.webp
   │   ├── tree.json
   │   ├── images/
   │   └── sections/
@@ -417,17 +417,17 @@ Phase 2 완료 시 /tmp/{feature}/ 에 다음이 준비되어야 함:
 
 단일 URL:
 /tmp/{feature}/
-├── full-screenshot.png          ← 전체 정답 사진
+├── full-screenshot.webp          ← 전체 정답 사진
 ├── tree.json                    ← 노드 트리 + CSS 수치
 ├── images/                      ← 모든 이미지 에셋
-│   ├── hero-bg.png
-│   ├── hero-title.png
-│   ├── card-item-1.png
+│   ├── hero-bg.webp
+│   ├── hero-title.webp
+│   ├── card-item-1.webp
 │   └── ...
 └── sections/                    ← 섹션별 정답 사진
-    ├── hero.png
-    ├── daily-checkin.png
-    ├── playtime-mission.png
+    ├── hero.webp
+    ├── daily-checkin.webp
+    ├── playtime-mission.webp
     └── ...
 
 멀티 URL: 위 2-1-multi 결과 구조 참조
@@ -471,7 +471,7 @@ UI 요소 → vw 비례:
 
 ```
 1. 시각 비교 — 각 프레임의 스크린샷을 순차 Read:
-   - frame-1/full-screenshot.png → frame-2/full-screenshot.png → ...
+   - frame-1/full-screenshot.webp → frame-2/full-screenshot.webp → ...
    - 시각적으로 반복되는 요소 식별:
      상단 영역 (GNB/Header), 하단 영역 (Footer),
      카드 패턴, 버튼 스타일, 섹션 레이아웃
@@ -661,14 +661,20 @@ Phase 1에서 생성한 빈 SCSS 파일에 기본 내용 Write:
    → 스크린샷은 검증용으로만 참조
 
 2. 기계적 매핑 (추정 없음):
-   a. 이미지: 노드 렌더링된 이미지를 static/images/{feature}/에 배치
-   b. 노드 → HTML 매핑:
+   a. 이미지 vs HTML 판별 (각 노드마다 — vibe.figma.convert 체크리스트 참조):
+      - TEXT 자식 있음 → HTML (이미지에 텍스트 포함 금지)
+      - INSTANCE 반복 패턴 → HTML 반복 구조 (내부 이미지 에셋만 추출)
+      - 인터랙티브 요소 (btn, CTA) → HTML <button>
+      - 동적 데이터 (가격, 기간, 수량) → HTML 텍스트
+      - 위 모두 아님 → 이미지 렌더링 가능
+   b. 이미지: 판별 통과한 노드만 static/images/{feature}/에 배치
+   c. 노드 → HTML 매핑:
       - BG 프레임 → CSS background-image (img 태그 아님)
       - Auto Layout 있음 → <div> + flex (direction/gap/padding 직접)
       - Auto Layout 없음 → <div> + position:relative (자식 absolute)
       - TEXT 노드 → <span> (Claude가 h2/p/button으로 승격)
-      - 콘텐츠 이미지 → <img src="렌더링된 파일">
-      - 반복 패턴 (동일 구조 3+) → v-for
+      - 순수 이미지 에셋 → <img src="렌더링된 파일">
+      - 반복 패턴 (동일 구조 2+) → v-for (카드 내 이미지만 <img>, 나머지 HTML)
    c. CSS 직접 매핑:
       - node.css의 모든 속성을 SCSS에 1:1 매핑
       - vw/clamp 반응형 단위 변환 (vibe.figma.convert 참조)
@@ -696,7 +702,7 @@ Phase 1에서 생성한 빈 SCSS 파일에 기본 내용 Write:
     tree.json의 Auto Layout 구조를 HTML flex 레이아웃으로 직접 매핑.
     Claude가 시맨틱 태그로 승격 (div → section/h2/p/button).
     Phase 1의 기능 요소(v-for, @click, v-if) 보존.
-    이미지 경로: /images/{feature}/파일명.png (실제 파일 존재 확인)
+    이미지 경로: /images/{feature}/파일명.webp (실제 파일 존재 확인)
     텍스트: tree.json의 TEXT 노드 characters 값 그대로.
 
   <script setup>
@@ -870,15 +876,15 @@ import { captureScreenshot, compareScreenshots } from 'src/infra/lib/browser'
 각 섹션에 대해:
   1. 렌더링 결과 스크린샷 캡처:
      await captureScreenshot(page, {
-       outPath: '/tmp/{feature}/rendered-{section}.png',
+       outPath: '/tmp/{feature}/rendered-{section}.webp',
        selector: '.{section}Section',   // Phase 1에서 만든 클래스
      })
 
   2. Figma 원본과 픽셀 비교:
      const diff = await compareScreenshots(
-       '/tmp/{feature}/sections/{section}.png',    // Figma 원본
-       '/tmp/{feature}/rendered-{section}.png',    // 렌더링 결과
-       '/tmp/{feature}/diff-{section}.png',        // 차이 시각화
+       '/tmp/{feature}/sections/{section}.webp',    // Figma 원본
+       '/tmp/{feature}/rendered-{section}.webp',    // 렌더링 결과
+       '/tmp/{feature}/diff-{section}.webp',        // 차이 시각화
      )
 
   3. diff 이미지를 Read로 확인:

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

@@ -53,7 +53,7 @@ ROOT folder: `{{MO_FOLDER}}/`, `{{PC_FOLDER}}/`
 
 | Image | Local Path | Type | Render Method |
 |-------|-----------|------|--------------|
-| {{NAME}} | `/images/{{FEATURE_KEY}}/{{FILE_NAME}}.png` | {{bg\|content\|vector-text}} | {{frame-render\|node-render\|group-render}} |
+| {{NAME}} | `/images/{{FEATURE_KEY}}/{{FILE_NAME}}.webp` | {{bg\|content\|vector-text}} | {{frame-render\|node-render\|group-render}} |
 
 Total assets: {{ASSET_COUNT}} (BG 렌더링 {{BG_COUNT}}장 + 콘텐츠 {{CONTENT_COUNT}}장)
 

package/skills/vibe.figma/templates/remapped-tree.md

@@ -43,8 +43,8 @@ tree.json을 코드 생성에 최적화된 구조로 리매핑한다.
         "states": ["default"]
       },
       "bg": {
-        "mo": { "nodeId": "...", "file": "mo-main/bg/hero-bg.png" },
-        "pc": { "nodeId": "...", "file": "pc-main/bg/hero-bg.png" }
+        "mo": { "nodeId": "...", "file": "mo-main/bg/hero-bg.webp" },
+        "pc": { "nodeId": "...", "file": "pc-main/bg/hero-bg.webp" }
       },
       "size": {
         "mo": { "w": 720, "h": 1280 },
@@ -63,8 +63,8 @@ tree.json을 코드 생성에 최적화된 구조로 리매핑한다.
               "role": "title-image",
               "type": "node-render",
               "render": {
-                "mo": { "nodeId": "...", "file": "mo-main/content/hero-title.png", "size": { "w": 620, "h": 174 } },
-                "pc": { "nodeId": "...", "file": "pc-main/content/hero-title.png", "size": { "w": 1200, "h": 340 } }
+                "mo": { "nodeId": "...", "file": "mo-main/content/hero-title.webp", "size": { "w": 620, "h": 174 } },
+                "pc": { "nodeId": "...", "file": "pc-main/content/hero-title.webp", "size": { "w": 1200, "h": 340 } }
               },
               "alt": "추운 겨울, 따뜻한 보상이 펑펑"
             },
@@ -72,8 +72,8 @@ tree.json을 코드 생성에 최적화된 구조로 리매핑한다.
               "role": "subtitle-image",
               "type": "node-render",
               "render": {
-                "mo": { "nodeId": "...", "file": "mo-main/content/hero-subtitle.png", "size": { "w": 586, "h": 32 } },
-                "pc": { "nodeId": "...", "file": "pc-main/content/hero-subtitle.png", "size": { "w": 1100, "h": 60 } }
+                "mo": { "nodeId": "...", "file": "mo-main/content/hero-subtitle.webp", "size": { "w": 586, "h": 32 } },
+                "pc": { "nodeId": "...", "file": "pc-main/content/hero-subtitle.webp", "size": { "w": 1100, "h": 60 } }
               },
               "alt": "겨울을 녹일 보상, 지금 PC방에서 획득하세요!"
             }
@@ -93,8 +93,8 @@ tree.json을 코드 생성에 최적화된 구조로 리매핑한다.
           "role": "period-panel",
           "type": "content-with-bg",
           "bg": {
-            "mo": { "nodeId": "...", "file": "mo-main/bg/period-bg.png" },
-            "pc": { "nodeId": "...", "file": "pc-main/bg/period-bg.png" }
+            "mo": { "nodeId": "...", "file": "mo-main/bg/period-bg.webp" },
+            "pc": { "nodeId": "...", "file": "pc-main/bg/period-bg.webp" }
           },
           "size": {
             "mo": { "w": 720, "h": 500 },

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

@@ -68,9 +68,14 @@ component-index (/tmp/{feature}/component-index.json) 에서 매칭되는 컴포
      children 없음    → 빈 div 또는 스킵
 
 2. 배경 레이어 판별:
-   부모와 동일 크기(±5%) + imageRef 있음 + z-index 낮음
-     → position:absolute + inset:0 + object-fit:cover
-     → 부모에 position:relative + overflow:hidden 추가
+   BG 프레임 (name에 "BG"/"bg" 또는 부모와 동일 크기)
+     ❌ <img> 태그로 배경 처리 금지
+     ❌ position:absolute + inset:0 으로 이미지 배치 금지
+     ✅ 부모 요소에 CSS background-image로 처리:
+        background-image: url('/images/{feature}/{section}-bg.webp');
+        background-size: cover;
+        background-position: center top;
+     ✅ BG 프레임은 HTML에 아무것도 렌더링하지 않음 (CSS만)
 
 3. 반복 패턴 감지:
    같은 부모 아래 동일 타입 + 유사 구조(children 수 동일) 노드 3개 이상
@@ -192,6 +197,27 @@ tree.json의 css 객체를 SCSS로 직접 변환한다. 추정하지 않는다.
 
 ## 2. 외부 SCSS 파일 구조
 
+### _base.scss (필수 — 래퍼 컨테이너)
+
+```scss
+// 모바일 퍼스트: vw 단위가 PC에서 거대해지는 것을 방지
+// designWidth(720px)를 max-width로 제한
+
+.{feature} {
+  width: 100%;
+  max-width: 720px;    // designWidth — PC에서 모바일 레이아웃 유지
+  margin: 0 auto;      // 중앙 정렬
+  overflow-x: hidden;
+
+  // PC 브레이크포인트에서 max-width 확장 (PC 디자인이 있을 때)
+  @media (min-width: 1025px) {
+    max-width: 100%;   // PC 디자인이 있으면 전체 너비
+  }
+}
+```
+
+이 파일이 없으면 vw 단위가 PC 뷰포트에서 비례 확대되어 레이아웃이 깨진다.
+
 ### layout vs components 구분
 
 ```
@@ -305,8 +331,8 @@ $bp-desktop: 1024px;
   Hero (INSTANCE 720x1280)
   ├── BG (FRAME — 배경 레이어)
   ├── Title (FRAME — flex-column, gap:24px)
-  │   ├── Title (RECTANGLE — imageRef → title.png)
-  │   └── Sub Title (VECTOR — imageRef → subtitle.png)
+  │   ├── Title (RECTANGLE — imageRef → title.webp)
+  │   └── Sub Title (VECTOR — imageRef → subtitle.webp)
   ├── Period (FRAME — flex-column, gap:10px, padding)
   │   └── Period (FRAME — flex-column, gap:22px)
   │       ├── Period_Left (FRAME — flex-column, gap:4px)
@@ -319,17 +345,15 @@ $bp-desktop: 1024px;
 -->
 <template>
   <section class="heroSection">
-    <!-- BG: 부모와 동일 크기 + imageRef → 배경 레이어 -->
-    <div class="heroBg">
-      <img src="/images/{feature}/hero-bg.png" alt="" aria-hidden="true" />
-    </div>
+    <!-- BG: CSS background-image로 처리 (img 태그 아님!) -->
+    <!-- .heroSection { background-image: url('/images/{feature}/hero-bg.webp'); background-size: cover; } -->
 
     <!-- Title: flex-column, gap:24px → 직접 매핑 -->
     <div class="heroTitle">
-      <img src="/images/{feature}/title.png"
+      <img src="/images/{feature}/title.webp"
            alt="추운 겨울, 따뜻한 보상이 펑펑"
            class="heroTitleImg" />
-      <img src="/images/{feature}/subtitle.png"
+      <img src="/images/{feature}/subtitle.webp"
            alt="겨울을 녹일 보상, 지금 PC방에서 획득하세요!"
            class="heroSubtitleImg" />
     </div>
@@ -353,7 +377,7 @@ $bp-desktop: 1024px;
 
     <!-- BTN_Share: flex, borderRadius:500px → 버튼으로 승격 -->
     <button class="heroShareBtn" @click="handleShare">
-      <img src="/images/{feature}/share-icon.png" alt="공유하기" class="heroShareIcon" />
+      <img src="/images/{feature}/share-icon.webp" alt="공유하기" class="heroShareIcon" />
     </button>
   </section>
 </template>
@@ -407,9 +431,10 @@ function handleShare(): void {
 트리 노드의 속성으로 이미지 유형을 판별한다:
 
 배경 이미지:
-  조건: imageRef 있음 + 부모와 크기 동일(±5%) + 형제 중 가장 먼저 위치
-  매핑: position:absolute + inset:0 + z-index:0 + object-fit:cover
-  태그: <img alt="" aria-hidden="true" />
+  조건: BG 프레임 (name에 BG/bg 또는 부모와 크기 동일)
+  ❌ <img> 태그 금지
+  ✅ CSS background-image로만 처리:
+     부모 { background-image: url('...'); background-size: cover; }
 
 콘텐츠 이미지:
   조건: imageRef 있음 + 독립적 크기 + TEXT 형제 없음
@@ -441,7 +466,7 @@ function handleShare(): void {
 같은 값 → 유지
 다른 px 값 → @include pc { width: {desktop값 × pcScaleFactor}px; }
 다른 레이아웃 → @include pc { flex-direction: row; }
-다른 이미지 → @include pc { content: url(/images/{feature}/desktop-xxx.png); }
+다른 이미지 → @include pc { content: url(/images/{feature}/desktop-xxx.webp); }
 
 기존 모바일 코드 삭제 금지.
 ```

package/skills/vibe.figma.convert/rubrics/conversion-rules.md

@@ -21,9 +21,39 @@
 
 ## 배경 레이어 판별
 
-부모와 동일 크기(±5%) + imageRef + 형제 중 첫 위치:
-  → `position: absolute; inset: 0; z-index: 0; object-fit: cover`
-  → 부모에 `position: relative; overflow: hidden` 추가
+BG 프레임 (name에 "BG"/"bg" 또는 부모와 동일 크기 ±5%):
+  ❌ <img> 태그로 배경 처리 금지
+  ❌ position:absolute + inset:0 으로 이미지 배치 금지
+  ✅ 부모 요소에 CSS background-image로만 처리:
+     background-image: url('/images/{feature}/{section}-bg.webp');
+     background-size: cover;
+     background-position: center top;
+  ✅ BG 프레임은 HTML에 아무것도 렌더링하지 않음 (CSS만)
+
+## 이미지 vs HTML 판별 (각 노드마다 확인)
+
+```
+노드를 이미지로 처리하기 전에 반드시 확인:
+
+Q1. 이 노드에 TEXT 자식이 있는가?
+  YES → HTML로 구현 (텍스트는 이미지에 넣지 않는다)
+  NO → Q2로
+
+Q2. 이 노드가 INSTANCE 반복 패턴의 일부인가?
+  YES → HTML 반복 구조 (v-for/.map()) — 내부 이미지 에셋만 개별 추출
+  NO → Q3로
+
+Q3. 이 노드에 클릭/인터랙션이 필요한가? (btn, CTA, link, tab)
+  YES → HTML <button>/<a> — 이미지 금지
+  NO → Q4로
+
+Q4. 이 노드의 콘텐츠가 동적 데이터인가? (가격, 수량, 기간, 상태)
+  YES → HTML 텍스트 — 이미지 금지
+  NO → 이미지 렌더링 가능
+
+위 체크에서 하나라도 YES → HTML로 구현
+모두 NO → 이미지(벡터 글자, BG, 래스터, 복잡 그래픽)로 렌더링
+```
 
 ## CSS 직접 매핑 규칙
 

package/skills/vibe.figma.convert/templates/component.md

@@ -20,10 +20,8 @@ tree.json 노드를 기반으로 컴포넌트를 생성할 때 이 템플릿을
 -->
 <template>
   <section class="{{sectionName}}">
-    <!-- BG: 부모와 동일 크기 + imageRef → 배경 레이어 -->
-    <div class="{{sectionName}}__bg">
-      <img src="/images/{{FEATURE_KEY}}/{{bg-file}}.png" alt="" aria-hidden="true" />
-    </div>
+    <!-- BG: CSS background-image로 처리. img 태그 사용 금지! -->
+    <!-- SCSS: .{{sectionName}} { background-image: url('/images/{{FEATURE_KEY}}/{{bg-file}}.webp'); background-size: cover; } -->
 
     <!-- {{CHILD_1}}: tree flex-column, gap:{{GAP}}px → 직접 매핑 -->
     <div class="{{sectionName}}__{{child1Name}}">
@@ -88,7 +86,7 @@ defineProps<{
   width: 100%;
   height: {{HEIGHT_VW}}vw;               // tree: {{HEIGHT}} / {{DESIGN_WIDTH}} × 100
   overflow: hidden;                       // tree: overflow:hidden
-  background-image: url('/images/{{FEATURE_KEY}}/{{section}}-bg.png');
+  background-image: url('/images/{{FEATURE_KEY}}/{{section}}-bg.webp');
   background-size: cover;
   background-position: center top;
 }

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

@@ -99,32 +99,72 @@ Bash:
 ```
 각 섹션의 BG 프레임을 식별 → 합성된 배경 1장으로 렌더링:
 
+⚠️ 주의: BG 프레임만 렌더링한다 (텍스트 포함된 상위 프레임 렌더링 금지)
+  ❌ 섹션 전체를 렌더링 → 텍스트가 이미지에 포함 → HTML 텍스트와 중복
+  ❌ TEXT 자식이 있는 프레임을 렌더링 → 이미지 텍스트 + HTML 텍스트 이중 표시
+  ✅ BG 하위 프레임만 렌더링 → 텍스트 없는 배경만 → CSS background-image
+  ✅ 텍스트는 tree.json에서 추출하여 HTML로 작성
+
+  렌더링 전 TEXT 자식 검증 (BLOCKING):
+    BG 프레임의 전체 자식 트리를 순회하여 TEXT 노드 존재 여부 확인
+    TEXT 노드 발견 시:
+      → TEXT 노드가 포함된 하위 프레임은 렌더링에서 제외
+      → BG 프레임 내 순수 시각 요소(이미지, 벡터, 장식)만 렌더링
+      → 또는 TEXT가 없는 가장 깊은 BG 하위 프레임을 개별 렌더링
+
 BG 프레임 판별 기준:
   - name에 "BG", "bg" 포함
   - 또는 부모와 크기 동일(±10%) + 자식 이미지 3개 이상
   - 또는 1depth 첫 번째 자식이면서 이미지 노드 다수 보유
 
 렌더링:
-  node "[FIGMA_SCRIPT]" screenshot {fileKey} {bg.nodeId} --out=/tmp/{feature}/bg/{section}-bg.png
+  node "[FIGMA_SCRIPT]" screenshot {fileKey} {bg.nodeId} --out=/tmp/{feature}/bg/{section}-bg.webp
 
 → BG 하위 20+ 레이어가 합성된 1장
 → CSS background-image로 처리
 → 개별 레이어(눈, 나무, 파티클 등) 다운로드하지 않음
 ```
 
+### 2-1.5. 렌더링 금지 노드 (HTML로 구현할 것)
+
+```
+다음 조건에 해당하는 노드는 이미지로 렌더링하지 않는다:
+
+1. TEXT 자식 보유 프레임 → HTML로 구현
+   - 기간, 가격, 수량, 설명 등 텍스트 → HTML
+   - "1,000", "보상 교환하기", "2025.12.22" 등 → 이미지에 넣지 않음
+   - 텍스트가 이미지에 포함되면 수정/번역/접근성 불가
+
+2. INSTANCE 반복 패턴 (카드/아이템 그리드) → HTML 반복 구조
+   - 같은 부모 아래 동일 구조 INSTANCE 2개 이상
+   - ❌ 카드 그리드를 통째 이미지 1장으로 렌더링 금지
+   - ✅ 각 카드 내부의 이미지 에셋(아이콘, 썸네일)만 개별 추출
+   - ✅ 카드 레이아웃, 텍스트, 버튼은 HTML+CSS
+
+3. 인터랙티브 요소 → HTML <button>/<a>
+   - name에 "btn", "button", "CTA", "link" 포함
+   - 클릭 이벤트가 필요한 요소는 이미지 금지
+
+4. 정보 표시 영역 → HTML 텍스트
+   - 기간 표시 ("이벤트 기간", "교환/응모 종료일")
+   - 가격/수량 ("1,000", "500")
+   - 상태 표시 ("참여 대상", "로그인")
+```
+
 ### 2-2. 콘텐츠 노드 렌더링
 
 ```
 BG가 아닌 콘텐츠 이미지를 개별 노드 렌더링:
 
-대상 식별 (tree.json에서):
-  - 타이틀/서브타이틀 이미지 (name에 "title", "sub title")
-  - 버튼 이미지 (name에 "btn", "button")
+⚠️ 렌더링 전 2-1.5 체크 필수 — 하나라도 해당하면 이미지 렌더링 금지
+
+대상 식별 (tree.json에서 — TEXT 자식 미보유 노드만):
+  - 타이틀/서브타이틀 이미지 (name에 "title", "sub title") — 벡터 글자만, TEXT 노드 아님
   - 아이콘 (VECTOR/GROUP 크기 ≤ 64px)
-  - 아이템/보상 이미지 (name에 "item", "reward", "token", "coin")
+  - 아이템/보상 썸네일 (name에 "item", "reward", "token", "coin") — 이미지 에셋만
 
 렌더링 (imageRef 다운로드 아님!):
-  node "[FIGMA_SCRIPT]" screenshot {fileKey} {node.nodeId} --out=/tmp/{feature}/content/{name}.png
+  node "[FIGMA_SCRIPT]" screenshot {fileKey} {node.nodeId} --out=/tmp/{feature}/content/{name}.webp
 
 → 텍스처 fill이 적용된 최종 결과물이 나옴
 → 22.7MB 텍스처 대신 364KB 렌더링 이미지
@@ -142,7 +182,7 @@ BG가 아닌 콘텐츠 이미지를 개별 노드 렌더링:
 
 렌더링:
   부모 GROUP을 통째로 렌더링 (개별 글자 다운로드 금지)
-  node "[FIGMA_SCRIPT]" screenshot {fileKey} {group.nodeId} --out=/tmp/{feature}/content/{name}.png
+  node "[FIGMA_SCRIPT]" screenshot {fileKey} {group.nodeId} --out=/tmp/{feature}/content/{name}.webp
 
 예시:
   "MISSION 01" GROUP (174x42, 벡터 9개) → 렌더링 1장 (58KB)
@@ -168,10 +208,10 @@ BG가 아닌 콘텐츠 이미지를 개별 노드 렌더링:
 코드 생성에는 사용하지 않는다. Phase 4 시각 검증에서만 사용.
 
 전체 스크린샷:
-  node "[FIGMA_SCRIPT]" screenshot {fileKey} {nodeId} --out=/tmp/{feature}/full-screenshot.png
+  node "[FIGMA_SCRIPT]" screenshot {fileKey} {nodeId} --out=/tmp/{feature}/full-screenshot.webp
 
 섹션별 스크린샷 (1depth 자식 프레임 각각):
-  node "[FIGMA_SCRIPT]" screenshot {fileKey} {child.nodeId} --out=/tmp/{feature}/sections/{name}.png
+  node "[FIGMA_SCRIPT]" screenshot {fileKey} {child.nodeId} --out=/tmp/{feature}/sections/{name}.webp
 
 용도:
   ✅ Phase 4에서 렌더링 결과와 pixelmatch 비교
@@ -189,26 +229,26 @@ BG가 아닌 콘텐츠 이미지를 개별 노드 렌더링:
 /tmp/{feature}/
 ├── tree.json                    ← 코드 생성의 PRIMARY 소스
 ├── bg/                          ← BG 프레임 렌더링 (섹션당 1장)
-│   ├── hero-bg.png
-│   ├── daily-bg.png
+│   ├── hero-bg.webp
+│   ├── daily-bg.webp
 │   └── ...
 ├── content/                     ← 콘텐츠 노드 렌더링
-│   ├── hero-title.png
-│   ├── hero-subtitle.png
-│   ├── mission-01.png           ← 벡터 글자 그룹 렌더링
-│   ├── btn-login.png
+│   ├── hero-title.webp
+│   ├── hero-subtitle.webp
+│   ├── mission-01.webp           ← 벡터 글자 그룹 렌더링
+│   ├── btn-login.webp
 │   └── ...
-├── full-screenshot.png          ← Phase 4 검증용
+├── full-screenshot.webp          ← Phase 4 검증용
 └── sections/                    ← Phase 4 섹션별 검증용
-    ├── hero.png
+    ├── hero.webp
     └── ...
 
 이미지 분류 (실제 테스트 기준):
   | 분류 | 처리 | 예시 |
   |------|------|------|
-  | BG 프레임 (89개) | 프레임 렌더링 → bg/ | hero-bg.png (4.2MB) |
-  | 벡터 글자 (33개) | GROUP 렌더링 → content/ | mission-01.png (58KB) |
-  | 콘텐츠 (8개) | 노드 렌더링 → content/ | hero-title.png (364KB) |
+  | BG 프레임 (89개) | 프레임 렌더링 → bg/ | hero-bg.webp (4.2MB) |
+  | 벡터 글자 (33개) | GROUP 렌더링 → content/ | mission-01.webp (58KB) |
+  | 콘텐츠 (8개) | 노드 렌더링 → content/ | hero-title.webp (364KB) |
   | 장식 (29개) | BG 렌더링에 포함 | — |
   → 전체 159개 → 실제 파일 약 18장
 

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

@@ -11,9 +11,9 @@
 
 | 이미지 유형 | 렌더링 방법 | 출력 위치 |
 |-----------|-----------|---------|
-| BG 프레임 (합성 배경) | `screenshot {fileKey} {bg.nodeId}` | `bg/{section}-bg.png` |
-| 콘텐츠 (타이틀, 버튼) | `screenshot {fileKey} {node.nodeId}` | `content/{name}.png` |
-| 벡터 글자 그룹 | `screenshot {fileKey} {group.nodeId}` | `content/{name}.png` |
+| BG 프레임 (합성 배경) | `screenshot {fileKey} {bg.nodeId}` | `bg/{section}-bg.webp` |
+| 콘텐츠 (타이틀, 버튼) | `screenshot {fileKey} {node.nodeId}` | `content/{name}.webp` |
+| 벡터 글자 그룹 | `screenshot {fileKey} {group.nodeId}` | `content/{name}.webp` |
 
 ## BG 프레임 판별
 
@@ -39,18 +39,66 @@ BG 프레임 = 다음 중 하나:
 → 커스텀 폰트 텍스트 = 웹폰트 없음 → 이미지로 사용
 ```
 
+## 렌더링 금지 노드 (HTML로 구현해야 하는 것)
+
+```
+다음 조건에 해당하는 노드는 이미지로 렌더링하지 않는다 — HTML+CSS로 구현:
+
+1. TEXT 자식 보유 프레임:
+   프레임 내부에 TEXT 노드가 1개 이상 있으면 → HTML로 구현
+   ⚠️ BG 프레임 렌더링 시에도 TEXT 포함 여부 반드시 확인:
+     - BG 프레임에 TEXT 자식이 있으면 → BG 하위만 렌더링 (TEXT 제외)
+     - 텍스트 포함된 상위 프레임을 통째 렌더링하면 → 이미지 텍스트 + HTML 텍스트 이중 표시
+
+2. INSTANCE 반복 패턴 (카드/아이템 그리드):
+   같은 부모 아래 동일 구조 INSTANCE 2개 이상 → HTML 반복 구조 (v-for/.map())
+   ❌ 카드 그리드를 통째 이미지 1장으로 렌더링 금지
+   ✅ 각 카드 내부의 이미지 에셋만 개별 추출 (아이콘, 아이템 이미지)
+   ✅ 카드 레이아웃, 텍스트, 버튼은 HTML로 구현
+
+3. 인터랙티브 요소:
+   name에 "btn", "button", "CTA", "link", "tab", "toggle" 포함 → HTML <button>/<a>
+   ❌ 버튼을 이미지로 렌더링 금지 (클릭 이벤트 불가)
+
+4. 정보 텍스트 영역:
+   기간, 가격, 수량, 설명 등 변경 가능 데이터 → HTML 텍스트
+   ❌ "1,000", "500 G-COIN", "보상 교환하기" 등을 이미지에 포함 금지
+```
+
+## 이미지로 렌더링하는 것 (HTML로 구현 불가)
+
+```
+다음만 이미지로 렌더링:
+
+1. 커스텀 폰트 텍스트 (벡터 글자 그룹):
+   - 웹폰트 없는 장식 타이틀 ("MISSION 01" 등)
+   - VECTOR 타입으로 분해된 글자 → GROUP 렌더링
+
+2. 합성 배경 (BG 프레임):
+   - 눈, 나무, 파티클 등 장식 레이어 합성물
+   - 텍스트 미포함 확인 필수
+
+3. 래스터 이미지 에셋:
+   - 게임 아이템 썸네일, 코인 아이콘 등
+   - imageRef가 있는 개별 RECTANGLE/노드
+
+4. 복잡한 벡터 그래픽:
+   - CSS로 재현 불가능한 일러스트/아이콘
+   - VECTOR/GROUP 조합의 복잡한 그래픽
+```
+
 ## Format
 
-- Output format: `.png` (Figma screenshot API 기본)
-- 최적화 필요 시 빌드 단계에서 webp 변환 (추출 단계에서는 png)
+- Output format: `.webp` (Figma API에서 png 수신 → cwebp로 webp 변환)
+- cwebp 미설치 시 `.png` 폴백
 
 ## Naming
 
 렌더링된 이미지의 파일명 = Figma 노드 name을 kebab-case로:
-  - `"Hero"` BG frame → `hero-bg.png`
-  - `"Mission 01"` vector group → `mission-01.png`
-  - `"Title"` content → `hero-title.png` (섹션명 prefix)
-  - `"Btn_Login"` → `btn-login.png`
+  - `"Hero"` BG frame → `hero-bg.webp`
+  - `"Mission 01"` vector group → `mission-01.webp`
+  - `"Title"` content → `hero-title.webp` (섹션명 prefix)
+  - `"Btn_Login"` → `btn-login.webp`
 
 Rules:
   - 공백 → 하이픈