[복붙 템플릿] 개발자 질문 ‘반토막’ 내는 리액트 기획서 표 3종(컴포넌트·Variant·State)
[복붙 템플릿] 개발자 질문 ‘반토막’ 내는 리액트 기획서 표 3종(컴포넌트·Variant·State)
“기획서에 다 적어놨는데도 개발자가 계속 물어본다”는 상황, 한 번쯤 겪어보셨죠?
리액트(React) 환경에선 특히 컴포넌트, State(상태), Variant(변형) 규칙이 빠지면 질문이 폭발합니다.
버튼 하나, 리스트 하나를 두고 “공통인가요?”, “로딩 때는요?”, “에러면 어디까지 보여요?”가 줄줄이 이어지면서 회의 시간이 기획서를 잡아먹습니다.
문제는 능력이 아니라 문서의 관점이 ‘화면’에만 묶여 있기 때문입니다.
이번 글에서는 개발자가 기획서에서 가장 먼저 찾는 정보를 그대로 담은 복붙 템플릿 표 3종(컴포넌트 인벤토리·Variant 규칙·State 규칙)을 공개합니다.
이 표만 기획서 앞쪽에 붙여도, 개발자는 질문 대신 “오케이, 구조 잡고 들어갈게요”를 먼저 말하게 됩니다.
바로 적용할 수 있게 예시까지 채워드릴 테니, 다음 기획서부터 소통비용을 확 줄여봅시다. 🧩
핵심 요약 (3분 적용)
- 컴포넌트 인벤토리: 공통/전용 부품과 재사용 범위를 표로 고정
- Variant 규칙표: “언제 primary인지” 같은 사용 조건을 문장(조건문)으로 명시
- State 규칙표: 로딩/에러/빈 화면의 진입 조건과 종료 조건을 표준화
1) 리액트 팀에서 질문이 늘어나는 진짜 이유
리액트(React) 개발자는 기획서를 “예쁜 화면 모음”으로 보지 않습니다. 먼저 확인하는 건 재사용(컴포넌트)과 변화(State)입니다.
- 재사용 가능성: 어떤 UI를 공통 컴포넌트로 뽑을 수 있는가?
- 상태와 변화: 어떤 데이터(State)가 언제 바뀌고, 그때 화면이 어떻게 변하는가?
2) 복붙 템플릿 표 3종(예시 포함)
아래 표들이 “표처럼” 보이도록 border/cellpadding/cellspacing를 넣었고, 모바일에서는 가로가 길어지면 깨지지 않게 가로 스크롤(overflow) 컨테이너로 감쌌습니다.
템플릿 1) 공통 컴포넌트 인벤토리(Inventory)
| 컴포넌트 ID | 컴포넌트명(가칭) | 목적/역할 | 사용 화면(예) | 변형(Variants) | 상태(States) | 입력/출력(Props/Events) | 정책/제약 | 비고 |
|---|---|---|---|---|---|---|---|---|
| C-BTN-001 | Button | 주요 액션 실행 | 로그인/상세/결제 | primary, secondary, ghost, danger | default, disabled, loading | label, icon, size / onClick | 동일 화면 primary 1개 원칙 | 공통 |
| C-INP-001 | TextInput | 텍스트 입력 | 회원가입/검색 | default, withIcon, password | default, focus, error, disabled | value, placeholder, maxLength / onChange | 에러 메시지 필수 | 공통 |
| C-LST-001 | ItemList | 목록 표시 | 검색/피드 | cardList, rowList | loading, empty, error | items, hasMore / onLoadMore | 스켈레톤 제공 | 확장 |
| C-MDL-001 | Modal | 확인/입력/안내 | 전체 | alert, confirm, form | open, closing | title, content / onConfirm, onClose | confirm은 CTA 2개 | 공통 |
| C-TOA-001 | Toast | 피드백 메시지 | 전체 | success, error, info | show, hide | message, duration | 중복 노출 규칙 | 공통 |
템플릿 2) Variant 규칙표(사용 조건을 조건문으로)
Button Variant 규칙 예시
| Variant | 사용 조건(기획 규칙) | 예시 위치 | 금지/예외 규칙 |
|---|---|---|---|
| primary | 화면의 최종 또는 핵심 액션 1개 | 결제하기, 저장 | 동일 화면 2개 이상 금지(예외 시 사유 표기) |
| secondary | 보조 액션 또는 대체 경로 | 취소, 뒤로 | primary 없이 secondary만 쓰는 경우는 사유 표기 |
| ghost | 덜 중요한 보조 액션(텍스트형) | 더보기, 공유 | 고위험 액션(삭제/결제 등)에는 사용 금지 |
| danger | 파괴적 또는 되돌리기 어려운 액션 | 삭제, 탈퇴 | confirm 모달(C-MDL-001) 필수 |
Input Variant 규칙 예시
| Variant | 사용 조건 | 예시 | 비고 |
|---|---|---|---|
| default | 일반 입력 | 이름, 이메일 | maxLength 정책 명시 |
| password | 비밀번호 입력 | 비밀번호, 비밀번호 확인 | 표시/숨김 토글 포함 여부 정의 |
| withIcon | 검색 또는 의미 강조 | 검색창 | 아이콘 클릭 액션 유무 명시 |
템플릿 3) State 규칙표(로딩·에러·빈 화면의 표준화)
| 컴포넌트 ID | State | 진입 조건(언제 true?) | 종료 조건(언제 false?) | UI 변화 | 우선순위/예외 |
|---|---|---|---|---|---|
| C-LST-001 | loading | 목록 조회 요청 시작 | 성공/실패 응답 수신 | 리스트 영역 스켈레톤 노출 | error와 동시 노출 금지 |
| C-LST-001 | empty | items.length = 0 | items 수신(1건 이상) | 빈 상태 안내 + CTA | loading 중에는 empty 숨김 |
| C-LST-001 | error | 목록 조회 실패 | 재시도 성공 | 에러 안내 + 재시도 버튼 | 권한/네트워크별 문구 분기 가능 |
| C-BTN-001 | disabled | 필수 입력 미완료 또는 권한 제한 | 조건 충족 | 버튼 비활성 | loading이 우선(loading 시 disabled 처리) |
| C-BTN-001 | loading | 저장/결제 요청 시작 | 응답 수신 | 버튼 스피너 + 클릭 방지 | 실패 시 toast(C-TOA-001) 노출 |
State 문장을 한 줄로 쓰는 공식
사용자 액션 또는 시스템 이벤트 + 변경되는 State + UI 영향 범위 + 예외 조건
- “필터 변경 시 filterState 업데이트, 목록 재조회, 로딩 스켈레톤 노출.”
- “저장 성공 시 toastState=success, 실패 시 toastState=error + 재시도 제공.”
3) 기획서에 적용하는 방법(1페이지 구조)
표 3종을 기획서 앞에 고정한 뒤, 각 화면 설계서에는 컴포넌트 ID로만 참조하세요. 화면이 많아질수록 문서가 깔끔해지고, 변경에도 강해집니다.
화면 구성 요약(Composition) 템플릿
- 화면명: 상품 상세
- 사용 컴포넌트:
- C-HDR-001 Header(공통)
- C-IMG-001 ImageCarousel(전용)
- C-BTN-001 Button(primary: 구매하기, ghost: 공유)
- C-MDL-001 Modal(confirm: 구매 전 확인)
- 데이터/상태:
- isLoadingDetail: true면 스켈레톤 노출
- isOutOfStock: true면 구매하기 버튼 disabled + 안내 문구
- errorDetail: 발생 시 에러 UI + 재시도
4) 배포 전 최종 체크리스트(질문 방지용)
- 인벤토리에 공통/전용 구분이 들어갔는가?
- 핵심 요소에 Variant 사용 조건이 정의됐는가?
- API 연동 화면에 Loading/Empty/Error가 모두 정의됐는가?
- State는 “어떻게 보임”보다 “언제 변함”으로 적혔는가?
5) 자주 묻는 질문(FAQ)
Q 기획자가 컴포넌트 이름까지 정해줘야 하나요?
A 이름은 개발자가 정하는 경우가 많습니다. 대신 공통/전용 의도와 재사용 범위, Variant 기준을 명확히 적어두면 충분합니다.
Q Variant 규칙은 어느 정도까지 상세히 써야 하나요?
A 디자인 디테일보다는 사용 조건, 금지 규칙, 예외 처리 중심으로 적는 것이 효율적입니다.
Q State 규칙표에서 가장 중요한 항목은 무엇인가요?
A 진입 조건과 종료 조건입니다. 이 2개가 명확하면 로딩/에러/빈 화면 구현 질문이 크게 줄어듭니다.