Tailwind からの移行

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

.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": {
    "spec": 1,
    "reset": "none",
    "strict": true,
    "tokens": {
      "spacingUnit": "0.25rem"
    },
    "breakpoints": {},
    "defaultTransitionTimingFunction": "ease",
    "authoredClasses": {},
    "safelist": {
      "docs-preview": []
    }
  }
}

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

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

主な変更点

• zudo-wind はバージョン管理されたユーティリティ言語です。v1 は spec: 1 で識別され、見慣れた表記でも別のエンジンとの互換性は保証しません。

• ユーティリティプラグインはありません。受け入れるカタログは言語バージョンごとに固定されます。

• 設定は zfb.config.ts または zfb.config.json のトップレベルの wind キーに置くデータです。CSS ディレクティブではエンジンを設定しません。

• パレット、余白単位、名前付きスケール、ブレークポイント、フォント、角丸、シャドウ、名前付きイージングトークンは暗黙に供給されません。トランジション系ユーティリティのデフォルトは ease です。別のプロジェクト共通設定には wind.defaultTransitionTimingFunction を指定します。

• ソースのスキャナーには完全なクラス候補が必要です。接頭辞と実行時の値を結合してもユーティリティにはなりません。

• どのユーティリティ基部にも一致しないプロジェクトのクラスは通常のクラステキストとして残ります。カタログの基部で始まる名前は最長一致する基部で解決され、ユーティリティとして検証されるため、トークンが足りなければ診断されます。手書き CSS 側で基部名と重なるクラスを所有する場合は、完全な候補を wind.authoredClasses に登録します。

• カタログ外の宣言とセレクタは、手書きの CSS または CSS Modules に置きます。

ディレクティブ

wind の設定と候補の発見は CSS の外で行います。スタイルシートの移行時には Tailwind 専用のディレクティブを削除してください。入口または import 先のスタイルシートに残っていると、wind: false で生成を無効にしていても、zfb は表記とソース位置を示す ZW009 を報告し、処理に失敗します。

スキャナーは旧式の宣言値関数 theme()、--spacing()、--alpha()、--value() も ZW009 で拒否します。コメントと文字列の内容は無視します。通常の @layer 宣言と、レイヤーを明示する CSS import は有効です。エラーの契約は診断とツールを参照してください。

設定

旧式のトップレベルの tailwind キーは zudo-wind では意味を持ちません。残っていれば、移行方法を示す設定エラーになります。wind に置き換えてください。切り替え後に wind キーを省略すると、空の v1 設定が有効になります。つまり生成は有効、リセットは none、トークンマップは空です。

import { defineConfig } from "zfb/config";

export default defineConfig({
  wind: {
    spec: 1,
    reset: "owned-v1",
    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" }
  }
});

以前の無効化設定 tailwind: { enabled: false } は wind: false になります。これにより wind の生成、トークン検証、マニフェスト読み込み、候補走査を無効にします。手書きのグローバル CSS、CSS Modules、構文ハイライトは続き、残存ディレクティブの検査も続きます。フィールドとマージ規則は設定を参照してください。

テーマとトークン

v1 は色パレットや余白スケールを同梱しません。名前付きのサイズ、フォントファミリーやウェイト、文字サイズ、行の高さ、字間、角丸、シャドウ、z-index、イージング、ブレークポイントもありません。定数 0、px、カタログのキーワードはテーマを意味しません。

Tailwind の --text-<n> と --text-<n>--line-height は、同じキーと size、任意の lineHeight を持つ fontSizes 項目に対応します。

ユーティリティが必要とする値を wind.tokens に移します。p-4 のような数値の余白は設定された spacingUnit を倍にし、名前付きの値は対応する群のマップから取得します。たとえば次の設定は、2 つの色ユーティリティをプロジェクト所有のプロパティに結び付けます。

{
  "wind": {
    "tokens": {
      "spacingUnit": "0.25rem",
      "colors": {
        "panel": "var(--app-panel)"
      }
    }
  }
}

:root {
  --app-panel: #f4f1ec;
}

これで bg-panel と text-panel は colors.panel から解決されます。トークンの項目は検証されるデータであり、実行可能な CSS や JavaScript ではありません。参照されるカスタムプロパティは手書きの CSS に残り、生成されたトークン変数がそれを指します。トークンや数値の余白単位がない場合、厳格な候補の発生元で報告され、デフォルトで補われません。マップと値の規則はトークンを参照してください。

