⚠️

重要前提

安装AI Skills的关键前提是：必须科学上网，且开启TUN模式，这一点至关重要，直接决定安装能否顺利完成，在此郑重提醒三遍：科学上网，科学上网，科学上网。查看完整安装教程 →

Tailwind CSS v4 + shadcn/ui 生产级技术栈配置指南与最佳实践

tailwind-v4-shadcn by ovachiever/droid-tings

74 周安装量

32 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/ovachiever/droid-tings --skill tailwind-v4-shadcn

UI组件库 CSS 前端架构

🇨🇳中文介绍

Tailwind v4 + shadcn/ui 生产级技术栈

生产环境验证：WordPress Auditor (https://wordpress-auditor.webfonts.workers.dev) 最后更新：2025-11-09 状态：生产就绪 ✅

⚠️ 开始前必读！

对 AI 助手至关重要：如果你是 Claude Code 正在帮助用户设置 Tailwind v4：

在对话开始时明确说明你正在使用此技能
参考技能中的模式而非通用知识
防止 reference/common-gotchas.md 中列出的已知问题
不要猜测 - 如果不确定，请查阅技能文档

用户需执行的操作：告诉 Claude 先检查此技能！

请说："我正在设置 Tailwind v4 + shadcn/ui - 请先检查 tailwind-v4-shadcn 技能"

为何这很重要（实际效果）

未激活技能时：

❌ 设置时间：约 5 分钟
❌ 遇到错误：2-3 个（tw-animate-css，重复的 @layer base）
❌ 需要手动修复：2+ 次提交
❌ Token 使用量：约 65k
❌ 用户信心：需要调试

激活技能后：

✅ 设置时间：约 1 分钟

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

此技能可预防的已知问题

tw-animate-css 导入错误（v4 中已弃用）
重复的 @layer base 块（shadcn init 会添加自己的）
错误的模板选择（vanilla TS 与 React）
缺少初始化后清理（不兼容的 CSS 规则）
错误的插件语法（使用 @import 或 require() 而不是 @plugin 指令）

当技能激活时，所有这些问题都会自动处理。

快速开始（5 分钟 - 严格按此顺序）

pnpm add tailwindcss @tailwindcss/vite
pnpm add -D @types/node
pnpm dlx shadcn@latest init

// vite.config.ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import tailwindcss from '@tailwindcss/vite'
import path from 'path'

export default defineConfig({
  plugins: [react(), tailwindcss()],
  resolve: {
    alias: {
      '@': path.resolve(__dirname, './src')
    }
  }
})

3. 更新 components.json

{
  "tailwind": {
    "config": "",              // ← 关键：v4 留空
    "css": "src/index.css",
    "baseColor": "slate",      // 基础调色板
    "cssVariables": true,
    "prefix": ""               // 工具类无前缀
  }
}

4. 删除 tailwind.config.ts

rm tailwind.config.ts  # v4 不使用此文件

四步架构（关键）

此模式是强制性的 - 跳过步骤会破坏你的主题。

步骤 1：在根层级定义 CSS 变量

/* src/index.css */
@import "tailwindcss";

:root {
  --background: hsl(0 0% 100%);      /* ← 必须使用 hsl() 包装 */
  --foreground: hsl(222.2 84% 4.9%);
  --primary: hsl(221.2 83.2% 53.3%);
  /* ... 所有浅色模式颜色 */
}

.dark {
  --background: hsl(222.2 84% 4.9%);
  --foreground: hsl(210 40% 98%);
  --primary: hsl(217.2 91.2% 59.8%);
  /* ... 所有深色模式颜色 */
}

✅ 在根层级定义（不在 @layer base 内部）
✅ 所有颜色值都使用 hsl() 包装
✅ 使用 .dark 表示深色模式（不是 .dark { @theme { } }）

步骤 2：将变量映射到 Tailwind 工具类

@theme inline {
  --color-background: var(--background);
  --color-foreground: var(--foreground);
  --color-primary: var(--primary);
  /* ... 映射所有 CSS 变量 */
}

为何需要此步骤：

生成工具类（bg-background、text-primary）
没有这个，bg-primary 等将不存在

步骤 3：应用基础样式

@layer base {
  body {
    background-color: var(--background);  /* 此处不要用 hsl() */
    color: var(--foreground);
  }
}

✅ 直接引用变量：var(--background)
❌ 切勿双重包装：hsl(var(--background))

步骤 4：结果 - 自动深色模式

<div className="bg-background text-foreground">
  {/* 不需要 dark: 变体 - 主题自动切换 */}
</div>

1. 创建 ThemeProvider

完整实现请参阅 reference/dark-mode.md 或使用模板：

// 复制自：templates/theme-provider.tsx

2. 包装你的应用

// src/main.tsx
import { ThemeProvider } from '@/components/theme-provider'

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <ThemeProvider defaultTheme="dark" storageKey="vite-ui-theme">
      <App />
    </ThemeProvider>
  </React.StrictMode>,
)

