[Tailwind CSS v4] @apply 인식 오류 해결하기

🔥 문제 개요

오늘 Tailwind CSS v4를 처음 적용한 프로젝트에서 아래와 같은 오류가 발생했습니다.

❌ 오류 메시지 예시

Error: Cannot apply unknown utility class: bg-primary-500

이 오류는 Tailwind CSS v4에서 @apply가 글로벌 범위에서 자동으로 적용되지 않기 때문에 발생합니다.

---

✅ Tailwind CSS v4에서 @theme을 활용한 변수 정의

Tailwind CSS v4에서는 @theme을 사용하여 CSS 변수 형태로 색상, 폰트, 패딩 등을 정의할 수 있습니다.

🔹 globals.css에서 @theme 정의 예시

@theme {
  --color-primary-50: oklch(0.982 0.018 155.826);
  --color-primary-100: oklch(0.962 0.044 156.743);
  --color-primary-200: oklch(0.925 0.084 155.995);
  --color-primary-300: oklch(0.871 0.15 154.449);
  --color-primary-400: oklch(0.792 0.209 151.711);
  --color-primary-500: oklch(0.723 0.219 149.579);
  --color-primary-600: oklch(0.627 0.194 149.214);
  --color-primary-700: oklch(0.527 0.154 150.069);
  --color-primary-800: oklch(0.448 0.119 151.328);
  --color-primary-900: oklch(0.393 0.095 152.535);
  --color-primary-950: oklch(0.266 0.065 152.934);
}

---

@theme에서 정의한 변수를 다른 CSS 파일에서 @apply로 사용하려면 단순히 @apply bg-primary-500을 추가하는 것만으로는 동작하지 않습니다.

Tailwind v4에서는 @apply가 글로벌 적용되지 않으므로, 다른 CSS 파일에서 @apply를 사용하려면 @reference를 추가해야 합니다.

🔹 components.css에서 @reference 사용 예시

@reference "./globals.css";  /* Tailwind가 정의된 파일을 참조 */

.btn-primary {
  @apply bg-primary-500 text-white font-bold py-2 px-4 rounded;
}
/* bg-primary-500 같은 @theme에서 정의된 변수들은 @reference를 추가해야 정상적으로 적용됩니다. */

✅ 이제 Tailwind가 @apply bg-primary-500을 정상적으로 인식할 수 있습니다!

---