インポート

@import はスタイルシートを配信し、その定義を利用可能にします。ローカルのコンパイルに定義が必要でも、ネイティブスタイルシートを別の出力が配信する場合は @reference を使います。アプリの設定はインストール、ルート別の所有関係はルート単位のスタイルを参照してください。

両ローカル出力で bg-brand を使います。インポートはネイティブの .card 規則を配信し、参照は定義だけを利用可能にします。ローカルで使うトークンはどちらの出力でも出力できます。

テキストによる説明

1. tokens.css は @theme で --color-brand を宣言し、それを参照するネイティブの .card 規則も定義します。両コンパイルの違いは @import と @reference だけです。
2. 両ローカル出力は bg-brand を生成し、依存先の --color-brand を保持します。
3. .card を含むのは import の出力だけです。参照はその規則をローカル使用の起点にせず、参照先のスタイルシートも公開しません。
4. 分岐はコンパイル結果の比較で、実行時の読み込み手順ではありません。ネイティブの上書きにも実際のスタイルシート配信が必要です。

@import "@master/css"

このパッケージのインポートが唯一のプロジェクトエントリーマーカーです。安定したレイヤー順序とベーススタイルを含むプリセットのネイティブ CSS を読み込み、生成ユーティリティ CSS を受け取るスタイルシートを特定します。

@import "@master/css";

明示的な単独のコンパイラー API と manifest API も利用できます。manifest だけではネイティブ CSS を読み込みません。ランタイムやサーバーレンダリングを使うアプリも、必要なネイティブスタイルシートを配信する必要があります。

ローカルファイル URL

Node のファイルコンパイルは CSS のエスケープと大文字小文字の規則でインポート名を読みます。相対 @import と @reference のパス名はソースファイルを基準に解決し、パーセントエスケープはファイル名の文字を表し、クエリ文字列とフラグメントはファイルシステムのパスから除きます。たとえば "./tokens%20%23.css?v=1#theme" は同じディレクトリの tokens #.css を読みます。既存の "tokens.css" のような接頭辞なしの相対 CSS パスも展開します。対応するローカルファイルのないパッケージインポートはホストのリゾルバーで引き続き解決できます。参照ファイルはコンパイル時の文脈であり、ネイティブ CSS は出力しません。用意された仮想スタイルシートでは、ホストが明示したファイルシステムのソース所有者が相対 CSS 参照の基準にもなります。参照されたテーマトークンのリソースは、別の場所で使っても参照ファイルを基準とします。

スタイルシートの境界とリソース URL

インポートの media、supports、layer 修飾は読み込むスタイルシートに適用されます。CSS の公開時もこの境界を保ち、画像とフォントの URL は元のソースファイルから解決してください。@reference で使うトークンも定義ファイルをリソースの所有者として保持します。

グローバルな Master 定義は修飾のないインポートまたは参照に置きます。修飾付きインポートには、すでに利用可能な ミックスイン を適用するネイティブ規則を含め、ネイティブ CSS を入れられます。ただし @theme、@utility、@mixin、@custom-media、@custom-container の定義は登録できません。

@import "./tokens.css";@import "./print.css" print;@import "./components.css" layer(components);

各 @import はスタイルシートを再びインライン化するため、複数箇所から読み込むと同じファイルが繰り返されます。1 つのインポートグラフでインライン化できる上限は 10,000 スタイルシート、64 MiB の CSS です。共有ファイルは利用する各ファイルからではなく 1 回だけ読み込んでください。

定義やスキャン用メタデータを読み込んでもファイルは公開されません。CLI のファイル書き出しと Vite の本番ビルドは必要なスタイルシートとリソースを公開します。独自のコンパイラーホストは配信 API が返す全アセットを公開する必要があり、manifest だけではネイティブ規則を配信しません。レンダリングとスタイルシート配信およびコンパイラーのエントリーポイントを参照してください。

全アセットを公開する

コンパイルした CSS エントリーにも他の CSS インポートや画像・フォントの参照が残る場合があります。エントリーのテキストだけを公開すると依存先を取得できません。返された各 URL とインポート修飾を保ってください。外部インポートを含む子を平坦化すると、読み込み順や条件のスコープが変わる場合があります。

エントリーから子スタイルシート、その画像へ参照をたどります。それぞれ別の配信ファイルで、print 修飾はインポートに残ります。名前は例であり、生成ファイル名の規則ではありません。