3. 添加主题切换

pnpm dlx shadcn@latest add dropdown-menu

ModeToggle 组件代码请参阅 reference/dark-mode.md。

关键规则（必须遵守）

在 :root 和 .dark 中用 hsl() 包装颜色值

--background: hsl(0 0% 100%); /* ✅ 正确 */
使用 @theme inline 映射所有 CSS 变量

@theme inline { --color-background: var(--background); }
在 components.json 中设置 "tailwind.config": ""

{ "tailwind": { "config": "" } }
删除 tailwind.config.ts（如果存在）
使用 @tailwindcss/vite 插件（不是 PostCSS）
使用 cn() 处理条件类

import { cn } from "@/lib/utils" <div className={cn("base", isActive && "active")} />

将 :root 或 .dark 放在 @layer base 内部

/* 错误 */ @layer base { :root { --background: hsl(...); } }
使用 .dark { @theme { } } 模式

/* 错误 - v4 不支持嵌套的 @theme */ .dark { @theme { --color-primary: hsl(...); } }
双重包装颜色

/* 错误 */ body { background-color: hsl(var(--background)); }
使用 tailwind.config.ts 定义主题颜色

/* 错误 - v4 会忽略此配置 */ export default { theme: { extend: { colors: { primary: 'hsl(var(--primary))' } } } }
使用 @apply 指令（v4 中已弃用）
对语义化颜色使用 dark: 变体

/* 错误 */ <div className="bg-primary dark:bg-primary-dark" />

<div className="bg-primary" />

语义化颜色标记

始终使用语义化名称定义颜色：

:root {
  --destructive: hsl(0 84.2% 60.2%);        /* 红色 - 错误，关键 */
  --success: hsl(142.1 76.2% 36.3%);        /* 绿色 - 成功状态 */
  --warning: hsl(38 92% 50%);               /* 黄色 - 警告 */
  --info: hsl(221.2 83.2% 53.3%);           /* 蓝色 - 信息，主要 */
}

<div className="bg-destructive text-destructive-foreground">关键</div>
<div className="bg-success text-success-foreground">成功</div>
<div className="bg-warning text-warning-foreground">警告</div>
<div className="bg-info text-info-foreground">信息</div>

常见问题与快速修复

症状	原因	修复方法
`bg-primary` 不生效	缺少 `@theme inline` 映射	添加 `@theme inline` 块
颜色全是黑/白	双重 `hsl()` 包装	使用 `var(--color)` 而非 `hsl(var(--color))`
深色模式不切换	缺少 ThemeProvider	用 `<ThemeProvider>` 包装应用
构建失败	`tailwind.config.ts` 存在	删除该文件
文字不可见	对比度颜色错误	检查 `:root`/`.dark` 中的颜色定义

完整故障排除指南请参阅 reference/common-gotchas.md。

所有模板均可在 templates/ 目录中找到：

index.css - 包含所有颜色变量的完整 CSS 设置
components.json - shadcn/ui v4 配置
vite.config.ts - Vite + Tailwind 插件设置
tsconfig.app.json - 带路径别名的 TypeScript 配置
theme-provider.tsx - 带 localStorage 的深色模式提供器
utils.ts - 用于合并类的 cn() 工具函数

将这些文件复制到你的项目并根据需要自定义。

