@su-record/vibe 2.8.23 → 2.8.25

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

@@ -7,7 +7,182 @@ tier: standard
 
 # vibe-figma-convert — 코드 변환
 
-`get_design_context` 참조 코드를 프로젝트 스택 코드 + 외부 SCSS 파일로 변환.
+`get_design_context` 참조 코드를 프로젝트 스택 코드로 변환.
+**두 가지 모드**: 일반 모드(외부 SCSS) / 직역 모드(scoped CSS).
+
+---
+
+## 0. 직역 모드 (비정형 레이어)
+
+비정형 레이어 감지 시 사용. 참조 코드의 구조와 좌표를 **거의 그대로** 보존.
+
+### 핵심 원칙
+
+```
+1. 참조 코드의 HTML 중첩 구조를 1:1로 유지
+2. absolute 좌표, rotate, mix-blend-mode, blur 등 시각 속성 전부 보존
+3. scaleFactor는 px 값에만 적용 (색상, opacity, blend-mode, z-index 미적용)
+4. 에셋 URL → 로컬 경로로만 교체
+5. 의미론적 재구성(BG+Content 분리) 시도하지 않음
+```
+
+### Tailwind → CSS 클래스 직역
+
+```
+참조 코드의 각 요소에 고유 클래스명을 부여하고,
+Tailwind 클래스를 CSS로 1:1 변환하여 <style scoped>에 작성.
+
+클래스명 규칙: data-name 또는 data-node-id 기반
+  data-name="BG"           → .bg
+  data-name="Period"       → .period
+  data-name="Title"        → .title
+  data-name="Light"        → .light
+  이름 없으면              → .node-{nodeId} (콜론→하이픈)
+
+변환 예시:
+  className="absolute h-[1280px] left-0 overflow-clip top-0 w-[720px]"
+  →
+  .bg {
+    position: absolute;
+    height: 853px;       /* 1280 × 0.667 */
+    left: 0;
+    overflow: clip;
+    top: 0;
+    width: 100%;         /* 720px = 뷰포트 전체폭 → 100% */
+  }
+
+  className="-translate-x-1/2 absolute h-[174px] left-1/2 top-1/2 w-[620px]"
+  →
+  .title-img {
+    position: absolute;
+    height: 116px;       /* 174 × 0.667 */
+    left: 50%;
+    top: 50%;
+    transform: translateX(-50%);
+    width: 413px;        /* 620 × 0.667 */
+  }
+```
+
+### 특수 패턴 직역
+
+```
+mix-blend:
+  className="mix-blend-lighten"
+  → mix-blend-mode: lighten;
+
+rotate + scale:
+  className="-scale-y-100 rotate-[149.7deg]"
+  → transform: scaleY(-1) rotate(149.7deg);
+
+mask-image:
+  style={{ maskImage: `url('${imgVar}')` }}
+  → :style="{ maskImage: `url('/images/{feature}/파일.webp')` }"
+  (Vue 동적 바인딩으로 변환)
+
+blur:
+  className="blur-[3.5px]"
+  → filter: blur(3.5px);
+
+소수점 좌표:
+  className="absolute h-[141.67px] left-[380.52px] top-[528.95px]"
+  → position: absolute;
+    height: 94px;        /* 141.67 × 0.667 반올림 */
+    left: 254px;         /* 380.52 × 0.667 반올림 */
+    top: 353px;          /* 528.95 × 0.667 반올림 */
+
+inset-[-18.13%]:
+  → inset: -18.13%; (% 값은 스케일링 안 함)
+
+overflow-hidden + 스프라이트:
+  className="absolute h-full left-[-129.09%] max-w-none top-0 w-[229.09%]"
+  → position: absolute;
+    height: 100%;
+    left: -129.09%;      /* % 값 그대로 */
+    max-width: none;
+    top: 0;
+    width: 229.09%;      /* % 값 그대로 */
+```
+
+### Vue SFC 출력 형태
+
+```vue
+<template>
+  <section class="heroSection">
+    <!-- 참조 코드의 HTML 구조를 1:1 유지 -->
+    <div class="bg">
+      <div class="bgInner">
+        <div class="bgImage1">
+          <img src="/images/{feature}/bg.webp" alt="" aria-hidden="true" />
+        </div>
+        <div class="tree4">
+          <img src="/images/{feature}/tree-4.webp" alt="" aria-hidden="true" />
+        </div>
+        <!-- ... 모든 서브 레이어 유지 -->
+      </div>
+      <!-- ... -->
+    </div>
+
+    <!-- 콘텐츠 영역 (참조 코드의 Title, Period 등) -->
+    <div class="titleArea">
+      <div class="titleImg">
+        <img src="/images/{feature}/title.webp" alt="추운 겨울, 따뜻한 보상이 펑펑" />
+      </div>
+    </div>
+  </section>
+</template>
+
+<script setup lang="ts">
+// Phase 1의 script 보존
+</script>
+
+<style scoped>
+.heroSection {
+  position: relative;
+  width: 100%;
+  height: 853px; /* 1280 × 0.667 */
+  overflow: hidden;
+}
+.bg {
+  position: absolute;
+  height: 853px;
+  left: 0;
+  overflow: clip;
+  top: 0;
+  width: 100%;
+}
+.tree4 {
+  position: absolute;
+  bottom: 215px;
+  height: 453px;
+  left: 50%;
+  transform: translateX(calc(-50% + 599px));
+  opacity: 0.4;
+  width: 1727px;
+}
+.tree4 img {
+  position: absolute;
+  inset: 0;
+  max-width: none;
+  object-fit: cover;
+  pointer-events: none;
+  width: 100%;
+  height: 100%;
+}
+/* ... 모든 레이어의 CSS */
+</style>
+```
+
+### 직역 모드에서의 반응형
+
+```
+첫 번째 URL → <style scoped>에 base 스타일
+두 번째 URL → 같은 <style scoped> 안에 @media (min-width:) 추가
+기존 스타일 삭제 금지
+```
+
+---
+
+## 이하: 일반 모드 (정형 레이어)
 
 ---
 

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

