# [[CSS Variables|CSS Variables]]

## 📌 Brief Summary
CSS Variables(사용자 지정 속성, CSS custom properties)은 React 및 최신 프론트엔드 프로젝트에서 디자인 토큰을 관리하고 동적 테마를 구현하는 데 사용되는 핵심 기반 기술입니다. 이 기술은 애플리케이션 전반에 걸쳐 하드코딩된 스타일 값을 대체하여 디자인의 일관성을 유지하고, 라이트/다크 모드와 같은 테마 전환을 쉽게 만듭니다. 특히 [[Tailwind CSS v4|Tailwind CSS v4]]와 같은 최신 프레임워크나 styled-components와 같은 CSS-in-JS 환경에서 [[React Server Components|React Server Components]](RSC) 호환성 및 런타임 성능 최적화를 달성하기 위한 필수적인 해결책으로 채택되고 있습니다.

## 📖 Core Content
* **디자인 토큰과 동적 테마([[Dynamic Theming|Dynamic Theming]])의 핵심:**
  CSS 변수는 색상, 타이포그래피, 간격 등의 디자인 토큰을 중앙 집중화하여 관리하는 단일 진실 공급원([[Single_Source_of_Truth|Single Source of Truth]]) 역할을 합니다 [1, 2]. Style Dictionary와 같은 도구를 사용해 JSON 형식의 디자인 토큰을 CSS 변수(예: `--color-primary`)로 변환하고 이를 `:root` 레벨에 정의하면, [[JavaScript|JavaScript]]의 개입 없이도 기본 테마나 라이트/다크 모드를 동적으로 전환할 수 있습니다 [3-6].

* **[[Tailwind CSS|Tailwind CSS]] v4의 CSS 우선(CSS-first) 아키텍처:**
  Tailwind CSS v4는 기존의 JavaScript 설정 파일(tailwind.config.js)을 제거하고 `@theme` 디렉티브를 사용하여 디자인 토큰을 기본 CSS 변수로 직접 노출합니다 [7-10]. 이를 통해 개발자는 JavaScript 구동 컨텍스트 업데이트 없이 런타임 테마 적용과 타입 안정성(Type Safety)을 확보할 수 있습니다 [10, 11]. 또한, 생성된 정규 CSS 변수는 인라인 스타일이나 임의의 값(arbitrary values)에서 참조할 수 있으며, JavaScript의 `getComputedStyle`을 통해서도 쉽게 접근이 가능합니다 [12-14].

* **styled-components 및 RSC 환경에서의 한계 극복:**
  React [[Server Components|Server Components]](RSC) 환경에서는 [[React Context|React Context]]가 제공되지 않기 때문에, styled-components나 Emotion이 의존하던 `ThemeProvider`를 통한 동적 테마 주입이 작동하지 않습니다 [15-17]. 이를 해결하기 위해 styled-components v6.4+ 에서는 `createTheme` 함수를 도입하여 테마 객체의 모든 리프(leaf) 값을 CSS 변수 참조(`var(--prefix-path)`)로 변환합니다 [18]. 이 접근법을 사용하면 React 컨텍스트 없이도 클라이언트 컴포넌트와 RSC 모두에서 안정적으로 테마를 적용할 수 있습니다 [18].

* **컴포넌트 아키텍처 내에서의 유연한 결합:**
  정의된 CSS 변수는 인라인 스타일, CSS 모듈, 혹은 styled-components와 같은 CSS-in-JS 라이브러리 내부에서 모두 호환되어 사용 가능합니다 [19]. 이는 특정 스타일링 패러다임에 종속되지 않고 애플리케이션의 시각적 일관성을 유지할 수 있도록 도와줍니다 [19, 20].

## 🔗 Knowledge Connections
- **Related Topics:** `[[Design Tokens|Design Tokens]]`, `Dynamic Theming`, `Tailwind CSS v4`, `[[React Server Components (RSC)|React Server Components (RSC]]`, `[[Styled Components|Styled Components]]`
- **Projects/Contexts:** `[[Next.js App Router|Next.js App Router]]` (RSC 환경 도입으로 인한 CSS-in-JS의 한계 및 CSS 변수를 활용한 테마 관리 체계로의 전환 맥락 [15-17]), `Figma DesignSystem Integration` ([[Figma|Figma]]에서 정의된 토큰을 CSS 변수로 변환하여 자동화된 워크플로우를 구축하는 프로젝트 환경 [21-23])
- **Contradictions/Notes:** 기존 CSS-in-JS 라이브러리(styled-components, Emotion)는 런타임에 JavaScript로 스타일을 생성하여 컴포넌트 수준의 강력한 동적 스타일링을 제공했으나 렌더링 성능과 RSC 호환성에서 단점이 존재했습니다. 최근에는 런타임 오버헤드가 없는 정적 빌드타임 CSS 변수(Tailwind CSS v4, [[vanilla-extract|vanilla-extract]]) 기반 접근법이 규모가 큰 프로덕션 환경에서 더욱 선호되는 추세입니다 [16, 17, 24-26].

---
*Last updated: 2026-04-26*