@su-record/vibe 2.8.3 → 2.8.5

package/commands/vibe.figma.md

@@ -1,6 +1,6 @@
 ---
 description: Figma design to code — extract + generate in one step
-argument-hint: "figma-url" ["figma-url-2"] [--standalone]
+argument-hint: "figma-url" ["figma-url-2"] [--new] [--component Name]
 ---
 
 # /vibe.figma
@@ -12,7 +12,7 @@ Extract Figma design data and generate production-ready component code, tailored
 ```
 /vibe.figma "url"                                    # Single design → project integrated (default)
 /vibe.figma "mobile-url" "desktop-url"               # Responsive — auto-detect viewport from frame width
-/vibe.figma "url" --standalone                        # Self-contained output folder
+/vibe.figma "url" --new                          # New feature — self-contained tokens, no existing design system dependency
 /vibe.figma "url" --component LoginForm               # Name the root component
 /vibe.figma --local                                   # Skip extraction, use existing figma-output/
 ```
@@ -22,7 +22,7 @@ Extract Figma design data and generate production-ready component code, tailored
 | Flag | Behavior |
 |------|----------|
 | _(default)_ | **Project integration.** Use project's design system, existing tokens, component patterns. Place files in project's component directory. |
-| `--standalone` | **Independent folder.** Create self-contained folder with own global styles, tokens, and components. No dependency on project's existing styles. Ready to copy-paste into any project. |
+| `--new` | **New feature.** Self-contained tokens + components in project structure. No dependency on existing design system. Portable across projects. |
 | _(multi URL)_ | **Responsive mode.** Auto-detected when 2+ URLs provided. Compares designs across viewports and generates responsive code with fluid scaling. |
 
 ### Responsive Mode
@@ -76,7 +76,7 @@ https://www.figma.com/design/:fileKey/:fileName?node-id=:nodeId
 **Single URL:**
 
 ```
-1. get_design_context(fileKey, nodeId) → 코드 + 스크린샷 + 메타데이터
+1. get_design_context(fileKey, nodeId) → 코드 + 스크린샷 + 메타데이터 + 에셋 URL
 2. get_metadata(fileKey, nodeId) → 레이어 구조 (XML)
 3. get_screenshot(fileKey, nodeId) → 프레임 이미지
 ```
