AI와 함께 디자인시스템 마이그레이션 여정 시작

기존 Mantine v6와 신규 v8 디자인시스템을 한 애플리케이션 내에서 동시에 공존시키기 위한 전략이 핵심입니다. 이를 위해 별도의 레포지토리(design-system-next)를 생성하고, v8 기반 컴포넌트를 독립적으로 개발했습니다. 핵심은 두 버전의 스타일이 충돌하지 않도록 CSS 클래스 격리(CSS Class Isolation)와 Provider 분리(Provider Separation)를 구현한 것입니다. v8용 ThemeProvider에 `classNamesPrefix`를 설정하여 `.mantine-Button-root`와 `.mantine-next-Button-root`처럼 클래스 이름을 분리하고, 각 버전에 맞는 ThemeProvider를 화면 영역별로 감싸 사용함으로써 런타임 스타일 충돌을 방지했습니다. 또한, 신규 패키지에서는 Mantine 의존성을 `peerDependencies` 대신 `dependencies`에 포함시켜 버전 간섭 없이 의존성을 완전히 격리했습니다. 이 방식은 번들 사이즈 증가라는 트레이드오프가 있지만, 점진적이고 지속 가능한 마이그레이션을 가능하게 합니다.

수십 개의 컴포넌트 마이그레이션을 AI 에이전트로 자동화하기 위해, 단순 반복 작업을 표준화된 절차로 문서화했습니다. 컴포넌트를 Type 1(순수 래퍼)부터 Type 4(완전 커스텀)까지 분류하고, 각 타입별로 분석, 실행(변환, 테스트 작성, 스토리북 생성), 검증 단계를 정의했습니다. 특히, AI가 공식 문서(Official Documentation)와 팀의 코딩 컨벤션을 참조하도록 Markdown 가이드와 색인 파일(manifest.json)을 제공하여, 존재하지 않는 API를 생성하는 AI 환각(Hallucination)을 최소화했습니다. 또한, 마이그레이션 절차를 bash 스크립트로 커맨드화하여 에이전트가 일관된 기준으로 작업을 수행하도록 했습니다. 이처럼 잘 정의된 절차와 데이터는 AI의 안정적인 결과 도출을 위한 필수 토대입니다.

디자인시스템 내부 컴포넌트 마이그레이션 이후, 이를 사용하는 애플리케이션의 코드 변경을 자동화하기 위해 Codemod를 도입했습니다. AST(Abstract Syntax Tree) 분석 기반의 Codemod 스크립트를 AI로 설계 및 구현하여, `import` 경로 변경이나 컴포넌트 `prop` 변환 같은 반복적인 작업을 자동화했습니다. `@inflearn/ds-codemod` 패키지로 제작하여 각 애플리케이션에서 `pnpm exec ds-codemod` 명령으로 실행 가능하게 했습니다. 이 방식은 코드 변경의 일관성을 보장하고, 마이그레이션 속도를 크게 향상시켰습니다. 다만, 애플리케이션별 환경 차이로 인한 예외 케이스는 수동으로 처리해야 했습니다.

Mantine v7부터 네이티브 CSS로 전환되었지만, 이번 마이그레이션에서는 기존 Emotion(CSS-in-JS) 스타일링 방식을 유지했습니다. 이는 스타일 기술 자체를 통째로 바꾸는 거대한 마이그레이션을 피하고, 점진적인 전환을 목표로 했기 때문입니다. 신규 디자인시스템에서도 `@mantine/emotion`을 통해 Emotion을 그대로 사용했습니다. 이로 인해 발생한 주요 이슈는 스타일 우선순위(Style Priority) 문제였습니다. v8 환경에서 컴포넌트의 `styles API`가 Emotion `css prop`보다 우선순위가 높아, 애플리케이션에서 직접 주입한 스타일이 적용되지 않는 경우가 발생했습니다. 이 문제는 Codemod를 통해 `css prop`을 `styles.root`로 자동 이관하는 규칙을 추가하여 해결했습니다.

AI 에이전트의 결과는 실행마다 달라질 수 있으므로, 안정적인 마이그레이션을 위해 여러 검증 장치를 마련했습니다. 첫째, 프리뷰 스토리북(Preview Storybook)을 제작하여 v6와 v8 컴포넌트를 나란히 비교하며 시각적 동일성을 확인했습니다. 둘째, v6↔v8 자동 비교 테스트를 도입하여 픽셀 단위로 외관 차이를 감지하고, 일정 비율 이상 차이 발생 시 테스트를 실패시켰습니다. 셋째, 실제 서비스와 유사한 Next.js 환경의 샘플 앱 테스트를 통해 혼합 사용 시나리오를 검증했습니다. 이러한 다층적인 검증 프로세스는 자동화된 변경 사항이 기존 기능과 UI를 해치지 않도록 보장하는 게이트 역할을 수행합니다.