로고SEED Design
Migration

Guides

Seed Design V2에서 V3로 마이그레이션하기 위해 필요한 작업들을 안내합니다.

마이그레이션 개요

V2에서 V3로 넘어가기 위해서는 크게 아래와 같은 순서로 진행됩니다.

  1. 이전 버전 용례 분석
  2. V3 설치
  3. 파운데이션 마이그레이션 (일괄 적용 권장)
  4. 컴포넌트 마이그레이션 (화면별로 적용 권장 및 점진적 적용 가능)

기본적으로 파운데이션까지는 프로젝트 전체에 일괄 교체를 진행합니다. 컴포넌트는 그 이후에 화면별로 적용하거나, 컴포넌트 별로 적용하는 것과 같이 점진적 적용이 가능합니다.

V3 설치

V3를 사용하기 위한 기반 작업들을 먼저 진행합니다. 아래 작업들이 끝나면 V3 사용이 가능합니다.

의존성 설치

필요한 의존성들을 설치해요.

npm install @seed-design/react @seed-design/css
  • @seed-design/react는 리액트 컴포넌트 라이브러리가 전부 포함되어 있습니다.
    • 기존 sprout 패키지들을 대체합니다.
    • 컴포넌트 마이그레이션 전까지는 기존 패키지들을 사용해주세요.
  • @seed-design/css는 스타일 관련된 모든 것이 포함되어 있습니다. (vars, theming, recipe, css, etc.)
    • 기존 @seed-design/stylesheet 라이브러리를 대체합니다.
    • 기존 @seed-design/design-token 라이브러리를 대체합니다.
    • 파운데이션 마이그레이션 전까지는 기존 패키지들을 사용해주세요.

CSS import

V2 @seed-design/stylesheet 패키지의 global.css와 상호운용이 가능합니다.

index.tsx
import "@seed-design/css/all.css";

V3 스타일시트 사용법은 Installation의 css import 설명을 참고해주세요.

Theme 적용

변경사항

기존 V2에서 사용되던 data-attribute가 바뀌었습니다.

<html data-seed data-seed-scale-color="light" />
<html data-seed data-seed-color-mode="system" data-seed-user-color-scheme="light" />
  • data-seed: Seed Design 전역 테마 적용 (V3에서 그대로 유지)
  • data-seed-color-mode: Seed Design 테마 강제 적용
    • light-only, dark-only, system 중 하나를 선택할 수 있습니다.
  • data-seed-user-color-scheme: 유저 기기의 설정
    • light, dark 중 하나의 값을 가집니다.
    • v2에서 data-seed-scale-color 속성을 사용하던 코드가 있다면 data-seed-user-color-scheme 속성으로 변경해주세요.

해당 속성들을 직접 적용하는 방법도 있지만 플러그인 적용 방식을 권장합니다. 지원되지 않는 번들러를 사용하는 경우 직접 스크립트 적용 방식을 사용해서 적용해주세요.

플러그인 적용

Vite, Rsbuild, Webpack 등의 번들러를 사용하는 프로젝트에서는 플러그인을 추가하면 바로 Theming을 적용할 수 있습니다.

Vite 사용 시

npm install @seed-design/vite-plugin

Rsbuild 사용 시

npm install @seed-design/rsbuild-plugin

Webpack 사용 시

npm install @seed-design/webpack-plugin

스크립트 적용

@seed-design/css/theming 패키지에서 제공하는 generateThemingScript 함수를 사용해서 스크립트를 생성해요.

index.tsx
import { generateThemingScript } from "@seed-design/css/theming";

생성된 스크립트를 직접 적용해주세요.

<script>
  {generateThemingScript({ mode: "system | light-only | dark-only" })}
</script>

혹은 직접 스크립트를 작성하실 수도 있습니다.

파운데이션 마이그레이션

파운데이션 마이그레이션에는 크게 Color와 Typography 두 가지에 대해서 작업이 필요합니다.

