디자인 토큰

색상·간격·타이포그래피 등 디자인 시스템의 기준 값을 CSS 변수로 관리합니다.UXKM 디자인 토큰과 기본 스타일을 참고해, 이 가이드에서는 :rootCSS 변수와 라이트/다크 테마 구조로 제공합니다. Next.js 앱은app/layout.jsx에서 src/scss/main.scss를 import해 동일한 토큰을 사용합니다.

디자인 토큰이란?

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

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

토큰 파일 구조

UXKM 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	본문·버튼 기본, .size_base
`--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	포커스 shadow 링 두께

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-danger`	Danger · 채움	.color_danger 삭제·오류 강조
`--color-danger-hover`	Danger · 호버 채움	위험 버튼 호버 상태
`--color-danger-text`	Danger · 텍스트	오류 메시지, 위험 링크
`--color-warning`	Warning · 채움	.color_warning 경고 배지·버튼
`--color-warning-hover`	Warning · 호버 채움	경고 버튼 호버 상태
`--color-warning-text`	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 레이블

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

토큰 사용 방법

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

SCSS

// 컴포넌트 SCSS에서 토큰 참조
.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">

/* _themes.scss — data-theme에 따라 의미 색상을 교체 */
[data-theme="light"] { --color-accent: #3d66c4; }
[data-theme="dark"]  { --color-accent: #386bc0; }

// React — src/hooks/useTheme.js
const { theme, toggleTheme } = useTheme();
document.documentElement.setAttribute('data-theme', theme);

초기 테마는 app/layout.jsx에서 라이트로 지정하며, useThemehook이 저장된 사용자 선택을 읽어<html data-theme>속성을 갱신합니다.

컴포넌트 토큰

전역 토큰을 조합해 버튼·아이콘·입력 등 개별 컴포넌트의 크기와 간격을 제어하는 CSS 변수입니다. --btn-*, --icon-*, --input-*처럼 컴포넌트 접두사를 사용해 전역 토큰과 구분합니다.

정의 위치— src/scss/components/_*.scss의 :root에 컴포넌트별 기본값을 정의합니다.
재정의— 페이지 또는 특정 래퍼에서 필요한 토큰만 다시 선언하면 해당 범위의 컴포넌트에 적용됩니다.
문서 확인— 각 컴포넌트 문서의 디자인 토큰 표에서 토큰명·기본값·설명을 제공합니다. 예시는 Button과 Icon을 참고하세요.