# [[React Component Architecture|React Component Architecture]]

## 📌 Brief Summary
React Component [[Architecture|Architecture]](리액트 컴포넌트 아키텍처)는 확장 가능하고 유지보수가 용이하며 재사용 가능한 사용자 인터페이스(UI)를 구축하기 위한 구조적 방법론 및 설계 패턴을 의미합니다. 이 아키텍처는 아토믹 디자인(Atomic Design)과 같은 세분화 기준을 통해 컴포넌트를 계층적으로 구성하고, 컴파운드 컴포넌트(Compound Components)나 헤드리스 컴포넌트([[Headless Components|Headless Components]])와 같은 고급 합성 패턴을 사용하여 비즈니스 로직과 스타일링의 결합도를 낮춥니다. 잘 설계된 컴포넌트 아키텍처는 디자인 토큰([[Design Tokens|Design Tokens]])의 적용을 용이하게 하며, 거대한 단일 컴포넌트에 발생하는 'Prop 드릴링' 문제를 최소화하여 대규모 프론트엔드 환경에서의 일관성과 유연성을 보장합니다.

## 📖 Core Content

*   **재사용성을 위한 핵심 설계 원칙 (Foundational Rules):**
    효과적인 컴포넌트 아키텍처는 네 가지 핵심 원칙을 따릅니다 [1]. 첫째, 각 컴포넌트는 하나의 일만 잘 수행해야 하는 '단일 책임 원칙(Single Responsibility)'입니다. 둘째, '상속보다 합성(Composition Over Inheritance)'을 통해 작은 블록을 결합하여 큰 컴포넌트를 구성해야 합니다. 셋째, 명시적인 계약(Explicit Contracts)을 통해 컴포넌트의 API(prop)를 예측 가능하게 설계해야 합니다. 넷째, 접근성([[Accessibility|Accessibility]])을 최우선으로 고려하여 키보드 내비게이션이나 스크린 리더 지원을 내재화해야 합니다 [1, 2]. 

*   **아토믹 디자인 방법론 (Atomic Design):**
    UI를 구성하는 컴포넌트를 원자(Atoms), 분자(Molecules), 유기체(Organisms), 템플릿(Templates), 페이지(Pages)의 다섯 단계로 분류하는 아키텍처 접근법입니다 [3, 4]. 가장 기본적인 HTML 요소(버튼, 인풋 등)인 원자에서 시작하여, 이들을 조합한 분자(예: 검색 폼), 더 복잡한 유기체(예: 헤더)로 확장해 나갑니다 [5-7]. 이 방법론은 디자인 시스템의 일관성을 강제하고, 대규모 팀 환경에서 컴포넌트의 계층구조를 체계적으로 관리하는 데 매우 유용합니다 [8-10].

*   **컴파운드 컴포넌트 패턴 (Compound Components):**
    단일 컴포넌트에 수십 개의 Prop을 주입하는 대신(Prop-driven API), 여러 하위 컴포넌트들이 [[React Context|React Context]]를 통해 암묵적으로 상태를 공유하며 협력하는 합성 패턴입니다 [11-14]. 예를 들어 `Accordion.Root`, `Accordion.Item`, `Accordion.Header`, `Accordion.Body`와 같이 컴포넌트를 분리하여 소비자가 자유롭게 레이아웃과 순서를 결정할 수 있게 합니다 [15, 16]. 이를 통해 렌더링 유연성이 극대화되고 API가 훨씬 선언적이며 깔끔해집니다 [13, 17].

*   **헤드리스 컴포넌트 (Headless Components):**
    상태 관리([[State|State]])나 접근성(Accessibility) 같은 복잡한 비즈니스 로직 및 동작만을 캡슐화하여 제공하되, 시각적 마크업과 스타일링은 개발자가 완전히 자유롭게 정의할 수 있도록 하는 패턴입니다 [18, 19]. 복잡한 커스텀 UI 라이브러리를 구축할 때 필수적이며, 특히 [[Tailwind CSS|Tailwind CSS]]와 같은 유틸리티 우선(Utility-first) 스타일링과 결합할 때 강력한 시너지를 발휘합니다 [18].

*   **오버라이드 패턴 ([[Overrides Pattern|Overrides Pattern]]):**
    Uber의 Base Web과 같은 엔터프라이즈 디자인 시스템에서 활용되는 패턴으로, 하위 컴포넌트의 렌더링 동작, 추가 Prop, 그리고 스타일을 통째로 덮어쓰거나(Override) 교체할 수 있는 통합된 API를 제공합니다 [20-23]. 이를 통해 라이브러리 제작자가 모든 엣지 케이스(Edge Case)에 대비하여 개별 Prop을 만들 필요 없이('prop soup' 방지), 개발자에게 깊은 수준의 커스터마이징 권한을 부여할 수 있습니다 [21, 23].

*   **모노레포 및 [[Feature-Sliced Design|Feature-Sliced Design]] (FSD) 기반 아키텍처:**
    앱이 확장됨에 따라 단일 컴포넌트를 넘어 앱 간의 의존성을 관리하는 것이 중요해집니다 [24]. 모노레포([[Turborepo|Turborepo]], Nx 등) 내에서 Feature-Sliced Design 방법론을 적용하여 코드를 Shared(UI 원자, 토큰), Entities, Features, Widgets, Pages, App 레이어로 나누어 계층 간 엄격한 의존성 방향을 설정할 수 있습니다 [25]. 이는 '무분별한 공유 폴더' 문제를 방지하고, 기능 단위의 독립성과 확장 가능한 UI 아키텍처를 제공합니다 [9].

## 🔗 Knowledge Connections
- **Related Topics:** [[Atomic Design|Atomic Design]], Compound Components, Headless Components, [[Design Tokens|Design Tokens]], [[Feature-Sliced Design (FSD)|Feature-Sliced Design (FSD]]
- **Projects/Contexts:** [[Uber Base Web|Uber Base Web]], Shopify Polaris, Tailwind CSS, [[Styled Components|Styled Components]]
- **Contradictions/Notes:** 컴파운드 컴포넌트 패턴은 뛰어난 유연성을 제공하지만, 지나친 자유도(Too much freedom)로 인해 개발자가 서브 컴포넌트를 임의로 생략하거나 순서를 바꿔 UX와 접근성을 훼손할 위험이 존재합니다 [26]. 따라서 버튼, 아이콘, 배지 등 고정된 레이아웃을 가진 단순한 컴포넌트에는 적용을 피하고(단순한 Prop 방식이 더 안전함), 레이아웃 변형이 잦은 복잡한 UI(탭, 모달, 아코디언 등)에만 선택적으로 사용해야 합니다 [27, 28].

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