Tailwindcss

Tailwind CSS v4 Development Guidelines

Best practices for using Tailwind CSS v4 utility classes effectively.

Note: Tailwind CSS v4 (released January 2025) uses a CSS-first configuration approach. If you need v3 compatibility, tailwind.config.js is still supported.

Core Principles

1. Utility-First: Use utility classes instead of custom CSS
2. Mobile-First: Design for mobile, then scale up with responsive modifiers
3. Component Extraction: Extract repeated patterns into components
4. Consistent Spacing: Use Tailwind's spacing scale
5. Custom Configuration: Extend the default theme for brand consistency

Basic Utilities

Layout

// Flexbox

  Content
  Sidebar

// Grid

  1
  2
  3

// Positioning

  Badge

Spacing

// Padding and Margin
           {/* padding: 1rem, margin: 0.5rem */}
        {/* padding-x: 1.5rem, padding-y: 1rem */}
        {/* margin-top: 2rem, margin-bottom: 1rem */}

// Space between children
        {/* margin-bottom on all but last child */}
  Item 1
  Item 2

Typography

Heading

  Paragraph text with comfortable line height.

Label

Colors

// Text colors
Text

// Background colors
Button

// Border colors
Box

Responsive Design

Breakpoints

// Mobile-first responsive classes

  {/* Full width on mobile, half on medium screens, third on large */}

  {/* Responsive text sizes */}

  {/* Responsive grid */}

Container

  {/* Centered container with horizontal padding */}

  {/* Responsive container padding */}

Component Patterns

Button

  Click me

// Variants

  Secondary

Card

  
  
    Card Title
    Card content goes here.
  

Form Input

  
    Email
  
  
  We'll never share your email.

State Variants

Hover, Focus, Active

  Interactive Button

  Link

Group Hover

  
  Hover the container

Disabled

  Disabled Button

Dark Mode

/* Tailwind v4: Configure in app/globals.css */
@import "tailwindcss";

@media (prefers-color-scheme: dark) {
  /* Or use class-based: .dark */
}

// Usage (same as v3)

  Title
  Description

Custom Styles

Arbitrary Values

           {/* Custom top value */}
          {/* Custom color */}
 {/* Custom grid template */}

@apply Directive

/* components/button.css */
.btn-primary {
  @apply px-4 py-2 bg-blue-600 text-white font-medium rounded-md;
  @apply hover:bg-blue-700 focus:outline-none focus:ring-2 focus:ring-blue-500;
  @apply disabled:opacity-50 disabled:cursor-not-allowed;
}

Configuration

Tailwind v4: CSS-First Configuration

/* app/globals.css */
@import "tailwindcss";

@theme {
  /* Custom colors */
  --color-brand-50: #eff6ff;
  --color-brand-100: #dbeafe;
  --color-brand-900: #1e3a8a;

  /* Custom spacing */
  --spacing-128: 32rem;

  /* Custom fonts */
  --font-family-sans: 'Inter', sans-serif;

  /* Custom breakpoints */
  --breakpoint-3xl: 1920px;
}

Tailwind v3 Config (Still Supported)

// tailwind.config.js (optional in v4)
module.exports = {
  content: [
    './app/**/*.{js,ts,jsx,tsx,mdx}',
    './components/**/*.{js,ts,jsx,tsx,mdx}',
  ],
  theme: {
    extend: {
      colors: {
        brand: {
          50: '#eff6ff',
          100: '#dbeafe',
          900: '#1e3a8a',
        }
      },
      spacing: {
        '128': '32rem',
      },
      fontFamily: {
        sans: ['Inter', 'sans-serif'],
      },
    },
  },
  plugins: [
    require('@tailwindcss/forms'),
    require('@tailwindcss/typography'),
  ],
}

Plugins

Official Plugins

npm install @tailwindcss/forms
npm install @tailwindcss/typography
npm install @tailwindcss/aspect-ratio
npm install @tailwindcss/container-queries

// @tailwindcss/forms

// @tailwindcss/typography

  Article Title
  Content...

Performance

Automatic Content Detection

Tailwind v4 automatically detects and scans all template files - no content configuration needed.

Build Performance

Tailwind v4 delivers 3.5x faster full builds (~100ms) compared to v3 using modern CSS features like @property and color-mix().

Browser Requirements: Safari 16.4+, Chrome 111+, Firefox 128+

Common Patterns

Centered Content

  Centered content

Sticky Header

  Navigation

Grid Layout

  {posts.map(post => (
    
  ))}

Truncate Text

This text will be truncated with ellipsis if too long
This text will show max 3 lines with ellipsis

Best Practices

1. Use Consistent Spacing: Stick to Tailwind's spacing scale
2. Responsive by Default: Always consider mobile-first design
3. Extract Components: Avoid repeating long class lists
4. Use Theme Colors: Define custom colors in config, not arbitrary values
5. Leverage @apply Sparingly: Prefer utility classes in JSX
6. Enable Dark Mode: Plan for dark mode from the start
7. Use Plugins: Leverage official plugins for common needs
8. Optimize Production: Ensure purge is configured correctly

Additional Resources

For detailed information, see:

• [Utility Patterns](resources/utility-patterns.md)
• [Component Library](resources/component-library.md)
• [Configuration Guide](resources/configuration.md)

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: blencorp
• Source: blencorp/claude-code-kit
• License: MIT

Install and usage instructions live in the source repository linked above.