안녕하세요. 토스증권 디자인 플랫폼 팀의 프론트엔드 US 엔지니어 박건영입니다.

오늘은 저는 이제 우당탕탕 디자인 시스템이라는 제목으로 저희 팀이 디자인 시스템을 운영하면서 맞닥뜨렸던 기술적인 문제들과 그것들을 팀의 현재 상황에 맞춰서 어떻게 풀어 나가는지에 대해서 이야기를 한번 해 보려고 해요.

먼저 저희 팀 소개를 한번 간단히 드리도록 하겠습니다.

토스증권의 디자인 플랫폼 팀은 제품의 메이커들이 높은 퀄리티의 UI를 빠르게 구현할 수 있는 환경을 만든다라는 미션을 가지고 있어요.

이 미션을 달성하기 위해서 저희는 디자인 시스템, 디자인 린터와 같은 여러 도구들을 만들고 활용하고 있는데요.

오늘은 이 중에서 디자인 시스템에 대한 이야기를 좀 한번 집중적으로 다뤄보도록 하겠습니다.

저희 디자인 시스템의 이름은 TDS, WTS인데요.

이 디자인 시스템은 토스증권 PC 서비스를 위한 것이고 증권 도메인 환경에 맞는 컴포넌트들을 제공하고 있습니다.

기술 스택은 리액트와 타입스크립트를 사용하고 있고요.

이 라이브러리는 사내 NPM 레지스트리에 올려서 배포를 하고 있습니다.

네. TDS 네. TDS WTS는 현재 제품에서 활발히 사용되면서도 지속적으로 발전을 하고 있는데요.

이 디자인 시스템을 만들고 유지보수하면서 겪었던 문제들 중에 공유하고 싶었던 주제 세 가지를 한번 골라봤어요.

지금부터 이 주제들에 대해서 하나씩 살펴보도록 하겠습니다.

먼저 저희 팀에서 지금 TDS WTS 라이브러리를 어떻게 만들고 적용하고 있는지에 대해 한번 설명을 드려 볼게요.

현재 디자인 시스템 코드는 제품 리포지토리와는 별도의 리포지토리에서 관리를 하고 있습니다.

디자인 시스템 컴포넌트들에 대해서 여러 기능에 대한 작업들을 커밋하고 나면 이걸 빌드해서 라이브러리 번들로 만들고 이거를 이거를 사내 npm 레지스트리에 퍼블리시를 하고 있어요.

그리고 나서 토스증권 PC 제품에서 이 변경 사항을 사용하고 싶을 때는 이 라이브러리 패키지를 인스톨해서 사용하는 구조를 가지고 있습니다.

이때 라이브러리 패키지의 버전을 관리하기 위해서 원래는 여기 계신 많은 분들에게 익숙하실 시맨틱 버전과 체인지셋의 조합을 사용했어요.

즉 어떤 기능 변경에 대한 작업을 하고 나서 PR로 올릴 때 체인지셋 파일에 어떤 변경점이 있었는지를 적고 메이저, 마이너, 패치 버전 중에 어떤 것을 올릴지 결정을 해야 했었어요.

이 방식을 사용하면 라이브러리를 사용하는 곳에서 메이저, 마이너, 패치를 보고 업데이트의 영향 범위를 예측하기 쉬워지는 장점이 있습니다.

이 방식은 자바스크립트 생태계에서도 기본적으로 널리 사용되는 방식이에요.

그런데 여기서 저희 팀의 상황을 한번 살펴볼게요.

TDS WTS를 사용하는 곳은 현재 증권 한국 서비스와 일본 서비스 단 두 곳뿐이에요.

그리고 또 라이브러리가 아직 초기 단계라서 매우 활발하게 기능 변경이 일어나고 있습니다.

네, 그래서 디자인 시스템이 변경되었을 때 이걸 업데이트하는 주체는 현재 저희 팀으로 하고 있습니다.

즉 사용처에서 직접 새로운 버전으로 업데이트를 하는 것이 아니라 저희 팀이 직접 제품 코드에 가서 업데이트를 반영을 해주고 있어요.

이런 환경에서 SemVer와 ChangeSet을 계속 쓰다 보니까 한 가지 의문이 좀 들기 시작했는데요.

