Tailwind CSS debugging and troubleshooting guide for common issues and solutions
Provides Tailwind CSS debugging guidance for common issues and v4 migration problems.
npx claudepluginhub josiahsiegel/claude-plugin-marketplaceThis skill inherits all available tools. When active, it can use any tool Claude has access to.
references/troubleshooting-guide.mdv4 automatically detects content, but if styles are missing:
/* Explicitly specify sources */
@import "tailwindcss";
@source "./src/**/*.{html,js,jsx,ts,tsx,vue,svelte}";
<!-- 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'}>
# Restart dev server
npm run dev
# Clear cache and rebuild
rm -rf node_modules/.vite
npm run build
// OLD (v3)
export default {
plugins: {
tailwindcss: {},
autoprefixer: {}
}
}
// NEW (v4)
export default {
plugins: {
'@tailwindcss/postcss': {}
}
}
/* v4 - Configure in CSS, not JS */
@import "tailwindcss";
@theme {
--color-primary: oklch(0.6 0.2 250);
}
/* v4 - Add if using selector strategy */
@custom-variant dark (&:where(.dark, .dark *));
/* Browser DevTools: Inspect element → Styles panel */
/* Look for crossed-out styles */
<!-- Use !important (last resort) -->
<div class="!mt-0">
<!-- Or increase specificity with variants -->
<div class="[&]:mt-0">
/* Your custom CSS should come after Tailwind */
@import "tailwindcss";
@import "./custom.css"; /* After Tailwind */
/* Ensure plugin is loaded */
@plugin "@tailwindcss/typography";
<!-- 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>
<!-- Forms plugin only styles inputs with type attribute -->
<input type="text" /> <!-- ✓ Styled -->
<input /> <!-- ✗ Not styled -->
@plugin "@tailwindcss/forms" {
strategy: class;
}
<!-- Now explicitly opt-in -->
<input type="text" class="form-input" />
# Install Tailwind CSS IntelliSense
code --install-extension bradlc.vscode-tailwindcss
Features:
npm install -D @tailwindcss/debug-screens
@plugin "@tailwindcss/debug-screens";
<!-- Shows current breakpoint in corner -->
<body class="debug-screens">
# Output CSS to file for inspection
npx tailwindcss -o output.css --content './src/**/*.{html,js}'
# With verbose logging
DEBUG=tailwindcss:* npm run build
# Look for plugin-related errors
npm run build 2>&1 | grep -i plugin
/* In browser DevTools, check :root for variables */
:root {
--color-blue-500: oklch(...);
--spacing-4: 1rem;
}
/* Add explicit sources if auto-detection fails */
@source "./src/**/*.tsx";
@source "./components/**/*.tsx";
/* Exclude paths */
@source not "./src/generated/**";
npm install -D @tailwindcss/postcss
Using v3 tooling with v4 syntax. Update your build setup:
npm install -D tailwindcss@latest @tailwindcss/postcss@latest
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]
# Restart dev server
npm run dev
# Clear Vite cache
rm -rf node_modules/.vite
# Clear Next.js cache
rm -rf .next
# Check CSS file size
ls -lh dist/assets/*.css
# If too large, check for:
# 1. Dynamic class generation
# 2. Unnecessary safelisting
# 3. Unused plugins
# Time the build
time npm run build
# v4 should be very fast
# Full build: <1s
# Incremental: microseconds
@import "tailwindcss";@tailwindcss/postcss (not tailwindcss)@tailwindcss/vite (if using Vite)# 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
Expert guidance for Next.js Cache Components and Partial Prerendering (PPR). **PROACTIVE ACTIVATION**: Use this skill automatically when working in Next.js projects that have `cacheComponents: true` in their next.config.ts/next.config.js. When this config is detected, proactively apply Cache Components patterns and best practices to all React Server Component implementations. **DETECTION**: At the start of a session in a Next.js project, check for `cacheComponents: true` in next.config. If enabled, this skill's patterns should guide all component authoring, data fetching, and caching decisions. **USE CASES**: Implementing 'use cache' directive, configuring cache lifetimes with cacheLife(), tagging cached data with cacheTag(), invalidating caches with updateTag()/revalidateTag(), optimizing static vs dynamic content boundaries, debugging cache issues, and reviewing Cache Component implementations.
Creating algorithmic art using p5.js with seeded randomness and interactive parameter exploration. Use this when users request creating art using code, generative art, algorithmic art, flow fields, or particle systems. Create original algorithmic art rather than copying existing artists' work to avoid copyright violations.