version: "1.0.1" name: tailwind-expert description: "Expert guide for Tailwind CSS v4, CSS-first configuration, @theme customization, and modern responsive design / Panduan ahli untuk Tailwind CSS v4, konfigurasi CSS-first, kustomisasi @theme, dan desain responsif modern." author: "Roedy Rustam"

Tailwind CSS Expert (v4 Edition)

English | Bahasa Indonesia

<a name="english"></a>

English

Description

Strict guidelines and best practices for Tailwind CSS v4. Enforces the CSS-first configuration model, @theme token definitions, dynamic utilities, and performance optimization via Lightning CSS.

Trigger Conditions

• Scaffold or configure a Tailwind CSS v4 project.
• Migrate a codebase from Tailwind CSS v3 to v4.
• Implement design tokens via @theme.
• Apply 3D transforms, CSS container queries, or field-sizing.

Orchestration & Integration

Integrates tightly with the following skills:

• `senior-frontend`: Feeds modern CSS capabilities into Next.js/React component architecture.
• `ui-components-expert`: Provides the styling primitives for Radix/shadcn-style components.
• `design-system-architect`: Establishes the core tokens mapped inside @theme.

Execution Standards

1. CSS-First Architecture

Do NOT create tailwind.config.js. Define all configuration inside CSS using the @theme directive.

/* app/globals.css */
@import "tailwindcss";
 
@theme {
  /* OKLCH Colors for wide-gamut displays */
  --color-brand-50: oklch(97% 0.02 250);
  --color-brand-500: oklch(55% 0.2 250);
 
  /* Typography */
  --font-sans: "Inter Variable", system-ui, sans-serif;
 
  /* Custom breakpoints */
  --breakpoint-3xl: 112rem;
}
 
/* Register plugins */
@plugin "@tailwindcss/typography";

2. Advanced Utilities

Utilize v4-native features instead of custom CSS where possible:

• 3D Transforms: Use perspective-1000, rotate-x-12, transform-3d, backface-hidden.
• Color Mix: Use inline mixing: text-[color-mix(in_oklch,blue_70%,white)].
• Container Queries: Use @container on the parent, @sm:grid-cols-2 on children.
• Auto-sizing: Use field-sizing-content for dynamically sizing textareas.

3. Migration (v3 to v4)

When upgrading older codebases:

1. Run npx @tailwindcss/upgrade automatically.
2. Manually verify tailwind.config.js logic is perfectly translated to @theme CSS variables.
3. Replace deprecated addVariant plugin code with @variant CSS directives:

``css @variant hocus (&:hover, &:focus); @variant dark (&:where(.dark, .dark *)); ``

4. Performance Directives

• Zero Configuration: Rely on v4's automatic content detection. Do not manually specify content paths.
• Specificity: Use @layer utilities strictly when custom CSS requires Tailwind's specificity tier.
• No `@apply` Abuse: Avoid @apply in loops or highly repeated components; use HTML utility classes to leverage Lightning CSS tree-shaking.

<a name="bahasa-indonesia"></a>

Bahasa Indonesia

Deskripsi

Panduan ketat dan praktik terbaik untuk Tailwind CSS v4. Memaksa penggunaan model konfigurasi CSS-first, definisi token @theme, utilitas dinamis, dan optimasi performa melalui Lightning CSS.

Kondisi Pemicu

• Menyiapkan atau mengonfigurasi proyek Tailwind CSS v4.
• Migrasi codebase dari Tailwind CSS v3 ke v4.
• Implementasi design token via @theme.
• Menggunakan 3D transform, container query, atau field-sizing.

Integrasi Orkestrasi

Terintegrasi erat dengan skill berikut:

• `senior-frontend`: Menyuplai kapabilitas CSS modern ke dalam arsitektur komponen Next.js/React.
• `ui-components-expert`: Menyediakan primitif styling untuk komponen gaya Radix/shadcn.
• `design-system-architect`: Membangun token utama yang dipetakan di dalam @theme.

Standar Eksekusi

1. Arsitektur CSS-First

JANGAN membuat tailwind.config.js. Definisikan semua konfigurasi di dalam CSS menggunakan direktif @theme.

/* app/globals.css */
@import "tailwindcss";
 
@theme {
  /* Warna OKLCH untuk layar wide-gamut */
  --color-brand-50: oklch(97% 0.02 250);
  --color-brand-500: oklch(55% 0.2 250);
 
  /* Tipografi */
  --font-sans: "Inter Variable", system-ui, sans-serif;
}
 
/* Registrasi plugin */
@plugin "@tailwindcss/typography";

2. Utilitas Lanjutan

Gunakan fitur bawaan v4 alih-alih CSS kustom:

• 3D Transform: Gunakan perspective-1000, rotate-x-12, transform-3d, backface-hidden.
• Color Mix: Gunakan text-[color-mix(in_oklch,blue_70%,white)].
• Container Queries: Gunakan @container pada induk, @sm:grid-cols-2 pada anak.
• Auto-sizing: Gunakan field-sizing-content untuk textarea agar ukurannya otomatis menyesuaikan.

3. Migrasi (v3 ke v4)

Saat memperbarui codebase lama:

1. Jalankan npx @tailwindcss/upgrade secara otomatis.
2. Verifikasi manual logika tailwind.config.js agar diterjemahkan sempurna ke variabel CSS @theme.
3. Ganti plugin addVariant lama dengan direktif CSS @variant:

``css @variant hocus (&:hover, &:focus); @variant dark (&:where(.dark, .dark *)); ``

4. Arahan Performa

• Konfigurasi Nol: Andalkan deteksi konten otomatis v4. Jangan tentukan path konten secara manual.
• Spesifisitas: Gunakan @layer utilities secara ketat hanya jika CSS kustom memerlukan tingkat spesifisitas Tailwind.
• Dilarang Menyalahgunakan `@apply`: Hindari @apply pada loop atau komponen berulang; gunakan kelas utilitas di HTML untuk memaksimalkan tree-shaking Lightning CSS.