# [[React Frontend Architecture|React Frontend Architecture]]

## 📌 Brief Summary
React 프론트엔드 아키텍처는 확장 가능하고 유지보수가 용이하며 고성능인 사용자 인터페이스를 구축하기 위한 구조 및 스타일링 패러다임을 의미합니다. 이는 [[Tailwind CSS|Tailwind CSS]]와 같은 정적 유틸리티 기반 프레임워크와 styled-components와 같은 런타임 CSS-in-JS 솔루션 간의 전략적 선택을 포함하며, 특히 [[React Server Components|React Server Components]](RSC) 환경에서의 성능과 호환성이 핵심 고려 사항이 됩니다. 더불어 Atomic Design, [[Compound Components|Compound Components]] 등의 컴포넌트 설계 패턴과 디자인 토큰, [[Feature-Sliced Design|Feature-Sliced Design]](FSD) 기반의 모노레포 구조를 결합하여 대규모 애플리케이션의 일관성과 재사용성을 극대화합니다.

## 📖 Core Content
*   **스타일링 패러다임 (Tailwind CSS vs styled-components):**
    *   **Tailwind CSS:** 유틸리티 클래스를 기반으로 빌드 타임에 정적 CSS를 생성하여 런타임 오버헤드를 제거한 프레임워크입니다 [1-3]. v4에서는 자바스크립트 구성 대신 `@theme` 및 `@source` 디렉티브와 네이티브 CSS 변수를 활용하는 'CSS-first' 아키텍처를 도입하였으며, Rust 기반 Oxide 엔진을 통해 빌드 속도를 크게 향상시켰습니다 [4-6]. 자바스크립트 실행에 의존하지 않으므로 RSC(React [[Server Components|Server Components]]) 및 Next.js App Router와 높은 호환성을 보이며, styled-components에서 Tailwind로 마이그레이션한 사례에서는 FID(First Input Delay) 및 INP(Interaction to Next Paint)와 같은 [[Core Web Vitals|Core Web Vitals]] 지표가 획기적으로 개선되었습니다 [7-11].
    *   **styled-components:** Tagged template literals를 사용하여 [[JavaScript|JavaScript]] 내에서 CSS를 정의하고 컴포넌트 단위로 스타일을 캡슐화합니다 [12-14]. 동적 스타일링에 매우 유리하지만, 브라우저가 런타임에 스타일을 생성하고 주입해야 하므로 CPU 및 JavaScript 오버헤드가 발생합니다 [3, 15, 16]. 기존 방식은 [[Context API|Context API]]에 의존하여 서버 컴포넌트 환경(RSC)과 근본적으로 호환되지 않는 문제가 있었으나 [17, 18], v6 업데이트를 통해 `createTheme`을 활용한 CSS 변수 테마 시스템과 `stylisPluginRSC` 플러그인을 도입하여 RSC 환경을 지원하기 시작했습니다 [19-22].

*   **확장 가능한 컴포넌트 아키텍처:**
    *   **Atomic Design:** UI를 원자(Atoms), 분자(Molecules), 유기체(Organisms), 템플릿(Templates), 페이지(Pages) 단위로 나누어 설계하는 방법론으로, 컴포넌트의 재사용성과 일관된 계층 구조를 확립합니다 [23-26].
    *   **Compound Components (복합 컴포넌트):** 과도한 Prop 전달로 인한 구조적 취약점(Prop soup)을 방지하는 패턴입니다 [27-29]. 부모 컴포넌트가 Context를 통해 내부 상태를 공유하고 하위 컴포넌트(예: `Accordion.Header`, `Accordion.Body`)를 조립하여 사용함으로써 레이아웃의 유연성을 높입니다 [28, 30, 31].
    *   **[[Headless Components|Headless Components]] & Overrides Pattern:** [[Headless UI|Headless UI]]는 상태 관리 및 접근성 로직만 제공하고 시각적 마크업은 개발자에게 완전히 위임하여 뛰어난 재사용성을 보장합니다 [32-34]. 또한, Uber의 Base Web 등에서는 구성 요소의 내부 하위 요소까지 덮어쓰기(override)할 수 있는 Overrides Pattern을 사용하여 컴포넌트 API의 비대화를 방지하고 있습니다 [35-37].

*   **디자인 토큰과 동적 테마 ([[Design Tokens|Design Tokens]] & Theming):**
    *   디자인 토큰은 색상, 간격, 타이포그래피 등의 시각적 결정을 코드화한 단일 진실 공급원([[Single_Source_of_Truth|Single Source of Truth]])입니다 [38, 39]. 효율적인 관리를 위해 원시 토큰(Primitive, 예: `#3366FF`), 목적에 맞게 매핑된 시맨틱 토큰(Semantic, 예: `color.primary`), 개별 요소를 지정하는 컴포넌트 토큰(Component, 예: `button.background`)의 3계층 구조로 설계하는 것이 모범 사례입니다 [40-43].
    *   [[Style Dictionary|Style Dictionary]] 도구나 Tailwind v4를 활용하여 JSON/YAML 형태의 토큰을 React에서 사용 가능한 CSS Custom Properties(CSS 변수)로 변환하면, 컴포넌트 수정 없이 다크 모드 등 동적 테마 적용을 자동화할 수 있습니다 [44-47].

*   **확장 가능한 조직화 (모노레포와 FSD):**
    *   규모가 큰 프론트엔드 환경에서는 다수의 애플리케이션과 공유 라이브러리의 종속성을 효율적으로 관리하기 위해 모노레포([[Monorepo|Monorepo]]) 아키텍처(pnpm workspaces, [[Turborepo|Turborepo]], Nx 등 사용)를 채택합니다 [48-50].
    *   **[[Feature-Sliced Design (FSD)|Feature-Sliced Design (FSD]]:** 대규모 코드베이스의 일관성을 위해 코드를 Shared, Entities, Features, Widgets, Pages, App의 계층 구조로 나누어 의존성을 단방향으로 통제하고, 내부 세부 구현이 타 모듈로 유출되는 것을 막는 방법론입니다 [51-53].

## 🔗 Knowledge Connections
- **Related Topics:** `[[Tailwind CSS|Tailwind CSS]]`, `Styled Components`, `Atomic Design`, `[[Compound Components|Compound Components]]`, `Design Tokens`, `[[React Server Components (RSC)|React Server Components (RSC]]`, `[[Feature-Sliced Design (FSD)|Feature-Sliced Design (FSD]]`
- **Projects/Contexts:** `[[Shopify Polaris|Shopify Polaris]]`, `Uber Base Web`, `Next.js App Router`, `[[Radix UI|Radix UI]]`
- **Contradictions/Notes:** 소스 [54]와 [55]에서는 [[Styled Components|Styled Components]]가 특정 벤치마크나 소규모 앱에서 빠른 시작 시간을 제공할 수 있다고 언급합니다. 그러나 소스 [56], [9], [10]는 실제 대규모 렌더링 테스트와 엔터프라이즈 환경에서 Tailwind CSS가 Styled Components보다 런타임 오버헤드가 없으며 Core Web Vitals(FID, INP) 및 서버 CPU 지연 시간 측면에서 압도적으로 우수하다고 상반되게 강조합니다. 또한, 소스 [17]은 기존 CSS-in-JS가 React Server Components와 호환되지 않는다고 지적하지만, 소스 [21], [22]은 [[Styled Components v6|Styled Components v6]] 업데이트에서 인라인 스타일 삽입 방식과 `stylisPluginRSC`를 도입하여 RSC 환경을 공식적으로 지원하기 시작했다고 덧붙이고 있습니다.

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