디자인 시스템 레거시 도입 가이드: 점진적 마이그레이션 전략
이미 수천 명의 사용자가 결제하고 있는 복잡한 레거시 프로젝트에 “오늘부터 디자인 시스템을 도입하겠습니다”라고 선언하는 것은 마치 달리고 있는 자동차의 엔진을 통째로 교체하겠다는 말과 같습니다. 코드 곳곳에 하드코딩된 #3B82F6 색상과 중구난방으로 적용된 여백들을 보면 어디서부터 손을 대야 할지 막막함이 앞서기 마련이죠.
실제로 많은 팀이 의욕적으로 ‘빅뱅(Big-bang) 방식’의 전면 개편을 시도하다가 예기치 못한 사이드 이펙트와 끝없는 회귀 테스트의 늪에 빠져 포기하곤 합니다. 하지만 포기하기엔 디자인 시스템이 주는 생산성의 가치가 너무나 큽니다. 20년 차 개발자로서 제가 수많은 ‘스파게티 코드’ 프로젝트에 디자인 시스템을 이식하며 정립한 안전하고 점진적인 마이그레이션 전략을 공유해 드릴게요.
빅뱅 방식은 왜 실패하는가: 병렬 운영의 필요성
레거시 시스템 마이그레이션에서 가장 큰 실수는 기존 코드를 삭제하고 새 코드를 넣으려는 시도입니다. 레거시 코드는 비즈니스 로직과 스타일이 거미줄처럼 엉켜 있는 경우가 많아, 클래스 하나만 건드려도 전혀 상관없는 페이지의 레이아웃이 무너질 수 있습니다.
그래서 우리는 ‘병렬 운영(Parallel Running)’ 전략을 취해야 합니다. 기존의 CSS/컴포넌트 체계를 그대로 둔 상태에서, 새로운 디자인 시스템 라이브러리를 의존성으로 추가하고 조금씩 영역을 넓혀가는 방식입니다. 새로운 기능을 개발할 때만 디자인 시스템 컴포넌트를 사용하고, 기존 페이지는 유지보수가 발생할 때마다 한 조각씩 교체해 나가는 ‘보이스카우트 규칙(캠프장을 올 때보다 더 깨끗하게 만들고 떠나기)’을 적용하는 것이죠.
[💡 에디터의 실무 팁: 레거시와 새 시스템이 충돌하지 않도록 새 시스템의 모든 CSS 클래스나 변수에는 반드시 ds-와 같은 접두사(Prefix)를 붙이세요. 이름 충돌만 막아도 마이그레이션 난이도가 절반으로 줄어듭니다.]
1단계: 디자인 토큰부터 이식하기 (The Low-hanging Fruit)
가장 위험이 적으면서 효과가 빠른 첫걸음은 컴포넌트가 아니라 ‘디자인 토큰’을 먼저 심는 것입니다. 프로젝트 전반에서 사용되는 핵심 색상, 폰트 크기, 간격 값을 CSS 변수(Custom Properties)로 정의하여 글로벌 스타일 파일에 주입하세요.
기존의 하드코딩된 값들을 한꺼번에 바꾸려 하지 마세요. 우선은 새로 작성하는 코드부터 color: var(--ds-color-primary)와 같이 토큰을 참조하도록 합니다. 그다음, 검색 기능을 활용해 빈번하게 쓰이는 헥사 코드를 찾아내어 점진적으로 토큰으로 교체해 나갑니다. 이 단계만으로도 전체 서비스의 톤앤매너를 제어할 수 있는 중앙 통제실을 확보하게 됩니다.
2단계: CSS 격리와 컴포넌트 브릿지 설계
레거시 프로젝트의 글로벌 오염(Global Pollution)은 마이그레이션의 최대 적입니다. 예전 스타일 가이드가 새 컴포넌트의 디자인을 망치지 않도록 방어막을 쳐야 합니다. 이를 위해 CSS Modules나 CSS-in-JS의 Scoping 기능을 적극 활용하세요.
만약 라이브러리 형태로 도입하기 어려운 상황이라면, ‘브릿지 컴포넌트’ 패턴을 추천합니다. 기존 프로젝트의 공통 버튼 컴포넌트 내부에서 새로운 디자인 시스템의 버튼을 조건부로 렌더링하거나, 스타일만 디자인 시스템 토큰을 따르도록 래핑하는 방식입니다. 이렇게 하면 외부 인터페이스는 유지하면서 내부 구현만 시스템화할 수 있어 사이드 이펙트를 최소화할 수 있습니다.
[💡 에디터의 실무 팁: 마이그레이션 도중 디자인 시스템이 아직 지원하지 않는 복잡한 UI를 만날 수 있습니다. 이때 시스템을 억지로 확장하기보다, 레거시 컴포넌트에 시스템 토큰만 입혀서 ‘하이브리드’ 상태로 두는 용기가 필요합니다.]
트러블슈팅: 예상치 못한 레이아웃 붕괴 대응법
실제로 한 이커머스 메인 페이지의 버튼을 시스템 컴포넌트로 교체했다가, 주변 요소들과의 마진 값이 꼬여서 전체 레이아웃이 틀어졌던 경험이 있습니다. 원인은 레거시 코드에 숨겨진 !important와 부모 요소에서 강제로 주입하는 display: inline-block 같은 스타일 때문이었습니다.
이런 상황에서 디자인 시스템 컴포넌트를 수정하는 것은 최악의 선택입니다. 시스템은 순수하게 유지하되, 레거시 페이지의 전용 스타일시트에서 해당 컴포넌트를 감싸는 ‘어댑터(Adapter)’ 클래스를 만들어 간격을 보정해 주세요. “레거시의 문제는 레거시에서 해결한다”는 원칙을 지켜야 디자인 시스템이 오염되는 것을 막을 수 있습니다.
마이그레이션 완료를 위한 로드맵과 팀 컨센서스
마이그레이션은 기술적인 작업인 동시에 문화적인 작업입니다. 모든 개발자가 마이그레이션의 우선순위를 공감해야 합니다. 저는 팀 내부에 ‘Migration Dashboard’를 만들어, 전체 컴포넌트 중 몇 퍼센트가 시스템 컴포넌트로 교체되었는지 시각화하여 공유하곤 했습니다.
숫자로 증명되는 진척도는 팀원들에게 성취감을 주고, 경영진에게는 시스템 도입의 타당성을 입증하는 훌륭한 근거가 됩니다. 완벽함보다는 지속성에 가치를 두세요. 레거시 코드의 80%가 시스템화되었다면, 나머지 20%는 억지로 고치기보다 자연스럽게 서비스가 종료되거나 개편될 때까지 기다리는 것이 비즈니스 관점에서 훨씬 현명한 판단일 수 있습니다.
자주 묻는 질문(FAQ)
Q1. 마이그레이션 기간 동안 디자인 시스템이 계속 바뀌면 어떡하죠? 디자인 시스템 자체의 버전 관리(Versioning)가 매우 중요합니다. 유의적 버전(SemVer)을 지키고, Breaking Changes가 발생할 때는 레거시 프로젝트에서 선택적으로 업데이트할 수 있도록 패키지 형태로 관리하는 것을 권장합니다.
Q2. 레거시가 너무 오래되어 최신 CSS 기능을 지원하지 않는데 어쩌죠? PostCSS와 같은 트랜스파일러를 활용해 CSS 변수를 일반 값으로 변환(Fallback)해 주거나, 디자인 시스템 빌드 시점에 IE11 등 하위 브라우저용 스타일시트를 별도로 생성하는 Style Dictionary 설정을 추가하여 해결할 수 있습니다.
Q3. 마이그레이션 비용 대비 효과를 어떻게 설득하나요? “신규 페이지 개발 속도”를 지표로 삼으세요. 디자인 시스템 도입 전과 후, 컴포넌트를 조합해 페이지 하나를 만드는 데 걸리는 시간이 얼마나 단축되었는지를 데이터로 보여주는 것이 가장 강력한 설득 도구입니다.