2nd/10_Wiki/Topics/React Component Library Architecture.md

React Component Library Architecture

📌 Brief Summary

React 컴포넌트 라이브러리 아키텍처는 확장 가능하고 유지보수가 용이한 프론트엔드 환경을 구축하기 위해 재사용 가능한 UI 컴포넌트를 설계하고 조직화하는 구조적 접근 방식입니다 [1, 2]. 이 아키텍처는 단일 책임 원칙과 합성을 강조하며, Prop의 과도한 사용으로 인한 결합도 증가를 피하고 유연성을 높이는 것을 목표로 합니다 [3-6]. 아토믹 디자인(Atomic Design), 컴파운드 컴포넌트(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 (FSD)와의 결합: 대규모 애플리케이션이나 모노레포(Monorepo) 환경에서는 범용적인 UI 원자(Atoms)를 'Shared' 계층의 별도 패키지로 분리하고, 비즈니스 로직은 'Features' 계층에 캡슐화하여 의존성 방향을 통제합니다 [15-17].

• 확장성을 위한 컴포넌트 패턴 (Scalable Component Patterns)

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

• 디자인 토큰과 테마 아키텍처 (Design Tokens & Theming)

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

• API 설계 및 접근성 (API Design & Accessibility)

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

🔗 Knowledge Connections

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

---

Last updated: 2026-04-26