[G1-Sync] Manual knowledge update
This commit is contained in:
Antigravity Agent
@@ -1,99 +1,181 @@
|
||||
---
|
||||
id: wiki-2026-0508-모듈식-css-modular-css
|
||||
title: 모듈식 CSS(Modular CSS)
|
||||
title: 모듈식 CSS (Modular CSS)
|
||||
category: 10_Wiki/Topics
|
||||
status: needs_review
|
||||
status: verified
|
||||
canonical_id: self
|
||||
aliases: []
|
||||
aliases: [Modular CSS, CSS Modules, Component CSS, Scoped Styles]
|
||||
duplicate_of: none
|
||||
source_trust_level: A
|
||||
confidence_score: 0.92
|
||||
tags: [uncategorized]
|
||||
confidence_score: 0.9
|
||||
verification_status: applied
|
||||
tags: [css, modules, frontend, architecture]
|
||||
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: unspecified
|
||||
framework: unspecified
|
||||
language: css
|
||||
framework: build-tools
|
||||
---
|
||||
|
||||
# [[모듈식 CSS(Modular CSS)|모듈식 CSS(Modular CSS]]
|
||||
# 모듈식 CSS (Modular CSS)
|
||||
|
||||
## 📌 한 줄 통찰 (The Karpathy Summary)
|
||||
모듈식 CSS([[CSS Modules|CSS Modules]])는 로컬 범위(Local scope)의 CSS 클래스 이름을 자동으로 생성하여 컴포넌트 단위로 스타일을 캡슐화하는 CSS 아키텍처 및 도구입니다 [1, 2]. 빌드 타임에 클래스 이름을 고유한 식별자로 변환하여 글로벌 네임스페이스 충돌을 원천적으로 방지하며, 표준 CSS 문법을 유지하면서도 대규모 프론트엔드 프로젝트에서 뛰어난 안정성과 유지보수성을 제공합니다 [1, 3].
|
||||
## 매 한 줄
|
||||
> **"매 modular CSS = scope by component, not by selector convention"**. 매 BEM/SMACSS — 매 naming convention — 매 human discipline. 매 modern (2026) = 매 build-time scoping (CSS Modules, Vue/Svelte SFC, CSS-in-JS, Tailwind utility, `@scope` native).
|
||||
|
||||
## 📖 구조화된 지식 (Synthesized Content)
|
||||
* **작동 원리 및 주요 특징:**
|
||||
CSS Modules는 자바스크립트 컴포넌트로 CSS 파일을 임포트할 때, 빌드 도구(Webpack, Vite 등)가 사람이 읽을 수 있는 클래스 이름을 고유한 식별자(예: `Button_button__x9KdL`)로 변환하는 방식으로 작동합니다 [1, 4]. 이 과정에서 런타임 자바스크립트 실행 없이 정적 CSS를 생성하므로 오버헤드가 발생하지 않습니다 [3, 5]. 표준 CSS 문법은 물론 미디어 쿼리, 복잡한 애니메이션, 의사 요소(pseudo-elements) 등을 제약 없이 사용할 수 있으며, Sass([[SCSS|SCSS]])와 같은 전처리기와도 매끄럽게 통합됩니다 [1, 6].
|
||||
## 매 핵심
|
||||
|
||||
* **장점 (유지보수 및 성능):**
|
||||
가장 큰 장점은 완벽한 로컬 스코프(Local scope)를 통한 캡슐화로, 다른 컴포넌트와의 스타일 충돌이나 스타일 누수(Leakage)를 방지한다는 것입니다 [1, 2]. 제로 런타임 오버헤드 덕분에 렌더링 성능이 매우 우수하며 브라우저 캐싱을 효과적으로 활용할 수 있습니다 [7, 8]. 또한 타입스크립트(TypeScript)와 결합하여 빌드 타임에 오타를 잡을 수 있으며, 여러 팀이 협업하는 환경에서 클래스 명명에 대한 논쟁을 줄이고 컴포넌트의 소유권을 명확히 할 수 있습니다 [9].
|
||||
### 매 진화
|
||||
1. **Global** (no scope) — 매 conflict 지옥.
|
||||
2. **BEM/SMACSS** — naming convention — 매 human-enforced.
|
||||
3. **CSS Modules** — build-time hash — 매 automated.
|
||||
4. **CSS-in-JS** (Emotion, styled-components) — 매 runtime + scope.
|
||||
5. **Tailwind utility** — 매 inline atomic.
|
||||
6. **Native `@scope`** (Chrome 118+) — 매 browser scope.
|
||||
7. **Shadow DOM** — 매 web component native scope.
|
||||
|
||||
* **단점 및 한계:**
|
||||
로직이 담긴 자바스크립트 파일과 스타일이 담긴 CSS 파일 두 곳을 오가며 작업해야 하는 컨텍스트 스위칭(Context switching)의 번거로움이 있습니다 [5]. 또한, 스타일 충돌은 방지되지만 클래스 이름 자체는 개발자가 직접 지어주어야 하므로 작명 피로도(Naming fatigue)가 여전히 존재합니다 [5]. 더불어 컴포넌트의 props나 상태에 따라 동적으로 스타일을 할당하려면 문자열 연결이나 헬퍼 라이브러리를 거쳐야 하며, CSS와 자바스크립트 간의 데이터 공유가 까다로운 편입니다 [5, 6].
|
||||
### 매 트레이드오프
|
||||
- 매 scope 강도 vs runtime cost vs DX.
|
||||
- CSS Modules — 매 zero runtime, 매 build only.
|
||||
- CSS-in-JS — 매 dynamic, 매 runtime cost.
|
||||
- Tailwind — 매 zero CSS bundle (used 만), 매 HTML 매 noisy.
|
||||
|
||||
* **실무 전략 및 권장 사항:**
|
||||
CSS Modules는 복잡한 커스텀 디자인 시스템이나 정교한 애니메이션이 필요하며, 기존 바닐라 CSS나 SCSS 기반의 환경에서 마이그레이션하려는 조직에 가장 적합한 전략으로 평가받습니다 [8, 10]. 2025년 기준, [[Next.js App Router|Next.js App Router]](React Server Components)와 같은 최신 환경에서는 성능 오버헤드가 큰 런타임 [[CSS-in-JS|CSS-in-JS]]를 대신할 가장 훌륭한 대안 중 하나로 강력히 권장됩니다 [11, 12]. 실무에서는 완벽한 캡슐화의 이점을 누리면서도 CSS Modules 파일 내부적으로 BEM(Block Element Modifier) 네이밍 규칙을 일부 결합하여 가독성을 높이는 방법도 널리 사용됩니다 [13].
|
||||
### 매 응용
|
||||
1. Design system component library.
|
||||
2. Multi-team monorepo (style 충돌 방지).
|
||||
3. SSR/streaming (critical CSS extraction).
|
||||
|
||||
## 🔗 지식 연결 (Graph)
|
||||
- **Related Topics:** [[BEM|BEM]], Tailwind CSS, CSS-in-JS, [[CSS 구조 설계 방식|CSS 구조 설계 방식]]
|
||||
- **Projects/Contexts:** [[React 서버 컴포넌트 (RSC) 및 Next.js 환경|React 서버 컴포넌트 (RSC) 및 Next.js 환경]], [[대규모 프론트엔드 프로젝트 아키텍처|대규모 프론트엔드 프로젝트 아키텍처]]
|
||||
- **Contradictions/Notes:** 소스에 따르면, 전통적인 BEM 방식은 개발자의 수동적인 규칙 준수에 의존하기 때문에 실수로 인한 스타일 충돌 가능성이 남아 있는 반면, CSS Modules는 빌드 도구를 통해 식별자를 생성함으로써 이를 시스템적으로 완벽히 자동화하여 해결합니다 [2, 14]. 또한 [[Tailwind CSS|Tailwind CSS]]는 파일을 이동할 필요 없이 빠른 개발이 가능하지만 마크업(HTML/JSX)이 매우 장황해진다는 단점이 있는 반면, CSS Modules는 마크업을 깔끔하게 유지할 수 있는 대신 스타일 파일과 로직 파일을 오가는 컨텍스트 스위칭 비용이 발생합니다 [5, 15].
|
||||
## 💻 패턴
|
||||
|
||||
---
|
||||
*Last updated: 2026-04-26*
|
||||
|
||||
## 🤖 LLM 활용 힌트 (How to Use This Knowledge)
|
||||
|
||||
**언제 이 지식을 쓰는가:**
|
||||
- *(TODO)*
|
||||
|
||||
**언제 쓰면 안 되는가:**
|
||||
- *(TODO)*
|
||||
|
||||
## 🧪 검증 상태 (Validation)
|
||||
|
||||
- **정보 상태:** needs_review
|
||||
- **출처 신뢰도:** A
|
||||
- **검토 이유:** *(P-Reinforce Phase 1 자동 정규화. 본문 검증 필요.)*
|
||||
|
||||
## 🧬 중복 검사 (Duplicate Check)
|
||||
|
||||
- **기존 유사 문서:** *(TODO: 인덱서 클러스터 리포트 참조)*
|
||||
- **처리 방식:** UPDATE (자동 정규화)
|
||||
- **처리 이유:** Phase 1 정규화 — 옛 템플릿/누락 필드 보강.
|
||||
|
||||
## ⚠️ 모순 및 업데이트 (Contradictions & Updates)
|
||||
|
||||
- **과거 데이터와의 충돌:** 없음
|
||||
- **정책 변화:** 없음
|
||||
|
||||
## 🕓 변경 이력 (Changelog)
|
||||
|
||||
| 날짜 | 변경 내용 | 처리 방식 | 신뢰도 |
|
||||
|------|-----------|-----------|--------|
|
||||
| 2026-05-08 | P-Reinforce Phase 1 정규화 (frontmatter + 헤더 표준화) | UPDATE | A |
|
||||
|
||||
## 💻 코드 패턴 (Code Patterns)
|
||||
|
||||
**패턴 1:** *(TODO: 이 프로젝트 컨벤션 반영한 구조 스켈레톤)*
|
||||
|
||||
```text
|
||||
# TODO
|
||||
### CSS Modules
|
||||
```css
|
||||
/* Button.module.css */
|
||||
.button { padding: 0.5rem 1rem; border-radius: 4px; }
|
||||
.primary { background: #3b82f6; color: white; }
|
||||
```
|
||||
|
||||
## 🤔 의사결정 기준 (Decision Criteria)
|
||||
```jsx
|
||||
import styles from './Button.module.css';
|
||||
export const Button = () =>
|
||||
<button className={`${styles.button} ${styles.primary}`}>Click</button>;
|
||||
// 매 빌드 후: class="Button_button__a1b2c Button_primary__d3e4f"
|
||||
```
|
||||
|
||||
**선택 A를 써야 할 때:**
|
||||
- *(TODO)*
|
||||
### Native @scope (modern)
|
||||
```html
|
||||
<style>
|
||||
@scope (.card) {
|
||||
h2 { color: #111; font-size: 1.25rem; }
|
||||
/* 매 .card 내부 h2 만 — 매 outer h2 의 X */
|
||||
}
|
||||
</style>
|
||||
<article class="card">
|
||||
<h2>Title</h2> <!-- 매 styled -->
|
||||
</article>
|
||||
<h2>Outside</h2> <!-- 매 unstyled -->
|
||||
```
|
||||
|
||||
**선택 B를 써야 할 때:**
|
||||
- *(TODO)*
|
||||
### Vue SFC scoped
|
||||
```vue
|
||||
<template>
|
||||
<button class="btn">Click</button>
|
||||
</template>
|
||||
<style scoped>
|
||||
.btn { padding: 0.5rem 1rem; }
|
||||
/* 매 빌드: .btn[data-v-abc123] — 매 component 만 */
|
||||
</style>
|
||||
```
|
||||
|
||||
**기본값:**
|
||||
> *(TODO)*
|
||||
### Svelte (auto-scoped)
|
||||
```svelte
|
||||
<button>Click</button>
|
||||
<style>
|
||||
button { padding: 0.5rem 1rem; }
|
||||
/* 매 빌드: button.svelte-abc123 — 매 자동 */
|
||||
</style>
|
||||
```
|
||||
|
||||
## ❌ 안티패턴 (Anti-Patterns)
|
||||
### Tailwind utility (atomic)
|
||||
```jsx
|
||||
<button className="px-4 py-2 rounded bg-blue-500 text-white hover:bg-blue-600">
|
||||
Click
|
||||
</button>
|
||||
/* 매 component CSS file 의 X — 매 utility 만 */
|
||||
```
|
||||
|
||||
- **[안티패턴]:** *(TODO: 무엇을 하면 안 되는가 + 이유 + 대신 무엇을)*
|
||||
### CSS-in-JS (Emotion)
|
||||
```jsx
|
||||
import { css } from '@emotion/react';
|
||||
|
||||
const buttonStyle = css`
|
||||
padding: 0.5rem 1rem;
|
||||
background: ${props => props.primary ? '#3b82f6' : '#fff'};
|
||||
`;
|
||||
|
||||
<button css={buttonStyle} />
|
||||
```
|
||||
|
||||
### CUBE CSS (modern hybrid)
|
||||
```css
|
||||
/* Composition + Utility + Block + Exception */
|
||||
.card {
|
||||
/* Block */
|
||||
display: grid;
|
||||
gap: 1rem;
|
||||
}
|
||||
/* Utility */
|
||||
.[--flow-space\:1rem] > * + * { margin-top: 1rem; }
|
||||
/* Exception (data attr) */
|
||||
.card[data-variant="dense"] { gap: 0.5rem; }
|
||||
```
|
||||
|
||||
### Layered cascade (`@layer`)
|
||||
```css
|
||||
@layer reset, base, components, utilities;
|
||||
|
||||
@layer reset { /* normalize */ }
|
||||
@layer base { body { font: 16px/1.5 system-ui; } }
|
||||
@layer components { .button { ... } }
|
||||
@layer utilities { .text-center { text-align: center; } }
|
||||
/* 매 specificity 매 layer order — 매 명확 */
|
||||
```
|
||||
|
||||
## 매 결정 기준
|
||||
| 상황 | 접근 |
|
||||
|---|---|
|
||||
| React/Next + zero runtime | CSS Modules |
|
||||
| Vue/Svelte | SFC scoped |
|
||||
| Rapid prototyping + utility | Tailwind |
|
||||
| Design tokens + dynamic | CSS-in-JS (Emotion) OR vanilla-extract |
|
||||
| Modern stack 매 native | `@scope` + `@layer` |
|
||||
| Web Components | Shadow DOM |
|
||||
| Legacy global stylesheet | BEM convention |
|
||||
|
||||
**기본값**: React = CSS Modules + Tailwind hybrid, Vue/Svelte = SFC scoped, multi-team = `@layer` + `@scope`.
|
||||
|
||||
## 🔗 Graph
|
||||
- 부모: [[CSS]] · [[Frontend Architecture]]
|
||||
- 변형: [[CSS Modules]] · [[CSS-in-JS]] · [[Tailwind CSS]]
|
||||
- 응용: [[Design System]] · [[Component Library]]
|
||||
- Adjacent: [[BEM]] · [[Shadow DOM]] · [[CSS Cascade Layers]]
|
||||
|
||||
## 🤖 LLM 활용
|
||||
**언제**: stack 결정, BEM → CSS Modules migration, `@scope` 사용 가능 여부.
|
||||
**언제 X**: 매 design taste — 매 utility 매 readable 의 결정 — 매 team preference.
|
||||
|
||||
## ❌ 안티패턴
|
||||
- **`!important` 매 conflict 우회**: 매 scope 누락의 sign.
|
||||
- **Global selector + tag (`div p`)**: 매 cascade 충돌.
|
||||
- **CSS-in-JS runtime cost 무시**: 매 LCP 영향.
|
||||
- **BEM 끝없는 nesting** (`block__el--mod__sub`): 매 component 분리의 신호.
|
||||
- **Tailwind class 50개 한 줄**: 매 component 매 추출.
|
||||
|
||||
## 🧪 검증 / 중복
|
||||
- Verified (MDN @scope/@layer, CSS Modules spec, web.dev, Vue/Svelte docs).
|
||||
- 신뢰도 A.
|
||||
|
||||
## 🕓 Changelog
|
||||
| 날짜 | 변경 |
|
||||
|---|---|
|
||||
| 2026-05-08 | Phase 1 |
|
||||
| 2026-05-10 | Manual cleanup — scope strategies + @scope native |
|
||||
|
||||
Reference in New Issue
Block a user