手書き CSS に Tailwind のデフォルトテーマ変数への参照が残っている場合は、デフォルトテーマ変数に挙げた方法のいずれかで対応してください。

大文字の DEFAULT は無効です。小文字の default は、その意味が定義されたマップだけで使います。radii.default は rounded、shadows.default は shadow の値を与えます。色や余白のフォールバックにはなりません。

リセット

デフォルトの reset は none で、リセット宣言は出力されません。ブラウザのデフォルトに対してページが置く前提に応じて選んでください。

owned-v1 では、デザインに必要なリストマーカーを戻してください。スキャフォールドの .prose ルールは disc と decimal のリストを明示的に復元します。見出しはブラウザ標準のサイズを保持しないため、手書きの CSS または設定済みの文字サイズユーティリティで指定します。接尾辞のない border ユーティリティは、どのリセットでも自身で実線のボーダーを設定します。フォーム部品はフォントスタイルを継承し、リセットはブラウザ標準のフォーカスアウトラインと appearance を維持します。wind のユーティリティはレイヤーを持たず、既定では手書きのグローバル CSS の後に続きます。名前付きレイヤーの通常の宣言より優先されますが、レイヤーのない手書きのルールは詳細度や後続順によって優先されます。逆の順序はユーティリティの配置と同点を参照してください。リセットは明示的な zudo-wind の選択であり、別の preflight とバイト単位で一致する保証ではありません。宣言とレイヤー順はカスケードとリセットを参照してください。

Tailwind preflight との違い

比較の基準は Tailwind CSS 4.2.0 の preflight と owned-v1 です。先行するレシピ移行では Chromium 147・151 と WebKit 26.4 で測定しました。追加の #3451 フィクスチャは Chromium 151 と WebKit 26.5 で、375px と 1280px の幅を使って確認しました。いずれも網羅的なマトリクスではありません。測定したプロジェクトでは、Tailwind のテーマは --default-font-family を --font-sans から、--default-mono-font-family を --font-mono から解決します。

元の 差分 0 要素 という結果は、そのフィクスチャの範囲内でした。元のフィクスチャには単独の text input がなく、abbr[title]、progress、:-moz-focusring も調べていません。#3451 のフィクスチャでは、下記の共通フォーム部品ルールを追加する前に、owned-v1 の text input がブラウザー標準の白い背景を保ち、Tailwind では透明になる差が見つかりました。ルール追加後は Chromium 151 と WebKit 26.5 の両方で、両方の幅における全要素の標準 computed style と2つの疑似要素が一致しました。4組のスクリーンショットもピクセル単位で同一でした。Chromium ではリンクまで Tab キーで移動した後も、キーボードフォーカスリングが表示されました。この測定範囲はすべてのフォーム部品、フォント、プラットフォームを網羅するものではありません。要素ごとの getComputedStyle の差分には ::placeholder と ::file-selector-button は現れないため、疑似要素を明示して取得し、見た目が重要ならピクセルも比較してください。

測定された preflight の振る舞いを戻したい場合は、次の CSS を手書きのスタイルシートに追加します。プロジェクトのフォントが異なる場合、例のスタックを置き換えてください。v3 に暗黙のテーマはありません。したがって、この例のように --font-sans と --font-mono を手書き CSS で宣言するか、両方の font-family にリテラルのスタックを指定する必要があります。

@layer base {
  :root {
    --font-sans: ui-sans-serif, system-ui, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji";
    --font-mono: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace;
  }
  html { font-family: var(--font-sans); -webkit-tap-highlight-color: transparent; }
  code, kbd, samp, pre { font-family: var(--font-mono); }
  small { font-size: 80%; }
  sub, sup { font-size: 75%; line-height: 0; position: relative; vertical-align: baseline; }
  sub { bottom: -0.25em; }
  sup { top: -0.5em; }
  hr { color: inherit; }
  button, input:where([type="button"], [type="reset"], [type="submit"]) { appearance: button; }
  button, input, select, optgroup, textarea {
    border-radius: 0;
    background-color: transparent;
    opacity: 1;
  }
  ::placeholder { opacity: 1; color: color-mix(in oklab, currentcolor 50%, transparent); }
  ::file-selector-button {
    box-sizing: border-box;
    margin: 0;
    margin-inline-end: 4px;
    padding: 0;
    border: 0 solid;
    border-radius: 0;
    background-color: transparent;
    font: inherit;
    font-feature-settings: inherit;
    font-variation-settings: inherit;
    letter-spacing: inherit;
    color: inherit;
    opacity: 1;
    appearance: button;
  }
  /* 任意指定。display ユーティリティがあっても hidden 要素を非表示に保つ。 */
  [hidden]:where(:not([hidden="until-found"])) { display: none !important; }
}

