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 - 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).
• Tailwind Variants: Use tailwind-variants (tv) for component styling instead of CVA.
• 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

Component Styling with Tailwind Variants

import { tv } from 'tailwind-variants'

const button = tv({
  base: [
    'inline-flex items-center justify-center rounded-md',
    'text-sm font-medium transition-colors',
    'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring',
  ],
  variants: {
    variant: {
      default: 'bg-primary text-primary-foreground hover:bg-primary/90',
      outline: 'border border-input hover:bg-accent hover:text-accent-foreground',
    },
    size: {
      default: 'h-10 py-2 px-4',
      sm: 'h-9 px-3 rounded-md',
      icon: 'size-10',
    },
  },
  defaultVariants: {
    variant: 'default',
    size: 'default',
  },
})

Long Class Strings

Break class strings longer than 100 characters into arrays:

// Good: Break into logical arrays
const card = tv({
  base: [
    'relative flex flex-col rounded-xl border border-border',
    'bg-card text-card-foreground shadow-xs transition-colors duration-150',
  ],
})

Responsive Design

// 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

<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)
• Using tailwind-variants for component styling
• Mobile-first responsive approach
• Run lint checks (pnpm run lint)

For detailed rules, anti-patterns, and configuration examples, see references/patterns.md.