디자인 토큰

디자인 토큰

색상·간격·타이포그래피 등 디자인 시스템의 기준 값을 CSS 변수로 관리합니다. UXKM 디자인 토큰과 기본 스타일을 참고해, 이 가이드에서는 :root CSS 변수와 라이트/다크 테마 구조로 제공합니다.

디자인 토큰이란?

디자인 시스템에서 반복되는 값을 의미 있는 이름으로 정의한 것입니다. 컴포넌트·페이지 스타일은 하드코딩 대신 토큰을 참조해 일관성을 유지하고, 변경 시 한 곳만 수정하면 전체에 반영됩니다.

  • 일관성 — 같은 의미의 값은 항상 같은 토큰을 사용합니다.
  • 유지보수 — 간격·색상 변경 시 _tokens.scss · _themes.scss만 수정합니다.
  • 테마 — 색상 토큰을 테마별로 교체해 라이트/다크를 지원합니다.
  • 협업 — 디자이너·개발자가 --space-md 같은 공통 언어로 소통합니다.

토큰 파일 구조

UXKM SCSS 실무 예제와 같이 tokens → themes → base/components 순으로 의존성을 쌓습니다. 이 가이드는 SCSS 변수와 CSS 변수를 함께 씁니다.

src/scss/
├── _tokens.scss      # :root CSS 변수 — 간격·타이포·컴포넌트 수치
├── _themes.scss      # 라이트/다크 색상 (data-theme)
├── _variables.scss   # SCSS 전용 — 브레이크포인트·폰트 스택
├── _mixins.scss      # color-token() 등 토큰 헬퍼
├── components/       # 컴포넌트별 스타일 (토큰 참조)
└── main.scss         # tokens → themes → … 순서로 @use

전역 수치 토큰은 _tokens.scss의 :root에 정의하고, 색상은 _themes.scss에서 data-theme별로 덮어씁니다. 미디어쿼리용 브레이크포인트 등 컴파일 타임 값만 _variables.scss에 둡니다.

Spacing 토큰

마진·패딩·gap 등 모든 간격의 기준입니다. rem 단위로 정의해 사용자 글꼴 크기 설정을 존중합니다.

토큰 기본값 사용
--space-xs 0.25rem 아이콘·배지 간 최소 간격, .space_gap-xs
--space-sm 0.5rem 버튼 내부 gap, .ml_sm · .p_sm · .space_gap-sm
--space-md 1rem 폼·카드 패딩, 그리드 gap, 기본 간격
--space-lg 1.5rem 섹션·모달 패딩, 폼 필드 간격
--space-xl 2rem 컨테이너 좌우 패딩, 빈 상태 여백
--space-2xl 3rem 페이지 섹션 상하 여백

Radius 토큰

토큰 기본값 사용
--radius-sm 6px 입력 필드, 페이지네이션, 스켈레톤
--radius-md 10px 코드 블록, 프리 영역
--radius-lg 12px 카드, 모달, 캐러셀
--radius-pill 9999px 배지, 태그, 스위치, 프로그레스

Typography 토큰

토큰 기본값 사용
--text-size-xs 0.75rem 캡션, 배지, 툴팁, .size_xs
--text-size-sm 0.8125rem 보조 텍스트, 메뉴, 탭, .size_sm
--text-size-base 0.875rem 본문·버튼 기본, .size_base
--text-size-lg 1rem 강조 본문, 모달 제목, .size_lg
--text-size-xl 1.125rem 리드 문단, 큰 라벨, .size_xl

제목·본문 변형(--typo-title-*, --typo-text-*)은 Typography 컴포넌트 문서를 참고하세요.

Motion · Layout 토큰

토큰 기본값 사용
--transition-fast 0.15s ease 호버·포커스 색상 전환
--transition-base 0.2s ease 패널·드로어 열림, 레이아웃 변화
--sidebar-width 280px 가이드 사이드바 너비
--header-height 56px 헤더·네비바 높이
--focus-outline-width 2px 키보드 포커스 링 두께
--focus-outline-offset 2px 포커스 링과 요소 사이 간격

Color 토큰

UXKM Color Tokens처럼 Surface(배경·테두리·텍스트)와 Semantic(Primary·Success·Danger·Warning)으로 구분합니다. 실제 hex 값은 테마에 따라 달라집니다.

