ディレクティブ
ディレクティブは、入力CSSに記述してTailwindの出力を組み合わせ、拡張し、順序付ける、@で始まるat-ruleです。このページでは@apply、@utility、@variant、@custom-variant、@layerを説明します。@themeはテーマ、@pluginはプラグイン、@sourceは@sourceで説明しています。
@apply
@applyは既存ユーティリティの宣言を独自のセレクターにインライン化します。ネストしたセレクターやメディアクエリ内も含め、セマンティックなクラスにユーティリティのスタイルを適用できます。
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レイヤーに並び、組み込みと同じようにバリアントを使えます。静的ユーティリティでは固定の本文を指定します。
@utility content-auto {
content-visibility: auto;
}
通常のユーティリティなので、バリアントは自動的に合成されます（hover:content-auto、md:content-auto）。本文では@applyやネストしたセレクターも使えます。
@utility btn-primary {
@apply px-4 py-2 bg-blue-500 text-white rounded;
}
@utility card {
color: red;
&:hover { color: blue; }
}
機能的ユーティリティは、名前に-*の接尾辞を使い、--value()で一致した値を読み取ります。
@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ルールに従います。/は最大1つ、%は末尾の数字の後にのみ置け、ドットは数字の間にのみ置けます。
@variant
@variantは、ユーティリティを定義せずに、独自のCSS内の宣言にバリアントを適用します。
.card {
color: red;
@variant hover {
color: blue;
}
@variant dark {
color: white;
}
}
.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は、新しいバリアントを定義し、任意のユーティリティの前に付けられるようにします。簡略形式では、バリアント名とセレクターまたはアットルールを括弧内に指定します。
セレクターリストのバリアントでは、要素を表すために&を使います。
@custom-variant hocus (&:hover, &:focus);
hocus:bg-blue-500は続いて:hoverルールと:focusルールの両方を出力します。属性形式も同じように使えます。
@custom-variant loading (&[data-loading="true"]);
アットルールのバリアントは、一致したユーティリティをそのアットルールで囲みます。
@custom-variant tablet (@media (min-width: 600px));
カスタムバリアントは組み込みバリアントとスタックできます。sm:hocus:bg-blue-500はsmメディアクエリ内にhocusセレクターをネストします。より複雑なケースでは、@slotでユーティリティの宣言を挿入する位置を示すブロック形式を使います。
@custom-variant child {
& > * {
@slot;
}
}
@custom-variant sidebar-open {
.sidebar-open & {
@slot;
}
}
@layer
@layerは、ネイティブのCSSカスケードレイヤーを使ってカスケード順序を制御します。単独の@layerステートメントでレイヤーの順序を宣言すると、セレクターの詳細度にかかわらず、後のレイヤーが優先されます。Tailwindの標準的な順序は次のとおりです。
@layer theme, base, components, utilities;
@import "tailwindcss"は、内部でまさにこの設定を行います。独自の順序を宣言するか、複数のステートメント（@layer reset, base;の後に@layer components, utilities;）に分けて指定できます。また、ブロックを使ってルールを名前付きレイヤーに割り当てられます。
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を参照してください。