# Tailwind CSS v4 Quick Reference Guide

## Common v3 → v4 Utility Migrations

| v3 Utility | v4 Utility | Notes |
|------------|------------|-------|
| `outline-none` | `outline-hidden` | Accessibility improvement |
| `ring` | `ring-3` | Must specify ring width |
| `shadow-sm` | `shadow-xs` | Renamed for consistency |
| `shadow` | `shadow-sm` | Renamed for consistency |
| `flex-shrink-0` | `shrink-0` | Shortened syntax |
| `bg-blue-500 bg-opacity-50` | `bg-blue-500/50` | New opacity syntax |
| `text-gray-700 text-opacity-75` | `text-gray-700/75` | New opacity syntax |
| `!outline-none` | `!outline-hidden` | Updated important syntax |

## Theme Variables (Available in CSS)

```css
/* Colors */
var(--color-primary)    /* #4f46e5 - Indigo-600 */
var(--color-secondary)  /* #e11d48 - Rose-600 */
var(--color-accent)     /* #8b5cf6 - Violet-500 */

/* Fonts */
var(--font-family-sans) /* Poppins, sans-serif */
```

## Usage in Templates

### Before (v3)
```html
<button class="outline-none ring hover:ring-2 shadow-sm bg-blue-500 bg-opacity-75">
  Click me
</button>
```

### After (v4)
```html
<button class="outline-hidden ring-3 hover:ring-2 shadow-xs bg-blue-500/75">
  Click me
</button>
```

## Development Commands

### Start Development Server
```bash
lsof -ti :8000 | xargs kill -9; find . -type d -name "__pycache__" -exec rm -r {} +; uv run manage.py tailwind runserver
```

### Force CSS Rebuild
```bash
uv run manage.py tailwind build
```

## New v4 Features

- **CSS-first configuration** via `@theme` blocks
- **Improved opacity syntax** with `/` operator  
- **Better color-mix() support**
- **Enhanced dark mode utilities**
- **Faster compilation**

## Troubleshooting

### Unknown utility class error
1. Check if utility was renamed (see table above)
2. Verify custom theme variables are defined
3. Run clean build process

### Colors not working
1. Ensure `@theme` block exists in `static/css/src/input.css`
2. Check CSS variable names match usage
3. Verify CSS compilation completed

## Resources

- [Full Migration Documentation](./TAILWIND_V4_MIGRATION.md)
- [Tailwind CSS v4 Official Docs](https://tailwindcss.com/docs)
- [Django-Tailwind Package](https://django-tailwind.readthedocs.io/)