共通フォーム部品のルールでは、Tailwind が設定する border radius、背景色、不透明度を戻します。button のルールはファイル選択ボタンの疑似要素には適用されないため、独立したルールが必要です。Chromium 151 の画像ギャラリーのレシピでは、測定に基づくファイルボタンのルールを追加すると、テストした 2 ページの明暗両テーマでピクセルと疑似要素の差分が 0 になりました。[hidden] のルールは任意です。!important は Tailwind preflight と同様に display ユーティリティより優先させるためです。レイヤーの前置きでは zw-reset が手書きの base より前にあるため、この補完ルールでリセットを上書きできます。キーボード操作時のフォーカス表示を残し、広範なリセットを無条件に貼り付けず、採用するルールを確認してください。リセット宣言を戻しても、ユーティリティの配置や関係セレクタの詳細度は戻りません。この差分は #3386 で追跡しています。

バリアントと文法

次の表は各構成要素に対する v1 の扱いを示します。対応する連鎖はレスポンシブ、ダーク、pointer、関係、状態、疑似要素、ユーティリティの順で、カテゴリは重複できません。

pointer-coarse と pointer-fine は設定不要です。any-pointer-*、motion-*、print、portrait、任意の [@media(...)] は未対応です（ZW002/R04、任意セレクターは ZW004/R09）。checked:、group-checked:、peer-checked:、max-sm:peer-checked:visible は使えますが、indeterminate、required、invalid は未対応です。selection: は content を生成せずに使えます。標準的な focus-visible:outline focus-visible:outline-2 は計算上の outline 幅 2px に解決します。

装飾の厚さと style は decoration-<整数>、0 以上の decoration-[<length>]、正確な decoration-solid|double|dotted|dashed|wavy を使います。thickness/style の負数やスラッシュ、decoration-auto、decoration-from-font は未対応です。設定済みの完全な色トークンは style 名より優先です。colors: { wavy: "#123456", "dotted-muted": "#123456" } なら decoration-wavy と decoration-dotted-muted/40 は text-decoration-color を出力します。トークンがなければ decoration-wavy は text-decoration-style を出力します。solid、double、dotted、dashed は以前から色トークン名として予約されていましたが、wavy は予約されていませんでした。衝突する名前で両方必要なら .decorated { text-decoration-style: wavy; text-decoration-color: var(--zw-color-wavy); } を手書きし、audit が診断する場合は decorated を wind.authoredClasses に登録してください。

候補の文法では区切りを分割する前に角括弧、丸括弧、引用符の対応を取るため、角括弧値内のコロンやスラッシュはバリアントや修飾子の区切りにはなりません。完全なカタログはバリアント、ユーティリティの文法、ユーティリティリファレンスを参照してください。

ユーティリティの配置と同点

Tailwind v4 のエントリーは通常、自前の CSS より前にユーティリティを import します。そのため、ユーティリティと詳細度が同じ手書きのルールは、後にあることで優先されていました。zudo-wind は既定でユーティリティを手書きのグローバル CSS の後に置くため、この勝敗が逆になります。

/* 手書き */
.card {
  color: red;
}

<p class="card text-accent">Card</p>

Tailwind の順序を保つには配置を設定します。

wind: {
  utilities: { placement: "before-authored" }
}

