tailwindcss-debugging

Included with Lifetime

$97 forever

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.

Web Dev

What this skill does


# Tailwind CSS Debugging & Troubleshooting

## Common Issues & Solutions

### 1. Styles Not Applying

#### Check Content Detection

v4 automatically detects content, but if styles are missing:

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

#### Verify Class Names

```html
<!-- 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

```bash
# 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

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

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

#### Configuration Moved to CSS

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

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

#### Dark Mode Variant

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

### 3. Classes Being Overridden

#### Check Specificity

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

#### Solutions

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

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

#### Check Import Order

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

### 4. Typography Plugin Issues

#### Styles Not Applied

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

#### Utilities Overridden by Prose

```html
<!-- 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

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

#### Using Class Strategy

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

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

## Debugging Tools

### VS Code Extension

```bash
# 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

```bash
npm install -D @tailwindcss/debug-screens
```

```css
@plugin "@tailwindcss/debug-screens";
```

```html
<!-- 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

```bash
# 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

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

### Verify CSS Variable Output

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

### Content Detection Issues

```css
/* 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'"

```bash
npm install -D @tailwindcss/postcss
```

### "Unknown at-rule @theme"

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

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

### "Class 'X' doesn't exist"

Dynamic class generation issue:

```javascript
// 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"

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

- [Official Docs](https://tailwindcss.com/docs)
- [GitHub Issues](https://github.com/tailwindlabs/tailwindcss/issues)
- [Tailwind CSS Discord](https://tailwindcss.com/discord)
- [Stack Overflow](https://stackoverflow.com/questions/tagged/tailwind-css)

Files: 2

Size: 12.6 KB

Complexity: 31/100

Category: Web Dev

Source: https://github.com/josiahsiegel/claude-plugin-marketplace/tree/main/plugins/tailwindcss-master/skills/tailwindcss-debugging

Related in Web Dev

generating-lwc-components

Included

Lightning Web Components with PICKLES methodology and 165-point scoring. Use this skill when the user creates or edits LWC components, builds wire service patterns, or writes Jest tests for LWC. TRIGGER when: user creates/edits LWC components, touches lwc/**/*.js, .html, .css, .js-meta.xml files, or asks about wire service, SLDS, or Jest LWC tests. DO NOT TRIGGER when: Apex classes (use generating-apex), Aura components, or Visualforce.

Web Devscripts

tanstack-query

Included

Manage server state in React with TanStack Query v5. Set up queries with useQuery, mutations with useMutation, configure QueryClient caching strategies, implement optimistic updates, and handle infinite scroll with useInfiniteQuery. Use when: setting up data fetching in React projects, migrating from v4 to v5, or fixing object syntax required errors, query callbacks removed issues, cacheTime renamed to gcTime, isPending vs isLoading confusion, keepPreviousData removed problems.

Web Devscripts

document-processor-api

Included

Process documents with Nutrient DWS. Use when the user wants to generate PDFs from HTML or URLs, convert Office/images/PDFs, assemble or split packets, OCR scans, extract text/tables/key-value pairs, redact PII, watermark, sign, fill forms, optimize PDFs, or produce compliance outputs like PDF/A or PDF/UA. Triggers include convert to PDF, merge these PDFs, OCR this scan, extract tables, redact PII, sign this PDF, make this PDF/A, or linearize for web delivery.

Web Devscripts

nutrient-document-processing

Included

Web Devscripts

tanstack-query

Included

Manage server state in React with TanStack Query v5. Covers useMutationState, simplified optimistic updates, throwOnError, network mode (offline/PWA), and infiniteQueryOptions. Use when setting up data fetching, fixing v4→v5 migration errors (object syntax, gcTime, isPending, keepPreviousData), or debugging SSR/hydration issues with streaming server components.

Web Devscripts

accelint-nextjs-best-practices

Included

Next.js performance optimization and best practices. Use when writing Next.js code (App Router or Pages Router); implementing Server Components, Server Actions, or API routes; optimizing RSC serialization, data fetching, or server-side rendering; reviewing Next.js code for performance issues; fixing authentication in Server Actions; or implementing Suspense boundaries, parallel data fetching, or request deduplication.

Web Devscripts