시맨틱 토큰

Tailwind v4 패키지는 모든 색상에 대해 시맨틱 CSS 변수(디자인 토큰)를 사용합니다. 이러한 토큰은 컴포넌트 스타일을 특정 색상 값에서 분리하여 테마 적용을 간단하게 만듭니다. 토큰 명명 규칙은 shadcn/ui에서 사용하는 것과 동일한 패턴을 따릅니다.

토큰 시스템

하드코딩된 색상(예: bg-sky-500) 대신 Tailwind v4 컴포넌트는 bg-primary, text-foreground, border-border와 같은 시맨틱 유틸리티를 사용합니다. 이것들은 프로젝트에 정의한 CSS 변수에 매핑됩니다.

bg-primary        → var(--color-primary)
text-foreground   → var(--color-foreground)
border-border     → var(--color-border)

필수 토큰

Tailwind v4의 @theme 지시문을 사용하여 CSS에 다음 토큰들을 정의하세요:

@theme {
  --color-background: oklch(1 0 0);
  --color-foreground: oklch(0.145 0.004 285.823);


  --color-popover: oklch(1 0 0);
  --color-popover-foreground: oklch(0.145 0.004 285.823);


  --color-primary: oklch(0.205 0.006 285.885);
  --color-primary-foreground: oklch(0.985 0.001 285.823);


  --color-muted-foreground: oklch(0.556 0.01 285.823);


  --color-accent: oklch(0.96 0.003 285.823);
  --color-accent-foreground: oklch(0.205 0.006 285.885);


  --color-destructive: oklch(0.577 0.245 27.325);


  --color-border: oklch(0.922 0.004 285.823);
  --color-input: oklch(0.922 0.004 285.823);
  --color-ring: oklch(0.87 0.006 285.823);
}

토큰 레퍼런스

토큰용도예시 유틸리티
--color-background페이지/앱 배경bg-background
--color-foreground기본 텍스트 색상text-foreground
--color-popover팝업 배경bg-popover
--color-popover-foreground팝업 텍스트text-popover-foreground
--color-primary선택된 날짜, 확인 버튼, 범위 끝점bg-primary, text-primary
--color-primary-foreground기본(primary) 배경 위의 텍스트text-primary-foreground
--color-muted-foreground옅은 텍스트 (플레이스홀더, 요일, 내비게이션 버튼)text-muted-foreground
--color-accent날짜 및 버튼의 호버(Hover) 배경bg-accent
--color-accent-foreground강조(accent) 배경 위의 텍스트text-accent-foreground
--color-destructive초기화/위험 버튼 텍스트text-destructive
--color-border일반 테두리 (푸터, 프리셋, 팝업)border-border
--color-input입력창/트리거 테두리border-input
--color-ring포커스 링 색상ring-ring

토큰이 컴포넌트에 매핑되는 방식

피커 전체에 토큰이 어떻게 적용되는지 다음과 같이 보여줍니다:

트리거 (Trigger)

  • 배경: bg-background
  • 테두리: border-input
  • 텍스트: 루트의 text-foreground에서 상속됨
  • 플레이스홀더: text-muted-foreground
  • 포커스 링: ring-ring

팝업 (Popup)

  • 배경: bg-popover
  • 텍스트: text-popover-foreground
  • 테두리: border-border

달력 날짜 (Calendar Days)

  • 기본 호버: bg-accent / text-accent-foreground
  • 선택됨: bg-primary / text-primary-foreground
  • 오늘: text-primary
  • 범위 내: bg-primary/10
  • 범위 시작/끝: bg-primary / text-primary-foreground
  • 비활성화됨: 불투명도가 낮아진 text-muted-foreground
  • 테두리: border-border
  • 취소 버튼: border-input, 호버 시 bg-accent
  • 확인 버튼: bg-primary / text-primary-foreground
  • 초기화 버튼: text-destructive

토큰 커스터마이징

기본(Primary) 색상 변경

피커의 브랜드를 다시 지정하려면 --color-primary 및 --color-primary-foreground를 변경하세요:

@theme {
  /* Purple primary */
  --color-primary: oklch(0.55 0.25 300);
  --color-primary-foreground: oklch(0.98 0.01 300);
}

따뜻한 색상 체계 (Warm Color Scheme)

@theme {
  --color-background: oklch(0.99 0.005 80);
  --color-foreground: oklch(0.2 0.02 60);


  --color-popover: oklch(0.99 0.005 80);
  --color-popover-foreground: oklch(0.2 0.02 60);


  --color-primary: oklch(0.6 0.2 40);
  --color-primary-foreground: oklch(0.98 0.005 80);


  --color-accent: oklch(0.95 0.02 80);
  --color-accent-foreground: oklch(0.2 0.02 60);


  --color-border: oklch(0.9 0.01 80);
  --color-input: oklch(0.9 0.01 80);
  --color-ring: oklch(0.85 0.02 80);
}

다크 모드 토큰

다크 모드의 경우 .dark 선택자 또는 @media (prefers-color-scheme: dark) 하위에서 토큰을 재정의하세요:

@theme {
  --color-background: oklch(1 0 0);
  --color-foreground: oklch(0.145 0.004 285.823);
  /* ... light values */
}


.dark {
  --color-background: oklch(0.145 0.004 285.823);
  --color-foreground: oklch(0.985 0.001 285.823);
  --color-popover: oklch(0.145 0.004 285.823);
  --color-popover-foreground: oklch(0.985 0.001 285.823);
  --color-primary: oklch(0.985 0.001 285.823);
  --color-primary-foreground: oklch(0.205 0.006 285.885);
  --color-muted-foreground: oklch(0.556 0.01 285.823);
  --color-accent: oklch(0.269 0.006 285.885);
  --color-accent-foreground: oklch(0.985 0.001 285.823);
  --color-destructive: oklch(0.577 0.245 27.325);
  --color-border: oklch(0.269 0.006 285.885);
  --color-input: oklch(0.269 0.006 285.885);
  --color-ring: oklch(0.369 0.006 285.885);
}

자세한 내용은 다크 모드를 참조하세요.

기존 shadcn/ui 프로젝트

프로젝트에 이미 shadcn/ui 토큰이 정의되어 있다면, 피커는 별도의 설정 없이 이를 자동으로 사용합니다. 토큰 이름은 의도적으로 호환되도록 만들어졌습니다. 자세한 내용은 shadcn Registry를 참조하세요.