용례 분석하기

우선 현재 프로젝트에서 @seed-design/design-token 패키지를 사용하는 용례를 분석해야합니다.

  • @seed-design/design-token 패키지의 vars를 사용하는 용례
  • @seed-design/design-token 패키지의 vars를 확장해서 사용하는 컴포넌트
  • 위 컴포넌트를 사용중인 코드 용례
  • @seed-design/styleesheet 패키지를 사용하는 용례
  • --seed- prefix로 시작하는 CSS Variable을 사용하는 용례
  • 사용중인 CSS 라이브러리와 @seed-design/design-token 패키지와 결합해서 사용하는 용례

아래의 프롬프트를 이용해서 현재 프로젝트에서 사용중인 용례를 분석할 수도 있습니다.

prompt
Seed Design System의 디자인 토큰을 새로운 토큰으로 마이그레이션
할건데 코드 어디 부분들을 변경해야 하는지 보고서를 써줘.

1. `@seed-design/design-token` 패키지의 vars 변수를 사용하는 용례
2. `@seed-design/design-token` 패키지의 vars 변수를 확장해서 사용하는 컴포넌트
3. 2번 컴포넌트를 사용중인 코드 용례 
4. `@seed-design/styleesheet` 패키지를 사용하는 용례
5. `--seed-` prefix로 시작하는 CSS Variable을 사용하는 용례
6. 사용중인 CSS 라이브러리와 `@seed-design/design-token` 패키지와 결합해서 사용하는 용례

위와 같은 사례들말고도 네가 더 분석해서 추가적으로 마이그레이션 해야하는 부분들도 알려줘.

마이그레이션 전략

  • 만약 여러 패키지를 사용하는 경우에는 공통 패키지 먼저 마이그레이션 합니다.
  • 전처리해서 사용하는 경우에는 전처리 코드 자체를 V3로 마이그레이션 한 후 나머지 코드들을 Codemod로 마이그레이션 하는게 좋습니다.
  • Color와 Typography 각각 진행해도 되지만, Color와 Typography 마이그레이션을 동시에 진행 후 한번에 QA를 진행하는게 더 간결합니다.

Typography Preset

많은 프로젝트에서 기존 타이포그래피 토큰을 이용해서 유틸리티 함수를 만들어서 사용하는 경우가 있습니다.

이런 경우에는 아래의 코드를 참고해서 전처리를 진행 후 코드들을 그에 맞게 변경해주세요.

typography.ts
import type { TextVariant } from '@seed-design/css/recipes/text';
 
import { vars as typographyVars } from '@seed-design/css/vars/component/typography';
 
/**
 * @see https://seed-design.io/docs/foundation/typography/overview
 * @example
 * typography.t1Bold
 * typography.t2Regular
 * typography.t3Bold
 * typography.t4Regular
 * typography.t5Bold
 * typography.t6Bold
 * typography.t7Bold
 * typography.screenTitle
 * ...
 */
export const typography = Object.entries(typographyVars).reduce(
  (acc, [key, value]) => {
    const withoutPrefix = key.replace('textStyle', '');
    const firstChar = withoutPrefix.charAt(0).toLowerCase();
    const restOfString = withoutPrefix.slice(1);
    const name = (firstChar + restOfString) as TextVariant['textStyle'];
    acc[name] = value.enabled.root;
    return acc;
  },
  {} as Record<
    TextVariant['textStyle'],
    {
      fontSize: string;
      fontWeight: string;
      lineHeight: string;
    }
  >,
);

Codemod

기본적으로 마이그레이션은 Codemod를 이용해 진행합니다.

