Tailwind v4 @theme, @utility, @layer utilities

[sgoldenbird]

📌 배운 내용

• Tailwind CSS v4에서 도입된 @theme, @utility, 그리고 기존의 @layer utilities의 개념을 정확히 이해하고, 커스텀 유틸리티 작성 시 각각의 역할과 차이를 구분할 수 있게 되었습니다.

---

🔍 배경 / 문제 상황

Tailwind CSS를 커스터마이징하는 과정에서 글씨 크기를 text-1, text-2 처럼 직관적으로 쓰고 싶었는데,
cn함수를 사용하며 text-* 네이밍은 Tailwind 기본과 충돌해 문제가 발생했습니다.
그래서 font-size-1, font-size-2 같은 네이밍으로 바꾸고 싶었고, 여기서 Tailwind v4의 @theme + @Utility 조합이 필요하다는 걸 알게 되었습니다.

---

✅ 핵심 정리 / 해결 방법

문제를 해결하기 위해 Tailwind의 디자인 시스템에 맞춰 유틸리티를 재정의했습니다.

1. @theme — 테마 변수 추출

• 역할: tailwind.config.ts의 theme 값을 CSS 변수로 노출
• 효과: CSS 안에서 theme 값을 그대로 사용할 수 있음

@theme {
  --font-size-10: 1rem;
  --font-size-11: 1.1rem;
  --font-size-12: 1.2rem;
  /* ... */
  --font-size-150: 15rem;
}

2. @Utility — 단일 유틸리티 클래스 정의

역할: 단 하나의 속성을 정의하는 Tailwind 유틸리티 작성 전용
장점: Tailwind의 충돌 해결 로직(cn 포함)과 호환됨

@utility font-size-* {
  font-size: --value(--font-size-*);
}

➡️ font-size-10, font-size-11 같은 클래스가 자동 생성되고
cn('font-size-10', 'font-size-12')에서도 Tailwind 규칙대로 올바르게 충돌이 해소됩니다.

3. @layer utilities — 다수의 유틸리티 정의

역할: 여러 개의 커스텀 유틸리티를 정의할 때 사용
특징: theme() 함수 직접 사용 불가 → 대신 @theme에서 정의한 CSS 변수를 참조해야 함

@layer utilities {
  .flex-center {
    @apply flex items-center justify-center;
  }

  .scrollbar-none {
    -ms-overflow-style: none;
    scrollbar-width: none;
  }

  .scrollbar-none::-webkit-scrollbar {
    display: none;
  }
}

최종 구조 예시

@import 'tailwindcss';

/* 1. 테마 변수 정의 */
@theme {
  --font-size-10: 1rem;
  --font-size-11: 1.1rem;
  /* ... */
  --font-size-150: 15rem;
}

/* 2. 단일 유틸리티 */
@utility font-size-* {
  font-size: --value(--font-size-*);
}

/* 3. 다중 유틸리티 */
@layer utilities {
  .flex-center {
    @apply flex items-center justify-center;
  }
}

✅ 핵심 차이 요약

구문	목적	theme() 사용 가능	특징
@theme	테마 값을 CSS 변수로 추출	✅ 가능	변수 정의 전용
@utility	단일 유틸리티 클래스 정의	✅ 가능	패턴 기반 클래스 정의, Tailwind 충돌 규칙과 호환
@layer utilities	여러 유틸리티 클래스 정의	❌ 불가	단순 유틸리티 모음 정의용, CSS 변수/하드코딩 값 사용

---

🤔 왜 @utility를 써야 할까? → 패턴 인식

Tailwind는 text-*, bg-*, font-size-*처럼 패턴 기반 유틸리티를 정의해 두고,
같은 속성에 해당하는 클래스들이 동시에 존재하면 마지막 것만 남도록 충돌 로직을 적용합니다.

@Utility로 작성하면 font-size-* 패턴이 Tailwind에 등록됨

@utility font-size-* {
  font-size: --value(--font-size-*);
}

@layer utilities로 작성하면 Tailwind 입장에서는 그냥 두 개의 커스텀 클래스

@layer utilities {
  .font-size-10 { font-size: 1rem; }
  .font-size-12 { font-size: 1.2rem; }
}

---

@Utility vs @layer utilities 차이점

1. 정의 단위

• @Utility: 단일 클래스만 정의 가능
  • 선언할 때마다 클래스 1개를 생성하는 게 원칙
  • 하지만 @utility font-size-*처럼 패턴을 주면 다수의 변형 클래스 생성 가능
• @layer utilities: 한 블록 안에서 여러 개 클래스 정의 가능
  • 자유도 높음 → 기존 CSS 작성하듯이 원하는 만큼 정의

2. 테마 값 사용

• @Utility: theme() 함수와 @theme 변수를 직접 사용 가능

  @utility text-brand {
    color: theme(colors.blue.500);
  }

• @layer utilities: theme() 함수 직접 사용 불가 → 반드시 @theme에서 노출한 변수를 참조해야 함

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

3. 충돌 인식 (패턴 지원)

• @Utility: Tailwind의 패턴 기반 충돌 로직에 포함됨

  cn('font-size-10', 'font-size-12') // → 마지막 값만 남음

• @layer utilities: 단순한 커스텀 클래스라 충돌 인식 없음

  cn('font-size-10', 'font-size-12') // → 두 클래스 다 적용됨 (순서 의존적)

4. DX (개발 경험)

• @Utility

  • 간결하고 선언적
  • 테마 값과 직접 연결 가능 → 디자인 토큰 기반 작업에 유리
  • 패턴 기반 확장성 (font-size-*, color-* 등)

• @layer utilities

  • 자유도가 높음 (여러 클래스 한 번에 정의 가능)
  • @apply 같은 Tailwind 도우미 사용 가능 (flex-center, scrollbar-none 등)
  • theme() 직접 접근 불가라는 제약 있음

요약

구분	@Utility	@layer utilities
정의 단위	단일 클래스	여러 클래스
theme() 사용	✅ 가능	❌ 불가 (CSS 변수 필요)
충돌 인식	✅ O (패턴 지원)	❌ X
활용 사례	font-size-*, color-*, spacing-* 같은 패턴 속성	flex-center, scrollbar-none, rotate-y-180 같은 개별 유틸리티 모음

결론

• 패턴 기반 속성 (font-size-, spacing-, color-*) → 반드시 @Utility
• 단순한 유틸리티 모음 (flex-center, scrollbar-none) → @layer utilities

---

🧠 느낀점 또는 생각 메모

Tailwind v4는 기존의 @layer 중심 방식에서 더 발전해, 테마 값 → 유틸리티 생성 흐름을 @theme와 @utility로 분리해준다는 것을 알았습니다.
특히 @Utility는 Tailwind의 패턴 인식 기반 충돌 해결 로직과 연결되어 있어, cn 같은 함수와 함께 사용할 때도 일관되게 작동한다는 점이 핵심 배움이었습니다.

실무적으로는

• 여러 개 유틸리티 클래스 정의가 필요할 때는 @layer utilities
• theme 값을 반영한 단일 유틸리티는 @theme → @utility

이렇게 나눠 적용하는 것이 가장 깔끔하고 유지보수에 적합하다고 느꼈습니다.

---

📚 래퍼런스

• Tailwind CSS v4 Migration Guide
• Tailwind CSS - @theme 지시어 문서
• Tailwind CSS - @utility 지시어 문서
• Tailwind CSS - Layers (@layer)