Tailwind CSS Best Practices

Stop your AI agent from generating Tailwind CSS v3 code. 12 rules for Tailwind v4 syntax, CSS-first config with @theme, modern utility patterns, and the anti-patterns every agent produces.

AI coding assistants (Cursor, Claude Code, Copilot, Codex) are trained on Tailwind v3 data. They generate tailwind.config.js, @tailwind directives, bg-opacity-50, and other patterns that don't exist in Tailwind CSS v4. This plugin fixes that.

Install

Cursor / Claude Code / Windsurf

npx skills add ofershap/tailwind-best-practices

Or copy skills/ into your .cursor/skills/ or .claude/skills/ directory.

What's Included

Type	Name	Description
Skill	tailwind-best-practices	12 rules covering @import, @theme, opacity, gradients, container queries, @utility, and more
Rule	best-practices	Always-on behavioral rule that enforces v4 patterns on every file
Command	/audit	Scan your codebase for Tailwind v3 anti-patterns

What Agents Get Wrong

AI agents consistently produce these outdated Tailwind patterns:

What the agent writes	What v4 actually uses
tailwind.config.js with JS objects	CSS-first @theme { } in your stylesheet
@tailwind base; @tailwind components;	@import "tailwindcss";
bg-opacity-50, text-opacity-25	bg-red-500/50, text-white/80
bg-gradient-to-r	bg-linear-to-r, bg-linear-45
!flex, !bg-red-500	flex!, bg-red-500!
bg-[--brand-color]	bg-(--brand-color)
grid-cols-[max-content,auto]	grid-cols-[max-content_auto]

Related Plugins

• shadcn-best-practices - shadcn/ui component patterns, forms, theming
• typescript-best-practices - TypeScript 5.x strict patterns
• sveltekit-best-practices - Svelte 5 runes and SvelteKit patterns

---

If this helped your workflow, a star helps others find it.

Author

License

MIT