TailwindCSS-Claude-Skill-Package

Use when a Tailwind utility class is in the compiled CSS but does NOT visually override a component class or a third-party rule, when @apply produces output that does not behave like the utility applied to a real element, when a custom utility you authored inside CSS does not respect responsive or hover variants, when plugin-emitted classes get overridden by your own classes in unexpected ways, or when you reach for !important and want to know the right syntax for v3 vs v4. Prevents the unlayered-CSS trap (custom CSS written outside @layer wins over any utility because unlayered styles defeat the cascade), the @apply !important-strip trap (v3 silently removes !important from utilities pulled in via @apply), the v3-vs-v4-important syntax flip (v3 prefix !bg-red-500, v4 suffix bg-red-500!), the wrong-layer trap (custom CSS in @layer base when you wanted utility-level priority), the plugin-order trap (v3 plugins array : LAST entry wins when two plugins emit the same class), and the same-property in @apply trap (

Use when upgrading a Tailwind CSS v3 codebase to v4 and hitting silent visual regressions, build errors after switching imports, or unexpected behavior changes that the codemod did not catch. Catalogs every default-behavior change between v3 and v4 with symptoms, root causes, and surgical fixes. Prevents the variant-order trap (v3 right-to-left first:*:pt-0 silently becomes wrong in v4 left-to-right where the correct form is *:first:pt-0), the invisible-borders trap (v4 default border-color flipped from gray-200 to currentColor so every border now renders in the parent text color), the thin-ring trap (default ring width dropped from 3px to 1px so focus rings disappear under existing UI), the shadow-shift trap (shadow-sm in v3 became shadow-xs in v4, shadow in v3 became shadow-sm in v4, same shift applies to blur, drop-shadow, backdrop-blur, rounded), the removed-config trap (corePlugins / safelist / separator no longer exist in JS config), the bg-opacity-removed trap (bg-opacity-50 no longer works, use bg-bla

Use when reviewing a Tailwind CSS codebase for cross-rule violations, performing a pre-PR audit of changes that touch styling, validating a v3-to-v4 migration result, or running a periodic codebase health check across utility classes, plugin authoring, and configuration files. The agent acts as a Tailwind-specific code reviewer that enforces every rule documented in the sibling skills of this package, producing an actionable report that cites the authoritative sibling skill for each finding. Prevents the four highest-impact Tailwind code-review misses: dynamic template-literal class strings that compile cleanly but emit no CSS in production, scoped @apply blocks in Vue/Svelte/CSS-modules without @reference under v4, v3-only config keys (corePlugins, safelist, separator) silently ignored after a v4 upgrade, and bare border/ring/placeholder usage inheriting the wrong default colour post-migration. Covers the full rule catalogue (no dynamic class strings, no scoped @apply without @reference, no v3 keys in v4 con

Use when a Tailwind build completes successfully but the compiled CSS is empty, partial, or stale, when classes appear in markup but styles never render in the browser, when a freshly added utility refuses to take effect, when an HMR update leaves the page styled with the previous build, or when a monorepo package's components ship un-styled because the scanner does not look at their files. Prevents the dynamic-class-name trap (string interpolation breaks detection in BOTH v3 content scanner and v4 Oxide scanner, the most common reason for "Tailwind is broken"), the too-narrow content glob (v3 content array misses new directories), the cached-build trap (Vite's node_modules/.vite cache + Next.js .next cache hold stale class output), the Turbopack arbitrary-value miss (Next.js 16.x + Turbopack incremental build misses aspect-[12/5], z-[100]), the Astro v4.0.8 regression (pin to v4.0.7), the monorepo-import trap (importing a UI lib from node_modules whose classes the scanner never sees), and the v3-v4 directive

Use when a Tailwind element has 20+ utility classes on one line, when reviewers complain about "utility soup", or when deciding between leaving utilities inline, extracting a component, or pulling utilities into @apply. Prevents the premature-extraction trap (extracting after one duplicate destroys readability and adds indirection), the never-extract trap (copy-pasting 30 utilities across 8 files), the @apply-everywhere trap (rebuilding the CSS framework you opted out of), the unsorted-class trap (random order produces noisy diffs and merge conflicts), and the whitelist-blocks-arbitrary trap (eslint-plugin-tailwindcss no-custom-classname rejects valid arbitrary-value classes without `whitelist`). Covers the 3-use rule (extract on the third copy, not the first), component vs @apply vs template partial decision, prettier-plugin-tailwindcss install + config (tailwindConfig for v3, tailwindStylesheet for v4, tailwindFunctions for clsx/cva/tw, tailwindAttributes for custom props), eslint-plugin-tailwindcss rules (

Use when Tailwind classes work in development but disappear in production builds, or when class names assembled at runtime (template literals like bg-${color}-500, server-injected JSON, CMS-driven attributes, i18n strings, user-configured colours) render in the DOM but produce no visible style. This is the most-reported Tailwind issue (tailwindlabs/tailwindcss issue 18136). Prevents the four most common wrong fixes: turning off purge/JIT entirely (no longer possible in v4 and wastes bundle weight in v3), pasting a massive hand-written safelist that drifts out of sync with the design system, listing every possible class as plain strings somewhere in source then deleting them (the cache survives only one build), and monkey-patching the build to ship the full unminified Tailwind output to production. Covers the four supported fixes ranked by preference: (1) map prop to complete static class string via lookup object, (2) inline style for truly arbitrary user values, (3) v3 safelist array and regex pattern with va

Use when migrating a project from Tailwind CSS v3.4 to v4.0+, deciding between the automated upgrade tool and manual conversion, planning a dual-version monorepo transition, auditing a codebase before the upgrade, or verifying behaviour after the upgrade. Prevents the five most damaging migration mistakes: assuming the automated tool covers 100 percent (it does not handle runtime opacity classes built from strings, scoped @apply blocks, or visual regressions from default border-color changes), running the tool without first auditing corePlugins/safelist/separator usage (all three removed or relocated in v4), missing the shadow/blur/rounded scale shift (shadow-sm in v3 is shadow-xs in v4, an entire visual layer jumps), ignoring the variant stacking-order flip (first:*:pt-0 becomes *:first:pt-0), and forgetting that @apply in Vue/Svelte/CSS-modules requires @reference in v4. Covers the npx @tailwindcss/upgrade tool (Node 20+, branch workflow, what it converts), the complete breaking-changes catalogue (renamed u

Use when composing Tailwind class strings dynamically across React, Vue, Svelte, Solid, or any framework where a parent component passes override classes to a child via a className prop, and the child combines them with its own defaults. Solves the duplicate-utility problem (twMerge('p-2 p-4') -> 'p-4') so the LAST value wins deterministically instead of the cascade emitting both and the outcome depending on stylesheet ordering. Prevents the ineffective-override trap (passing 'p-4' to a child whose default is 'p-2 text-blue-500' leaves BOTH padding classes in the markup, and whichever the bundler ships later wins), the stale-cache trap (calling extendTailwindMerge inside a render path on every render rebuilds the big data structure), the wrong-package-version trap (tailwind-merge v2.x is for Tailwind v3, v3.x is for Tailwind v4), and the prefix-mismatch trap (custom Tailwind prefix tw- requires configuring tailwind-merge with that prefix or merges silently return wrong output). Covers twMerge / twJoin / exten

Use when writing custom CSS that needs to share design tokens with Tailwind utilities via @apply, organizing component / base / utility CSS via @layer, or fixing the "Cannot apply unknown utility class" error in Vue, Svelte, or CSS-module scoped styles by adding @reference. Prevents the utility-extraction anti-pattern (wrapping every utility in @apply destroys utility-first benefits like JIT pruning, in-context readability, and consistent design tokens), the scoped-style trap in v4 (Vue SFC, Svelte SFC, and CSS modules evaluate @apply against an empty token registry without @reference, failing with "Cannot apply unknown utility class"), the layer-order trap (custom CSS outside @layer leaks above utilities and gets overridden), the important-modifier syntax flip between v3 (leading bang, !font-bold) and v4 (trailing bang, font-bold!), and the @apply !important keyword vs modifier confusion. Covers @apply semantics (copies utility declarations into the current rule), @layer base / components / utilities (specif

Use when installing, configuring, or customising any of the four official Tailwind plugins: @tailwindcss/typography (prose classes for rendered Markdown), @tailwindcss/forms (form-input/select/checkbox base reset), @tailwindcss/container-queries (@container variants), @tailwindcss/aspect-ratio (legacy aspect-w-*/aspect-h-* syntax). Prevents the v3-syntax-in-v4 trap (require() arrays do not work in v4, you need @plugin), the missing-plugin trap (forgetting to add container-queries to v3 silently emits zero @-variant classes), the unneeded-plugin-in-v4 trap (installing container-queries or aspect-ratio in v4 wastes bundle size and ships duplicated utilities), the forms-strategy mismatch (strategy base auto-styles every form element globally, strategy class only adds form-* classes), the not-prose escape miss (Markdown rendered inside a button or card inherits prose typography unintentionally), and the typography theme-customisation confusion (v3 uses theme.typography in JS, v4 uses @plugin block syntax). Covers

Use when authoring a custom Tailwind CSS plugin to add utilities, components, base styles, or variants, regardless of whether the host project runs Tailwind v3 (JS plugin in tailwind-config-js) or v4 (JS plugin loaded via @plugin or the CSS-native @utility directive). Prevents the four most common plugin-authorship traps: registering utilities through addBase (where variants do not apply), forgetting the second-argument default theme so theme('tabSize') returns undefined, omitting the values map on matchUtilities causing zero classes to compile, and importing tailwindcss/plugin in a v4-only project where the package no longer exists at runtime. Covers the full plugin() signature (addUtilities, addComponents, addBase, addVariant, matchUtilities, matchComponents, matchVariant, theme, config, corePlugins, e), plugin-withOptions for parameterised plugins, shipping default theme values through the configFn, the v4-native @utility name-* with --value() and --modifier(), the v4 @custom-variant directive, the v4 @plu

Use when wiring Tailwind CSS into Astro, SvelteKit, Nuxt, or Remix: choosing the right install path per framework + Tailwind version, picking the correct config file (astro.config.mjs, svelte.config.js, nuxt.config.ts, vite.config.ts), placing the global CSS in the framework-specific location, importing it from the right entry (layout, root, app.vue), and handling SSR/CSR specifics. Prevents the wrong-integration trap (using @astrojs/tailwind with v4 instead of @tailwindcss/vite, using @nuxtjs/tailwindcss module with v4 instead of the Vite plugin), the missing-import trap (global CSS file exists but never imported in layout/root, so utilities silently miss), the SSR-flash trap (CSS not in critical path because imported in client-only branch), the v3-v4 mix-up (npx astro add tailwind installs the v3 integration even in a v4 project), and the wrong-CSS-path trap (Nuxt expects ./app/assets/css/main.css, Remix expects ./app/tailwind.css with ?url query). Covers Astro 4+/5+ (v4 via Vite plugin in astro.config, v3

Use when wiring Tailwind CSS into a non-Vite build : the PostCSS plugin (Next.js, Remix, Astro pre-Vite, Nuxt v3, Webpack, Rollup, esbuild, Parcel, Laravel Mix, Symfony Encore, any postcss.config.js consumer), or the standalone CLI binary for Rails, Laravel Blade, Django, PHP, Go, Rust, Elixir, .NET, or any non-Node project that has no JS bundler. Prevents the wrong-plugin-name trap (v4 ships @tailwindcss/postcss as a separate package, NOT tailwindcss directly), the autoprefixer-duplication trap (v4 includes Lightning CSS so adding autoprefixer in postcss.config breaks the cascade), the forgot-init trap (v3 requires npx tailwindcss init to create tailwind.config.js before content scanning works), the CLI-binary-vs-npx trap (CLI runs as npx @tailwindcss/cli in v4 but npx tailwindcss in v3), and the @tailwind-vs-@import trap (v3 uses three @tailwind directives, v4 uses one @import "tailwindcss"). Covers postcss.config.mjs/cjs/js for both versions, every CLI flag (--input/-i, --output/-o, --watch, --minify, --co

Use when wiring Tailwind CSS into a Vite project: choosing between the v4 dedicated Vite plugin and the v3 PostCSS pipeline, picking the right packages and configs, importing the stylesheet, enabling HMR, and scoping template-scan paths in monorepos. Prevents the wrong-plugin trap (using postcss-plugin with v4 instead of @tailwindcss/vite gives much slower builds and broken at-rules), the broken-classnames trap (writing @import "tailwindcss" in v3 yields no utilities), the missing-content trap (v3 without content paths produces an empty stylesheet), the missing-source trap (v4 in a monorepo where workspace templates live outside the Vite root never get scanned), the upgrade trap (v4-0-8 Astro break, issue 16733), and the wrong-tool trap (chasing Turbopack issue 19825 in a Vite project). Covers v4 with @tailwindcss/vite (install, vite-config-ts plugin entry, @import "tailwindcss" in the entry CSS, automatic content detection, @source for monorepo/external paths, HMR), v3 with postcss-plugin (npm install -D tai

Use when installing or wiring Tailwind CSS into a Next.js project, for either the App Router or the Pages Router, on Tailwind v3 or v4, and when hooking next/font/google families into the Tailwind theme so utilities like font-sans resolve to the loaded family. Prevents the four most common Next-js install traps: importing globals.css in the wrong file for the active router, forgetting the @tailwindcss/postcss plugin under v4, breaking the v3 content glob on catch-all route folders named [...slug], and pasting font CSS variables into next/font/local without declaring them inside @theme inline so they never become utilities. Covers v4 App Router with @import tailwindcss, v4 Pages Router, v3 App Router with @tailwind directives, v3 Pages Router, next/font wiring via className on html plus @theme inline { --font-sans: var(--font-inter) }, why React Server Components have zero runtime cost from Tailwind, and the Turbopack arbitrary-value miss workaround for Next 16 plus v4 from tailwindlabs/tailwindcss issue 19825

Use when configuring a Tailwind CSS v3.4 project: writing the `tailwind.config.js` / `.mjs` / `.ts` file, setting up content scanning globs, extending or replacing the default theme, registering plugins, picking a dark-mode strategy, disabling core utilities, safelisting classes that string-concatenation produces, or applying a project-wide prefix. Use also when reading an existing v3 config and needing to know the precise semantics of `theme` vs `theme.extend`, what `corePlugins`, `safelist`, and `separator` do, and which options are REMOVED in v4 so a v3 to v4 migration plan can flag them in advance. Prevents (a) accidentally REPLACING the default theme by writing `theme: { colors: {...} }` when `theme.extend.colors` was intended, (b) leaking content scanning into `node_modules` via `./**/*.{js,html}` and tanking build times, (c) configuring `darkMode: 'class'` and forgetting to toggle the class on `<html>` (no dark styles ever fire), (d) using `corePlugins: { float: false }`, `safelist: [...]`, or `separat

Use when setting up or editing a Tailwind CSS v4 configuration via the CSS-first model: writing the entry stylesheet, defining design tokens in @theme, scoping content detection with @source, adding custom utilities with @utility, declaring custom variants with @custom-variant, wiring legacy JS plugins via @plugin, or fixing the Vue/Svelte/CSS-modules @apply trap with @reference. Prevents the silent-token-drop trap (defining @theme tokens without correct namespace prefix yields nothing), the lost-overrides trap (forgetting --color-*: initial before custom palette leaves old defaults active), the scoped-style breakage (@apply in Vue <style scoped> fails without @reference), the safelist miss (forgetting @source inline brace expansion for dynamic class names), and the @theme inline confusion (resolves var refs at build vs runtime). Covers every v4 directive (@import, @theme, @theme inline, @theme static, @source, @source not, @source inline, @source none, @plugin, @utility with --value/--modifier/--alpha/--spac

Use when reaching for v4-only modern CSS utilities that were unavailable or required heavy custom code in v3: CSS-only enter and exit animations on dialogs and popovers via `@starting-style` plus the `starting:` variant and `transition-discrete`, auto-resizing textareas via `field-sizing-content`, native form-control colour scheme via `scheme-*`, variable-font width axes via `font-stretch-*`, and layered inset shadows and inset rings via `inset-shadow-*` and `inset-ring-*`. Prevents the canonical v3-mental-model traps: trying to animate `display: none` to `display: block` without `transition-discrete` (the property never transitions in v3), using a JS resize hook instead of `field-sizing-content` (verbose and laggy compared to the native CSS property), setting `color-scheme` via inline style when the `scheme-*` utility exists, and stacking multiple `box-shadow` declarations in custom CSS when `inset-shadow-*` plus outer `shadow-*` plus `ring-*` plus `inset-ring-*` compose four layers natively. Covers: `transi

Use when building linear, conic, or radial gradient backgrounds, picking an interpolation colour space (oklab default, oklch, srgb, hsl, longer-hue, shorter-hue), placing color stops at specific positions, or migrating a v3 `bg-gradient-to-r from-X to-Y` markup to v4's expanded gradient API with `bg-linear-*`, `bg-radial-*`, and `bg-conic-*`. Prevents the rename-trap (every v3 `bg-gradient-*` class is renamed to `bg-linear-*` in v4), the muddy-middle trap (sRGB interpolation produces a gray midpoint between saturated complementary colours where oklch keeps it vivid), the conic-without-from trap (`bg-conic` without a `from-{color}` produces an invisible gradient), and the v3-radial-by-arbitrary trap (v3 has no native bg-radial-* and forces `bg-[radial-gradient(...)]`). Covers every linear direction utility, the angle-based form (bg-linear-45), the conic and radial families, every from-/via-/to- color and position stop, and the seven interpolation modifiers. Keywords: tailwind gradient, bg-linear, bg-linear-to-

Use when authoring custom Tailwind utilities in v4 with the `@utility` directive that need to accept parameters: a theme-namespace key (like `tab-github`, `tab-2`, `tab-4`), a bare integer/number/ratio/percentage, a literal keyword, an arbitrary bracketed value, or a slash-modifier (like `text-base/relaxed`). Prevents the common v3-to-v4 plugin-authoring mistakes: writing a `matchUtilities()` JS plugin where a native `@utility name-* { ... }` block would do, attempting to use `--value()` / `--modifier()` / `--alpha()` / `--spacing()` inside v3 (silently ignored as unrecognised CSS functions), and forgetting that `--value()` accepts multiple type forms simultaneously so users can pick theme key OR bare integer OR arbitrary bracket on the same utility. Covers: the four v4-only CSS functions `--value()`, `--modifier()`, `--alpha()`, `--spacing()`; type-hint syntax (`integer`, `[length]`, `--namespace-*`, literal strings, `[*]`); default-value syntax via `--default(<value>)`; combining theme keys with bare and ar

Use when building 3D effects in Tailwind v4: card-flip animations, 3D carousels, product showcases, hover-reveal effects, parallax-like depth, or any layout that requires elements to rotate or translate along the Z axis. Use also when an existing v3 project is migrating to v4 and adopting depth effects for the first time, or when reading v4 markup that contains `transform-3d`, `perspective-*`, `rotate-x-*`, `rotate-y-*`, `rotate-z-*`, `translate-z-*`, or `backface-hidden` and needing to know what each utility does and what its parent must declare. Prevents (a) applying 3D rotations without declaring `perspective-*` on the parent, which renders flat with no depth, (b) forgetting `transform-3d` on the parent of a 3D scene, which collapses children into 2D space, (c) leaving the back of a card-flip element visible during the flip because `backface-hidden` was omitted, (d) reaching for these utilities in a Tailwind v3.4 project where NONE of the 3D-axis utilities exist (they compile to nothing and the layout sile

Use when adding, debugging, or migrating dark-mode support in a Tailwind project: choosing between the default `prefers-color-scheme` strategy and user-toggleable class or attribute strategies, wiring the JavaScript toggle, swapping CSS-variable token values for light vs dark, or porting v3 `darkMode` configuration to the v4 `@custom-variant dark` directive. Prevents the four canonical dark-mode failures: assuming `dark:` utilities need configuration before they work, leaving v3's `darkMode: 'class'` config in a v4 project (silently ignored), forgetting the v4 `@custom-variant dark` directive when migrating from v3 `darkMode: 'class'`, and shipping a toggle that flashes the wrong theme on first paint because the script runs after CSS. Covers: default `media` strategy, class-based toggling (v3 `darkMode: 'class'` and 'selector', v4 `@custom-variant dark (&:where(.dark, .dark *))`), attribute-based toggling (`[data-theme="dark"]`), custom variant strategies, theme-token swap via CSS variables, and the canonical

Use when styling element states (form input validity, checked, disabled, required, placeholder visibility), structural positions (first, last, even, odd, nth-child), pseudo-elements (before, after, placeholder, file, marker, selection, first-letter), or motion-preference (motion-safe, motion-reduce), or when wiring a Tailwind class to a CSS pseudo-element with the content utility. Prevents the empty-before-pseudo trap (the ::before disappears when Preflight is disabled), the structural-variant scope mistake (first: applied to grandchildren when it should be on direct children), the placeholder-styling mistake (placeholder: on the wrapper instead of the input), the form-state target mistake (invalid: triggers before user input via :user-invalid in v4), and the dialog/details open-state confusion (open: works for both via the :is() compound). Covers structural pseudo-class variants, all pseudo-element variants, the content-[...] utility for ::before and ::after, motion-preference media query variants, the full

Use when needing a one-off value that is not in the theme: specific hex colors, arbitrary pixel sizes, calc() expressions, custom grid templates, unusual font sizes, specific transforms, custom selectors, runtime CSS-variable values. Use also when reading existing Tailwind markup and encountering `bg-[#1da1f2]`, `w-[calc(100%-2rem)]`, `data-[state=open]:`, `[mask-type:luminance]`, `bg-(--brand)`, `[&_p]:`, or any other square-bracket / parens-bracket utility, and needing to know what it compiles to. Use also when an arbitrary value is being misinterpreted (background-size vs background-position, font-size vs color) and a type hint is required. Prevents (a) reaching for arbitrary syntax when a theme token already exists (lazy arbitrary values fragment design systems), (b) dynamic class-string concatenation like `bg-[${color}]` that never appears as a literal token and silently generates no CSS, (c) using v4 parens CSS-var syntax `bg-(--brand)` in a v3 project where it is parsed incorrectly, (d) using literal s

Use when building responsive layouts with Tailwind CSS, picking between viewport breakpoints (sm/md/lg/xl/2xl) and container queries (@sm, @md, named @container/name), targeting a breakpoint range with max-* variants, using arbitrary breakpoints (min-[400px], max-[800px]), customising the default breakpoint set, or migrating a v3 codebase that installed @tailwindcss/container-queries to v4 where container queries are built-in. Prevents the mobile-first mistake (sm:text-center hiding text on mobile), the v3-to-v4 plugin trap (forgetting to remove the container-queries plugin in v4 still works but emits warnings), and the named-container scoping mistake (@sm:flex bleeding across nested @container parents). Covers viewport breakpoints, max-* range targeting, arbitrary breakpoints, custom breakpoint registration (v3 theme.screens vs v4 @theme --breakpoint-*), container queries (built-in v4 vs plugin v3), named containers, the full @3xs through @7xl scale, and container-query length units (cqw, cqh, cqi, cqb). Key

Use when writing Tailwind markup and you need to recall or verify the vocabulary of base utility families (spacing, color, typography, layout, flexbox, grid, sizing, border, background, effects). Also use when diagnosing why a class name does not produce expected styling, or when porting from a different framework and looking up the Tailwind equivalent. Prevents incorrect class names that the content scanner silently ignores, the v4 shadow-scale shift confusion where `shadow-sm` is smaller than v3's `shadow-sm` because `shadow-xs` was inserted, and the "I thought sm: meant small screens only" responsive trap (see [tailwind-syntax-responsive] for the full responsive treatment). Covers : the canonical class vocabulary for the ten base utility families with v3 and v4 differences flagged inline; the value scales (spacing 0..96, type xs..9xl, shadow 2xs..2xl, color 50..950, etc.); v4 dynamic spacing utilities that accept any integer; v4 opacity modifier syntax (`bg-red-500/50`); the official 22-family color palett

Use when applying conditional styles in Tailwind: hover, focus, active, dark mode, responsive breakpoints, group-* and peer-* combinators, aria-* and data-* attribute variants, has-* and not-* selectors, position-in-parent variants (first, last, *, nth-*), or arbitrary [&...] variants. Use also when stacking multiple variants (`md:hover:dark:bg-blue-500`) and the resulting selector does not match the intended element. Use also when migrating variant chains from Tailwind v3 to v4: the stacking order flipped from right-to-left to left-to-right and is the #1 silent breakage during upgrade. Prevents the common mistakes of (a) reading a v3 stack like `first:*:pt-0` and expecting the same compiled selector in v4 (it is now `*:first:pt-0`), (b) writing hover variants that mysteriously stop working on touch devices in v4 (hover is now gated on `@media (hover: hover)`), (c) writing `!flex` important syntax that fails silently in v4 (the bang moved to the trailing position: `flex!`), (d) using unscoped `group-hover:` w

Use when starting a new Tailwind CSS project, evaluating whether Tailwind fits a codebase, debating utility-first vs BEM / CSS Modules / CSS-in-JS, or reviewing a PR that mixes architectural styles. Prevents the "ad-hoc CSS leaking into utility-first markup" failure mode, premature `@apply` extraction, and dynamic-class anti-patterns that break the content scanner. Covers utility-first philosophy, atomic CSS tradeoffs, the design-system constraint model, how Tailwind scans source files for classes, when utility-first wins, when it loses, and a decision tree for adoption. Both Tailwind v3.4 and v4 share this architecture; engine details (JIT vs Oxide) live in tailwind-core-v3-vs-v4. Keywords: utility-first, atomic CSS, design tokens, content scanning, source detection, constraint-based design, when to use Tailwind, should I use Tailwind, Tailwind vs BEM, Tailwind vs CSS Modules, Tailwind vs CSS-in-JS, utility soup, premature extraction, no styles showing up, classes not generated, blank page after build, dynam

Use when designing or picking values for a Tailwind CSS project: choosing spacing units, color tokens, font sizes, breakpoints, or opacity. Use also when reading existing utility classes and needing to know whether a value comes from the default theme or a custom override. Prevents hardcoded colors, ad-hoc spacing arithmetic, mismatched type scales, and the common v3 to v4 color-format mistake (rgb/hsl vs oklch). Covers the default spacing scale (single base unit in v4, 32-step scale in v3), the default 22 color families (slate / gray / zinc / neutral / stone plus 17 chromatic families), the v4 oklch P3 wide-gamut color format vs the v3 rgb/hsl format, the text-xs through text-9xl type scale, the default breakpoint scale (sm 640, md 768, lg 1024, xl 1280, 2xl 1536), the v4 CSS-variable token model (--color-*, --spacing, --font-*, --text-*, --breakpoint-*, --radius-*, --shadow-*), the v3 tailwind.config.js theme object, and opacity modifier syntax (bg-red-500/50, text-white/[0.85], bg-cyan-400/(--my-alpha)). K

Use when picking a Tailwind CSS version for a new project, deciding whether to upgrade an existing v3 codebase to v4, or debugging visual regressions and build errors that appear right after a v3 to v4 bump. Prevents the silent visual breakages (border-color, ring-width, shadow scale rename) and the removed-option traps (corePlugins, safelist, separator) that bite every v3 to v4 migration. Covers the JIT vs Oxide engine model, JS config vs CSS-first @theme configuration, default behaviour shifts, removed APIs, browser baseline requirements, and the upgrade-or-stay decision tree. Keywords: tailwind v3, tailwind v4, tailwindcss v4, oxide engine, JIT, tailwind upgrade, tailwind migration, @theme, @tailwind directive removed, corePlugins removed, safelist removed, separator removed, ring-width changed, border-color changed, shadow-sm changed, should I upgrade tailwind, tailwind 4 vs 3, breaking changes tailwind, lightning css, @import tailwindcss