정교한 디자인 토큰 설계하기

CSS 변수만으로는 한계가 있어요

”이 버튼 색상을 primary로 바꿔주세요”라는 디자이너의 요청에 당황한 적 있나요? CSS 파일을 뒤져보니 --blue-500, --primary-blue, --main-color 같은 비슷한 이름들만 가득하고, 정작 어떤 걸 써야 할지 모르겠어요.

:root {
  --blue-500: #3b82f6;
  --primary-blue: #2563eb; 
  --main-color: #1d4ed8;
  --accent: #3b82f6; /* 어? 이건 blue-500과 같은 값이네? */
}

프로젝트가 커질수록 이런 문제가 심해져요. 체계적인 디자인 토큰 네이밍으로 이 혼란을 해결할 수 있어요.

디자인 토큰이 뭔가요?

디자인 토큰은 colors, spacing, typography, scale 같은 디자인 시스템을 구성하는 가장 작은 단위예요. 쉽게 말해서 “디자인의 레고 블록”이라고 생각하시면 돼요.

왜 토큰을 써야 할까요?

잘 만들어진 토큰 이름은 디자이너와 개발자 사이의 소통을 원활하게 해줘요. 그리고 프로젝트가 커져도 일관성을 유지할 수 있고요.

토큰은 어떻게 진화할까요?

가장 간단한 토큰부터 시작해서 점진적으로 의미 있는 토큰으로 발전시켜 보아요.

보시는 것처럼 토큰이 점점 더 구체적이고 의미 있게 변해가죠?

처음엔 단순히 blue-500이었던 것이 마지막엔 color-action-primary-hover가 되었어요. 이제 개발자가 “버튼에 마우스를 올렸을 때 primary 색상”이 필요하다면 바로 어떤 토큰을 써야 할지 알 수 있어요.

하지만 이렇게 복잡한 토큰을 만들려면 체계적인 규칙이 필요해요. 그래서 4단계 레벨 시스템을 사용하는 거예요.

토큰 이름은 4가지 레벨로 구성돼요:

• NameSpace: 프로젝트나 팀 이름으로 다른 라이브러리와 구분해요
• Object: 특정 컴포넌트(button, input 등)에서만 사용할 때 지정해요
• Base: 가장 기본이 되는 카테고리와 속성이에요 ⭐
• Modifier: 구체적인 용도나 상태를 나타내요

이제 각 레벨을 어떻게 활용하는지 차근차근 알아볼까요?

// 흰 배경 색상
$color-background: #fff;
// 큰 텍스트
$typography-xl: 2rem;
// 빨간 알림 배경 색상
$color-feedback-background: #fb3b1e;

// 피드백 색상 그룹
$color-feedback-success: #10b981;
$color-feedback-error: #ef4444;
// 액션 색상 그룹  
$color-action-primary: #3b82f6;
$color-action-secondary: #6b7280;

// 제목 크기
$typography-heading-xxl: 3rem;
// 부제목 크기
$typography-heading-l: 2rem;

html {
  --size-action-height-coarse: 32px;
 
  @media (pointer: coarse) {
    --size-action-height-coarse: 48px;
  }
}
 
button {
  min-height: var(--size-action-height-coarse);
}

// Input 컴포넌트 전용 토큰
$input-color-border-default: #d1d5db;
$input-color-border-error: #ef4444;
$input-color-border-success: #10b981;

$input-prefix-icon-size: 1rem;
$input-inline-link-color-text: #3b82f6;

// 로컬 토큰 (처음)
$input-color-border-error: #ef4444;
 
// 전역 토큰 (재사용 확실해진 후)
$forms-color-border-error: #ef4444;

$lds-orange-color-action-primary: #f97316;
$lds-dark-color-background-primary: #1f2937;
$lds-light-color-text-primary: #111827;

네이밍 규칙 정리

지금까지 배운 4단계 레벨을 조합하면 이런 순서로 토큰을 만들 수 있어요:

NameSpace-Object-Base-Modifier

실제 예시:

• lds-button-color-background-hover (모든 레벨 포함)
• color-action-primary (NameSpace, Object 생략)
• button-spacing-padding-x (NameSpace 생략)

실무에서 유용한 팁들

다크모드 대응

CSS 변수를 활용하면 테마별 토큰을 깔끔하게 관리할 수 있어요:

:root {
  --color-background-primary: #ffffff;
  --color-text-primary: #1f2937;
}
 
[data-theme="dark"] {
  --color-background-primary: #1f2937;
  --color-text-primary: #f9fafb;
}

자동화로 편리하게

NameSpace를 매번 입력하기 귀찮다면 빌드 시간에 자동으로 추가하세요:

// 개발 시
$color-primary: $blue-500;
 
// 빌드 후
$myapp-color-primary:$blue-500;

컴포넌트 라이브러리 연동

React나 Vue 컴포넌트와 토큰을 연결할 때:

// Button 컴포넌트 전용 토큰
--button-color-background-primary: var(--color-action-primary);
--button-color-background-primary-hover: var(--color-action-primary-hover);
--button-spacing-padding-x: var(--spacing-medium);
--button-spacing-padding-y: var(--spacing-small);

Class Variance Authority로 더 쉽게

Class Variance Authority (CVA)를 사용해도 토큰 기반의 컴포넌트 variant를 체계적으로 관리할 수 있어요:

import { cva } from 'class-variance-authority';
 
const buttonVariants = cva(
  // 기본 토큰들
  'bd-inline-flex bd-items-center bd-justify-center bd-rounded-md',
  {
    variants: { 
      variant: { 
        primary: 'bd-bg-primary bd-text-primary-foreground', 
        secondary: 'bd-bg-secondary bd-text-secondary-foreground', 
        outline: 'bd-border bd-border-input bd-bg-background', 
      }, 
      size: { 
        sm: 'bd-h-9 bd-px-3', 
        md: 'bd-h-10 bd-px-4', 
        lg: 'bd-h-11 bd-px-8', 
      }, 
    }, 
    defaultVariants: { 
      variant: 'primary', 
      size: 'md', 
    }, 
  }
);
 
// 사용 시
<Button variant="outline" size="lg">...</Button>

이렇게 하면 디자인 토큰의 네이밍 규칙과 컴포넌트 API가 일치해서 개발자 경험이 훨씬 좋아져요!

마치며

디자인 토큰 네이밍이 처음엔 복잡해 보일 수 있지만, 체계적인 규칙을 따르면 일관성 있는 디자인 시스템을 만들 수 있어요.

가장 중요한 건 팀 전체가 같은 규칙을 따르는 거예요. 완벽한 토큰을 처음부터 만들려고 하지 말고, 프로젝트가 성장하면서 점진적으로 개선해 나가세요.

더 알아보기

디자인 토큰에 대해 더 자세히 알고 싶다면:

• 디자인 토큰 커뮤니티 그룹 - 표준 규격과 도구들
• 크로스 플랫폼 디자인 시스템, 1.5년의 기록 - 실무 경험담
• 효과적인 토큰 작성하기 - 네이밍 베스트 프랙티스