@@ -0,0 +1,83 @@
+# React+Tailwind → Project Stack Conversion Rules
+
+## Mode Selection (Do This First)
+
+Classify each section before writing any code. Literal mode if ANY of:
+- 15+ asset URLs in the section
+- Fractional coordinates (`left-[117.13px]`)
+- `mix-blend-*` on any layer
+- `rotate-[Ndeg]` or `-scale-y-100`
+- `mask-image` usage
+- `blur-[Npx]` filter
+- BG cropped from 2560px+ source
+
+Normal mode only when ALL of:
+- Flex/grid layout, no absolute coordinates (or integer-only)
+- Fewer than 10 asset URLs
+- No blend/rotate/mask/blur
+
+## Normal Mode Rules
+
+- Extract CSS values from Tailwind classes — never estimate
+- Apply `scaleFactor` to all `px` values; never to colors, opacity, z-index, line-height (unitless)
+- Put layout properties in `layout/_section.scss`, visual/text properties in `components/_section.scss`
+- No `<style>` block in the component file
+- No inline `style=""` attribute in the template
+
+## Literal Mode Rules
+
+- Preserve the full HTML nesting structure 1:1
+- Keep all absolute coordinates, fractional px values (rounded after scaling)
+- Keep all `mix-blend-mode`, `rotate`, `mask-image`, `blur` values unchanged
+- Put all styles in `<style scoped>` inside the component
+- Do not create external SCSS files for literal sections
+
+## Tailwind Class Gotchas
+
+| Tailwind | Correct CSS | Common Mistake |
+|----------|------------|----------------|
+| `size-full` | `width: 100%; height: 100%` | Only setting `width: 100%` |
+| `inset-0` | `inset: 0` (shorthand) | Expanding to 4 properties |
+| `inset-[-18.13%]` | `inset: -18.13%` | Scaling the % value |
+| `overflow-clip` | `overflow: clip` | Using `overflow: hidden` |
+| `leading-[1.4]` | `line-height: 1.4` | Applying scaleFactor |
+| `max-w-none` | `max-width: none` | Omitting entirely |
+| `object-cover` on `<img>` | `object-fit: cover` + parent `overflow: hidden` | Forgetting parent clip |
+| `pointer-events-none` | `pointer-events: none` | Omitting for decorative layers |
+| `text-white` | `color: #FFFFFF` | Using `color: white` |
+| `font-black` | `font-weight: 900` | Using `font-weight: bold` |
+
+## Scale Application
+
+Apply `× scaleFactor` to:
+- `px` sizes: font-size, padding, margin, gap, border-radius, width, height, top, left, bottom, right
+- `px` in box-shadow, blur filter, letter-spacing
+
+Do NOT scale:
+- Color values
+- Opacity values
+- `%` values
+- Unitless line-height
+- z-index
+- `mix-blend-mode` values
+- `rotate` degree values
+
+## Sprite / Overflow Image Pattern
+
+When `left` is a large negative %, it is a sprite crop — do NOT scale:
+```css
+/* Correct */
+left: -129.09%;
+width: 229.09%;
+
+/* Wrong — do not scale % values */
+left: -86.09%; /* -129.09 × 0.667 — incorrect */
+```
+
+## Class Naming (Literal Mode)
+
+Source priority: `data-name` attribute → `data-node-id`
+- `data-name="BG"` → `.bg`
+- `data-name="Light"` → `.light`
+- No `data-name` → `.node-{nodeId}` (replace `:` with `-`)
+- Conflicts: append parent name prefix (`.heroLight`, `.kidLight`)

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

