Coming from 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": {}
  }
}

What changes in one minute

• zudo-wind is a versioned utility language. V1 is identified by spec: 1; familiar spellings do not promise compatibility with another engine.

• There are no utility plugins. The accepted catalog is closed for each language version.

• Configuration is data in the top-level wind key of zfb.config.ts or zfb.config.json. CSS directives do not configure the engine.

• No palette, spacing unit, named scale, breakpoint, font, radius, shadow, or named easing token is supplied implicitly. Transition utilities use ease by default; set wind.defaultTransitionTimingFunction to choose another project default.

• The source scanner needs complete class candidates. A prefix joined to a runtime value does not become a utility.

• A project class with no matching utility root stays ordinary class text. A name that starts with a catalog root is resolved against the longest matching root and validated as a utility, so missing tokens receive diagnostics. Reserve a complete authored candidate with wind.authoredClasses when CSS owns a name that overlaps a utility root.

• Keep declarations and selectors outside the catalog in authored CSS or CSS Modules.

Directives

Wind configuration and candidate discovery live outside CSS. Remove Tailwind-only directives when migrating a stylesheet. If one remains in the entry sheet or any imported sheet, zfb reports ZW009 with its spelling and source location and fails the pass, even when wind: false disables utility generation.

The scanner also rejects the legacy declaration-value functions theme(), --spacing(), --alpha(), and --value() with ZW009. It ignores comments and string contents. Ordinary @layer statements and CSS imports that explicitly name a layer remain valid. See Diagnostics and tools for the error contract.

Configuration

The old top-level tailwind key has no zudo-wind meaning. A leftover key is a hard configuration error with a named migration message. Replace it with wind. A missing wind key enables the empty v1 configuration after cutover; that means generation is enabled, reset is none, and the token maps start empty.

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" }
  }
});

The old opt-out tailwind: { enabled: false } becomes wind: false. That disables wind generation, token validation, manifest loading, and candidate scanning. Authored global CSS, CSS Modules, and syntax highlighting still run, and the leftover-directive check still runs. For all fields and merge rules, see Configuration.

Theme and tokens

V1 ships no color palette or spacing scale. It also supplies no named sizes, font families or weights, font sizes, line heights, tracking, radii, shadows, z-index values, easing values, or breakpoints. The constants 0, px, and catalog keywords do not imply a theme.

Tailwind's --text-<n> and --text-<n>--line-height variables map to a fontSizes entry with the same key, size, and optional lineHeight:

Move the values that utilities need into wind.tokens. Numeric spacing such as p-4 multiplies the configured spacingUnit; named values come from their family map. For example, this binds both color utilities to a project-owned property:

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

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

Then bg-panel and text-panel resolve from colors.panel. Token entries are validated data, not executable CSS or JavaScript. A referenced custom property remains authored CSS; the generated token variable points to it. Missing tokens and missing numeric spacing units are reported at strict candidate origins instead of being repaired with defaults. See Tokens for the supported maps and value rules.

For authored CSS that still references a Tailwind default-theme variable, apply one of the remedies in Default theme variables.

Uppercase DEFAULT is invalid. Use the lowercase key default only in maps that define that meaning: radii.default supplies bare rounded, and shadows.default supplies bare shadow. It is not a fallback for colors or spacing.

Reset

The default reset is none, which emits no reset declarations. Select a reset for the assumptions a page makes about browser defaults.

With owned-v1, add list markers back where the design calls for them; the scaffold's .prose rules explicitly restore disc and decimal lists. Headings do not retain browser heading sizes, so set them in authored CSS or with configured font-size utilities. Bare border utilities set their own solid border under every reset choice. Controls inherit font styling, and the reset leaves native focus outlines and appearance alone. Wind utilities are unlayered and, by default, follow authored global CSS: they beat normal declarations in named layers, while an unlayered authored rule can still win by specificity or later order. See Utility placement and ties for the opposite order. The reset is an explicit zudo-wind choice, not a promise to reproduce another preflight byte for byte. See Cascade and reset for the complete declarations and layer order.

Differences from Tailwind preflight

The baseline is Tailwind CSS 4.2.0 preflight vs owned-v1. The earlier recipe migrations were measured in Chromium 147 and 151 and WebKit 26.4. The supplemental #3451 fixture ran in Chromium 151 and WebKit 26.5 at 375px and 1280px; neither matrix is exhaustive. In the measured projects, Tailwind's theme resolves --default-font-family from --font-sans and --default-mono-font-family from --font-mono.

