[CSS] TailwindCSS 4.x에서 theme 커스터마이징

기존 Tailwind CSS 프로젝트에서 커스텀 스타일을 적용하는 주된 방법은 tailwind.config.js 파일의 theme.extend 옵션을 활용하는 것이었다. 작업중 이전 프로젝트에서 하던대로 작성을 하고 있었는데, 제대로 작동이 되지 않았다. 알고보니 최신 버전에서는 테마 변수(Theme Variables) 와 @theme 지시어를 도입하여 CSS 내에서 직접 테마를 확장하고 커스텀하는 방식을 사용하고 있었고, 이 방식을 사용하여 해결하였다.

테마 변수와 @theme 지시어란?

Tailwind CSS 공식 문서(Theme variables - Customizing your theme)에 따르면, 테마 변수는 @theme 지시어를 사용하여 정의하는 특별한 CSS 변수이다. 이 변수들은 프로젝트에서 사용 가능한 유틸리티 클래스 생성에 직접적인 영향을 미친다. 즉, CSS 파일 내에서 @theme 블록을 사용하여 새로운 색상, 간격, 폰트 크기 등을 정의하면, Tailwind가 자동으로 해당 값에 대응하는 유틸리티 클래스(예: bg-new-color, text-new-color)를 만들어준다.

테마 변수 정의 및 유틸리티 클래스 생성 예시:

예를 들어, 프로젝트의 기본 CSS 파일(app.css 등) 내에서 'mint'라는 새로운 색상을 추가하고 싶다고 가정해보자. @theme 블록 안에 --color-{이름}-{명도} 형식으로 테마 변수를 정의할 수 있다.

@import "tailwindcss"; /* 기본 Tailwind 스타일 임포트 */

@theme {
  /* 새로운 'mint' 색상에 대한 테마 변수 정의 */
  --color-mint-500: oklch(0.72 0.11 178);
}

이렇게 --color-mint-500 테마 변수를 정의하는 것만으로, Tailwind는 빌드 시점에 이 변수를 인식하고 관련된 유틸리티 클래스들을 자동으로 생성한다. 이제 HTML 마크업에서 다음과 같이 새로 생성된 클래스들을 사용할 수 있다.

<!-- 새로 정의된 'mint' 색상 유틸리티 클래스 사용 -->
<div class="bg-mint-500 text-white p-4 rounded">
  민트색 배경과 흰색 텍스트
</div>

<button class="border-mint-500 hover:bg-mint-500/10 border-2 rounded px-3 py-1">
  민트색 테두리 버튼
</button>

일반 CSS 변수로서의 활용:

테마 변수의 또 다른 장점은 일반적인 CSS 커스텀 속성(변수)으로도 동시에 생성된다는 점이다. 따라서 var() 함수를 사용하여 CSS 코드 어디에서든 이 값을 참조할 수 있다.

<!-- 생성된 CSS 변수를 인라인 스타일에서 직접 사용 -->
<div style="background-color: var(--color-mint-500); color: white; padding: 1rem; border-radius: 0.25rem;">
  인라인 스타일에서 var(--color-mint-500) 사용
</div>

<!-- 임의 값 문법 내에서 CSS 변수 사용 -->
<div class="h-32 w-32 bg-[var(--color-mint-500)]">
  임의 값 배경색
</div>

커스텀 CSS에서 테마 변수 활용하기

Tailwind는 기본 테마 값들(폰트 크기, 색상, 간격 등)에 해당하는 CSS 변수들을 자동으로 생성해준다. 예를 들어, 폰트 크기 text-base는 --text-base 변수로, 색상 gray-700은 --color-gray-700 변수로 접근할 수 있다.

다음은 @layer components를 사용하여 마크다운 콘텐츠의 기본 타이포그래피 스타일을 정의하는 예시이다. var() 함수를 통해 Tailwind의 테마 변수를 참조하여 일관된 스타일을 적용한다.

@import "tailwindcss";

/* 필요에 따라 @theme 블록으로 커스텀 변수 정의 */
/* @theme { ... } */

@layer components {
  /* .typography 클래스 하위 요소들의 기본 스타일 정의 */
  .typography {
    p {
      font-size: var(--text-base); /* Tailwind의 기본 텍스트 크기 변수 */
      color: var(--color-gray-700); /* Tailwind의 회색 계열 색상 변수 */
      line-height: theme(lineHeight.relaxed); /* theme() 함수도 사용 가능 */
    }
    h1 {
      font-size: var(--text-2xl); /* 2xl 텍스트 크기 변수 */
      /* line-height는 변수 이름에 포함될 수 있음: --text-2xl--line-height */
      font-weight: var(--font-weight-semibold); /* semibold 굵기 변수 */
      color: var(--color-gray-950); /* 더 어두운 회색 변수 */
      margin-bottom: theme(spacing.4); /* theme() 함수로 간격 참조 */
    }
    h2 {
      font-size: var(--text-xl); /* xl 텍스트 크기 변수 */
      font-weight: var(--font-weight-semibold);
      color: var(--color-gray-950);
      margin-top: theme(spacing.8);
      margin-bottom: theme(spacing.3);
    }
    /* 다른 요소들(a, ul, li, code 등)에 대한 스타일 추가... */
  }
}

이렇게 정의된 .typography 클래스를 마크다운 콘텐츠를 감싸는 최상위 요소에 적용하면, 내부의 <h1>, <p> 등의 태그들이 @layer components에 정의된 스타일을 따르게 된다.

컴포넌트 내 <style> 블록에서의 활용

Svelte나 Vue 같은 컴포넌트 기반 프레임워크에서는 각 컴포넌트의 <style> 블록 내에서도 @theme 지시어를 사용하여 Tailwind의 기본 테마 값(예: 기본 색상 팔레트, 폰트 크기 등)을 참조하고 이를 CSS 변수로 활용할 수 있다. 이를 위해서는 <style> 태그에 lang="postcss" 속성을 추가해야 할 수 있다.

<div class="component-specific-style p-4">
  컴포넌트 고유 스타일
</div>

<style lang="postcss">
  /* Tailwind의 기본 색상 테마를 참조 */
  @theme "tailwindcss/colors";

  .component-specific-style {
    /* 참조된 테마의 값을 CSS 변수로 사용 */
    background-color: var(--color-indigo-100);
    border: 1px solid var(--color-indigo-400);
    color: var(--color-indigo-800);
    border-radius: theme(borderRadius.lg); /* 기존 theme() 함수도 여전히 사용 가능 */
  }
</style>

참고 자료

• Theme variables - Customizing your theme