已创建 Vite + React + TypeScript 项目
已安装 @tailwindcss/vite（不是 postcss）
vite.config.ts 使用 tailwindcss() 插件
tsconfig.json 已配置路径别名
components.json 存在且 "config": ""
没有 tailwind.config.ts 文件
src/index.css 遵循 v4 模式：
- :root 和 .dark 在根层级（不在 @layer 内）
- 颜色用 hsl() 包装
- @theme inline 映射所有变量
- @layer base 使用未包装的变量
已安装主题提供器并包装应用
已创建深色模式切换组件
在浏览器中测试主题切换是否正常工作

添加新的语义化颜色：

:root {
  --brand: hsl(280 65% 60%);
  --brand-foreground: hsl(0 0% 100%);
}

.dark {
  --brand: hsl(280 75% 70%);
  --brand-foreground: hsl(280 20% 10%);
}

@theme inline {
  --color-brand: var(--brand);
  --color-brand-foreground: var(--brand-foreground);
}

用法：<div className="bg-brand text-brand-foreground">品牌化</div>

完整的 v3 → v4 迁移步骤请参阅 reference/migration-guide.md。

始终使用语义化标记

<Button variant="destructive">删除</Button> /* ✅ / <Button className="bg-red-600">删除</Button> / ❌ */
使用 cn() 处理条件样式

import { cn } from "@/lib/utils"

<div className={cn(

  "基础类",
  isActive && "激活类",
  hasError && "错误类"
)} />

3. 组合使用 shadcn/ui 组件

    <Dialog>
  <DialogTrigger asChild>
    <Button>打开</Button>
  </DialogTrigger>
  <DialogContent>
    <DialogHeader>
      <DialogTitle>标题</DialogTitle>
    </DialogHeader>
  </DialogContent>
</Dialog>

{
  "dependencies": {
    "tailwindcss": "^4.1.17",
    "@tailwindcss/vite": "^4.1.17",
    "clsx": "^2.1.1",
    "tailwind-merge": "^3.3.1",
    "@radix-ui/react-*": "latest",
    "lucide-react": "^0.553.0",
    "react": "^19.2.0",
    "react-dom": "^19.2.0"
  },
  "devDependencies": {
    "@types/node": "^24.10.0",
    "@vitejs/plugin-react": "^5.1.0",
    "vite": "^7.2.2",
    "typescript": "~5.9.0",
    "tw-animate-css": "^1.4.0"
  }
}

动画包（2025年11月更新）

shadcn/ui 已弃用 tailwindcss-animate，改用 tw-animate-css 以兼容 Tailwind v4。

✅ 务必安装（v4 兼容）：

pnpm add -D tw-animate-css

然后添加到 src/index.css：

@import "tailwindcss";
@import "tw-animate-css";

❌ 切勿安装：

npm install tailwindcss-animate  # 已弃用 - 仅限 v3

原因：tw-animate-css 是官方提供的 v4 兼容动画替代方案，shadcn/ui 组件需要它。

Tailwind v4 支持使用 CSS 中的 @plugin 指令的官方插件。

官方插件（Tailwind Labs）

排版插件 - 样式化 Markdown/CMS 内容

何时使用： 显示博客文章、文档或任何来自 Markdown/CMS 的 HTML 内容。

pnpm add -D @tailwindcss/typography

配置（v4 语法）：

/* src/index.css */
@import "tailwindcss";
@plugin "@tailwindcss/typography";

<article class="prose lg:prose-xl dark:prose-invert">
  {{ markdown_content }}
</article>

prose - 基础排版样式
prose-sm、prose-base、prose-lg、prose-xl、prose-2xl - 尺寸变体
dark:prose-invert - 深色模式样式

表单插件 - 重置表单元素样式

何时使用： 构建不使用 shadcn/ui 组件的自定义表单，或需要跨浏览器一致的表单样式。

pnpm add -D @tailwindcss/forms

配置（v4 语法）：

/* src/index.css */
@import "tailwindcss";
@plugin "@tailwindcss/forms";

重置浏览器默认表单样式
使表单元素可使用 Tailwind 工具类进行样式设置
修复输入框、选择框、复选框、单选框的跨浏览器不一致问题

