診断とツール

{
  "wind": {
    "spec": 1,
    "reset": "none",
    "strict": false,
    "tokens": {
      "spacingUnit": "0.25rem"
    },
    "breakpoints": {},
    "defaultTransitionTimingFunction": "ease",
    "authoredClasses": {},
    "safelist": {}
  }
}

{
  "wind": {
    "spec": 1,
    "reset": "none",
    "strict": true,
    "tokens": {
      "spacingUnit": "0.25rem"
    },
    "breakpoints": {},
    "defaultTransitionTimingFunction": "ease",
    "authoredClasses": {},
    "safelist": {}
  }
}

{
  "wind": {
    "spec": 1,
    "reset": "none",
    "strict": true,
    "tokens": {},
    "breakpoints": {},
    "defaultTransitionTimingFunction": "ease",
    "authoredClasses": {},
    "safelist": {
      "docs-preview": [
        "p-4"
      ]
    }
  }
}

候補の 4 つの結果

候補には次の 4 種類の結果があります。

クラス属性内の site-header のようにユーティリティの基部を持たない名前は、通常の CSS クラスのテキストとして残ります。カタログの基部で始まる名前は、接尾辞を調べる前に最長一致する基部で解決します。たとえば text-link は text ユーティリティとして扱われ、色またはフォントサイズの対応するトークンがなければ ZW006 になります。同様に、bg-panel、border-soft、font-title のような手書きの名前は、CSS 側で所有するなら予約が必要です。すべての未知の名前を通常のクラスとみなすのではなく、綴り間違いや未設定のユーティリティを見つけるための厳格な分類です。確信度の低い完全なリテラルでも、有効ならルールを生成できますが、無効でもビルドは失敗しません。明示的なセーフリストとマニフェストの項目は厳格に扱います。

診断コード

診断レコードには、利用可能な候補、重大度、コード、発生元、メッセージ、任意の提案と拒否 ID が残ります。発生元は種類ごとに構造化されます。

出現情報は保持され、発生元、オフセットまたはキー・番号、コード、候補のバイト列の順に並びます。

診断出力の読み方

zfb build、zfb dev、zfb css は、診断を 1 行に 1 つずつ source:line:column: CODE candidate: message の形で出力します。行は 1 始まり、列は 1 始まりのバイト列です。そのため、同じ行の前にある ASCII 以外の文字は UTF-8 のバイト数で数えます。CRLF の改行は 1 つの改行として数えます。ソース上の位置がない候補は、node_modules/widgets/wind.json (manifest widgets[2]) や wind.safelist.app[0] のように由来を示します。エラーで処理が止まる場合は、異なるエラーをすべて列挙します。同じ候補が 2 か所にあれば 2 回、同じ位置の完全な重複は 1 回だけ報告します。エントリーのスタイルシートとそのインポート先に残ったディレクティブは、同じ実行ですべて報告します。

zfb wind audit も同じ source:line:column の位置を使います。バイトオフセットは --json 出力の byteOffset にだけ現れます。設定エラーは失敗したフィールドを示し、評価済みの設定全体ではなく、その値を長さを制限して表示します。全体を表示するには ZFB_DEBUG_CONFIG=1 を設定します。

候補の抽出では、クラスになり得ない文字列リテラルを、build と audit のどちらでも読み飛ばします。対象は、import、export … from、import()、require() のモジュール指定子、URL または相対パスだけのリテラル、href、src、content、name、rel、type 属性の値、<style> 要素の CSS テキストです。クラス属性とクラス用ヘルパーを読み取り、そのほかの適格なリテラルも完全な候補を提供できます。CSS であると証明できないテンプレート定数もその対象です。

推測的なリテラル位置では、対応の取れた […] または (…) の外に =、引用符、コンマ、+、*、@、%、# を含むトークンを除外します。Unicode 文字と、対応の取れた任意 CSS 値の内側の句読点は候補になれます。明示的なクラス位置では不正な候補も診断します。リテラルが埋め込みマークアップとして解析された場合、認識した class 属性を一度だけ抽出し、生の空白区切りトークン走査を省きます。連結や補間に隣接する URL または相対パスだけの断片は引き続き除外します。

ZW001～ZW006 は、クラス、セーフリスト、厳格なマニフェストの発生元ではエラーです。確信度の低いソース位置では監査専用情報です。その位置で見つかった有効な完全候補は引き続き出力されます。基部名を持つクラスを手書きとして使う場合は、authoredClasses: { "text-link": true } のように完全な候補表記を wind.authoredClasses に追加します。この予約は候補全体に対するユーティリティの検証、診断、CSS 生成を抑止します。それ以外の場合は、ユーティリティの綴りを直すか不足トークンを宣言します。site-header のように一致するユーティリティ基部を持たない名前は通常のクラステキストとして残ります。

