1. 개요
프로젝트를 진행하며 SCSS 기반 스타일 시스템을 운영하는 과정에서 컬러 및 스타일 변수 관리 방식이 점차 복잡해지는 문제를 경험하였습니다. 초기에는 단순 변수 선언만으로도 충분했지만, 서비스 규모가 커지고 다양한 UI 컴포넌트가 추가되면서 변수의 역할이 불명확해지고 중복 정의가 증가하였습니다.
특히 여러 서비스에서 공통 UI를 함께 사용하는 구조에서는 동일한 색상을 서로 다른 이름으로 사용하는 경우가 발생하였고, 이는 유지보수성과 협업 효율 저하로 이어졌다. 디자인 시스템 관점에서도 “값 중심”의 구조는 한계가 있었으며, 의미 기반의 토큰 체계로 재구성할 필요성이 커졌습니다.
이에 따라 기존 SCSS 변수 구조를 디자인 토큰 기반 구조로 리팩토링하였으며, 유지보수성과 확장성을 개선하기 위한 방향으로 시스템을 재설계하였습니다.
또한 기존에는 스타일 정의가 컴포넌트 내부에 혼재되어 있어 공통 스타일 관리가 어려웠다. 서비스별 요구사항이 늘어날수록 동일한 컴포넌트에서도 스타일 분기가 많아졌으며, 코드 가독성이 낮아지는 문제가 있었습니다. 이러한 문제를 해결하기 위해 공통 디자인 기준을 토큰 단위로 관리하는 방향을 고려하게 되었습니다.
2. 기존 구조의 문제점
기존 변수 구조는 --gray200, --primary600 형태처럼 실제 색상 값에 가까운 네이밍으로 관리되고 있었다. 이 방식은 초기 개발 속도는 빠르지만 프로젝트 규모가 커질수록 여러 문제가 발생하였습니다.
첫 번째는 의미 전달의 한계였다. 변수명만으로는 해당 색상이 텍스트인지, 배경인지, 보더인지 구분하기 어려웠다. 결과적으로 개발자마다 해석이 달라질 수 있었고, 협업 과정에서도 커뮤니케이션 비용이 증가하였습니다.
두 번째는 중복 정의 문제였습니다. 새로운 UI를 개발할 때 기존 색상을 재사용하기보다 유사한 색상을 새롭게 정의하는 경우가 많아졌습니다. 이 과정에서 디자인 시스템의 일관성이 점차 약화되었습니다.
세 번째는 유지보수 비용 증가였습니다. 특정 색상 변경 시 영향을 받는 범위를 파악하기 어려워 예상치 못한 UI 변경이 발생하기도 하였습니다. 특히 공통 컴포넌트에서 사용하는 변수의 영향도를 추적하는 과정이 비효율적이었습니다.
또한 컴포넌트 단위의 스타일 커스터마이징이 많아질수록 스타일 충돌 가능성도 증가하였습니다. 프로젝트 규모가 커질수록 변수 체계만으로는 안정적인 관리가 어려웠으며, 보다 체계적인 구조 설계가 필요했습니다.
3. 개선 방향
위 문제를 해결하기 위해 단순 값 기반 구조에서 벗어나 의미 중심의 디자인 토큰 시스템을 도입하였습니다. 토큰은 Primitive, Alias, Semantic의 3단계 계층 구조로 설계하였습니다.
3.1 Primitive Token
Primitive Token은 실제 색상 값을 정의하는 역할을 수행합니다. 예를 들어 gray 계열, primary 계열 등의 실제 HEX 값을 관리합니다.
3.2 Alias Token
Alias Token은 색상의 역할을 정의합니다. 예를 들어 텍스트, 보더, 배경 등 의미 단위로 그룹화하여 관리하였습니다.
3.3 Semantic Token
Semantic Token은 실제 UI 요소에 적용되는 단계입니다. 버튼 배경색, 카드 보더, 상태 메시지 등 실제 컴포넌트 레벨에서 사용되는 토큰을 정의하였습니다.
이러한 구조를 통해 단순 값이 아닌 의미 기반의 스타일 관리가 가능해졌으며, 공통 UI와 서비스별 UI를 보다 체계적으로 관리할 수 있게 되었습니다.
또한 토큰 구조를 계층화함으로써 다크 모드나 서비스별 테마 확장에도 유연하게 대응할 수 있는 기반을 마련하였습니다. 기존에는 색상 변경 시 코드 전반을 수정해야 했지만, 현재 구조에서는 특정 레이어만 수정해도 전체 UI에 일관되게 반영할 수 있게 되었습니다.
4. 적용 과정
토큰 구조를 도입하는 과정에서는 단순 변수명 변경이 아니라 실제 사용 목적을 기준으로 전체 스타일 구조를 재정비하였습니다.
먼저 기존 SCSS 변수들을 전수 조사하여 어떤 화면과 컴포넌트에서 사용되고 있는지 분석하였습니다. 이를 기반으로 의미 단위로 재분류를 진행하였습니다.
또한 SCSS의 @use와 @forward를 활용하여 모듈 시스템을 구성하였습니다. 각 토큰 레이어를 파일 단위로 분리하고 _index.scss를 통해 import 구조를 통합하였습니다. 이를 통해 의존성을 명확하게 하고 필요한 토큰만 명시적으로 사용할 수 있도록 개선하였습니다.
전체 코드를 한 번에 교체하는 방식은 리스크가 크다고 판단하여 점진적 적용 전략을 사용하였습니다. 신규 페이지 및 수정이 필요한 영역부터 우선 적용하였으며, 기존 코드와 병행 운영하는 방식으로 안정적으로 전환을 진행하였습니다.
또한 디자인팀과 협업하며 토큰 네이밍 규칙을 정리하고 공통 기준을 문서화하였습니다. 이 과정은 단순 코드 개선뿐 아니라 협업 프로세스를 정리하는 데에도 큰 도움이 되었습니다.
실제 적용 과정에서는 디자인 QA를 반복적으로 진행하며 토큰 적용 범위를 검증하였습니다. 특히 공통 컴포넌트에 적용되는 스타일은 여러 서비스에서 동시에 사용되기 때문에, 작은 변경도 전체 UI에 영향을 줄 수 있어 세심한 검토가 필요했습니다.
5. 개선 효과
디자인 토큰 구조 적용 이후 가장 크게 개선된 부분은 가독성과 협업 효율이었습니다. Semantic Token을 통해 변수명만으로도 역할을 직관적으로 파악할 수 있게 되었으며, 디자이너와 개발자 간 의사소통이 보다 명확해졌습니다.
유지보수 측면에서도 효과가 있었습니다. 특정 UI의 색상을 수정할 경우 관련 Semantic Token만 변경하면 전체 스타일에 일관되게 반영되었습니다. 이전보다 수정 범위를 빠르게 파악할 수 있었고, 예상치 못한 사이드 이펙트도 줄어들었습니다.
확장성 또한 크게 향상되었습니다. 새로운 컴포넌트를 추가할 때 기존 토큰 구조를 기반으로 일관된 방식으로 개발할 수 있었으며, 서비스 간 디자인 일관성을 유지하기도 수월해졌습니다.
추가적으로 다크 모드나 서비스별 테마 확장 가능성도 확보할 수 있었습니다. 기존에는 색상 값 자체가 코드 곳곳에 분산되어 있어 테마 변경이 어려웠지만, 현재 구조에서는 Alias 및 Semantic 단계만 조정하여 유연하게 대응할 수 있게 되었습니다.
무엇보다 공통 디자인 기준이 신규 인원이 프로젝트에 합류했을 때도 빠르게 구조를 이해할 수 있게 되었습니다. 이는 협업 효율뿐 아니라 프로젝트 안정성 측면에서도 긍정적인 효과를 가져왔습니다.
6. 결론 및 회고
이번 리팩토링은 단순한 변수 정리 작업이 아니라 디자인 시스템 관점에서 구조를 재설계한 경험이었습니다. 특히 “값” 중심이 아닌 “의미” 중심으로 스타일을 관리해야 유지보수성과 확장성을 동시에 확보할 수 있다는 점을 체감할 수 있었습니다.
또한 토큰 구조를 설계하는 과정에서 협업 기준과 네이밍 규칙의 중요성도 다시 확인할 수 있었습니다. 디자인 시스템은 단순한 스타일 모음이 아니라 팀 전체가 함께 사용하는 공통 언어에 가깝다는 점을 느꼈습니다.
향후에는 컬러뿐 아니라 spacing, typography, radius, shadow 등 다양한 디자인 요소에도 동일한 토큰 구조를 적용할 계획입니다. 이를 통해 보다 체계적이고 확장 가능한 디자인 시스템 환경을 구축하고자 합니다.
이번 작업을 통해 단순 구현 중심의 개발이 아니라 장기적인 유지보수성과 확장성을 고려한 구조 설계의 중요성을 경험할 수 있었습니다. 앞으로도 공통 시스템 관점에서 프로젝트를 바라보며 보다 안정적인 UI 환경을 구축해 나가고자 합니다.
nature