'이게 과연 우리 환경에서 제일 효율적인 방식인가?'라는 의문이 들었습니다.

효율성에 의문을 품게 된 원인은 두 가지가 있었는데요.

먼저 첫 번째로 기존 방식에서는 어떤 코드의 변경이 있었을 때 버전 업데이트를 위해서 ChangeSet을 매번 작성을 해주었어야 했는데 어차피 이 내용은 PR 본문에서 이미 잘 작성하고 있었어요.

그래서 ChangeSet에 따로 또 이 내용을 한 번 더 작성하는 것은 좀 중복되는 작업이라고 느껴졌어요.

그리고 두 번째로 SemVer의 장점은 사용자에서 라이브러리를 업데이트할 때 변경의 범위를 쉽게 예상할 수 있게 만든다라는 것에 있다고 생각하는데요.

문제는 저희 상황에선 라이브러리를 수정한 쪽에서 바로 실제 제품에 적용까지 하고 있으니까 이런 SemVer의 장점이 다소 퇴색되었어요.

따라서 지금 팀의 상황을 고려해 봤을 땐 SemVer와 체인지셋을 사용하는 것이 오히려 좀 비효율적인 방법이라고 판단했어요.

그래서 나중에 상황이 좀 바뀐다면 그때 다시 SemVer 방식을 쓰더라도 일단 지금은 현재 상황에 가장 효율적인 방법을 찾고 싶었어요.

그래서 고민을 좀 해 본 결과 날짜 기반 버전을 사용하는 방식을 선택을 해 봤는데요.

이 버전 방법에서는 버전에 가장 첫 번째로는 메이저 버전, 두 번째로는 배포를 한 날짜 마지막으로 오늘 몇 번째를 배포했는지에 대한 순번을 지정을 합니다.

예를 들어 오늘 두 번째로 배포를 했다면 버전은 20260224.2가 됩니다.

이렇게 했을 때 장점은 우선 새로운 버전 번호를 자동으로 만들어 낼 수 있어요.

따라서 PR을 만들 때 메머 체인지를 작성하고 메이저 마이너 패치 버전 중 어떤 것을 올릴지 고민하지 않아도 되어서 번거로움이 조금 줄 수 있었습니다.

또 버전만 보고도 '아 이 버전은 2026년 2월 24일에 나온 버전이구나'를 한눈에 알 수 있어서 업데이트가 얼마나 밀렸는지도 직관적으로 확인하기 쉬운 소소한 장점도 있었어요.

날짜 기반 버전을 사용하고 체인지셋을 작성하지 않는다면 각 버전의 변경점은 작업의 풀 리퀘스트들의 목록이 됩니다.

이렇게 하면 따로 체인지 로그를 작성하지 않아도 되는 점은 좀 편리하지만 실제로 변경된 것이 어떤 것이 있는지를 보려면 PR을 다 하나하나 뜯어서 봐야 되기 때문에 이거를 한눈에 변경점을 보기가 어렵다는 새로운 문제가 생겼어요.

그래서 이 문제도 해결하기 위해서 패키지 버전별로 변경점을 한눈에 모아볼 수 있는 릴리즈 노트를 만들도록 했는데요.

이때 릴리즈 노트는 최소한의 공수로 만들 수 있도록 AI 에이전트가 PR의 내용과 diff를 읽어서 이를 기반으로 릴리즈 노트를 자동으로 지정된 형식으로 생성해 주도록 구성했어요.

이렇게 하니 버전 관리에 대한 부담은 줄면서도 부작용은 최소화하는 워크플로우를 만들어 볼 수 있었습니다.

네. 네, 두 번째 주제로 넘어가 볼게요. 이거는 컴포넌트 커스텀 제어에 관한 주제입니다.

디자인 시스템을 사용하다 보면 이런 상황이 간간이 생깁니다.

조금 다르게 쓰고 싶은데 컴포넌트에서 이거는 지원하지 않네.

저희 팀은 이런 상황을 커스텀을 하는 상황이라고 정의하는데요.

이럴 때 사용자에게는 크게 네 가지 선택지가 있습니다.

아예 안 쓰거나 처음부터 새로 만들거나 기존 컴포넌트를 어떻게든 마개조해서 쓰거나 아니면 디자인 시스템 팀의 기능 추가를 요청하거나.