ZW013 は同じバリアント区分でカタログが暗黙のデフォルトとして定義した上書きを省きます。border 幅と style、outline 幅と style、transition と duration/ease が対象です。style 同士、duration 同士、transition-property 同士、sr-only と padding、辺と省略形の幅の競合は引き続き報告します。 同じバリアント区分の互換な translate-x-* と translate-y-* は、カタログが定義する合成用の宣言を共有しても競合とは扱いません。同じ軸の異なる値や、ほかのプロパティの重複は引き続き ZW013 の対象です。

未宣言の色名に有効な /0～/100 を付けた text-*、border-*、border-x-*、outline-*、placeholder:text-* は、トークン不足の ZW006/R17 を報告します。不正な不透明度、負の形、未対応のスラッシュは ZW005 のままです。

宣言済みの色を slash なしの shadow-<name> または有効な shadow-<name>/<opacity>（/0～/100）に使うと、v1 は色を shadow に合成しないことを示す専用ヒント付きの ZW004/R20 が出ます。shadow 基部は完全な値、つまり none、任意の box-shadow 値、または shadows トークンを受け付けます。色を shadows トークンに含めるか、完全な box-shadow を CSS に記述して wind.authoredClasses にクラスを登録してください。同名の shadows トークンは slash なしなら解決しますが、slash 修飾子は未対応です。

正しい括弧構文の has-[…]:、not-[…]:、nth-[…]:、nth-last-[…]:、supports-[…]: は ZW004/R09、min-[…]: と max-[…]: は ZW004/R24（wind.breakpoints を設定）、group-aria-[…]:、group-data-[…]:、peer-aria-[…]:、peer-data-[…]: は ZW004/R08 です。空・余分な接尾辞・連続・不均衡・未知の括弧付きの形式は ZW001 のままです。min-[56rem]:table-cell や has-[:focus-visible]:filter-[blur(2px)] のように、拒否されたバリアントが ZW014 のユーティリティを包む場合は、同一候補とソース範囲に ZW004 と ZW014 の両方を explain と audit が表示し、CSS は出力しません。explain は invalid のままです。strict モードはクラス位置の ZW014 をエラーにし、確信度の低いリテラルは監査情報のまま、完全一致の authored class は両診断を抑止します。

wind explain --json の tokenResolutions[*].hostOverride は、変更されたプリセットの結合に限り presetIndex、previousValue、finalValue を含みます。wind audit --json は ZW015 を標準診断オブジェクトとして出力し、severity: "auditInfo"、カテゴリと名前の候補、設定キーの出所、変更前後の値をメッセージに含みます。両 CLI の schemaVersion: 1 は変わりません。

移行時の警告と strict モード

zudo-wind は Tailwind のユーティリティをすべて実装しているわけではありません。バージョン付きの限定された移行語彙が、意図的に対象外とした主な Tailwind ユーティリティを列挙しています。table とほかの table 系 display 値、contents、flow-root、list-item、container、not-sr-only、line-clamp-*、order-*、basis-*、fill-*、stroke-*、backdrop-blur-*、appearance-*、will-change-*、content-* です。これらの名前は通常のクラステキストとして黙って通過せず、未対応の外部ユーティリティ ZW014 として報告されます。診断は代わりに手書きすべき宣言を示し、推測した CSS は決して出力しません。table-wrapper や order-summary のように外部ユーティリティに似ているだけの名前は通常のクラスのままです。

移行語彙 v4 は論理方向の ms-*／me-*、ps-*／pe-*、start-*／end-*、border-s／border-e（有効な任意値の接尾辞を含む）、isolation、float/clear、break/word-break、transform origin、filter/backdrop-filter、text-shadow も認識します。対応する論理方向の margin、padding、inset、border などの CSS を自作してください。合成 CSS は生成しません。設定済みトークンが実際に解決する場合はそちらが優先です。border-s-[3px] と border-e-[red] は ZW014、ml-zzz-[3px] のような未知の余分な接尾辞は ZW005 です。

v4 のグラデーション語彙には、v3 の bg-gradient-to-*、bg-linear-to-* と整数角度の bg-linear-*、bg-radial と bg-radial-[<value>]、bg-conic と整数角度の bg-conic-*、および宣言済み color token、current、transparent、角括弧で囲んだ任意の color または position を stop 値に使う from-*／via-*／to-* が含まれます。CSS は生成されません。background-image を自作し、完全なクラス名を wind.authoredClasses に登録してください。角括弧なしの from-10%、via-30%、to-90% は現在 candidate parser が拒否し、from-[60%] は ZW014 に到達します。

ZW014 は既定では警告なので、移行中のプロジェクトはビルドを続けつつ、スタイルを失ったクラスを把握できます。クラス位置でエラーにするには wind.strict: true を設定します。strict モードでも確信度の低いリテラルは昇格しません。クラス属性に届かない定数やテストのタイトルにある適格な完全候補は監査専用情報のままです。URL だけのリテラルは読み飛ばします。手書きの CSS がスタイルを付けているために名前を残す場合は、完全な表記を wind.authoredClasses に予約してください。

