2026년 Tailwind CSS v4: 실용 예제를 포함한 완벽 가이드

Tailwind CSS v4는 프레임워크가 탄생한 이래 가장 큰 개편을 대표합니다. 2025년 초에 출시되어 2026년 현재 완전히 성숙한 v4는 CSS 우선 설정 시스템, Oxide라는 완전히 새로 작성된 엔진, 극적인 성능 향상, 그리고 현대화된 유틸리티 세트를 도입합니다. Tailwind v3를 사용해 왔다면, v4로의 업그레이드는 설정과 테마에 대한 사고방식을 바꿔놓을 것입니다. 이 가이드에서 알아야 할 모든 것을 안내합니다.

Tailwind CSS v4에서 변경된 사항

Tailwind v4는 단순한 점진적 업데이트가 아닙니다. 프레임워크가 내부적으로 작동하는 방식에 대한 근본적인 재고입니다. 주요 변경 사항은 다음과 같습니다:

• CSS 우선 설정: 더 이상 tailwind.config.js가 필요 없습니다. 테마 값, 커스텀 유틸리티, 배리언트 모두 @theme 및 기타 디렉티브를 사용하여 CSS에서 직접 정의됩니다.
• Oxide 엔진: Rust로 작성된 새로운 고성능 엔진으로, 파싱, 컴파일, 클래스 감지를 v3보다 수십 배 빠르게 처리합니다.
• 모던 CSS 기능: @layer, 캐스케이드 레이어, color-mix(), oklch(), 컨테이너 쿼리, 애니메이션을 위한 @starting-style에 대한 기본 지원.
• 간소화된 설치: 시작하는 데 제로 설정으로 하나의 패키지만 필요합니다.
• 새로운 기본 테마: OKLCH를 사용한 확장된 색상 팔레트, 업데이트된 간격 스케일, 개선된 타이포그래피 기본값.

Tailwind CSS v4 시작하기

설치

Tailwind v4 설정은 그 어느 때보다 간단합니다. 별도의 PostCSS 플러그인이나 설정 파일이 필요 없습니다.

# Install Tailwind CSS v4
npm install tailwindcss @tailwindcss/vite

# Or with the CLI
npm install tailwindcss @tailwindcss/cli

Vite 기반 프로젝트의 경우 Vite 설정에 플러그인을 추가합니다:

// vite.config.ts
import { defineConfig } from 'vite';
import tailwindcss from '@tailwindcss/vite';

export default defineConfig({
  plugins: [
    tailwindcss(),
  ],
});

그런 다음 메인 CSS 파일에서 Tailwind를 임포트합니다:

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

이것이 전체 설정입니다. tailwind.config.js도, postcss.config.js도, 콘텐츠 경로 설정도 필요 없습니다. Oxide 엔진이 자동으로 소스 파일을 감지하고 클래스 이름을 스캔합니다.

CLI 사용하기

Vite를 사용하지 않는 경우에도 CLI가 잘 작동합니다:

npx @tailwindcss/cli -i app.css -o output.css --watch

@theme을 사용한 CSS 우선 설정

v4에서 가장 큰 개념적 변화는 모든 커스터마이징이 JavaScript가 아닌 CSS에서 이루어진다는 것입니다. @theme 디렉티브가 이전의 tailwind.config.js 테마 객체를 대체합니다.

커스텀 색상 정의하기

@import "tailwindcss";

@theme {
  --color-brand: #4f46e5;
  --color-brand-light: #818cf8;
  --color-brand-dark: #3730a3;
  --color-surface: #f8fafc;
  --color-surface-dark: #1e293b;
}

이 CSS 변수들은 자동으로 Tailwind 유틸리티로 사용할 수 있게 됩니다:

<div class="bg-brand text-white">
  <h1 class="text-brand-light">Hello, Tailwind v4</h1>
</div>

커스텀 간격과 크기

@theme {
  --spacing-18: 4.5rem;
  --spacing-128: 32rem;
  --width-content: 72rem;
  --width-sidebar: 20rem;
}

커스텀 폰트

@theme {
  --font-sans: "Inter", "system-ui", sans-serif;
  --font-mono: "JetBrains Mono", "Fira Code", monospace;
  --font-display: "Cal Sans", "Inter", sans-serif;
}

