tailwind-design-system

Tailwind CSS 与 shadcn/ui 设计系统

概述

使用 Tailwind CSS（v4.1+）和 shadcn/ui 创建并管理集中式设计系统的专家指南。本技能提供结构化工作流，用于定义设计令牌、使用 CSS 变量配置主题，以及基于 shadcn/ui 基础组件构建一致的 UI 组件库。

与其他技能的关系：

• tailwind-css-patterns 涵盖实用工具优先的样式设计、响应式设计和 Tailwind CSS 的一般用法
• shadcn-ui 涵盖单个组件的安装、配置和实现
• 本技能 专注于系统级编排：设计令牌、主题基础设施、组件封装模式，以及确保整个应用的一致性

使用时机

• 从零开始，使用 Tailwind CSS 和 shadcn/ui 搭建设计系统
• 将设计令牌（颜色、排版、间距、圆角、阴影）定义为 CSS 变量
• 使用集中式主题系统（浅色／深色模式）配置 globals.css
• 将 shadcn/ui 组件封装为设计系统基础组件，并强制执行约束
• 构建由令牌驱动的组件库，以确保 UI 一致
• 从基于 JavaScript 的 Tailwind 配置迁移到 CSS 优先配置（v4.1+）
• 使用 oklch 格式建立具有感知均匀性的调色板
• 创建浅色／深色模式之外的多主题支持（例如品牌主题）

说明

步骤 1：初始化设计系统配置

运行以下命令设置项目：

# Check if Tailwind is installed
npx tailwindcss --version

# For Tailwind v4 (recommended)
npx @tailwindcss/vite@latest init   # or: npm install -D tailwindcss @tailwindcss/vite

# Initialize shadcn/ui CLI
npx shadcn@latest init

# Install core shadcn/ui components
npx shadcn@latest add button card input -y

验证检查点：设置完成后，使用以下命令进行验证：

ls src/components/ui/        # Should list installed components
cat src/app/globals.css       # Should contain @tailwind directives

步骤 2：定义设计令牌

在 src/app/globals.css 中创建设计令牌：

@tailwind base;
@tailwind components;
@tailwind utilities;

@layer base {
  :root {
    /* Brand Colors */
    --primary: oklch(0.55 0.18 250);
    --primary-foreground: oklch(0.985 0 0);

    /* Semantic Colors */
    --background: oklch(0.99 0 0);
    --foreground: oklch(0.15 0 0);
    --secondary: oklch(0.96 0.01 250);
    --secondary-foreground: oklch(0.20 0 0);

    /* Validation: all colors must have foreground pair */
    --destructive: oklch(0.55 0.22 25);
    --destructive-foreground: oklch(0.985 0 0);
  }

  .dark {
    --primary: oklch(0.65 0.20 250);
    --background: oklch(0.14 0 0);
    --foreground: oklch(0.97 0 0);
    --secondary: oklch(0.25 0.02 250);
  }
}

验证检查点：验证令牌是否为有效的 CSS：

grep -E "^[[:space:]]*--[a-z-]+:" src/app/globals.css | wc -l
# Should return count of defined tokens (e.g., 10+)

步骤 3：配置主题基础设施

将 CSS 变量映射到 Tailwind 实用工具（Tailwind v4.1+）：

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

在 components/providers/theme-provider.tsx 中添加深色模式类切换：

import { useEffect } from "react";
export function ThemeProvider({ children }: { children: React.ReactNode }) {
  useEffect(() => {
    const isDark = window.matchMedia("(prefers-color-scheme: dark)").matches;
    document.documentElement.classList.toggle("dark", isDark);
  }, []);
  return <>{children}</>;
}

验证检查点：测试深色模式：

document.documentElement.classList.contains("dark") // in browser console

步骤 4：封装 shadcn/ui 组件

创建 src/components/ds/Button.tsx：

import { Button as ShadcnButton } from "@/components/ui/button";

type DSVariant = "primary" | "secondary" | "destructive" | "ghost";
const variantMap: Record<DSVariant, "default" | "secondary" | "destructive" | "ghost"> = {
  primary: "default", secondary: "secondary",
  destructive: "destructive", ghost: "ghost",
};

export function Button({ variant = "primary", ...props }: { variant?: DSVariant } & React.ComponentProps<typeof ShadcnButton>) {
  return <ShadcnButton variant={variantMap[variant]} {...props} />;
}

验证检查点：验证构建是否通过：

npx tsc --noEmit src/components/ds/Button.tsx

步骤 5：验证并编写文档

运行令牌验证脚本：

