디자인 시스템 구축에 참여해보고 느낀 것들

개발자 현직자 솔직 경험담

디자인 시스템 구축에 참여해보고 느낀 것들

Next.js + Tailwind 기반 사내 디자인 시스템을 처음부터 만들어보며 배운, 코드보다 어려웠던 것들.

입사 3년 차쯤, 팀에 디자인 시스템이 없다는 게 불편하다는 얘기가 여기저기서 나오기 시작했다. 버튼 컴포넌트가 페이지마다 미묘하게 색이 다르고, 같은 "Primary 버튼"인데 어떤 곳은 8px 라운드, 어떤 곳은 12px 라운드였다. 결국 내가 손을 들고 이 작업을 맡게 됐는데, 시작할 땐 "컴포넌트 몇 개 만들면 끝나겠지"라고 순진하게 생각했다. 결과적으로 3개월이 걸렸고, 코드보다 사람 설득이 더 어려운 프로젝트였다.

디자인 시스템 구축에 참여해보고 느낀 것들

3개월구축 소요 기간

42개최종 컴포넌트 수

7팀이해관계자 팀 수

1. 첫 번째 착각 — "컴포넌트 라이브러리 = 디자인 시스템"

처음엔 Storybook 켜놓고 Button, Input, Modal 같은 컴포넌트를 Tailwind로 뚝딱 만들면 끝날 줄 알았다. 실제로 1주 차에 버튼 컴포넌트를 다 만들어놓고 뿌듯해했는데, 디자이너분이 확인하시더니 이렇게 말씀하셨다.

디자이너 이 버튼, 코드는 완벽한데 저희 Figma 파일이랑 spacing이 안 맞아요. 그리고 이 색상은 어떤 기준으로 고르신 거예요?

나 아... 기존 페이지에서 제일 많이 쓰이는 색을 그냥 가져왔어요.

디자이너 그러면 이건 시스템이 아니라 그냥 지금 상태를 복사한 거예요. 색상 팔레트부터 다시 정의해야 할 것 같아요.

이 대화 이후로 처음부터 다시 시작했다. 디자인 토큰(색상, 여백, 타이포그래피 단위)을 먼저 정의하지 않고 컴포넌트부터 만든 게 근본적인 실수였다. 코드 짜는 순서로 치면 데이터베이스 스키마 없이 API부터 만든 셈이었다.

⚠ 뒤늦게 깨달은 것 디자인 시스템은 컴포넌트 목록이 아니라 "일관된 결정을 내리는 기준"이다. 색상 하나를 고를 때도 "왜 이 색인가"에 대한 답이 있어야 하고, 그 답이 토큰 단위로 문서화되어 있어야 나중에 확장할 수 있다.

2. 디자인 토큰부터 다시 잡은 과정

디자이너분과 함께 2주 정도 색상, 간격, 타이포그래피 스케일을 처음부터 다시 논의했다. 실제로 정리했던 토큰 체계 일부를 코드로 옮기면 이랬다.

// tokens.ts export const colors = { primary: { 50: "#f4f0fb", 500: "#a878e0", 700: "#5a3a82", }, gray: { 100: "#f2f2f5", 900: "#18131f" }, }; export const spacing = { xs: "4px", sm: "8px", md: "16px", lg: "24px", }; // tailwind.config.ts 에서 그대로 참조 extend: { colors, spacing }

이 토큰을 Tailwind 설정에 직접 연결하니, 이후에는 컴포넌트를 만들 때마다 "이 색 괜찮나요?"라고 매번 물어볼 필요가 없어졌다. 토큰 자체가 결정의 기준이 되어준 거다.

Primary 50

 

#f4f0fb

Primary 500

 

#a878e0

Primary 700

 

#5a3a82

Gray 900

 

#18131f

3. 진짜 어려웠던 건 코드가 아니라 "설득"이었다

토큰과 컴포넌트를 다 만들어도 끝이 아니었다. 각 팀에서 이미 쓰고 있던 기존 스타일을 새 시스템으로 마이그레이션해야 했는데, 여기서 예상 못 한 저항이 있었다.

