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 ~/.claude/skills/tailwind-validator/scripts/validate.py --root .

Validate with auto-fix suggestions

python3 ~/.claude/skills/tailwind-validator/scripts/validate.py --root . --suggest-fixes

Strict mode (fail on any v3 pattern)

python3 ~/.claude/skills/tailwind-validator/scripts/validate.py --root . --strict

What Gets Checked 1. Package Version // GOOD: v4+ "tailwindcss": "^4.0.0"

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

1. 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;

1. 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.

1. 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: {}, }, };

1. 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 Update package.json: bun remove tailwindcss autoprefixer bun add tailwindcss@latest @tailwindcss/postcss

Update postcss.config.js: export default { plugins: { '@tailwindcss/postcss': {}, }, };

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; }

Replace @tailwind directives:

Before:

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

After:

@import "tailwindcss";

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:

Verify components.json uses CSS variables Check that generated components use v4 patterns 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 ~/.claude/skills/tailwind-validator/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.