tailwind-best-practices_skill

Overview

This skill helps you apply Tailwind CSS v4 best practices while writing HTML, templates, or configuring themes. It enforces v4 syntax, recommends theme-driven values, and suggests component extraction and accessibility improvements. Use it to get clear, production-ready Tailwind patterns and class ordering guidance.

How this skill works

The skill inspects your markup, CSS, and Tailwind directives for v4-specific patterns and anti-patterns. It suggests replacements (e.g., @theme vs tailwind.config.js, @import "tailwindcss" instead of old directives), orders utility classes for readability, and flags accessibility and duplication issues. When needed, it can generate component templates or convert plain CSS to Tailwind utilities.

When to use it

• When writing HTML or templates that use Tailwind classes
• When configuring Tailwind themes or converting a project to v4
• When you need accessible focus states, semantic theme variables, or consistent class ordering
• When extracting repeated utility combinations into components
• When converting raw CSS into Tailwind utility classes

Best practices

• Always use Tailwind v4 syntax: @import "tailwindcss" and @theme for customization
• Prefer theme variables (e.g., bg-primary) over hardcoded hex or utility colors
• Follow a consistent class order: layout → spacing → sizing → typography → colors → effects → interactive
• Extract repeated utility combinations into @layer components after they appear 3+ times
• Use mobile-first responsive classes and add breakpoints for larger screens
• Include accessibility utilities: focus-visible, sr-only, and check color contrast

Example use cases

• Create a primary button with hover and accessible focus ring, then extract it to a .btn-primary component
• Convert CSS rules to Tailwind utilities for a card layout and suggest component extraction
• Validate templates for v3-v4 anti-patterns and provide v4 replacements (@theme, @variant dark)
• Suggest optimized responsive classes for a grid that collapses on mobile and expands at md/lg breakpoints
• Recommend replacing inline styles or arbitrary px with scale-based spacing utilities