@@ -0,0 +1,152 @@
+# Component Output Template
+
+Use this template when generating a section component from Figma reference code.
+
+---
+
+## Normal Mode (External SCSS)
+
+```vue
+<!-- components/{{FEATURE_KEY}}/{{ComponentName}}.vue -->
+<template>
+  <section class="{{sectionName}}">
+    <!-- BG Layer (if section has background image) -->
+    <div class="{{sectionName}}Bg">
+      <img src="/images/{{FEATURE_KEY}}/{{bg-file}}.webp" alt="" aria-hidden="true" />
+    </div>
+
+    <!-- Content Layer -->
+    <div class="{{sectionName}}Content">
+      <!-- Title image (if present) -->
+      <div class="{{sectionName}}Title">
+        <img src="/images/{{FEATURE_KEY}}/{{title-file}}.webp" alt="{{TITLE_ALT_TEXT}}" />
+      </div>
+
+      <!-- Repeating items (from storyboard mock data) -->
+      <ul class="{{sectionName}}List">
+        <li
+          v-for="item in items"
+          :key="item.id"
+          class="{{sectionName}}Item"
+        >
+          <img :src="item.image" :alt="item.label" />
+          <p class="{{sectionName}}ItemLabel">{{ item.label }}</p>
+        </li>
+      </ul>
+
+      <!-- CTA Button -->
+      <button class="{{sectionName}}Btn" @click="handleAction">
+        {{BUTTON_LABEL}}
+      </button>
+    </div>
+  </section>
+</template>
+
+<script setup lang="ts">
+/**
+ * {{SECTION_DISPLAY_NAME}}
+ *
+ * [기능 정의]
+ * - {{FEATURE_REQUIREMENT_1}}
+ * - {{FEATURE_REQUIREMENT_2}}
+ *
+ * [인터랙션]
+ * ① {{INTERACTION_1}}
+ * ② {{INTERACTION_2}}
+ *
+ * [상태] {{STATE_LIST}}
+ */
+
+interface {{ItemType}} {
+  id: number
+  label: string
+  image: string
+}
+
+const items: {{ItemType}}[] = [
+  { id: 1, label: '{{MOCK_LABEL_1}}', image: '/images/{{FEATURE_KEY}}/{{mock-img-1}}.webp' },
+  { id: 2, label: '{{MOCK_LABEL_2}}', image: '/images/{{FEATURE_KEY}}/{{mock-img-2}}.webp' },
+  { id: 3, label: '{{MOCK_LABEL_3}}', image: '/images/{{FEATURE_KEY}}/{{mock-img-3}}.webp' },
+]
+
+const emit = defineEmits<{
+  action: []
+}>()
+
+function handleAction(): void {
+  // TODO: {{ACTION_DESCRIPTION}}
+  emit('action')
+}
+</script>
+<!-- styles: styles/{{FEATURE_KEY}}/layout/_{{section}}.scss + components/_{{section}}.scss -->
+```
+
+---
+
+## Literal Mode (Scoped CSS)
+
+```vue
+<!-- components/{{FEATURE_KEY}}/{{ComponentName}}.vue -->
+<template>
+  <section class="{{sectionName}}">
+    <!-- 1:1 structure from reference code — preserve all nesting -->
+    <div class="bg">
+      <img src="/images/{{FEATURE_KEY}}/{{bg-file}}.webp" alt="" aria-hidden="true" />
+    </div>
+    <div class="titleArea">
+      <img src="/images/{{FEATURE_KEY}}/{{title-file}}.webp" alt="{{TITLE_ALT_TEXT}}" />
+    </div>
+    <!-- Re-insert Phase 1 functional elements at appropriate positions -->
+    <button class="ctaBtn" @click="handleAction">{{BUTTON_LABEL}}</button>
+  </section>
+</template>
+
+<script setup lang="ts">
+/**
+ * {{SECTION_DISPLAY_NAME}}
+ * [기능 정의] {{FEATURE_REQUIREMENT_1}}
+ * [인터랙션] ① {{INTERACTION_1}}
+ * [상태] {{STATE_LIST}}
+ */
+
+function handleAction(): void {
+  // TODO: {{ACTION_DESCRIPTION}}
+}
+</script>
+
+<style scoped>
+.{{sectionName}} {
+  position: relative;
+  width: 100%;
+  height: {{SECTION_HEIGHT_SCALED}}px; /* {{SECTION_HEIGHT_ORIGINAL}} × {{SCALE_FACTOR}} */
+  overflow: hidden;
+}
+
+.bg {
+  position: absolute;
+  inset: 0;
+}
+
+.bg img {
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+}
+
+.titleArea {
+  position: absolute;
+  top: {{TITLE_TOP_SCALED}}px;    /* {{TITLE_TOP_ORIGINAL}} × {{SCALE_FACTOR}} */
+  left: 50%;
+  transform: translateX(-50%);
+  width: {{TITLE_WIDTH_SCALED}}px;
+  height: {{TITLE_HEIGHT_SCALED}}px;
+}
+
+/* {{RESPONSIVE_BREAKPOINT}} */
+@media (min-width: {{BP_PC}}px) {
+  .{{sectionName}} {
+    height: {{SECTION_HEIGHT_PC_SCALED}}px;
+  }
+}
+</style>
+```

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