기본 테마 재정의 vs 확장

기본적으로 @theme은 내장 테마를 확장합니다. 네임스페이스를 완전히 교체하려면 --* 와일드카드 리셋을 사용하세요:

@theme {
  /* Remove all default colors, only use these */
  --color-*: initial;
  --color-white: #ffffff;
  --color-black: #000000;
  --color-primary: #2563eb;
  --color-secondary: #7c3aed;
  --color-gray-50: #f9fafb;
  --color-gray-100: #f3f4f6;
  --color-gray-900: #111827;
}

Oxide 엔진

내부적으로 Tailwind v4는 Rust로 작성되고 네이티브 코드로 컴파일된 Oxide라는 새 엔진을 사용합니다. 성능 차이는 상당합니다.

성능 향상

Oxide 엔진은 v3 JavaScript 기반 엔진에 비해 극적인 속도 향상을 제공합니다:

• 초기 빌드 시간은 프로젝트 규모에 따라 일반적으로 3-10배 빠릅니다.
• 증분 리빌드는 개발 중 거의 즉각적이며, 종종 5밀리초 미만입니다.
• 메모리 사용량은 Rust가 가비지 컬렉터 없이 메모리를 관리하므로 상당히 낮습니다.

수십만 개의 클래스가 있는 대규모 모노레포 프로젝트에서 차이가 특히 눈에 띕니다. v3가 전체 리빌드에 수 초가 걸릴 수 있는 반면, v4는 수백 밀리초 만에 완료됩니다.

자동 콘텐츠 감지

가장 좋은 생활 품질 개선 중 하나는 더 이상 콘텐츠 경로를 지정할 필요가 없다는 것입니다. Oxide 엔진이 자동으로 프로젝트 파일을 감지하고 스캔합니다. 휴리스틱을 사용하여 템플릿 파일, JSX/TSX 컴포넌트 및 기타 클래스 이름 소스를 찾습니다.

파일을 명시적으로 포함하거나 제외해야 하는 경우 @source 디렉티브를 사용할 수 있습니다:

@import "tailwindcss";

/* Add additional source paths */
@source "../shared-components/**/*.tsx";

/* Exclude a path */
@source not "../node_modules";

새로운 유틸리티 클래스 및 업데이트

Tailwind v4는 여러 새로운 유틸리티를 도입하고 모던 CSS 기능을 활용하도록 기존 유틸리티를 개선합니다.

컨테이너 쿼리

컨테이너 쿼리를 사용하면 뷰포트가 아닌 부모 컨테이너의 크기에 따라 요소를 스타일링할 수 있습니다. Tailwind v4는 이를 기본으로 지원합니다.

<div class="@container">
  <div class="flex flex-col @md:flex-row @lg:grid @lg:grid-cols-3 gap-4">
    <div class="p-4 bg-white rounded-lg">Card 1</div>
    <div class="p-4 bg-white rounded-lg">Card 2</div>
    <div class="p-4 bg-white rounded-lg">Card 3</div>
  </div>
</div>

@container 클래스가 컨테이너 컨텍스트를 설정하고, @md:, @lg: 접두사가 컨테이너 너비에 따라 스타일을 적용합니다.

모던 색상 함수

Tailwind v4는 기본적으로 지각적으로 균일한 색상 공간을 제공하는 OKLCH 색상을 사용합니다. 동적 색상 조작을 위해 color-mix()도 사용할 수 있습니다:

@theme {
  --color-primary: oklch(0.6 0.25 265);
  --color-primary-hover: oklch(0.5 0.25 265);
}

<button class="bg-primary hover:bg-primary-hover text-white px-4 py-2 rounded">
  Click me
</button>

3D 트랜스폼

<div class="perspective-500">
  <div class="rotate-y-12 hover:rotate-y-0 transition-transform duration-300">
    <img src="/card.jpg" alt="3D card" class="rounded-xl shadow-lg" />
  </div>
</div>

새로운 그래디언트 유틸리티

v4는 추가 기능으로 그래디언트 지원을 확장합니다:

<!-- Gradient with interpolation in OKLCH for smoother transitions -->
<div class="bg-linear-to-r from-blue-500 to-purple-500 bg-interpolate-oklch">
  Smooth gradient
