tailwind-css

Tailwind CSS v4 Engineering Standards

This skill codifies Tailwind CSS v4's CSS-first architecture — the paradigm shift from JavaScript configuration to native CSS-based theming and customization.

1. Core Paradigm: CSS-First Configuration

Entry Point

Replace all legacy directives with a single import:

/* main.css */
@import 'tailwindcss';

• NEVER use @tailwind base; @tailwind components; @tailwind utilities; — this is v3 syntax
• No tailwind.config.js needed for most projects — CSS is the single source of truth
• Use @config "./tailwind.config.js" only for legacy migration or PostCSS plugin compatibility

The @theme Directive

All design tokens are defined directly in CSS:

@import 'tailwindcss';

@theme {
  /* Colors */
  --color-primary-50: #eff6ff;
  --color-primary-500: #3b82f6;
  --color-primary-900: #1e3a5a;

  /* Typography */
  --font-display: 'Inter', sans-serif;
  --font-mono: 'JetBrains Mono', monospace;

  /* Spacing */
  --spacing-container: 1200px;

  /* Border Radius */
  --radius-card: 0.75rem;
}

• Tailwind automatically generates utility classes from @theme variables
• --color-primary-500 → bg-primary-500, text-primary-500, border-primary-500
• --font-display → font-display
• Tokens are native CSS variables — inspectable in browser DevTools

2. Dark Mode

Configuration (v4 Pattern)

/* Class-based dark mode (most common) */
@custom-variant dark (&:where(.dark, .dark *));

Usage in HTML

<div class="bg-white dark:bg-gray-900 text-gray-900 dark:text-gray-100">
  <h1 class="text-primary-500 dark:text-primary-300">Title</h1>
</div>

System Preference (Default)

By default, Tailwind v4 respects prefers-color-scheme. If you want manual class toggle control, use @custom-variant dark as shown above.

Toggle Implementation

// Toggle dark mode via JavaScript
document.documentElement.classList.toggle('dark')

// Or persist to localStorage
const isDark = localStorage.getItem('theme') === 'dark'
document.documentElement.classList.toggle('dark', isDark)