Tailwindcss Debugging

Name: Tailwindcss Debugging
Author: josiahsiegel

josiahsiegel/claude-plugin-marketplace

181 installs
50 repo stars
Updated June 18, 2026
josiahsiegel/claude-plugin-marketplace

Diagnose why Tailwind utilities fail to apply, purge unexpectedly, or conflict with component CSS during local dev and production builds.

About

Helps developers systematically debug Tailwind CSS problems: missing utilities, incorrect content globs, purge side effects, @layer conflicts, and build-time class generation failures across React, Vue, and plain HTML frontends.

Content path and purge configuration checks
Specificity and layer ordering fixes
JIT class generation troubleshooting
DevTools inspection workflows
Framework-specific style override patterns

Tailwindcss Debugging by the numbers

181 all-time installs (skills.sh)
+4 installs in the week ending Aug 2, 2026 (Skillselion tracking)
Ranked #893 of 2,245 Frontend Development skills by installs in the Skillselion catalog
Data as of Aug 3, 2026 (Skillselion catalog sync)

npx skills add https://github.com/josiahsiegel/claude-plugin-marketplace --skill tailwindcss-debugging

Add your badge

Show developers this skill is listed on Skillselion. Paste this into your README.

[![Listed on Skillselion](https://skillselion.com/badge/skills/josiahsiegel/claude-plugin-marketplace/tailwindcss-debugging.svg)](https://skillselion.com/skills/josiahsiegel/claude-plugin-marketplace/tailwindcss-debugging)

Installs	181
repo stars	★ 50
Last updated	June 18, 2026
Repository	josiahsiegel/claude-plugin-marketplace ↗

What it does

Diagnose why Tailwind utilities fail to apply, purge unexpectedly, or conflict with component CSS during local dev and production builds.

Files

SKILL.mdMarkdownGitHub ↗

Tailwind CSS Debugging & Troubleshooting

Common Issues & Solutions

1. Styles Not Applying

Check Content Detection

v4 automatically detects content, but if styles are missing:

/* Explicitly specify sources */
@import "tailwindcss";
@source "./src/**/*.{html,js,jsx,ts,tsx,vue,svelte}";

Verify Class Names

<!-- WRONG - Dynamic class won't be detected -->
<div class={`text-${color}-500`}>

<!-- CORRECT - Use complete class names -->
<div class={color === 'blue' ? 'text-blue-500' : 'text-red-500'}>

Check Build Process

# Restart dev server
npm run dev

# Clear cache and rebuild
rm -rf node_modules/.vite
npm run build

2. v4 Migration Issues

PostCSS Plugin Changed

// OLD (v3)
export default {
  plugins: {
    tailwindcss: {},
    autoprefixer: {}
  }
}

// NEW (v4)
export default {
  plugins: {
    '@tailwindcss/postcss': {}
  }
}

Configuration Moved to CSS

/* v4 - Configure in CSS, not JS */
@import "tailwindcss";

@theme {
  --color-primary: oklch(0.6 0.2 250);
}

Dark Mode Variant

/* v4 - Add if using selector strategy */
@custom-variant dark (&:where(.dark, .dark *));

3. Classes Being Overridden

Check Specificity

/* Browser DevTools: Inspect element → Styles panel */
/* Look for crossed-out styles */

Solutions

<!-- Use !important (last resort) -->
<div class="!mt-0">

<!-- Or increase specificity with variants -->
<div class="[&]:mt-0">

Check Import Order

/* Your custom CSS should come after Tailwind */
@import "tailwindcss";
@import "./custom.css";  /* After Tailwind */

4. Typography Plugin Issues

Styles Not Applied

/* Ensure plugin is loaded */
@plugin "@tailwindcss/typography";

Utilities Overridden by Prose

<!-- Use element modifiers -->
<article class="prose prose-h1:text-4xl prose-a:text-blue-600">

<!-- Or escape prose entirely -->
<article class="prose">
  <div class="not-prose">
    <CustomComponent />
  </div>
</article>

5. Forms Plugin Issues

Styles Not Applied to Plain Inputs

<!-- Forms plugin only styles inputs with type attribute -->
<input type="text" />  <!-- ✓ Styled -->
<input />              <!-- ✗ Not styled -->

Using Class Strategy

@plugin "@tailwindcss/forms" {
  strategy: class;
}

<!-- Now explicitly opt-in -->
<input type="text" class="form-input" />

Debugging Tools

VS Code Extension

# Install Tailwind CSS IntelliSense
code --install-extension bradlc.vscode-tailwindcss

Features:

Autocomplete for class names
Hover previews showing CSS
Linting for errors
Color decorators

Debug Screens Plugin

npm install -D @tailwindcss/debug-screens

@plugin "@tailwindcss/debug-screens";

<!-- Shows current breakpoint in corner -->
<body class="debug-screens">

Browser DevTools

1. Inspect Element → See computed styles 2. Styles Panel → See which rules apply 3. Filter → Search for Tailwind classes 4. Computed Tab → See final computed values

Check Generated CSS

# Output CSS to file for inspection
npx tailwindcss -o output.css --content './src/**/*.{html,js}'

# With verbose logging
DEBUG=tailwindcss:* npm run build

v4 Specific Debugging

Check Plugin Loading

# Look for plugin-related errors
npm run build 2>&1 | grep -i plugin

Verify CSS Variable Output

/* In browser DevTools, check :root for variables */
:root {
  --color-blue-500: oklch(...);
  --spacing-4: 1rem;
}

Content Detection Issues

/* Add explicit sources if auto-detection fails */
@source "./src/**/*.tsx";
@source "./components/**/*.tsx";

/* Exclude paths */
@source not "./src/generated/**";

Common Error Messages

"Cannot find module '@tailwindcss/postcss'"

npm install -D @tailwindcss/postcss

"Unknown at-rule @theme"

Using v3 tooling with v4 syntax. Update your build setup:

npm install -D tailwindcss@latest @tailwindcss/postcss@latest

"Class 'X' doesn't exist"

Dynamic class generation issue:

// BAD
const classes = `bg-${dynamic}-500`

// GOOD
const colorMap = {
  primary: 'bg-blue-500',
  danger: 'bg-red-500'
}
const classes = colorMap[dynamic]

"Styles not updating in development"

# Restart dev server
npm run dev

# Clear Vite cache
rm -rf node_modules/.vite

# Clear Next.js cache
rm -rf .next

Performance Debugging

Large CSS Output

# Check CSS file size
ls -lh dist/assets/*.css

# If too large, check for:
# 1. Dynamic class generation
# 2. Unnecessary safelisting
# 3. Unused plugins

Slow Builds

# Time the build
time npm run build

# v4 should be very fast
# Full build: <1s
# Incremental: microseconds

Debugging Checklist

Initial Setup

[ ] Correct import: @import "tailwindcss";
[ ] PostCSS plugin: @tailwindcss/postcss (not tailwindcss)
[ ] Vite plugin: @tailwindcss/vite (if using Vite)
[ ] CSS file imported in entry point
[ ] Development server restarted after changes

Styles Not Applying

[ ] Class name is complete (no dynamic generation)
[ ] File is in content path
[ ] Browser cache cleared
[ ] No CSS specificity conflicts
[ ] Check DevTools for overridden styles

After Migration

[ ] tailwind.config.js removed or converted
[ ] @theme directive used for customization
[ ] PostCSS config updated
[ ] Dark mode variant added if using selector strategy
[ ] Plugins updated to v4-compatible versions

Production Issues

[ ] NODE_ENV=production
[ ] Build output includes styles
[ ] CSS file linked correctly
[ ] No dynamic class generation issues

Getting Help

Create Minimal Reproduction

# Create fresh project
npm create vite@latest repro -- --template react-ts
cd repro
npm install -D tailwindcss @tailwindcss/vite

# Add minimal code that shows the issue
# Share on GitHub Issues or Discord

Resources

Tailwind CSS Troubleshooting Guide

Classes Not Working

Symptom: Utility class has no effect

1. Dynamic Class Names

Most common issue. Tailwind can't detect dynamically constructed classes:

// WON'T WORK
const color = 'blue'
className={`bg-${color}-500`}  // ❌

// WORKS
const bgColors = {
  blue: 'bg-blue-500',
  red: 'bg-red-500',
}
className={bgColors[color]}  // ✓

2. Content Detection Failure

v4 auto-detects files, but may miss custom locations:

/* Add explicit source paths */
@import "tailwindcss";
@source "../custom-components/**/*.tsx";
@source "../../shared-ui/**/*.jsx";

3. CSS Specificity Conflict

Check browser DevTools for overridden styles:

Look for crossed-out declarations
Check for !important rules
Look for more specific selectors (IDs, inline styles)

Fix: Use !important modifier or restructure CSS:

<div class="!mt-0">Forces margin-top: 0</div>

4. Cache Issues

# Clear all caches
rm -rf node_modules/.cache .next/cache .vite

# Restart dev server
npm run dev

5. Build Not Running

Verify Tailwind is processing your CSS:

# Check for tailwind in output
grep "bg-blue-500" dist/output.css

Dark Mode Not Working

Symptom: `dark:` variants have no effect

1. Missing dark mode configuration

/* globals.css */
@import "tailwindcss";
@custom-variant dark (&:where(.dark, .dark *));

2. `dark` class not on html/body

<html class="dark">  <!-- Required for selector strategy -->
  <body>...</body>
</html>

3. Using wrong strategy

/* For media query strategy (prefers-color-scheme) */
@custom-variant dark (media(prefers-color-scheme: dark));

/* For selector strategy (class-based) */
@custom-variant dark (&:where(.dark, .dark *));

Responsive Breakpoints Not Working

Symptom: `sm:`, `md:`, etc. have no effect

1. Viewport too small

Remember breakpoints are mobile-first (min-width):

Prefix	Min-width
`sm:`	640px
`md:`	768px
`lg:`	1024px
`xl:`	1280px

2. Parent container constraining width

<!-- Parent might limit width -->
<div class="max-w-sm">
  <div class="md:flex"><!-- md: won't trigger if parent is narrow --></div>
</div>

3. Browser zoom affecting viewport

Reset zoom to 100% for accurate testing.

PostCSS / Build Errors

"Unknown at-rule @import"

Missing PostCSS configuration:

// postcss.config.mjs
export default {
  plugins: {
    '@tailwindcss/postcss': {},
  }
}

"Cannot find module 'tailwindcss'"

npm install -D tailwindcss @tailwindcss/postcss

Vite-specific errors

// vite.config.js
import tailwindcss from '@tailwindcss/vite'

export default defineConfig({
  plugins: [tailwindcss()],  // Must be in plugins
})

IntelliSense Not Working

VS Code autocomplete missing

1. Install extension

code --install-extension bradlc.vscode-tailwindcss

2. Configure for custom locations

// .vscode/settings.json
{
  "tailwindCSS.includeLanguages": {
    "typescript": "javascript",
    "typescriptreact": "javascript"
  },
  "tailwindCSS.experimental.classRegex": [
    ["clsx\\(([^)]*)\\)", "(?:'|\"|`)([^']*)(?:'|\"|`)"],
    ["cn\\(([^)]*)\\)", "(?:'|\"|`)([^']*)(?:'|\"|`)"],
    ["cva\\(([^)]*)\\)", "[\"'`]([^\"'`]*).*?[\"'`]"]
  ]
}

3. Restart extension

Cmd/Ctrl + Shift + P
"Tailwind CSS: Reload Extension"

Performance Issues

Slow builds

1. Too many files in content scan

/* Be specific with @source */
@source "./src/**/*.{tsx,jsx}";
@source not "./src/**/*.test.tsx";
@source not "./node_modules/**";

2. Large safelist

Minimize or remove safelist:

/* Avoid large safelists */
@source inline("bg-red-500 bg-blue-500");  /* Only when necessary */

Large CSS output

1. Check for dynamic class patterns

# Find potential issues
grep -r "bg-\${" src/ --include="*.tsx"
grep -r "text-\${" src/ --include="*.tsx"

2. Analyze output

# Check CSS size
ls -lh dist/assets/*.css

# Count selectors
grep -o '\.[a-zA-Z]' dist/output.css | wc -l

Common Migration Issues (v3 → v4)

Border color changed

/* v3: border used gray-200 by default */
/* v4: border uses currentColor */

/* Fix: Set explicit color */
.legacy-borders {
  @apply border-gray-200;
}

Ring defaults changed

/* v3: ring was 3px blue-500 */
/* v4: ring is 1px currentColor */

/* Fix: Be explicit */
@theme {
  --default-ring-width: 3px;
  --default-ring-color: var(--color-blue-500);
}

theme() function deprecated

/* v3 */
.element {
  background: theme(colors.blue.500);
}

/* v4 */
.element {
  background: var(--color-blue-500);
}

Debugging Checklist

Quick Verification

Add this test element to any page:

<div class="bg-red-500 p-4 text-white fixed top-0 right-0 z-50">
  Tailwind Working
</div>

Full Debug Steps

1. ✓ Check browser DevTools for the class 2. ✓ Search compiled CSS for the class name 3. ✓ Verify PostCSS config exists 4. ✓ Check for dynamic class name issues 5. ✓ Clear caches and restart 6. ✓ Check console for errors 7. ✓ Verify file is in content detection path 8. ✓ Check for CSS specificity conflicts

Browser DevTools

1. Right-click element → Inspect
2. Check "Styles" panel for your class
3. If present but crossed out → specificity issue
4. If missing → content detection or build issue
5. Check "Computed" panel for final values

Verbose Build Output

# See what Tailwind is processing
DEBUG=tailwindcss:* npm run build

Related skills

Vercel React Best PracticesAutomatically apply Vercel’s official React and Next.js performance rules during code generation and review.587k29.6k

Vercel Composition PatternsGenerate and refactor React components that stay maintainable as complexity grows without boolean prop explosion.267k29.6k

ShadcnAdd, compose, search, fix, and style production-grade React components directly from source without leaving their editor.257k120k

Develop UserscriptsCorrectly write, debug, and package userscripts for Tampermonkey and ScriptCat with proper metadata, GM APIs, and runtime decisions.224k72

Minimalist UiGenerate clean, editorial-style web interfaces with warm monochrome palettes, typographic hierarchy, bento grids and flat components that feel premium and utilita212k69.4k

Image To CodeConvert high-fidelity design images into production-ready, visually accurate frontend code that avoids generic AI design pitfalls.177k69.4k

Frontend Developmentfrontend

About

Tailwindcss Debugging by the numbers

Add your badge

What it does

Files

Tailwind CSS Debugging & Troubleshooting

Common Issues & Solutions

1. Styles Not Applying

Check Content Detection

Verify Class Names

Check Build Process

2. v4 Migration Issues

PostCSS Plugin Changed

Configuration Moved to CSS

Dark Mode Variant

3. Classes Being Overridden

Check Specificity

Solutions

Check Import Order

4. Typography Plugin Issues

Styles Not Applied

Utilities Overridden by Prose

5. Forms Plugin Issues

Styles Not Applied to Plain Inputs

Using Class Strategy

Debugging Tools

VS Code Extension

Debug Screens Plugin

Browser DevTools

Check Generated CSS

v4 Specific Debugging

Check Plugin Loading

Verify CSS Variable Output

Content Detection Issues

Common Error Messages

"Cannot find module '@tailwindcss/postcss'"

"Unknown at-rule @theme"

"Class 'X' doesn't exist"

"Styles not updating in development"

Performance Debugging

Large CSS Output

Slow Builds

Debugging Checklist

Initial Setup

Styles Not Applying

After Migration

Production Issues

Getting Help

Create Minimal Reproduction

Resources

Tailwind CSS Troubleshooting Guide

Classes Not Working

Symptom: Utility class has no effect

Dark Mode Not Working

Symptom: dark: variants have no effect

Responsive Breakpoints Not Working

Symptom: sm:, md:, etc. have no effect

PostCSS / Build Errors

"Unknown at-rule @import"

"Cannot find module 'tailwindcss'"

Vite-specific errors

IntelliSense Not Working

VS Code autocomplete missing

Performance Issues

Slow builds

Large CSS output

Common Migration Issues (v3 → v4)

Border color changed

Ring defaults changed

theme() function deprecated

Debugging Checklist

Quick Verification

Full Debug Steps

Browser DevTools

Verbose Build Output

Related skills

This week in AI coding

Symptom: `dark:` variants have no effect

Symptom: `sm:`, `md:`, etc. have no effect