tailwind-validator

Tailwind 4 Validator

Validates that a project uses Tailwind CSS v4 with proper CSS-first configuration. Detects and flags Tailwind v3 patterns that should be migrated.

Purpose

CRITICAL: Claude and other AI assistants often default to Tailwind v3 patterns. This skill ensures:

• Projects use Tailwind v4 CSS-first configuration
• Old tailwind.config.js patterns are detected and flagged
• Proper @theme blocks are used instead of JS config
• Dependencies are v4+

When to Use

• Before any Tailwind work: Run validation first
• New project setup: Ensure v4 is installed correctly
• After AI generates Tailwind code: Verify no v3 patterns snuck in
• Auditing existing projects: Check for migration needs
• CI/CD pipelines: Prevent v3 regressions

Quick Start

# Validate current project
python3 scripts/validate.py --root .

# Validate with auto-fix suggestions
python3 scripts/validate.py --root . --suggest-fixes

# Strict mode (fail on any v3 pattern)
python3 scripts/validate.py --root . --strict

What Gets Checked

1. Package Version

// GOOD: v4+
"tailwindcss": "^4.0.0"

// BAD: v3
"tailwindcss": "^3.4.0"

2. CSS Configuration (v4 CSS-first)

GOOD - Tailwind v4:

/* app.css or globals.css */
@import "tailwindcss";

@theme {
  --color-primary: #3b82f6;
  --color-secondary: #64748b;
  --font-sans: "Inter", sans-serif;
  --breakpoint-3xl: 1920px;
}

BAD - Tailwind v3:

/* Old v3 directives */
@tailwind base;
@tailwind components;
@tailwind utilities;

3. Config Files

BAD - Should not exist in v4:

• tailwind.config.js
• tailwind.config.ts
• tailwind.config.mjs
• tailwind.config.cjs

Note: These files are deprecated in v4. All configuration should be in CSS using @theme.

4. PostCSS Configuration

GOOD - v4:

// postcss.config.js (minimal or not needed)
export default {
  plugins: {
    '@tailwindcss/postcss': {},
  },
};

BAD - v3:

// postcss.config.js
module.exports = {
  plugins: {
    tailwindcss: {},
    autoprefixer: {},
  },
};

5. Import Patterns

GOOD:

@import "tailwindcss";
@import "tailwindcss/preflight";
@import "tailwindcss/utilities";

BAD:

@tailwind base;
@tailwind components;
@tailwind utilities;

Validation Output

=== Tailwind 4 Validation Report ===

Package Version: tailwindcss@4.0.14 ✓

CSS Configuration:
  ✓ Found @import "tailwindcss" in src/app/globals.css
  ✓ Found @theme block with 12 custom properties
  ✗ Found @tailwind directive in src/styles/legacy.css (line 3)

Config Files:
  ✗ Found tailwind.config.ts - should migrate to CSS @theme

PostCSS:
  ✓ Using @tailwindcss/postcss plugin

Summary: 2 issues found
  - Migrate tailwind.config.ts to @theme in CSS
  - Remove @tailwind directives from src/styles/legacy.css

Migration Guide

From Tailwind v3 to v4

1. Update package.json:

bun remove tailwindcss autoprefixer
bun add tailwindcss@latest @tailwindcss/postcss

1. Update postcss.config.js:

export default {
  plugins: {
    '@tailwindcss/postcss': {},
  },
};

1. Convert tailwind.config.js to CSS @theme:

Before (v3):

// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      colors: {
        primary: '#3b82f6',
        secondary: '#64748b',
      },
      fontFamily: {
        sans: ['Inter', 'sans-serif'],
      },
    },
  },
};

After (v4):

/* globals.css */
@import "tailwindcss";

@theme {
  --color-primary: #3b82f6;
  --color-secondary: #64748b;
  --font-sans: "Inter", sans-serif;
}

1. Replace @tailwind directives:

Before:

@tailwind base;
@tailwind components;
@tailwind utilities;

After:

@import "tailwindcss";

1. Delete old config files:

rm tailwind.config.js tailwind.config.ts

Common v3 Patterns to Avoid

v3 Pattern	v4 Replacement
@tailwind base	@import "tailwindcss"
@tailwind utilities	@import "tailwindcss/utilities"
tailwind.config.js	@theme block in CSS
theme.extend.colors	--color-* CSS variables
theme.extend.spacing	--spacing-* CSS variables
theme.extend.fontFamily	--font-* CSS variables
content: ['./src/**/*.tsx']	Not needed (auto-detected)
plugins: [require('@tailwindcss/forms')]	@plugin "@tailwindcss/forms"

v4 @theme Reference

@import "tailwindcss";

@theme {
  /* Colors */
  --color-primary: #3b82f6;
  --color-primary-50: #eff6ff;
  --color-primary-900: #1e3a8a;

  /* Typography */
  --font-sans: "Inter", system-ui, sans-serif;
  --font-mono: "JetBrains Mono", monospace;

  /* Spacing (extends default scale) */
  --spacing-128: 32rem;

  /* Breakpoints */
  --breakpoint-3xl: 1920px;

  /* Animations */
  --animate-fade-in: fade-in 0.3s ease-out;

  /* Shadows */
  --shadow-glow: 0 0 20px rgba(59, 130, 246, 0.5);

  /* Border radius */
  --radius-4xl: 2rem;
}

@keyframes fade-in {
  from { opacity: 0; }
  to { opacity: 1; }
}

Using with shadcn/ui

shadcn/ui v2+ supports Tailwind v4. After running the shadcn CLI:

1. Verify components.json uses CSS variables
2. Check that generated components use v4 patterns
3. Ensure @theme includes shadcn color tokens:

@theme {
  --color-background: hsl(0 0% 100%);
  --color-foreground: hsl(222.2 84% 4.9%);
  --color-card: hsl(0 0% 100%);
  --color-card-foreground: hsl(222.2 84% 4.9%);
  --color-popover: hsl(0 0% 100%);
  --color-popover-foreground: hsl(222.2 84% 4.9%);
  --color-primary: hsl(222.2 47.4% 11.2%);
  --color-primary-foreground: hsl(210 40% 98%);
  --color-secondary: hsl(210 40% 96.1%);
  --color-secondary-foreground: hsl(222.2 47.4% 11.2%);
  --color-muted: hsl(210 40% 96.1%);
  --color-muted-foreground: hsl(215.4 16.3% 46.9%);
  --color-accent: hsl(210 40% 96.1%);
  --color-accent-foreground: hsl(222.2 47.4% 11.2%);
  --color-destructive: hsl(0 84.2% 60.2%);
  --color-destructive-foreground: hsl(210 40% 98%);
  --color-border: hsl(214.3 31.8% 91.4%);
  --color-input: hsl(214.3 31.8% 91.4%);
  --color-ring: hsl(222.2 84% 4.9%);
  --radius-sm: 0.25rem;
  --radius-md: 0.375rem;
  --radius-lg: 0.5rem;
}

CI/CD Integration

Add to your CI pipeline:

# .github/workflows/lint.yml
- name: Validate Tailwind v4
  run: |
    python3 scripts/validate.py \
      --root . \
      --strict \
      --ci

Troubleshooting

"Found tailwind.config.js but using v4"

Some tools still generate v3 configs. Delete the file and use @theme instead.

"@tailwind directives found"

Replace with @import "tailwindcss". The old directives are not supported in v4.

"autoprefixer in postcss.config"

Remove autoprefixer - it's built into @tailwindcss/postcss.

"content array in config"

v4 auto-detects content files. Remove the content config entirely.