tailwindcss-debugging

Q: How do I install tailwindcss-debugging?

Run npx skills add https://github.com/josiahsiegel/claude-plugin-marketplace --skill tailwindcss-debugging in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/tailwindcss-debugging/ (personal) or .claude/skills/tailwindcss-debugging/ (project).

by josiahsiegelCode Quality & Workflow

Tailwind CSS debugging and troubleshooting common issues. PROACTIVELY activate for: (1) classes not applying / no styles in browser, (2) JIT mode not picking up dynamic class names (string concatenation), (3) v3-to-v4 migration errors, (4) PostCSS configuration issues, (5) IntelliSense not autocompleting in VS Code, (6) production build missing classes (purge/content config), (7) CSS variable conflicts, (8) specificity issues with @layer, (9) prefix conflicts with other CSS frameworks, (10) HMR not updating styles. Provides: troubleshooting decision tree, dynamic-class allowlist patterns, content-config templates, IntelliSense setup, and PostCSS debugging steps.

Installs: 205
Last 24h: —
Trending rank: —
Security: Not audited

Install

Works with every agent the skills CLI supports.

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

01
Install
Run the command in your project. The CLI asks which agents to install for.
02
Describe the task
Ask your agent for something this skill covers. It loads tailwindcss-debugging automatically when relevant.
03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

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

Inspect Element → See computed styles
Styles Panel → See which rules apply
Filter → Search for Tailwind classes
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

FAQ

What does the tailwindcss-debugging skill do?

How do I install tailwindcss-debugging?

Run npx skills add https://github.com/josiahsiegel/claude-plugin-marketplace --skill tailwindcss-debugging in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/tailwindcss-debugging/ (personal) or .claude/skills/tailwindcss-debugging/ (project).

Which AI agents can use tailwindcss-debugging?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is tailwindcss-debugging safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains tailwindcss-debugging?

It is published by josiahsiegel in josiahsiegel/claude-plugin-marketplace. It has 205 recorded installs.