함수와 디렉티브

함수와 디렉티브

Tailwind는 CSS 안에서 쓰는 자체 디렉티브(at-rule)들과 빌드 타임 함수들을 제공해요. HTML에는 유틸리티만 쓰고 "설정·확장은 어디에서 하지?" 하는 부분이 바로 이 디렉티브들이에요. @import로 Tailwind를 불러오고, @theme로 토큰을 정의하고, @utility·@custom-variant로 확장을 다루는 흐름이죠. 이 글에서는 v4에서 실제로 쓰는 디렉티브와 함수를 중심으로 정리할게요.

출처: Functions and directives — Tailwind CSS 공식문서

디렉티브

디렉티브는 Tailwind 전용의 커스텀 at-rule이에요. CSS에서 특별한 기능을 제공하죠.

@import

CSS 파일을 인라인으로 가져오는 데 씁니다. Tailwind 자체를 불러올 때도 이걸 사용해요.

@import "tailwindcss";

@theme

프로젝트의 커스텀 디자인 토큰(폰트·색·브레이크포인트 등)을 정의하는 디렉티브예요.

@theme {
  --font-display: "Satoshi", "sans-serif";
  --breakpoint-3xl: 120rem;
  --color-avocado-100: oklch(0.99 0 0);
  --ease-fluid: cubic-bezier(0.3, 0, 0, 1);
}

@source

Tailwind의 자동 콘텐츠 감지로 잡히지 않는 소스 파일을 명시적으로 지정할 때 씁니다.

@source "../node_modules/@my-company/ui-lib";

@utility

hover·focus·lg 같은 변형자와 함께 동작하는 커스텀 유틸리티를 추가하는 디렉티브예요.

@utility tab-4 {
  tab-size: 4;
}

@variant

커스텀 CSS 안에서 Tailwind 변형자를 적용할 때 씁니다.

.my-element {
  background: white;
  @variant dark {
    background: black;
  }
}

@custom-variant

프로젝트에 커스텀 변형자를 추가하는 디렉티브예요. 아래처럼 정의하면 theme-midnight:bg-black, theme-midnight:text-white 같은 유틸리티를 쓸 수 있어요.

@custom-variant theme-midnight (&:where([data-theme="midnight"] *));

@apply

기존 유틸리티 클래스를 자신이 만든 CSS에 인라인으로 끌어다 쓸 때 사용해요.

.select2-dropdown {
  @apply rounded-b-lg shadow-md;
}
.select2-results__group {
  @apply text-lg font-bold text-gray-900;
}

서드파티 라이브러리 스타일을 오버라이드하는 커스텀 CSS를 쓰면서도, 테마 토큰과 HTML에서 쓰던 것과 같은 문법을 유지하고 싶을 때 유용해요.

@reference

Vue·Svelte 컴포넌트의 <style> 블록이나 CSS 모듈 안에서 @apply·@variant를 쓰려면, 그 테마 변수·커스텀 유틸리티·커스텀 변형자를 그 컨텍스트에서 쓸 수 있게 해야 해요. @reference는 메인 스타일시트를 출력에 중복 없이 참조만 가져옵니다.

<style>
  @reference "../../app.css";
  h1 { @apply text-2xl font-bold text-red-500; }
</style>

커스터마이징 없이 기본 테마만 쓴다면 @reference "tailwindcss";로 바로 참조할 수도 있어요. CLI·Vite·PostCSS 환경에서는 package.json의 imports 매핑을 따르는 서브패스 임포트("#app.css" 같은 형식)도 지원합니다.

함수

빌드 타임에 동작해 색과 간격 스케일을 다루기 쉽게 해 주는 함수들이에요.

--alpha()

색의 투명도를 조절하는 함수예요.

/* 입력 */
.my-element { color: --alpha(var(--color-lime-300) / 50%); }

/* 컴파일 결과 */
.my-element { color: color-mix(in oklab, var(--color-lime-300) 50%, transparent); }

--spacing()

테마에 기반한 간격 값을 생성하는 함수예요. --spacing(4)는 calc(var(--spacing) * 4)로 컴파일돼요.

.my-element { margin: --spacing(4); }

임의 값 안에서 calc()와 함께 쓰는 것도 가능해요. py-[calc(--spacing(4)-1px)] 같은 식이죠.

v3 호환 디렉티브

아래 디렉티브·함수는 Tailwind v3.x와의 호환을 위한 것이에요. @config·@plugin은 @theme·@utility 등 CSS 기반 기능과 함께 쓸 수 있고, CSS에 정의된 것이 우선해요.

@config

레거시 JavaScript 기반 설정 파일을 불러오는 디렉티브예요. 다만 v4.0에서 corePlugins·safelist·separator 옵션은 지원되지 않아요. 유틸리티를 safelist 하려면 v4에선 @source inline()을 사용해요.

@config "../../tailwind.config.js";

@plugin

레거시 JavaScript 기반 플러그인을 불러오는 디렉티브예요. 패키지 이름이나 로컬 경로를 받아요.

@plugin "@tailwindcss/typography";

theme()

점 표기법으로 Tailwind 테마 값을 가져오는 함수예요. theme(spacing.12)처럼 쓰지만 deprecated 상태라, CSS 테마 변수를 쓰는 쪽을 권장해요.

.my-element { margin: theme(spacing.12); }

더 알아보기 (Learn more)