注意： 对 shadcn/ui 用户来说不太关键（他们有预样式的表单组件），但对于基础表单仍然有用。

在 v4 项目中使用 v3 语法时会出现这些错误：

❌ 错误（v3 配置文件语法）：

// tailwind.config.js
module.exports = {
  plugins: [require('@tailwindcss/typography')]
}

❌ 错误（使用 @import 而不是 @plugin）：

@import "@tailwindcss/typography";  /* 无效 */

✅ 正确（v4 @plugin 指令）：

/* src/index.css */
@import "tailwindcss";
@plugin "@tailwindcss/typography";
@plugin "@tailwindcss/forms";

内置功能（无需插件）

容器查询已内置到 Tailwind v4 核心中 - 无需插件：

<div className="@container">
  <div className="@md:text-lg">
    响应容器宽度，而非视口
  </div>
</div>

❌ 不要安装： @tailwindcss/container-queries（已弃用，现为核心功能）

如需更深入理解，请参阅：

architecture.md - 四步模式的深入解析
dark-mode.md - 完整的深色模式实现
common-gotchas.md - 所有可能出错的地方（及修复方法）
migration-guide.md - 将硬编码颜色迁移到 CSS 变量

shadcn/ui Vite 设置：https://ui.shadcn.com/docs/installation/vite
shadcn/ui Tailwind v4 指南：https://ui.shadcn.com/docs/tailwind-v4
shadcn/ui 深色模式（Vite）：https://ui.shadcn.com/docs/dark-mode/vite
Tailwind v4 文档：https://tailwindcss.com/docs
shadcn/ui 主题化：https://ui.shadcn.com/docs/theming

此技能基于 WordPress Auditor 项目：

在线地址：https://wordpress-auditor.webfonts.workers.dev
技术栈：Vite + React 19 + Tailwind v4 + shadcn/ui + Cloudflare Workers
深色模式：完整的系统/浅色/深色支持
版本：Tailwind v4.1.14 + shadcn/ui 最新版（2025年10月）

此技能中的所有模式均已通过生产环境验证。

有问题？遇到问题？

先检查 reference/common-gotchas.md
验证四步架构中的所有步骤
确保 components.json 中 "config": ""
删除 tailwind.config.ts（如果存在）
查看官方文档：https://ui.shadcn.com/docs/tailwind-v4

🇺🇸English

Tailwind v4 + shadcn/ui Production Stack

