테마와 토큰
브랜드 토큰을 Tailwind 유틸로 쓰는 방법, 다크 모드, shadcn 별칭을 알아봐요.
브랜드 테마를 설치하면 모든 Rootage 토큰이 CSS 변수(--rb-*)와 Tailwind v4 유틸로 들어와요. 컴포넌트와 화면 코드는 임의의 색·크기 대신 토큰 유틸을 써야 브랜드와 다크 모드를 자동으로 따라가요.
토큰 → Tailwind 유틸
토큰 이름의 그룹 접두사($color., $dimension., $radius. …)를 떼고 점을 하이픈으로 바꾸면 유틸 이름이 돼요.
| 토큰 | CSS 변수 | Tailwind 유틸 |
|---|---|---|
$color.bg.brand-solid | --rb-color-bg-brand-solid | bg-bg-brand-solid |
$color.fg.on-brand-solid | --rb-color-fg-on-brand-solid | text-fg-on-brand-solid |
$color.fg.neutral-subtle | --rb-color-fg-neutral-subtle | text-fg-neutral-subtle |
$color.stroke.neutral-muted | --rb-color-stroke-neutral-muted | border-stroke-neutral-muted |
$color.palette.gray-200 | --rb-color-palette-gray-200 | bg-palette-gray-200 |
$dimension.x4 | --rb-dimension-x4 | p-x4, gap-x4, h-x4 … |
$dimension.x1_5 | --rb-dimension-x1_5 | gap-x1_5 |
$dimension.spacing-x.global-gutter | --rb-dimension-spacing-x-global-gutter | px-spacing-x-global-gutter |
$radius.r2 | --rb-radius-r2 | rounded-r2 |
$font-size.t5 + $line-height.t5 | --rb-font-size-t5 | text-t5 (크기와 행간 함께) |
$font-weight.bold | --rb-font-weight-bold | font-bold |
$shadow.s2 | --rb-shadow-s2 | shadow-s2 |
$timing-function.enter | --rb-timing-function-enter | ease-enter |
$duration.d3 | --rb-duration-d3 | duration-(--rb-duration-d3) |
색 유틸은 bg-, text-, border-, outline-, fill- 등 모든 색 접두사와 함께 쓸 수 있어요. 시간(duration)은 Tailwind 테마 네임스페이스가 없어서 CSS 변수를 직접 참조해요.
<div className="flex flex-col gap-x1_5 rounded-r3 border border-stroke-neutral-muted bg-bg-layer-default p-x4 shadow-s1">
<p className="text-t5 font-bold text-fg-neutral">주문이 접수됐어요</p>
<p className="text-t4 text-fg-neutral-subtle">판매자가 확인하면 알림을 보내드려요.</p>
<button className="mt-x2 rounded-r2 bg-bg-brand-solid px-x4 py-x2_5 text-t4 font-bold text-fg-on-brand-solid active:bg-bg-brand-solid-pressed">
주문 내역 보기
</button>
</div>임의 값 대신 토큰
bg-[#ff6600], p-[16px] 처럼 값을 직접 쓰면 브랜드를 바꾸거나 다크 모드로 바꿔도 따라가지 않아요. 토큰에 없는 값이 꼭 필요할 때만 임의 값을 써요.
시맨틱 색 고르기
색은 원시 팔레트(palette-*)보다 시맨틱 토큰을 먼저 써요. 시맨틱 토큰은 브랜드와 모드마다 알맞은 값으로 바뀌어요.
| 용도 | 배경 | 전경 | 테두리 |
|---|---|---|---|
| 기본 화면 | bg-bg-layer-default | text-fg-neutral | border-stroke-neutral-muted |
| 보조 텍스트 | - | text-fg-neutral-subtle, text-fg-neutral-muted | - |
| 브랜드 강조 | bg-bg-brand-solid | text-fg-on-brand-solid | border-stroke-brand-solid |
| 약한 브랜드 | bg-bg-brand-weak | text-fg-brand-contrast | border-stroke-brand-weak |
| 위험·오류 | bg-bg-critical-solid | text-fg-on-critical-solid | border-stroke-critical-solid |
| 비활성 | bg-bg-disabled | text-fg-disabled | - |
| 팝오버·시트 | bg-bg-layer-floating | text-fg-neutral | - |
전체 토큰과 값은 Foundations 에서 볼 수 있어요.
다크 모드
색과 그림자 토큰은 light / dark 값을 함께 가져요. 상위 요소에 .dark 클래스를 붙이면 그 아래의 모든 토큰이 다크 값으로 바뀌어요. 컴포넌트에 dark: 변형을 따로 쓸 필요가 없어요.
<html class="dark">
...
</html>시스템 설정을 따르려면 prefers-color-scheme 을 읽어 .dark 를 토글하거나 next-themes 같은 라이브러리를 써요. 화면 일부만 다크로 보여주고 싶다면 그 요소에만 .dark 를 붙여도 돼요.
Tailwind 의 dark: 변형이 클래스 기준으로 동작하도록 CSS 에 아래 줄이 있는지 확인해요. shadcn 초기화가 기본으로 넣어줘요.
@custom-variant dark (&:is(.dark *));shadcn 별칭
브랜드 테마는 shadcn/ui 의 CSS 변수도 브랜드 토큰에 연결해요. 그래서 bg-primary, text-muted-foreground, border-border, rounded-lg 같은 shadcn 유틸과 서드파티 shadcn 컴포넌트도 브랜드 색을 따라요.
| shadcn 변수 | 연결된 토큰 (Clay) |
|---|---|
--background | $color.bg.layer-default |
--foreground | $color.fg.neutral |
--primary / --primary-foreground | $color.bg.brand-solid / $color.fg.on-brand-solid |
--secondary, --muted | $color.bg.neutral-weak |
--muted-foreground | $color.fg.neutral-subtle |
--destructive | $color.bg.critical-solid |
--border | $color.stroke.neutral-muted |
--ring | $color.stroke.focus-ring |
--radius | $radius.r2_5 |
새 코드에서는 SEED 이름의 토큰 유틸(bg-bg-brand-solid)을 쓰고, shadcn 별칭은 외부 컴포넌트 호환용으로 남겨 두는 것을 권장해요.
컴포넌트 스타일 덮어쓰기
모든 컴포넌트는 className 을 받고 cn() 으로 병합해요. tailwind-merge 가 충돌하는 유틸을 정리하므로, 나중에 준 클래스가 이겨요.
<ActionButton className="rounded-full px-x6">둥근 버튼</ActionButton>여러 곳에서 같은 변형이 필요하다면 복사된 컴포넌트 파일의 cva variant 에 직접 추가해요.