CSS·Tailwind 색상 토큰 정리하는 법 — 변수 이름 짓기
· 3분 분량
색상 변수를 역할별로 이름 짓고 정리하는 법, CSS에서 라이트·다크 모드를 연결하는 법, 같은 토큰을 Tailwind v4 테마에서 쓰는 법을 알려드려요.
스타일시트 곳곳에 하드코딩된 HEX 값은 색을 바꾸기 힘들게 만드는 가장 큰 원인이에요. 리브랜딩, 다크 모드 추가, 대비 문제 수정이 모두 수백 줄에 걸친 찾아 바꾸기가 돼요. 색이 어디에 쓰이는지를 이름으로 붙인 변수, 즉 색상 토큰이 이 문제를 해결해요. 이 가이드에서는 일반 CSS에서 토큰을 구성하는 법과 같은 토큰을 Tailwind에서 쓰는 법을 보여 줘요.
두 층: 기본 토큰과 역할 토큰
탄탄한 구성은 색이 무엇인지와 색을 어떻게 쓰는지를 나눠요.
기본 토큰(primitive)은 색상과 단계로 이름 붙인 날것의 팔레트예요. 컴포넌트 스타일에는 절대 직접 나오지 않아요.
:root {
--blue-100: #E3E8FF;
--blue-500: #3D5AFE;
--blue-700: #2638C4;
--sand-50: #F7F5F0;
--ink-900: #1D2433;
}시맨틱(역할) 토큰은 인터페이스에서 맡은 일을 나타내고, 기본 토큰을 가리키거나 자기 값을 직접 가져요. 컴포넌트는 오직 이 토큰만 써요.
:root {
--color-bg: var(--sand-50);
--color-surface: #EFECE4;
--color-border: #DAD6CC;
--color-text: var(--ink-900);
--color-muted: #5C6475;
--color-primary: var(--blue-500);
--color-on-primary: #FFFFFF;
--color-accent: #C2410C;
}.button {
background: var(--color-primary);
color: var(--color-on-primary);
}
.card {
background: var(--color-surface);
border: 1px solid var(--color-border);
color: var(--color-text);
}이제 버튼은 자기가 파랗다는 걸 몰라요. 브랜드 색이 초록으로 바뀌면 한 줄만 고치면 돼요. 대비 검사에서 걸리면 토큰 하나만 조정하면 모든 컴포넌트가 따라와요.
토큰 이름은 생김새가 아니라 역할로
--light-gray나 --brand-blue 같은 이름은 지금 그 색이 어떻게 보이는지를 말해요. 값이 바뀌는 순간 틀린 이름이 되고, 다크 모드에서는 --light-gray에 어두운 색이 들어가게 돼요. 역할 이름은 계속 맞는 말로 남아요.
- 구조:
--color-bg,--color-surface,--color-border. - 콘텐츠:
--color-text와--color-muted. - 강조:
--color-primary,--color-accent. - 면을 채운 색 위의 글자:
--color-on-primary,--color-on-accent. - 필요하면 상태 역할:
--color-success,--color-warning,--color-danger.
목록은 짧게 유지하세요. 역할 토큰 열두 개 정도면 대부분의 제품을 감당해요. 컴포넌트마다 토큰을 만들면 처음 문제로 되돌아가요.
다크 모드는 새 값의 묶음이 돼요
역할 토큰을 쓰면 다크 모드는 두 번째 스타일시트가 아니에요. 같은 이름에 다른 값을 넣을 뿐이에요. 아래 방식은 시스템 설정을 따르면서도 토글로 data-theme 속성을 붙여 어느 테마든 강제할 수 있게 해요.
@media (prefers-color-scheme: dark) {
:root:not([data-theme="light"]) {
--color-bg: #14161F;
--color-surface: #1C1F2B;
--color-border: #2C3040;
--color-text: #E6E8EF;
--color-muted: #9AA1B2;
--color-primary: #8C9EFF;
--color-on-primary: #14161F;
--color-accent: #FB923C;
}
}
:root[data-theme="dark"] {
/* 같은 값 (다크를 직접 고른 사람용) */
}다크 모드의 주조색은 더 밝은 파랑이고 그 위 글자는 어둡다는 점을 보세요. 다크 값은 뒤집어서 계산하지 말고 직접 골라야 해요. 이유는다크 모드 가이드에서 설명해요.
요즘 브라우저는 두 값을 한 줄에 담는 light-dark() 함수도 지원해요. 이 함수는 color-scheme 속성을 따르므로 그 선언이 있어야 동작해요.
:root {
color-scheme: light dark;
--color-bg: light-dark(#F7F5F0, #14161F);
--color-text: light-dark(#1D2433, #E6E8EF);
}차분한 색은 섞어서 만들기
서피스와 테두리는 손으로 고르는 대신 배경과 텍스트 색을 섞어 만들 수 있어요. CSS에서는 color-mix()가 이 일을 하고, OKLCH로 섞으면 고르고 자연스러운 단계가 나와요.
:root {
--color-surface: color-mix(in oklch, var(--color-bg) 94%, var(--color-text));
--color-border: color-mix(in oklch, var(--color-bg) 82%, var(--color-text));
}다른 토큰을 참조하므로 다크 모드에서도 저절로 바뀌어요. 입력란 같은 컨트롤을 표시하는 테두리라면 3:1을 넘는지 확인하세요.
Tailwind CSS v4에서 토큰 쓰기
Tailwind v4는 CSS에서 설정해요. @theme에 선언한 --color-* 변수는 모두 유틸리티 한 벌(bg-*,text-*, border-* 등)이 돼요. 만들어진 유틸리티는 실행 시점에 변수를 읽어요. bg-primary는background-color: var(--color-primary)가 되죠. 그래서 다크 모드에서는 변수만 덮어쓰면 충분해요.
@import "tailwindcss";
/* 라이트 값이 유틸리티가 된다: bg-bg, text-text, bg-primary ... */
@theme {
--color-bg: #F7F5F0;
--color-surface: #EFECE4;
--color-text: #1D2433;
--color-muted: #5C6475;
--color-primary: #3D5AFE;
--color-on-primary: #FFFFFF;
--color-accent: #C2410C;
}
/* 다크 값은 같은 변수를 덮어쓴다 */
@media (prefers-color-scheme: dark) {
:root {
--color-bg: #14161F;
--color-text: #E6E8EF;
--color-primary: #8C9EFF;
--color-on-primary: #14161F;
/* ... */
}
}<button class="bg-primary text-on-primary">Save</button>
<p class="text-muted">Last edited 2 hours ago</p>요소마다 dark: 변형을 붙일 필요가 없어요. 토큰이 이미 바뀌니까 bg-primary는 두 테마 모두에서 맞는 색이에요.
Tailwind v3
v3에서는 같은 변수를 설정 파일에 연결해요.
// tailwind.config.js
module.exports = {
theme: {
extend: {
colors: {
bg: 'var(--color-bg)',
surface: 'var(--color-surface)',
text: 'var(--color-text)',
primary: 'var(--color-primary)',
accent: 'var(--color-accent)',
},
},
},
}OKLCH로 값 쓰기
색을 저장하는 데는 HEX도 괜찮지만, 값을 고칠 때는 OKLCH가 훨씬 다루기 쉬워요. 세 채널은 명도, 채도(chroma), 색상이고, 명도가 눈에 보이는 밝기와 잘 맞아요. 브랜드 색을 글자용으로 더 어둡게 만들려면 L만 낮추고 나머지는 그대로 두면 돼요.oklch(55% 0.2 265)가 oklch(42% 0.2 265)가 되는 식이에요. 현재 주요 브라우저는 모두 oklch()를 지원해요.
직접 타이핑할 필요 없이
Colorset의 모든 팔레트는 바로 이 구조로 내보낼 수 있어요. 라이트·다크 모드 역할 토큰을 담은 CSS 변수, Tailwind v4 테마, Tailwind v3 설정, SCSS, JSON, 디자인 토큰을 HEX, RGB, HSL, OKLCH 중 원하는 값으로요. 마음에 드는 배색을 골라 내보내기를 열고 붙여 넣으세요. 기본 토큰 층을 직접 만들고 싶다면 단계 색상 생성기가 어떤 색으로든 50–950 기본 단계를 만들어 줘요.