tailwind-validator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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.

验证项目是否正确使用了基于CSS优先配置的Tailwind CSS v4，检测并标记需要迁移的Tailwind v3模式。

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+

重要提示：Claude及其他AI助手通常默认使用Tailwind v3模式。此工具可确保：

项目采用Tailwind v4的CSS优先配置
检测并标记旧的
```
tailwind.config.js
```
模式
使用正确的
```
@theme
```
块替代JS配置
依赖版本为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

任何Tailwind工作开始前：先运行验证
新项目搭建：确保v4安装正确
AI生成Tailwind代码后：检查是否混入v3模式
现有项目审计：检查是否需要迁移
CI/CD流水线：防止v3模式回归

Quick Start

快速开始

bash

undefined

bash

undefined

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

undefined

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

undefined

What Gets Checked

检查内容

1. Package Version

1. 包版本

json

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

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

json

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

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

2. CSS Configuration (v4 CSS-first)

2. CSS配置（v4 CSS优先）

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;

推荐写法 - 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;
}

不推荐写法 - Tailwind v3:

css

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

3. Config Files

3. 配置文件

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

不推荐写法 - v4中不应存在：

```
tailwind.config.js
```
```
tailwind.config.ts
```
```
tailwind.config.mjs
```
```
tailwind.config.cjs
```

注意：这些文件在v4中已被弃用，所有配置应通过CSS中的

@theme

块完成。

4. PostCSS Configuration

4. PostCSS配置

GOOD - v4:

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

BAD - v3:

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

推荐写法 - v4:

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

不推荐写法 - v3:

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

5. Import Patterns

5. 导入模式

GOOD:

css

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

BAD:

css

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

推荐写法:

css

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

不推荐写法:

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

=== 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

从Tailwind v3迁移到v4

Update package.json:

bash

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):

css

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

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

Replace @tailwind directives:

Before:

css

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

After:

css

@import "tailwindcss";

Delete old config files:

bash

rm tailwind.config.js tailwind.config.ts

更新package.json:

bash

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

更新postcss.config.js:

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

将tailwind.config.js转换为CSS @theme:

迁移前（v3）:

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

迁移后（v4）:

css

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

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

替换@tailwind指令:

替换前:

css

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

替换后:

css

@import "tailwindcss";

删除旧配置文件:

bash

rm tailwind.config.js tailwind.config.ts

Common v3 Patterns to Avoid

需要避免的常见v3模式

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

v3模式	v4替代方案
`@tailwind base`	`@import "tailwindcss"`
`@tailwind utilities`	`@import "tailwindcss/utilities"`
`tailwind.config.js`	CSS中的 `@theme` 块
`theme.extend.colors`	`--color-*` CSS变量
`theme.extend.spacing`	`--spacing-*` CSS变量
`theme.extend.fontFamily`	`--font-*` CSS变量
`content: ['./src/*/.tsx']`	无需配置（自动检测）
`plugins: [require('@tailwindcss/forms')]`	`@plugin "@tailwindcss/forms"`

v4 @theme Reference

v4 @theme参考示例

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

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配合使用

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:

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

shadcn/ui v2+支持Tailwind v4。运行shadcn CLI后：

验证
```
components.json
```
是否使用CSS变量
检查生成的组件是否采用v4模式
确保
```
@theme
```
包含shadcn颜色标记：

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

CI/CD集成

Add to your CI pipeline:

yaml

undefined

添加到你的CI流水线：

yaml

undefined

.github/workflows/lint.yml

name: Validate Tailwind v4 run: | python3 ~/.claude/skills/tailwind-validator/scripts/validate.py
--root .
--strict
--ci

undefined

name: Validate Tailwind v4 run: | python3 ~/.claude/skills/tailwind-validator/scripts/validate.py
--root .
--strict
--ci

undefined

Troubleshooting

故障排除

"Found tailwind.config.js but using v4"

"检测到tailwind.config.js但使用的是v4"

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

@theme

instead.

部分工具仍会生成v3配置文件。删除该文件并使用

@theme

替代。

"@tailwind directives found"

"检测到@tailwind指令"

Replace with

@import "tailwindcss"

. The old directives are not supported in v4.

替换为

@import "tailwindcss"

。旧指令在v4中不再受支持。

"autoprefixer in postcss.config"

"postcss.config中存在autoprefixer"

Remove autoprefixer - it's built into

@tailwindcss/postcss

移除autoprefixer - 它已内置到

@tailwindcss/postcss

中。

"content array in config"

"配置中存在content数组"

v4 auto-detects content files. Remove the

content

config entirely.

v4会自动检测内容文件。完全移除

content

配置即可。