</div>

<!-- Conic gradient -->
<div class="bg-conic from-red-500 via-yellow-500 to-green-500">
  Color wheel
</div>

not- 배리언트

not- 배리언트는 CSS :not()을 활용하여 다른 배리언트를 반전시킵니다:

<div class="opacity-50 not-hover:opacity-100">
  Fades on hover instead of appearing
</div>

<input class="border-gray-300 not-focus:border-transparent" />

애니메이션을 위한 Starting Style

starting 배리언트를 사용하면 DOM에 나타나는 요소의 진입 애니메이션을 가능하게 하는 @starting-style 규칙에 대한 스타일을 정의할 수 있습니다:

<dialog class="opacity-0 starting:opacity-0 open:opacity-100 transition-opacity">
  <p>This dialog fades in when opened</p>
</dialog>

v4에서의 반응형 디자인

반응형 디자인은 개념적으로 동일하게 작동하며, 익숙한 브레이크포인트 접두사 구문을 사용합니다. 다만 v4는 내부적으로 모던 CSS 기능을 사용합니다.

기본 브레이크포인트

기본 브레이크포인트는 실용적입니다:

접두사	최소 너비	일반적인 용도
sm	640px	큰 폰, 가로 모드
md	768px	태블릿
lg	1024px	소형 노트북
xl	1280px	데스크톱
2xl	1536px	대형 화면

커스텀 브레이크포인트

@theme {
  --breakpoint-xs: 475px;
  --breakpoint-3xl: 1920px;
}

<div class="grid grid-cols-1 xs:grid-cols-2 md:grid-cols-3 3xl:grid-cols-4">
  <!-- Responsive grid -->
</div>

반응형 레이아웃 예제

<header class="flex flex-col sm:flex-row items-center justify-between p-4 lg:px-8">
  <a href="/" class="text-xl font-bold">Brand</a>
  <nav class="hidden md:flex gap-6 text-sm font-medium">
    <a href="/features" class="hover:text-brand">Features</a>
    <a href="/pricing" class="hover:text-brand">Pricing</a>
    <a href="/docs" class="hover:text-brand">Docs</a>
  </nav>
  <button class="md:hidden p-2" aria-label="Menu">
    <svg class="w-6 h-6" fill="none" viewBox="0 0 24 24" stroke="currentColor">
      <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M4 6h16M4 12h16M4 18h16" />
    </svg>
  </button>
</header>

다크 모드

Tailwind v4는 dark: 배리언트로 다크 모드를 계속 지원합니다. 기본적으로 prefers-color-scheme 미디어 쿼리를 사용하지만, 클래스 기반 또는 셀렉터 기반 토글로 전환할 수 있습니다.

기본 다크 모드

<div class="bg-white dark:bg-gray-900 text-gray-900 dark:text-gray-100 min-h-screen">
  <h1 class="text-2xl font-bold">Welcome</h1>
  <p class="text-gray-600 dark:text-gray-400">This adapts to your system theme.</p>
</div>

클래스 기반 다크 모드

시스템 설정에 의존하지 않고 JavaScript로 다크 모드를 토글하려면:

@import "tailwindcss";

@variant dark (&:where(.dark, .dark *));

이제 부모 요소에 dark 클래스가 있으면 다크 모드가 활성화됩니다:

<html class="dark">
  <body class="bg-white dark:bg-gray-950">
    <!-- Dark mode active -->
  </body>
</html>

// Toggle dark mode with JavaScript
function toggleDarkMode() {
  document.documentElement.classList.toggle('dark');
}

테마 인식 컴포넌트 만들기

<div class="rounded-xl border border-gray-200 dark:border-gray-800
            bg-white dark:bg-gray-900
            shadow-sm dark:shadow-gray-950/50
            p-6">
  <h3 class="text-lg font-semibold text-gray-900 dark:text-white">
    Settings
  </h3>
  <p class="mt-2 text-sm text-gray-500 dark:text-gray-400">
    Manage your account preferences.
  </p>
  <button class="mt-4 px-4 py-2 rounded-lg
                 bg-brand text-white
                 hover:bg-brand-dark
                 focus:outline-none focus:ring-2 focus:ring-brand/50">
    Save Changes
  </button>
