From zenbu-powers
TailwindCSS v4 的完整技術參考，採用 CSS-first 設定（非 v3 的 JS config）。 **版本判斷優先**：使用前先讀 package.json 的 `tailwindcss` 版本—— 若 pin 為 `^4.x` 或存在 `@tailwindcss/vite` / `@tailwindcss/postcss` 依賴， 使用此 skill；若為 `^3.x` 或存在 `tailwind.config.js`，改用 tailwindcss-v3 skill。 涵蓋 @theme 指令、@custom-variant、@utility、@source、@plugin、design tokens、 container queries、3D transforms、@starting-style、field-sizing、prose 排版、 @tailwindcss/vite、@tailwindcss/typography 等 v4 專屬 API。 ⚠️ utility class（bg-*、text-*、flex、grid、hover: 等）v3/v4 共用語法， 不可單憑這些 class 名稱觸發本 skill——必須先確認專案為 v4。 v3 與 v4 架構不相容，snippets 無法跨版互通。
npx claudepluginhub zenbuapps/zenbu-powers --plugin zenbu-powersThis skill uses the workspace's default tool permissions.
> **適用版本**：v4.x（含 v4.0.7+）| **文件來源**：https://tailwindcss.com/docs | **最後更新**：2026-03
Searches, retrieves, and installs Agent Skills from prompts.chat registry using MCP tools like search_skills and get_skill. Activates for finding skills, browsing catalogs, or extending Claude.
Checks Next.js compilation errors using a running Turbopack dev server after code edits. Fixes actionable issues before reporting complete. Replaces `next build`.
Guides code writing, review, and refactoring with Karpathy-inspired rules to avoid overcomplication, ensure simplicity, surgical changes, and verifiable success criteria.
Share bugs, ideas, or general feedback.
適用版本：v4.x（含 v4.0.7+）| 文件來源：https://tailwindcss.com/docs | 最後更新：2026-03
v4 是 CSS-first 的重大改版。核心變化：用 @import "tailwindcss" 取代三行 @tailwind 指令，用 @theme CSS 區塊取代 tailwind.config.js，效能提升 3-5x（增量建置快達 182x）。
// vite.config.ts
import { defineConfig } from 'vite'
import tailwindcss from '@tailwindcss/vite'
export default defineConfig({
plugins: [tailwindcss()],
})
/* src/index.css */
@import "tailwindcss";
安裝：npm install tailwindcss @tailwindcss/vite
@import "tailwindcss";
@theme {
/* 新增自訂 token，自動生成 utility class */
--color-brand: oklch(0.72 0.11 178);
--font-display: "Satoshi", sans-serif;
--breakpoint-3xl: 120rem;
/* 覆蓋整個命名空間 */
--color-*: initial;
--color-white: #fff;
--color-primary: oklch(0.72 0.11 221);
/* 覆蓋全部預設 */
--*: initial;
}
生成結果：bg-brand、text-brand、font-display、3xl:* 等 class。
@theme inline {
--color-canvas: var(--acme-canvas-color); /* 在使用處解析，不在定義處解析 */
--font-sans: var(--font-inter);
}
/* 短語法 */
@custom-variant theme-midnight (&:where([data-theme="midnight"] *));
/* 完整語法（多規則） */
@custom-variant dark (&:where(.dark, .dark *));
/* 多層巢狀 */
@custom-variant any-hover {
@media (any-hover: hover) {
&:hover {
@slot;
}
}
}
/* 靜態 utility */
@utility content-auto {
content-visibility: auto;
}
/* 函式式 utility（配合主題） */
@utility tab-* {
tab-size: --value(--tab-size-*); /* 匹配主題值 */
tab-size: --value(integer); /* 匹配裸數字 */
tab-size: --value([integer]); /* 匹配任意值 */
}
@import "tailwindcss";
/* 加入額外來源（預設不掃 node_modules） */
@source "../node_modules/@my-company/ui-lib";
/* 強制生成特定 class（safelist） */
@source inline("underline");
@source inline("{hover:,focus:,}bg-red-{50,{100..900..100},950}");
/* 排除路徑 */
@source not "../src/legacy";
/* 停用自動偵測 */
@import "tailwindcss" source(none);
@import "tailwindcss";
@plugin "@tailwindcss/typography";
/* 帶參數的插件 */
@plugin "@tailwindcss/typography" {
className: wysiwyg;
}
/* 在全域 CSS 中使用 */
.select2-dropdown {
@apply rounded-b-lg shadow-md border border-gray-300;
}
/* 在 Vue/Svelte <style> 或 CSS Modules 中需要 @reference */
<style>
@reference "../../app.css";
h1 { @apply text-2xl font-bold text-red-500; }
</style>
/* 在 CSS 中設定 */
@import "tailwindcss";
@custom-variant dark (&:where(.dark, .dark *));
<html class="dark">
<div class="bg-white dark:bg-gray-900 text-gray-900 dark:text-white">
內容
</div>
</html>
// 切換邏輯
document.documentElement.classList.toggle(
'dark',
localStorage.theme === 'dark' ||
(!('theme' in localStorage) && window.matchMedia('(prefers-color-scheme: dark)').matches)
)
<div class="@container">
<div class="grid grid-cols-1 @sm:grid-cols-3 @lg:grid-cols-4">
<!-- 根據容器寬度響應 -->
</div>
</div>
<!-- 命名容器（巢狀時區分） -->
<div class="@container/main">
<div class="@sm/main:flex-row flex-col">...</div>
</div>
<div class="perspective-distant">
<article class="rotate-x-51 rotate-z-43 transform-3d">
3D 旋轉卡片
</article>
</div>
新增 utilities：rotate-x-*、rotate-y-*、scale-z-*、translate-z-*、perspective-*、transform-3d
<div
popover
id="my-popover"
class="transition-discrete starting:open:opacity-0 opacity-100"
>
<!-- 從透明到不透明的進場動畫 -->
</div>
/* 安裝：npm install -D @tailwindcss/typography */
@import "tailwindcss";
@plugin "@tailwindcss/typography";
<article class="prose lg:prose-xl dark:prose-invert max-w-none">
<!-- Markdown 渲染內容 -->
</article>
<!-- 排除部分內容不套用 prose 樣式 -->
<article class="prose">
<h1>標題</h1>
<div class="not-prose">不套用排版樣式</div>
</article>
| 嚴重程度 | 問題 | 解法 |
|---|---|---|
| 🔴 重大 | v4 無 tailwind.config.js（預設不讀取） | 改用 @theme 或加 @config "tailwind.config.js" |
| 🔴 重大 | ring 預設寬度從 3px 改為 1px | 使用 ring-3 明確指定，或設 --default-ring-width: 3px |
| 🔴 重大 | border 預設顏色從 gray-200 改為 currentColor | 明確加 border-gray-200 |
| 🔴 重大 | shadow-sm 變 shadow-xs，shadow 變 shadow-sm（整體縮小一級） | 全面更新 shadow class 名稱 |
| 🔴 重大 | outline-none 現在真的設 outline-style: none | 使用 outline-hidden 代替 |
| 🟡 中等 | @layer utilities { .tab-4 {...} } 不適用於 variant | 改用 @utility tab-4 { ... } |
| 🟡 中等 | CSS 變數在 arbitrary value 需用括號 bg-(--brand) | 棄用 bg-[--brand] 語法（舊語法仍支援） |
| 🟡 中等 | Variant 堆疊順序改為左到右 | *:first:pt-0 而非 first:*:pt-0 |
| 🟡 中等 | hover: 在 v4 預設包含 @media (hover: hover) | 行動裝置需自訂 @custom-variant hover (&:hover) |
| 🟡 中等 | space-y-* 選擇器改為 :not(:last-child) | 考慮改用 gap-* |
| 🟡 中等 | 不支援 Sass/Less/Stylus | v4 本身即為 preprocessor |
| 🟢 輕微 | flex-shrink-* -> shrink-*，flex-grow-* -> grow-* | 已棄用 class 仍可用 |
| 需求 | 參閱檔案 |
|---|---|
| 完整 v3 -> v4 破壞性變更對照表 | references/breaking-changes.md |
| @theme 命名空間完整清單 & 所有指令 API | references/directives-and-theme.md |
| 所有 Variant 完整清單（pseudo-class、media、group、peer 等） | references/variants.md |
| 常用 utility class 範例（顏色、間距、排版、動畫等） | references/utilities-examples.md |