Tailwind CSS v4 실전 가이드: CSS 우선 설정과 새로운 기능 총정리

@import "tailwindcss";

@import "tailwindcss";

@theme {
  --font-display: "Satoshi", "sans-serif";
  --breakpoint-3xl: 1920px;
  --color-brand-100: oklch(0.93 0.03 220);
  --color-brand-500: oklch(0.68 0.16 230);
  --color-brand-900: oklch(0.30 0.08 230);
  --ease-fluid: cubic-bezier(0.3, 0, 0, 1);
}

// v3에서는 resolveConfig()가 필요했지만, v4에서는 CSS 변수를 직접 사용합니다
const brandColor = getComputedStyle(document.documentElement)
  .getPropertyValue('--color-brand-500')

// React 컴포넌트에서 동적 스타일링에 활용
function ThemedButton({ children }: { children: React.ReactNode }) {
  return (
    <button
      style={{ backgroundColor: 'var(--color-brand-500)' }}
      className="text-white px-4 py-2 rounded-sm"
    >
      {children}
    </button>
  )
}

@import "tailwindcss";

/* 특정 경로 제외 */
@source not "./src/components/legacy";

/* 특정 유틸리티 강제 포함 (v3의 safelist 대체) */
@source inline("underline");

// tailwind.config.js
module.exports = {
  content: ['./src/**/*.{js,ts,jsx,tsx}'],
  theme: {
    extend: {
      colors: {
        brand: {
          100: '#e0f2fe',
          500: '#0ea5e9',
          900: '#0c4a6e',
        },
      },
      fontFamily: {
        display: ['Satoshi', 'sans-serif'],
      },
      screens: {
        '3xl': '1920px',
      },
    },
  },
  plugins: [],
}

// postcss.config.mjs
export default {
  plugins: {
    "postcss-import": {},
    tailwindcss: {},
    autoprefixer: {},
  },
}

/* globals.css */
@tailwind base;
@tailwind components;
@tailwind utilities;

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

@theme {
  --font-display: "Satoshi", "sans-serif";
  --breakpoint-3xl: 1920px;
  --color-brand-100: oklch(0.93 0.03 220);
  --color-brand-500: oklch(0.68 0.16 230);
  --color-brand-900: oklch(0.30 0.08 230);
}

// postcss.config.mjs (PostCSS 사용 시)
export default {
  plugins: {
    "@tailwindcss/postcss": {},
  },
}

// vite.config.ts — PostCSS 설정 파일이 아예 필요 없음
import { defineConfig } from "vite"
import tailwindcss from "@tailwindcss/vite"

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

<!-- 컨테이너 선언 -->
<div class="@container">
  <div class="grid grid-cols-1 @sm:grid-cols-3 @lg:grid-cols-4">
    <div class="p-4">카드 1</div>
    <div class="p-4">카드 2</div>
    <div class="p-4">카드 3</div>
  </div>
</div>

<!-- Max-width 쿼리 -->
<div class="@container">
  <div class="grid grid-cols-3 @max-md:grid-cols-1">
    <!-- 컨테이너가 md보다 작으면 1컬럼 -->
  </div>
</div>

<!-- 범위 쿼리 (Min + Max) -->
<div class="@container">
  <div class="flex @min-md:@max-xl:hidden">
    <!-- md~xl 범위에서만 숨김 -->
  </div>
</div>

<!-- v3: tailwind.config.js에 정의하거나 [값]으로 사용 -->
<!-- v4: 설정 없이 바로 사용 가능 -->
<div class="grid grid-cols-15"><!-- 15컬럼 그리드 --></div>
<div class="mt-17"><!-- 17단위 마진 --></div>
<div class="w-29"><!-- 29단위 너비 --></div>

/* v4가 생성하는 CSS */
.mt-8 { margin-top: calc(var(--spacing) * 8); }
.w-17 { width: calc(var(--spacing) * 17); }

<!-- 각도 지정 그래디언트 -->
<div class="bg-linear-45 from-indigo-500 via-purple-500 to-pink-500"></div>

<!-- OKLCH 색상 공간으로 보간 -->
<div class="bg-linear-to-r/oklch from-indigo-500 to-teal-400"></div>

<!-- 원뿔형 그래디언트 -->
<div class="size-24 rounded-full bg-conic/[in_hsl_longer_hue] from-red-600 to-red-600"></div>

<!-- 방사형 그래디언트 -->
<div class="size-24 rounded-full bg-radial-[at_25%_25%] from-white to-zinc-900 to-75%"></div>

<!-- not-* variant: 특정 상태가 아닐 때 스타일 적용 -->
<button class="opacity-100 not-hover:opacity-75">
  호버하지 않으면 반투명
</button>

<!-- @starting-style: JavaScript 없이 진입 애니메이션 -->
<div popover id="menu" class="transition-discrete starting:open:opacity-0 open:opacity-100">
  팝오버가 열릴 때 페이드인
</div>

<!-- inert: 비활성 요소 스타일링 -->
<div class="inert:opacity-50 inert:pointer-events-none">
  비활성 상태 영역
</div>

<!-- Text Shadow 유틸리티 -->
<h1 class="text-shadow-lg text-shadow-black/30">그림자 텍스트</h1>

<!-- 방향 마스크 -->
<div class="mask-t-from-50% bg-[url(/img/mountains.jpg)]"></div>

<!-- 폼 검증 (사용자 상호작용 후에만 표시) -->
<input
  required
  class="border user-valid:border-green-500 user-invalid:border-red-500"
  placeholder="이메일 입력"
/>

<!-- 터치/마우스 장치 구분 -->
<div class="grid grid-cols-6 gap-2 pointer-coarse:grid-cols-3 pointer-coarse:gap-4">
  <!-- 터치 디바이스에서 더 큰 터치 타겟 -->
</div>

npx @tailwindcss/upgrade

<!-- 1. 기본 border 색상 변경: gray-200 → currentColor -->
<!-- v3 -->
<div class="border"></div>
<!-- v4: 명시적으로 색상 지정 필요 -->
<div class="border border-gray-200"></div>

<!-- 2. Important 수정자 위치 변경 -->
<!-- v3 -->
<div class="!flex !bg-red-500"></div>
<!-- v4 -->
<div class="flex! bg-red-500!"></div>

<!-- 3. Variant 스태킹 순서: 우→좌에서 좌→우로 -->
<!-- v3 -->
<ul class="first:*:pt-0"></ul>
<!-- v4 -->
<ul class="*:first:pt-0"></ul>

/* theme() 함수 → CSS 변수 */
/* v3 */
.my-class {
  background-color: theme(colors.red.500);
}
/* v4 */
.my-class {
  background-color: var(--color-red-500);
}

/* 커스텀 유틸리티 정의 방식 */
/* v3 */
@layer utilities {
  .tab-4 { tab-size: 4; }
}
/* v4 */
@utility tab-4 {
  tab-size: 4;
}

@import "tailwindcss";
@config "../../tailwind.config.js";

npm install tailwindcss @tailwindcss/postcss postcss

// postcss.config.mjs
const config = {
  plugins: {
    "@tailwindcss/postcss": {},
  },
}
export default config

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

npm install tailwindcss @tailwindcss/vite

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

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

npm install tailwindcss @tailwindcss/webpack

// webpack.config.js
const tailwindcss = require('@tailwindcss/webpack')

module.exports = {
  plugins: [tailwindcss()],
}