テキストによる説明

1. 配信する app.css は print 修飾で print.css を読み込みます。子は別のスタイルシートのままで、修飾もインポートに残ります。
2. print.css 内の宣言は、子スタイルシートの配信 URL を基準に mark.svg を相対参照します。
3. エントリー、子スタイルシート、画像を各参照先の URL で公開します。app.css だけをコピーすると依存先 2 つが取得できません。
4. 図は依存グラフであり、リクエストのウォーターフォールではありません。実際の生成名やアセットを別に保つかはコンパイルとホストで決まります。

本番での平坦化はカスケードを保ちます。レイヤー文は元の位置に残り、layer()、supports()、media 修飾は同等の @layer、@supports、@media ブロックに変わり、空のスタイルシートは消えます。先行するものが他の外部インポートだけなら、先頭の外部インポートはスタイルシートとともに上に移動します。修飾の下に namespace やインポートを保持する場合、または外部インポートがインライン化した規則の後になる場合、そのスタイルシートは別ファイルのままです。@import は規則の後に置けないため、同じファイルでその前にあるインポートも別ファイルに残します。

画像とフォントは、@reference 経由のリソースも含め、定義元のスタイルシートをソース所有者として保ちます。公開時に URL を書き換え、クエリ文字列とフラグメントは保持します。参照専用のスタイルシートは、定義を読んだだけでは公開しません。

CLI の --no-export はアセットをコピーせず CSS を表示します。ファイル書き出しの監視モードでは、インポート先やリソースがない場合、最後に成功した出力を保ち、エラーを報告し、復旧後に再ビルドします。古い出力を最新ビルドの成功とみなさないでください。

独自ホストはコンパイラーの配信契約を参照してください。Vite の処理済みテキスト、元ソース、URL のインポートはスタイルシートの読み込み、ローカルスタイルシートを所有するページはルート単位のスタイルで説明します。

@reference

別のスタイルシートの定義がコンパイルに必要でも、ネイティブ規則はインポートしない場合に参照を使います。この例はアプリのエントリーから余白トークンとセレクターの ミックスイン を読み込みます。

@import "@master/css";@mixin --manual-dark {  &:where([data-theme="dark"], [data-theme="dark"] *) {    @contents;  }}

@reference "../app.css";.button {  padding: var(--spacing-md);  @apply --manual-dark {    color: white;  }}

参照はトークン、ユーティリティ、ミックスイン、独自メディア、独自コンテナー、ネイティブキーフレームの定義を解決に供給します。参照先のネイティブ CSS を配信せず、クラスを生成せず、スキャン元も加えません。使用する管理対象トークンやキーフレームの依存先はローカル出力に含まれ得ます。参照されたネイティブ規則は使用の起点になりません。ネイティブの上書きには実際の @import か別途配信するスタイルシートが必要です。参照されたキーフレームはローカルで使う場合だけ出力します。

両ケースは同じファイルを参照し、ローカルの使用だけが変わります。出力抜粋では外側の theme レイヤーを省略しています。

テキストによる説明

1. 参照先は --color-accent と .remote { color: var(--color-accent); } を定義します。配信しないネイティブ規則は使用の起点ではありません。
2. 参照だけでは、トークンを利用可能にするものの、ネイティブ規則は配信せず、そのためだけにトークンを保持もしません。
3. .local { color: var(--color-accent); } を加えるとローカルの参照元がトークンを保持します。出力は引き続き .remote をコピーしません。

参照は引用符付きのリソースを 1 つ持つ最上位の文でなければなりません。相対パスは宣言元のスタイルシートのディレクトリが基準です。パッケージ参照はエクスポートされた CSS エントリーを解決します。参照はエントリーマーカーではありません。

Vite、Next.js、Webpack はローカルスタイルシート、CSS Modules、SFC のスタイルにプロジェクトの定義文脈を供給します。その外の依存先や単独のコンパイルには明示的な参照が便利です。ローカルスタイルシートはスキャンやプルーニングの起点にはなりません。CSS Modules やスコープ付きホストは、生成するテーマセレクターをグローバルに配信する必要があります。

定義文脈はローカル定義の前に読み込むため、ローカル定義がインポートや参照の定義を置き換えられます。CSS 出力を分割するコンパイラーホストは、共有変数とキーフレームをどの出力が配信するかも追跡する必要があります。コンパイラーのリソース所有権を参照してください。