---
name: tailwind-4
description: >
Tailwind CSS 4 patterns and best practices.
Trigger: When styling with Tailwind - cn(), theme variables, no var() in className.
license: Apache-2.0
metadata:
author: gentleman-programming
version: "1.1"
---
## Styling Decision Tree
```
Tailwind class exists? → className="..."
Dynamic value? → style={{ width: `${x}%` }}
Conditional styles? → cn("base", condition && "variant")
Static only? → className="..." (no cn() needed)
Library can't use class?→ style prop with var() constants
```
## Critical Rules
### Never Use var() in className
```typescript
// ❌ NEVER: var() in className
// ✅ ALWAYS: Use Tailwind semantic classes
```
### Never Use Hex Colors
```typescript
// ❌ NEVER: Hex colors in className
// ✅ ALWAYS: Use Tailwind color classes
```
## The cn() Utility
```typescript
import { clsx } from "clsx";
import { twMerge } from "tailwind-merge";
export function cn(...inputs: ClassValue[]) {
return twMerge(clsx(inputs));
}
```
### When to Use cn()
```typescript
// ✅ Conditional classes
// ✅ Merging with potential conflicts
// className might override
// ✅ Multiple conditions
```
### When NOT to Use cn()
```typescript
// ❌ Static classes - unnecessary wrapper
// ✅ Just use className directly
```
## Style Constants for Charts/Libraries
When libraries don't accept className (like Recharts):
```typescript
// ✅ Constants with var() - ONLY for library props
const CHART_COLORS = {
primary: "var(--color-primary)",
secondary: "var(--color-secondary)",
text: "var(--color-text)",
gridLine: "var(--color-border)",
};
// Usage with Recharts (can't use className)
```
## Dynamic Values
```typescript
// ✅ style prop for truly dynamic values
// ✅ CSS custom properties for theming
```
## Common Patterns
### Flexbox
```typescript
```
### Grid
```typescript
```
### Spacing
```typescript
// Padding
// All sides
// Horizontal, vertical
// Top, bottom
// Margin
// Center horizontally
```
### Typography
```typescript
```
### Borders & Shadows
```typescript
```
### States
```typescript
```
### Responsive
```typescript
```
### Dark Mode
```typescript
```
## Arbitrary Values (Escape Hatch)
```typescript
// ✅ OK for one-off values not in design system
// ❌ Don't use for colors - use theme instead
// NO
```
## Keywords
tailwind, css, styling, cn, utility classes, responsive