그런데 각각의 선택지에는 약간씩 다 문제가 있습니다.

아예 안 쓰면 디자인을 하는 데 한계가 생겨 버리고요.

처음부터 다 만들려면 엄청난 공수가 들어갑니다. 또 마개조를 해서 사용하게 되면 디자인 시스템이 업데이트할 때 문제가 생길 가능성이 높고요.

디자인 플랫폼 팀에 추가를 요청하면 반영되기까지는 시간이 좀 걸립니다.

그런데 당장 제품을 빠르게 완성해서 나가야 하는 상황에서는 어떤 선택지를 골라도 문제가 있게 되는 아주 찜찜한 상황이 만들어집니다.

이런 찜찜한 상황을 만들지 않으려면 디자인 시스템 단에서는 어떻게 할 수 있을까요?

사실 여기서 1번과 2번 선택지는 디자인 시스템을 안 쓰는 것과 크게 다를 바가 없기 때문에 그나마 3번과 4번 선택지를 개선하는 방식이 좀 현실적인데요.

4번 선택지를 택하자니 아무리 저희 팀이 빠르게 움직이더라도 제품 팀이 원하는 것을 바로바로 만들어 주기에는 커뮤니케이션하는 시간 자체가 드니까 그렇게 해주기에는 물리적인 한계가 있을 수밖에 없었습니다.

따라서 저희가 택한 접근법은 이 3번의 문제, 마개조하는 것을 해결하는 것이었는데요.

앞서 언급드린 이 마개조를 어느 정도 안전하게 만들 안전하게 할 수 있도록 만들어서 스펙에서 조금 벗어난 확장은 공식적으로 허용한다라는 정책을 가져가 보기로 했어요.

자, 구체적인 예시로 한번 버튼 컴포넌트를 봐 볼게요. 지금 이 버튼 컴포넌트에 해당하는 버튼 프롭스에는 'filled'랑 'onClick' 같은 프롭들이 있어요.

되게 간단하죠? 이렇게 'improp'에 'blue'를 넣으면 파란색 버튼이 화면이 나옵니다.

여기까지는 아무 문제가 없어요. 그런데 만약에 모종의 이유로 이렇게 온 포인터 다운 캡처 프롭을 추가해서 사용하고 싶다라고 한다면 어떻게 해야 될까요?

당연히 현재 버튼의 프롭은 이게 없으니까 사용할 수 없습니다.

이거는 컴포넌트를 만들 때 상정하지 않은 부분이니까요.

이런 경우를 미리 좀 지원을 해 줄 수 있게 하기 위해서 자주 사용하는 방법들 중 하나는 HTML 엘리먼트의 타입을 확장하는 것인데요.

이렇게 리액 이렇게 이제 리액트점 컴포넌트 프롭스의 버튼 타입을 확장하도록 만들면 표준 HTML의 버튼의 모든 속성을 모두 다 그대로 활용할 수 있게 됩니다.

따라서 여기에는 온 포인터 다운 캡처가 들어가 있기 때문에 이 경우는 문제없이 사용할 수 있게 돼요.

하지만 이 방식에도 약간의 문제가 있습니다.

HTML 엘리먼트의 프롭들을 통째로 다 가져오면 컴포넌트를 설계할 때 의도하지 않았던 프롭들도 같이 포함되게 됩니다.

예를 들어 지금 이 버튼의 경우에는 '컬러'라는 프롭을 사용할 수 있습니다.

문제는 처음 버튼을 설계할 때는 이 컬러 프롭을 의도하지 않았습니다.

버튼의 색은 테마를 사용하기로 했으니까 말이죠. 여기서 컬러 프롭이 포함되어 버린 이유는 HTML의 기본 버튼의 속성 중에서 논 스탠더드 속성이긴 한데 컬러가 이미 있기 때문에 이것이 흘러 들어온 겁니다.

이렇게 되면 원래 컴포넌트에서 의도한 프롭이 어떤 것인지를 알 수 없어지고 이것을 사용처에서 잘못 사용할 수 있는 문제가 발생합니다.

그래서 이 방식도 저는 좀 한계가 있다고 보았습니다.

또 중첩된 상황에서도 문제가 하나 있는데요.

