amaranth.log
💻 개발

디자인 시스템 설계 과정에서 고민했던 개발 측면에서의 논의점들(feat. Storybook 스터디)

📄 서론

나는 현재 근무 중인 회사에서 진행되고 있는 ‘스토리북을 활용한 디자인 시스템 구축하기’ 스터디에 참여 중이다. 매주 스터디 시간마다 디자인, 개발, 시스템 설계 면에서 많은 논의가 이루어지고 있는데, 논의 끝에 서서히 개발을 해 나가고 있는 상황이다.
이번에 함께 개발을 담당하고 있는 친구와 각자 구축해온 코드를 비교해보면서, 개발 측면에서의 몇 가지 논의점이 생겼다. 그래서 다음 스터디 숙제로 각 논의점에 대한 서로의 의견을 비교해오기로 해서, 그 과정을 글로 정리해봤다.

🤔 생각 정리

폴더 구조의 차이

친구의 레포를 처음 열었을 때 가장 먼저 보였던 차이점은 프로젝트의 폴더 구조였다.
  1. 스토리 파일과 소스코드 파일을 분리
      • src
        • stories
          • atom
            • Typhography.stories.ts
            • Icon.stories.ts
          • molecular
          • organism
        • components
          • Typhography
            • Typography.tsx
          • Input
            • TextField.tsx
  1. 스토리 파일과 소스코드 파일을 합쳐 도메인 별로 분리
      • src
        • component
          • atom
            • Input
              • Input.stories.ts
              • Input.tsx
            • Text
              • Text.stories.ts
              • Text.tsx
          • molecular
          • organism
ㅤ
분리형 구조
통합형 구조(도메인 기반 분류)
가독성
컴포넌트와 스토리 파일이 명확히 구분됨
관련 파일이 가까이 있어 맥락을 파악하기 쉬움
확장성
문서 작성 외에도 다양한 테스트, 실험 파일들을 따로 두기 용이하다.
한 도메인마다 폴더의 크기가 커지기 쉬워 가독성이 저하될 수 있음
스토리북 유지보수
스토리 위치가 흩어져있어 찾기 어려울 수 있음
컴포넌트를 보며 스토리도 바로바로 확인 가능(찾기가 쉬움)
협업&리뷰
컴포넌트만 리뷰하는 경우 볼륨이 적음
변경사항 리뷰 시 스토리까지 한 번에 확인하기 용이함
테스트와의 통합성
테스트와 스토리가 함께 묶이지 않아 테스트 코드를 별도로 관리할 수 있음
*.test.tsx, *.stories.tsx를 한 데 묶어서 관리할 수 있음
러닝 커브
초보자는 파일 위치를 따로 파악해야 함
파일이 맥락에 따라 모여있기 때문에 이해하기 쉬움
🤖
GPT의 결론
디자인 시스템, 컴포넌트 중심의 개발이라면 통합형 구조를 추천.
  • 스토리북과 같은 UI 문서화 툴을 활용할 때, 핵심은 컴포넌트를 보여주는 문서이므로 컴포넌트 옆에 스토리가 있는 것이 직관적이다.
  • 테스트, 문서화 파일, 스타일 등 하나의 컴포넌트 context 안에 모아두는 방식이 현대 프론트엔드 개발 트렌드임(Colocation 원칙)
*단, 규모가 커지고 다양한 도메인과 기능이 함께 있는 경우에는 도메인 별 상위 폴더를 두고 그 안에 통합형 구조를 결합한 방식을 사용하는 것이 좋다.
분리형 구조는 컴포넌트 하나를 수정할 때마다 스토리/테스트 코드를 고치기 위해 일일이 다른 폴더를 찾아 열어야 하고, 관련 변경사항을 한 데 보기가 어렵다.
대신, 관심사를 명확하게 분리할 수 있어 테스트 코드만 보는 상황/스토리북 코드만 보는 상황에서는 좀 더 편리하게 작업을 수행할 수 있다.
그리고 특정 목적의 파일들을 일괄 처리하고 검색하기가 용이한데, 이는 통합형 구조에서도 확장자를 통한 검색 혹은 IDE 인터페이스 기능을 활용해 충분히 커버 가능한 장점이라 논외로 치겠다.
반면 통합형 구조는 컴포넌트 별 폴더 크기가 커져서 가독성이 떨어질 수 있다는 단점이 있다고 하는데, 솔직히 폴더가 커져봤자 얼마나 커질까 싶기도 하다.(물론 아직 큰 규모의 프로젝트를 경험해보지 못해서 드는 안일한 생각일 수도 있다) 그리고 한 컴포넌트를 수정하게 되었을 때, 그 변경사항을 관련된 다른 파일에 적용하기 용이하다는 장점이 있다.
 