このとき出力されるスタイルシートは、レイヤーの前置き、巻き上げられた外部 import、ハイライトブロック、リセットとトークンのレイヤー、@property 登録、レイヤーのないユーティリティ、手書きのグローバル CSS、最後に CSS Modules の順になります。配置が決めるのは、レイヤーのないルール同士で詳細度が同じ場合の勝敗だけです。どちらの設定でも、詳細度の高い手書きのセレクターが優先され、レイヤー内の手書きのルールはどのユーティリティにも負け、手書きの !important 宣言が優先されます。ブレークポイントとダークのバリアントは詳細度を加えないため、同じ同点の規則に従います。ユーティリティを名前付きレイヤーに出力する機能はありません。

関係バリアントの詳細度

Tailwind は group-hover:text-accent を .group-hover\:text-accent:is(:where(.group):hover *) として出力し、詳細度は (0,2,0) です。zudo-wind は :where(.group:hover) .group-hover\:text-accent を出力し、詳細度は (0,1,0) です。peer-* のバリアントも同様です。配置はセレクターを変えないため、この詳細度は戻りません。以前は group や peer の状態に負けていた (0,2,0) や (0,1,1) の手書きのルールは、どちらの配置でも優先されるようになります。

/* (0,2,0): group-hover:text-accent に勝つようになる */
.panel .title {
  color: red;
}

ルールごとに次のいずれかを選びます。

• 手書きのセレクターの詳細度をユーティリティと同じにします。たとえば :where(.panel) .title です。既定の配置では、状態のほうが順序で優先されます。

• @layer components { .panel .title { color: red; } } のように手書きのルールをレイヤーに移し、すべてのユーティリティが優先されるようにします。

• ホバー時のスタイルも手書きの CSS で指定します。.panel:hover .title { color: var(--zw-color-accent); } です。

以前は何も出力しなかったクラス

クラスに見える文字列のすべてがユーティリティルールを作るわけではありません。site-header のような名前はユーティリティ基部に一致しないため、通常のクラスとしてマークアップに残り、wind はルールを出力しません。一方 text-link は text 基部に一致してユーティリティとして検証されるため、必要なトークンがなければ ZW006 になります。未解決の名前をすべて通常のクラスとして扱うのではなく、綴り間違いを検出できる厳格な分類です。単独の group または peer マーカーもルールを出力せず、対応する候補のために関係メタデータを提供します。

line-clamp-2、order-1、basis-1/2、container など zudo-wind が実装しない Tailwind ユーティリティは、通常のテキストとして扱われません。代わりに手書きすべき宣言を添えた ZW014 として報告され、既定では警告、wind.strict: true ではエラーです。card__title のようにアンダースコアを含む名前は通常のクラスのままです。

zfb wind audit は、通常のクラス位置の名前、不足または使われていない候補、動的な断片、同じクラスリストリテラル内のプロパティ競合を列挙します。意図的な手書きクラスとスペルミスしたユーティリティの区別に役立ちますが、代替の候補は推測しません。ユーティリティ基部から始まる手書きクラスは、{ "text-link": true } のように wind.authoredClasses に完全な候補表記を追加して予約します。hover:text-link のような候補ではバリアント連鎖も含めます。一致すると、その候補はすべての発生元でユーティリティの検証、診断、CSS 生成を抑止します。それ以外の場合はユーティリティの綴りを直すか、不足トークンを宣言します。診断とツールを参照してください。

ZW014 移行語彙 v4 は論理方向の ms-*／me-*、ps-*／pe-*、start-*／end-*、border-s／border-e を報告します。margin-inline-*、padding-inline-*、inset-inline-*、border-inline-* の CSS を自作してください。isolation、float、clear、word-break／break-*、transform origin、filter、backdrop-filter、text-shadow、グラデーションも対象です。完全なクラス名を wind.authoredClasses に予約し、CSS を自作してください。合成 CSS は生成されません。origin-story、float-label、clear-fix は自作クラスとして残り、実際に解決するカタログ／トークンユーティリティが優先です。グラデーションには bg-gradient-to-*、bg-linear-to-*、整数角度の bg-linear-*、bg-radial と角括弧付き値、bg-conic と整数角度、宣言済み色・current・transparent・角括弧付き色／位置の from-*／via-*／to-* を含みます。background-image を自作します。角括弧なしの stop percentage（from-10%、via-30%、to-90%）は parser が拒否し、from-[60%] は ZW014 に到達します。

移行例

basic-blog スキャフォールドの callout は my-6、rounded-md、border-l-4、px-4、py-3、dark:bg-sky-950/40、group-hover:text-accent などの実際の候補を使います。移行表では表記を維持します。採用されるとは、スキャフォールドがトークンとバリアントを明示的に設定した後に解決されるという意味です。

