Tailwind CSS v4 验证器 - 检测并修复 v3 模式，确保 CSS 优先配置正确

tailwind-validator by shipshitdev/library

77 周安装量

18 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/shipshitdev/library --skill tailwind-validator

CSS 前端优化代码质量

🇨🇳中文介绍

Tailwind 4 验证器

验证项目是否正确使用 Tailwind CSS v4 并采用 CSS 优先配置。检测并标记应迁移的 Tailwind v3 模式。

目的

关键提示：Claude 和其他 AI 助手通常默认使用 Tailwind v3 模式。此技能确保：

项目使用 Tailwind v4 CSS 优先配置
检测并标记旧的 tailwind.config.js 模式
使用正确的 @theme 块而非 JS 配置
依赖项为 v4+

使用时机

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

快速开始

# 验证当前项目
python3 ~/.claude/skills/tailwind-validator/scripts/validate.py --root .

# 验证并提供自动修复建议
python3 ~/.claude/skills/tailwind-validator/scripts/validate.py --root . --suggest-fixes

# 严格模式（任何 v3 模式均视为失败）
python3 ~/.claude/skills/tailwind-validator/scripts/validate.py --root . --strict

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

2. CSS 配置（v4 CSS 优先）

良好 - Tailwind v4：

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

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

不良 - Tailwind v3：

/* 旧的 v3 指令 */
@tailwind base;
@tailwind components;
@tailwind utilities;

不良 - v4 中不应存在：

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

注意：这些文件在 v4 中已弃用。所有配置都应使用 @theme 在 CSS 中完成。

// postcss.config.js（最小化或不需要）
export default {
  plugins: {
    '@tailwindcss/postcss': {},
  },
};

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

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

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

=== Tailwind 4 验证报告 ===

包版本：tailwindcss@4.0.14 ✓

CSS 配置：
  ✓ 在 src/app/globals.css 中找到 @import "tailwindcss"
  ✓ 找到包含 12 个自定义属性的 @theme 块
  ✗ 在 src/styles/legacy.css 中找到 @tailwind 指令（第 3 行）

配置文件：
  ✗ 找到 tailwind.config.ts - 应迁移到 CSS @theme

PostCSS：
  ✓ 使用 @tailwindcss/postcss 插件

摘要：发现 2 个问题
  - 将 tailwind.config.ts 迁移到 CSS 中的 @theme
  - 从 src/styles/legacy.css 中移除 @tailwind 指令

从 Tailwind v3 迁移到 v4

更新 package.json：

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）：

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

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

替换 @tailwind 指令：

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

@import "tailwindcss";

删除旧配置文件：

rm tailwind.config.js tailwind.config.ts

应避免的常见 v3 模式

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

@import "tailwindcss";

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

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

  /* 间距（扩展默认比例） */
  --spacing-128: 32rem;

  /* 断点 */
  --breakpoint-3xl: 1920px;

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

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

  /* 边框半径 */
  --radius-4xl: 2rem;
}

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

与 shadcn/ui 配合使用

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

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

@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 流水线：

# .github/workflows/lint.yml
- name: 验证 Tailwind v4
  run: |
    python3 ~/.claude/skills/tailwind-validator/scripts/validate.py \
      --root . \
      --strict \
      --ci

"找到 tailwind.config.js 但使用 v4"

某些工具仍会生成 v3 配置。删除该文件并使用 @theme 替代。

"找到 @tailwind 指令"

替换为 @import "tailwindcss"。旧指令在 v4 中不受支持。

"postcss.config 中存在 autoprefixer"

移除 autoprefixer - 它已内置到 @tailwindcss/postcss 中。

"配置中的 content 数组"

v4 自动检测内容文件。完全移除 content 配置。

🇺🇸English

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"

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

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

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.

Weekly Installs

Repository

shipshitdev/library

GitHub Stars

First Seen

Jan 20, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykPass

Installed on

codex56

opencode53

gemini-cli52

claude-code51

cursor51

github-copilot45

React视图过渡API使用指南：实现原生浏览器动画与状态管理

5,700 周安装