Production-tested : WordPress Auditor (https://wordpress-auditor.webfonts.workers.dev) Last Updated : 2025-11-09 Status : Production Ready ✅

⚠️ BEFORE YOU START (READ THIS!)

CRITICAL FOR AI AGENTS : If you're Claude Code helping a user set up Tailwind v4:

Explicitly state you're using this skill at the start of the conversation
Reference patterns from the skill rather than general knowledge
Prevent known issues listed in reference/common-gotchas.md
Don't guess - if unsure, check the skill documentation

USER ACTION REQUIRED : Tell Claude to check this skill first!

Say: "I'm setting up Tailwind v4 + shadcn/ui - check the tailwind-v4-shadcn skill first"

Why This Matters (Real-World Results)

Without skill activation:

❌ Setup time: ~5 minutes
❌ Errors encountered: 2-3 (tw-animate-css, duplicate @layer base)
❌ Manual fixes needed: 2+ commits
❌ Token usage: ~65k
❌ User confidence: Required debugging

With skill activation:

✅ Setup time: ~1 minute
✅ Errors encountered: 0
✅ Manual fixes needed: 0
✅ Token usage: ~20k (70% reduction)
✅ User confidence: Instant success

Known Issues This Skill Prevents

tw-animate-css import error (deprecated in v4)
Duplicate @layer base blocks (shadcn init adds its own)
Wrong template selection (vanilla TS vs React)
Missing post-init cleanup (incompatible CSS rules)
Wrong plugin syntax (using @import or require() instead of @plugin directive)

All of these are handled automatically when the skill is active.

Quick Start (5 Minutes - Follow This Exact Order)

1. Install Dependencies

pnpm add tailwindcss @tailwindcss/vite
pnpm add -D @types/node
pnpm dlx shadcn@latest init

2. Configure Vite

// vite.config.ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import tailwindcss from '@tailwindcss/vite'
import path from 'path'

export default defineConfig({
  plugins: [react(), tailwindcss()],
  resolve: {
    alias: {
      '@': path.resolve(__dirname, './src')
    }
  }
})

3. Update components.json

{
  "tailwind": {
    "config": "",              // ← CRITICAL: Empty for v4
    "css": "src/index.css",
    "baseColor": "slate",      // Base color palette
    "cssVariables": true,
    "prefix": ""               // No prefix for utility classes
  }
}

4. Delete tailwind.config.ts

rm tailwind.config.ts  # v4 doesn't use this file

The Four-Step Architecture (CRITICAL)

This pattern is mandatory - skipping steps will break your theme.

Step 1: Define CSS Variables at Root Level

/* src/index.css */
@import "tailwindcss";

:root {
  --background: hsl(0 0% 100%);      /* ← hsl() wrapper required */
  --foreground: hsl(222.2 84% 4.9%);
  --primary: hsl(221.2 83.2% 53.3%);
  /* ... all light mode colors */
}

.dark {
  --background: hsl(222.2 84% 4.9%);
  --foreground: hsl(210 40% 98%);
  --primary: hsl(217.2 91.2% 59.8%);
  /* ... all dark mode colors */
}

Critical Rules:

✅ Define at root level (NOT inside @layer base)
✅ Use hsl() wrapper on all color values
✅ Use .dark for dark mode (NOT .dark { @theme { } })

Step 2: Map Variables to Tailwind Utilities

@theme inline {
  --color-background: var(--background);
  --color-foreground: var(--foreground);
  --color-primary: var(--primary);
  /* ... map ALL CSS variables */
}

Why This Is Required:

Generates utility classes (bg-background, text-primary)
Without this, bg-primary etc. won't exist

Step 3: Apply Base Styles

@layer base {
  body {
    background-color: var(--background);  /* NO hsl() here */
    color: var(--foreground);
  }
}

Critical Rules:

✅ Reference variables directly: var(--background)
❌ Never double-wrap: hsl(var(--background))

Step 4: Result - Automatic Dark Mode

<div className="bg-background text-foreground">
  {/* No dark: variants needed - theme switches automatically */}
</div>

Dark Mode Setup

1. Create ThemeProvider

See reference/dark-mode.md for full implementation or use template:

// Copy from: templates/theme-provider.tsx

2. Wrap Your App

// src/main.tsx
import { ThemeProvider } from '@/components/theme-provider'

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <ThemeProvider defaultTheme="dark" storageKey="vite-ui-theme">
      <App />
    </ThemeProvider>
  </React.StrictMode>,
)

3. Add Theme Toggle

pnpm dlx shadcn@latest add dropdown-menu

See reference/dark-mode.md for ModeToggle component code.

Critical Rules (MUST FOLLOW)

✅ Always Do:

Wrap color values withhsl() in :root and .dark

--background: hsl(0 0% 100%); /* ✅ Correct */
Use@theme inline to map all CSS variables

@theme inline { --color-background: var(--background); }
Set"tailwind.config": "" in components.json

{ "tailwind": { "config": "" } }
Deletetailwind.config.ts if it exists
Use@tailwindcss/vite plugin (NOT PostCSS)

❌ Never Do:

Put:root or .dark inside @layer base

/* WRONG */ @layer base { :root { --background: hsl(...); } }
Use.dark { @theme { } } pattern

/* WRONG - v4 doesn't support nested @theme */ .dark { @theme { --color-primary: hsl(...); } }
Double-wrap colors

/* WRONG */ body { background-color: hsl(var(--background)); }
Usetailwind.config.ts for theme colors

/* WRONG - v4 ignores this */ export default { theme: { extend: { colors: { primary: 'hsl(var(--primary))' } } } }
Use@apply directive (deprecated in v4)

/* CORRECT */

<div className="bg-primary" />

Semantic Color Tokens

Always use semantic names for colors:

:root {
  --destructive: hsl(0 84.2% 60.2%);        /* Red - errors, critical */
  --success: hsl(142.1 76.2% 36.3%);        /* Green - success states */
  --warning: hsl(38 92% 50%);               /* Yellow - warnings */
  --info: hsl(221.2 83.2% 53.3%);           /* Blue - info, primary */
}

