# 지시문

지시문은 입력 CSS에서 작성해 Tailwind 출력을 구성하고 확장하며 순서를 지정하는 `@` 접두 at-rule입니다. 이 페이지에서는 `@apply`, `@utility`, `@variant`, `@custom-variant`, `@layer`을 다룹니다. `@theme`은 [Theme](https://tailwindphp.inline0.dev/ko/docs/usage/theme)에서, `@plugin`은 [Plugins](https://tailwindphp.inline0.dev/ko/docs/plugins)에서, `@source`는 [@source](https://tailwindphp.inline0.dev/ko/docs/usage/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 믹스인 초안](https://drafts.csswg.org/css-mixins-1/#apply-rule)의 CSS 믹스인입니다. 따라서 TailwindPHP으로 확인할 수 없으며, 같은 `@apply`에 믹스인과 유틸리티를 함께 넣으면 오류가 발생합니다(`You cannot use @apply with both mixins and utilities…`). 현재 믹스인 규칙은 전달되지 않고 출력에서 제거됩니다([#12](https://github.com/inline0/tailwindphp/issues/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-variant`s를 지정할 수도 있습니다. 최상위 `@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](https://tailwindphp.inline0.dev/ko/docs/usage/imports)에서 다룹니다.

## 다음 단계

- [Theme](https://tailwindphp.inline0.dev/ko/docs/usage/theme) — `@theme` 토큰과 테마 함수.
- [Imports](https://tailwindphp.inline0.dev/ko/docs/usage/imports) — `@import`, 가상 모듈, `layer()` 수정자.
- [Plugins](https://tailwindphp.inline0.dev/ko/docs/plugins) — `@plugin` 지시문과 플러그인 API.
- [@source](https://tailwindphp.inline0.dev/ko/docs/usage/source) — 스캔할 파일과 클래스를 제어합니다.