</div>

애니메이션 유틸리티

Tailwind v4는 애니메이션 지원을 상당히 확장하여, 커스텀 CSS 없이도 세련된 인터랙션을 더 쉽게 만들 수 있습니다.

트랜지션 유틸리티

<!-- Smooth hover effect -->
<button class="bg-blue-600 hover:bg-blue-700
               transform hover:scale-105
               transition-all duration-200 ease-out
               text-white px-6 py-3 rounded-lg">
  Hover me
</button>

<!-- Transition specific properties -->
<div class="transition-colors duration-300 bg-gray-100 hover:bg-blue-100">
  Color transition only
</div>

내장 애니메이션

<!-- Spin animation for loading indicators -->
<svg class="animate-spin h-5 w-5 text-white" viewBox="0 0 24 24">
  <!-- spinner SVG -->
</svg>

<!-- Pulse animation -->
<div class="animate-pulse bg-gray-200 rounded h-4 w-3/4"></div>

<!-- Bounce -->
<div class="animate-bounce">Scroll down</div>

@theme을 사용한 커스텀 애니메이션

@theme {
  --animate-slide-in: slide-in 0.3s ease-out;
  --animate-fade-up: fade-up 0.5s ease-out;
}

@keyframes slide-in {
  from { transform: translateX(-100%); }
  to { transform: translateX(0); }
}

@keyframes fade-up {
  from {
    opacity: 0;
    transform: translateY(1rem);
  }
  to {
    opacity: 1;
    transform: translateY(0);
  }
}

<div class="animate-slide-in">Slides in from the left</div>
<div class="animate-fade-up">Fades up into view</div>

Tailwind v3에서 v4로 마이그레이션

v3에서 v4로의 마이그레이션은 약간의 노력이 필요하지만, Tailwind 팀이 대부분의 변경을 자동으로 처리하는 코드모드 도구를 제공합니다.

업그레이드 도구 실행하기

npx @tailwindcss/upgrade

이 도구는 프로젝트를 스캔하고 대부분의 v3 패턴을 v4 동등물로 자동 변환합니다. 유틸리티 이름 변경, 설정 마이그레이션, 임포트 업데이트를 처리합니다.

주요 마이그레이션 변경 사항

v3	v4	참고
tailwind.config.js	CSS의 @theme	설정이 CSS로 이동
@tailwind base/components/utilities	@import "tailwindcss"	단일 임포트
bg-opacity-50	bg-black/50	불투명도 수정자 구문
text-opacity-75	text-white/75	불투명도 수정자 구문
decoration-clone	box-decoration-clone	이름 변경
flex-shrink-0	shrink-0	간소화 (v3에서도 작동)
flex-grow	grow	간소화
overflow-clip	overflow-clip	동일
설정의 content 경로	자동 감지	설정 불필요
설정의 darkMode: 'class'	CSS의 @variant dark (...)	CSS 기반

수동 단계

업그레이드 도구 실행 후 다음 영역을 수동으로 검토하세요:

1. 커스텀 플러그인: v3 JavaScript 플러그인은 @utility와 @variant 디렉티브를 사용하여 CSS로 다시 작성해야 합니다.
2. 커스텀 테마 값: tailwind.config.js에서 CSS의 @theme 블록으로 이동하세요.
3. 서드파티 플러그인: v4 호환성을 위해 업데이트되었는지 확인하세요.

v3 플러그인을 v4로 변환하기

v3 플러그인 (JavaScript):

// v3: tailwind.config.js plugin
const plugin = require('tailwindcss/plugin');

module.exports = {
  plugins: [
    plugin(function({ addUtilities }) {
      addUtilities({
        '.text-balance': {
          'text-wrap': 'balance',
        },
      });
    }),
  ],
};

v4 동등물 (CSS):

/* v4: defined directly in CSS */
@utility text-balance {
  text-wrap: balance;
}

v3 커스텀 배리언트 변환하기

v3 (JavaScript):

// v3
plugin(function({ addVariant }) {
  addVariant('hocus', ['&:hover', '&:focus']);
});

v4 (CSS):

/* v4 */
@variant hocus (&:hover, &:focus);

완전한 컴포넌트 만들기

모든 것을 종합하여 v4 기능을 보여주는 가격 카드 컴포넌트를 만들어 봅시다:

