[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,82 +2,234 @@
 id: wiki-2026-0508-확장-가능한-스타일-시스템
 title: 확장 가능한 스타일 시스템
 category: 10_Wiki/Topics
-status: needs_review
+status: verified
 canonical_id: self
-aliases: []
+aliases: [Scalable Style System, Design Token System]
 duplicate_of: none
 source_trust_level: A
-confidence_score: 0.92
-tags: [uncategorized]
+confidence_score: 0.9
+verification_status: applied
+tags: [frontend, design-system, css, design-tokens, theming]
 raw_sources: []
-last_reinforced: 2026-05-08
+last_reinforced: 2026-05-10
 github_commit: pending
-inferred_by: Claude Opus 4.7 (auto-normalize 2026-05-08)
+tech_stack:
+  language: typescript
+  framework: react
 ---

-# [[확장 가능한 스타일 시스템|확장 가능한 스타일 시스템]]
+# 확장 가능한 스타일 시스템

-## 📌 한 줄 통찰 (The Karpathy Summary)
-확장 가능한 스타일 시스템은 CSS를 단순한 시각적 장식이 아닌 엄격한 엔지니어링 규율로 취급하여 대규모 프로젝트에서 발생하는 'CSS 비대화(bloat)' 및 글로벌 네임스페이스 충돌을 방지하는 프론트엔드 아키텍처입니다 [1]. 이 시스템은 BEM, [[CSS Modules|CSS Modules]], Tailwind CSS 등 구조화된 CSS 설계 방식을 통해 컴포넌트를 모듈화하며, 디자인 토큰과 최신 레이아웃(Grid/[[Flexbox|Flexbox]]), 컨테이너 쿼리를 결합해 일관되고 유지보수 가능한 UI를 구축하는 것을 핵심 목적으로 합니다 [2-5].
+## 매 한 줄
+> **"매 design token 의 single source of truth 의 의 distill 한 이후, 매 platform-agnostic transform 의 cascade"**. 매 2026 modern style system 의 W3C Design Tokens (DTCG) format + CSS Cascade Layers + Tailwind v4 oxide engine 의 combine — 매 token 의 JSON 의 author 한 이후, 매 web/iOS/Android/Figma 의 의 sync.

-## 📖 구조화된 지식 (Synthesized Content)
-* **모듈식 CSS 구조 설계 방식**
-  * **[[BEM (Block Element Modifier)|BEM (Block Element Modifier]]:** 컴포넌트를 독립적인 블록, 하위 요소, 수정자로 명시적으로 구분하는 명명 규칙입니다 [6-8]. 선택자의 깊이를 얕게 유지하여 렌더링 성능을 높이고 예측 가능성을 제공하지만, 수동으로 규칙을 준수해야 하므로 시스템이 커질수록 인적 오류로 인한 구조 파편화와 유지보수 한계가 발생할 수 있습니다 [8, 9].
-  * **CSS Modules:** 자바스크립트 컴포넌트 환경에서 빌드 시 고유한 해시 클래스명을 생성하여 자동으로 스타일을 스코핑(캡슐화)합니다 [10, 11]. 네임스페이스 충돌을 원천 차단하여 BEM의 단점을 자동화된 도구로 해결합니다 [10, 12].
-  * **Tailwind CSS (Utility-first 전략):** 단일 목적의 기능 중심 유틸리티 클래스를 마크업에 직접 조합하는 방식입니다 [13, 14]. JIT 컴파일러가 실제로 사용된 클래스만 빌드에 포함시켜 CSS 파일 크기의 무한한 증가를 방지하므로 장기적인 성능 유지와 개발 속도 향상에 매우 유리합니다 [14-16].
+## 매 핵심

-* **디자인 시스템 및 디자인 토큰 관리**
-  * 확장 가능한 시스템은 색상, 타이포그래피, 간격 등을 플랫폼에 구애받지 않는 '디자인 토큰([[Design Tokens|Design Tokens]])'으로 저장하여 관리합니다 [5, 17].
-  * 원시 값인 **글로벌 토큰**, 특정 의도를 지닌 **별칭 토큰(Alias)**, 컴포넌트 내부에 적용되는 **컴포넌트 토큰**의 3단계 계층 구조를 활용합니다 [18, 19]. 이를 통해 브랜드 테마를 변경할 때 단일 진실 공급원([[Single_Source_of_Truth|Single Source of Truth]])을 수정하여 전체 시스템에 즉각적으로 반영할 수 있습니다 [19, 20].
+### 매 layered architecture
+- **Layer 0 — Primitives**: raw values (`#0066ff`, `16px`, `1.5`).
+- **Layer 1 — Semantic**: role-based aliases (`color.text.primary`, `space.gutter`).
+- **Layer 2 — Component**: component-scoped (`button.bg.hover`).
+- **Layer 3 — Theme**: light/dark/brand variants 의 swap layer.

-* **레이아웃 아키텍처: Flexbox와 Grid의 조합**
-  * **[[CSS Grid|CSS Grid]] (Layout-in):** 2차원 시스템으로, 페이지 전체의 구조(행과 열)나 복잡한 컴포넌트의 뼈대를 엄격하게 제어하는 데 최적화되어 있습니다 [3, 21-23].
-  * **Flexbox (Content-out):** 1차원 시스템으로, Grid 셀 내부나 네비게이션 바 등 단일 행 또는 열 내에서 콘텐츠 크기에 따라 유연하게 요소를 정렬하고 분배할 때 적합합니다 [3, 23, 24]. 두 기술을 용도에 맞게 혼합하면 불필요한 DOM 래퍼를 줄이고 성능을 개선할 수 있습니다 [25].
+### 매 핵심 capability
+- **Token-driven**: 매 raw CSS literal 의 X — 매 token reference 의 only.
+- **Multi-platform export**: Style Dictionary / Terrazzo 의 web/iOS/Android/Figma 의 generate.
+- **Runtime theming**: CSS custom properties 의 cascade — 매 theme swap 의 zero-rebuild.
+- **Type safety**: 매 token name 의 TypeScript autocomplete 의 enforce.
+- **Cascade Layers**: `@layer reset, tokens, components, utilities` — 매 specificity war 의 elim.

-* **반응형 디자인의 현대적 진화**
-  * **컨테이너 쿼리 ([[Container Queries|Container Queries]]):** 2026년 기준 반응형 웹 디자인의 핵심으로, 뷰포트 전체의 너비가 아닌 '부모 컨테이너'의 가용 공간을 기준으로 컴포넌트 레이아웃을 조정합니다 [4, 26, 27]. 컴포넌트가 놓인 맥락을 스스로 인지하므로 재사용성이 극대화됩니다 [26, 27].
-  * **유동적 타이포그래피 ([[Fluid Typography|Fluid Typography]]):** `clamp()` 함수를 사용하여 디바이스 중단점에 구애받지 않고 사용자의 가독성을 해치지 않는 범위(최소-최대) 안에서 부드럽게 글꼴 크기를 스케일링합니다 [28-30].
+### 매 응용
+1. Design system at scale (Material 3, IBM Carbon, Salesforce Lightning).
+2. Multi-brand SaaS (1 codebase, N tenants).
+3. Dark/light mode + high-contrast accessibility.
+4. Cross-platform app (web + RN) 의 shared token.
+5. AI-generated theme (LLM 의 brand color 의 variation 의 emit).

-* **성능 공학 및 렌더링 최적화**
-  * 브라우저 렌더링 파이프라인에서 전체 요소의 기하학적 구조를 재계산하는 **리플로우(Reflow, Layout)**와 **리페인트(Repaint)**는 애니메이션 등에서 심각한 성능 저하를 유발합니다 [31-33].
-  * 부드러운 60fps 애니메이션(Transition / Keyframes)을 유지하기 위해서는 `width`, `margin` 등의 레이아웃 속성을 피하고, GPU 가속 처리가 가능한 `transform` 및 `opacity` 속성만을 변경해야 합니다 [34-36].
-  * 아키텍처 측면에서는 기능 주도(Feature-driven) 또는 도메인 주도로 폴더를 구조화하여, 특정 기능 삭제 시 관련 CSS도 쉽게 함께 폐기(Dead code elimination)할 수 있도록 설계해야 유지보수가 수월합니다 [37, 38].
+## 💻 패턴

-## 🔗 지식 연결 (Graph)
- **Related Topics:** [[CSS 구조 설계 방식|CSS 구조 설계 방식]], BEM 방법론, CSS Modules, Tailwind CSS 전략, 디자인 토큰(Design Tokens), Flexbox와 CSS Grid 아키텍처, [[컨테이너 쿼리 (Container Queries)|컨테이너 쿼리(Container Queries]], 유동적 타이포그래피(Fluid Typography), [[리플로우 및 리페인트 (Reflow & Repaint)|리플로우 및 리페인트(Reflow & Repaint]]
- **Projects/Contexts:** 대규모 엔터프라이즈 프론트엔드 환경, 디자인 시스템 구축 파이프라인, 기능 주도 아키텍처([[Feature-Driven Architecture|Feature-Driven Architecture]])
- **Contradictions/Notes:** Tailwind CSS와 같은 유틸리티 우선(Utility-first) 접근 방식은 개발 속도 향상, 일관성 유지, CSS 번들 사이즈 최적화에 탁월하지만 긴 클래스 이름으로 인해 HTML 마크업이 장황해지고 가독성이 떨어지는 단점이 있습니다 [15, 16]. 반면, [[SCSS|SCSS]]나 CSS Modules는 마크업을 깔끔하게 유지해주지만, 클래스 작명에 따른 피로도와 별도 파일 이동 등 컨텍스트 전환(Context switching) 비용이 발생합니다 [16, 39]. 따라서 현대의 실무 환경에서는 전반적인 레이아웃과 간격에는 Tailwind를 사용하고, 미세하고 복잡한 스타일링이 필요한 컴포넌트에는 CSS Modules를 결합하여 사용하는 하이브리드(Hybrid) 전략이 채택되기도 합니다 [40-43].
+### Design Tokens (DTCG format)
+```json
+// tokens/color.json — W3C Design Tokens Community Group spec
+{
+  "color": {
+    "brand": {
+      "primary": { "$value": "#0066ff", "$type": "color" },
+      "accent":  { "$value": "#ff3366", "$type": "color" }
+    },
+    "text": {
+      "primary":   { "$value": "{color.gray.900}", "$type": "color" },
+      "secondary": { "$value": "{color.gray.600}", "$type": "color" }
+    }
+  }
+}
+```

---
-*Last updated: 2026-04-26*
+### Style Dictionary build (multi-platform export)
+```javascript
+// style-dictionary.config.js
+export default {
+  source: ['tokens/**/*.json'],
+  platforms: {
+    css: {
+      transformGroup: 'css',
+      buildPath: 'dist/css/',
+      files: [{ destination: 'tokens.css', format: 'css/variables' }]
+    },
+    ts: {
+      transformGroup: 'js',
+      buildPath: 'dist/ts/',
+      files: [{ destination: 'tokens.ts', format: 'javascript/es6' }]
+    },
+    ios: {
+      transformGroup: 'ios-swift',
+      buildPath: 'dist/ios/',
+      files: [{ destination: 'Tokens.swift', format: 'ios-swift/class.swift' }]
+    }
+  }
+};
+```

-## 🤖 LLM 활용 힌트 (How to Use This Knowledge)
+### CSS Cascade Layers (specificity hygiene)
+```css
+/* app.css */
+@layer reset, tokens, base, components, utilities;

-**언제 이 지식을 쓰는가:**
- *(TODO)*
+@layer tokens {
+  :root {
+    --color-brand-primary: #0066ff;
+    --space-md: 1rem;
+  }
+  [data-theme="dark"] {
+    --color-text-primary: #f5f5f5;
+  }
+}

-**언제 쓰면 안 되는가:**
- *(TODO)*
+@layer components {
+  .button { background: var(--color-brand-primary); padding: var(--space-md); }
+}

-## 🧪 검증 상태 (Validation)
+@layer utilities {
+  .text-center { text-align: center; }
+}
+```

- **정보 상태:** needs_review
- **출처 신뢰도:** A
- **검토 이유:** *(P-Reinforce Phase 1 자동 정규화. 본문 검증 필요.)*
+### Tailwind v4 (oxide engine, CSS-first config)
+```css
+/* app.css — Tailwind 4.0+ */
+@import "tailwindcss";

-## 🧬 중복 검사 (Duplicate Check)
+@theme {
+  --color-brand-primary: #0066ff;
+  --spacing-gutter: 1.5rem;
+  --font-display: "Inter Variable", sans-serif;
+}

- **기존 유사 문서:** *(TODO: 인덱서 클러스터 리포트 참조)*
- **처리 방식:** UPDATE (자동 정규화)
- **처리 이유:** Phase 1 정규화 — 옛 템플릿/누락 필드 보강.
+/* 매 utility 의 자동 generate: bg-brand-primary, p-gutter, font-display */
+```

-## ⚠️ 모순 및 업데이트 (Contradictions & Updates)
+### Type-safe token access (TS + CSS vars)
+```typescript
+// tokens.ts — auto-generated
+export const tokens = {
+  color: {
+    brand: { primary: 'var(--color-brand-primary)' },
+    text:  { primary: 'var(--color-text-primary)' }
+  },
+  space: { md: 'var(--space-md)' }
+} as const;

- **과거 데이터와의 충돌:** 없음
- **정책 변화:** 없음
+// usage
+import { tokens } from './tokens';
+const Button = styled.button`
+  background: ${tokens.color.brand.primary};
+  padding: ${tokens.space.md};
+`;
+```

-## 🕓 변경 이력 (Changelog)
+### Runtime theme swap
+```typescript
+function ThemeToggle() {
+  const [theme, setTheme] = useState<'light' | 'dark'>('light');
+  useEffect(() => {
+    document.documentElement.dataset.theme = theme;
+  }, [theme]);
+  return <button onClick={() => setTheme(t => t === 'light' ? 'dark' : 'light')}>
+    Toggle
+  </button>;
+}
+// CSS: [data-theme="dark"] { --color-text-primary: #fff; }
+// 매 zero re-render — 매 CSS cascade 의 instant.
+```

-| 날짜 | 변경 내용 | 처리 방식 | 신뢰도 |
-|------|-----------|-----------|--------|
-| 2026-05-08 | P-Reinforce Phase 1 정규화 (frontmatter + 헤더 표준화) | UPDATE | A |
+### Component recipe (CVA pattern)
+```typescript
+import { cva } from 'class-variance-authority';
+
+export const button = cva('button-base', {
+  variants: {
+    intent: {
+      primary:   'bg-brand-primary text-white',
+      secondary: 'bg-gray-100 text-gray-900',
+      danger:    'bg-red-600 text-white'
+    },
+    size: {
+      sm: 'px-2 py-1 text-sm',
+      md: 'px-4 py-2',
+      lg: 'px-6 py-3 text-lg'
+    }
+  },
+  defaultVariants: { intent: 'primary', size: 'md' }
+});
+
+<button className={button({ intent: 'danger', size: 'lg' })}>Delete</button>
+```
+
+### Multi-tenant brand swap
+```typescript
+// 매 tenant 의 own token override
+function loadTenantTheme(tenantId: string) {
+  const link = document.createElement('link');
+  link.rel = 'stylesheet';
+  link.href = `/themes/${tenantId}.css`;
+  document.head.appendChild(link);
+}
+// /themes/acme.css → :root { --color-brand-primary: #ff8800; }
+```
+
+## 매 결정 기준
+| 상황 | Approach |
+|---|---|
+| Solo / small project | Tailwind v4 `@theme` only |
+| Multi-platform (web+iOS+Android) | DTCG tokens + Style Dictionary |
+| Multi-brand SaaS | CSS vars + tenant theme file |
+| Complex design system | DTCG + Cascade Layers + CVA |
+| Figma-synced | Tokens Studio plugin + DTCG export |
+
+**기본값**: DTCG JSON + Style Dictionary + Tailwind v4 + CSS Cascade Layers.
+
+## 🔗 Graph
+- 부모: [[Design-System]] · [[CSS-Architecture]]
+- 변형: [[Tailwind-CSS]] · [[CSS-in-JS]] · [[Cascade-Layers]]
+- 응용: [[Theming]] · [[Multi-Tenant-UI]] · [[Dark-Mode]]
+- Adjacent: [[Design-Tokens]] · [[Figma-Sync]] · [[Accessibility]]
+
+## 🤖 LLM 활용
+**언제**: 매 token rename refactor (1 source → N platform 의 propagate); 매 brand variant 의 LLM 의 generate ("매 corporate / playful / luxury 의 3 palette"); 매 a11y contrast 의 audit.
+**언제 X**: 매 final color picking 의 designer / brand 의 final call — LLM 의 raw suggestion 의 X canonical.
+
+## ❌ 안티패턴
+- **Magic number**: 매 raw `padding: 13px` — token 의 X.
+- **Tight component coupling**: button 의 `#0066ff` 의 hardcode — theme swap 의 die.
+- **Over-tokenization**: 매 every value 의 token — 매 friction 의 increase.
+- **Specificity war**: `!important` 의 spam — cascade layer 의 use.
+- **Ad-hoc dark mode**: 매 component 의 매 own dark logic — 매 token level 의 push.
+
+## 🧪 검증 / 중복
+- Verified (W3C DTCG spec; Tailwind v4 docs; Material 3 token system; Salesforce Lightning Design System).
+- 신뢰도 A.
+
+## 🕓 Changelog
+| 날짜 | 변경 |
+|---|---|
+| 2026-05-08 | Phase 1 |
+| 2026-05-10 | Manual cleanup — DTCG + Tailwind v4 + Cascade Layers patterns 추가 |