Tailwind CSS v4 색상 변경: 개발자가 알아야 할 사항

Tailwind CSS v4는 최초 릴리스 이후 프레임워크에서 확인된 가장 중요한 업데이트입니다. 많은 헤드라인 변경 사항에는 새로운 CSS 우선 구성 시스템 및 엔진 성능이 포함되어 있지만 색상 시스템도 내부적으로 sRGB 16진수에서 OKLCH로 이동하고 모든 색상을 CSS 사용자 정의 속성으로 노출하며 개발자가 사용자 정의 색상을 등록하는 방법을 재고하는 등 똑같이 중요한 업그레이드를 받았습니다. Tailwind v3 프로젝트가 있고 마이그레이션을 계획 중이거나 v4를 사용하여 새 프로젝트를 시작하는 경우 이 가이드에서는 색상 관련 변경 사항에 대해 알아야 할 모든 내용을 다룹니다.

Tailwind v4의 CSS 우선 구성

Tailwind v4의 가장 파괴적인 변화는 특별히 색상과 관련이 없지만 색상 구성 방식에 대한 모든 것을 변경합니다. v3에서는 JavaScript 파일을 통해 프레임워크를 사용자 정의했습니다.

// tailwind.config.js — v3 approach
module.exports = {
  theme: {
    extend: {
      colors: {
        brand: {
          500: '#0F766E',
          600: '#0D9488',
        },
      },
    },
  },
}

v4에서는 tailwind.config.js가 사라졌습니다. 색상을 포함한 모든 구성은 @theme 블록 내부의 CSS 파일로 이동됩니다.

/* styles.css — v4 approach */
@import "tailwindcss";

@theme {
  --color-brand-500: #0F766E;
  --color-brand-600: #0D9488;
}

이는 외관상의 변화가 아닙니다. @theme 블록은 유틸리티 클래스를 생성하는 디자인 토큰으로 처리할 CSS 사용자 정의 속성을 Tailwind에 알려줍니다. --color-brand-500라는 변수는 theme.extend.colors에서 정의한 것과 똑같이 bg-brand-500, text-brand-500, border-brand-500, ring-brand-500 및 기타 모든 색상 유틸리티 변형을 자동으로 생성합니다. 플러그인도 없고, safelist도 없고, 일반 CSS 처리 이상의 재구축 단계도 없습니다.

이것이 색상 작업 흐름에 중요한 이유

JS에서 CSS로의 전환은 팀이 색상을 관리하는 방식에 실질적인 영향을 미칩니다.

• 단일 정보 소스: 디자인 토큰은 색상이 실제로 적용되는 CSS에 있습니다. 동기화를 유지할 JavaScript 레이어가 없습니다.
• 네이티브 CSS 도구: @theme에 정의된 CSS 변수는 빌드 단계 없이 DevTools, CSS calc() 및 CSS를 사용하는 모든 도구에서 작동합니다.
• 더 이상 require() 해킹이 없습니다: v3에서는 Tailwind 구성과 맞춤 CSS 간에 색상을 공유하려면 require('tailwindcss/resolveConfig')로 구성을 가져와야 했으며 이로 인해 JS가 아닌 컨텍스트에 복잡성이 추가되었습니다. v4에서는 공유가 간단합니다. 모든 것이 CSS 변수입니다.

단점은 이전에 Tailwind 구성에서 16진수 값을 가져온 JavaScript 소비자(차트, 캔버스, 특정 React 라이브러리)가 이제 getComputedStyle(document.documentElement).getPropertyValue('--color-brand-500')를 통해 런타임에 CSS 사용자 정의 속성 값을 읽어야 한다는 것입니다. 이는 약간 더 장황하지만 올바르게 작동합니다.

OKLCH 내부 정보

Tailwind v3에서는 색상이 sRGB 16진수 코드로 저장되었습니다. v4에서는 내장 팔레트가 OKLCH로 표현됩니다. 유틸리티 클래스를 사용하는 대부분의 개발자에게는 이것이 보이지 않습니다. bg-blue-500는 여전히 파란색 배경을 생성합니다. 그러나 그 의미는 의미가 있습니다.

OKLCH란?

OKLCH는 Björn Ottosson이 개발한 지각 색상 공간으로 CIE L*a*b* 및 LCH 시스템을 기반으로 합니다. 세 가지 구성 요소는 다음과 같습니다.

