tailwind-errors-build-failures

name	tailwind-errors-build-failures
description	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-mix trap (using @tailwind base in v4 OR @import "tailwindcss" in v3 yields empty output). Covers v3 content array + safelist + blocklist + transform + extract, v4 auto-detect + @source + @source not + @source inline + @source none, brace-expansion safelist syntax, monorepo absolute-path patterns, Vite cache invalidation (rm -rf node_modules/.vite), Next.js cache invalidation (rm -rf .next), Turbopack workarounds, Astro version pinning, watch-mode-misses-new-directory restart procedure, and the static-class-name discipline that prevents 90% of all build failures. Keywords: tailwind build fails, no utility classes generated, empty output css, tailwind classes not applied, styles missing in build, jit not detecting class, content not scanned, @source not working, v4 source detection, v3 content array, safelist, blocklist, dynamic class names, string interpolation tailwind, monorepo tailwind, ui library not styled, node_modules tailwind, vite cache stale, node_modules/.vite, next cache, .next cache, turbopack arbitrary value, aspect-[12/5] not generated, z-[100] missing, next.js 16 turbopack, astro 4.0.8 broken, tailwind 4.0.7 pin, @tailwindcss/vite regression, @import tailwindcss missing utilities, watch mode not detecting new file, why is my tailwind class missing, my class is in html but no style, my padding class disappeared, tailwind not rebuilding, hot reload broken tailwind, brace expansion safelist, bg-red-{50,100,200,300}, force generate tailwind class, arbitrary values jit, monorepo @source absolute path, restart tailwind watcher
license	MIT
compatibility	Designed for Claude Code. Requires Tailwind CSS v3.4 or v4.0+.
metadata	{"author":"OpenAEC-Foundation","version":"1.0"}

Tailwind Build Failures : Why Your Classes Don't Render

The Tailwind compiler emits ONLY the utility classes it can DETECT in your source files. Every "Tailwind is broken" report is one of :

1. The compiler did not see the file containing the class.
2. The compiler saw the file but could not parse the class as a complete unbroken string.
3. The class was detected, compiled, but a stale build cache served yesterday's CSS to the browser.
4. A version-specific regression in v4 or Turbopack swallowed certain class patterns silently.

This skill is the diagnostic flow for all four. Always go top to bottom : root-cause-first.

Companion skills :

• tailwind-impl-config-v3 : the content array surface
• tailwind-impl-config-v4 : the @source directive surface
• tailwind-impl-build-vite : Vite-specific cache behaviour
• tailwind-impl-build-postcss-cli : PostCSS / CLI flow
• tailwind-errors-runtime : when classes ARE in CSS but not applied
• tailwind-errors-v4-migration : v3-to-v4 specific breakage

Quick Reference : 60-Second Diagnostic

1. Inspect compiled CSS (open the file the browser loads).
   - File is EMPTY                   -> scanner found nothing
   - File has SOME classes, missing X -> X was not detected
   - File looks right but browser shows old styles -> cache stale
   - File is missing a recently added class -> watcher missed it

2. Search compiled CSS for the missing class :
   grep "p-4" dist/output.css

3. If absent : the SCANNER missed it. Go to "Scanner Diagnosis".
   If present : the BUILD is stale OR another rule wins. Go to
   "Cache Diagnosis" + tailwind-errors-runtime.

Decision Tree : Scanner Missed the Class

Is the class an UNBROKEN STRING in source ?
  ├── NO  (string interpolation: `bg-${color}-500`)
  │   -> FIX: replace with static lookup (see "Static-Class Discipline")
  │
  └── YES
      ├── v3 : Is the file inside `content` globs ?
      │   ├── NO  -> add the glob OR widen existing one
      │   └── YES -> check next branch
      │
      └── v4 : Is the file inside auto-detect scope OR explicit @source ?
          ├── NO (file in node_modules, monorepo sibling, etc.)
          │   -> Add @source "../path/to/file"
          └── YES
              ├── Turbopack ? -> see "Turbopack Workaround"
              ├── Astro v4.0.8 ? -> pin to v4.0.7
              └── Otherwise -> restart watcher (new-directory case)

Decision Tree : Stale Cache

Did the class appear in CSS yesterday but not today after a code change ?

Vite project ?
  -> rm -rf node_modules/.vite ; npm run dev

Next.js project ?
  -> rm -rf .next ; npm run dev

Webpack project ?
  -> Disable persistent cache OR rm -rf node_modules/.cache

Astro project ?
  -> rm -rf .astro dist node_modules/.vite ; npm run dev

CLI watch mode ?
  -> Ctrl-C, restart npx (@tailwindcss/cli OR tailwindcss)