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 기본 단계를 만들어 줘요.