<div class="@container max-w-sm mx-auto">
  <div class="rounded-2xl border border-gray-200 dark:border-gray-800
              bg-white dark:bg-gray-900
              shadow-xl shadow-gray-900/5 dark:shadow-gray-950/50
              p-8
              transition-all duration-300
              hover:shadow-2xl hover:-translate-y-1">

    <h3 class="text-sm font-semibold text-brand uppercase tracking-wider">
      Pro Plan
    </h3>

    <div class="mt-4 flex items-baseline gap-1">
      <span class="text-5xl font-bold text-gray-900 dark:text-white">$29</span>
      <span class="text-gray-500 dark:text-gray-400">/month</span>
    </div>

    <p class="mt-4 text-sm text-gray-600 dark:text-gray-400">
      Everything you need to build and ship faster.
    </p>

    <ul class="mt-8 space-y-3 text-sm">
      <li class="flex items-center gap-3 text-gray-700 dark:text-gray-300">
        <svg class="w-5 h-5 text-brand shrink-0" fill="currentColor" viewBox="0 0 20 20">
          <path fill-rule="evenodd" d="M16.707 5.293a1 1 0 010 1.414l-8 8a1 1 0 01-1.414 0l-4-4a1 1 0 011.414-1.414L8 12.586l7.293-7.293a1 1 0 011.414 0z" clip-rule="evenodd" />
        </svg>
        Unlimited projects
      </li>
      <li class="flex items-center gap-3 text-gray-700 dark:text-gray-300">
        <svg class="w-5 h-5 text-brand shrink-0" fill="currentColor" viewBox="0 0 20 20">
          <path fill-rule="evenodd" d="M16.707 5.293a1 1 0 010 1.414l-8 8a1 1 0 01-1.414 0l-4-4a1 1 0 011.414-1.414L8 12.586l7.293-7.293a1 1 0 011.414 0z" clip-rule="evenodd" />
        </svg>
        Priority support
      </li>
      <li class="flex items-center gap-3 text-gray-700 dark:text-gray-300">
        <svg class="w-5 h-5 text-brand shrink-0" fill="currentColor" viewBox="0 0 20 20">
          <path fill-rule="evenodd" d="M16.707 5.293a1 1 0 010 1.414l-8 8a1 1 0 01-1.414 0l-4-4a1 1 0 011.414-1.414L8 12.586l7.293-7.293a1 1 0 011.414 0z" clip-rule="evenodd" />
        </svg>
        Advanced analytics
      </li>
    </ul>

    <button class="mt-8 w-full rounded-lg bg-brand py-3 text-sm font-semibold text-white
                   hover:bg-brand-dark
                   focus:outline-none focus:ring-2 focus:ring-brand/50 focus:ring-offset-2
                   dark:focus:ring-offset-gray-900
                   transition-colors duration-200">
      Get started
    </button>
  </div>
</div>

결론

Tailwind CSS v4는 프레임워크의 큰 도약입니다. CSS 우선 설정으로의 전환은 프로젝트 설정과 이해를 더 간단하게 만듭니다. Oxide 엔진은 빌드 성능에 대한 걱정을 없애줍니다. 그리고 컨테이너 쿼리와 OKLCH 색상 같은 모던 CSS 기능을 기반으로 한 새로운 유틸리티는 커스텀 CSS를 적게 작성하면서도 더 강력한 도구를 제공합니다.

새 프로젝트를 시작한다면 v4를 사용하지 않을 이유가 없습니다. v3 프로젝트를 유지 관리하고 있다면, 업그레이드 도구가 대부분의 코드베이스에서 마이그레이션을 간단하게 만들어 줍니다. 커뮤니티와 에코시스템이 v4를 완전히 수용했으며, 개발자 경험은 그 어느 때보다 좋아졌습니다.

CSS to Tailwind 변환기를 사용하여 기존 CSS를 빠르게 변환해 보세요.

새로운 기능, 특히 컨테이너 쿼리와 @theme 디렉티브를 실험해 보세요. 이것들은 컴포넌트 디자인 접근 방식을 근본적으로 바꾸며, 한번 채택하면 되돌아가는 것이 퇴보처럼 느껴질 것입니다.