Tailwind CSS Cursor Rules: Utility-First Styling Guide

---
description: Enforces best practices for Tailwind CSS development, focusing on utility-first patterns, responsive design, and class ordering. Provides comprehensive guidelines for writing clean, maintainable styles with proper context.
globs: **/*.{html,jsx,tsx,vue,css}
---
# Tailwind CSS Best Practices

You are an expert in Tailwind CSS and modern styling approaches.
You understand modern Tailwind development practices, design system principles, and the importance of providing complete context in code generation.

### Context-Aware Code Generation
- Always provide full markup context including component structure and layout intent
- Include relevant configuration files (tailwind.config.js, postcss.config.js) when generating styles
- Specify breakpoint requirements and responsive behavior upfront
- Provide context about design system tokens and theme values in use
- Include dark mode and accessibility requirements in styling context

### Utility-First Patterns
- Prefer utility classes over custom CSS for 95% of styling needs
- Compose utilities directly in markup to keep CSS minimal
- Group related utilities logically within element classes
- Use shorthand classes (p-4 over padding: 1rem) whenever possible

### Class Order
1. Layout (position, display, z-index, overflow)
2. Spacing (margin, padding)
3. Sizing (width, height, min/max)
4. Visual (colors, borders, shadows, bg)
5. Typography (text, font, leading)
6. State (hover, focus, active, disabled)

### Custom Configuration
- Define theme values (colors, fonts, spacing) in tailwind.config.js using extend
- Use CSS custom properties for runtime theme switching
- Configure content paths properly to avoid purging needed classes
- Use arbitrary values with bracket syntax for one-off overrides

### Responsive Design
- Use mobile-first approach: base styles first, responsive overrides with sm:/md:/lg:/xl:
- Apply responsive utilities to individual elements rather than wrappers
- Use container and max-w-* for layout width constraints
- Test each breakpoint threshold for visual consistency

### Dark Mode and Theming
- Use dark: variant for dark mode overrides on individual classes
- Define dark palette colors in tailwind.config.js theme extension
- Use class-based dark mode strategy for runtime control
- Set up CSS custom properties for brand color theming

### Component Extraction
- Extract repeated utility patterns into framework components (React, Vue)
- Use @apply only for complex multi-element patterns that repeat frequently
- Prefer composition of small components over @apply for reusability
- Name extracted components by visual purpose (Card, Badge, Button, Banner)

### Performance
- Rely on JIT engine to tree-shake unused classes automatically
- Avoid dynamic class construction (template literals concatenating class names)
- Keep class patterns consistent for maximum JIT content detection
- Minimize @apply usage to avoid duplicating styles in production output

### AI Instructions
- Use shorthand classes over long equivalents (p-4 vs padding: 1rem)
- Add custom colors and values in tailwind.config.js before using arbitrary syntax
- Use consistent class ordering: layout, spacing, sizing, visual, typography, state
- Apply mobile-first responsive prefixes for all breakpoints

// Before — raw arbitrary values scattered
<div style="padding: 16px; margin-bottom: 12px; color: blue;">
  <p>Welcome</p>
</div>

// After — Tailwind utility-first with consistent class ordering
<div className="p-4 mb-3 text-blue-600">
  <p>Welcome</p>
</div>

// Responsive card grid using mobile-first breakpoints
// Base = mobile, md: = tablet+, lg: = desktop+
<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4 dark:bg-gray-900">
  <div className="p-6 bg-white dark:bg-gray-800 rounded-lg shadow hover:shadow-lg transition-shadow">
    <h3 className="text-lg font-semibold text-gray-900 dark:text-gray-100">Card Title</h3>
    <p className="mt-2 text-sm text-gray-600 dark:text-gray-400">Card content</p>
  </div>
</div>