2nd/10_Wiki/Topics/CSS_Architecture_and_Styling.md

---
id: wiki-2026-0508-css-architecture-and-styling
title: CSS Architecture and Styling
category: 10_Wiki/Topics
status: verified
canonical_id: self
aliases: [CSS Patterns, Styling Architecture, CSS Methodologies]
duplicate_of: none
source_trust_level: A
confidence_score: 0.92
verification_status: applied
tags: [css, frontend, design-system, web]
raw_sources: []
last_reinforced: 2026-05-10
github_commit: pending
tech_stack:
  language: CSS/TS
  framework: Tailwind v4 / CSS-in-JS / vanilla CSS
---

# CSS Architecture and Styling

## 매 한 줄
> **"매 CSS architecture 의 핵심: scope + composition + design tokens + 매 minimize specificity wars"**. 매 2010s OOCSS / BEM / SMACSS, 매 2017 CSS-in-JS, 매 2020 utility-first (Tailwind), 매 2024 native CSS (cascade layers, container queries, `:has()`, nesting, view transitions). 매 2026 현재 Tailwind v4 + CSS Modules + design-token system 의 dominant.

## 매 핵심

### 매 architecture pillars
- **Scoping**: 매 CSS Modules / Shadow DOM / Tailwind atomic / Vue scoped.
- **Tokens**: 매 design tokens (`--color-primary`) — 매 single source of truth.
- **Cascade layers**: 매 `@layer` — 매 explicit specificity ordering.
- **Container queries**: 매 component-level responsive (not viewport).
- **Logical properties**: 매 `margin-inline` — 매 i18n RTL/LTR free.

### 매 modern CSS features (2026 baseline)
- `@layer reset, base, components, utilities;`
- `@container (min-width: 30rem) { ... }`
- `:has(> img)` parent selector.
- Native nesting `&` (no preprocessor needed).
- `view-transition-name: card-hero;` for smooth navigation.
- `color-mix(in oklch, var(--brand) 80%, white)`.

### 매 응용
1. Design systems (Radix, shadcn/ui, Material 3).
2. Multi-brand white-label apps (token theming).
3. Email templates (limited subset).
4. Cross-platform (web + React Native via NativeWind).

## 💻 패턴

### Design tokens with CSS custom properties
```css
:root {
  --color-bg: oklch(98% 0.01 250);
  --color-fg: oklch(20% 0.03 250);
  --color-brand: oklch(60% 0.18 260);
  --space-1: 0.25rem;
  --space-2: 0.5rem;
  --radius: 0.5rem;
}
[data-theme="dark"] {
  --color-bg: oklch(15% 0.02 250);
  --color-fg: oklch(95% 0.01 250);
}
```

### Cascade layers (specificity sanity)
```css
@layer reset, base, components, utilities;

@layer reset {
  *, *::before, *::after { box-sizing: border-box; margin: 0; }
}
@layer components {
  .btn {
    background: var(--color-brand);
    color: white;
    padding: var(--space-2) var(--space-4);
    border-radius: var(--radius);
  }
}
@layer utilities {
  .mt-4 { margin-top: 1rem; }
}
```

### Container queries
```css
.card-grid { container-type: inline-size; }

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

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

@theme {
  --color-brand: oklch(60% 0.18 260);
  --font-display: "Inter Display", sans-serif;
  --breakpoint-3xl: 120rem;
}

@utility scrollbar-hidden {
  scrollbar-width: none;
  &::-webkit-scrollbar { display: none; }
}
```

### CSS Modules (Vite/Next)
```tsx
// Button.module.css
.btn { background: var(--color-brand); }
.btn:hover { filter: brightness(1.1); }

// Button.tsx
import s from "./Button.module.css";
export const Button = (p) => <button className={s.btn} {...p} />;
```

### CSS-in-JS (vanilla-extract, zero-runtime)
```ts
import { style, createTheme } from "@vanilla-extract/css";

export const [themeClass, vars] = createTheme({
  color: { brand: "oklch(60% 0.18 260)" },
});

export const button = style({
  background: vars.color.brand,
  padding: "0.5rem 1rem",
});
```

### View transitions API
```css
::view-transition-old(card),
::view-transition-new(card) {
  animation-duration: 0.3s;
}
```

```js
document.startViewTransition(() => updateDOM());
```

### `:has()` for parent-state styling
```css
.card:has(> img) { padding: 0; }
form:has(input:invalid) .submit { opacity: 0.5; }
```

## 매 결정 기준
| 상황 | Approach |
|---|---|
| Solo / small app | Tailwind v4 |
| Design system / library | CSS Modules + tokens, or vanilla-extract |
| Mature React app | shadcn/ui (Tailwind + Radix) |
| Web Components | Shadow DOM + adopted stylesheets |
| Static site / MPA | Native CSS + cascade layers |
| Email | Inline styles + table layout |

**기본값**: 매 web app 의 Tailwind v4 + design tokens + cascade layers.

## 🔗 Graph
- 부모: [[Web Standards]]
- 변형: [[CSS_Architecture_and_Styling|Tailwind CSS]] · [[CSS Modules]] · [[CSS_Architecture_and_Styling|CSS-in-JS]]
- 응용: [[Design Systems]]
- Adjacent: [[Accessibility (A11y)|Accessibility]] · [[Web Performance]] · [[Responsive Design]]

## 🤖 LLM 활용
**언제**: 매 component CSS scaffolding, 매 token system design, 매 Tailwind class consolidation, 매 legacy CSS refactor (BEM → cascade layers).
**언제 X**: 매 pixel-perfect designer review — 매 visual diff tooling 사용.

## ❌ 안티패턴
- **`!important` 의 남용**: 매 specificity war — 매 cascade layers 로 해결.
- **Magic numbers (`top: 17px`)**: 매 token / spacing scale 의 사용.
- **Global selectors (`div { ... }`)**: 매 leakage — 매 scoped 사용.
- **Inline styles for everything (CSS-in-JS overuse)**: 매 runtime cost.
- **Ignoring `prefers-reduced-motion`**: 매 a11y violation.
- **Pixel-only sizing**: 매 `rem` / `em` / `clamp()` 의 사용.

## 🧪 검증 / 중복
- Verified (MDN cascade layers, web.dev container queries, Tailwind v4 docs 2025, CSS Working Group specs).
- 신뢰도 A.

## 🕓 Changelog
| 날짜 | 변경 |
|---|---|
| 2026-05-08 | Phase 1 |
| 2026-05-10 | Manual cleanup — modern CSS 2026 (cascade layers, :has, Tailwind v4) |