6주 차

A팀에서 "우리 페이지는 이미 완성됐는데 굳이 바꿔야 하나요"라는 반응. 마이그레이션 필요성을 데이터 없이 설득하려다 실패.

7주 차

중복 스타일 코드량을 실제로 측정해서 공유. 버튼 관련 CSS 클래스가 프로젝트 전체에 340줄 이상 중복되어 있다는 걸 수치로 제시하니 설득력이 생겼다.

9주 차

전면 교체 대신 "새로 만드는 페이지부터 신규 컴포넌트 사용"이라는 점진적 적용 규칙으로 합의점을 찾았다.

12주 차

7개 팀 중 5개 팀이 자발적으로 마이그레이션 시작. 나머지 2개 팀은 다음 분기 리팩토링 일정에 포함.

⚠ 배운 점 "이게 더 좋은 방식이에요"라는 말은 설득력이 없다. 기존 방식의 비용(중복 코드량, 버그 발생 빈도, 디자인 QA 시간)을 구체적인 숫자로 보여줘야 다른 팀도 움직인다.

4. 컴포넌트 API를 설계하며 겪은 시행착오

기술적으로 가장 오래 고민했던 부분은 컴포넌트의 props 설계였다. 처음엔 유연성을 극대화하겠다고 모든 걸 커스터마이징 가능하게 만들었는데, 오히려 팀원들이 잘못 사용하는 경우가 늘었다.

1차 설계 (과도한 자유도)

<Button color="#ff0000" />

임의 색상 지정 가능 → 토큰 무시하고 사용하는 사례 발생

2차 설계 (제한된 variant)

<Button variant="danger" />

토큰에 정의된 variant만 선택 가능 → 일관성 유지

이 경험으로 컴포넌트 설계에서 자유도가 높다고 무조건 좋은 게 아니라는 걸 배웠다. 오히려 선택지를 의도적으로 제한하는 게 시스템을 지키는 방법이었다.

3개월 후 결과

42개 컴포넌트, 완전한 디자인 토큰 문서, Storybook 기반 가이드를 구축했다. 새 페이지 개발 시 UI 작업 시간이 체감상 절반 가까이 줄었고, 디자이너와의 QA 커뮤니케이션 비용도 눈에 띄게 줄었다.

💡 다시 시작한다면 바꿀 점 처음부터 디자이너, PM, 각 팀 리드를 포함한 작은 워킹그룹을 먼저 만들었을 것 같다. 혼자 만들고 나중에 설득하는 방식보다, 처음부터 함께 의사결정에 참여시키는 편이 훨씬 빠르고 저항도 적었을 것이다.

"디자인 시스템은 코드로 시작해서 사람으로 끝나는 프로젝트였다."

2026년 기준으로 Tailwind CSS와 shadcn/ui 조합으로 사내 디자인 시스템을 구축하는 팀이 많아지고 있는데, 토큰 관리 도구로 Style Dictionary 같은 오픈소스를 함께 활용하면 Figma 변수와 코드 토큰을 동기화하기가 훨씬 수월하다는 이야기를 최근 동료 개발자들에게 자주 듣는다. 다만 팀 규모와 조직 구조에 따라 적합한 방식이 다를 수 있으니, 도입 전에 작은 스코프로 먼저 실험해보는 걸 추천한다.

결론

디자인 시스템 구축은 기술적으로는 그렇게 어렵지 않았다. 진짜 어려웠던 건 팀마다 다른 이해관계를 조율하고, 기존 방식을 바꾸는 데 대한 저항을 설득하는 과정이었다. 코드만 잘 짜면 된다고 생각했던 나에게는 큰 시야 확장의 경험이었고, 이후로는 어떤 프로젝트를 시작하든 "이 결정을 누구와 함께 내려야 하는가"를 먼저 생각하게 됐다.

디자인 시스템 구축 경험 있으신가요?

비슷한 프로젝트를 진행하며 겪은 어려움이나 노하우가 있다면 댓글로 공유해주세요. 지금 막 시작하려는 다른 개발자분들께 큰 도움이 될 것 같습니다.