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

## 📌 Brief Summary
React 컴포넌트 라이브러리 아키텍처는 확장 가능하고 유지보수가 용이한 프론트엔드 환경을 구축하기 위해 재사용 가능한 UI 컴포넌트를 설계하고 조직화하는 구조적 접근 방식입니다 [1, 2]. 이 아키텍처는 단일 책임 원칙과 합성을 강조하며, Prop의 과도한 사용으로 인한 결합도 증가를 피하고 유연성을 높이는 것을 목표로 합니다 [3-6]. 아토믹 디자인([[Atomic Design|Atomic Design]]), 컴파운드 컴포넌트([[Compound Components|Compound Components]]), 헤드리스(Headless) UI 등 다양한 고급 디자인 패턴과 디자인 토큰을 결합하여 다양한 플랫폼 및 테마 요구사항에 대응할 수 있는 일관된 시스템을 제공합니다 [7-10].

## 📖 Core Content
*   **구조적 계층화 방법론 (Structural Methodologies)**
    *   **아토믹 디자인 (Atomic Design):** UI를 원자(Atoms: 버튼, 입력창 등), 분자(Molecules: 라벨이 있는 입력창 등), 유기체(Organisms: 헤더 등), 템플릿(Templates), 페이지(Pages)의 5단계로 세분화하는 방법론입니다 [2, 7, 11]. 이를 통해 일관성을 강제하고 추상적인 요소부터 구체적인 최종 UI까지 유기적인 설계가 가능합니다 [12-14].
    *   **[[Feature-Sliced Design|Feature-Sliced Design]] (FSD)와의 결합:** 대규모 애플리케이션이나 모노레포([[Monorepo|Monorepo]]) 환경에서는 범용적인 UI 원자(Atoms)를 'Shared' 계층의 별도 패키지로 분리하고, 비즈니스 로직은 'Features' 계층에 캡슐화하여 의존성 방향을 통제합니다 [15-17].

*   **확장성을 위한 컴포넌트 패턴 (Scalable Component Patterns)**
    *   **컴파운드 컴포넌트 (Compound Components):** `Select`와 `Option`의 관계처럼 여러 하위 컴포넌트들이 [[React Context|React Context]]를 통해 암시적으로 상태를 공유하며 하나의 단위로 작동하는 패턴입니다 [8, 18]. 소비자가 직접 레이아웃과 구성을 결정할 수 있게 하여 유연성을 극대화하며, 수많은 Prop으로 인한 'Prop 지옥(prop soup)'을 방지합니다 [3, 5, 8, 19].
    *   **헤드리스 컴포넌트 ([[Headless Components|Headless Components]]):** 복잡한 상태 관리와 접근성(A11y), 비즈니스 로직만을 캡슐화하여 제공하고 시각적인 마크업과 스타일링은 전적으로 개발자에게 위임하는 패턴입니다 [10, 20]. [[Tailwind CSS|Tailwind CSS]]와 같은 유틸리티 퍼스트 프레임워크와 함께 사용할 때 브랜딩에 맞춘 UI 라이브러리를 구축하는 데 매우 효과적입니다 [10].
    *   **오버라이드 패턴 ([[Overrides Pattern|Overrides Pattern]]):** Uber의 Base Web 등에서 사용되는 아키텍처로, 컴포넌트 내부의 각 하위 요소에 식별자를 부여하여 `overrides` Prop을 통해 개별 스타일, 속성, 심지어 렌더링되는 컴포넌트 자체를 교체할 수 있도록 합니다 [21-23].

*   **디자인 토큰과 테마 아키텍처 ([[Design Tokens|Design Tokens]] & Theming)**
    *   성공적인 컴포넌트 아키텍처는 컴포넌트 내부에 고정된 스타일 값을 사용하지 않고, 3계층의 디자인 토큰 시스템(원시 토큰, 시맨틱 토큰, 컴포넌트 토큰)을 활용하여 디자인 의도와 컴포넌트를 분리합니다 [24-27].
    *   이러한 토큰들은 CSS 변수(Custom Properties)로 변환되어 React 컴포넌트에 주입되며, 이를 통해 자바스크립트 컴파일 없이도 다크 모드 등 동적 런타임 테마 전환이 가능해집니다 [28-30]. 

*   **API 설계 및 접근성 (API Design & [[Accessibility|Accessibility]])**
    *   **명시적 계약:** 컴포넌트 API는 직관적이고 최소한의 Prop을 유지해야 하며, 부모 상태를 임의로 변이하지 않는 명시적인 계약을 가져야 합니다 [6, 31]. 
    *   **접근성(A11y) 내장:** 재사용 가능한 컴포넌트 아키텍처는 키보드 탐색, 올바른 ARIA 속성 및 역할 부여, 포커스 관리 등 화면 판독기 지원을 기본적으로 내장해야 합니다 [6, 32-34].

## 🔗 Knowledge Connections
- **Related Topics:** [[Atomic Design|Atomic Design]], Compound Components, Headless UI, [[Design Tokens|Design Tokens]], Tailwind CSS, [[Styled Components|Styled Components]], Monorepo, [[Feature-Sliced Design|Feature-Sliced Design]]
- **Projects/Contexts:** [[Radix UI|Radix UI]], Shopify Polaris, Uber Base Web, [[Next.js App Router|Next.js App Router]]
- **Contradictions/Notes:** 컴파운드 컴포넌트 패턴은 높은 구성 자유도를 제공하지만 과도한 추상화를 유발할 수 있습니다. 레이아웃이 고정되어 있거나 구조가 단순한 컴포넌트(예: 버튼, 아이콘, 배지 등)에는 컴파운드 패턴을 피하고 단순한 Prop 기반 컴포넌트를 사용하는 것이 더 안전하고 유지보수에 유리합니다 [35, 36].

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