Tailwindcss

---
name: tailwindcss
description: Guide for Tailwind CSS v4 patterns and best practices. Use when styling components with Tailwind CSS, creating responsive layouts, or working with Tailwind 4 features. Don't use for plain-CSS authoring, CSS-in-JS libraries (styled-components, emotion), or non-Tailwind utility frameworks.
allowed-tools: Read, Grep, Glob
metadata:
  author: Pedro Nauck
  github: https://github.com/pedronauck
  repository: https://github.com/pedronauck/skills
---
# Tailwind CSS Developer Guide

This skill provides guidelines, patterns, and best practices for working with Tailwind CSS v4 in this project.

## Quick Reference

For detailed patterns, examples, and checklists, see:
- [references/patterns.md](references/patterns.md) - Complete usage patterns, design tokens, and anti-patterns

## Core Principles

- **Utility-First**: Embrace utility-first approach and avoid custom CSS.
- **Design Tokens**: Always use design system tokens (`bg-background`, `text-foreground`) instead of explicit colors (`bg-white`, `text-black`).
- **Mobile-First**: Build responsive layouts with mobile-first approach.

## Critical: Design Token Usage

To ensure theme switching works correctly:

**Always use:**
- Backgrounds: `bg-background`, `bg-card`, `bg-muted`, `bg-popover`
- Text: `text-foreground`, `text-muted-foreground`, `text-card-foreground`
- Borders: `border-border`, `border-input`, `border-ring`
- Actions: `bg-primary text-primary-foreground`, `bg-secondary text-secondary-foreground`
- States: `bg-destructive text-destructive-foreground`, `bg-accent text-accent-foreground`

**Never use:** `bg-white`, `text-black`, `border-gray-200`, `bg-blue-500`

## Common Tasks

### Long Class Strings

Break class strings longer than 100 characters into arrays:

```typescript
const cardBaseClasses = [
  'relative flex flex-col rounded-xl border border-border',
  'bg-card text-card-foreground shadow-xs transition-colors duration-150',
]

// Usage: className={cardBaseClasses.join(' ')} or spread into cn()/clsx
```

### Responsive Design

```tsx
// Mobile-first responsive design
<div className="grid grid-cols-1 gap-4 sm:grid-cols-2 md:grid-cols-3 lg:grid-cols-4">

// Container queries (built-in in v4)
<div className="@container">
  <div className="@lg:flex @lg:items-center">
```

### Modern v4 Utilities

```tsx
<div className="size-10">          {/* Instead of w-10 h-10 */}
<div className="h-dvh">            {/* Dynamic viewport height */}
<div className="grid-cols-15">     {/* Dynamic grid columns */}
<h1 className="text-shadow-md">    {/* Text shadows */}
<div className="bg-(--custom-color)">  {/* CSS variables */}
```

## Anti-Patterns to Avoid

- Don't use `@apply` except for base styles
- Avoid inline styles when Tailwind has utilities
- Don't create utility classes that duplicate Tailwind
- Never use `!important` unless absolutely necessary
- Don't construct classes dynamically (`bg-${color}-500`)

## Validation Checklist

Before finishing a task involving Tailwind CSS:

- [ ] Using design tokens instead of explicit colors
- [ ] Long class strings broken into arrays (>100 chars)
- [ ] Mobile-first responsive approach
- [ ] Run lint checks (`pnpm run lint`)

For detailed rules, anti-patterns, and configuration examples, see [references/patterns.md](references/patterns.md).