컴포넌트 설계 문서 작성

[monam2]

Summary

React 컴포넌트를 변경에 강하고 재사용 가능하게 설계하기 위한 컴포넌트 설계 지침 문서를 작성했습니다.

단일 책임 원칙을 기준으로 컴포넌트 경계를 나누는 방법을 정리하고, 복잡한 UI를 설계할 때 활용할 수 있는 Compound Components와 Headless UI 패턴을 문서화했습니다.

배경

컴포넌트가 커지거나 재사용 범위가 넓어질수록 아래와 같은 문제가 반복될 수 있습니다.

• 하나의 컴포넌트가 여러 변경 이유를 가지면서 수정 범위가 커지는 경우
• Tabs, Select, Menu처럼 여러 하위 요소가 함께 동작해야 하는 UI를 하나의 거대한 컴포넌트로 처리하는 경우
• 동작과 스타일이 강하게 결합되어 같은 기능을 다른 디자인으로 재사용하기 어려운 경우
• 접근성, 키보드 동작, 상태 노출 같은 컴포넌트 계약이 명확하지 않은 경우

이 문제들에 대해 팀 차원의 컴포넌트 설계 기준을 세우기 위해 문서를 작성했습니다.

팀 논의 내용

• 컴포넌트 설계 문서는 상태 위치, 커스텀 훅 추출, Props 세부 설계보다 컴포넌트의 책임 경계와 복합 UI 설계 패턴에 집중합니다.
• 단일 책임 원칙은 “컴포넌트 크기”보다 “변경 이유”를 기준으로 판단합니다.
• Compound Components는 단순 합성 패턴이 아니라, 여러 하위 컴포넌트가 같은 상태를 공유하는 복합 UI 설계 방식으로 다룹니다.
• Headless UI는 동작, 접근성, 상태 노출은 컴포넌트가 담당하고, 마크업과 스타일은 사용하는 쪽에서 제어할 수 있도록 분리하는 패턴으로 정리했습니다.
• children, render props, slot 선택 기준은 Props/인터페이스 문서에서 다루고, 상태 위치 판단은 상태 관리 문서에서 다루도록 경계를 명확히 했습니다.

작성한 문서

문서	핵심 내용
docs/component-design/single-responsibility.md	단일 책임 원칙을 기준으로 컴포넌트 변경 이유를 나누고, 상품 카드 예시를 통해 하위 컴포넌트로 책임을 분리하는 기준을 정리했습니다.
docs/component-design/compound-components.md	Tabs 예시를 중심으로 여러 하위 컴포넌트가 같은 상태를 공유하는 복합 UI 설계 기준을 정리했습니다.
docs/component-design/headless-ui.md	Menu 예시를 중심으로 동작/접근성/상태 노출과 마크업/스타일을 분리하는 Headless UI 설계 기준을 정리했습니다.
docs/component-design/index.md	컴포넌트 설계 토픽의 범위와 다른 토픽과의 경계를 명시하고, 하위 지침 목록을 추가했습니다.

변경 파일

• docs/component-design/single-responsibility.md (신규)
• docs/component-design/compound-components.md (신규)
• docs/component-design/headless-ui.md (신규)
• docs/component-design/index.md (지침 목록 및 토픽 범위 업데이트)
• docs/.vitepress/config.mts (컴포넌트 설계 사이드바 네비게이션 추가)

참고 자료

• React 공식 문서 - Thinking in React
• Radix Primitives
• Radix Primitives - Styling
• React Aria
• Patterns.dev - Compound Pattern
• Epic React - Compound Components
• Headless Component: a pattern for composing React UIs
• WAI-ARIA Authoring Practices Guide
• Single Responsibility Principle in React: The Art of Component Focus
• [번역] 리액트에서의 단일 책임 원칙: 컴포넌트 집중의 기술

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
sipe_frontend_principles	Ready	Preview, Comment	May 1, 2026 3:08pm