設定

{
  "wind": {
    "spec": 1,
    "reset": "none",
    "strict": true,
    "tokens": {
      "spacingUnit": "0.25rem",
      "colors": {
        "panel": "#eaf2ff"
      }
    },
    "breakpoints": {
      "sm": {
        "minWidthPx": 640
      }
    },
    "defaultTransitionTimingFunction": "ease",
    "authoredClasses": {
      "wind-demo-card": true
    },
    "safelist": {
      "docs-preview": [
        "bg-panel",
        "p-4",
        "sm:p-8"
      ]
    }
  }
}

.wind-demo-card { max-width: 24rem; border: 1px solid #b6c4d2; border-radius: 0.5rem; color: #172b4d; }
.wind-demo-card h2 { margin: 0 0 0.5rem; font-size: 1.1rem; }
.wind-demo-card p { margin: 0; }

wind キー

ルート設定の wind は zfb.config.ts と zfb.config.json の両方で使えます。切り替え後はキーを省略しても空のオブジェクトと同じです。生成が有効になり、リセットは none、トークンマップは空、ソースは zfb のソースプランから供給されます。

import { defineConfig } from "zfb/config";

export default defineConfig({
  wind: {
    spec: 1,
    reset: "none",
    defaultTransitionTimingFunction: "cubic-bezier(0.4, 0, 0.2, 1)",
    tokens: {
      spacingUnit: "0.25rem",
      colors: { panel: "var(--app-panel)" }
    },
    breakpoints: {
      sm: { minWidthPx: 640 }
    },
    dark: { attribute: "data-theme", value: "dark" },
    safelist: {
      app: ["sm:hover:bg-panel"]
    },
    authoredClasses: {
      prose: true
    },
    manifests: {
      widgets: { path: "@example/widgets/wind.json" }
    }
  }
});

ホストのトークン値がプリセットの結合と異なる場合、ビルド中は無言で置き換えます。wind explain は任意の tokenResolutions[*].hostOverride で変更された結合を示し、wind audit は ZW015 を監査専用情報として報告します。同じ値なら上書きレコードは出しません。

マニフェストパスの解決

マニフェストのパスは基準ディレクトリから解決されます。@example/widgets/wind.json のような bare package specifier は Node の解決規則と producer パッケージの exports を使います。この表記は推奨形式で、pnpm のパッケージ配置でも動作します。producer パッケージからマニフェストをエクスポートしてください。

{
  "name": "@example/widgets",
  "exports": {
    "./wind.json": "./wind.json"
  }
}

./ または ../ で始まるパスはプロジェクトルートを基準に解決されます。ここでいうプロジェクトルートは zfb.config.ts または zfb.config.json を含むディレクトリで、現在の作業ディレクトリには依存しません。zfb css や zfb wind が --config で指定されたファイルを読み込む場合は、そのファイルのディレクトリがこの役割を担います（明示的な config ファイル を参照）。definePreset() で作られたプリセット由来のマニフェスト宣言では、zfb がプリセットパッケージを出所として記録するため、相対パスと bare package specifier のどちらもプリセットパッケージのディレクトリを基準に解決されます。

ソースの除外とパッケージルート

sources はソースプランを調整します。これらの宣言は任意で既定値は空なので、sources を指定しなければ既定のソースプランのままです。

wind: {
  sources: {
    rootPackage: false,
    roots: ["src", "tests"],
    exclude: ["src/**/__tests__/**", "worker"],
    classHelpers: ["uiClasses"],
    ignoreAttributes: ["css", "displayJs"],
    packageRoots: ["@example/widgets", "./packages/ui"]
  }
}

sources.rootPackage は、pnpm-workspace.yaml が . を明示している場合に行う、ワークスペースルートパッケージの暗黙の Wind 走査を制御します。既定値は true です。false を指定するとそのソースだけを除外し、true は走査を明示的に維持します。プロジェクトのルート、import されたソース、明示した sources.roots と sources.packageRoots、マニフェスト、safelist は独立した入力のままです。複数のプリセットがこの値を指定する場合は、最初のプリセットの値が優先されます。プロジェクトが値を明示するとプリセットを上書きし、省略するとプリセット値を継承します。プリセットにも指定がなければ、省略時は true です。

exclude の各エントリは、宣言元ルートからの相対パスに照合する glob です。宣言元ルートはプロジェクトルート（--config を指定した場合はそのファイルのディレクトリ）、または definePreset() 由来の宣言ではプリセットパッケージです。パス自体か親ディレクトリのいずれかに一致するとそのパスは除外されるため、worker または worker/ は worker/ 以下をすべて除外します。* は / をまたがず、任意の深さには ** を使います。除外はすべてのソースルートに適用され、明示的な --source のファイルより優先され、自身の宣言元ルート内のファイルだけを取り除きます。否定 (!)、絶対パス、.. を含むパターンは拒否されます。テストファイルはパターンで指定しない限り除外されません。

sources.roots は宣言元のプロジェクトまたはプリセットより厳密に下にあるディレクトリを列挙します。宣言元自身やその外側は指定できません。これらのルートには gitignore、標準のスキップ対象ディレクトリ、wind.sources.exclude が適用されます。通常の .ts と .test.ts は候補ですが、宣言ファイル .d.ts は常に除外され、audit の範囲には excluded **/*.d.ts (declaration files) と表示されます。packageRoots は走査規則が異なる独立した第一者パッケージ用チャネルです。

packageRoots の各エントリは、宣言元ルートからの ./ または ../ パスか、@example/widgets/dist のように任意のサブパスを付けたインストール済みパッケージ名です。パッケージ名は宣言元ルートより上の node_modules ディレクトリから探します。パッケージルートは、プロジェクトルートそのものやその祖先ではないディレクトリとして存在する必要があり、そのパッケージ自身の dist と node_modules も含め、Gitignore の規則を使わずに走査されます。出力先、--output、スクラッチディレクトリはその中でも除外されたままです。

sources.classHelpers は組み込みのクラスヘルパーに追加するローカル識別子を明示します。プリセットとプロジェクトのリストは重複を除いて決定的な順序で結合します。対応する文字列・テンプレート、配列、オブジェクト引数をクラスリストとして扱いますが、cva や twMerge を指定しても別の意味を推測しません。sources.ignoreAttributes は組み込みの除外 prop href、src、content、name、rel、type に名前を追加し、プリセットとプロジェクトの宣言は重複を除きます。名前には Unicode 識別子文字を使い、後続に - または : の区切りを付けられます。class と className は拒否されます。クラスではない内容を保持する css、html、js、displayJs、title などは必要に応じて指定してください。除外 prop の値全体が対象で、入れ子のマークアップ、補間、クラスヘルパー呼び出しも除外します。ほかの場所の実際の class 属性や診断は残ります。クエリーセレクターやスクリプト本文のヒューリスティックは追加されていません。

JSON でも同じオブジェクトを wind プロパティの値として指定できます。

{
  "wind": {
    "spec": 1,
    "reset": "none",
    "tokens": {
      "spacingUnit": "0.25rem",
      "colors": {
        "panel": "var(--app-panel)"
      },
      "fontSizes": {
        "sm": {
          "size": "0.875rem",
          "lineHeight": "1.25rem"
        }
      }
    },
    "breakpoints": {
      "sm": {
        "minWidthPx": 640
      }
    }
  }
}

wind: false は build、dev、単独の CSS コマンドで、wind の生成、トークン検証、マニフェスト読み込み、候補の走査を無効にします。手書きのグローバル CSS、CSS Modules、ハイライト処理は続きます。スタイルシートに残ったディレクティブの検査も続きます。none 以外のリセットは候補がなくても CSS を出力できます。有効な空の設定で解決済みルールがなければ、wind スタイルシートは出力されません。

フィールド

ダークモードの属性は小文字の HTML 属性識別子でなければなりません。値は空にできず、制御文字も含められません。所有者 ID と生成者 ID は ASCII 英数字、ドット、アンダースコア、スラッシュ、ハイフンからなり、英数字で始まる空でない文字列です。手書きのクラスのキーは、空白や制御文字を含まない完全なトークンでなければなりません。

defaultTransitionTimingFunction には CSS のタイミング関数を指定し、tokens.easings の名前は指定しません。明示する ease-* ユーティリティ用の値は tokens.easings に設定します。これらのユーティリティはトランジションのデフォルトより後に並び、同じバリアント区画ではデフォルトを上書きします。設定値は単一のタイミング関数またはキーワードとして検証されます。transition-none はデフォルトの時間とタイミング関数を出力しません。

厳格な検証とマージ

ネストした設定オブジェクトはいずれも、使用できるフィールド名が限定されています。未知のフィールド、null、誤った値型、未対応のバージョンやリセット名、重複するブレークポイント幅、無効なトークンデータは検証に失敗します。省略された任意のオブジェクトには文書化された空のデフォルトが入るため、部分的なオブジェクトは指定できます。

プリセットとユーザー設定をマージすると、オブジェクトは再帰的にマージされ、ユーザー値が優先されます。異なるセーフリスト所有者とマニフェスト生成者は別々に残ります。sources の宣言はそれぞれ自身の宣言元ルートとともに保持されます。プリセットの順にプリセットのエントリが先に並び、その後にユーザーのエントリが続き、ユーザーの宣言がプリセットの宣言を置き換えることはありません。同じ所有者のセーフリストでは、ユーザーの配列がプリセットの配列を置き換え、連結はされません。手書きのクラスマップはキーごとにマージされ、ユーザー値が優先されます。v1 に個別エントリの削除マーカーはなく、wind を false にするとシステム全体が無効になります。

トップレベルに旧式の tailwind キーが残っていると、移行方法を示すエラーになります。v3 移行ガイドに従って更新してください。

関連項目

• 概要

• トークン

• ソースと候補

• Tailwind からの移行