디자인 토큰 마이그레이션: 역할을 나누고 이전 토큰을 안전하게 폐기하기

디자인 토큰은 색상 역할, 간격 단계, 타입 스케일, 요소의 높이와 계층을 나타내는 값처럼 반복 결정을 컴포넌트와 플랫폼에서 재사용하게 합니다. 토큰이 틀렸거나 모호하거나 제품에 맞지 않게 되면 문제가 시작됩니다. 이름이나 값을 한 번에 바꾸면 대비·레이아웃·문서·코드가 동시에 깨질 수 있습니다.

안전한 방법은 토큰 변경을 마이그레이션으로 다루는 것입니다. 이전 결정의 사용처를 찾고 더 명확한 대체를 도입한 뒤 사용처를 작은 그룹으로 옮기고, 검증을 통해 안전하게 제거할 수 있음을 확인한 뒤 이전 이름을 폐기합니다. 처음부터 토큰 세트를 만드는 일과 달리 이미 운영 중인 시스템을 유지하는 방법입니다.

기초 내용은 디자인 토큰 가이드(영문)와 Pixso의 디자인 토큰 개요를 참고하세요. 이 글은 폐기·소유권·마이그레이션 근거에 범위를 좁힙니다.

토큰 변경이 위험해지는 이유

이전 토큰은 검색 결과보다 많은 곳에 나타날 수 있습니다. 의미 색상이 버튼·차트·비활성 상태·파트너 브랜드 테마에 공급될 수 있고, 간격 토큰이 컴포넌트 재정의에 복사되거나 플랫폼별 상수로 변환될 수 있습니다. blue-500 같은 이름도 한 제품에서는 성공 색, 다른 제품에서는 강조 색으로 쓰일 수 있습니다.

마이그레이션 위험은 보통 네 가지 공백에서 나옵니다:

1. 팀이 토큰 사용처를 모르는 경우
2. 대체가 값뿐 아니라 의미도 바꾸는 경우
3. 디자인과 코드의 일정이 다른 경우
4. 이전 토큰의 완료 조건이 정의되지 않은 경우

해결책은 시스템을 동결하는 것이 아니라 대체를 공지하기 전에 의존성과 결정을 드러내는 것입니다.

이름이 아니라 역할별로 토큰 인벤토리 만들기

의도와 사용을 설명하는 표로 시작합니다. 토큰 이름·범주·의미 역할·지원 모드·토큰을 사용하는 컴포넌트·담당자·제안 행동을 넣습니다. 헥스 값만으로 의미 역할을 추론하지 마세요. 같은 값이어도 역할은 다를 수 있고, 하나의 토큰도 라이트·다크 테마에서 다른 값이 필요할 수 있습니다.

첫 시도부터 분류를 완벽하게 만들려 하지 말고 근거를 기록합니다. 추측한 의존성이 가득한 큰 목록보다 정확한 작은 인벤토리가 유용합니다. 디자인 토큰 명명 가이드(영문)는 원칙을 제공하지만 마이그레이션 결정은 토큰을 사용하는 제품을 담당하는 팀의 몫입니다.

이름 변경·별칭·교체 중 선택하기

이 행동들은 서로 다른 문제를 해결합니다.

명확성을 위한 이름 변경

토큰의 의미는 맞지만 이름이 오해를 부르거나 일관되지 않을 때 이름을 변경합니다. 정해진 전환 기간에는 이전 이름에서 새 이름으로 별칭을 유지합니다. 이름 변경과 동시에 대비나 간격을 몰래 바꾸면 회귀 원인을 구분할 수 없습니다.

호환성을 위한 별칭

호환용 별칭은 각 사용처가 새 토큰으로 옮겨 가는 동안에도 이전 이름으로 값을 찾을 수 있게 합니다. 해당 별칭의 담당자와 제거 조건을 정합니다. 이는 영구적으로 유지할 수 있는 의미 기반 참조와 구분해야 합니다. 예를 들어 text-secondary는 시스템이 유지되는 동안 계속 기초 색상 토큰을 참조할 수 있습니다. 다른 토큰을 참조한다는 사실만으로 참조하는 토큰이나 참조 대상 토큰이 사용 중단 권고 상태가 되는 것은 아닙니다.

의미 결정을 교체하기

하나의 이름이 양립할 수 없는 용도를 덮을 때 의미 결정을 교체합니다. text-muted가 읽을 수 있는 폼 안내와 비활성 버튼 라벨에 모두 쓰인다면 text-secondary와 text-disabled로 나눕니다. 전역 치환 하나로 두 역할을 올바르게 매핑할 수 없으므로 사용처를 역할별로 검토합니다.

