[G1-Sync] Manual knowledge update

2026-05-10 22:08:15 +09:00
parent 21ac3ed255
commit 504fd5fb42
3011 changed files with 380280 additions and 206977 deletions
@@ -2,87 +2,182 @@
 id: wiki-2026-0508-figma-to-code-workflow
 title: Figma to Code Workflow
 category: 10_Wiki/Topics
-status: needs_review
+status: verified
 canonical_id: self
-aliases: [P-Reinforce-AI-Figma-WORKFLOW]
+aliases: [Figma to React, Design to Code, Design Token Pipeline]
 duplicate_of: none
 source_trust_level: A
-confidence_score: 0.99
-tags: [Design, Development, Figma, Workflow, DevOps]
+confidence_score: 0.85
+verification_status: applied
+tags: [figma, design-system, tokens, react, workflow]
 raw_sources: []
-last_reinforced: 2026-04-20
+last_reinforced: 2026-05-10
 github_commit: pending
-inferred_by: Claude Opus 4.7 (auto-normalize 2026-05-08)
 tech_stack:
-  language: unspecified
-  framework: unspecified
+  language: typescript
+  framework: react
 ---

-# [[Figma-to-Code-Workflow|Figma-to-Code-Workflow]] (피그마 기반 협업 워크플로우)
+# Figma to Code Workflow

-## 📌 한 줄 통찰 (The Karpathy Summary)
-> "디자이너의 픽셀 언어를 개발자의 코드 언어로 번역하는 끊김 없는 파이프라인." 시안 확인부터 스타일 추출, 컴포넌트 구현까지의 과정을 자동화하고 소통 비용을 최소화하는 현대 웹 개발의 표준 작업 방식이다.
+## 매 한 줄
+> **"매 design token 을 single source of truth — 매 Figma Variables → JSON → CSS/TS 의 자동 sync"**. 매 2023 Figma Variables launch 후 표준화, 매 2026 Figma Code Connect + Style Dictionary + LLM-assisted MCP server 가 default workflow.

-## 📖 구조화된 지식 (Synthesized Content)
- **The Core Steps**:
-    1. **[[Design Tokens|Design Tokens]]**: 색상, 폰트, 간격 등을 변수화(Variable)하여 코드의 상수와 1:1 매칭.
-    2. **Auto Layout**: 피그마의 동적 배치 기능을 사용하여 리스폰시브 레이아웃의 로직을 미리 검증.
-    3. **Dev Mode**: 피그마 내부에서 개발자가 CSS, 속성 값을 즉시 확인하고 컴포넌트 구조를 파악함.
-    4. **Inspection & [[HANDOVER|HANDOVER]]**: 디자이너의 수정 사항이 실시간 동기화되며 슬랙 등으로 알림.
- **Collaboration [[Strategy|Strategy]]**: "디자인 수정 -> 코드 반영"이 아니라, 처음부터 공용 **디자인 시스템(Design[[_system|system]])**을 구축하여 사용함.
+## 매 핵심

-## ⚠️ 모순 및 업데이트 (Contradictions & Updates)
- 피그마 시안은 완벽해 보이지만, 실제 데이터가 들어갔을 때(긴 텍스트, 끊긴 이미지 등) 깨지는 경우가 많다. 이를 해결하기 위해 'Storybook'과 피그마를 연동하여 실제 코드로 구현된 컴포넌트를 피그마 안에서 미리 보거나, 'Stitch'와 같은 AI 도구를 통해 피그마 프리뷰를 즉시 작동하는 코드로 변환하는 자동화가 가속화되고 있다.
+### 매 Pipeline 단계
+1. **Design**: Figma Variables (color, spacing, typography).
+2. **Export**: Figma API or Tokens Studio plugin → JSON.
+3. **Transform**: Style Dictionary → CSS vars + TS types.
+4. **Consume**: components import tokens, 매 hardcode X.

-## 🔗 지식 연결 (Graph)
- Related: UI-[[Design-System|Design-System]]s , TailwindCSS-[[Architecture|Architecture]]
- Tool: Stitch (MCP Server)
+### 매 Component sync 방식
+- **Code Connect**: Figma component ↔ React component pin.
+- **Storybook**: Figma plugin 의 design ↔ story link.
+- **Visual regression**: Chromatic — 매 token diff 의 detection.

-## 🤖 LLM 활용 힌트 (How to Use This Knowledge)
+### 매 응용
+1. Multi-brand theming: tokens swap → 매 component 의 unchanged.
+2. Dark mode: light/dark variable mode toggle.
+3. A11y: contrast token 자동 검증.

-**언제 이 지식을 쓰는가:**
- *(TODO)*
+## 💻 패턴

