Tailwind v4 실전 — CSS-first config·variants·Container Query 활용

핵심 요약

Tailwind v4는 v3와 호환을 일부 깨는 중요한 업데이트. 핵심은 (1) JS config → CSS config 전환, (2) 빌드 속도 10배 향상 (Lightning CSS), (3) Container Query·@starting-style 등 모던 CSS 기본 지원.

• 출시: 2025-10 (Tailwind v4.0)
• 빌드 속도: v3 대비 10배 (Lightning CSS Rust 엔진)
• config: tailwind.config.js → app.css
• 번들 크기: v3 대비 약 30% 감소

1. CSS-first 설정

/* app.css */
@import "tailwindcss";

@theme {
  --color-brand: oklch(0.6 0.2 240);
  --color-accent: #d4a85a;
  --font-display: "Pretendard", sans-serif;
  --breakpoint-3xl: 120rem;
}

@source "./components/**/*.tsx";
@source "./pages/**/*.tsx";

JS 파일 없이 CSS 파일로 config. CSS 변수가 직접 Tailwind 토큰이 됨.

2. Variant 시스템 단순화

/* hover, focus 등 기본 */
<button class="bg-brand hover:bg-brand-dark">

/* not-: 부정 */
<input class="not-focus:ring-0" />

/* has-: 자식 선택자 */
<label class="has-[input:checked]:bg-blue-500">

/* group-, peer- 그대로 */
<div class="group">
  <span class="group-hover:text-brand">

3. Container Query

parent 컨테이너 폭에 따른 반응형. 미디어 쿼리보다 모던.

<div class="@container">
  <div class="text-base @md:text-xl @lg:text-2xl">
    컨테이너 폭에 따라 크기 변경
  </div>
</div>

4. @starting-style — 진입 애니메이션

<div class="starting:opacity-0 starting:translate-y-4 transition-all duration-300 opacity-100 translate-y-0">
  처음 렌더 시 fade in + slide up
</div>

JS 없이 mount 시 애니메이션. v4 신기능.

5. 색상 시스템 — OKLCH

Tailwind v4는 RGB·HSL 대신 OKLCH 권장. 인지적으로 균일한 명도 변화.

@theme {
  /* OKLCH(L C H) — Lightness 0~1, Chroma 0~0.4, Hue 0~360 */
  --color-brand-50: oklch(0.96 0.04 240);
  --color-brand-500: oklch(0.6 0.2 240);
  --color-brand-900: oklch(0.25 0.15 240);
}

6. 디자인 토큰 일관성

@theme {
  /* 의미적 명명 */
  --color-bg: var(--color-neutral-50);
  --color-bg-elevated: var(--color-white);
  --color-text: var(--color-neutral-900);
  --color-text-muted: var(--color-neutral-600);
  --color-border: var(--color-neutral-200);
  --color-primary: var(--color-brand-500);
  --color-primary-hover: var(--color-brand-600);
  
  /* dark 모드 자동 매핑 */
}

@media (prefers-color-scheme: dark) {
  @theme {
    --color-bg: var(--color-neutral-950);
    --color-text: var(--color-neutral-100);
  }
}

7. v3 → v4 마이그레이션

# Codemod
npx @tailwindcss/upgrade@latest

주요 호환성 변경

• tailwind.config.js → @theme (CSS)
• @apply가 제한됨 — 가능하면 직접 클래스 사용
• 일부 클래스명 변경: ring → outline 일부 케이스
• JIT mode 항상 활성 (v3와 동일)
• @layer 시스템 단순화

8. 컴포넌트 라이브러리 통합

shadcn/ui v3은 Tailwind v4 기본. Radix Primitives + Tailwind v4 + CVA(class-variance-authority) 조합이 모던 디자인 시스템 표준.

import { cva } from 'class-variance-authority'

const buttonVariants = cva(
  'inline-flex items-center justify-center rounded-md font-medium transition-colors',
  {
    variants: {
      variant: {
        primary: 'bg-brand text-white hover:bg-brand-hover',
        ghost: 'hover:bg-neutral-100',
      },
      size: {
        sm: 'h-8 px-3 text-sm',
        md: 'h-10 px-4',
        lg: 'h-12 px-6 text-lg',
      },
    },
    defaultVariants: { variant: 'primary', size: 'md' },
  }
)

9. 성능 — 빌드 속도

Lightning CSS (Rust)로 v3 대비 10배. dev 환경 HMR 즉시.

실전 도입 체크

• v3 프로젝트라면 codemod 후 빌드만 테스트
• 큰 디자인 시스템은 점진적 — @theme로 토큰 먼저 옮김
• shadcn/ui v3 사용 중이면 v4 자동 호환
• Tailwind UI·Headless UI 일부 컴포넌트는 v4 패치 필요

자주 묻는 질문

v3 사용 중인데 굳이 v4 가야 하나?

빌드 속도 차이가 매우 큼. 큰 프로젝트일수록 v4 효과 큼. 호환성 문제는 codemod로 90% 해결.

JS config 파일이 필요한 케이스?

매우 동적인 색 생성·플러그인 등은 여전히 JS 가능 (config.ts 옵션). 단 일반적 사용엔 CSS만으로 충분.

OKLCH로 바꾸는 게 정말 의미 있나?

brand color 같은 명도 ramps에서 효과 큼. 단순 색은 RGB도 OK. dark mode 색 정의 시 OKLCH가 일관성 좋음.