Theme 토큰 — semantic vs literal

색에 blue-500 이라 이름 지으면 그게 뭔지 말해줘. brand 라 이름 지으면 그게 뭘 하는지 말해줘. 둘 다 자리 있어. 어떤 게 어디 가는지 아는 게 기술.

Literal 토큰 (빌트인)

Tailwind 가 팔레트 출하: blue-500, slate-900, cyan-400. 이것들은 literal — 특정 hex 값 묘사. One-off 액센트, dev 작업, 스크래치 UI 에 사용.

Semantic 토큰 (본인 것)

Semantic 토큰은 본인이 추가하는 이름: brand, danger, surface, text-muted. 외양 아니라 역할 묘사. 그걸 쓰는 모든 컴포넌트 안 만지고 정확한 색 바꿀 수 있음 (예: brand 색 리브랜드).

2-layer 패턴

대부분의 성숙한 디자인 시스템이 literal 로 정의, semantic 으로 사용:

@theme {
  /* Literal 팔레트 */
  --color-pink-500: #FF8FBE;
  /* Semantic 매핑 */
  --color-brand: var(--color-pink-500);
}

이렇게 하면 --color-brand 를 pink-500 에서 violet-500 으로 한 줄에서 swap 하고 앱 전체의 모든 bg-brand 업데이트.

cwkPippa 팔레트

cwkPippa 의 index.css 가 컴포넌트에서 거의 semantic 토큰만 사용 (bg-bg, text-fg, text-brand) 하고 작은 literal 레이어에서 가져옴. Literal 레이어가 아빠가 새 액센트 색 고를 때 바뀌는 유일한 자리.

좋은 semantic 이름의 조건

역할 기반: danger, success, warning, info 가 red, green, yellow, blue 이김.
Surface 기반: bg, bg-elevated, bg-card 가 gray-950, gray-900, gray-850 이김.
계층 인식: 본문 primary/secondary/tertiary 에 text, text-muted, text-subtle.

이름 짓기가 유연성 사고, 모호가 비용. blue 라 부른 토큰은 semantic 깨지 않고 빨강 못 됨. brand 라 부른 토큰은 어떤 색조든 가능. 의미 안 바꾸고 색 바뀔 수 있는 이름 골라.

Code

v4 문법의 2-layer 토큰 시스템·css

@import "tailwindcss";

@theme {
  /* Layer 1 — literal 팔레트 (디자인 시스템 안정 후 거의 안 만짐) */
  --color-pink-400: #FFA8CE;
  --color-pink-500: #FF8FBE;
  --color-pink-600: #D62E84;
  --color-slate-900: #0d0d12;
  --color-slate-800: #16161e;
  --color-slate-100: #e8e8ee;

  /* Layer 2 — semantic (컴포넌트가 실제 쓰는 것) */
  --color-bg: var(--color-slate-900);
  --color-bg-elevated: var(--color-slate-800);
  --color-fg: var(--color-slate-100);
  --color-brand: var(--color-pink-500);
  --color-brand-strong: var(--color-pink-600);
  --color-danger: #FF6B6B;
  --color-success: #51CF66;
}

[data-theme="light"] {
  /* Light mode 는 semantic 레이어만 swap */
  --color-bg: #ffffff;
  --color-bg-elevated: #fafafd;
  --color-fg: #1a1a1f;
}

컴포넌트는 semantic 토큰만 만짐·tsx

// 다 semantic — brand 색 바뀌어도 이것들 중 어느 것도 안 바뀜.
function Banner() {
  return (
    <div className="bg-bg-elevated text-fg border-l-4 border-brand p-4 rounded">
      <h3 className="font-medium">New message</h3>
      <p className="text-muted text-sm">From: Dad</p>
      <button className="mt-2 px-3 py-1 bg-brand text-bg rounded hover:bg-brand-strong">
        Open
      </button>
    </div>
  );
}

// Literal 만 쓴 경우 비교:
// className="bg-slate-800 text-slate-100 border-l-4 border-pink-500 ..."
// 오늘은 같은 렌더. 내일 brand 색 바뀌면 고통.

Exercise

Literal Tailwind 클래스 (bg-slate-900, text-white 등) 쓴 작은 페이지 (또는 본인 부트스트랩 프로젝트 App.tsx) 가져와. @theme 에 semantic 토큰 다섯 (bg, bg-elevated, fg, muted, brand) 정의. 페이지를 그것들만 쓰게 리팩토링. @theme 에서 literal 색 하나 바꿔서 모든 컴포넌트 업데이트되는지 확인.

Hint

bg-brand 가 안 적용되면 @theme 의 토큰 이름이 유틸 클래스랑 매치되는지 확인 — --color-brand 가 bg-brand, text-brand, border-brand 등 생성.

Theme 토큰 — semantic vs literal

Literal 토큰 (빌트인)

Semantic 토큰 (본인 것)

2-layer 패턴

cwkPippa 팔레트

좋은 semantic 이름의 조건

Code

External links

Exercise

Progress

댓글 0