2nd/10_Wiki/Topics/Frontend/유지보수 가능한 대규모 프론트엔드 CSS 설계.md

---
id: wiki-2026-0508-유지보수-가능한-대규모-프론트엔드-css-설계
title: 유지보수 가능한 대규모 프론트엔드 CSS 설계
category: 10_Wiki/Topics
status: verified
canonical_id: self
aliases: [Scalable CSS Architecture, CSS at Scale, Design System CSS]
duplicate_of: none
source_trust_level: A
confidence_score: 0.9
verification_status: applied
tags: [frontend, css, architecture, design-system]
raw_sources: []
last_reinforced: 2026-05-10
github_commit: pending
tech_stack:
  language: css
  framework: tailwind-css
---

# 유지보수 가능한 대규모 프론트엔드 CSS 설계

## 매 한 줄
> **"매 CSS 는 매 N 명 의 개발자 가 매 6개월 후 의 코드 base 에서 매 두려움 없이 수정할 수 있어야 한다"**. 매 대규모 CSS 의 적은 매 specificity 폭주, 매 dead code, 매 inconsistent spacing. 매 2026 의 정답 — utility-first (Tailwind 4) + design tokens + CSS Layers + container queries.

## 매 핵심

### 매 4 개 의 추상 레벨
- **Tokens**: color, spacing, typography 의 매 raw value (CSS custom property).
- **Primitives**: Box, Stack, Grid 의 매 layout primitive.
- **Components**: Button, Card, Modal — 매 design system 의 unit.
- **Patterns**: Page-level 조합.

### 매 방법론 비교
- **BEM**: `.block__element--modifier`. 매 명시적이지만 매 verbose.
- **CSS Modules**: 매 file-scoped, 매 collision 없음.
- **CSS-in-JS**: styled-components, Emotion — 매 runtime cost.
- **Utility-first (Tailwind)**: 매 2026 의 default — 매 zero runtime, JIT.
- **Vanilla Extract / Panda**: 매 typed CSS, build-time.

### 매 응용
1. Design System 구축 (Material, Ant, Chakra).
2. Multi-brand whitelabel (token swap).
3. Dark mode / theming.

## 💻 패턴

### Design tokens (CSS Custom Properties)
```css
:root {
  --color-primary-500: oklch(60% 0.2 270);
  --space-1: 0.25rem;
  --space-2: 0.5rem;
  --radius-md: 0.5rem;
  --font-body: "Inter", system-ui, sans-serif;
}

[data-theme="dark"] {
  --color-primary-500: oklch(75% 0.2 270);
}
```

### CSS Layers (cascade 제어)
```css
@layer reset, base, components, utilities;

@layer reset { *, *::before, *::after { box-sizing: border-box; } }
@layer base   { body { font-family: var(--font-body); } }
@layer components { .btn { padding: var(--space-2); } }
@layer utilities { .mt-4 { margin-top: var(--space-4); } }
```

### Tailwind 4 (CSS-first config)
```css
@import "tailwindcss";

@theme {
  --color-brand-500: oklch(60% 0.2 270);
  --spacing: 0.25rem;
}
```
```html
<button class="bg-brand-500 px-4 py-2 rounded-md text-white">매 Click</button>
```

### Container queries (매 layout-aware component)
```css
.card-container { container-type: inline-size; }

.card { display: grid; grid-template-columns: 1fr; }

@container (min-width: 30rem) {
  .card { grid-template-columns: 200px 1fr; }
}
```

### 컴포넌트 + variants (CVA)
```typescript
import { cva } from "class-variance-authority";

export const button = cva("rounded-md font-medium", {
  variants: {
    intent: {
      primary: "bg-brand-500 text-white",
      ghost: "bg-transparent text-brand-500",
    },
    size: { sm: "px-2 py-1", md: "px-4 py-2", lg: "px-6 py-3" },
  },
  defaultVariants: { intent: "primary", size: "md" },
});
```

### Logical properties (i18n-ready)
```css
.card {
  padding-inline: var(--space-4);   /* LTR / RTL 모두 동작 */
  margin-block-end: var(--space-2);
  border-inline-start: 2px solid var(--color-accent);
}
```

### Style scoping (CSS Modules)
```typescript
import styles from "./Card.module.css";
export const Card = ({ children }) => <div className={styles.card}>{children}</div>;
```

## 매 결정 기준
| 상황 | Approach |
|---|---|
| New project (2026) | Tailwind 4 + CVA + design tokens |
| Existing BEM codebase | 매 점진적 migration + Layers |
| Component library 출시 | CSS Modules or Vanilla Extract |
| Multi-brand SaaS | CSS custom properties + theme swap |

**기본값**: **Tailwind 4 + CVA + CSS custom property tokens + Container queries**.

## 🔗 Graph
- 부모: [[CSS_Architecture_and_Styling|CSS Architecture]] · [[Design System]]
- 변형: [[BEM]] · [[CSS Modules]] · [[CSS_Architecture_and_Styling|CSS-in-JS]]
- 응용: [[CSS_Architecture_and_Styling|Tailwind CSS]] · [[Vanilla Extract]] · [[Theming]]
- Adjacent: [[컨테이너 쿼리 (Container Queries)|Container Queries]]

## 🤖 LLM 활용
**언제**: 매 design system 구축, 매 large team, 매 multi-brand product.
**언제 X**: 매 single-page landing, 매 prototype.

## ❌ 안티패턴
- **Specificity 전쟁**: `!important` 남발 → 매 cascade 붕괴.
- **Magic numbers**: `padding: 13px` — 매 token 미사용.
- **Global selector overuse**: `div > p > span` — 매 brittle.
- **Dead CSS**: 매 unused selector 누적 → 매 bundle bloat.

## 🧪 검증 / 중복
- Verified (Tailwind 4 docs, MDN CSS Layers, CSS Tricks).
- 신뢰도 A.

## 🕓 Changelog
| 날짜 | 변경 |
|---|---|
| 2026-05-08 | Phase 1 |
| 2026-05-10 | Manual cleanup — scalable CSS 7 patterns |