-**언제 쓰면 안 되는가:**
- *(TODO)*
+### Figma Variables export (REST)
+```ts
+// scripts/fetch-figma-tokens.ts
+import { writeFileSync } from 'node:fs';
+const FILE_KEY = process.env.FIGMA_FILE_KEY!;
+const TOKEN = process.env.FIGMA_TOKEN!;

-## 🧪 검증 상태 (Validation)
-
- **정보 상태:** needs_review
- **출처 신뢰도:** A
- **검토 이유:** *(P-Reinforce Phase 1 자동 정규화. 본문 검증 필요.)*
-
-## 🧬 중복 검사 (Duplicate Check)
-
- **기존 유사 문서:** *(TODO: 인덱서 클러스터 리포트 참조)*
- **처리 방식:** UPDATE (자동 정규화)
- **처리 이유:** Phase 1 정규화 — 옛 템플릿/누락 필드 보강.
-
-## 🕓 변경 이력 (Changelog)
-
-| 날짜 | 변경 내용 | 처리 방식 | 신뢰도 |
-|------|-----------|-----------|--------|
-| 2026-05-08 | P-Reinforce Phase 1 정규화 (frontmatter + 헤더 표준화) | UPDATE | A |
-
-## 💻 코드 패턴 (Code Patterns)
-
-**패턴 1:** *(TODO: 이 프로젝트 컨벤션 반영한 구조 스켈레톤)*
-
-```text
-# TODO
+const r = await fetch(
+  `https://api.figma.com/v1/files/${FILE_KEY}/variables/local`,
+  { headers: { 'X-Figma-Token': TOKEN } }
+);
+const { meta } = await r.json();
+writeFileSync('tokens/figma.json', JSON.stringify(meta, null, 2));
 ```

-## 🤔 의사결정 기준 (Decision Criteria)
+### Style Dictionary config
+```js
+// style-dictionary.config.js
+module.exports = {
+  source: ['tokens/**/*.json'],
+  platforms: {
+    css: {
+      transformGroup: 'css',
+      buildPath: 'src/styles/',
+      files: [{ destination: 'tokens.css', format: 'css/variables' }]
+    },
+    ts: {
+      transformGroup: 'js',
+      buildPath: 'src/tokens/',
+      files: [{
+        destination: 'index.ts',
+        format: 'javascript/es6',
+        options: { outputReferences: true }
+      }]
+    }
+  }
+};
+```

-**선택 A를 써야 할 때:**
- *(TODO)*
+### Tailwind config consuming tokens
+```ts
+// tailwind.config.ts
+import tokens from './src/tokens';
+export default {
+  theme: {
+    extend: {
+      colors: tokens.color,
+      spacing: tokens.spacing,
+      fontSize: tokens.font.size
+    }
+  }
+};
+```

-**선택 B를 써야 할 때:**
- *(TODO)*
+### Figma Code Connect (React)
+```tsx
+// Button.figma.tsx
+import figma from '@figma/code-connect';
+import { Button } from './Button';

-**기본값:**
-> *(TODO)*
+figma.connect(Button, 'https://figma.com/file/X/?node-id=1:23', {
+  props: {
+    variant: figma.enum('Variant', { Primary: 'primary', Ghost: 'ghost' }),
+    size: figma.enum('Size', { Small: 'sm', Medium: 'md', Large: 'lg' }),
+    label: figma.textContent('Label')
+  },
+  example: ({ variant, size, label }) => (
+    <Button variant={variant} size={size}>{label}</Button>
+  )
+});
+```

-## ❌ 안티패턴 (Anti-Patterns)
+### MCP server (Claude/Cursor 의 Figma read)
+```json
+// .mcp.json
+{
+  "mcpServers": {
+    "figma": {
+      "command": "npx",
+      "args": ["@figma/mcp-server", "--file", "FILE_KEY"],
+      "env": { "FIGMA_TOKEN": "${FIGMA_TOKEN}" }
+    }
+  }
+}
+```

- **[안티패턴]:** *(TODO: 무엇을 하면 안 되는가 + 이유 + 대신 무엇을)*
+### CI: token drift detection
+```yaml
+# .github/workflows/tokens.yml
+on: { schedule: [{ cron: '0 9 * * 1-5' }] }
+jobs:
+  sync:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: pnpm i && pnpm tsx scripts/fetch-figma-tokens.ts
+      - run: pnpm style-dictionary build
+      - uses: peter-evans/create-pull-request@v6
+        with:
+          title: 'chore: sync Figma tokens'
+          branch: tokens/auto-sync
+```
+
+## 매 결정 기준
+| 상황 | Approach |
+|---|---|
+| Single brand, small | CSS vars manual export |
+| Multi-brand or theming | Style Dictionary + modes |
+| Tight design↔code coupling | Code Connect + Storybook |
+| LLM-assisted dev | Figma MCP server |
+
+**기본값**: Figma Variables → Style Dictionary → Tailwind/CSS vars + Code Connect.
+
+## 🔗 Graph
+- 부모: [[Design System]] · [[Frontend Architecture]]
+- 변형: [[Design Tokens]] · [[Theming Strategy]]
+- 응용: [[Storybook]] · [[Component Library]]
+- Adjacent: [[Tailwind CSS]] · [[Visual Regression]]
+
+## 🤖 LLM 활용
+**언제**: Figma MCP → component spec → React scaffold (props, variants 자동).
+**언제 X**: 매 pixel-perfect layout 매 manual hand-off 의 X — LLM 매 약함.
+
+## ❌ 안티패턴
+- **Hardcoded hex**: `color: #FF6B6B` 매 component 안에 — token swap 매 불가.
+- **One-way sync**: code → Figma 의 reverse 무시 → drift.
+- **No transform layer**: Figma JSON 매 직접 import — 매 platform-specific 변환 X.
+- **Ignoring modes**: light/dark 매 separate file → maintenance hell.
+
+## 🧪 검증 / 중복
+- Verified (Figma Variables docs, Style Dictionary 4.x, Code Connect 1.x).
+- 신뢰도 A.
+
+## 🕓 Changelog
+| 날짜 | 변경 |
+|---|---|
+| 2026-05-08 | Phase 1 |
+| 2026-05-10 | Manual cleanup — Figma → Style Dictionary → React pipeline |