디자인 시스템 Compound Component 패턴 전환

v1 디자인 시스템은 빠르게 만들기 위해 단일 Props 방식으로 갔어요. <Accordion title="..." subtitle="..." rightIcon={...} expandable showDivider ... /> 같은 형태죠. 처음엔 빨랐지만 새 화면 요구사항이 나올 때마다 prop이 하나씩 늘었어요. 1년쯤 지나니 prop이 10개를 넘는 컴포넌트가 생겼고, 동료들이 새 prop이 있는지 매번 storybook을 열어봐야 했습니다.

진짜 문제는 두 가지였어요. 첫째, 마크업 자유도. "헤더 우측에 토글 버튼을 넣고 싶다", "헤더와 본문 사이에 사용자 정보를 넣고 싶다" 같은 변형이 들어오면 prop으로 표현이 어려워서 억지로 prop을 추가하거나 새 컴포넌트를 fork 하는 식으로 처리됐어요. 둘째, 학습 곡선. prop의 이름과 효과를 다 외워야 동료들이 쓸 수 있는 상태였습니다.

Compound Component 패턴으로 바꾸니 두 문제가 동시에 풀렸어요. <Accordion> 안에 <Accordion.Summary>, <Accordion.Details>, <Accordion.Item> 같은 하위 컴포넌트를 두고, 사용자가 JSX 트리 자체로 구조를 표현합니다. 헤더 우측에 뭔가 넣고 싶으면 그냥 <Accordion.Summary> 안에 넣으면 끝이고, prop으로 모든 변형을 미리 예측할 필요가 없어졌어요. 동료들이 처음 보는 컴포넌트라도 HTML과 비슷한 사고로 쓸 수 있어서 학습 비용이 거의 0이 됐습니다. 결과적으로 v1 대비 prop 개수가 절반 이하로 줄었어요.

세 패턴 다 검토했어요. 각자 트레이드오프가 다릅니다.

Render Props는 children에 함수를 전달해서 부모가 자식의 마크업을 구성하는 방식이에요. <Accordion>{(state) => (...)}</Accordion> 같은 형태인데, 중첩이 깊어지면 콜백 지옥이 됩니다. 게다가 JSX 트리가 평탄하지 않아서 가독성이 떨어져요. 정말 필요한 케이스는 hooks가 등장한 이후엔 거의 사라졌습니다.

**HOC (Higher-Order Component)**는 withTheme(Component) 처럼 컴포넌트를 한 번 감싸서 prop을 주입하는 방식이에요. 문제는 두 개입니다. 첫째, prop 충돌 — 사용자가 같은 이름의 prop을 넘기면 누가 이기는지 명확하지 않아요. 둘째, displayName이 깨져서 React DevTools에서 디버깅이 불편해요. hooks 도입 이후 HOC를 새로 만드는 일은 거의 없는 흐름입니다.

Compound Component는 Context로 부모-자식 사이에 상태를 공유하면서 사용자에겐 평탄한 JSX 트리를 노출해요. <Accordion><Accordion.Summary>...</Accordion.Summary></Accordion> 처럼 HTML과 흡사한 사고가 가능합니다. prop 충돌도 없고, JSX가 그대로 트리 구조라 가독성이 가장 좋아요. 더불어 TypeScript에서 Accordion.Summary 같은 attached 타입 선언이 자연스럽게 됩니다.

선택 이유는 결국 DX였어요. 동료가 처음 봐도 직관적으로 이해할 수 있는지가 디자인 시스템의 핵심 KPI인데, Compound가 그걸 가장 잘 만족시켰습니다.

이건 Context API의 가장 흔한 함정이에요. provider에 value={{ count, setCount }} 처럼 객체 리터럴을 그냥 넘기면 부모가 리렌더될 때마다 새 객체가 만들어져서, Context를 구독하는 모든 자식이 리렌더됩니다.

세 단계로 막았어요. 첫째, value를 useMemo로 감싸서 참조 안정성 확보. const value = useMemo(() => ({ ... }), [count]) 같은 식으로 의존성이 진짜 바뀔 때만 새 객체를 만듭니다. 둘째, 하위 컴포넌트를 React.memo로 감싸기. 부모가 리렌더돼도 props가 같으면 자식은 리렌더 안 하도록 하는 보호막이에요. 셋째, 그래도 부족하면 Context를 분리. 자주 바뀌는 state와 거의 안 바뀌는 dispatch/setter를 다른 Context로 나누면, dispatch만 쓰는 컴포넌트는 state 변경에 영향 안 받습니다.

이렇게 했더니 리렌더 프로파일이 훨씬 깔끔해졌어요. 측정은 React Profiler로 했고, "한 Item 토글 시 다른 Item이 리렌더되지 않는다"를 회귀 테스트 케이스로 두고 검증했습니다.

HTML input을 떠올리시면 됩니다. <input value={x} onChange={...} />은 controlled, <input defaultValue="..." />은 uncontrolled예요. 같은 컴포넌트가 두 모드를 다 지원하면, 외부 폼 라이브러리(react-hook-form 등)와 통합하고 싶을 땐 controlled로 쓰고, 그냥 단순 토글이면 uncontrolled로 부모 코드 없이 쓸 수 있어요.

내부 구현은 단순합니다.

function Accordion({ value, defaultValue, onChange, children }) {
  const [internal, setInternal] = useState(defaultValue);
  const isControlled = value !== undefined;
  const current = isControlled ? value : internal;
  const setCurrent = (next) => {
    if (!isControlled) setInternal(next);
    onChange?.(next);
  };
  // current와 setCurrent를 Context로 내려보냄
}

value가 주어졌으면 외부가 source of truth, 안 주어졌으면 내부 state가 source of truth. setter는 항상 onChange를 호출하면서, uncontrolled일 때만 내부 state도 갱신합니다.

이걸 모든 핵심 컴포넌트에 동일한 패턴으로 적용해서, 동료들이 "토스 디자인 시스템 컴포넌트는 input처럼 쓰면 된다"는 멘탈 모델 하나로 전체를 다룰 수 있게 했어요. 학습 비용을 최소화한 설계 결정 중 가장 만족스러운 부분이었습니다.

v1을 통째로 바꿔치는 빅뱅 전환은 리스크가 너무 컸어요. 대신 v2를 별도 패키지로 분리해서 v1과 함께 살게 했어요. 같은 모노레포 안에 core-v1과 core-v2가 공존하고, 팀이 원하는 시점에 import 경로만 v2로 바꾸면 마이그레이션이 끝나는 구조입니다.

핵심은 v2 API가 v1과 1:1 대응되도록 미리 설계한 것이었어요. 컴포넌트 이름, 기본 동작, 핵심 prop은 그대로 유지하고, 새로 추가된 자유도는 children 슬롯으로만 노출. 그래서 단순 케이스는 import 경로 변경만으로 끝나고, 변형이 필요한 경우만 children 마크업을 손대면 됐습니다.

추가로 두 가지를 했어요. 첫째, 마이그레이션 가이드 문서. 컴포넌트별로 "v1에선 이렇게, v2에선 이렇게"의 before/after 코드 스니펫을 정리. 둘째, storybook에 v1과 v2를 같은 카테고리에 두고 옆에 띄워서 비교. 동료들이 직접 두 버전을 보면서 변경점을 이해할 수 있게 했어요.

이 전략 덕에 마이그레이션을 강제하지 않고도 6개월 안에 자연스럽게 v2로 수렴했습니다. (※ 기간은 본인 기억에 맞게)