01-tokens — 디자인 토큰의 계층과 W3C DTCG 표준

이 챕터가 답하는 질문: 디자인 토큰을 어떻게 계층화하고, 어떤 포맷으로 직렬화하며, 어떻게 여러 플랫폼(Tailwind, Panda, iOS, Android)에 동시에 주입할 것인가. 작성: 2026-05-19 / 분량: 6개 본문 + 인덱스

한 문장 답 (Pyramid Top)

디자인 토큰은 **“디자인 결정을 이름으로 박제한 값”**이며, 현대 디자인 시스템은 그 토큰을 primitive(blue.500) → semantic(primary) → component(button.bg.default)의 3-tier로 나누고, W3C DTCG JSON 한 벌로 정의한 뒤 Style Dictionary 파이프라인을 통해 Tailwind preset / Panda config / CSS variables / iOS UIColor / Android XML을 한꺼번에 생성한다.

Why — 왜 토큰 챕터가 디자인 시스템의 심장인가

디자인 시스템에서 가장 자주 깨지는 약속은 컴포넌트의 모양이 아니라 값이다.

토큰을 값 그 자체가 아니라 이름으로 약속된 슬롯으로 다루면, 위 약속들은 하나의 JSON 파일에서 일관성을 강제할 수 있다. 이 챕터는 그 약속의 문법(DTCG)·계층(3-tier)·도구(Style Dictionary)·운영(versioning)을 모두 다룬다.

How — 6개 문서로 어떻게 쪼갰나

What — 한눈에 보는 3-tier (이 챕터의 핵심)

┌─────────────────────────────────────────────────────────────┐
│ Tier 1: Primitive (raw 값, 의미 없음)                          │
│   color.blue.500 = #3b82f6                                  │
│   color.gray.50  = #f9fafb                                  │
│   spacing.4      = 16px                                     │
└─────────────────────────────────────────────────────────────┘
                            ↓ alias
┌─────────────────────────────────────────────────────────────┐
│ Tier 2: Semantic (의미·역할, 테마에 따라 바뀜)                   │
│   color.primary       = {color.blue.500}     (light)        │
│                       = {color.blue.400}     (dark)         │
│   color.bg.surface    = {color.gray.50}      (light)        │
│                       = {color.gray.900}     (dark)         │
└─────────────────────────────────────────────────────────────┘
                            ↓ alias
┌─────────────────────────────────────────────────────────────┐
│ Tier 3: Component (특정 컴포넌트 슬롯)                          │
│   button.bg.default   = {color.primary}                     │
│   button.bg.hover     = {color.primary.hover}               │
│   card.bg             = {color.bg.surface}                  │
└─────────────────────────────────────────────────────────────┘

왜 이 구조가 결정적인가:

• 브랜드 색을 바꾼다 → Tier 1만 수정
• 다크모드를 추가한다 → Tier 2의 mode만 수정 (Tier 1은 그대로)
• 버튼만의 hover를 바꾼다 → Tier 3만 수정 (Tier 2는 그대로)

각 변경의 반경이 한 층에서 닫힌다. 자세한 설명은 02번 문서에서.

What-if — 토큰을 잘못 다루면

• 함정 1: primitive를 컴포넌트에 직접 박는다 → bg-blue-500이 100곳, 다크모드 추가 시 100곳 수정
• 함정 2: semantic 층을 건너뛰고 component 토큰만 만든다 → button.bg와 card.bg가 따로 놀아 일관성 깨짐
• 함정 3: alias의 alias의 alias → 체인이 깊어져 cycle 감지 실패·디버깅 지옥
• 함정 4: $type 누락 → Style Dictionary가 color를 string으로 처리해 iOS UIColor 생성 실패
• 함정 5: 토큰 이름을 SemVer 없이 변경 → 소비자 코드 무더기로 깨짐 (06번 문서 참고)

Insight — 이 챕터의 큰 그림

디자인 토큰은 2014년 Salesforce Lightning Design System에서 처음 “design token”이라는 용어로 등장했다. 그 직전까지는 Sass 변수가 같은 역할을 했지만, Sass는 웹 한 플랫폼에서만 컴파일된다. iOS·Android·웹에 같은 값을 주고 싶어진 순간, “값의 표현은 플랫폼 중립이어야 한다”는 통찰이 도착했고, Style Dictionary(Amazon, 2016)와 W3C DTCG(2021~)로 이어졌다.

오늘날의 흐름은:

• 포맷 표준화: 모두가 DTCG JSON으로 수렴
• 계층 표준화: primitive/semantic/component 3-tier
• 도구 표준화: Style Dictionary가 사실상 lingua franca

이 챕터는 그 세 가지 표준화를 한 권에 담는다.

다음 챕터

• 02-color-system — primitive color tier를 OKLCH로 수치적으로 설계하기
• 06-theming — semantic 층의 mode 전환 메커니즘
• 07-panda-tailwind-interop — 이 챕터의 토큰을 두 라이브러리에 동시 주입