@@ -88,17 +88,59 @@ https://www.figma.com/design/:fileKey/:fileName?node-id=:nodeId
 프레임 width로 mobile/tablet/desktop 자동 감지.
 ```
 
-### 0-3. Verify Output & Detect Mode
+### 0-2. Image Asset Extraction (필수)
 
+`get_design_context` 응답에 포함된 이미지 에셋 URL을 **반드시 다운로드**하여 프로젝트에 저장해야 함.
+MCP가 반환하는 URL은 **7일 후 만료**되므로 임시 URL을 코드에 직접 넣으면 안 됨.
+
+**에셋 URL 감지:**
+
+`get_design_context` 응답의 코드에 다음 패턴이 포함됨:
+```
+const image = 'https://www.figma.com/api/mcp/asset/...'
+```
+
+**다운로드 및 저장:**
+
+```
+1. 응답에서 모든 이미지 URL 추출 (https://www.figma.com/api/mcp/asset/...)
+2. WebFetch로 각 URL 다운로드
+3. 프로젝트의 에셋 디렉토리에 저장:
+   - Nuxt: public/images/{feature}/ 또는 assets/images/{feature}/
+   - Next.js: public/images/{feature}/
+   - React: public/images/{feature}/ 또는 src/assets/{feature}/
+4. 파일명은 레이어 이름 기반 (kebab-case):
+   - "Hero Background" → hero-background.webp
+   - "Product Photo 1" → product-photo-1.webp
+5. 생성된 코드에서 임시 URL을 로컬 경로로 교체:
+   - 'https://www.figma.com/api/mcp/asset/...' → '/images/{feature}/hero-background.webp'
+```
+
+**SVG 처리:**
+
+```
+- 아이콘/로고 등 벡터 에셋은 SVG로 추출
+- SVG는 인라인 컴포넌트로 변환하거나 파일로 저장
+  - 작은 아이콘 (< 1KB) → 인라인 SVG 컴포넌트
+  - 큰 SVG → 파일로 저장 후 <img> 또는 import
+```
+
+**에셋 미추출 시 경고:**
+
+코드 생성 완료 후, MCP 임시 URL이 코드에 남아있으면 경고:
 ```
-1. Check figma-output/responsive.json exists → if yes, enter RESPONSIVE MODE
-2. If responsive mode:
-   - Read responsive.json → verify all listed files exist
-   - Confirm at least 2 viewports with different width classes
-3. If single mode:
-   - Check figma-output/layers.json exists → if not, report error and stop
-   - Check figma-output/frame.png exists → optional (only with node-id)
-4. Validate all layers JSON files have children array → warn if empty
+⚠️ 임시 Figma URL이 코드에 남아있습니다. 7일 후 만료됩니다:
+   - src/components/Hero.vue: line 12 (hero-bg)
+   → WebFetch로 다운로드 후 로컬 경로로 교체하세요.
+```
+
+### 0-3. Verify Extraction
+
+```
+1. 모든 MCP 호출 성공 확인
+2. 이미지 에셋 다운로드 완료 확인
+3. 임시 URL이 코드에 남아있지 않은지 확인
+4. Responsive mode: 최소 2개 뷰포트 확인
 ```
 
 ---
@@ -305,11 +347,14 @@ Stored in `~/.vibe/config.json` → `figma.breakpoints`. Partial overrides merge
 
 ### 3-4. Resolve Generation Mode
 
+**Both modes use the project's existing directory structure.** Never create `figma-output/generated/`.
+
 ```
-if --standalone flag:
-  → create isolated output folder (default: figma-output/generated/)
-  → generate self-contained global styles + component styles
-  → no dependency on project's existing code
+if --new flag:
+  → detect project's page/component/style directories (same as default)
+  → generate self-contained token file (no MASTER.md dependency)
+  → components are self-contained (own tokens, no external design system imports)
+  → placed in project's standard directories with feature-named subfolder
 
 default (no flag):
   → scan existing component directories, theme files, token definitions
@@ -329,35 +374,65 @@ default (no flag):
 2. **design-context.json tokens** — if `detectedStack.fonts`, `aesthetic.colorMood` exist, align with these
 3. **New figma-tokens** — only for values that have no existing match
 
-**Standalone mode**: Always generate a self-contained token file (no MASTER.md dependency).
+**--new mode**: Generate self-contained token file (no MASTER.md dependency), in project's standard directories.
+
+#### Output Structure (both modes — project structure 준수)
+
+프로젝트의 기존 디렉토리 구조를 감지하여 올바른 위치에 파일 생성.
 
-#### --standalone mode output:
+**Step 1: 디렉토리 감지**
 
 ```
-figma-output/generated/
-├── styles/
-│   ├── tokens.css              ← CSS custom properties (colors, spacing, typography, shadows)
-│   ├── global.css              ← Reset + base typography + global layout
-│   └── index.css               ← Re-exports tokens.css + global.css
-├── components/
-│   ├── ComponentName/
-│   │   ├── ComponentName.tsx   ← Component code
-│   │   └── ComponentName.module.css (or .styles.ts)
-│   └── ...
-└── index.ts                    ← Barrel export
+페이지 디렉토리:
+  Next.js → pages/ or app/
+  Nuxt    → pages/
+  React   → src/pages/ or src/views/
+  Vue     → src/views/
+
+컴포넌트 디렉토리:
+  Next.js → components/ or src/components/
+  Nuxt    → components/
+  React   → src/components/
+  Vue     → src/components/
+
+스타일 디렉토리:
+  SCSS    → assets/scss/ or src/scss/ or src/styles/
+  CSS     → src/styles/ or styles/
+  Tailwind → tailwind.config.* (extend)
 ```
 
-#### Default (project integration) mode output:
+**Step 2: 피처명 기반 폴더 생성**
+
+`--component` 플래그 또는 Figma 파일명에서 피처명 추출 → kebab-case 변환.
 
 ```
-{project-component-dir}/       ← e.g., src/components/
-├── ComponentName/
-│   ├── ComponentName.tsx
-│   └── ComponentName.module.css (or .styles.ts)
-└── ...
+예: Figma 파일명 "PUBG 9주년 이벤트" → pubg-anniversary
+
+Nuxt 프로젝트:
+  pages/pubg-anniversary.vue                      ← 루트 페이지
+  components/pubg-anniversary/
+    HeroSection.vue                                ← 섹션 컴포넌트
+    EventSection.vue
+    RewardSection.vue
+    ...
+  assets/scss/_pubg-anniversary-tokens.scss        ← 피처별 토큰
+
+React + Next.js 프로젝트:
+  app/pubg-anniversary/page.tsx                    ← 루트 페이지
+  components/pubg-anniversary/
+    HeroSection.tsx
+    HeroSection.module.css (or .module.scss)
+    EventSection.tsx
+    ...
+  styles/pubg-anniversary-tokens.css               ← 피처별 토큰
+
+Default mode 차이점:
+  → 토큰 파일에서 기존 MASTER.md / 프로젝트 토큰 참조
+  → 새 토큰만 추가
 
-{project-style-dir}/           ← e.g., src/styles/ or extend existing
-└── figma-tokens.css            ← Only NEW tokens not already in project
+--new mode 차이점:
+  → 토큰 파일이 자체 완결 (외부 의존 없음)
+  → 다른 프로젝트에 폴더째 복사 가능
 ```
 
 ### 4-2. Token File Format
@@ -1406,7 +1481,7 @@ After generating code, output a brief correction report:
 ## Correction Notes
 
 ### Generation Mode
-- Mode: default / --standalone / responsive
+- Mode: default / --new / responsive
 - Output directory: {path}
 - Viewports: {list of viewport labels + widths, if responsive}
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@su-record/vibe",
-  "version": "2.8.3",
+  "version": "2.8.5",
   "description": "AI Coding Framework for Claude Code — 49 agents, 41+ tools, multi-LLM orchestration",
   "type": "module",
   "main": "dist/cli/index.js",