@@ -0,0 +1,67 @@
+# Image Extraction Rules
+
+## Format
+
+- Output format: `.webp` always — never `.png`, `.jpg`, `.svg` from MCP asset URLs
+- Exception: SVG icons referenced as inline code (not MCP URLs) stay as `.svg`
+- Do not convert or re-encode after download — use the raw bytes from `curl`
+
+## Naming
+
+Convert the JavaScript variable name to kebab-case:
+
+| Variable | File Name |
+|----------|-----------|
+| `img21` | `img-21.webp` |
+| `imgTitle` | `title.webp` (strip leading `img` prefix) |
+| `imgSnowParticle12` | `snow-particle-12.webp` |
+| `imgImgBannerStatic` | `banner-static.webp` (collapse double `img`) |
+| `imgBtnShare` | `btn-share.webp` |
+
+Rules:
+- Strip leading `img` prefix before converting to kebab-case
+- Numbers stay as-is: `item11` → `item-11`
+- Acronyms lowercased: `BTN` → `btn`, `BG` → `bg`
+
+## Destination
+
+```
+public/images/{feature}/    ← Vue/Nuxt
+static/images/{feature}/    ← Nuxt 2 legacy
+public/{feature}/           ← Next.js (under /public)
+```
+
+Always use the directory confirmed in Phase 0 setup.
+
+## Size Limits
+
+| Type | Warn threshold | Block threshold |
+|------|---------------|----------------|
+| Background image | 500 KB | 2 MB |
+| Content image | 200 KB | 1 MB |
+| Decorative image | 100 KB | 500 KB |
+| Total per section | 3 MB | 10 MB |
+
+If a file exceeds the warn threshold, log it. Never block the download — size checks are advisory.
+
+## Download Rules
+
+- [ ] Download ALL `const img...` variables — zero omissions ("core assets only" is forbidden)
+- [ ] Use `curl -sL "{url}" -o {dest}` — silent, follow redirects
+- [ ] After download: `ls -la {dir}` — verify file exists and size > 0
+- [ ] On 0-byte file: retry once. On second failure: log and continue (do not block code gen for a single failed decorative image)
+- [ ] On missing asset (visible in screenshot but no URL): use `get_metadata` → sub-node `get_design_context` → `get_screenshot` fallback chain
+
+## Image Mapping Table
+
+After all downloads, produce a mapping before writing any component code:
+
+```js
+const imageMap = {
+  imgTitle: '/images/{feature}/title.webp',
+  img21:    '/images/{feature}/img-21.webp',
+  // ...every variable
+}
+```
+
+This map is the only source for `src` values in generated components. No raw Figma URLs in output code.