사용처가 남아 있지 않을 때만 제거하기

삭제는 마지막 단계입니다. 팀이 확인할 수 없는 패키지에서 이전 토큰을 아직 사용한다면 확인할 수 없는 범위를 기록하고 사용 중단 권고 상태를 유지합니다. 토큰을 찾지 못해 빌드에서 대체값이 적용되는 것은 정리가 성공했다는 증거가 아닙니다.

평가 가능한 대체 토큰 만들기

대체 토큰에는 한 문장 정의, 허용 맥락, 모드, 올바른·잘못된 사용 예가 있어야 합니다. 값이 바뀐다면 견본만 보지 말고 실제 컴포넌트의 전후를 보여 줍니다. 포커스·호버·비활성·선택·오류·고밀도 상태도 검토합니다. 토큰의 결함은 컴포넌트의 기본 화면에 드러나지 않는 상태에 숨어 있는 경우가 많습니다.

보조 텍스트도 읽을 수 있어야 하며 더 옅은 색이라고 대비를 무시할 수는 없습니다. WCAG의 비활성 컨트롤 예외는 disabled라는 이름이 아니라 실제 컨트롤 상태에 연결됩니다. 다른 범주의 토큰도 실제로 사용하는 컴포넌트에서 줄바꿈·간격·포커스 가시성·테마 동작을 확인합니다. 견본에서는 문제가 없는 값도 실제 사용 맥락에서는 적합하지 않을 수 있습니다.

대체 토큰 옆에 마이그레이션 메모를 추가합니다:

새 작업에서는 text-muted를 사용하지 않습니다. 읽을 수 있어야 하는 보조 문구에는 text-secondary를, 실제로 비활성화된 컨트롤의 라벨에는 text-disabled를 적용합니다. 기존 사용처는 해당 컴포넌트를 검토할 때까지 이전 값을 유지합니다. 컴포넌트 담당자는 각 변경을 기록하고 호환용 별칭을 제거해도 되는 시점을 확인합니다.

구체적인 범위가 있어야 디자이너·개발자·리뷰어가 풀 리퀘스트에서 이전 참조를 만났을 때 메모를 사용할 수 있습니다.

이 비교에 집중한 Pixso 파일에서 같은 설정 카드의 text-muted를 text-secondary와 text-disabled로 나누기 전후를 비교합니다. 레이아웃과 문구는 그대로 유지합니다. “날짜 선택” 안내는 읽을 수 있어야 하고, “변경 저장”은 실행할 수 없는 동작을 나타내야 합니다. 각 라벨이 사용하는 역할을 주석으로 표시한 뒤 두 컴포넌트를 구현 담당자와 검토합니다. 대응하는 코드 매핑은 별도로 기록하고, 검토가 끝나면 승인된 디자인 라이브러리 업데이트를 게시합니다.

Pixso에서 스타일 변경 전후 비교하기 →

컴포넌트나 제품 영역별로 나누어 이전하기

검토하고 필요하면 되돌릴 수 있을 만큼 작업 범위를 작게 나눕니다. 한 컴포넌트군·제품 영역·테마로 시작합니다. 큰 파일의 모든 토큰을 옮기면 효율적으로 보이지만 회귀 위치를 찾기 어려우므로 정상·상호작용·비활성·오류 상태를 모두 사용하는 대표 컴포넌트부터 선택합니다.

각 작업 단위에 다음을 기록합니다:

• 이전·새 토큰 이름
• 영향받는 컴포넌트와 상태
• 예상 시각·의미 변화
• 디자인·코드 담당자
• 검증 스크린샷 또는 링크
• 별칭 경로 종료 가능 날짜

공유 디자인 작업 공간에서는 상태를 비교하고 결정을 검토할 수 있습니다. 디자인 시스템 예시(영문)와 디자인 시스템 확장 가이드(영문)는 전체적인 맥락을 제공하지만 마이그레이션 기록은 현재 컴포넌트에 붙어 있어야 합니다.

의미 회귀와 시각 회귀를 따로 점검하기

시각 비교만으로는 충분하지 않습니다. 대체가 비슷해 보여도 의미·대비·포커스 표시·코드 사용처의 폴백이 바뀔 수 있습니다. 의미 점검과 시각 점검 두 목록을 사용합니다.

의미 점검

• 토큰이 문서화된 역할에만 사용되는가?
• 값이 대비·상태 요건을 충족하는가?
• 지원 테마에서 일관되게 동작하는가?
• 내보낸 이름과 플랫폼 매핑이 안정적인가?
• 지원하지 않는 용도의 사용을 차단하거나, 적어도 검토 과정에서 드러나게 하는가?

시각 점검