npx @seed-design/codemod <transform> <target_path> <옵션>
  • Codemod는 기본적으로 color와 typography transform을 분리해서 제공합니다.
  • 현재는 Tailwind CSS, Stitches 혹은 Emotion, Vanilla Extract CSS와 같은 CSS-in-JS 라이브러리에 대한 transform을 제공합니다.
  • 각팀에서 커스텀으로 제공되는 transform의 경우에는 replace-custom-의 prefix로 제공됩니다.
  • 커스텀 transform의 변경 예시를 살펴보고 프로젝트와 상황이 같다면 사용할 수 있습니다.
  • 추가로 특정 라이브러리의 transform이 필요하거나, 필요한 경우 커스텀 transform을 만들 수 있습니다. (디자인코어 팀에 문의)

Tailwind CSS

  • Tailwind V3 플러그인을 제공합니다.
  • @seed-design/tailwind3-plugin
  • @seed-design/tailwind4-theme
  • Tailwind transform은 replace-tailwind-typography, replace-tailwind-color 두 개가 제공됩니다.
  • Tailwind 같은 경우는 각 프로젝트에서 커스텀 플러그인을 작성해서 사용중인 경우가 많기 때문에 Codemod가 정확하게 맞지 않을 수 있습니다.
  • Codemod 페이지에서 변경 예시를 살펴보고 프로젝트와 상황이 같다면 사용할 수 있습니다.
  • 예시와 맞지 않다면 디자인코어팀에 문의해주세요.

Stitches CSS

Emotion, Vanilla Extract CSS, (CSS-in-JS)

  • Emotion, Vanilla Extract CSS와 같은 CSS-in-JS 라이브러리는 @seed-design/design-token을 사용하는 경우가 대부분입니다.
  • replace-seed-design-token-vars transform을 사용해서 일괄적으로 마이그레이션 할 수 있습니다.
  • 해당 transform은 color와 typography 두 개 동시에 변경합니다.
  • replace-seed-design-token-vars

Native CSS

Codemod 사용 시 주의사항

Codemod는 다수의 파일을 변경하기 때문에 주의가 필요합니다.

  • 변경사항 추적과 히스토리 관리를 위해서 별도의 브랜치를 사용할 것을 권장합니다.
  • transform에 따라 커밋을 나누는 것을 권장합니다.
  • Codemod 실행 후 lint와 test를 진행해주세요.

Codemod Log 파일

Codemod 실행 시 디버깅에 도움을 주는 로그 파일을 생성할 수 있습니다.

  • --log 옵션을 추가해주세요.
  • 로그 파일은 Codemod 실행 경로에 .report 폴더에 생성됩니다.
  • 로그 파일은 변경사항을 추적하고 히스토리 관리에 도움을 줍니다.
{transform_name}-debug.log
{transform_name}-issues.log
{transform_name}-success.log

debug.log

  • 디버깅 정보를 기록합니다.
  • 변경 시도한 파일 경로와 시간을 기록합니다.
debug.log
2025-03-28 19:17:36 [DEBUG]: Starting transformation of /Project/src/component1.tsx
2025-03-28 19:17:36 [DEBUG]: Starting transformation of /Project/src/component2.tsx
2025-03-28 19:17:36 [DEBUG]: Starting transformation of /Project/src/component3.tsx
2025-03-28 19:17:36 [DEBUG]: Starting transformation of /Project/src/component4.tsx

issues.log

  • 확인이 필요한 변경사항을 기록합니다.
  • 문제가 있는 파일 경로와 라인 번호를 기록합니다.
  • 문제가 있는 이유를 기록합니다.
  • 매핑이 없는 경우를 제외하고는 이미 변경된 상태입니다.
issues.log
2025-03-28 18:46:55 [WARN]: /Project/src/component1.tsx (line: 171)
 ↳ reason: $gray900-static static에서 palette로 변경되는 색상으로 용도 파악 필요
2025-03-28 18:46:55 [WARN]: /Project/src/component2.tsx (line: 194)
 ↳ reason: $gray900-static static에서 palette로 변경되는 색상으로 용도 파악 필요