Usage:

<div className="bg-destructive text-destructive-foreground">Critical</div>
<div className="bg-success text-success-foreground">Success</div>
<div className="bg-warning text-warning-foreground">Warning</div>
<div className="bg-info text-info-foreground">Info</div>

Common Issues & Quick Fixes

Symptom	Cause	Fix
`bg-primary` doesn't work	Missing `@theme inline` mapping	Add `@theme inline` block
Colors all black/white	Double `hsl()` wrapping	Use `var(--color)` not `hsl(var(--color))`
Dark mode not switching	Missing ThemeProvider	Wrap app in `<ThemeProvider>`

See reference/common-gotchas.md for complete troubleshooting guide.

File Templates

All templates are available in the templates/ directory:

index.css - Complete CSS setup with all color variables
components.json - shadcn/ui v4 configuration
vite.config.ts - Vite + Tailwind plugin setup
tsconfig.app.json - TypeScript with path aliases
theme-provider.tsx - Dark mode provider with localStorage
utils.ts - cn() utility for class merging

Copy these files to your project and customize as needed.

Complete Setup Checklist

Vite + React + TypeScript project created
@tailwindcss/vite installed (NOT postcss)
vite.config.ts uses tailwindcss() plugin
tsconfig.json has path aliases configured
components.json exists with "config": ""
NO tailwind.config.ts file exists
src/index.css follows v4 pattern:
- :root and .dark at root level (not in @layer)

Advanced Topics

Custom Colors

Add new semantic colors:

:root {
  --brand: hsl(280 65% 60%);
  --brand-foreground: hsl(0 0% 100%);
}

.dark {
  --brand: hsl(280 75% 70%);
  --brand-foreground: hsl(280 20% 10%);
}

@theme inline {
  --color-brand: var(--brand);
  --color-brand-foreground: var(--brand-foreground);
}

Usage: <div className="bg-brand text-brand-foreground">Branded</div>

Migration from v3

See reference/migration-guide.md for complete v3 → v4 migration steps.

Component Best Practices

Always use semantic tokens

<Button variant="destructive">Delete</Button> /* ✅ / <Button className="bg-red-600">Delete</Button> / ❌ */
Usecn() for conditional styling

import { cn } from "@/lib/utils"

<div className={cn(

  "base-class",
  isActive && "active-class",
  hasError && "error-class"
)} />

3. Compose shadcn/ui components

    <Dialog>
  <DialogTrigger asChild>
    <Button>Open</Button>
  </DialogTrigger>
  <DialogContent>
    <DialogHeader>
      <DialogTitle>Title</DialogTitle>
    </DialogHeader>
  </DialogContent>
</Dialog>

Dependencies

✅ Install These

{
  "dependencies": {
    "tailwindcss": "^4.1.17",
    "@tailwindcss/vite": "^4.1.17",
    "clsx": "^2.1.1",
    "tailwind-merge": "^3.3.1",
    "@radix-ui/react-*": "latest",
    "lucide-react": "^0.553.0",
    "react": "^19.2.0",
    "react-dom": "^19.2.0"
  },
  "devDependencies": {
    "@types/node": "^24.10.0",
    "@vitejs/plugin-react": "^5.1.0",
    "vite": "^7.2.2",
    "typescript": "~5.9.0",
    "tw-animate-css": "^1.4.0"
  }
}

Animation Packages (Updated Nov 2025)

shadcn/ui has deprecated tailwindcss-animate in favor of tw-animate-css for Tailwind v4 compatibility.

✅ DO Install (v4-compatible) :

pnpm add -D tw-animate-css

Then add to src/index.css:

@import "tailwindcss";
@import "tw-animate-css";

❌ DO NOT Install :

npm install tailwindcss-animate  # Deprecated - v3 only

Why : tw-animate-css is the official v4-compatible replacement for animations, required by shadcn/ui components.

Reference : https://ui.shadcn.com/docs/tailwind-v4

Tailwind v4 Plugins

Tailwind v4 supports official plugins using the @plugin directive in CSS.

