# [[Building Reusable UI Components]]

## 📌 Brief Summary
재사용 가능한 UI 컴포넌트는 여러 프로젝트와 위치에서 코드를 크게 수정하지 않고도 사용할 수 있는 독립적이고 이식성(Portable)과 예측 가능성(Predictable)이 뛰어난 UI 구성 요소입니다 [1]. 이는 단일 책임을 가지며 명확한 API(Props)와 접근성(Accessibility)을 갖추어 확장 가능하고 일관성 있는 디자인 시스템을 구축하는 핵심 역할을 합니다 [2, 3]. 최신 React 생태계에서는 복잡성을 줄이기 위해 단순한 Prop 전달을 넘어서, 컴파운드 컴포넌트나 헤드리스 컴포넌트와 같은 고급 합성 패턴을 활용하여 재사용성을 극대화합니다 [4, 5].

## 📖 Core Content
* **재사용 가능한 컴포넌트의 4가지 핵심 원칙 (Four Golden Rules)**:
  * **단일 책임 (Single Responsibility):** 각 컴포넌트는 한 가지 기능만 잘 수행하도록 만들어 버그를 줄이고 재사용성을 높여야 합니다 [3].
  * **상속보다 합성 (Composition Over Inheritance):** 의견이 배제된(unopinionated) 기본 컴포넌트들을 블록처럼 조립하여 더 큰 컴포넌트를 구성해야 합니다 [3].
  * **명확한 계약 (Explicit Contracts):** 컴포넌트가 받는 값(Props)과 반환하는 이벤트(Callbacks)의 API를 명확히 정의하여 부작용을 방지해야 합니다 [3, 6].
  * **접근성 우선 (Accessibility First):** 키보드 내비게이션, ARIA 역할(Roles), 포커스 관리 등 스크린 리더 및 모든 사용자를 위한 접근성을 기본적으로 내장해야 합니다 [3, 7].

* **상태 관리 및 API 설계 (State Boundaries & API Design)**:
  * Prop 기반의 API는 요구사항이 늘어날수록 수많은 상태 변수(Prop Soup)를 발생시켜 확장을 어렵게 만듭니다 [6, 8]. 의도에 맞는 Prop 이름을 사용하고 안전한 기본값(Defaults)을 설정해야 합니다 [6].
  * 툴팁 토글과 같은 로컬 UI 상태는 컴포넌트 내부에 유지하되, 필터링이나 데이터 호출과 같은 비즈니스 로직은 상위 부모 컴포넌트로 올려야(Push up) 재사용성이 높아집니다 [9].

* **재사용성을 극대화하는 고급 React 패턴 (Scalable Component Patterns)**:
  * **컴파운드 컴포넌트 (Compound Components):** 아코디언(Accordion)이나 탭(Tabs)처럼 여러 하위 컴포넌트가 Context를 통해 암시적으로 상태를 공유하도록 구성하여, 소비자가 레이아웃을 유연하게 제어할 수 있게 합니다 [10-12].
  * **헤드리스 컴포넌트 (Headless Components):** 시각적인 마크업(UI) 없이 상태와 동작 로직만 제공하여, 디자인 시스템과 무관하게 접근성 높고 재사용 가능한 컴포넌트를 만들 수 있습니다 [13-15].
  * **렌더 프롭스 (Render Props):** 함수를 자식 요소로 전달하여 로직을 공유하고 렌더링에 대한 완전한 제어권을 사용자에게 부여합니다 [15, 16].
  * **슬롯 및 영역 (Slots / Regions):** 소비자가 직접 콘텐츠를 끼워 넣을 수 있는 의도적인 빈 공간(예: 헤더, 푸터)을 제공하여 Prop의 과부하를 막습니다 [14].

* **스타일링과 테마 적용 (Styling & Theming)**:
  * 재사용 가능한 컴포넌트는 하드코딩된 스타일을 피하고, 색상이나 간격 등의 디자인 토큰(Design Tokens)을 기반으로 브랜드의 룩을 상속받아야 합니다 [17].
  * 구조를 캡슐화하면서도 클래스 이름이나 스타일 Prop을 주입할 수 있는 훅을 노출하여, 코드를 포크(Fork)하지 않고도 여러 제품 스킨이나 다크 모드 테마에 유연하게 대응하도록 설계해야 합니다 [17, 18].

## 🔗 Knowledge Connections
- **Related Topics:** [[Compound Components]], [[Headless Components]], [[Atomic Design]], [[Design Tokens]]
- **Projects/Contexts:** [[Shopify Polaris]] (재사용 가능한 컴포넌트와 접근성을 제공하여 일관된 앱 UI를 구축하는 쇼피파이의 디자인 시스템 [19, 20]), [[Uber Base Web]] (다양한 요구사항에 대응하기 위해 모든 하위 요소의 스타일과 기능을 제어할 수 있는 'Overrides' 패턴을 구현한 React 컴포넌트 라이브러리 사례 [21, 22])
- **Contradictions/Notes:** 컴파운드 컴포넌트는 뛰어난 레이아웃 구성의 자유도를 제공하지만 [10], 지나친 자유도는 UX 일관성을 해칠 수 있으며, 단순하고 구조가 고정된 컴포넌트(예: 버튼, 아이콘)에 사용할 경우 불필요한 추상화와 유지보수 비용만 증가시키게 되므로 상황에 맞게 적용해야 합니다 [23-25].

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