tailwind-v4

Tailwind CSS v4

Overview

Tailwind v4 is CSS-first: no tailwind.config.js, no PostCSS config. Everything lives in CSS via directives.

Setup (Vite)

pnpm add tailwindcss @tailwindcss/vite

// vite.config.ts
import tailwindcss from '@tailwindcss/vite'
export default defineConfig({ plugins: [react(), tailwindcss()] })

/* App.css */
@import "tailwindcss";

No content globs needed — auto-detected. No autoprefixer — Lightning CSS handles it.

v3 → v4 Key Changes

v3	v4
tailwind.config.js	@theme in CSS
@tailwind base/components/utilities	@import "tailwindcss"
darkMode: 'class'	@custom-variant dark
content: [...]	Auto-detected
PostCSS required	@tailwindcss/vite plugin
Container query plugin	Built-in @container

Design flow: token-first

設計 UI 時先看 design token，再考慮 utility。不要遇到設計稿的值就寫 arbitrary（text-[13px] / bg-[#3a7] / p-[7px]）。

正確順序（寫 JSX 前跑一遍）：

1. 先查既有 token — 需要的顏色 / 字級 / 間距 / radius / shadow / z-index 是否已經在 @theme 或內建 scale？
   • 顏色：grep "^\s*--color-" apps/web/src/App.css
   • Spacing / text / z：用「優先內建 utility」表對照
2. 差 1–2px / 1–2 階 → 就近取 — design system 的一致性 > pixel-perfect。13px 取 text-xs 或 text-sm、#3a7d5e 取 text-success。
3. 超出既有 token 範圍 → 先擴 token，不要寫 arbitrary
   • 新色階：加 --color-X 到 @theme
   • 新語意層級（z-index、muted tier、shadow）：加對應 --* token
   • 新可重用效果：抽 @utility
4. 只有這些 arbitrary 值是合法的（見下方「Arbitrary value 正當情境」）：
   • calc(...) 計算值
   • 引用動態 CSS variable
   • 刻意 off-grid 且有清楚理由（icon 尺寸、對齊特定視覺錨點）

不要這樣做：

// ❌ 為了新設計稿直接寫 arbitrary
<div className="bg-[#2a4a6e] text-[13px] p-[7px] shadow-[0_2px_8px_rgba(0,0,0,0.4)]" />

// ✅ 先把需要的值加進 @theme，再用 semantic utility
// App.css:  --color-surface-sunken: oklch(...); --shadow-card: 0 2px 8px rgba(0,0,0,0.4);
<div className="bg-surface-sunken text-xs p-2 shadow-card" />

特別 callout — literal-pixel arbitraries：

任何 \w+-[Npx]（text-[13px] / h-[38px] / max-h-[480px] / max-w-[180px] 等）明確禁止。