들어가며
현재 사내에서 디자인시스템 2버전에서 3버전으로 마이그레이션을 진행 중입니다. 필요한 파운데이션과 컴포넌트는 어느 정도 개발이 완료된 상태이고, 이제 각 팀에 마이그레이션을 적용해야 하는 단계에 와 있습니다.
문서 작성과 패키지 및 툴링 관련 수정해야 할 부분들이 아직 많아 가야 할 길이 멀지 만, 지금까지의 중간 과정에서 어떤 방식으로 진행하고 있는지, 앞으로 무엇을 해야 하는지 정리해보려고 합니다.
이 글의 목적은 정보 전달보다는 제 경험 공유와 중간 과정 정리에 가깝습니다. 따라서 실용적인 내용이 부족하거나 구성이 다소 산만할 수 있음을 미리 양해 부탁드립니다.
파운데이션 마이그레이션
기존 디자인시스템은 약 1년 반에서 2년 정도 유지되어 왔습니다. 그동안 각 팀의 코드베이스에 깊숙이 녹아들어 정말 다양한 방식으로 사용되고 있죠. 이 상황은 마치 이미 잘 달리고 있는 자동차의 바퀴를 주행 중에 갈아끼워야 하는 것과 같습니다.
파운데이션은 크게 두 가지로 나눌 수 있습니다:
- 컬러
- 타이포그래피
타이포그래피는 아직 정확한 마이그레이션 계획이 수립되지 않았고, 컬러에 비해 코드상에서 사용되는 빈도가 현저히 낮습니다. 타이포그래피는 주로 텍스트가 있는 곳에만 사용되지만, 컬러는 배경색, 테두리 색, 글자색 등 훨씬 다양한 용도로 활용되기 때문에 마이그레이션 비용이 더 큽니다. 따라서 이 글에서는 우선 컬러 마이그레이션에 초점을 맞추겠습니다.
이번 마이그레이션에서는 파운데이션 토큰들의 이름 체계와 전반적인 구조가 변경되었기 때문에 이에 대한 체계적인 접근이 필요했습니다.
용례 파악
첫 번째 과제는 현재 코드베이스에서 디자인시스템이 어떻게 사용되고 있는지 파악하는 것이었습니다. 각 프로젝트마다 사용하는 스타일링 라이브러리가 다양했습니다:
- Tailwind CSS
- Vanilla Extract
- Emotion CSS
- Native CSS
- etc.
심지어 한 프로젝트 내에서도 여러 스타일링 방식이 혼용되는 경우도 있었습니다.
지금까지의 경험을 바탕으로 보면, 대부분의 프로젝트에서는 우리 디자인시스템의 Variable 패키지를 import하여 다양한 방식으로 활용하고 있었습니다. 예를 들어, Tailwind에서는 Plugin을 직접 만들어 color를 extend하거나, Vanilla Extract에서는 TypeScript로 작성하기 때문에 variable package를 그대로 사용하는 식이었습니다.
1// 예시를 들자면 이런 느낌입니다. 2// Tailwind Config 3import { vars } from "design-system-variable-package"; 4 5export default { 6 theme: { 7 extend: { 8 color: { 9 ...vars, 10 } 11 } 12 } 13}
또 다른 패턴으로는 각 프로젝트에서 <Text />, <Box /> 같은 유틸리티 컴포넌트를 만들어 디자인시스템 variable들을 prop으로 받아 사용하는 경우도 있었습니다. 이런 경우들도 모두 새로운 디자인 토큰으로 변경해야 했습니다.
1// 예시 2<Text color="primary" /> 3<Box bgColor="gray900" />
매핑 전략
마이그레이션의 핵심은 이전 토큰과 새 토큰 간의 명확한 매핑을 제공하는 것이었습니다. 이를 위해 다음과 같은 매핑 구조를 만들었습니다:
1export const semanticColorMappings = [ 2 { 3 previous: "$semantic.color.on-primary", 4 next: ["$color.palette.static-white"], 5 }, 6 { 7 previous: "$semantic.color.primary", 8 next: ["$color.bg.brand-solid", "$color.fg.brand"], 9 alternative: ["$color.palette.carrot-600"], 10 }, 11 // ... 12];
이 매핑 파일은 진실의 원천(source of truth)으로 작동하며, Codemod나 변경사항을 정리하는 문서 페이지는 이 매핑 파일을 import하여 사용하도록 설계했습니다. 인터페이스는 상황이나 환경에 따라 달라질 수 있지만, 이러한 아키텍처 구성은 매우 효과적이었습니다.
디자인시스템 마이그레이션은 컬러뿐만 아니라 타이포그래피, 컴포넌트, 아이콘 등 다양한 요소에 걸쳐 변경사항이 많았기 때문에, 팩트에 기반한 정보를 체계적으로 관리할 공간이 필요했습니다. 모든 값은 토큰 ID를 기준으로 정리했습니다.
참고:
Codemod 활용
Codemod에 대해서는 Toss Tech의 글이 잘 정리되어 있으니 참 고하시면 좋을 것 같습니다.
단순히 코드 에디터에서 Find and Replace를 사용할 수도 있지만, 맵핑에 대한 맥락을 고려해야 했고, 최근에는 LLM을 활용하여 codemod transform을 빠르게 작성할 수 있게 되었습니다.
우리의 목표는 고수준의 CLI를 제공하거나 새로운 라이브러리를 만드는 것이 아니었습니다. 단순히 jscodeshift를 래핑하여 사용하는 방식을 선택했습니다. transform(변환 함수)은 최대한 작은 기능 단위로 구성했습니다:
- tailwind color className만 변경
- 디자인토큰 패키지에서 import한 vars 변수들만 새 토큰으로 교체
- 컴포넌트 prop 값 변경
처음부터 과도한 추상화보다는 현재 마이그레이션이 필요한 프로젝트의 문제를 확실하게 해결하는 방식으로 접근했습니다. 그 과정에서 최적화할 수 있는 부분이 보이면 점진적으로 개선해 나갔습니다.
현재는 replace-color-tailwind, replace-color-vars, replace-color-prop 등의 변환 함수를 사용하고 있습니다. 또한 CSS 파일 변환을 위한 transform도 작성 중인데, jscodeshift는 CSS parsing을 지원하지 않기 때문에 PostCSS와 같은 다른 처리 도구를 활용할 계획입니다.
참고:
컴포넌트 마이그레이션
이번 디자인시스템 버전 업데이트에서는 색상이나 타이포그래피의 실제 값 자체가 변경되는 경우가 있습니다. 예를 들어, 같은 gray-600이라는 이름이지만 실제 색상 값이 달라진 경우가 있습니다. 이런 상황에서 각 프로젝트의 컬러만 마이그레이션하면 사이트 전체가 시각적으로 깨질 위험이 있습니다.
그 이유는 컴포넌트 라이브러리를 제외한 나머지 부분에서는 색상이 업데이트되었지만, 컴포넌트 자체는 여전히 이전 버전의 컬러 토큰을 사용하고 있기 때문입니다.
"컴포넌트도 그냥 빨리 마이그레이션하면 되지 않을까?"라고 생각할 수 있지만, 작업 분량이 방대하고 컴포넌트 마이그레이션은 파운데이션 마이그레이션과는 또 다른 도전 과제입니다. 아직 완전히 정리되지 않은 부분도 있어서, 두 작업을 순차적으로 진행하기로 결정했습니다.
이런 상황에서 가장 효과적인 접근법은 이전 버전과 새로운 버전 간의 호환성(compatibility)을 제공하는 것입니다. 다행히 이전 버전의 컴포넌트 CSS variables만 정의해둔 레이어가 존재하기 때문에, 그 부분의 토큰들만 변환하여 이전 버전 컴포넌트의 버전을 업데이트할 수 있습니다.
이렇게 하면 사용자는 "새로운 컬러 토큰을 사용하는 이전 버전의 컴포넌트"를 다운로드하기만 하면 새로운 토큰들과의 호환성을 확보할 수 있습니다. 현재로서는 이러한 방식으로 진행할 계획입니다.
앞으로의 계획
아직 정리해야 할 부분이 많고, 가야 할 길도 멀며, 공부해야 할 내용도 넘쳐납니다. 그래서 각 부분에 대해 상세하게 다루지는 못했습니다.
하나의 디자인시스템 안에서도 각 파트를 깊이 있게 살펴보면 공부해야 할 부분과 논의할 내용이 많지만, 현재는 열심히 공부하고, 만들고, 마이그레이션하는 단계이기 때문에 자세한 내용은 추후에 다루겠습니다.
작년에는 아이콘 마이그레이션을 전적으로 담당하고 이끌었는데, 그 경험도 블로그에 공유할 수 있으면 좋겠습니다. 앞으로도 디자인시스템 관련 작업을 진행하면서 얻은 교훈과 인사이트를 계속해서 공유하겠습니다.
여러 마이그레이션 가이드 문서
개인 참고용
