Tailwind Knowledge Patch

Tailwind CSS Knowledge Patch

Use this patch when configuring, migrating, integrating, or extending a Tailwind CSS project. Check migration-sensitive behavior first, then open only the topic reference relevant to the task.

Reference Index

Migration Hazards First

Use the CSS-first entry point

@import "tailwindcss";

@theme {
  --color-brand: oklch(0.68 0.14 250);
  --breakpoint-3xl: 120rem;
}

• Put framework tokens in a top-level @theme; a :root custom property alone does not create a utility or variant.
• Use @config and @plugin only as bridges for legacy JavaScript configuration and plugins.
• Do not carry forward corePlugins, safelist, or separator; they are unsupported. Replace safelisting with @source inline().

Update renamed and deprecated classes

Unmodified gradients interpolate in OKLAB. Append an explicit modifier such as /srgb or /oklch only when a particular color space is required.

Preserve compatibility deliberately

• Older-browser fallbacks cover oklab, opacity-modified colors, and registered-custom-property implementations used by shadows, transforms, and gradients.
• Explicit gradient interpolation falls back to the browser default when unsupported; test visual fidelity when older browsers matter.
• CSS nesting is processed even when Lightning CSS does not run, including in @tailwindcss/browser and Tailwind Play.
• The default sans stack uses explicit platform fonts so Windows CJK selection can follow the document's lang attribute.

Theme and Configuration Quick Reference

Theme block modes

Theme namespaces create APIs for colors, fonts, text sizes, font weights, tracking, leading, spacing, radii, shadows, inset shadows, drop shadows, blur, perspective, aspect ratios, easing, and animation. Breakpoint tokens create responsive variants; container tokens create container variants and size utilities.

Animation ownership

Nest a keyframe in @theme beside its --animate-* token when it should be emitted only if that animation is used. Put @keyframes outside @theme when it must always exist.

@theme {
  --animate-fade-in: fade-in 300ms ease-out;

  @keyframes fade-in {
    from { opacity: 0; }
    to { opacity: 1; }
  }
}

Source detection controls

@source not "./src/components/legacy";
@source inline("{hover:,}bg-red-{50,{100..900..100},950}");
@source not inline("container");

• @source not excludes paths from candidate scanning.
• @source inline() generates literal candidates and supports brace-expanded lists, ranges, and variants.
• @source not inline() suppresses a candidate even if project scanning finds it.

Build-time functions and functional utilities

.card {
  color: --alpha(var(--color-lime-300) / 50%);
  margin: --spacing(4);
}

@utility tab-* {
  tab-size: --value(integer, --default(4));
}

--alpha() compiles opacity changes to color-mix(). --spacing() multiplies the base spacing token and preserves a length for zero by compiling --spacing(0) to 0px. Within a functional @utility, nest --default(...) in --value(...) or --modifier(...) to support both a bare utility and explicitly valued forms.

Common Utility Changes

Values and gradients

Grid counts and spacing-based utilities accept bare values outside a configured scale:

<div class="grid grid-cols-15 w-17 pr-29"></div>

Linear, radial, and conic gradients share from-*, via-*, and to-* stops:

<div class="bg-linear-45/oklch from-indigo-500 to-pink-500"></div>
<div class="bg-conic/[in_hsl_longer_hue] from-red-600 to-red-600"></div>
<div class="bg-radial-[at_25%_25%] from-white to-zinc-900 to-75%"></div>

Shadows and masks

<h1 class="text-shadow-lg text-shadow-sky-300">Title</h1>
<h2 class="text-shadow-sm/12.5">Subtitle</h2>
<svg class="drop-shadow-xl drop-shadow-cyan-500/50">...</svg>
<img class="mask-b-from-50% mask-radial-[50%_90%] mask-radial-from-80%" src="photo.jpg" />

• Text shadows range from text-shadow-2xs through text-shadow-lg; size and color compose.
• Box, text, drop, and inset shadow sizes accept fractional opacity modifiers.
• Drop-shadow size and color are separate; color accepts an opacity modifier.
• Linear, radial, and conic mask utilities compose on one element.

Wrapping and alignment

Safe alignment works across flex and grid alignment properties by appending -safe to the alignment value.

Logical properties, scrollbars, and size containers

• Spacing and borders: pbs-*, pbe-*, mbs-*, mbe-*, scroll-pbs-*, scroll-pbe-*, scroll-mbs-*, scroll-mbe-*, border-bs-*, and border-be-*.
• Sizing: inline-*, block-*, min-inline-*, max-inline-*, min-block-*, and max-block-*.
• Positioning: inset-s-*, inset-e-*, inset-bs-*, and inset-be-*.

<div class="scrollbar-thin scrollbar-thumb-sky-700/60 scrollbar-track-sky-100 scrollbar-gutter-stable overflow-auto"></div>
<div class="@container-size/sidebar"><div class="h-[50cqb]"></div></div>

@container-size creates a size container with block-axis units such as cqb and cqh; use @container-size/{name} for a named one.

Variant Quick Reference

<button class="p-2 pointer-coarse:p-4">Select</button>
<input required class="border user-valid:border-green-500 user-invalid:border-red-500" />
<div class="hidden noscript:block">Please enable JavaScript.</div>

In authored CSS, a colon stacks conditions while a comma applies one declaration block to alternatives:

.button {
  @variant hover:focus { background: var(--color-sky-600); }
  @variant active, disabled { opacity: 50%; }
}

Integration Choices

• Use @reference in component styles or CSS modules to expose theme values, custom utilities, and variants without duplicating the referenced stylesheet.
• Use @tailwindcss/vite with Vite projects, including Vite 8.
• Use @tailwindcss/webpack to run Tailwind directly as a webpack loader instead of routing through PostCSS.
• Add --poll or --poll=<milliseconds> to CLI watch mode when filesystem events are unavailable or unreliable.
• prettier-plugin-tailwindcss can sort classes while removing duplicate classes and unnecessary whitespace.
• Tailwind Plus plain-HTML UI blocks include accessible interactive behavior without a framework requirement.

Before You Finish

• Confirm tokens that should create utilities live in @theme, not only in :root.
• Check migrated gradients and logical positioning for renamed classes.
• Keep @source inline() inputs explicit and use exclusions narrowly.
• Choose primary-pointer or any-pointer variants based on the actual interaction requirement.
• Prefer higher-level typography utilities such as tabular-nums before font-features-*.
• Open the topic references before changing configuration or writing compatibility-sensitive utilities.