OKLCH의 중요한 특성은 지각적 균일성입니다. L 구성 요소의 0.1 변화는 색상에 관계없이 동일한 밝기 변화 크기로 보입니다. HSL에서 노란색은 동일한 L 값에서 본질적으로 파란색보다 가볍기 때문에 항상 수동 조정이 필요했습니다. OKLCH는 이 문제를 대부분 제거합니다.

색상 변환기를 사용하여 OKLCH의 모든 색상을 검사할 수 있습니다. 예를 들어 Tailwind의 blue-500(#3B82F6)는 대략 oklch(0.623 0.214 264.1)로 변환됩니다. teal-500(#14B8A6)는 oklch(0.704 0.14 186.0)입니다. L 값(0.623 대 0.704)은 청록색-500이 파란색-500보다 가벼워 보이는 것을 정확하게 반영합니다. 이는 HSL이 안정적으로 포착하지 못하는 관계입니다.

넓은 색상 영역

Tailwind v4에서는 OKLCH로 색상을 표현함으로써 해당 색상을 지원하는 디스플레이에서 폭넓은 색상을 사용할 수 있습니다. 최신 Apple 디스플레이(P3 색 영역)는 sRGB 영역에서 허용하는 것보다 더 생생한 색상을 재현할 수 있습니다. oklch(0.7 0.3 264)와 같은 CSS 값은 구형 디스플레이에서는 sRGB 영역으로 고정되지만 P3 화면에서는 최대한 생생하게 렌더링됩니다.

@theme {
  /* This color is slightly outside sRGB on P3 displays — full gamut on those screens */
  --color-brand-500: oklch(0.65 0.28 264);
}

Tailwind v4의 내장 팔레트는 호환성을 유지하기 위해 sRGB 내에 유지되지만 작성자가 16진수 대신 OKLCH 값을 작성하여 선택하면 사용자 정의 색상이 넓은 색역을 활용할 수 있습니다.

그라데이션 보간 개선

OKLCH 내부의 눈에 띄는 이점 중 하나는 그라디언트 품질입니다. CSS 그라데이션은 기본적으로 sRGB 공간에서 색상을 보간하므로 많은 색조 간 그라데이션 중간에 나타나는 "흐릿한 회색 밴드" 아티팩트가 생성됩니다. v4에서는 Tailwind의 bg-gradient-to-r 유틸리티를 in oklch 보간 힌트와 결합하여 이 문제를 제거할 수 있습니다.

<!-- v4: smooth gradient from blue to red via oklch interpolation -->
<div class="bg-gradient-to-r from-blue-500 to-red-500 [color-interpolation-method:oklch]">

이는 아직 자동이 아닙니다. color-interpolation-method 속성에는 명시적인 유틸리티 또는 임의의 값이 필요하지만 v4의 OKLCH 인프라는 이를 간단하게 만듭니다.

v4의 새로운 색상 유틸리티 클래스

v4는 내부 아키텍처 변경 외에도 유틸리티 계층에 새로운 기능을 추가합니다.

CSS 가변 색상 불투명도

v3에서는 bg-blue-500/50와 같은 불투명 수정자가 빌드 시 rgba() 값을 구성하여 작동했습니다. v4에서는 이제 동일한 구문이 런타임 시 불투명도에 대한 CSS 사용자 정의 속성을 사용합니다. 즉, 불투명 수정자는 Tailwind 외부에서 정의된 색상을 포함하여 모든 CSS 변수 색상에서 작동합니다.

:root {
  --my-brand-color: #0F766E;
}

<!-- v4: this works even though --my-brand-color is not a @theme variable -->
<div class="bg-[--my-brand-color]/30">...</div>

v3에서는 이 패턴에 해결 방법이 필요했습니다. v4에서는 색상 유틸리티의 임의 CSS 변수 참조가 기본적으로 불투명도 수정자와 구성됩니다.

그라데이션 색상 중지

v4에는 여러 그래디언트 색상 정지점을 보다 표현력 있게 설정하는 기능이 추가되었습니다. 3스톱 그라데이션을 위한 via-* 클래스는 이제 불투명도 수정자를 허용하며 from-*/to-* 위치는 임의의 값으로 설정할 수 있습니다.

<div class="bg-gradient-to-r from-blue-500 from-10% via-purple-500/60 via-50% to-pink-500 to-90%">

이를 통해 Tailwind의 유틸리티 시스템을 벗어나지 않고도 그라데이션 모양을 훨씬 더 정확하게 제어할 수 있습니다.

color-mix() 통합

v4 유틸리티는 임의의 값을 통해 기본 CSS color-mix() 기능을 활용하여 마크업에서 직접 색상 혼합을 활성화할 수 있습니다.

<div class="bg-[color-mix(in_oklch,theme(colors.blue.500)_70%,theme(colors.purple.500))]">

이는 새 테마 변수를 정의하지 않고 일회성 혼합 값에 대해 장황하지만 강력합니다.

v4에서 사용자 정의 색상 등록

v4의 사용자 정의 색상은 생성되는 유틸리티를 결정하는 명명 규칙을 사용하여 @theme 블록에 등록됩니다.

본격적인 등록

Tailwind의 내장 제품군과 일치하는 완전한 11단계 척도를 등록하려면 다음을 수행하세요.

@import "tailwindcss";

@theme {
  --color-cobalt-50:  oklch(0.97 0.01 264);
  --color-cobalt-100: oklch(0.93 0.03 264);
  --color-cobalt-200: oklch(0.87 0.06 264);
  --color-cobalt-300: oklch(0.78 0.10 264);
  --color-cobalt-400: oklch(0.67 0.15 264);
  --color-cobalt-500: oklch(0.57 0.19 264);
  --color-cobalt-600: oklch(0.49 0.18 264);
  --color-cobalt-700: oklch(0.42 0.16 264);
  --color-cobalt-800: oklch(0.34 0.13 264);
  --color-cobalt-900: oklch(0.27 0.10 264);
  --color-cobalt-950: oklch(0.18 0.07 264);
}

Shade Generator를 사용하여 모든 시작 16진수 코드에서 Tailwind 호환 50-950 스케일을 생성하세요. 브랜드의 기본 색상(예: 진한 파란색의 경우 #1D4ED8)을 입력하고 변환기를 사용하여 출력을 OKLCH 값으로 @theme 블록에 복사합니다.

시맨틱 색상 토큰

v4의 @theme는 의미 체계 토큰의 자연스러운 본거지이기도 합니다. 색상은 모양보다는 역할에 따라 설명됩니다.

@theme {
  /* Semantic layer */
  --color-primary:          var(--color-cobalt-600);
  --color-primary-hover:    var(--color-cobalt-700);
  --color-primary-active:   var(--color-cobalt-800);
  --color-surface:          var(--color-neutral-50);
  --color-surface-elevated: var(--color-neutral-100);
  --color-on-surface:       var(--color-neutral-900);
}

이는 모든 구성 요소가 아닌 @theme 매핑만 변경하여 브랜드 변경 후에도 유지되는 의미론적 유틸리티인 bg-primary, text-on-surface 등을 생성합니다.

내장 색상 재정의

내장된 Tailwind 색상을 변경하려면 @theme에서 재정의하면 됩니다.

@theme {
  /* Make blue-500 more indigo-leaning */
  --color-blue-500: oklch(0.56 0.24 270);
}

내장 색상을 완전히 제거하려면(생성된 CSS 크기를 줄이기 위해) initial로 설정하세요.

@theme {
  --color-cyan-*: initial;    /* removes all cyan-* utilities */
  --color-fuchsia-*: initial; /* removes all fuchsia-* utilities */
}

이 glob 구문은 Tailwind v4의 @theme에만 적용되며 임의의 CSS에서는 작동하지 않습니다.

v3에서 v4로 색상 구성 마이그레이션

체계적인 프로세스를 따르면 기존 Tailwind v3 색상 구성을 v4로 마이그레이션하는 것은 간단합니다.

1단계: 공식 업그레이드 도구 실행

Tailwind에서는 업그레이드 코드 모드를 제공합니다.

npx @tailwindcss/upgrade@next

이는 대부분의 상용구를 처리합니다. @theme를 사용하여 새로운 styles.css를 생성하고 theme.extend.colors 값을 여기에 마이그레이션합니다. 출력을 검토합니다. codemod는 복잡한 구성 뒤에 있는 의도를 알지 못하며 OKLCH를 선호하는 곳에 축어적인 16진수 값을 생성할 수 있습니다.

2단계: 색상 값을 OKLCH로 변환(선택 사항이지만 권장됨)

그라데이션에서 조작하거나 사용하려는 색상의 경우 색상 변환기를 사용하여 16진수에서 OKLCH로 변환하세요. 이를 통해 넓은 범위의 기능과 향상된 그라디언트 보간에 액세스할 수 있습니다. 예를 들어:

3단계: resolveConfig 사용법 교체

JavaScript 코드가 Tailwind 구성에서 색상을 가져온 경우:

// v3 pattern — no longer works in v4
const config = require('tailwindcss/resolveConfig')(require('./tailwind.config'))
const blue500 = config.theme.colors.blue[500]

이것을 런타임 CSS 변수 읽기로 바꿉니다.

// v4 pattern
const blue500 = getComputedStyle(document.documentElement)
  .getPropertyValue('--color-blue-500')
  .trim()

DOM 없이 색상 값이 필요한 서버 측 코드의 경우 토큰 이름을 값에 매핑하는 별도의 색상 상수 파일을 정의하고 @theme 블록과 JS 모두에서 해당 파일을 참조하세요.

4단계: 다크 모드 감사

darkMode: 'class' 전략을 사용하는 v3 다크 모드는 .dark를 루트 클래스로 사용했습니다. v4는 기본적으로 CSS @variant dark { @media (prefers-color-scheme: dark) { ... } } 접근 방식을 사용합니다. v3에서 darkMode: 'class'를 사용한 경우 그에 따라 v4 @variant를 설정하십시오.

@import "tailwindcss";

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

이는 v3 클래스 기반 다크 모드 동작을 재현하므로 기존 dark:bg-gray-900 유틸리티가 계속 작동합니다.

5단계: PostCSS 및 Autoprefixer 구성 제거

Tailwind v4는 자체 변환기를 사용합니다. postcss.config.js에 tailwindcss가 플러그인으로 필요한 경우 @tailwindcss/postcss로 교체하세요. autoprefixer를 사용하는 경우 v4는 최신 CSS 공급업체 접두사를 내부적으로 처리하므로 대부분의 프로젝트에서 autoprefixer를 제거할 수 있습니다.

일반적인 마이그레이션 문제

마이그레이션 후 누락된 색상

마이그레이션 후 bg-brand-700 작동이 중지되면 변수가 :root나 일반 CSS 블록이 아닌 @theme에 정의되어 있는지 확인하세요. :root의 변수는 CSS에서 액세스할 수 있지만 Tailwind는 유틸리티를 생성하기 위해 변수를 스캔하지 않습니다. @theme 변수만 유틸리티를 생성합니다.

불투명도 수정자 깨짐

bg-brand-500/80 작동이 중지되면 문제는 일반적으로 색상 값이 16진수 또는 OKLCH 값이 아닌 rgb() 또는 hsl() 함수로 정의되었다는 것입니다. Tailwind v4의 불투명도 수정자 시스템에서는 색상 값이 슬래시를 포함하는 함수(예: rgba(15, 118, 110, 1))가 아닌 원시 색상으로 구문 분석 가능해야 합니다. @theme 값에 16진수 또는 OKLCH를 사용하세요.

플러그인 호환성

tailwindcss-animate 또는 DaisyUI와 같이 Tailwind의 색상 시스템에 연결되는 여러 인기 타사 플러그인에는 v4 호환 릴리스가 있습니다. 마이그레이션하기 전에 각 플러그인의 변경 로그를 확인하세요. npx @tailwindcss/upgrade를 실행하면 호환되지 않는 플러그인이 표시됩니다.

주요 내용

• Tailwind v4는 스타일시트에서 @theme를 사용하여 tailwind.config.js를 CSS 우선 구성으로 대체합니다. 색상 등록은 JavaScript 객체에서 CSS 사용자 정의 속성 선언으로 이동합니다.
• 프레임워크는 이제 내장된 색상을 OKLCH에 내부적으로 저장하여 지각적으로 균일한 밝기 조정, 향상된 그라데이션 보간 및 P3 디스플레이에서 선택적 광색역 색상 출력을 가능하게 합니다.
• 사용자 정의 색상은 전체 유틸리티 클래스 세트를 생성하기 위해 @theme의 명명 규칙 --color-{family}-{step}를 따릅니다. 시맨틱 토큰은 스케일 값을 참조하여 브랜드 친화적인 유틸리티 이름을 만들 수 있습니다.
• 공식 @tailwindcss/upgrade codemod는 v3에서 기계적 마이그레이션의 대부분을 처리하지만 OKLCH 변환 및 다크 모드 전략 변경에는 수동 검토가 필요합니다.
• 색상 생성기를 사용하여 모든 시작 색상에서 완전한 50-950 OKLCH 스케일을 생성하고 색상 변환기를 사용하여 v3 16진수 값을 해당 OKLCH 값으로 변환합니다.