지시문

Markdown으로 보기 GitHub에서 수정 문서 위치 3843abd

지시문은 입력 CSS에서 작성해 Tailwind 출력을 구성하고 확장하며 순서를 지정하는 @ 접두 at-rule입니다. 이 페이지에서는 @apply, @utility, @variant, @custom-variant, @layer을 다룹니다. @theme은 Theme에서, @plugin은 Plugins에서, @source는 @source에서 설명합니다.

`@apply`

@apply은 기존 유틸리티의 선언을 자체 선택자 안에 인라인으로 삽입합니다. 의미 있는 클래스에 유틸리티 스타일을 연결할 때 사용하며, 중첩 선택자와 미디어 쿼리 안에서도 사용할 수 있습니다.

PHP

use TailwindPHP\tw;

$css = tw::generate('<div class="btn">', '
    @import "tailwindcss";

    @theme { --color-brand: #3b82f6; }

    .btn {
        @apply px-4 py-2 rounded-lg bg-brand text-white;
    }
');

변형은 @apply 목록에서 작동합니다. @apply bg-blue-500 hover:bg-blue-600;은 :hover 상태로 확장되고, @apply px-4 md:px-6 lg:px-8; 같은 반응형 접두사는 해당 @media 규칙을 출력합니다. important 수정자도 적용됩니다(@apply !flex;). 중첩 선택자도 지원하므로 .card { h2 { @apply text-xl font-bold; } } 같은 규칙은 중첩된 h2에 유틸리티를 적용합니다.

@apply은 문장입니다. 본문이 있는 @apply px-4 { … }은 오류를 발생시킵니다. 점선 식별자만 나열한 @apply(@apply --my-mixin;)는 유틸리티 목록이 아니라 CSS 믹스인 초안의 CSS 믹스인입니다. 따라서 TailwindPHP으로 확인할 수 없으며, 같은 @apply에 믹스인과 유틸리티를 함께 넣으면 오류가 발생합니다(You cannot use @apply with both mixins and utilities…). 현재 믹스인 규칙은 전달되지 않고 출력에서 제거됩니다(#12).

`@utility`

@utility은 Tailwind 엔진에 참여하는 사용자 지정 유틸리티를 등록합니다. utilities 레이어에 정렬되고 내장 유틸리티처럼 변형을 지원합니다. 정적 유틸리티는 고정된 본문을 사용합니다:

CSS

@utility content-auto {
    content-visibility: auto;
}

실제 유틸리티이므로 변형이 자동으로 조합됩니다(hover:content-auto, md:content-auto). 본문에서 @apply와 중첩 선택자를 사용할 수도 있습니다:

CSS

@utility btn-primary {
    @apply px-4 py-2 bg-blue-500 text-white rounded;
}

@utility card {
    color: red;
    &:hover { color: blue; }
}

기능형 유틸리티는 이름에 -* 접미사를 사용하고 --value()로 일치하는 값을 읽습니다:

CSS

@theme {
    --gutter-wide: 3rem;
}

@utility gutter-* {
    padding-inline: --value(--gutter-*, [length]);
    padding-inline: --spacing(--value(integer));
}

--value()은 후보 값을 각 소스에 차례로 대입해 확인합니다. 테마 네임스페이스(--gutter-*), 데이터 유형이 지정된 임의 값([length]), 또는 단순 값 유형(integer, number, percentage, ratio)입니다. --value()이 확인되지 않는 선언은 제외되므로 선언을 쌓아 대체 값을 지정할 수 있습니다:

클래스	출력
`gutter-wide`	`padding-inline: var(--gutter-wide);`
`gutter-[5px]`	`padding-inline: 5px;`
`gutter-4`	`padding-inline: calc(var(--spacing) * 4);`

--modifier()은 / 뒤의 부분도 같은 방식으로 확인합니다. 본문에 line-height: --modifier(integer);가 있으면 gutter-4/7도 line-height: 7를 출력합니다. 유틸리티 이름은 TailwindCSS v4.3.3 규칙을 따릅니다. /은 최대 하나, %은 숫자 뒤 맨 끝에만 올 수 있으며, 점은 숫자 사이에만 올 수 있습니다.

`@variant`

@variant은 유틸리티를 정의하지 않고 자체 CSS 안의 선언에 변형을 적용합니다:

CSS

.card {
    color: red;

    @variant hover {
        color: blue;
    }

    @variant dark {
        color: white;
    }
}

CSS

.card {
  color: red;
}
@media (hover: hover) {
  .card:hover {
    color: #00f;
  }
}
@media (prefers-color-scheme: dark) {
  .card {
    color: #fff;
  }
}

변형은 쌓아서 사용할 수 있고(@variant hover:focus), 쉼표로 나열하거나 서로 중첩할 수 있으며 자체 @custom-variants를 지정할 수도 있습니다. 최상위 @variant에 본문이 없거나 @slot이 있는 경우 이전 버전과의 호환성을 위해 @custom-variant로 처리합니다.

`@custom-variant`

@custom-variant은 모든 유틸리티 앞에 붙일 수 있는 새 변형을 정의합니다. 간결한 형식은 변형 이름과 괄호 안의 선택자 또는 at-rule을 지정합니다.

선택자 목록 변형에서는 &을 요소 자리표시자로 사용합니다:

CSS

@custom-variant hocus (&:hover, &:focus);

hocus:bg-blue-500은 :hover 규칙과 :focus 규칙을 모두 출력합니다. 속성 형식도 같은 방식으로 작동합니다:

CSS

@custom-variant loading (&[data-loading="true"]);

at-rule 변형은 일치하는 유틸리티를 해당 at-rule로 감쌉니다:

CSS

@custom-variant tablet (@media (min-width: 600px));

사용자 지정 변형은 내장 변형과 조합할 수 있습니다. sm:hocus:bg-blue-500은 sm 미디어 쿼리 안에 hocus 선택자를 중첩합니다. 더 복잡한 경우에는 블록 형식을 사용하고, @slot으로 유틸리티 선언을 삽입할 위치를 지정하세요:

CSS

@custom-variant child {
    & > * {
        @slot;
    }
}

@custom-variant sidebar-open {
    .sidebar-open & {
        @slot;
    }
}

`@layer`

@layer은 네이티브 CSS 캐스케이드 레이어를 사용해 캐스케이드 순서를 제어합니다. 본문이 없는 @layer 문은 레이어 순서를 선언하며, 뒤에 오는 레이어가 선택자 명세도와 관계없이 우선합니다. Tailwind의 표준 순서는 다음과 같습니다:

CSS

@layer theme, base, components, utilities;

이는 @import "tailwindcss"이 내부적으로 설정하는 것과 정확히 같습니다. 직접 순서를 선언하거나 여러 문으로 나눌 수 있으며(@layer reset, base; 다음에 @layer components, utilities;), 블록으로 규칙을 지정된 레이어에 배치할 수 있습니다:

PHP

use TailwindPHP\tw;

$css = tw::generate('<article><h1>Title</h1></article>', '
    @import "tailwindcss";

    @layer base {
        h1 { font-size: var(--text-2xl); }
        a  { color: var(--color-blue-600); text-decoration-line: underline; }
    }
');

@layer base으로 기본 스타일을 추가하면 components과 utilities보다 낮은 우선순위에 배치되어 유틸리티 클래스가 요소 기본 스타일을 항상 덮어씁니다. 유틸리티 아래에 배치할 컴포넌트 클래스의 @layer components { … }에도 같은 방식이 적용됩니다. 익명 레이어와 @import의 layer() 수정자는 Imports에서 다룹니다.

다음 단계

Theme — @theme 토큰과 테마 함수.
Imports — @import, 가상 모듈, layer() 수정자.
Plugins — @plugin 지시문과 플러그인 API.
@source — 스캔할 파일과 클래스를 제어합니다.