[G1-Sync] Manual knowledge update

2026-05-09 21:08:02 +09:00
parent f0befc887a
commit 93ec7e9056
363 changed files with 68333 additions and 64 deletions
@@ -0,0 +1,158 @@
+---
+id: frontend-design-tokens
+title: Design Tokens — 색 / spacing / type / 토큰화
+category: Coding
+status: draft
+source_trust_level: B
+verification_status: conceptual
+created_at: 2026-05-09
+updated_at: 2026-05-09
+tags: [frontend, design-tokens, design-system, vibe-coding]
+tech_stack: { language: "TS / CSS / Figma", applicable_to: ["Web", "iOS", "Android"] }
+applied_in: []
+aliases: [design tokens, tokens.json, Style Dictionary, Figma Variables]
+---
+
+# Design Tokens
+
+> 색 / 크기 / 타이포 = 단일 source. **Figma Variables → tokens.json → 각 platform** (CSS / iOS / Android) 자동 변환. Style Dictionary / Tokens Studio.
+
+## 📖 핵심 개념
+- Token: 디자인 결정 단위 (`color.brand.500 = #3b82f6`).
+- Layer: primitive (raw) → semantic (intent) → component.
+- Alias: `bg-surface` → `gray-50` → `#fafafa`.
+- Theme: dark / light 가 같은 semantic 의 다른 primitive 매핑.
+
+## 💻 코드 패턴
+
+### tokens.json (W3C Design Tokens)
+```json
+{
+  "color": {
+    "blue": {
+      "500": { "$value": "#3b82f6", "$type": "color" },
+      "600": { "$value": "#2563eb", "$type": "color" }
+    },
+    "brand": {
+      "primary": { "$value": "{color.blue.500}", "$type": "color" }
+    }
+  },
+  "spacing": {
+    "1": { "$value": "4px", "$type": "dimension" },
+    "2": { "$value": "8px", "$type": "dimension" }
+  }
+}
+```
+
+### Style Dictionary 빌드
+```ts
+// build.ts
+import StyleDictionary from 'style-dictionary';
+
+StyleDictionary.extend({
+  source: ['tokens/**/*.json'],
+  platforms: {
+    css: {
+      transformGroup: 'css',
+      buildPath: 'src/styles/',
+      files: [{ destination: 'tokens.css', format: 'css/variables' }],
+    },
+    ios: {
+      transformGroup: 'ios-swift',
+      buildPath: 'ios/Tokens/',
+      files: [{ destination: 'Tokens.swift', format: 'ios-swift/class.swift' }],
+    },
+    android: {
+      transformGroup: 'android',
+      buildPath: 'android/app/src/main/res/values/',
+      files: [
+        { destination: 'colors.xml', format: 'android/colors' },
+        { destination: 'dimens.xml', format: 'android/dimens' },
+      ],
+    },
+  },
+}).buildAllPlatforms();
+```
+
+### CSS 결과
+```css
+:root {
+  --color-blue-500: #3b82f6;
+  --color-brand-primary: var(--color-blue-500);
+  --spacing-1: 4px;
+}
+```
+
+### iOS Swift
+```swift
+public class Tokens {
+  public static let colorBlue500 = UIColor(red: 0.231, green: 0.510, blue: 0.965, alpha: 1)
+  public static let colorBrandPrimary = colorBlue500
+  public static let spacing1: CGFloat = 4
+}
+```
+
+### Android XML
+```xml
+<color name="color_blue_500">#3b82f6</color>
+<dimen name="spacing_1">4dp</dimen>
+```
+
+### Layer 패턴
+```json
+// primitive
+"color.blue.500": "#3b82f6",
+"color.gray.50":  "#fafafa",
+
+// semantic (intent)
+"color.bg.surface": "{color.gray.50}",
+"color.text.brand": "{color.blue.500}",
+
+// component
+"button.primary.bg": "{color.text.brand}"
+```
+
+### Theme switching
+```json
+// light.json
+"color.bg.surface": "{color.gray.50}",
+// dark.json
+"color.bg.surface": "{color.gray.900}"
+```
+
+```css
+:root { --color-bg-surface: var(--gray-50); }
+.dark { --color-bg-surface: var(--gray-900); }
+```
+
+### Figma Tokens Studio
+- Figma plugin: 디자이너가 토큰 편집.
+- GitHub sync: 디자이너 변경 → PR.
+- Style Dictionary 가 PR 의 토큰을 빌드.
+
+## 🤔 의사결정 기준
+| 규모 | 도구 |
+|---|---|
+| 1 platform 작은 앱 | Tailwind theme 으로 충분 |
+| Web 만 강력 | CSS variables + tokens.json |
+| Cross-platform (web/iOS/AOS) | Style Dictionary |
+| 디자이너 직접 편집 | Figma Variables + Tokens Studio |
+| Figma 없음 | tokens.json 직접 + PR review |
+
+## ❌ 안티패턴
+- **Magic value 코드 깊이**: hex 직접 작성. 토큰화.
+- **Primitive 만 — semantic 없음**: rebrand 시 모든 코드 변경.
+- **너무 많은 token (10000+)**: 너무 잘게. 적당히 추상.
+- **Component token 만 — primitive 안 보임**: 새 컴포넌트 만들 때 base 없음.
+- **Cross-platform 없이 platform 별 다른 색**: brand 일관성 깨짐.
+- **No naming convention**: 같은 의미 다른 이름.
+
+## 🤖 LLM 활용 힌트
+- 3 layer (primitive → semantic → component).
+- Style Dictionary cross-platform 빌드.
+- Figma → tokens.json sync.
+
+## 🔗 관련 문서
+- [[Frontend_Tailwind_Architecture]]
+- [[CSS_in_JS_vs_Utility_Tradeoffs]]
+- [[Cross_Platform_Theming]]