01 — Design Tokens

한 줄 답: 디자인 토큰은 디자인 결정을 코드로 표현한 단일 진실 소스다. blue-500 같은 원시(primitive) 토큰, color-primary 같은 의미(semantic) 토큰, button-bg 같은 컴포넌트(component) 토큰의 3계층으로 쌓여, 디자이너의 결정이 Figma → JSON → CSS → 모든 플랫폼으로 한 방향 전파되게 한다. 2024년부터 W3C Design Tokens Community Group(DTCG)의 JSON 포맷이 사실상 표준화되고 있다.

Why — 왜 토큰이 필요한가

토큰 없는 세계

.button         { background: #2563eb; }
.link-cta       { color: #2563eb; }
.tag-active     { border-color: #2563eb; }
.notification   { background: #2563eb; }
/* 200개 파일에 #2563eb가 흩어져 있다 */

이제 다크모드를 추가하라는 요청이 오면 → 200개 파일을 모두 수정해야 한다. 색상 하나 변경에 PR 200개. 디자이너가 “조금 더 진한 파란색으로”라고 말하면 그 한 문장이 주 단위 작업이 된다.

토큰 있는 세계

:root {
  --color-brand-500: #2563eb;        /* primitive */
  --color-action-primary: var(--color-brand-500); /* semantic */
}
.button { background: var(--color-action-primary); }

다크모드 → --color-action-primary 한 줄 변경. *재브랜딩 → primitive 한 줄 변경. 디자인 결정이 코드에서도 한 군데에 산다.

How — 토큰의 3계층 구조

1) Primitive Tokens (원시 토큰)

“무엇” 을 표현한다. 값을 갖는 가장 작은 단위.

:root {
  /* color palette */
  --blue-50:  #eff6ff;
  --blue-500: #2563eb;
  --blue-900: #1e3a8a;
  --gray-50:  #f9fafb;
  --gray-900: #111827;
 
  /* spacing scale */
  --space-1: 4px;
  --space-2: 8px;
  --space-3: 12px;
  --space-4: 16px;
 
  /* typography */
  --font-sans: ui-sans-serif, system-ui, sans-serif;
  --font-size-sm: 14px;
}

원칙:

• 이름은 값 자체를 묘사한다. blue-500(O), primary(X — 의미는 다음 층의 일).
• 디자이너의 컬러 팔레트와 1:1 매핑된다.
• 변경 빈도가 매우 낮다. 변경은 보통 리브랜딩급 이벤트.

2) Semantic Tokens (의미 토큰)

“어디에 쓰는지” 를 표현한다. primitive를 역할에 묶는다.

:root {
  --color-action-primary:   var(--blue-500);
  --color-action-primary-h: var(--blue-600);   /* hover */
  --color-text-default:     var(--gray-900);
  --color-text-muted:       var(--gray-500);
  --color-surface-default:  white;
  --color-surface-elevated: var(--gray-50);
  --color-border-subtle:    var(--gray-200);
 
  --space-stack-tight:  var(--space-2);
  --space-stack-cozy:   var(--space-4);
  --space-inline-icon:  var(--space-2);
}

원칙:

• 이름은 의도를 묘사한다 — action-primary, surface-elevated, text-muted.
• 컴포넌트가 무엇인지 모른다. 버튼·링크·태그가 같은 --color-action-primary를 공유한다.
• 다크모드의 핵심 층이다 — 여기서만 값을 바꿔 끼우면 된다.

:root[data-theme="dark"] {
  --color-text-default:    var(--gray-100);
  --color-surface-default: var(--gray-900);
  --color-action-primary:  var(--blue-400); /* 어두운 배경에선 더 밝게 */
}

3) Component Tokens (컴포넌트 토큰) — 선택적

“어느 부품인지” 를 표현한다. semantic을 컴포넌트에 묶는다.

:root {
  --button-bg:           var(--color-action-primary);
  --button-bg-hover:     var(--color-action-primary-h);
  --button-text:         white;
  --button-padding-y:    var(--space-3);
  --button-padding-x:    var(--space-4);
  --button-radius:       var(--radius-md);
}
 
.button {
  background: var(--button-bg);
  color:      var(--button-text);
  padding:    var(--button-padding-y) var(--button-padding-x);
}
.button:hover { background: var(--button-bg-hover); }

원칙:

• 해당 컴포넌트 안에서만 쓰인다.
• 디자이너가 “버튼만 좀 더 진하게”라고 할 때, 다른 컴포넌트를 건드리지 않고 바꿀 수 있는 마지막 안전판.
• 단점: 토큰 수 폭증. 작은 시스템은 2계층(primitive + semantic)으로 충분.

What — W3C Design Tokens Format (DTCG)

2024년 활성화된 W3C Design Tokens Community Group의 JSON 포맷. Figma·Tokens Studio·Style Dictionary·Specify 등이 이 포맷을 채택 중.

최소 예시 (Working Draft 기준)

{
  "color": {
    "blue": {
      "500": {
        "$value": "#2563eb",
        "$type": "color"
      }
    },
    "action": {
      "primary": {
        "$value": "{color.blue.500}",
        "$type": "color",
        "$description": "기본 CTA 색상"
      }
    }
  },
  "space": {
    "4": {
      "$value": "16px",
      "$type": "dimension"
    }
  }
}

핵심 규약:

• $value: 실제 값.
• $type: color · dimension · fontFamily · fontWeight · duration · cubicBezier · number · shadow · gradient · typography 등.
• {path.to.token}: 다른 토큰 참조 — alias.
• $description: 디자이너·개발자용 메모.
• $extensions: 도구별 확장 (com.figma.* 등).

빌드 파이프라인

Style Dictionary 출력 예시

tokens.json 한 파일 → 플랫폼별 출력 자동 생성:

/* output: tokens.css */
:root {
  --color-blue-500: #2563eb;
  --color-action-primary: var(--color-blue-500);
  --space-4: 16px;
}

// output: Tokens.swift
public enum DesignTokens {
  public static let colorBlue500 = UIColor(hex: 0x2563eb)
  public static let colorActionPrimary = colorBlue500
}

What — 실전 토큰 카탈로그

성숙한 디자인 시스템이 다루는 토큰 카테고리:

Material Design Tokens는 위 카테고리에 elevation(고도)과 state(focus/pressed/disabled)를 추가한다.

What-if — 토큰이 잘못 설계되면

1) Primitive만 쓰고 Semantic 생략