이렇게 버튼 컴포넌트가 앞에 예시와는 조금 다르게 실제로 컴포넌트 하나가 두 겹의 DOM을 가지고 있는 구조라고 해 볼게요.

그래서 안쪽에 이제 실제 버튼 태그의 프롭들을 현재 스프레드를 하고 그것을 바깥에 스판 태그로 감싸 놓았다고 가정을 해 볼게요.

이 상태에서 프롭의 클래스 네임이 들어온다면 이거는 어디로 가야 될까요?

컴포넌트에 만약에 마진을 주고 싶어서 클래스 네임을 넣었다면 지금 코드는 제대로 동작하지 않을 겁니다.

이 경우에는 바깥쪽에 있는 스판에 이 클래스 네임이 들어가는 것이 맞고요.

그런데 또 포커스링 스타일을 만지고 싶었던 경우라면 이 안쪽 버튼에 들어가는 것이 맞습니다.

이러면 하나의 클래스 네임 프롭이 어디로 가야 할지를 미리 딱 정할 수가 없게 돼요.

따라서 HTML의 어트리뷰트를 확장하는 방식으로는 이런 커스텀 경우를 커버하는 데는 좀 한계가 있습니다.

중첩 DOM이 문제라면 컴파운드 패턴을 사용할 수도 있지 않을까 하는 생각 하는 이제 생각이 될 수도 있는데요.

실제로 컴포넌트 하나 겹의 DOM을 가지도록 만들고 여러 겹의 DOM은 무조건 컴파운드 컴파운드로 제공하게 된다면 조금 전의 문제는 발생하지 않습니다.

다만 모든 컴포넌트를 이렇게 제공하게 되면 또 다른 문제가 있는데요.

컴파운드 패턴을 사용하면 각 서브 컴포넌트가 어떤 식으로 조합돼야 하는지를 정확하게 알고 사용해야 되기 때문에 사용하기가 다소 어려워집니다.

그리고 작성된 코드의 양도 눈에 띄게 늘어나기도 하고요.

그래서 모든 그래서 그 도우미 중첩되는 상황에서 서브 컴포넌트를 다 만들게 된다면 이걸 다루는 피로도가 다소 올라가게 됩니다.

그래서 모든 것의 컴파운드 컴파운드 패턴을 적용하는 것이 맞는 해결책이 될 수는 없다고 생각을 했습니다.

그래서 저희는 이 네 가지 조건들을 동시에 만족할 수 있는 간단한 방법이 필요하다고 생각을 했는데요.

필요하다면 DOM 속성에 직접 접근이 가능하면서도 의도가 확실한 프롭들 위 위주로 노출하면서 중첩 DOM 상황도 다룰 수 있고 간단하게 사용할 수 있어야 돼요.

이것들을 달성하기 위해서 저희가 고안했던 시점은 커스텀 프롭스라는 패턴을 만들어 만드는 것인데요.

이거는 이제 MUI 디자인 시스템 라이브러리에서 조금 영감을 받았어요.

이 방식은 기본적으로 컴포넌트의 프롭에 띵 같은 이제 명확히 미리 의도된 것들만 선언을 합니다.

그리고 사용자에서는 의도하지 않은 추가적인 돔 속성이 필요할 경우에 이 커스텀 프롭을 통해서 접근할 수 있도록 했습니다.

테크톡톡 2026 | Frontend Developer - 우당탕탕 디자인 시스템

토스 챌린저스

토스증권 디자인 플랫폼 팀은 제품 메이커들이 높은 품질의 UI를 빠르게 구현할 수 있도록 디자인 시스템(TDS WTS)을 구축하고 운영하며, 기술적 문제를 팀 상황에 맞춰 해결하고 있습니다.

패키지 버전 관리 시, SemVer와 ChangeSet 방식이 현재 팀의 효율성과 맞지 않아 날짜 기반 버전 관리와 AI 에이전트를 활용한 릴리즈 노트 자동 생성을 통해 워크플로우를 개선했습니다.

컴포넌트 커스텀 제어를 위해 '커스텀 프롭스' 패턴을 도입하여 컴포넌트의 유연한 확장을 허용하고, 시각적 분기 문제를 해결하기 위해 아이콘의 '이상적인 크기 배율' 개념을 도입하여 리소스 센터와 디자인 시스템 간의 관심사를 분리했습니다.

