---
description: Tailwind CSS utility-first design system patterns
alwaysApply: false
globs: **/*.{vue,html,jsx,tsx}
---

# Tailwind CSS Mastery

## Core Principles

### 1. Embrace Utility Classes
Don't fight against utilities - they're your superpower.

### 2. Extract Components When You Repeat
Create component classes only after repeating a pattern **3+ times**.

### 3. Mobile-First Responsive Design
Always start mobile, progressively enhance for larger screens.

```html
<div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
  <!-- Content scales beautifully -->
</div>
```

### 4. Use Design Tokens
Extend Tailwind's config with your design system.

```javascript
// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      colors: {
        primary: {
          DEFAULT: '#606060',
          light: '#808080',
          dark: '#404040',
        },
      },
    }
  }
}
```

## Spacing System (4px Grid)

**The 4px Base Grid Rule**: All spacing follows a 4px base grid for mathematical harmony.

```
4px   = p-1, m-1, gap-1
8px   = p-2, m-2, gap-2
16px  = p-4, m-4, gap-4
24px  = p-6, m-6, gap-6
32px  = p-8, m-8, gap-8
```

## Responsive Breakpoints

```javascript
sm:  640px   // Mobile landscape
md:  768px   // Tablets
lg:  1024px  // Desktop
xl:  1280px  // Large desktop
```

### Mobile-First Pattern

```html
<!-- Base = Mobile, then enhance -->
<div class="text-base md:text-lg lg:text-xl">
  <!-- 16px → 18px → 20px -->
</div>

<div class="p-4 md:p-6 lg:p-8">
  <!-- 16px → 24px → 32px padding -->
</div>
```

## Component Patterns

### Buttons

```html
<!-- Primary -->
<button class="px-6 py-3 bg-primary text-white rounded-lg font-semibold
               hover:bg-primary-dark transition-colors duration-200
               focus:outline-none focus:ring-2 focus:ring-primary-focus">
  Primary Action
</button>

<!-- Secondary -->
<button class="px-6 py-3 border-2 border-primary text-primary rounded-lg
               hover:bg-primary hover:text-white transition-all">
  Secondary Action
</button>
```

### Cards

```html
<div class="bg-white rounded-lg shadow-md p-6 mb-6
            hover:shadow-lg transition-shadow duration-300">
  <h3 class="text-xl font-semibold mb-2">Card Title</h3>
  <p class="text-gray-600">Content</p>
</div>
```

### Form Elements

```html
<input 
  type="text"
  class="w-full px-4 py-2.5 border border-gray-300 rounded-lg
         focus:border-primary focus:ring-2 focus:ring-primary-focus
         transition-colors"
  placeholder="Enter text"
/>
```

## Color Contrast for Accessibility

Always ensure **4.5:1 contrast ratio** minimum (WCAG AA).

```html
<!-- Good - High contrast -->
<p class="text-gray-900 bg-white">Dark text on light</p>

<!-- Bad - Low contrast (avoid) -->
<p class="text-gray-400 bg-gray-300">Hard to read!</p>
```

## Custom Component Classes

Only extract after 3+ repetitions:

```css
@layer components {
  .btn-primary {
    @apply px-6 py-3 bg-primary text-white rounded-lg font-semibold;
    @apply hover:bg-primary-dark transition-colors duration-200;
    @apply focus:outline-none focus:ring-2 focus:ring-primary-focus;
  }
}
```

## Summary Checklist

- ✅ Start mobile-first, enhance for larger screens
- ✅ Use design tokens (extend Tailwind config)
- ✅ Follow 4px spacing grid
- ✅ Extract components after 3+ repetitions
- ✅ Keep utility classes in HTML
- ✅ Ensure color contrast for accessibility
- ✅ Use transitions for smooth interactions
- ✅ Configure PurgeCSS for production