.button { background: var(--blue-500); }

다크모드에서 모든 컴포넌트의 --blue-500 사용처를 일일이 분기해야 한다. Semantic 층이 다크모드의 분리 지점인데, 이 층이 없으면 분리 불가능.

2) Component 토큰을 너무 일찍 만든다

작은 팀에서 --button-bg, --link-color, --tag-bg, --badge-bg를 다 만들면 → 토큰 1000개. 유지보수가 오히려 더 어려워진다. 작은 시스템은 semantic까지만.

3) primitive에 의미 이름을 붙인다

--primary: #2563eb;   /* 안티패턴 */

--primary라는 이름은 의미다. 그런데 값은 원시다. 나중에 “primary를 빨간색으로 바꾸자”가 되면 이름과 값이 따로 논다. primitive는 값을, semantic은 의미를.

4) 토큰 alias 깊이가 4+

--button-bg → --action-primary → --color-brand → --blue-base → --blue-500

5단 alias. 디버깅 시 5번 점프해야 값에 도달. 권장: 최대 3단(primitive → semantic → component).

5) Figma 변수와 코드 토큰이 수동 동기화

디자이너가 Figma에서 색을 바꿔도 코드에 자동 반영되지 않으면 → 결국 드리프트. Tokens Studio 같은 도구로 자동 export 필수.

What-if — @property로 토큰에 타입을 준다

CSS Custom Properties는 기본적으로 모두 문자열이다. @property로 등록하면 타입·기본값·상속 여부를 선언할 수 있다.

@property --color-action-primary {
  syntax: '<color>';
  inherits: true;
  initial-value: #2563eb;
}

장점:

• 잘못된 값(--color-action-primary: 42) 무시.
• transition: --color-action-primary 200ms 가능 (문자열이 아니라 컬러임을 알기 때문).
• DevTools에서 타입 정보 표시.

2024년부터 모든 모던 브라우저 지원. 토큰 시스템에 점진 도입 가능.

Insight — 토큰은 언어의 진화다

CSS가 문서 스타일에서 디자인 시스템 언어로 진화한 결정적 순간이 디자인 토큰의 등장이다.

2014년 Jina Anne가 Salesforce에서 Design Tokens 라는 용어를 처음 만들고 Lightning Design System에 적용했다. 당시는 Sass 변수를 JSON으로 export하는 빌드 스크립트 정도였다.

2016년 Amazon Style Dictionary 오픈소스, 2018년 Adobe Spectrum, 2019년 Material Design Tokens — 큰 회사들이 같은 패턴을 재발명했다.

2021년 W3C Design Tokens Community Group(DTCG) 설립. Figma·Adobe·Microsoft·Salesforce·Google이 한 자리에 모여 JSON 포맷을 표준화하기 시작.

2023년 Figma가 Variables 기능을 출시, 디자인 도구가 처음으로 토큰을 네이티브 1급 시민으로 다루기 시작.

2024년 DTCG Format Module Draft Working Draft가 프로덕션 사용에 충분히 안정화. Tokens Studio, Specify, Knapsack 같은 토큰 관리 SaaS가 폭발적으로 늘어남.

왜 이게 중요한가? — 이전까지 디자이너의 결정과 개발자의 코드 사이에는 항상 수동 번역 단계가 있었다. 디자이너가 “이 색을 좀 더 진하게”라고 말하면, 개발자가 어디 어디에 쓰이는지를 찾아서 손으로 바꿨다. 토큰은 그 번역을 자동화한다. 디자이너의 변경이 코드에 자동으로 전파된다.

Brad Frost는 “Tokens are the contract between design and engineering” 이라고 했다. 토큰은 두 직군 사이의 계약이다 — 디자이너는 토큰 안에서 결정하고, 개발자는 토큰 밖으로 나가지 않는다.

토큰은 단순한 변수가 아니라 조직의 디자인 의사결정 인프라다.

요약 + Mermaid

• 토큰은 primitive → semantic → component의 3계층 (작은 시스템은 2계층까지).
• primitive는 무엇, semantic은 어디에, component는 어느 부품에.
• W3C DTCG가 JSON 포맷을 표준화 중 ($value·$type·{alias}).
• Style Dictionary로 한 소스 → N 플랫폼 출력.
• @property로 토큰에 타입을 줄 수 있다.
• 다크모드의 핵심은 semantic 층의 재매핑에 있다.

다음: 02-methodologies — 토큰을 컴포넌트에 분배하는 5개 메서드론(BEM·OOCSS·SMACSS·ITCSS·ECSS).