토스증권 디자인 플랫폼 팀의 박건영 프론트엔드 US 엔지니어는 **'우당탕탕 디자인 시스템'이라는 제목으로 팀이 디자인 시스템을 운영하면서 겪었던 기술적 문제들과 해결 과정**을 공유했습니다. 팀은 제품 메이커들이 높은 퀄리티의 UI를 빠르게 구현할 수 있는 환경을 만드는 미션을 가지고 있으며, 이를 위해 디자인 시스템(TDS WTS)과 같은 도구들을 활용하고 있습니다.

TDS WTS는 토스증권 PC 서비스를 위한 디자인 시스템으로, **증권 도메인 환경에 맞는 컴포넌트를 리액트와 타입스크립트 기술 스택으로 제공**하며, 사내 NPM 레지스트리를 통해 배포됩니다. 이 디자인 시스템은 현재 제품에서 활발히 사용되며 지속적으로 발전하고 있습니다. 발표에서는 디자인 시스템을 만들고 유지보수하면서 겪었던 세 가지 주요 문제와 해결 방안이 논의되었습니다.

패키지 버전 관리의 비효율성 개선

기존에는 디자인 시스템 라이브러리의 버전 관리를 위해 **시맨틱 버전(SemVer)과 ChangeSet 조합을 사용**했습니다. 이 방식은 라이브러리 사용처에서 업데이트의 영향 범위를 예측하기 쉽다는 장점이 있지만, 토스증권의 특수한 환경에서는 비효율적이라는 문제가 제기되었습니다. TDS WTS는 현재 한국과 일본 서비스 단 두 곳에서만 사용되며, 라이브러리가 초기 단계라 기능 변경이 매우 활발하게 일어나고 있습니다. 또한, 라이브러리 업데이트 주체가 디자인 시스템 팀 자체였기 때문에 SemVer의 장점이 퇴색되었습니다.

ChangeSet 작성은 PR 본문 내용과 중복되는 작업이었고, 팀에서 직접 제품 코드에 업데이트를 반영하는 상황에서 SemVer의 장점은 크게 의미가 없었습니다. 이에 팀은 **날짜 기반 버전 방식을 선택**했습니다. 이 방식은 '메이저 버전.배포 날짜.오늘 몇 번째 배포인지' 순번으로 버전을 지정하며, 버전 번호 자동 생성으로 ChangeSet 작성의 번거로움을 줄였습니다. 또한, 버전만으로 업데이트 시점을 직관적으로 파악할 수 있는 소소한 장점도 있습니다.

날짜 기반 버전 사용 시 각 버전의 변경점을 한눈에 파악하기 어렵다는 문제에 대응하기 위해, **AI 에이전트가 PR 내용과 diff를 기반으로 릴리즈 노트를 자동으로 생성**하도록 구성했습니다. 이로써 버전 관리 부담은 줄이면서도 부작용을 최소화하는 워크플로우를 구축할 수 있었습니다.

컴포넌트 커스텀 제어의 유연성 확보

디자인 시스템을 사용하다 보면 컴포넌트가 지원하지 않는 기능을 추가하거나 다르게 사용하고 싶은 **'커스텀' 상황이 발생**합니다. 이때 사용자는 아예 사용하지 않거나, 새로 만들거나, 기존 컴포넌트를 '마개조'하거나, 디자인 시스템 팀에 기능 추가를 요청하는 네 가지 선택지를 가질 수 있습니다. 하지만 이 모든 선택지에는 각각 한계와 문제가 있습니다.

특히 '마개조'는 디자인 시스템 업데이트 시 문제를 일으킬 가능성이 높고, 기능 추가 요청은 반영되기까지 시간이 소요되어 제품 개발 속도를 저해할 수 있습니다. 이에 팀은 **'스펙에서 조금 벗어난 확장은 공식적으로 허용한다'는 정책을 도입하여 마개조를 안전하게 할 수 있는 방법**을 모색했습니다.