package/skills/vibe-figma-frame/rubrics/frame-selection.md

@@ -0,0 +1,55 @@
+# Frame Selection Rubric
+
+> This skill is merged into vibe-figma-extract. Use this rubric to select the right frames before calling `get_design_context`.
+
+## Frame Classification by Name Pattern
+
+| Pattern in Name | Class | Action |
+|----------------|-------|--------|
+| "기능 정의서", "정책", "spec", "policy" | SPEC | `get_design_context` — extract text requirements |
+| "해상도", "브라우저", "config", "resolution" | CONFIG | `get_design_context` — extract scale factor |
+| "공통", "GNB", "Footer", "Popup", "shared", "common" | SHARED | Read if referenced; skip if project already has them |
+| "화면설계", "메인 -", "section", numbered frames | PAGE | Core implementation targets |
+
+## Selection Priority
+
+1. SPEC frame (1 frame) — read first, informs all feature requirements
+2. CONFIG frame (1 frame) — establishes scale factors for both breakpoints
+3. PAGE frames — top-level only (e.g. `3.1`, `3.2`, not `3.1.1`, `3.1.2`)
+4. SHARED frames — only if component does not already exist in the project
+
+Never read sub-case frames (e.g. `3.1.1`, `3.2.1`) during Phase 1. Read them in Phase 2 only if a sub-state is needed for a specific interaction.
+
+## Tall Frame Decision Tree
+
+```
+Frame height > 1500px?
+  YES → Split before calling get_design_context
+    1. get_metadata(nodeId) → get child node list
+    2. Call get_design_context per child node
+    3. Merge results as one logical section
+  NO → Call get_design_context directly
+```
+
+Height thresholds from real data:
+- Safe direct call: up to ~900px
+- Risk zone: 900–1500px (attempt once, split on timeout)
+- Always split: 1500px+
+
+## Skipping Frames
+
+Skip a frame entirely when:
+- Name contains "OLD", "archive", "deprecated", "참고", "예시" (reference only)
+- Frame is a copy/duplicate of another already processed frame
+- Frame is a component definition (Figma component, not an instance) — use its instances instead
+
+## Viewport Frames
+
+When multiple frames represent the same section at different widths:
+- Smallest width = mobile (Phase 2 base URL)
+- Larger widths = desktop breakpoints (Phase 2 subsequent URLs)
+- Process mobile first, then add desktop as responsive layer — never the reverse
+
+## Frame Count Warning
+
+If total PAGE frames > 10, confirm with the user before proceeding. Large frame counts may indicate the Figma file covers multiple pages that should be separate feature implementations.

