[Next.js] TailwindCSS v4에서 CSS 변수로 커스텀 유틸리티 만들기

오프닝

 

TailwindCSS를 사용하다 보면 “우리 프로젝트만의 색상, 폰트, 여백” 등을 디자인 시스템처럼 통일해서 쓰고 싶을 때가 많다.

 

Tailwind v4에서는 CSS 변수를 활용해서 커스텀 유틸리티 클래스를 만드는 방식이 굉장히 자연스럽고 강력해졌다.

 

오늘은 CSS 변수로 나만의 Tailwind 유틸리티를 만드는 패턴을 정리해보고자 한다.

 

 

 

 

1. Tailwind v4에서 커스텀 스타일을 만드는 2가지 단계

 

🔹 1단계: :root에서 CSS 변수 선언

: 먼저, globals.css 혹은 layout 레벨에서 CSS 변수를 정의한다.

:root {
  --primary: #4F46E5;
  --secondary: #22D3EE;
  --foreground: #171717;
}

→ 이 부분은 우리만의 디자인 토큰을 선언하는 영역이라고 보면 된다.

 

 

🔹 2단계: @layer utilities로 유틸리티 클래스 정의

: Tailwind v4에서는 @layer를 통해 커스텀 유틸리티 클래스를 추가할 수 있습니다.

@layer utilities {
  .text-primary {
    color: var(--primary);
  }

  .bg-primary {
    background-color: var(--primary);
  }

  .text-secondary {
    color: var(--secondary);
  }
}

 

이렇게 하면 Tailwind에서 기본 제공하는 유틸리티 클래스처럼 className=“bg-primary” 이런 식으로 사용할 수 있다.

 

 

 

2. 왜 이렇게 사용하는가?

 

Tailwind의 theme.extend.colors를 활용해서 색상을 등록할 수도 있지만, CSS 변수 방식은 다크모드, 테마 전환, 유동적인 디자인 시스템에 훨씬 유리한 패턴이다.

• CSS 변수만 바꿔주면 전체 스타일이 즉시 반영됨
• prefers-color-scheme 대응이 쉬움
• 테마 토글 (다크모드/라이트모드 등)을 만들 때 간단하게 구현 가능

 

 

 

3. 사용 예시 (Component)

export default function Button() {
  return (
    <button className="bg-primary text-white px-4 py-2 rounded-md">
      Primary Button
    </button>
  );
}

→ 완전히 Tailwind 유틸리티 쓰듯 자연스럽게 쓸 수 있다.

 

 

 

4. 핵심 포인트 요약

순서	설명
1단계	:root { --primary: #4F46E5; } 형태로 CSS 변수 선언
2단계	@layer utilities { .bg-primary { background-color: var(--primary); } }로 유틸리티 클래스 정의
장점	테마 시스템 구축, 다크모드 대응, 유지보수 편리

 

 

 

마무리

 

Tailwind v4에서는 더 이상 theme.extend에 모든 걸 넣지 않고, CSS 변수를 기반으로 한 커스텀 유틸리티 클래스 패턴이 훨씬 더 실용이다.

 

이 패턴을 잘 익혀두면, 다크모드 토글, 사용자 커스텀 테마, 실시간 스타일 변경까지 깔끔하게 대응할 수 있으니 꼭 한 번 적용해보자!