zfb wind explain は、このような名前を unsupported foreign utility の結果として報告します。

公開 Rust の移行分類関数は foreign_family(candidate, tokens) です。検証済みトークンを渡すことで、設定済みユーティリティを ZW014 より優先できます。Rust カタログのメタデータには、ZW013 の暗黙デフォルト例外を示す DefaultOverride と CatalogEntry.default_overrides もあります。カタログと言語の仕様は revision 12 のままで、シリアライズされた CLI スキーマのバージョンは 1 のままです。このメタデータ追加で CSS 出力は変わりません。

explain と audit

zfb wind explain を実行すると、候補の解析と解決を調べられます。カタログ項目、言語のバージョンとリビジョン、トークンの結び付き、カテゴリ未検証の値、宣言、セレクタ、条件、完全なソートタプルが表示されます。wind: false のときは CSS を生成せず、無効という結果を返します。

zfb wind audit は、通常のクラス位置の名前、不足または使われていないユーティリティ、動的な断片、同じクラスリストリテラル内のプロパティ競合と、宣言されていない Tailwind デフォルトテーマ変数へのフォールバックなしの参照（ZW016。デフォルトテーマ変数を参照）を調べます。マーカーと、完全一致する手書きクラスの許可リスト項目は除外します。競合の比較は 1 つのリテラル内に限られ、無関係な要素間では行いません。wind: false のときは生成が無効と報告し、候補レポートは空になります。

--plan standalone（既定）は、--source なしの zfb css と同じルート、つまり規約上のプロジェクトルートと、設定された wind.sources.roots、パッケージルート、除外を監査します。--plan build は zfb build と zfb dev が走査するソースプランを監査します。プラグインの setup を実行して、パッケージ所有のルート、兄弟ミラールート、プラグインの仮想モジュールを見つけ、仮想モジュールは plugin/<specifier> として監査します。preBuild と postBuild フックは実行せず、ビルド出力も書き込みません。どちらのモードでも、最初に wind audit plan: <mode> と、走査するすべてのルート、仮想モジュール、マニフェスト、除外とその理由を出力します。

デフォルトでは、エラー重大度の指摘があっても監査完了時の終了ステータスは 0 です。その場合、標準エラーに --fail-on error の案内が表示されます。--fail-on error はエラー重大度の診断で失敗し、--fail-on warning は警告でも失敗します。auditInfo の指摘はどちらのしきい値にも影響しません。設定が無効な場合やソースの走査に失敗した場合は常に非ゼロで終了します。

--group を使うとテキスト監査を簡潔に表示できます。未認識クラスは候補名ごと、dead class と診断は候補名・コード・severity ごとにまとめ、件数と決定的に選んだ最初の origin を示します。診断の要約には、その origin に対応するメッセージと、あれば推奨表記も残ります。既定のテキスト形式と終了ポリシーは変わらず、--json では無視されて JSON の出現ごとの配列も変わりません。CLI リファレンスを参照してください。

codeHighlight.roleClasses は意図的に寛容です。有効なユーティリティは出力され、無効または未知の role 値はビルド診断を伴わない通常のクラスとして残ります。監査では無視された role として報告されることがあります。authoredClasses との完全一致は、すべての発生元でユーティリティの検証、生成、診断を抑止します。設定エラーやスタイルシートの検査は抑止できません。

残存ディレクティブと CSS コマンド

コンパイラは旧エンジンの import とディレクティブを拒否します。対象には @tailwind、任意の修飾子を伴う @theme、@source、@custom-variant、@apply、@utility、@variant、@plugin、@config、@reference が含まれます。tailwindcss とそのサブパスの import も拒否されます。宣言値内の旧式の関数 theme()、--spacing()、--alpha()、--value() もエラーです。診断には表記、スタイルシートのファイルと範囲が示され、Tailwind からの移行へのリンクが付きます。

スキャナーはコメントと文字列の内容を無視し、エスケープされた CSS 識別子と import 文字列を復号します。禁止された import の解決を試みる前に、手書きのスタイルシートとすべての import 先を検査します。この検査は wind が false でも実行されます。通常の @layer と、レイヤーを明示する import は有効です。

単独の zfb css コマンドは引き続き wind コンパイラです。生成が有効なら、--source と --no-auto-source はソース発見、ハイライト用フラグはハイライトの意味を保ちます。wind: false のときは wind を生成せず、手書きの CSS とハイライトを処理します。別の zfb wind explain と zfb wind audit コマンドで候補の調査とソースの監査ができます。

生成物の識別子

生成されるリセット、トークン、登録、ユーティリティルールは、すべて仮想ソース zudo-wind://spec/1 を使います。ソースレコードは言語バージョン 1、リビジョン 12 を示します。v1 は生成ソースマップを作らず、行番号の対応も保証しません。代わりに、候補からソースへの位置情報をルールのメタデータと診断に保持します。

関連項目

• ソースと候補

• ユーティリティの文法

• カスケードとリセット

• Tailwind からの移行

• CLI リファレンス