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