git:20260729.f16bff5 to git:20260816.d23736e

85 added, 133 removed. Audit A to A.

---

name: tailwind-expert

- description: "Deep guide for Tailwind CSS v4, CSS-first configuration, theme customization, and responsive design / Panduan mendalam untuk Tailwind CSS v4, CSS-first configuration, theme kustomisasi, dan responsive design."

- author: "Roedy Rustam"

+ 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: "vibes-plug-swarm"

---

# Tailwind CSS Expert (v4 Edition)

[English](#english) | [Bahasa Indonesia](#bahasa-indonesia)

---

## English

### Description

- Deep expert guide for **Tailwind CSS v4** — covering the new CSS-first configuration model, `@theme` directive for design tokens, `@plugin` for plugins, 3D transforms, gradient improvements, and migration from v3.

+ 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

- - Setting up or configuring a new Tailwind CSS v4 project.

- - Defining design tokens via `@theme` directive in CSS.

- - Migrating from Tailwind CSS v3 to v4.

- - Using new v4 utilities: 3D transforms, `field-sizing`, color mix functions.

- - Registering custom plugins with `@plugin` directive.

+ - 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`.

- ### Tailwind v4 — The CSS-First Paradigm Shift

+ ## 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`.

- Tailwind v4 eliminates `tailwind.config.js` entirely. All configuration happens in CSS:

+ ### Execution Standards

+ #### 1. CSS-First Architecture

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

```css

/* app/globals.css */

@import "tailwindcss";

- /* Design tokens — replaces tailwind.config.js theme */

@theme {

- /* Colors using OKLCH for wide-gamut displays */

+ /* OKLCH Colors for wide-gamut displays */

--color-brand-50: oklch(97% 0.02 250);

--color-brand-500: oklch(55% 0.2 250);

- --color-brand-900: oklch(20% 0.1 250);

/* Typography */

- --font-sans: "Inter Variable", "Inter", ui-sans-serif, system-ui, sans-serif;

- --font-mono: "JetBrains Mono", "Fira Code", ui-monospace;

- /* Spacing & Sizing */

- --spacing-18: 4.5rem;

- --spacing-112: 28rem;

- /* Custom animations */

- --animate-slide-in: slide-in 0.3s ease-out;

- --animate-fade-up: fade-up 0.4s ease-out;

+ --font-sans: "Inter Variable", system-ui, sans-serif;

- /* Breakpoints */

+ /* Custom breakpoints */

--breakpoint-3xl: 112rem;

}

- /* Register plugins via @plugin directive */

+ /* Register plugins */

@plugin "@tailwindcss/typography";

- @plugin "@tailwindcss/forms";

- @plugin "./plugins/animations.js";

- /* Custom keyframes */

- @keyframes slide-in {

- from { transform: translateX(-100%); opacity: 0; }

- to { transform: translateX(0); opacity: 1; }

- }

- @keyframes fade-up {

- from { transform: translateY(16px); opacity: 0; }

- to { transform: translateY(0); opacity: 1; }

- }

```

- ### New Utilities in Tailwind v4

- #### 3D Transforms

- ```html

-

- <div class="perspective-1000">

- <div class="rotate-x-12 rotate-y-6 transform-3d hover:rotate-y-0 transition-transform duration-500">

- Card content

- </div>

-

-

-

-

- ```

- #### Color Mix & Relative Colors

- ```html

-

- <div class="bg-brand-500/50">

- <div class="text-[color-mix(in_oklch,blue_70%,white)]">

- <div class="border-brand-500 hover:border-brand-700">

- ```

- #### Container Queries

- ```html

-

- <div class="@container">

- <div class="@sm:grid-cols-2 @lg:grid-cols-3 grid grid-cols-1">

-

- </div>

- ```

- #### `field-sizing` for Auto-Resizing Textareas

- ```html

- <textarea class="field-sizing-content resize-none min-h-20 max-h-64">

- Auto-resizes to fit content — no JavaScript needed!

- </textarea>

- ```

- ### Migration from v3 to v4

- #### Automated Migration Tool

- ```bash

- npx @tailwindcss/upgrade

- ```

- #### Key Breaking Changes

- | v3 | v4 Equivalent |

- |---|---|

- | `tailwind.config.js` | `@theme {}` in CSS |

- | `theme.extend.colors` | `--color-*` CSS vars in `@theme` |

- | `plugins: [require('@tailwindcss/typography')]` | `@plugin "@tailwindcss/typography"` |

- | `darkMode: 'class'` | `@variant dark (&:where(.dark, .dark *))` |

- | `screens` in config | `--breakpoint-*` in `@theme` |

- | `content` array | Auto-detected (no config needed) |

+ #### 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.

- #### Custom Variants in v4

- ```css

- /* Custom variants — replaces addVariant() in plugins */

- @variant hocus (&:hover, &:focus);

- @variant dark (&:where(.dark, .dark *));

- @variant reduced-motion (@media (prefers-reduced-motion: reduce));

- ```

+ #### 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 *));

+ ```

- ### Performance Tips

- - Tailwind v4 uses **Lightning CSS** for transforms — 4x faster builds than v3 with PostCSS.

- - CSS bundle is now fully tree-shaken — only styles used in your HTML/JSX are generated.

- - Use `@layer utilities` for custom utilities that need Tailwind's specificity.

- - Avoid `@apply` in performance-critical loops — prefer utility classes directly in HTML.

+ #### 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.

---

## Bahasa Indonesia

### Deskripsi

- Panduan mendalam untuk **Tailwind CSS v4** — mencakup model konfigurasi CSS-first baru, direktif `@theme` untuk design token, `@plugin` untuk plugin, 3D transform, peningkatan gradient, dan migrasi dari v3.

+ 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 baru.

- - Mendefinisikan design token via direktif `@theme` di CSS.

- - Migrasi dari Tailwind CSS v3 ke v4.

- - Menggunakan utilitas v4 baru: 3D transform, `field-sizing`, fungsi color mix.

- - Mendaftarkan plugin kustom dengan direktif `@plugin`.

+ - 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`.

- ### Tailwind v4 — Pergeseran Paradigma CSS-First

+ ## 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`.

- Tailwind v4 menghilangkan `tailwind.config.js` sepenuhnya. Semua konfigurasi dilakukan di CSS menggunakan direktif `@theme`. Plugin didaftarkan dengan `@plugin`. Breakpoint, warna, spacing, animasi — semuanya didefinisikan sebagai variabel CSS `--*` di dalam blok `@theme`.

+ ### Standar Eksekusi

- ### Utilitas Baru di Tailwind v4

+ #### 1. Arsitektur CSS-First

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

- #### 3D Transform

- Tailwind v4 menambahkan utilitas untuk 3D transform: `perspective-{nilai}`, `rotate-x-{derajat}`, `rotate-y-{derajat}`, `transform-3d`, `backface-visible`, `backface-hidden` — ideal untuk efek flip kartu dan galeri 3D.

+ ```css

+ /* app/globals.css */

+ @import "tailwindcss";

- #### Container Queries

- Gunakan `@container` dan utilitas `@sm:`, `@lg:` untuk membuat komponen yang responsif terhadap ukuran container induknya, bukan ukuran viewport.

+ @theme {

+ /* Warna OKLCH untuk layar wide-gamut */

+ --color-brand-50: oklch(97% 0.02 250);

+ --color-brand-500: oklch(55% 0.2 250);

- #### `field-sizing` untuk Textarea Auto-Resize

- Kelas `field-sizing-content` membuat textarea otomatis menyesuaikan ukurannya dengan konten — tanpa JavaScript.

+ /* Tipografi */

+ --font-sans: "Inter Variable", system-ui, sans-serif;

+ }

- ### Migrasi dari v3 ke v4

+ /* Registrasi plugin */

+ @plugin "@tailwindcss/typography";

+ ```

- Gunakan alat migrasi otomatis `npx @tailwindcss/upgrade` untuk konversi dasar. Perubahan kunci:

- - `tailwind.config.js` → `@theme {}` di CSS

- - `plugins: [require('...')]` → `@plugin "..."`

- - `darkMode: 'class'` → `@variant dark`

- - Array `content` → Deteksi otomatis (tidak perlu konfigurasi)

+ #### 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.

- ### Tip Performa

- - Tailwind v4 menggunakan **Lightning CSS** — build 4x lebih cepat dari v3 dengan PostCSS.

- - Bundle CSS sepenuhnya di-tree-shake — hanya style yang digunakan yang dihasilkan.

- - Gunakan `@layer utilities` untuk utilitas kustom yang membutuhkan spesifisitas Tailwind.

- - Hindari `@apply` di loop kritis performa — gunakan kelas utilitas langsung di HTML.

+ #### 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.