REQUIRED=("primary" "primary-foreground" "background" "foreground" "secondary" "secondary-foreground")
for token in "${REQUIRED[@]}"; do
  grep -q "$token:" src/app/globals.css || echo "MISSING: --$token"
done

验证检查点：确保所有 shadcn 组件都使用 DS 令牌：

grep -r "bg-primary\|text-primary\|bg-background" src/components/ds/

示例

添加自定义令牌

在 globals.css 中扩展基础令牌：

:root {
  --warning: oklch(0.84 0.16 84);
  --warning-foreground: oklch(0.28 0.07 46);
}

.dark {
  --warning: oklch(0.41 0.11 46);
  --warning-foreground: oklch(0.99 0.02 95);
}

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

用法：<div className="bg-warning text-warning-foreground">Warning</div>

将 shadcn/ui 组件封装为设计系统基础组件

请参阅 references/component-wrapping.md，查看包含 Button、Text 和 Stack 基础组件及完整 TypeScript 类型的示例。

创建受约束的设计系统组件，强制使用令牌。 行内示例：

import { Button as ShadcnButton } from "@/components/ui/button";

export function Button({ variant = "primary", size = "md", ...props }) {
  const variantMap = { primary: "default", secondary: "secondary" };
  const sizeMap = { sm: "sm", md: "default", lg: "lg" };
  return (
    <ShadcnButton
      variant={variantMap[variant]}
      size={sizeMap[size]}
      {...props}
    />
  );
}

多主题支持

对于需要浅色／深色模式之外的多个品牌主题的应用：

[data-theme="ocean"] {
  --primary: oklch(0.55 0.18 230);
  --primary-foreground: oklch(0.985 0 0);
}

[data-theme="forest"] {
  --primary: oklch(0.50 0.15 145);
  --primary-foreground: oklch(0.985 0 0);
}

const [theme, setTheme] = useState("light");
useEffect(() => {
  document.documentElement.setAttribute("data-theme", theme);
}, [theme]);

设计令牌验证

验证是否已定义所有必需令牌：

#!/bin/bash
REQUIRED=("--background" "--foreground" "--primary" "--primary-foreground")
for token in "${REQUIRED[@]}"; do
  grep -q "$token:" src/styles/globals.css || echo "Missing: $token"
done

约束和警告

• oklch 颜色格式：使用 oklch 实现感知均匀性。并非所有浏览器都原生支持 oklch；如果面向较旧的浏览器，请检查兼容性
• 令牌命名：遵循 shadcn/ui 约定（--primary、--primary-foreground），以实现无缝集成
• @theme inline 与 @theme：将 CSS 变量映射到 Tailwind 工具类时使用 @theme inline；直接定义令牌时使用 @theme
• 组件封装：保持包装组件轻量。只添加用于强制执行设计系统规则的约束；避免重复 shadcn/ui 的逻辑
• 深色模式：始终在 :root 中为每个令牌定义深色模式值。缺少深色令牌会导致视觉回归
• CSS 变量作用域：在 :root 中定义的令牌是全局的。使用 [data-theme] 选择器实现互不冲突的多主题
• 性能：避免过多的 CSS 自定义属性链。每次 var() 查找都会带来少量但不可忽略的开销
• Tailwind v4 与 v3：@theme 指令和 @theme inline 是 v4.1+ 功能。对于 v3 项目，请使用 tailwind.config.js 中的 theme.extend

最佳实践

1. 单一事实来源：所有设计令牌都放在 globals.css 中。切勿在组件中硬编码颜色值
2. 语义化命名：使用基于用途的名称（--primary、--destructive），而非基于外观的名称（--blue-500、--red-600）
3. 前景色配对：每个背景令牌都必须有对应的 -foreground 令牌，以满足对比度要求
4. 令牌比例：为自定义调色板定义完整的比例（50-950），以提供灵活性
5. 组件集中导出：从单个 index.ts 导出所有 DS 组件，便于导入
6. 无障碍性：确保所有令牌对（背景色/前景色）均符合 WCAG AA 对比度标准（正文文本为 4.5:1，大号文本为 3:1）
7. 记录令牌：为团队维护所有令牌的可视化参考
8. 间距一致：通过 DS 组件使用 Tailwind 的间距比例（gap-2、gap-4、gap-6），而非任意值

参考资料

• Tailwind CSS v4 主题配置：https://tailwindcss.com/docs/theme
• Tailwind CSS 函数和指令：https://tailwindcss.com/docs/functions-and-directives
• shadcn/ui 主题指南：https://ui.shadcn.com/docs/theming
• shadcn/ui 安装（手动）：https://ui.shadcn.com/docs/installation/manual
• oklch 色彩空间：https://oklch.com