• 예상 폭에서 텍스트가 다르게 줄바꿈되지 않는가?
• 테두리·구분선·포커스 링이 구분되는가?
• 오버레이와 메뉴 계층이 유지되는가?
• 데이터가 많은 화면의 밀도와 훑어보기가 유지되는가?
• 모바일과 데스크톱이 정렬되는가?

두 목록은 보기 좋은 스크린샷이 상태나 접근성 회귀를 가리는 일을 막습니다. 컴포넌트 리뷰에 근거를 붙이고 두 목록을 통과한 뒤에만 토큰 상태를 바꿉니다.

변경을 제품 변화로 소통하기

토큰을 사용하는 팀에 이전 이름·변경 이유·대체 규칙·영향 컴포넌트·담당자·제거 릴리스를 담은 마이그레이션 공지를 제공합니다. Design Tokens Format Module(영문)을 사용한다면 $deprecated로 상태와 설명을 표시할 수 있습니다. 이 메타데이터는 상태를 알릴 뿐 사용처를 찾거나 참조를 자동으로 이동하지 않습니다.

팀 전체가 이해할 수 있는 상태 어휘를 사용합니다:

상태를 토큰과 릴리스 노트에 함께 둡니다. 디자인 토큰 릴리스 문서를 팀 내부의 마이그레이션 목록에서 연결할 수는 있지만, 일반적인 제품 안내가 개별 프로젝트의 전환 일정을 보장하는 것처럼 표현하지 않습니다.

근거로 이전 토큰 폐기하기

제거 전에 디자인 파일·코드 패키지·문서·내보낸 자산에서 최종 사용처 검색을 실행합니다. 외부·보관 화면의 담당자에게 경계를 확인받고 생성 파일과 소스 파일을 모두 확인합니다. 생성 패키지에 이전 이름이 남아 있어도 빌드는 통과할 수 있습니다.

명확한 종료 기록을 정의합니다:

1. 지원 대상 사용처 중 이전 이름이 필요한 곳이 더 이상 없는가? 예외가 남아 있다면 다른 패키지에서 토큰을 제거하기 전에 해당 사용처를 위한 호환 경로를 유지했는가?
2. 대체 토큰이 지원하는 모든 모드에서 의미 점검과 시각 점검을 모두 통과했는가?
3. 별칭과 노트에 제거일이 공지됐는가?
4. 문서·예시·자동완성이 이전 이름을 권장하지 않는가?
5. 뒤늦게 발견된 사용처를 위한 롤백 경로가 있는가?

지원 사용처가 마이그레이션된 패키지에서만 이전 토큰을 제거합니다. 마지막 작동 패키지 버전·매핑·검증 예시를 함께 보존해 롤백이 이전 계약을 복원하게 합니다. 뒤늦게 발견된 사용처가 나타나면 담당자가 매핑을 검토하는 동안 호환성을 복원하고 비슷해 보이는 값으로 몰래 대체하지 않습니다.

예외 레지스터 유지하기

모든 사용처가 같은 일정으로 이동할 수는 없습니다. 모바일 릴리스가 동결됐거나 파트너 패키지가 공개 토큰 이름을 노출하거나 레거시 테마가 대체를 지원하지 않을 수 있습니다. 각 예외에 담당자·영향 화면·이유·검토일을 기록합니다. 명시적이고 임시인 예외가 조용히 별칭을 남기는 것보다 안전합니다.

레지스터에는 전환 중 사용자가 보게 될 것도 적습니다. 레거시 테마가 이전 값을 유지한다면 예상 차이와 아직 검증하지 않은 상태를 문서화합니다. 담당자가 적용 조건의 변화를 확인하면 사용처 목록을 갱신하고 예외를 해소해, 문서화되지 않은 두 번째 마이그레이션 경로가 남지 않게 합니다. 제품과 패키지가 서로 다른 속도로 바뀌어도 이 기록을 통해 토큰 관리가 실제 상황을 반영하도록 유지할 수 있습니다.

각 사용처의 변경을 확인하고 마이그레이션 완료하기

설정 카드의 종료는 도움말과 비활성 라벨이 디자인·구현에서 문서화된 역할을 사용하고, 지원 테마를 검토했으며, 지원 인스턴스가 text-muted에 의존하지 않는 상태입니다. 해결되지 않은 사용처는 마이그레이션 기록에 남깁니다. 새 토큰이 단독으로 완성되어 보일 때가 아니라 의존성이 사라졌을 때 패키지에서 이전 이름을 제거합니다.

추가 읽을거리

• Design Tokens Community Group: Format Module(영문)
• W3C Design Tokens Community Group(영문)
• Material Design: 디자인 토큰(영문)