그럼 이제 고민해볼 지점은, 현재 우리가 참여하고 있는 디자인 시스템 구축 과정에서, 컴포넌트 수정으로 인해 해당 컴포넌트의 스토리북 파일까지 수정해야 하는 상황이 잦을까, 스토리북 파일 공통의 수정사항을 일괄적으로 적용하는 상황이 더 잦을까? 이렇게 생각하니 당연히 전자가 더 빈번할 것이라는 생각이 들었다.
이러한 이유와 더불어 스토리북과 디자인시스템 설계 방식 자체가 컴포넌트 중심 개발이기 때문에, 컴포넌트 단위 개발에 좀 더 친화적인 통합형 구조를 채택하는 것이 좋을 것 같다.

CSS 라이브러리의 차이

나는 손에 익은 툴이라는 이유로 tailwindcss로 구축을 했고, 친구는 styled-components를 사용했다. 둘 다 사용해본 경험이 있어서 학습곡선에 대한 부담이 없는 상태라, 여러 지표로 둘을 비교 해보았다.
ㅤ
TailwindCSS+classnames
styled-components
런타임 성능
빠르다.(정적 클래스, css가 미리 생성됨)
느릴 수 있음(런타임에 style 태그 생성)
자동완성/DX
IDE 지원, 클래스 암기 필요(러닝커브)
JS 문법을 그대로 작성함, 문맥 유지쉬움.
재사용/모듈화
@apply, 컴포넌트화, tailwind plugin을 활용해서 가능
고도화된 재사용 가능, prop에 따른 동적 스타일링 가능
디자이너와의 협업 용이성
클래스 기반이라 다소 난해할 수 있음
css 문법을 그대로 사용하기 때문에 디자이너도 이해하기 용이
동적 스타일링
조건부 className 조합이 필요함
props 기반 스타일링이 자연스러움
🤖
GPT의 결론
  • 빠른 UI 구현과 경량 스타일 시스템 구축이 목적이라면 Tailwind css가 적합
  • 복잡한 동적 스타일, 애니메이션, 디자인 시스템 중심의 구조라면 styled-components가 적합
구축하려는 디자인 시스템이 사내 디자인 시스템인 만큼 규모가 작지 않고 요구사항도 다양하기 때문에, 재사용성이 좋고 강력한 JS 동적 스타일링을 제공하는 styled-components 쪽이 더 적합해보인다.
결정적으로, 우리는 사내 디자인 시스템을 구축하면서 디자이너와 개발자 간 협업 용이성을 중요 포인트로 가져가기로 했기 때문에 디자이너 입장에서 난해할 수 있는 tailwindcss보다는 styled-compoenents가 합리적이다.
 
다른 css 라이브러리는 어떨지 좀 더 알고 싶어서 GPT한테 정보를 더 얻어봤다.
notion image
이걸 보고 Emotion과 Vanilla Extract에도 관심이 생겨서 나중에 좀 더 알아볼 생각이다. 일단 지금은 학습 곡선을 고려해 styled-components를 채택하는 것이 좋을 것 같다.

Props의 타입 정의(타입 정의 기준)