2025-03-28 18:46:55 [WARN]: /Project/src/component3.tsx (line: 147)
 ↳ reason: $gray900-static static에서 palette로 변경되는 색상으로 용도 파악 필요
2025-03-28 18:46:56 [WARN]: /Project/src/component4.tsx (line: 242)
 ↳ reason: $gray900-static static에서 palette로 변경되는 색상으로 용도 파악 필요

자주 발생하는 문제들은 제일 아래 issues.log 파일에 생긴 문제들은 어떻게 해결해야 하나요?에 정리해두었습니다.

success.log

  • 변경사항 추적에 도움을 줍니다.
  • 변경된 파일 경로와 라인 번호를 기록합니다
  • 변경된 토큰을 기록합니다.
  • CSS 파일을 변경하는 transform의 경우는 토큰을 일일이 기록하지 않습니다.
  • tailwind 같은 경우는 변경된 className을 기록합니다.
success.log
2025-03-28 18:46:54 /Project/src/hooks/hook1.tsx (line: 149): $gray900 → $palette-gray-1000 (line 149)
2025-03-28 18:46:54 /Project/src/hooks/hook2.tsx (line: 155): $gray700 → $palette-gray-800 (line 155)
2025-03-28 18:46:54 /Project/src/components/component1.tsx (line: 54): $divider1-semantic → $stroke-neutral-muted (line 54)
2025-03-28 18:46:54 /Project/src/components/component2.tsx (line: 60): $paperDefault-semantic → $bg-layer-default (line 60)

V2 V3 Compatibility

Color, Typography 마이그레이션이 끝나고 나면 기존 Sprout (V2) 컴포넌트와의 호환성 문제가 있을 수 있습니다.

Sprout 내부에 V2 토큰을 V3 토큰으로 전부 교체한 Compatibility 버전을 제공합니다. 여기까지 진행해야 파운데이션 마이그레이션이 끝난 것으로 간주할 수 있습니다.

Sprout Compatibility 버전 페이지에서 -v3-compat 태그가 붙은 버전중에 최신 버전으로 모든 컴포넌트를 전부 교체해주시면 됩니다. (모든 컴포넌트 동일한 버전을 제공합니다.)

주의할 점: 너무 예전의 버전을 사용하는 경우 컴포넌트 내부에서 breaking changes가 있을 수 있습니다.

V2 V3 Compatibility 버전까지 설치가 되었다면 파운데이션 마이그레이션이 끝난 것으로 간주할 수 있습니다. 이론상 이때부터는 @seed-design/design-token 패키지와 @seed-design/stylesheet 패키지를 제거할 수 있습니다. 또한 V3 컴포넌트를 점진적 사용이 가능합니다.

V3 Compat Script 제거

<script src="https://assets.krrt.io/daangn/seed-design-critical-script/latest/lib/index.js"></script>

기존에 25.10.0 앱버전 이상에서 V2 백그라운드 색상을 V3로 변경하기 위해 추가했던 스크립트는 마이그레이션이 끝나고 제거해도 됩니다.

컴포넌트 마이그레이션

TBD

자주 묻는 질문

issues.log 파일에 생긴 문제들은 어떻게 해결해야 하나요?

토큰 매핑이 안되는 경우 (컬러, 타이포그래피)

  • V3에서 지원하지 않는 토큰을 사용하는 경우입니다. (주로 alpha 색상 토큰이거나 너무 작거나 큰 타이포 토큰입니다.)
  • 토큰 매핑을 확인할 수 있는 방법은 파운데이션을 토큰 매핑을 알고 싶습니다. 설명을 참고해주세요.
  • 해당 경우는 디자이너분과 상의 후 다른 적절한 토큰으로 직접 매핑해주세요.
  • 결정에 어려움이 있는 경우 디자인코어팀에 문의해주세요.

