- 일관성 — 같은 의미의 값은 항상 같은 토큰을 사용합니다.
- 유지보수 — 전역 간격·색상은 _tokens.scss · _themes.scss에서, 컴포넌트 전용 값은 해당 컴포넌트 SCSS에서 관리합니다.
- 테마 — 색상 토큰을 테마별로 교체해 라이트/다크를 지원합니다.
- 협업 — 디자이너·개발자가 --space-md 같은 공통 언어로 소통합니다.
디자인 토큰
색상·간격·타이포그래피 등 디자인 시스템의 기준 값을 CSS 변수로 관리합니다. UXKM 디자인 토큰과 기본 스타일 을 참고해, 이 가이드에서는 :root CSS 변수와 라이트/다크 테마 구조로 제공합니다.
디자인 토큰이란?
디자인 시스템에서 반복되는 값을 의미 있는 이름으로 정의한 것입니다. 컴포넌트·페이지 스타일은 하드코딩 대신 토큰을 참조해 일관성을 유지하고, 변경 시 한 곳만 수정하면 전체에 반영됩니다.
토큰 파일 구조
main.scss에서 tokens → themes → base/components 순으로 불러옵니다. 런타임에 바뀌는 값은 CSS 변수로, 브레이크포인트·폰트 스택처럼 컴파일 시 필요한 값은 SCSS 변수로 관리합니다.
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 | 본문·버튼 기본값 (별도 유틸리티 클래스 없음) |
--text-size-lg | 1rem | 강조 본문, 모달 제목, .size_lg |
--text-size-xl | 1.125rem | 리드 문단, 큰 라벨, .size_xl |
제목·본문 변형(--typo-title-*, --typo-text-*)은 Typography 컴포넌트 문서를 참고하세요.
Motion · Interaction · Layout 토큰
Motion
| 토큰 | 기본값 | 사용 |
|---|---|---|
--transition-fast | 0.15s ease | 호버·포커스 색상 전환 |
--transition-base | 0.2s ease | 패널·드로어 열림, 레이아웃 변화 |
Interaction
| 토큰 | 기본값 | 사용 |
|---|---|---|
--ripple-color | currentColor | 클릭 파장 색상 |
--ripple-opacity | 0.18 | 클릭 파장 불투명도 |
--ripple-duration | 550ms | 클릭 파장 지속 시간 |
--ripple-easing | cubic-bezier(0, 0, 0.2, 1) | 클릭 파장 가속도 |
--focus-outline-width | 2px | 키보드 포커스 링 두께 |
--focus-outline-offset | 2px | 포커스 링과 요소 사이 간격 |
--focus-shadow-width | 3px | 그림자형 포커스 링 너비 |
Layout
| 토큰 | 기본값 | 사용 |
|---|---|---|
--sidebar-width | 280px | 가이드 사이드바 너비 |
--header-height | 56px | 헤더·네비바 높이 |
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 | 비활성 컨트롤 | 스위치·슬라이더 트랙 등 |
--color-header-bg | 반투명 헤더 배경 | 고정 가이드 헤더 |
--color-overlay | 오버레이 배경 | 모달·드로어 뒤 딤드 영역 |
--shadow-sm | 낮은 표면 그림자 | 카드, 툴팁, 캘린더 |
--shadow-md | 높은 표면 그림자 | 강조 패널, 떠 있는 콘텐츠 |
Semantic
| 토큰 | 역할 | 사용 |
|---|---|---|
--color-accent | Primary · 채움 | .color_primary 채움 버튼, 활성 탭 |
--color-accent-hover | Primary · 채움 호버 | 채움 버튼 호버·활성 상태 |
--color-accent-text | Primary · 텍스트 | 링크, 고스트 버튼, 강조 텍스트 |
--color-accent-text-hover | Primary · 텍스트 호버 | 링크·텍스트 버튼 호버 |
--color-accent-muted | Primary · 약한 배경 | 배지, 선택 영역, 강조 배경 |
--color-on-accent | Primary · 채움 위 텍스트 | filled primary 버튼 레이블 |
--color-success | Success · 채움 | .color_success 채움, 성공 상태 |
--color-success-hover | Success · 채움 호버 | 성공 버튼 호버·활성 상태 |
--color-success-text | Success · 텍스트 | 성공 메시지, 체크 아이콘 |
--color-success-text-hover | Success · 텍스트 호버 | 성공 링크·텍스트 버튼 호버 |
--color-danger | Danger · 채움 | .color_danger 삭제·오류 강조 |
--color-danger-hover | Danger · 채움 호버 | 위험 버튼 호버·활성 상태 |
--color-danger-text | Danger · 텍스트 | 오류 메시지, 위험 링크 |
--color-danger-text-hover | Danger · 텍스트 호버 | 위험 링크·텍스트 버튼 호버 |
--color-warning | Warning · 채움 | .color_warning 경고 배지·버튼 |
--color-warning-hover | Warning · 채움 호버 | 경고 버튼 호버·활성 상태 |
--color-warning-text | Warning · 텍스트 | 경고 설명, 주의 문구 |
--color-warning-text-hover | Warning · 텍스트 호버 | 경고 링크·텍스트 버튼 호버 |
--color-on-warning | Warning · 채움 위 텍스트 | filled 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 레이블 |
테마 적용 방법은 설치 및 사용 · 테마를 참고하세요.
토큰 사용 방법
CSS 변수는 SCSS·CSS·HTML에서 var()로 참조합니다. 컴포넌트 범위에서 변수를 재정의하면 해당 요소와 하위 요소에만 적용됩니다. SCSS에서는 mixins의 color-token() 같은 헬퍼도 사용할 수 있습니다.
SCSS
// 컴포넌트 SCSS에서 토큰과 헬퍼 참조
@use "../mixins" as *;
.card {
padding: var(--space-lg);
border-radius: var(--radius-lg);
background: var(--color-surface);
border: 1px solid var(--color-border-subtle);
color: color-token(default);
font-size: var(--text-size-sm);
transition: box-shadow var(--transition-fast);
}CSS · 범위 재정의
/* HTML·인라인 스타일 */
<section style="display: grid; 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 — 각 표에는 기본값과 설명(사용) 열이 함께 제공됩니다.