나는 관습적으로 컴포넌트 Props 타입을 정의할 때 interface를 사용해왔는데, 친구는 type을 위주로 활용하는 습관을 갖고 있었다. 이런 코드 스타일에 대해서는 깊이 생각해본 적이 없는 것 같아서 이참에 두 방식을 비교해봤다.
ㅤ
interface
type
정의 방식
객체 구조만 정의 가능
객체, 유니언, 튜플 등 거의 모든 타입을 표현할 수 있음. *유니언: type Example = ‘test’ | ‘example’ *튜플: type NameAndAge = [string, number]
선언 병합
지원됨(같은 이름의 interface를 자동 병합)
지원 안됨
확장 방법
extends로 확장 가능
&으로 확장 가능
리터럴 표현
리터럴 타입 정의 불가
문자열, 유니언 등 리터럴 표현 가능
컴파일 결과
컴파일러 최적화가 더 잘 되는 경향이 있다
복잡한 경우 디버깅이 어려울 수 있다
interface는 명확하게 객체 모델을 표현할 수 있어서 객체 중심 구조에 직관적이다. 대신 유니언 타입이나 튜플, 기타 복잡한 타입은 표현이 불가하다.
type은 모든 타입을 표현할 수 있고, 여러 타입을 간결하게 조합할 수 있다. 대신 선언 병합이 불가하기 때문에 타입 이름이 중복되면 에러가 발생한다.(오히려 직관적이어서 좋을지도…?)
props 구조를 확장할 가능성이 있는 경우, 선언병합을 지원하고 extends로 확장이 용이한 interface가 추천된다.
사실 interface나 type이나 그렇게까지 큰 차이는 없다고 생각이 든다. 하지만 디자인 시스템은 컴포넌트를 기반으로 구성되기 때문에 확장성과 재사용성이 중요하고, 그러기에 보다 직관적인 interface가 좀 더 낫지 않나하는 생각이 든다.
그외에도, 내겐 interface를 사용하는 것이 조금 더 익숙하기도 하고, 좀 더 표준적이라고 생각이 들어서(공식문서 등에서도 컴포넌트 props 타입으로 interface가 사용되는 것을 봤었다.) 나는 interface 쪽을 선택하고 싶다.

atom 컴포넌트 구현 시 네이티브 props를 활용할지, 커스텀 props를 만들지