HTML 엘리먼트 타입 확장 방식은 표준 HTML 속성을 모두 활용할 수 있게 하지만, 컴포넌트 설계 시 의도하지 않은 프롭(예: `color` 프롭)이 포함되어 **사용처에서 오용될 수 있는 문제**가 있었습니다. 또한 중첩된 DOM 구조에서는 하나의 `className` 프롭이 어느 DOM에 적용되어야 할지 명확하지 않아 커스텀에 한계가 있었습니다. 컴파운드 패턴은 이 문제를 해결할 수 있지만, 사용 난이도가 높아지고 코드 양이 늘어나는 단점이 있어 모든 컴포넌트에 적용하기는 어렵다고 판단했습니다.

이를 해결하기 위해 팀은 MUI 디자인 시스템에서 영감을 받아 **'커스텀 프롭스' 패턴을 고안**했습니다. 이 방식은 컴포넌트의 프롭에 미리 의도된 것들만 선언하고, 사용자에게 추가적인 DOM 속성이 필요할 경우 `customProps`를 통해 접근하도록 합니다. 예를 들어, `root`라는 이름을 가장 상위 DOM을 지칭하도록 정의하여 `customProps.root`에 들어간 스타일은 버튼의 가장 상위 DOM에 적용되도록 했습니다. 이 방법은 컴포넌트를 직관적으로 사용하면서도 커스텀이 필요한 경우 유연하게 대응할 수 있게 하며, 어떤 부분이 커스텀되었는지 한눈에 파악하여 향후 공식 기능으로 편입시킬 전략을 세우는 데 도움을 줍니다. 다만, 리액트 서버 컴포넌트 대응에는 어려움이 있을 수 있으나, 현재 토스증권 환경에서는 이를 감안하기로 했습니다.

커스텀 프롭스 구현을 돕기 위해 **`createCustomSlots` 함수와 `useSlot` 훅으로 구성된 `CustomSlots` 유틸리티를 개발**했습니다. 이를 통해 하위 DOM의 이름과 태그를 선언적으로 정의하고, 컴포넌트 내부에서 타입 세이프하게 하위 DOM을 조립하고 다룰 수 있게 하여 커스텀 프롭스를 사용하는 컴포넌트 내부의 복잡도를 낮췄습니다.

시각적 분기 로직의 관심사 분리

디자인 시스템의 `Asset` 컴포넌트는 리소스 센터에 업로드된 아이콘이나 이미지 같은 리소스를 적절한 프레임 안에 렌더링합니다. 토스 커뮤니티에서는 리소스 센터 사용이 사실상 표준으로 자리 잡고 있습니다. 하지만 **리소스 센터에 업로드된 아이콘들은 여백의 시각적 특성이 미묘하게 달라** (빈 공간이 많거나, 꽉 채우거나, 중간이거나) 동일한 크기의 컴포넌트임에도 아이콘 크기가 다르게 보이는 문제가 발생했습니다.

디자인 요구사항은 어떤 아이콘을 넣든 간에 **같은 크기의 컴포넌트는 서로 같은 크기의 아이콘을 보여줘야 한다는 것**이었습니다. 초기에는 각 아이콘 타입의 여백에 맞춰 컴포넌트 내부에서 크기에 대한 분기 로직을 처리했으나, 컴포넌트 자체의 사이즈(`small`, `medium`, `large` 등)가 다양해지면서 크기 조합이 폭발적으로 늘어나 유지보수가 매우 어려워지는 문제가 발생했습니다.

이 문제의 본질을 파악한 결과, **아이콘 여백이 다른 것은 리소스 센터의 관심사이지 디자인 시스템 컴포넌트의 관심사가 아니라는 결론**에 도달했습니다. 이에 팀은 아이콘의 이상적인 크기를 하나 정의하고 이를 표준으로 삼았습니다. 각 아이콘 타입별로 이 이상적인 크기에 도달하기 위한 배율을 계산하고, 이 배율 로직을 담은 리소스 센터 라이브러리를 별도로 만들었습니다. 이 패키지를 통해 관심사를 분리함으로써, 사용자 입장에서는 리소스 센터 패키지의 컴포넌트만 사용하면 이상적인 크기로 표준화된 아이콘을 볼 수 있게 했습니다.

