안녕하세요. 토스증권 디자인 플랫폼 팀의 프론트엔드 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 - 우당탕탕 디자인 시스템

Scripts