The original 0 differing elements result was limited to its fixture: it omitted a standalone text input, abbr[title], progress, and :-moz-focusring. The #3451 fixture found one difference before the common-control rule below: the text input had the UA white background under owned-v1 and a transparent background under Tailwind. After adding the rule, every standard computed-style property on the fixture elements and both pseudo-elements matched in Chromium 151 and WebKit 26.5 at both widths; all four screenshot pairs were pixel-identical. Chromium also retained a visible keyboard focus ring on the link after tabbing to it. This matrix still does not cover every control, font installation, or platform. A per-element getComputedStyle diff does not inspect ::placeholder or ::file-selector-button; query each explicitly and compare pixels where appearance matters.

For projects that want these measured preflight behaviors, add the following to authored CSS. Replace the sample font stacks with your project's stacks if they differ. The project must declare --font-sans and --font-mono in authored CSS, as this block does, or substitute literal stacks at both font-family declarations: v3 supplies no implicit theme.

@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;
  }
  /* Optional: keep hidden elements hidden even when a display utility is present. */
  [hidden]:where(:not([hidden="until-found"])) { display: none !important; }
}

The common-control rule restores Tailwind's border radius, background, and opacity declarations. The file-selector rule is separate because the button rule does not style that pseudo-element. In the Chromium 151 image-gallery recipe, adding the measured file-selector rule removed the pixel and pseudo-element differences on both tested pages in light and dark themes. The [hidden] rule is optional; its !important overrides display utilities, as Tailwind preflight does. The layer prelude orders zw-reset before authored base, so these declarations can override the reset. Keep keyboard focus indicators and review each rule you adopt rather than pasting a broader reset blindly. Restoring reset declarations does not restore utility placement or relation-selector specificity; that migration difference is tracked in #3386.

Variants and grammar

The table names the v1 disposition for each construct. Supported chains use the order responsive, dark, pointer, relation, state, pseudo-element, utility, with no repeated category.

pointer-coarse and pointer-fine need no config. any-pointer-*, motion-*, print, portrait, and arbitrary [@media(...)] remain unsupported (ZW002/R04; an arbitrary selector reports ZW004/R09). checked:, group-checked:, peer-checked:, and max-sm:peer-checked:visible are admitted; indeterminate, required, and invalid remain unsupported. selection: is admitted, without creating content. The standard focus-visible:outline focus-visible:outline-2 idiom resolves with a computed 2px outline width.

Decoration thickness/style use decoration-<integer>, nonnegative decoration-[<length>], and exact decoration-solid|double|dotted|dashed|wavy. Negative and slash thickness/style forms, decoration-auto, and decoration-from-font are unsupported. Configured full color tokens take precedence over style names: colors: { wavy: "#123456", "dotted-muted": "#123456" } makes decoration-wavy and decoration-dotted-muted/40 emit text-decoration-color. Without the token, decoration-wavy emits text-decoration-style. The names solid, double, dotted, and dashed were already reserved as color-token names; wavy was not. To get both declarations under a colliding name, author .decorated { text-decoration-style: wavy; text-decoration-color: var(--zw-color-wavy); } and reserve decorated in wind.authoredClasses if audit diagnoses it.

The candidate grammar balances brackets, parentheses, and quotes before splitting separators, so a colon or slash inside a bracket value is not treated as a variant or modifier separator. See Variants, Utility grammar, and the utility reference for the full catalog.

Utility placement and ties

A Tailwind v4 entry usually imports the utilities before its own CSS, so an authored rule with the same specificity as a utility won by coming later. zudo-wind places utilities after authored global CSS by default, which flips those ties:

/* authored */
.card {
  color: red;
}

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

To keep Tailwind's order, set the placement:

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

The emitted stylesheet is then: the layer prelude, hoisted external imports, the highlight block, the reset and token layers, @property registrations, the unlayered utilities, the authored global CSS, and finally CSS Modules. Placement decides only ties of equal specificity between unlayered rules. Under either setting a more specific authored selector wins, an authored rule inside a layer loses to every utility, and an authored !important declaration wins. Breakpoint and dark variants add no specificity, so they follow the same tie rule. Emitting utilities into a named layer is not available.

Relation variant specificity

Tailwind emits group-hover:text-accent as .group-hover\:text-accent:is(:where(.group):hover *), with specificity (0,2,0). zudo-wind emits :where(.group:hover) .group-hover\:text-accent, with specificity (0,1,0), and peer-* variants likewise. Placement does not change any selector, so it does not restore that specificity. An authored (0,2,0) or (0,1,1) rule that used to lose to a group or peer state now wins under either placement:

/* (0,2,0): now beats group-hover:text-accent */
.panel .title {
  color: red;
}

Choose one of these per rule:

• Lower the authored selector to the utility's specificity, for example :where(.panel) .title. The state then wins by order under the default placement.

• Move the authored rule into a layer, such as @layer components { .panel .title { color: red; } }, so every utility beats it.