Official Plugins (Tailwind Labs)

Typography Plugin - Style Markdown/CMS Content

When to use: Displaying blog posts, documentation, or any HTML from Markdown/CMS.

Installation:

pnpm add -D @tailwindcss/typography

Configuration (v4 syntax):

/* src/index.css */
@import "tailwindcss";
@plugin "@tailwindcss/typography";

Usage:

<article class="prose lg:prose-xl dark:prose-invert">
  {{ markdown_content }}
</article>

Available classes:

prose - Base typography styles
prose-sm, prose-base, prose-lg, prose-xl, prose-2xl - Size variants
dark:prose-invert - Dark mode styles

Forms Plugin - Reset Form Element Styles

When to use: Building custom forms without shadcn/ui components, or need consistent cross-browser form styling.

Installation:

pnpm add -D @tailwindcss/forms

Configuration (v4 syntax):

/* src/index.css */
@import "tailwindcss";
@plugin "@tailwindcss/forms";

What it does:

Resets browser default form styles
Makes form elements styleable with Tailwind utilities
Fixes cross-browser inconsistencies for inputs, selects, checkboxes, radios

Note: Less critical for shadcn/ui users (they have pre-styled form components), but still useful for basic forms.

Common Plugin Errors

These errors happen when using v3 syntax in v4 projects:

❌ WRONG (v3 config file syntax):

// tailwind.config.js
module.exports = {
  plugins: [require('@tailwindcss/typography')]
}

❌ WRONG (@import instead of @plugin):

@import "@tailwindcss/typography";  /* Doesn't work */

✅ CORRECT (v4 @plugin directive):

/* src/index.css */
@import "tailwindcss";
@plugin "@tailwindcss/typography";
@plugin "@tailwindcss/forms";

Built-in Features (No Plugin Needed)

Container queries are built into Tailwind v4 core - no plugin needed:

<div className="@container">
  <div className="@md:text-lg">
    Responds to container width, not viewport
  </div>
</div>

❌ Don't install: @tailwindcss/container-queries (deprecated, now core feature)

Reference Documentation

For deeper understanding, see:

architecture.md - Deep dive into the 4-step pattern
dark-mode.md - Complete dark mode implementation
common-gotchas.md - All the ways it can break (and fixes)
migration-guide.md - Migrating hardcoded colors to CSS variables

Official Documentation

shadcn/ui Vite Setup : https://ui.shadcn.com/docs/installation/vite
shadcn/ui Tailwind v4 Guide : https://ui.shadcn.com/docs/tailwind-v4
shadcn/ui Dark Mode (Vite) : https://ui.shadcn.com/docs/dark-mode/vite
Tailwind v4 Docs : https://tailwindcss.com/docs
shadcn/ui Theming : https://ui.shadcn.com/docs/theming

Production Example

This skill is based on the WordPress Auditor project:

Live : https://wordpress-auditor.webfonts.workers.dev
Stack : Vite + React 19 + Tailwind v4 + shadcn/ui + Cloudflare Workers
Dark Mode : Full system/light/dark support
Version : Tailwind v4.1.14 + shadcn/ui latest (Oct 2025)

All patterns in this skill have been validated in production.

Questions? Issues?

Check reference/common-gotchas.md first
Verify all steps in the 4-step architecture
Ensure components.json has "config": ""
Delete tailwind.config.ts if it exists
Check official docs: https://ui.shadcn.com/docs/tailwind-v4

Weekly Installs

Repository

ovachiever/droid-tings

GitHub Stars

First Seen

Jan 20, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykPass

Installed on

gemini-cli57

opencode57

codex54

claude-code52

cursor51

github-copilot50

前端开发AI工具 | 5大专业能力构建生产级前端页面 | 设计工程与动效系统

759 周安装

Usecn() for conditional classes

import { cn } from "@/lib/utils" <div className={cn("base", isActive && "active")} />

Usedark: variants for semantic colors

/* WRONG */ <div className="bg-primary dark:bg-primary-dark" />

Colors wrapped with hsl()

@theme inline maps all variables

@layer base uses unwrapped variables

Theme provider installed and wrapping app

Dark mode toggle component created

Test theme switching works in browser