Tailwind CSS v4 Best Practices

Introduction

Tailwind CSS v4 brings powerful new features and improvements. Let’s explore some best practices for using it effectively in your Hugo Paper projects.

Utility-First Approach

The core philosophy of Tailwind CSS is utility-first. Instead of writing custom CSS, you compose styles using utility classes.

Good Example

<div class="flex items-center justify-between p-4 bg-primary text-white rounded-lg">
  <h2 class="text-lg font-bold">Title</h2>
  <button class="px-4 py-2 bg-white text-primary rounded hover:bg-gray-100 transition-colors">
    Action
  </button>
</div>

Avoid Custom CSS for Simple Styles

❌ Don’t do this:

.card {
  padding: 1rem;
  border-radius: 0.5rem;
  box-shadow: 0 1px 3px rgba(0, 0, 0, 0.1);
}

✅ Do this instead:

<div class="p-4 rounded-lg shadow-sm">...</div>

Component Extraction

When styles are repeated, extract them into components or use @apply.

@layer components {
  .btn-primary {
    @apply px-4 py-2 bg-primary text-white rounded-lg font-medium 
           hover:bg-accent transition-colors duration-200;
  }
}

Then use it:

<button class="btn-primary">Click me</button>

Responsive Design

Tailwind makes responsive design simple with breakpoint prefixes:

<!-- Mobile: 1 column, Tablet: 2 columns, Desktop: 3 columns -->
<div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
  <!-- content -->
</div>

Dark Mode

Hugo Paper includes dark mode support using CSS variables:

<!-- This will automatically adjust for dark mode -->
<div class="bg-background text-foreground">
  <p class="text-muted">This text adjusts based on theme</p>
</div>

Performance Tips

1. Avoid Arbitrary Values When Possible

❌ Avoid: class="w-[347px]"
✅ Prefer: class="w-full max-w-md"

2. Use Content Configuration

Make sure your tailwind.config.js has the correct content paths:

module.exports = {
  content: [
    './layouts/**/*.html',
    './content/**/*.md',
  ],
}

3. Purge Unused Styles

Production builds automatically remove unused CSS:

hugo --minify

Animation and Transitions

Tailwind includes built-in animations:

<!-- Fade in animation -->
<div class="animate-fade-in">Fading in...</div>

<!-- Smooth color transition -->
<button class="bg-primary hover:bg-accent transition-colors duration-200">
  Hover me
</button>

Customization

Extend Tailwind with custom utilities:

// tailwind.config.js
theme: {
  extend: {
    colors: {
      'brand': '#your-color',
    },
    spacing: {
      '128': '32rem',
    },
  },
}

Common Mistakes to Avoid

Mixing utility and custom CSS - Stick to utilities
Not using component extraction - Use @apply for repeated patterns
Ignoring responsive design - Always design mobile-first
Overusing arbitrary values - Extend config instead

Resources

Happy styling!