tailwind-design-system

Tailwind Design System（v4）用于借助 Tailwind CSS v4 构建生产级设计系统，涉及 CSS-first 配置、设计令牌、组件变体、响应式模式与可访问性。资料说明该技能面向 Tailwind CSS v4（2024 及以后版本）；若项目使用 v3，需参考升级指南。

适用场景

• 使用 Tailwind v4 创建组件库
• 通过 CSS-first 配置实现设计令牌与主题
• 构建响应式且可访问的组件
• 在代码库中标准化 UI 模式
• 从 Tailwind v3 迁移到 v4
• 使用原生 CSS 特性设置暗色模式

v4 关键变化 资料以对照表列出若干变化：tailwind.config.ts 改为 CSS 中的 @theme；@tailwind base/components/utilities 改为 @import "tailwindcss"；darkMode: "class" 改为 @custom-variant dark (&:where(.dark, .dark *))；theme.extend.colors 改为 @theme { --color-*: value }；require("tailwindcss-animate") 改为在 @theme 中写 CSS @keyframes 并用 @starting-style 处理进入动画。

快速开始（CSS-first 配置） 示例在 app.css 中先 @import "tailwindcss"，再用 @theme 定义语义化颜色令牌（如 --color-background、--color-foreground、--color-primary、--color-secondary、--color-muted、--color-accent、--color-destructive、--color-border、--color-ring、--color-card、--color-ring-offset 等，使用 OKLCH 色彩空间），并定义半径令牌 --radius-sm/md/lg/xl 与动画令牌 --animate-fade-in、--animate-fade-out、--animate-slide-in、--animate-slide-out 及对应 @keyframes。随后以 @custom-variant dark 声明基于类的暗色模式，在 .dark 中覆盖颜色令牌，并在 @layer base 中设置基础样式。

核心概念

• 设计令牌层级：品牌令牌（抽象）→ 语义令牌（用途）→ 组件令牌（具体）。示例：oklch(45% 0.2 260) → --color-primary → bg-primary。
• 组件架构：基础样式 → 变体 → 尺寸 → 状态 → 覆盖。

主要模式

1. CVA（Class Variance Authority）组件：以 Button 为例，使用 cva 定义基础样式与 variant（default、destructive、outline、secondary、ghost、link）、size（default、sm、lg、icon）及默认变体，配合 Radix Slot 支持 asChild。示例注明 React 19 无需 forwardRef，ref 可直接作为 prop。
2. 复合组件：以 Card 为例，导出 Card、CardHeader、CardTitle、CardDescription、CardContent、CardFooter，同样适配 React 19 的 ref 用法。
3. 表单组件：Input 支持 error 属性，输出 aria-invalid 与 aria-describedby，并以 role="alert" 显示错误；Label 使用 cva。示例结合 React Hook Form 与 Zod 做登录表单校验。
4. 响应式 Grid 系统：Grid 通过 cva 提供 cols（1–6）与 gap（none/sm/md/lg/xl）变体；Container 提供 sm/md/lg/xl/2xl/full 尺寸变体，并给出使用示例。
5. 原生 CSS 动画（v4）：在 @theme 中定义 --animate-dialog-in/out 及 @keyframes，并演示使用原生 [popover]、@starting-style 与 allow-discrete 的过渡；Dialog 组件结合 Radix Dialog 使用 data-[state=open] 等动画类。
6. 暗色模式（v4）：提供简化版 ThemeProvider，支持 'dark' | 'light' | 'system'，包含 setTheme 与 resolvedTheme，示例在 useEffect 中读取 localStorage（资料在代码处截断，后续内容未完整给出）。

限制与未提供信息 资料未给出安装命令、依赖清单、价格或收费信息、支持平台、性能或效果数据；上述内容均未提供，不应视为已有事实。