古いスタイルシートは Tailwind の import と独自のダークバリアントから始まり、@theme で 3 つのプロジェクト色を宣言します。

@import "tailwindcss";
@custom-variant dark (&:where([data-theme="dark"], [data-theme="dark"] *));

@theme {
  --color-accent: oklch(0.53 0.21 258);
  --color-code-bg: #2b303b;
  --color-code-fg: #c0c5ce;
}

callout のソースには、次の tone 文字列があります。

tone: "border-sky-500 bg-sky-50 dark:bg-sky-950/40",
accent: "text-sky-700 dark:text-sky-300",

2 つの Tailwind ディレクティブを削除します。ユーティリティの値を設定に移し、CSS 専用のテーマプロパティは手書きのままにします。

import { defineConfig } from "zfb/config";

export default defineConfig({
  wind: {
    spec: 1,
    reset: "owned-v1",
    tokens: {
      spacingUnit: "0.25rem",
      colors: {
        accent: "var(--color-accent)",
        "sky-50": "#f0f9ff",
        "sky-300": "#7dd3fc",
        "sky-500": "#0ea5e9",
        "sky-700": "#0369a1",
        "sky-950": "#082f49"
      },
      radii: { md: "0.375rem" }
    },
    breakpoints: { sm: { minWidthPx: 640 } },
    dark: { attribute: "data-theme", value: "dark" },
    authoredClasses: { prose: true }
  }
});

この設定抜粋は、示した callout のトークンをカバーします。完全なスキャフォールド設定では、残りの候補と手書きの CSS が使うすべての色とスケールも宣言します。暗黙に補完されるマップはありません。

テーマプロパティを既存の手書きの base レイヤーに統合し、color-scheme と selection のルールを保ちます。

@layer base {
  :root {
    --color-accent: oklch(0.53 0.21 258);
    --color-code-bg: #2b303b;
    --color-code-fg: #c0c5ce;
    color-scheme: light;
  }

  [data-theme="dark"] {
    --color-accent: oklch(0.79 0.13 254);
    color-scheme: dark;
  }
}

既存の base と components レイヤーは残します。wind の前置きが順序を定めます。手書きの .prose クラスはスタイルシートに残し、authoredClasses に完全な名前を登録します。デフォルトテーマ変数で説明したように、色トークンが設定されているなら、手書き CSS 内の旧 var(--color-neutral-900) 参照を出力されるトークン変数 var(--zw-color-neutral-900) に更新します。設定済みの accent トークンは手書きの --color-accent を参照するため、テーマ切り替えでは引き続きその値を変更できます。スキャフォールドは owned-v1 リセットを使いますが、ほかのプロジェクトのデフォルトは none です。ここで扱うのは言語とスタイルシートの変更です。プロジェクト全体の移行順序はv3 への移行を参照してください。

未対応の機能と代替方法

• 暗黙のパレットや余白スケールはありません。プロジェクトの値を wind.tokens に宣言します。

• shadow に色を合成する機能はありません。shadow-<color> と有効な shadow-<color>/<opacity>（/0～/100）は colors トークンを shadow に適用しません。色を shadows トークンに含めるか、完全な box-shadow を CSS に記述してクラスを予約してください。同名の colors と shadows トークンがある場合、slash のない shadow-<name> は shadow トークンとして解決しますが、slash 修飾子は未対応です。shadow-none と shadow-[0_1px_2px_#000] のような完全な任意値は使えます。

• ring、animation、scale、transform 文字列、任意プロパティのユーティリティはありません。手書きの CSS または CSS Module に宣言します。

• 属性や任意セレクタのバリアント、名前付き group や peer はありません。手書きのセレクタを使います。

• プラグイン定義のクラスや @apply 展開はありません。対応するユーティリティにはカタログの候補を使い、独自の宣言は CSS に残します。

• 実行時に組み立てる候補や正規表現のセーフリストはありません。有限のリテラルマップ、所有者キー付きセーフリスト、厳格なバージョン付きパッケージマニフェストを使います。

v1 カタログはユーティリティリファレンス、候補と移行エラーの調査は診断とツールを参照してください。