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 ```bash # 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 ```json // GOOD: v4+ "tailwindcss": "^4.0.0" // BAD: v3 "tailwindcss": "^3.4.0" ``` ### 2. CSS Configuration (v4 CSS-first) **GOOD - Tailwind v4:** ```css /* 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:** ```css /* 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:** ```js // postcss.config.js (minimal or not needed) export default { plugins: { '@tailwindcss/postcss': {}, }, }; ``` **BAD - v3:** ```js // postcss.config.js module.exports = { plugins: { tailwindcss: {}, autoprefixer: {}, }, }; ``` ### 5. Import Patterns **GOOD:** ```css @import "tailwindcss"; @import "tailwindcss/preflight"; @import "tailwindcss/utilities"; ``` **BAD:** ```css @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:** ```bash bun remove tailwindcss autoprefixer bun add tailwindcss@latest @tailwindcss/postcss ``` 1. **Update postcss.config.js:** ```js export default { plugins: { '@tailwindcss/postcss': {}, }, }; ``` 1. **Convert tailwind.config.js to CSS @theme:** **Before (v3):** ```js // tailwind.config.js module.exports = { theme: { extend: { colors: { primary: '#3b82f6', secondary: '#64748b', }, fontFamily: { sans: ['Inter', 'sans-serif'], }, }, }, }; ``` **After (v4):** ```css /* globals.css */ @import "tailwindcss"; @theme { --color-primary: #3b82f6; --color-secondary: #64748b; --font-sans: "Inter", sans-serif; } ``` 1. **Replace @tailwind directives:** **Before:** ```css @tailwind base; @tailwind components; @tailwind utilities; ``` **After:** ```css @import "tailwindcss"; ``` 1. **Delete old config files:** ```bash 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 ```css @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: ```css @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: ```yaml # .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.