alpha 토큰이 사라진 경우 (컬러)

  • alpha가 들어간 토큰은 대부분의 경우 더 이상 사용되지 않습니다.
  • 직접 CSS에 alpha 채널을 적용해주세요. (opacity 속성을 사용하거나, rgba 형식으로 직접 적용)

static 토큰이 palette로 변경된 경우 (컬러)

  • V3에서 static 컬러 토큰은 웬만해서는 white, black 두 가지만 지원합니다.
  • 나머지 색상 (yellow, green, blue, red, gray) 등은 palette 토큰으로 변경되었습니다.
  • 다크모드와 라이트모드에 따라 색상이 달라질 수 있기 때문에 확인이 필요합니다.
  • 배경은 변하는데 텍스트 색상이 변하지 않거나, 그 반대의 상황이 나올 수 있습니다.
  • 대부분의 경우는 static 토큰이 필요한 경우가 아니기 때문에 palette 토큰으로 변경되었습니다.
  • 이 경우는 디자이너분과 상의 후 기존 static 토큰을 다른 적절한 palette 토큰으로 직접 매핑해주세요.

선택지가 두개인 토큰으로 매핑된 경우 (컬러)

  • 컬러 토큰의 경우 대체 토큰이 두 가지인 경우가 있습니다. (ex. primary -> bg.brand-solid, fg.brand)
  • fg는 텍스트, 아이콘 등 UI의 전경 요소에 사용되는 색상입니다. (color, fill, etc.)
  • bg는 전체 화면 또는 UI의 배경에 사용하는 색상입니다. (backgroundColor, etc.)
  • 변경되어야 하는 토큰을 Codemod가 판단하기 어려울 수 있습니다.
  • 이 경우는 직접 적절한 토큰으로 매핑해주세요.

alternate 토큰으로 변경된 경우 (타이포그래피)

  • 기본적으로 Mapping은 1:1 매핑을 지원합니다.
  • 하지만 V3에서 Deprecated 된 토큰인 경우, 대체 토큰으로 매핑 될 수 있습니다.
  • 그런 경우 font size나 line height가 변경되었을 수 있습니다.
  • 이 경우는 직접 UI를 확인해야 합니다.

파운데이션을 토큰 매핑은 어디서 확인할 수 있나요?

Migration Reference에서 토큰 매핑을 확인할 수 있습니다.

Known Issues

Vanill Extract CSS + Vite + V3 사용시

  • @vanilla-extract/vite-plugin와 @seed-design/vite-plugin을 같이 사용하는 경우 빌드가 실패할 수 있습니다.
  • @vanilla-extract/vite-plugin의 버전을 5 이상으로 업그레이드 해주세요.

MCP

AI Agent를 활용해 생산성을 높일 수 있는 Model Context Protocol(MCP)를 제공합니다.

Improvements

Next Page

On this page

마이그레이션 개요
V3 설치
의존성 설치
CSS import
Theme 적용
변경사항
플러그인 적용
스크립트 적용
파운데이션 마이그레이션
용례 분석하기
마이그레이션 전략
Typography Preset
Codemod
Tailwind CSS
Stitches CSS
Emotion, Vanilla Extract CSS, (CSS-in-JS)
Native CSS
Codemod 사용 시 주의사항
Codemod Log 파일
debug.log
issues.log
success.log
V2 V3 Compatibility
V3 Compat Script 제거
컴포넌트 마이그레이션
자주 묻는 질문
issues.log 파일에 생긴 문제들은 어떻게 해결해야 하나요?
토큰 매핑이 안되는 경우 (컬러, 타이포그래피)
alpha 토큰이 사라진 경우 (컬러)
static 토큰이 palette로 변경된 경우 (컬러)
선택지가 두개인 토큰으로 매핑된 경우 (컬러)
alternate 토큰으로 변경된 경우 (타이포그래피)
파운데이션을 토큰 매핑은 어디서 확인할 수 있나요?
Known Issues
Vanill Extract CSS + Vite + V3 사용시