Tailwind CSS v4 — CSS 기반 설정의 시대

무엇이 바뀌었나

Tailwind CSS v4는 설정 방식을 근본적으로 바꿨다. JavaScript 설정 파일이 사라지고, CSS 안에서 모든 커스터마이징이 이루어진다.

v3 방식:

// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      colors: {
        primary: '#00D4AA',
      },
      fontFamily: {
        sans: ['Geist', 'system-ui'],
      },
    },
  },
};

v4 방식:

/* global.css */
@import 'tailwindcss';

@theme {
  --color-primary: #00D4AA;
  --font-sans: 'Geist', system-ui, sans-serif;
}

설정이 CSS로 들어왔다. 별도 파일 없이 스타일시트 안에서 디자인 시스템을 정의한다.

@theme 디렉티브

@theme은 Tailwind의 디자인 토큰을 정의하는 블록이다. CSS 커스텀 프로퍼티(변수)를 사용한다.

@theme {
  /* 색상 */
  --color-bg-base: #0a0a0b;
  --color-bg-surface: #141418;
  --color-text-primary: #F5F0EB;
  --color-accent-teal: #00D4AA;

  /* 타이포그래피 */
  --font-sans: 'Geist', 'Inter', system-ui, sans-serif;
  --font-mono: 'Geist Mono', 'JetBrains Mono', monospace;

  /* 크기 */
  --font-size-hero: clamp(2.5rem, 5vw, 4rem);
  --font-size-h1: clamp(2rem, 4vw, 3rem);

  /* 레이아웃 */
  --max-width-content: 75rem;
  --max-width-narrow: 48rem;

  /* 그림자 */
  --shadow-card: 0 1px 3px rgba(0,0,0,0.4);

  /* 애니메이션 */
  --animate-fade-in: fadeIn 0.5s ease-out forwards;
}

이 변수들은 Tailwind 클래스에서 바로 사용된다. --color-accent-teal을 정의하면 text-accent-teal, bg-accent-teal, border-accent-teal 클래스가 자동 생성된다.

장점

1. 하나의 언어

v3에서는 JavaScript(설정) + CSS(스타일) 두 언어를 오갔다. v4에서는 CSS만으로 완결된다. 디자이너가 설정을 이해하기 쉬워졌다.

2. IDE 지원 향상

CSS 커스텀 프로퍼티는 모든 에디터에서 자동 완성된다. tailwind.config.js의 깊은 중첩 객체보다 탐색이 쉽다.

3. 빌드 속도

v4는 Rust 기반 엔진(Oxide)을 사용한다. v3 대비 빌드 속도가 최대 10배 빠르다. Karnel Labs 사이트 빌드에서 CSS 처리 시간이 체감될 정도로 줄었다.

4. 런타임 접근

@theme에서 정의한 변수는 표준 CSS 커스텀 프로퍼티이므로, JavaScript에서 getComputedStyle로 읽을 수 있다. 다크 모드 전환이나 동적 테마 변경에 유용하다.

마이그레이션

v3에서 v4로 넘어오는 건 크게 어렵지 않다.

1. tailwind.config.js 삭제
2. global.css에 @import 'tailwindcss' 추가
3. 기존 설정을 @theme 블록으로 이동
4. @apply 사용 줄이기 (v4에서도 동작하지만 권장하지 않음)

색상 이름 매핑만 주의하면 된다. v3의 colors.primary는 v4에서 --color-primary가 된다.

Vite 플러그인

v4는 PostCSS 대신 Vite 플러그인으로 동작한다.

// vite.config.js 또는 astro.config.mjs
import tailwindcss from '@tailwindcss/vite';

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

PostCSS 설정, postcss.config.js 파일이 필요 없다. 설정 파일이 하나 더 줄었다.

주의사항

• @apply 의존도 줄이기: v4에서도 동작하지만, CSS 커스텀 프로퍼티와 직접 클래스 사용이 권장된다
• 플러그인 호환성: v3 플러그인은 v4에서 동작하지 않을 수 있다. 공식 플러그인은 대부분 대응 완료
• 브라우저 지원: CSS 커스텀 프로퍼티를 사용하므로 IE는 지원하지 않는다 (2026년이면 문제없다)

정리

Tailwind v4는 “CSS 프레임워크는 CSS로 설정한다”는 당연한 방향으로 진화했다. JavaScript 설정 파일이 사라지면서 프로젝트 루트가 깔끔해졌고, Oxide 엔진으로 빌드 속도도 빨라졌다. 새 프로젝트라면 v4를 쓰지 않을 이유가 없다.