Surface

토큰 역할 사용
--color-bg 페이지 배경 body, 가이드 레이아웃 배경
--color-surface 카드·패널 배경 카드, 모달, 입력 필드 배경
--color-surface-raised 들어 올린 표면 헤더 영역, 호버 배경, 스켈레톤
--color-border 기본 테두리 입력·버튼 outline, 구분선
--color-border-subtle 보조 테두리 카드·디바이더, 약한 구분
--color-text 본문 텍스트 제목·본문 기본 색
--color-text-muted 보조 텍스트 설명, 메타, placeholder 톤
--color-text-disabled 비활성 텍스트 disabled · is-disabled 레이블·본문 (4.5:1)
--color-border-disabled 비활성 테두리 비활성 입력·버튼·컨트롤 테두리 (3:1)
--color-surface-disabled 비활성 배경 비활성 입력·카드·드롭존 배경
--color-control-disabled 비활성 컨트롤 스위치·슬라이더 트랙 등

Semantic

토큰 역할 사용
--color-accent Primary · 채움 .color_primary 채움 버튼, 활성 탭
--color-accent-text Primary · 텍스트 링크, 고스트 버튼, 강조 텍스트
--color-on-accent Primary · 채움 위 텍스트 filled primary 버튼 레이블
--color-success Success · 채움 .color_success 채움, 성공 상태
--color-success-text Success · 텍스트 성공 메시지, 체크 아이콘
--color-danger Danger · 채움 .color_danger 삭제·오류 강조
--color-danger-text Danger · 텍스트 오류 메시지, 위험 링크
--color-warning Warning · 채움 .color_warning 경고 배지·버튼
--color-warning-text Warning · 텍스트 경고 설명, 주의 문구
--color-accent-disabled Primary · 비활성 채움 filled primary · 체크박스 비활성 선택 배경
--color-on-accent-disabled Primary · 비활성 채움 위 텍스트 비활성 filled primary 레이블·체크
--color-success-disabled Success · 비활성 채움 filled success 비활성 배경
--color-on-success-disabled Success · 비활성 채움 위 텍스트 비활성 success 레이블
--color-danger-disabled Danger · 비활성 채움 filled danger 비활성 배경
--color-on-danger-disabled Danger · 비활성 채움 위 텍스트 비활성 danger 레이블
--color-warning-disabled Warning · 비활성 채움 filled warning 비활성 배경
--color-on-warning-disabled Warning · 비활성 채움 위 텍스트 비활성 warning 레이블

테마 적용 방법은 설치 및 사용 · 테마를 참고하세요.

토큰 사용 방법

SCSS·CSS·HTML 어디서든 var()로 참조합니다. 컴포넌트 범위에서 CSS 변수를 재정의하면 해당 블록만 스케일을 바꿀 수 있습니다.

SCSS

// 컴포넌트 SCSS에서 토큰 참조
@use "../variables" as *;

.card {
  padding: var(--space-lg);
  border-radius: var(--radius-lg);
  background: var(--color-surface);
  border: 1px solid var(--color-border-subtle);
  font-size: var(--text-size-sm);
  transition: box-shadow var(--transition-fast);
}

CSS · 범위 재정의

/* HTML·인라인 스타일 */
<section style="padding: var(--space-xl); gap: var(--space-md);">
  …
</section>

/* 컴포넌트 범위에서 토큰 재정의 */
.my-panel {
  --icon-size: 1.5rem;
  --btn-padding-y: 0.75rem;
}

테마

<!-- 테마 전환 — 색상 토큰이 함께 바뀝니다 -->
<html lang="ko" data-theme="light">
<html lang="ko" data-theme="dark">

/* _themes.scss — 의미별 색상만 테마별로 정의 */
[data-theme="light"] { --color-accent: #3d66c4; }
[data-theme="dark"]  { --color-accent: #386bc0; }

컴포넌트 토큰

버튼·아이콘·입력 등 컴포넌트 전용 토큰(--btn-*, --icon-*, --input-* 등)은 각 컴포넌트 문서 하단의 「디자인 토큰」 표에서 기본값과 사용처를 확인할 수 있습니다.

예: Icon 문서의 --icon-size, Button의 --btn-padding-y — 각 표에는 기본값과 설명(사용) 열이 함께 제공됩니다.