• State the hover style in authored CSS too: .panel:hover .title { color: var(--zw-color-accent); }.

Classes that used to emit nothing

Not every class-shaped string is meant to create a utility rule. A project name such as site-header has no matching utility root, so it remains ordinary class text in markup and wind emits no rule for it. A name such as text-link does match the text root and is validated as a utility; if its required token is missing, it receives ZW006. This strict classification preserves typo detection instead of treating every unresolved name as ordinary. A standalone group or peer marker also emits no rule, while still supplying relation metadata to matching candidates.

A Tailwind utility zudo-wind does not implement, such as line-clamp-2, order-1, basis-1/2, or container, is not treated as ordinary text. It is reported as ZW014 with the declaration to author instead, as a warning by default and an error under wind.strict: true. Names with underscores, such as card__title, remain ordinary.

Run zfb wind audit to list ordinary class-position names, missing or dead utility candidates, dynamic fragments, and property conflicts within a class-list literal. Audit helps distinguish an intentionally authored class from a misspelled utility; it does not invent a replacement. To use an authored class whose name starts with a utility root, reserve the exact complete candidate spelling in wind.authoredClasses, for example { "text-link": true }. Include the variant chain when reserving a candidate such as hover:text-link. A match suppresses utility validation, diagnostics, and generated CSS for that candidate at every origin. Otherwise, correct the utility spelling or declare its missing token. See Diagnostics and tools.

ZW014 vocabulary v4 identifies logical ms-*/me-*, ps-*/pe-*, start-*/end-*, border-s/border-e for authored margin-inline-*, padding-inline-*, inset-inline-*, and border-inline-* declarations. It also identifies isolation, float, clear, word-break/break-*, transform origin, filter, backdrop-filter, text-shadow, and gradient families. Use authored CSS and reserve each exact retained class in wind.authoredClasses; no composed CSS is generated. Names such as origin-story, float-label, and clear-fix stay authored. An actual catalog/token utility resolves first. Gradient spellings include bg-gradient-to-*, bg-linear-to-*, integer-angle bg-linear-*, bg-radial and bracketed values, bg-conic and integer angles, and from-*/via-*/to-* with a declared color, current, transparent, or bracketed color/position. Author background-image. Bare stop percentages (from-10%, via-30%, to-90%) are parser-rejected; bracketed from-[60%] reaches ZW014.

A worked migration

The basic-blog scaffold's callout uses actual candidates such as my-6, rounded-md, border-l-4, px-4, py-3, dark:bg-sky-950/40, and group-hover:text-accent. The migration table keeps these spellings. Adoption means they resolve only after the scaffold explicitly configures their tokens and variants.

The old stylesheet begins with the Tailwind import and a custom dark variant, and declares three project colors through @theme:

@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;
}

The callout source supplies these tone strings:

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

Remove the two Tailwind directives. Move utility values to config and keep the CSS-only theme properties authored:

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 }
  }
});

This config excerpt covers the shown callout tokens. A complete scaffold config also declares every color and scale used by the remaining candidates and authored CSS; nothing fills those maps implicitly.

Merge the theme properties into the existing authored base layer, retaining its color-scheme and selection rules:

@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;
  }
}

Keep the existing base and component layers; wind's prelude establishes their order. The authored .prose class remains in the stylesheet and is entered exactly in authoredClasses. As described in Default theme variables, update the old authored var(--color-neutral-900) reference to the emitted var(--zw-color-neutral-900) token variable when the color token is configured. The configured accent token points back to the authored --color-accent property, so the theme toggle can continue changing that value. The scaffold reset is owned-v1; other projects still default to none. These are language and stylesheet changes only; the full ordered project upgrade is in Migrating to v3.

What is not supported, and what to do instead

• No implicit palette or spacing scale: declare project values under wind.tokens.

• No shadow-color composition: shadow-<color> and valid shadow-<color>/<opacity> forms (/0–/100) do not apply colors tokens to a shadow. Fold the tint into a shadows token or author the complete box-shadow in CSS and reserve the class. A bare shadow-<name> with matching colors and shadows tokens resolves as the shadow token; slash modifiers remain unsupported. shadow-none and complete arbitrary values such as shadow-[0_1px_2px_#000] remain supported.

• No ring, animation, scale, transform-string, or arbitrary-property utility: write the declarations in authored CSS or a CSS Module.

• No attribute or arbitrary-selector variant and no named group or peer: use an authored selector.

• No plugin-defined classes or @apply expansion: use catalog candidates for supported utilities and keep custom declarations in CSS.

• No runtime-built candidate or regex safelist: write a finite literal map, an owner-keyed safelist, or a strict versioned package manifest.

Use the utility reference for the v1 catalog and Diagnostics and tools to inspect candidates and migration errors.