tailwind-v4-architect

name	Tailwind v4 Architect
description	Master guide for Tailwind CSS v4. Enforces CSS-first configuration, native container queries, and Vite-native performance patterns.

Tailwind v4 Architect

⚠️ CORE DIRECTIVE: Treat CSS as the configuration source. Tailwind v4 puts CSS variables and the @theme directive at the center of the architecture.

1. CSS-Native Configuration

DO NOT use tailwind.config.js unless absolutely necessary for complex JavaScript plugins. DO use strict CSS variables for theming.

Required Setup (src/styles/global.css)

@import "tailwindcss";

@theme {
  /* Semantic Tokens (oklch preferred for wide gamut) */
  --color-primary: oklch(0.55 0.25 260); /* Blue-ish */
  --color-accent: oklch(0.85 0.15 85);   /* Gold-ish */
  
  /* Fluid Spacing */
  --spacing-4xl: 2.25rem;
  
  /* Fonts */
  --font-display: "Playfair Display", serif;
}

2. Vite-Native Integration

Tailwind 4 is a PostCSS plugin no more—it's a native Vite plugin. Verified Config (astro.config.mjs):

import tailwindcss from '@tailwindcss/vite';
export default defineConfig({
  vite: { plugins: [tailwindcss()] }
});

3. Container Queries (Standard)

Stop using media queries for components. Use container queries to make components portable.

• Parent: @container
• Child: @md:flex-row (Apply styles based on parent width)

4. Modern Anti-Patterns (To Avoid)

• ❌ @apply for simple utilities (creates bloat)
• ❌ tailwind.config.js for simple colors
• ❌ @import from npm packages (Tailwind 4 verifies these automatically)

5. Verification

• Use npx tailwindcss --help to verify CLI availability.
• Check browser devtools: CSS variables should appear on :root.
• HMR should be <50ms.