디자인 시스템의 Atom 컴포넌트를 만들 때, HTML 자체의 네이티브 props를 그대로 활용하는 편이 좋을지, 디자인 시스템 상에서 제어하기로 한 속성만을 사용할지(=커스텀 props만 컴포넌트 상인터페이스에 노출할지)에 대해 고민이 됐다.
각각의 방식은 디자인 시스템의 유연성(자유도)과 통제성(예측가능성) 중 무엇에 가치를 둘지…
만약 네이티브 props를 사용할 경우, 다음과 같은 컴포넌트 props 타입을 구성할 수 있을 것이다.
type ButtonProps = React.ButtonHTMLAttributes<HTMLButtonElement> & { variant?: "primary" | "secondary"; };
예시
이 방식의 장점은, 개발자 입장에서 직관적이고 친숙하며 props forwarding이 용이하다.
단점은 디자인시스템에서 허용하지 않는 속성이 노출될 수 있어, 디자인 시스템에서 의도적으로 제한하려는 속성이 있을 경우 예상치 못한 문제가 발생할 수 있다는 것이다.(일관성&예측가능성 저하)
그리고 IDE 자동완성에 불필요한 속성이 많이 노출되기 때문에, 문서화 시 의도한 사용자 정의 props가 묻힐 수 있다.
*하지만 스토리북에서는 원하는 props만 따로 노출되도록 통제할 수 있기 때문에 해당 문제는 해결 가능하다.
❓
props forwarding
컴포넌트에 전달된 props를 내부 엘리먼트에 그대로 넘기는 것
const Button = (props: React.ButtonHTMLAttributes<HTMLButtonElement>) => { return <button {...props} />; };
커스텀 props만 정의하는 방식은 다음과 같은 구성을 가리킨다.
interface ButtonProps { onClick?: () => void; disabled?: boolean; variant?: "primary" | "secondary"; }
이 경우, 어떤 속성을 사용할 수 있는지를 명확하게 설계할 수 있고, 스토리북에서 props 목록을 간결하고 정확하게 표기할 수 있다.
단점으로는 기존 HTML 태그가 제공하는 props를 빠짐없이 반영하기 어렵고, 특히 aria-*, form, tabIndex과 같은 접근성 관련 속성도 일일이 추가해주어야 해서 개발 상의 번거로움이 있을 수 있다. 그리고 디자인 시스템을 구축하는 개발자의 재량에 따라 누락된 속성들은 상황에 따라 컴포넌트의 사용성을 저하시킬 수 있다.(예를 들면, 위와 같이 ButtonProps로 onClick, disabled, variant만을 props로 설정하고 디자인시스템을 구축했는데, 컴포넌트 사용자가 일반 button 태그에서 제공하던 readonly 속성을 이용하고 싶은 경우 사용자는 해당 컴포넌트를 다시 커스텀해야 한다.
🤖
GPT의 결론
  • 네이티브 엘리먼트를 래핑한 Atom 컴포넌트의 경우(Button, Input 등) ⇒ HTMLAttributes를 상속
  • 디자인 시스템 규칙에 따라 props를 엄격히 제한할 필요가 있는 경우 ⇒ 커스텀 props 사용
  • 실제 대부분의 디자인시스템은 둘을 결합한 하이브리드 방식을 사용한다.
내가 생각하기로 두 방식 모두 장단점이 있고 극단적인 것 같아, 두 방식을 절충해 Button이나 Input같이 네이티브 엘레멘트를 래핑한 컴포넌트는 네이티브 props를 상속하게 하고, 그 외 컴포넌트는 커스텀 props를 활용하는 것이 좋을 것 같다.
디자인 시스템 상 불필요한 네이티브 속성은 TypeScript의 Omit으로 제거하면 될 듯 하다.
type ButtonProps = { variant?: "primary" | "secondary"; isLoading?: boolean; } & Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "type">;

컴포넌트를 넘겨주기 vs 간접적으로 props를 넘겨줄지

// 방법1. 직접 컴포넌트를 넘겨주기 <InputLabel NestedLabelText={<LabelText text='테스트' error/>} /> // 방법2. 간접적으로 props를 넘겨주기 <InputLabel nestedProps={ labelText: { text:'테스트', error:true, } } />
다음으로 고민해볼만한 포인트는 컴포넌트의 사용자가 컴포넌트 내 하위 엘레멘트를 제어하고 싶을 때, as나 component와 같은 props 속성으로 컴포넌트 자체를 넘겨 해당 하위 엘레멘트를 교체하게 하는 편이 좋을지, 하위 엘레멘트가 가질 props 속성을 넘겨 props forwarding하는 것이 좋을지였다. 현재까지 구현된 코드를 보니 명확한 기준 없이 뒤죽박죽인 것 같아, 일관된 규칙을 정할 필요성을 느꼈다.
두 방식의 장단점을 비교해보니 다음과 같이 정리할 수 있었다.
ㅤ
직접 컴포넌트 넘기기
간접적으로 props 넘기기
유연성
매우 높음
제한적임
제어력
낮음(의도치 않은 컴포넌트를 넘겨 예상치 못한 동작을 초래할 수 있음)
높음(일관된 동작을 보장할 수 있다.)
코드 가독성
낮아질 수 있음(복잡한 로직이 생길 수 있음)
높음(명확하게 동작을 예상할 수 있음)
디자인 시스템 적합도
낮음(의도치 않은 UI 컴포넌트가 사용될 수 있음)
높음(정해진 방식으로만 사용되므로
이 문제 역시 유연성과 예측가능성 사이의 트레이드 오프이다. 둘 중 무엇이 중요할지는 컴포넌트를 사용하게 될 맥락에 따라 달라질 것으로 생각이 되어, 명확한 결정 기준을 가지고 가는게 좋을 것 같다.
🤖
GPT의 결론
  • 유틸리티형 컴포넌트나 외부 라이브러리와의 연동이 필요한 경우(유연성 필요) ⇒ 컴포넌트를 직접 넘기는 방식
  • 디자인 시스템 내 핵심 컴포넌트(통제 가능성이 중요함) ⇒ 간접적으로 props를 넘기는 방식
커스텀 렌더링이 필요한 유틸리티 컴포넌트의 경우(MUI의 Box, Stack과 같은), 직접 컴포넌트를 넘겨 유연성을 보장하는 것이 좋을 듯 하다. 그리고 일관된 스타일, 접근성, UX가 중요한 대부분의 컴포넌트는 간접적으로 props를 전달하는 방식으로 활용성에 제한을 두는 것이 안전할 것 같다.
 
+)Jul 20, 2025 추가
실제로, 대표적인 UI 라이브러리인 MUI에서는 어떻게 사용하고 있는지를 확인해보니 두 방식을 함께 제공해주고 있었다.
// 직접 넘기기 - slot <DatePicker slots={{ openPickerIcon: FlightTakeoffIcon }} /> // props로 넘기기 - slotProps <DatePicker slotProps={{ openPickerIcon: { color: 'primary', }, }} /> // 두 방식 혼용 <DatePicker slots={{ openPickerIcon: FlightTakeoffIcon }} slotProps={{ openPickerIcon: { color: 'primary', }, }} />

레이아웃/컨테이너 컴포넌트와 UI 컴포넌트의 구분

지난 디자인 시스템 설계 논의 중 다음과 같은 안건이 있었다.
데이터를 표시하는 UI 컴포넌트를 구현할 때, 표시할 데이터를 children 속성으로 받게 하는 것이 좋을까, label, content같은 속성으로 받게 하는 것이 좋을까?
이에 대한 명확한 기준을 잡고 가는 것이 좋을 것 같아 이번에 개발 관련 논의사항을 정리하는 김에 관련 문서를 찾아보며 다시 내 의견을 정리해보기로 했다.
위 안건의 구체적인 예시를 들면 다음과 같이 경우를 나눌 수 있다.
//1. props로 받기 <Chip label='테스트'/> //2. children으로 받기 <Chip>테스트</Chip>
*두 방식으로 렌더링한 컴포넌트는 UI상으로는 동일하다.
일단, children 속성을 언제 쓰는 것이 적절할지에 대해 알아보니 주로 레이아웃을 구성하는 레이아웃 컴포넌트에서 children을 열어두고 그 외 UI를 표현하는 컴포넌트(이하 UI 컴포넌트)는 자체 속성으로 데이터를 전달하는 것이 일반적이라고 한다.
레이아웃 컴포넌트와 UI 컴포넌트는 다음과 같이 구분된다.
항목
UI 컴포넌트
레이아웃/컨테이너 컴포넌트
목적
데이터를 표현하는 것
데이터를 배치하는 것
예시
Button, Card, Avatar
Stack, Grid, Flex, Container, Sidebar, PageLayout
책임
스타일링과 인터랙션
하위 컴포넌트의 위치, 간격, 정렬
주로 쓰는 속성
color, size, variant, onClick
gap, direction, alignItems, justifyContent, wrap
이건 우리 스터디 내 논의에서도 나왔던 문젠데, 그럼 Card나 Modal 컴포넌트는 어느 쪽에 해당이 되는 걸까?
GPT가 내려준 답변에서도 Card는 기준이 조금 모호할 수 있다고 언급하고 있었는데, GPT는 Card를 ‘레이아웃의 역할을 하나의 UI 단위로 래핑한 UI 컴포넌트’로 보는 편이 맞다고 결론 내렸다. Modal도 같은 기준으로 판단한 것 같다.
🤖
GPT의 결론
  • 컴포넌트가 데이터의 UI 상 구조나 정렬까지 책임질 경우 ⇒ 레이아웃 컴포넌트
  • 일관된 UI 덩어리를 재사용하기 위한 목적인 경우 ⇒ UI 컴포넌트
  • 모호한 컴포넌트은 별도의 composite 카테고리로 관리하는 것도 하나의 방법.
확실히, 배치/정렬과 같은 레이아웃 커스텀에 초점을 둔 컴포넌트라면 children으로 표시할 데이터를 받는 편이 좋을 것 같다.
*그리고 또 생각해보니, 코드 가독성만을 생각했을 때, 전달하려는 속성 데이터 크기가 크다면 개별 props에 들어가는 것보다 children으로 넘겨주는 편이 더 보기 좋을 것 같다. 그리고 레이아웃 컴포넌트라면 아무래도 내부 데이터가 메인이 되다 보니 데이터 크기가 대체로 클 것이다.
UI 재사용성에 초점을 둔 컴포넌트라면 레이아웃 컴포넌트보다는 대체로 표시할 데이터의 크기도 작을 것이니, 자체 props로 넘겨주는 편이 가독성 측면에서도 좋을 것 같다.
 

Jul 20, 2025 추가

지난 스터디에서 진행했던 논의 중 기억에 남았던 몇몇 쟁점에 대한 고민을 추가했다.

문자열 컨텐츠를 넘겨주는 방식에 대해

MUI의 <Chip />처럼 텍스트가 주 컨텐츠가 되는 컴포넌트의 경우 해당 텍스트를 props로 넘겨받을 때 string으로 컨텐츠 타입을 제약하곤 한다. 하지만 이런 방식은 다른 스타일의 텍스트를 혼합하거나 svg형식의 아이콘을 함께 사용하고 싶은 상황에서 그렇게 하지 못해 불편함이 있었다.
그래서 논의 끝에 우리의 디자인 시스템에서는 이러한 컴포넌트의 props 타입을 모두 string | ReactNode로 설정하자는 결론을 내렸다.
<Chip> <Typography color=’black’>Title - </Typography> <Typography color=’gray’>SubTitle</Typography> </Chip>
label: string | ReactNode ... <Chip label=’title’ />

error, disabled와 같은 속성은 어떻게 넘겨주는 것이 좋을까?

컴포넌트를 설계하다보면 TextField와 같은 분자 컴포넌트를 구성할 때, 여러 개의 하위 컴포넌트(InputLabel, Input, HelperText 등)를 활용하게 되는데, error, disabled와 같은 속성이 주어질 경우 하위 컴포넌트들의 스타일(혹은 기능)도 함께 변경되어야 한다.
그렇다면 해당 속성들을 하위 컴포넌트로 전달해야 하는데, 이 방법을 두고 고민을 하게 됐다.
가장 먼저 떠올랐던 방법은, input 관련 컴포넌트에서 사용하는 공통 상태들을 정리해서 모든 하위 컴포넌트에 {…props} 형태로 전달하는 방식이었다.
직관적이고 단순한 방식이긴 하지만 이것이 이상적인 방법인지는 확신이 서지 않았다.
문제는 하위 컴포넌트마다 고려해야 하는 상태 속성이 조금씩 다르다는 것이다. TextField의 Input 요소는 error, readonly, disabled 세 상태에 대해 스타일, 기능적 제약이 모두 다르기 때문에 세 상태를 모두 넘겨주어야 하는 반면, LabelText 요소는 readonly, disabled 상태에 대응하는 별도의 스타일이 없다. (물론 이는 서비스의 디자인 요구사항에 따라 조금씩 다를 수는 있다.) 그래서 모든 컴포넌트에 불필요한 속성을 갖게 된다는 점이 마음에 걸렸다.
그렇다고 하위 컴포넌트가 필요로 하는 상태만 선택적으로 넘겨받도록 하자니 일관성이 떨어지고 명세 관리도 복잡해질 수 있었다.
그러다가 Context API를 활용해 전역적으로 error, disabled와 같은 상태에 접근할 수 있게끔 하여 하위 컴포넌트가 재량껏 상태를 활용할 수 있게 하는 것은 어떻냐는 의견이 나왔다. 이렇게 하면 불필요한 props 전달을 피하면서도 하위 컴포넌트가 유연하게 자신에게 필요한 상태 속성만 활용할 수 있게 할 수 있다.
Context API를 활용하기 위해서는, 해당 상태 속성을 저장할 역할을 해줄 유틸리티 컴포넌트가 필요하다.(이하 Provider 컴포넌트라 칭함)
<FormProvider state={{ error, readonly, disabled }}> <TextField /> </FormProvider>
컴포넌트 사용자는 별도의 추가적인 구현 없이 TextField 컴포넌트만 사용할 수 있도록, TextField 컴포넌트 내에서 Provider 컴포넌트로 요소를 감싸게끔 구현하는 편이 좋아보인다.
// 내부 구현 예시 const InputContext = createContext({ error: false, disabled: false, readOnly: false }); const TextField = ({ error, disabled, readOnly, ...rest }) => { return ( <InputContext.Provider value={{ error, disabled, readOnly }}> <InputWrapper> <InputLabel>Label</InputLabel> <Input {...rest} /> <HelperText>Helper</HelperText> </InputWrapper> </InputContext.Provider> ); };
 
이 문제에 대해 레퍼런스를 얻기 위해 실제 UI 라이브러리들은 어떤 방식을 취하고 있는지 알아본 결과, MUI, Chakra, Radix UI 모두 Context API를 활용하고 있었다.