# 使用 Tailwind CSS 进行样式设置使用 Tailwind CSS v4 实用程序类和 shadcn/ui 组件模式构建可访问的 UI。 **Tailwind v4 仅使用 CSS 优先配置 - 切勿创建或修改`tailwind.config.js`/`tailwind.config.ts`。** 支持 Radix UI（默认）或 Base UI 作为原始库。 ## 关键规则 ### 没有 `tailwind.config.js` \- 仅 CSS-First Tailwind v4 在 CSS 中配置所有内容。迁移任何 JS/TS 配置： * `theme.extend.colors` → `@theme { --color-*: ... }` * `plugins` → `@plugin "..."` 或 `@utility` * `内容` → `@source "..."` * `tailwindcss-animate` → `@import "tw-animate-css"` * `@layer utility` → `@utility name { ... }` ### 始终使用语义颜色标记 // 正确 - 尊重主题和深色模式

// 错误 - 破坏主题

始终将“bg-*”与“text-*-foreground”配对。在 [theming.md]() 中扩展 success/warning/info。 ### 永远不要动态构建类名 // 错误 - 破坏 Tailwind 扫描仪

// 正确 - 通过查找完成字符串 const colorMap = { 红色：“bg-red-500”，蓝色：“bg-blue-500” } as const

### cn() 合并顺序默认优先，消费者 `className` 最后（顺风合并最后获胜）： className={cn(buttonVariants({variant, size }), className)} // 正确 className={cn(className, buttonVariants({variant, size }))} // 错误 ### 动画表演 // 错误 - 全部转换会导致布局抖动

// 正确 - 仅转换发生变化的部分

// 正确 - 尊重减少的运动

### `@theme` 与 `@theme inline` * `@theme` \- 静态标记，可被插件覆盖 * `@theme inline` \- 引用 CSS 变量，遵循暗模式更改 @主题{ --color-brand: oklch(0.6 0.2 250); } /* 静态 */ @主题内联{ --color-primary: var(--primary); } /* 动态 */ 有关更多陷阱，请参阅 [components.md]()，有关颜色系统参考，请参阅 [theming.md]()。 ## 核心模式 ### 用于主题化的 CSS 变量 shadcn/ui 使用映射到 Tailwind 实用程序的语义 CSS 变量： /* globals.css - 灯光模式 */ ：根{ --背景：oklch(1 0 0); --前景：oklch(0.145 0 0); --主要：oklch(0.205 0 0); --主要前景：oklch(0.985 0 0); --静音：oklch(0.97 0 0); --静音前景：oklch(0.556 0 0); --边框：oklch(0.922 0 0); --半径：0.5rem； } /* 深色模式 */ .暗{ --背景：oklch(0.145 0 0); --前景：oklch(0.985 0 0); --主要：oklch(0.922 0 0); --主要前景：oklch(0.205 0 0); } /* Tailwind v4: 映射变量 */ @主题内联{ --颜色背景：var(--背景); --前景颜色：var(--前景); --颜色主色：var(--primary); } **在组件中的使用：** // 背景颜色省略“-background”后缀

### 组件创作模式组件使用带有“data-slot”属性的普通函数（React 19 - 没有“forwardRef”）：从“类方差权威”导入 { cva, type VariantProps } 从“@/lib/utils”导入 { cn } const 按钮变体 = cva( “内联柔性项目中心对齐中心间隙-2圆形-md文本-sm字体-中过渡颜色焦点可见：轮廓-无焦点可见：环-1禁用：指针事件-无禁用：opacity-50”， { 变体：{ 变体：{ 默认值：“bg-primary text-primary-foreground 阴影悬停：bg-primary/90”，破坏性：“bg-破坏性文本-破坏性-前景悬停：bg-破坏性/ 90”，大纲：“边框边框-输入bg-背景悬停：bg-accent”，幽灵：“悬停：背景重音悬停：文本重音前景”，链接：“文本主下划线偏移-4悬停：下划线”， }, 尺寸：{ 默认值：“h-9 px-4 py-2”， sm: "h-8 px-3 文本-xs", lg：“h-10 px-8”，图标：“尺寸-9”， }, }, defaultVariants: { 变体: "默认", 大小: "默认" }, } ） // 使用 React.ComponentProps 的普通函数（不是forwardRef）功能按钮({ 类名, 变体，尺寸， ...道具 }: React.ComponentProps<"button"> & VariantProps) { 返回（ <按钮数据槽=“按钮” className={cn(buttonVariants({ 变体, 大小, className }))} {...道具} /> ） } // 用法点击我 **图标间距与`data-icon`:** <按钮> 生成... <按钮> 保存更改 ### 响应式设计移动优先断点： // 在移动设备上堆叠，在平板电脑+上网格

// 在手机上隐藏

// 每个断点有不同的布局

// 响应文本大小

### 容器查询 Tailwind v4 中一流，无需插件：

响应容器宽度，而不是视口

// 命名容器

### 深色模式 // 使用 dark: 前缀 - 但更喜欢语义颜色而不是手动 dark: 覆盖
// 自动深色模式
// 手动覆盖 // 使用下一个主题进行切换：useTheme() → setTheme("dark" | "light") // 总是在中添加suppressHydrationWarning以防止闪现 ## 常见组件模式 ### 卡

标题

描述

内容

页脚

### 表单字段
电子邮件 <输入类型=“电子邮件” className =“flex h-9 w-full rounded-md border border-input bg-transparent px-3 py-1 text-sm Shadow-sm transition-colors placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring禁用:光标不允许禁用:opacity-50” />
帮助文本

### 徽章常量徽章变体 = cva( “inline-flex items-center rounded-md border px-2.5 py-0.5 text-xs font-semibold 过渡颜色”， { 变体：{ 变体：{ 默认值：“边框-透明背景-主要文本-主要-前景阴影”， secondary: "边框透明背景-辅助文本-辅助-前景", 破坏性的：“边框透明背景破坏性文本破坏性前景”，大纲：“文本前景”， }, }, } ） ## 布局模式 ### 居中布局

{/* 内容 */}

### 侧边栏布局

侧边栏

内容

### 仪表板网格
宽卡 <卡>常规 <卡>常规全宽
## 辅助功能模式 ### 焦点可见

沙顺顺风

包含技能