결과적으로, `Asset` 컴포넌트는 더 이상 아이콘 타입이 무엇인지 신경 쓸 필요 없이 **자신이 정한 `small`, `medium`, `large` 크기에 따라 표준화된 아이콘을 렌더링하는 데만 집중**할 수 있게 되었습니다. 이러한 관심사 분리를 통해 아이콘 여백 타입이 아무리 다양해져도 컴포넌트 코드에서는 분기 로직 없이 깔끔하게 처리할 수 있게 되었습니다.

결론: 팀 상황에 맞는 최적의 해결책 모색

토스증권 디자인 플랫폼 팀은 **패키지 버전 관리, 컴포넌트 커스텀 제어, 시각적 분기라는 세 가지 기술적 문제**를 팀의 특수한 상황에 맞춰 해결했습니다. 날짜 기반 버전 전환, 커스텀 프롭 패턴 도입, 시각적 분기 로직의 관심사 분리 등 각 해결책은 모든 상황에서 통용되는 만능 해법이 아니라, **팀의 현재 상황에 가장 효율적인 방법을 찾아 적용한 결과**입니다. 이러한 경험 공유는 디자인 시스템 운영에 있어 유연한 사고와 상황에 맞는 문제 해결의 중요성을 보여줍니다.

토스증권 디자인 플랫폼 팀이 디자인 시스템을 운영하며 겪었던 주요 기술적 문제 3가지와 각 문제에 대한 해결책은 무엇인가요?

패키지 버전 관리 방식에 있어, 토스증권 디자인 플랫폼 팀이 SemVer와 ChangeSet 방식 대신 날짜 기반 버전 방식을 선택한 주된 이유는 무엇이며, 이 방식의 장점은 무엇인가요?

컴포넌트 커스텀 제어를 위해 토스증권 디자인 플랫폼 팀이 고안한 '커스텀 프롭스' 패턴은 무엇이며, 이 패턴이 기존의 HTML 엘리먼트 확장 방식이나 컴파운드 패턴 방식의 한계를 어떻게 해결하나요?

아이콘의 시각적 분기 문제를 해결하기 위해 디자인 플랫폼 팀이 '아이콘의 이상적인 크기 배율' 개념을 도입하고 관심사를 분리한 과정과 그 결과는 무엇인가요?

토스증권 디자인 시스템 운영 중 겪은 기술적 문제와 해결 방안 소개

토스증권 디자인 플랫폼 팀의 미션: 높은 퀄리티의 UI를 빠르게 구현하는 환경 조성

미션 달성을 위해 디자인 시스템, 디자인 린터 등 여러 도구 활용

발표는 디자인 시스템(TDS, WTS)에 집중

TDS, WTS는 토스증권 PC 서비스용으로, 증권 도메인 환경에 맞는 컴포넌트 제공

기술 스택: React, TypeScript, 사내 NPM 레지스트리를 통한 배포

디자인 시스템 구축 및 유지보수 중 겪은 세 가지 주요 문제 공유

디자인 시스템 코드는 제품 리포지토리와 별도로 관리하며, 빌드 후 사내 npm 레지스트리에 퍼블리시

제품에서는 라이브러리 패키지를 인스톨하여 사용

기존에는 시맨틱 버전(SemVer)과 ChangeSet을 조합하여 버전 관리

SemVer의 장점: 라이브러리 사용자에게 업데이트 영향 범위 예측 용이

현재 TDS WTS 사용처는 증권 한국/일본 서비스 두 곳뿐이며, 라이브러리가 초기 단계라 기능 변경이 매우 활발함

디자인 시스템 변경 시 업데이트 주체는 디자인 플랫폼 팀

현 환경에서 SemVer와 ChangeSet 방식의 비효율성 문제 제기

비효율성 원인 1: ChangeSet 작성은 PR 본문과 내용 중복

비효율성 원인 2: SemVer의 장점(업데이트 범위 예측)이 팀의 상황(팀이 직접 제품에 적용)에서는 퇴색

해결책: 날짜 기반 버전 방식 도입 (메이저 버전.배포 날짜.당일 배포 순번)

날짜 기반 버전의 장점 1: 버전 번호 자동 생성으로 번거로움 감소

날짜 기반 버전의 장점 2: 버전만으로 업데이트 시점 파악 용이

날짜 기반 버전의 단점: 체인지셋 미작성 시 변경점 파악 어려움

단점 해결책: AI 에이전트를 활용하여 PR 내용 기반 릴리즈 노트 자동 생성