package/skills/vibe-figma-pipeline/rubrics/pipeline-stages.md

@@ -0,0 +1,96 @@
+# Pipeline Stage Descriptions and Failure Handling
+
+> This skill is merged into vibe-figma-consolidate (D-4). This rubric describes each stage of the Figma-to-code pipeline and what to do when a stage fails.
+
+## Stage Map
+
+```
+Phase 0: Setup
+  └─ Detect stack → Determine feature key → Create directories
+
+Phase 1: Storyboard
+  └─ Classify frames → Analyze SPEC/CONFIG/PAGE → Generate component shells
+
+Phase 2: Design (per breakpoint)
+  ├─ 2-1: Style scaffold
+  ├─ 2-2: Classify mode (normal/literal) per section
+  ├─ 2-3: Split tall frames if needed
+  └─ 2-4: Section loop
+       ├─ a. get_design_context
+       ├─ b. Download all assets
+       ├─ c. Convert code
+       ├─ d. Refactor component template
+       └─ e. Verify section
+
+Phase 3: Verification
+  ├─ Automated grep checks
+  └─ Screenshot comparison
+```
+
+## Stage Failure Handling
+
+### Phase 0 Failures
+
+| Failure | Resolution |
+|---------|-----------|
+| Cannot detect stack | Ask user: "Vue or React? SCSS or Tailwind?" |
+| Directory already exists | Proceed — do not overwrite existing files unless replacing |
+
+### Phase 1 Failures
+
+| Failure | Resolution |
+|---------|-----------|
+| Metadata too large (>100K chars) | Save to file, parse with Bash/Python to extract frame list |
+| No SPEC frame found | Continue without feature requirements; note missing in report |
+| No CONFIG frame | Use default scale factors (mobile: 480/720=0.667, PC: 1920/2560=0.75) |
+| Storyboard URL is "없음" | Skip Phase 1, go directly to Phase 2 |
+
+### Phase 2-a Failures (get_design_context)
+
+| Failure | Retry | Escalation |
+|---------|-------|-----------|
+| Timeout on first call | Retry once with `excludeScreenshot: true` | Split frame → per-child calls |
+| Timeout after split | Retry individual child once | `get_screenshot` + visual estimation |
+| Empty response | Retry once | Skip section, log in consolidation report |
+
+Maximum retries per section: 2. After 2 failures: use screenshot fallback. Never loop more than 3 times on the same section.
+
+### Phase 2-b Failures (Asset Download)
+
+| Failure | Resolution |
+|---------|-----------|
+| 0-byte file | Retry once with same curl command |
+| 404 URL | Try `get_metadata` → sub-node → `get_design_context` for fresh URL |
+| All retries failed | Log missing asset; continue with other assets; mark section as needs-review |
+
+Single asset failure does not block the entire section unless it is a critical background image.
+
+### Phase 2-e Section Verification Failures
+
+| Check Failed | Action |
+|-------------|--------|
+| Figma URL in output | Find and replace all occurrences; re-verify |
+| 0-byte or missing image | Re-download; if impossible, use placeholder only with TODO comment |
+| Empty template | Do not proceed to next section until fixed |
+| Build error | Fix TypeScript/template error; re-build |
+
+### Phase 3 Failures (Screenshot Comparison)
+
+| Priority | Issue Type | Action |
+|----------|-----------|--------|
+| P1 | Image missing, wrong layout, unstyled text | Fix immediately; re-verify before continuing |
+| P2 | Spacing delta, slight color difference | Fix if time allows; defer if P1=0 and deadline is tight |
+| P3 | Pixel-perfect micro-adjustments | Deferred to `/design-polish` pass |
+
+P1 = 0 is required before the feature is considered complete. P2/P3 are best-effort.
+
+## Design Quality Pipeline (Post-completion)
+
+```
+/design-normalize  → normalize inconsistent values
+/design-audit      → automated audit (quick pass)
+/design-critique   → thorough visual critique
+/design-polish     → final polish pass
+```
+
+Run at minimum: `/design-normalize` → `/design-audit --quick` before committing.