mcpField
T
tailwind-validator

tailwind-validator

github.com/shipshitdevTesting & quality38183 installsUpdated 2d ago
Repository

About tailwind-validator

A validation skill for checking that projects follow Tailwind CSS v4 conventions. It detects v3 configuration patterns and provides commands for validation, suggested fixes, and strict checks.

Key features

  1. 01Check Tailwind CSS package versions
  2. 02Detect legacy JavaScript config files
  3. 03Validate CSS-first @theme configuration
  4. 04Check PostCSS plugin setup
  5. 05Suggest fixes and run strict checks

Use cases

  1. 01Validate a new Tailwind project setup
  2. 02Audit a project before upgrading to v4
  3. 03Check generated Tailwind code for v3 patterns
  4. 04Prevent v3 regressions in CI/CD

Install

Copy the command and run it in a terminal.

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

After installing, type/tailwind-validatorin Claude Code to confirm it loaded.

Bundled files

References and scripts installed along with SKILL.md.

plugin.json
references/
full-guide.md
scripts/
validate.py

Details

From the project README

Tailwind 4 Validator

Purpose

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

python3 scripts/validate.py --root .
python3 scripts/validate.py --root . --suggest-fixes
python3 scripts/validate.py --root . --strict

What Gets Checked

CheckGood (v4)Bad (v3)
Package version"tailwindcss": "^4.0.0""^3.4.0"
CSS config@import "tailwindcss"; + @theme { --color-primary: ...; }@tailwind base/components/utilities;
Config filesnone - config lives in CSStailwind.config.{js,ts,mjs,cjs} (deprecated in v4)
PostCSSplugins: { '@tailwindcss/postcss': {} } onlytailwindcss + autoprefixer as separate plugins
Imports@import "tailwindcss/preflight" / .../utilities@tailwind directives

See references/full-guide.md (§ What Gets Checked, § Validation Output) for full GOOD/BAD examples and a sample validation report.

Migration Guide (v3 to v4)

  1. Swap packages: remove tailwindcss/autoprefixer, add tailwindcss@latest + @tailwindcss/postcss
  2. Point postcss.config.js at the @tailwindcss/postcss plugin only
  3. Convert tailwind.config.js theme/extend values into an @theme { --color-*, --font-*, ... } block in CSS
  4. Replace @tailwind directives with @import "tailwindcss"
  5. Delete tailwind.config.{js,ts,mjs,cjs}

See references/full-guide.md (§ Migration Guide, § CI/CD Integration) for the exact before/after code per step and a CI workflow snippet.

Common v3 Patterns to Avoid

v3 Patternv4 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"

See references/full-guide.md (§ v4 @theme Reference, § Using with shadcn/ui) for a full @theme token example and shadcn/ui token setup.

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.

Comments

Markdown supported