결과: 버전 관리 부담 감소 및 부작용 최소화

디자인 시스템 컴포넌트가 지원하지 않는 커스텀 요구 발생

사용자의 선택지: 사용 포기, 새로 개발, 마개조, 기능 추가 요청 (각각 문제점 존재)

해결 접근법: 마개조를 안전하게 허용하여 스펙에서 벗어난 확장 공식 허용

예시: 버튼 컴포넌트에 'onPointerDownCapture'와 같은 프롭 추가 시도

일반적인 해결 시도: HTML 엘리먼트 타입 확장으로 표준 HTML 속성 활용

HTML 타입 확장 방식의 문제 1: 설계 의도와 다른 프롭(예: 'color') 포함되어 오용 가능성

HTML 타입 확장 방식의 문제 2: 중첩된 DOM 구조에서 'className'과 같은 프롭의 적용 위치 불명확성

대안 시도: 컴파운드 패턴 사용

컴파운드 패턴의 문제: 사용 난이도 증가 및 코드 양 증대로 인한 피로도 증가

필요 조건: DOM 속성에 직접 접근, 의도된 프롭만 노출, 중첩 DOM 처리, 간단한 사용법

해결책: 커스텀 프롭스(CustomProps) 패턴 도입 (MUI 영감)

커스텀 프롭스 특징: 미리 의도된 프롭만 선언, 추가 DOM 속성은 커스텀 프롭스를 통해 접근

내부 DOM에 이름 선언 및 커스텀 프롭스의 키로 지정 (예: 'root'는 최상위 DOM 지칭)

장점 1: 직관적인 사용 + 유연한 커스텀 대응

장점 2: 커스텀 빈도 추적으로 공식 기능 편입 전략 수립 가능

단점: React 서버 컴포넌트 대응 어려움 (현 증권 환경에서는 감안)

구현 도구: `createCustomSlots` 함수와 `useSlot` 훅으로 타입 세이프하게 하위 DOM 조립

문제 3: 시각적 분기 (아이콘 여백 문제)

에셋 컴포넌트: 리소스 센터의 아이콘을 적절한 프레임 안에 렌더링

리소스 센터: 디자이너가 아이콘, 이미지 등 리소스를 업로드하고 프론트엔드에서 활용하는 내부 서비스

문제: 리소스 센터 아이콘들의 시각적 특성(여백)이 미묘하게 다름

디자인 요구사항: 아이콘 종류와 무관하게 같은 크기의 컴포넌트는 같은 크기 아이콘을 보여줘야 함

초기 해결 시도: 아이콘 타입에 맞춰 컴포넌트 내부에서 크기 분기 처리

초기 시도 문제점: 컴포넌트 사이즈(Small, Medium, Large)까지 고려하면 크기 조합 폭증으로 유지보수 어려움

근본적인 질문: 아이콘 여백 문제는 리소스 센터의 관심사가 아닌가?

관점 전환: 아이콘 여백 차이 보정은 리소스 센터 맥락에서 처리하고, 디자인 시스템은 신경 쓰지 않아야 함

해결책: 아이콘의 이상적인 크기 정의 및 표준화

각 아이콘 타입별로 이상적인 크기에 도달하기 위한 배율 계산

배율 로직을 담은 별도의 리소스 센터 라이브러리 생성 및 관심사 분리

사용자 입장에서는 리소스 센터 패키지 사용 시 이상적인 크기의 아이콘이 자동으로 보임

에셋 컴포넌트의 변화: 외부에서 표준화된 아이콘이 들어오므로, 아이콘 타입에 신경 쓰지 않고 자신의 크기만 집중

결과: 관심사 분리를 통해 분기 로직 없이 깔끔한 아이콘 처리 가능

패키지 버전: 팀 상황에 맞춰 SemVer에서 날짜 기반 버전으로 전환

컴포넌트 커스텀 제어: 커스텀 프롭 패턴 도입으로 안전한 확장 허용

시각적 분기: 아이콘 이상적인 크기 배율 개념 도입으로 관심사 분리 및 분기 로직 제거

제시된 방법들은 모든 상황에 통용되는 것은 아니며, 팀의 상황에 가장 적합한 방법을 찾아 적용한 경험 공유