다중 테마 및 다중 브랜드 토큰 아키텍처

테마는 동일한 브랜드의 색상 모드를 변경합니다. 예를 들어 같은 제품의 밝은 버전과 어두운 버전이 있습니다. 브랜드는 서로 다른 시각적 정체성입니다. 즉, 서로 다른 제품이나 고객을 위해 동일한 디자인 시스템 컴포넌트를 다른 색상, 타이포그래피, 간격으로 표현합니다. 둘 다 동일한 토큰 구조를 사용하지만 서로 다른 추상화 수준에서 작동합니다.

기본 토큰은 시스템에서 사용할 수 있는 원시 값의 전체 팔레트입니다. 여기에는 모든 색상 단계(color-blue-50부터 color-blue-900까지), 모든 간격 단위, 모든 글꼴 크기가 포함됩니다. 기본 토큰은 컴포넌트에서 직접 사용하지 않으며 의미 토큰만 기본 토큰을 참조합니다. 팔레트는 한 번 정의하고 모든 테마와 브랜드에서 공유합니다.

의미 토큰은 의도를 표현합니다. color-background-page, color-text-primary, color-action-primary 등이 그 예입니다. 각 의미 토큰은 현재 테마에 적합한 기본 토큰 값을 참조합니다. 컴포넌트는 오직 의미 토큰을 기준으로 만들어집니다. 테마 적용은 바로 이 계층에서 이루어집니다.

밝은 테마에서는 color-background-page가 color-white를 참조하고, color-text-primary가 color-gray-900를 참조하며, color-action-primary가 color-blue-500을 참조합니다. 이러한 매핑은 테마별 토큰 파일에 정의되며 밝은 환경에 맞게 의미 계층을 재정의합니다.

어두운 테마에서는 color-background-page가 color-gray-950을 참조하고, color-text-primary가 color-gray-50을 참조하며, color-action-primary가 color-blue-400을 참조합니다. 어두운 배경에서 대비를 높이기 위해 약간 더 밝은 색상을 사용합니다. 의미 토큰 매핑만 변경되고 기본 팔레트와 모든 컴포넌트는 그대로 유지됩니다.

브랜드 A는 파란색을 기본 색상으로 사용합니다(color-action-primary: {color-blue-500}). 브랜드 B는 녹색을 사용합니다(color-action-primary: {color-green-500}). 버튼 컴포넌트는 var(--color-action-primary)를 읽으며 어떤 브랜드가 활성화되어 있는지 전혀 알지 못합니다. 브랜드 재정의는 의미 토큰 매핑만 변경하고 컴포넌트 코드는 변경하지 않습니다.

CSS 사용자 지정 속성을 사용하면 런타임 테마 전환을 간단하게 구현할 수 있습니다. 현재 테마를 데이터 속성에 저장합니다. document.documentElement.setAttribute('data-theme', 'dark')를 사용합니다. CSS 규칙은 [data-theme="dark"] 선택자 아래에서 의미 토큰을 재정의합니다. 브라우저는 모든 var() 참조를 새 값으로 즉시 해석하므로 JavaScript로 다시 렌더링할 필요가 없습니다.

서로 다른 브랜드를 별도로 배포하는 경우에는 빌드 시 테마 적용을 사용합니다. Style Dictionary로 브랜드별 CSS 토큰 파일을 별도로 생성하고 애플리케이션 시작 시 올바른 브랜드 CSS를 불러옵니다. 이 방식은 브랜드가 사용자 상호 작용 시점이 아니라 배포 시점에 결정될 때 적합합니다. 예를 들어 서로 다른 도메인, 하위 도메인 또는 화이트 라벨 인스턴스에서 사용할 수 있습니다.

다중 브랜드 및 다중 테마 시스템에는 2차원 행렬이 필요합니다. 브랜드 A 밝은 테마, 브랜드 A 어두운 테마, 브랜드 B 밝은 테마, 브랜드 B 어두운 테마가 그 예입니다. CSS 사용자 지정 속성은 중첩 선택자를 사용해 이를 깔끔하게 처리합니다. [data-brand="a"][data-theme="dark"]는 해당 조합에 맞는 의미 토큰을 재정의합니다. 네 가지 조합을 네 개의 코드베이스로 만들 필요 없이 네 개의 CSS 블록으로 처리할 수 있습니다.

디자인 시스템이 발전하면 토큰이 추가되거나 이름이 변경되거나 삭제됩니다. 토큰은 코드와 같은 저장소에서 버전 관리합니다. 토큰의 사용을 중단할 때는 한 번의 릴리스 주기 동안 이전 이름을 새 이름을 가리키는 별칭으로 유지하고, 사용 중단 주석을 추가하며, 토큰을 사용하는 코드를 업데이트합니다. 구조화된 변경 로그를 통해 디자인 팀과 엔지니어링 팀 간에 토큰 변경 사항을 조율합니다.

관리 체계는 누가 토큰을 추가하거나 변경할 수 있는지, 그리고 어떤 검토 절차가 필요한지를 정의합니다. 원시 토큰은 디자인 팀의 승인이 필요합니다. 의미 토큰은 디자인 팀과 엔지니어링 팀의 검토가 모두 필요합니다. 컴포넌트 토큰은 해당 컴포넌트 소유자가 관리할 수 있습니다. 이러한 관리 체계가 없으면 중복 토큰이 생겨나고 "단일 진실 공급원"이라는 보장이 무너집니다.

컴포넌트는 왜 원시 토큰 대신 의미 토큰을 참조해야 할까요?

테마는 브랜드 안에서 색상 모드를 변경하고, 브랜드는 서로 다른 시각적 정체성입니다. 원시 토큰은 가공되지 않은 색상 팔레트이고, 의미 토큰은 의미를 표현하며 테마 적용을 가능하게 합니다. 컴포넌트는 의미 토큰만 사용합니다. 다크 모드와 브랜드 재정의는 의미 토큰 매핑만 변경하며, 컴포넌트는 변경되지 않습니다. 런타임 테마 적용은 CSS 사용자 지정 속성과 [data-theme] 선택자를 사용하고, 빌드 시점 브랜딩은 브랜드별로 별도의 CSS를 생성합니다. 토큰 관리 체계와 버전 관리는 시스템이 발전하는 동안 일관성을 유지합니다.