tailwind-design-system

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Tailwind CSS & shadcn/ui Design System

Tailwind CSS & shadcn/ui 设计系统

Overview

概述

Expert guide for creating and managing a centralized Design System using Tailwind CSS (v4.1+) and shadcn/ui. This skill provides structured workflows for defining design tokens, configuring themes with CSS variables, and building a consistent UI component library based on shadcn/ui primitives.

Relationship with other skills:

tailwind-css-patterns covers utility-first styling, responsive design, and general Tailwind CSS usage
shadcn-ui covers individual component installation, configuration, and implementation
This skill focuses on the system-level orchestration: design tokens, theming infrastructure, component wrapping patterns, and ensuring consistency across the entire application

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

与其他Skill的关联：

tailwind-css-patterns 涵盖实用优先的样式设计、响应式设计及Tailwind CSS的通用用法
shadcn-ui 涵盖单个组件的安装、配置与实现
本Skill 聚焦于系统层面的编排：设计令牌、主题基础设施、组件封装模式，以及确保整个应用的一致性

When to Use

适用场景

Setting up a new design system from scratch with Tailwind CSS and shadcn/ui
Defining design tokens (colors, typography, spacing, radius, shadows) as CSS variables
Configuring
```
globals.css
```
with a centralized theming system (light/dark mode)
Wrapping shadcn/ui components into design system primitives with enforced constraints
Building a token-driven component library for consistent UI
Migrating from a JavaScript-based Tailwind config to CSS-first configuration (v4.1+)
Establishing color palettes with oklch format for perceptual uniformity
Creating multi-theme support beyond light/dark (e.g., brand themes)

使用Tailwind CSS和shadcn/ui从零搭建新的设计系统
将设计令牌（颜色、排版、间距、圆角、阴影）定义为CSS变量
为
```
globals.css
```
配置集中式主题系统（亮色/暗色模式）
将shadcn/ui组件封装为带有强制约束的设计系统基础组件
构建由令牌驱动的组件库以实现UI一致性
从基于JavaScript的Tailwind配置迁移至CSS优先的配置（v4.1+）
使用oklch格式建立色彩调色板以实现感知一致性
创建超越亮色/暗色的多主题支持（如品牌主题）

Instructions

操作步骤

Step 1: Initialize Design System Configuration

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

Assess the project: Check if Tailwind CSS and shadcn/ui are already installed
Create the globals.css: Set up the central CSS file with design tokens
Configure Tailwind: Use the
```
@theme
```
directive (v4.1+) or
```
tailwind.config.js
```
(v3)
Install shadcn/ui: Initialize with the CLI and configure the theme

项目评估：检查是否已安装Tailwind CSS和shadcn/ui
创建globals.css：建立包含设计令牌的核心CSS文件
配置Tailwind：使用
```
@theme
```
指令（v4.1+）或
```
tailwind.config.js
```
（v3版本）
安装shadcn/ui：通过CLI初始化并配置主题

Step 2: Define Design Tokens

步骤2：定义设计令牌

Design tokens are the foundation. Define them as CSS custom properties in

globals.css

Colors: Brand palette, semantic colors, surface colors
Typography: Font families, sizes, weights, line heights
Spacing: Consistent spacing scale
Borders: Radius, widths
Shadows: Elevation levels
Animations: Transition durations and easing functions

设计令牌是基础。在

globals.css

中将它们定义为CSS自定义属性：

颜色：品牌调色板、语义化颜色、表面颜色
排版：字体族、字号、字重、行高
间距：一致性间距比例
边框：圆角、边框宽度
阴影：层级阴影
动画：过渡时长与缓动函数

Step 3: Configure Theming Infrastructure

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

Set up light/dark mode support and expose tokens to Tailwind via

@theme inline

设置亮色/暗色模式支持，并通过

@theme inline

将令牌暴露给Tailwind。

Step 4: Wrap shadcn/ui Components

步骤4：封装shadcn/ui组件

Create design system primitives that enforce token usage and provide consistent API.

创建能强制使用令牌并提供一致API的设计系统基础组件。

Step 5: Document and Validate

步骤5：文档与验证

Create a living style guide and validate token usage across the codebase.

创建动态样式指南，并验证令牌在整个代码库中的使用情况。

Examples

示例

Complete globals.css with Design Tokens

包含设计令牌的完整globals.css

See

references/globals.css.example

for a complete, production-ready

globals.css

with all design tokens configured.

Quick example for adding custom tokens:

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);
}

Usage:

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

查看

references/globals.css.example

获取包含所有配置好的设计令牌的完整生产级

globals.css

。

添加自定义令牌的快速示例：

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>

Wrapping shadcn/ui Components as Design System Primitives

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

Create constrained design system components that enforce token usage. See

references/component-wrapping.md

for complete examples including Button, Text, and Stack primitives.

Quick example:

tsx

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}
    />
  );
}

创建带有约束的设计系统组件，强制使用令牌。查看

references/component-wrapping.md

获取包括Button、Text和Stack基础组件在内的完整示例。

快速示例：

tsx

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}
    />
  );
}

Multi-Theme Support

多主题支持

For applications requiring multiple brand themes beyond light/dark:

css

[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);
}

tsx

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

对于需要超越亮色/暗色的多品牌主题的应用：

css

[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);
}

tsx

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

Design Token Validation

设计令牌验证

Verify all required tokens are defined:

bash

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

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

bash

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

Constraints and Warnings

约束与注意事项

oklch color format: Use oklch for perceptual uniformity. Not all browsers support oklch natively; check compatibility if targeting older browsers
Token naming: Follow the shadcn/ui convention (
```
--primary
```
,
```
--primary-foreground
```
) for seamless integration
@theme inline vs @theme: Use
```
@theme inline
```
when bridging CSS variables to Tailwind utilities; use
```
@theme
```
for direct token definition
Component wrapping: Keep wrapper components thin. Only add constraints that enforce design system rules; avoid duplicating shadcn/ui logic
Dark mode: Always define dark mode values for every token in
```
:root
```
. Missing dark tokens cause visual regressions
CSS variable scoping: Tokens defined in
```
:root
```
are global. Use
```
[data-theme]
```
selectors for multi-theme without conflicts
Performance: Avoid excessive CSS custom property chains. Each
```
var()
```
lookup adds minimal but non-zero overhead
Tailwind v4 vs v3: The
```
@theme
```
directive and
```
@theme inline
```
are v4.1+ features. For v3 projects, use
```
tailwind.config.js
```
with
```
theme.extend
```

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

Best Practices

最佳实践

Single source of truth: All design tokens live in
```
globals.css
```
. Never hardcode color values in components
Semantic naming: Use purpose-based names (
```
--primary
```
,
```
--destructive
```
) not appearance-based (
```
--blue-500
```
,
```
--red-600
```
)
Foreground pairing: Every background token must have a matching
```
-foreground
```
token for contrast compliance
Token scale: Define a complete scale for custom palettes (50-950) to provide flexibility
Component barrel exports: Export all DS components from a single
```
index.ts
```
for clean imports
Accessibility: Ensure all token pairs (background/foreground) meet WCAG AA contrast (4.5:1 for text, 3:1 for large text)
Document tokens: Maintain a visual reference of all tokens for the team
Consistent spacing: Use Tailwind's spacing scale (
```
gap-2
```
,
```
gap-4
```
,
```
gap-6
```
) through DS components rather than arbitrary values

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

References

参考资料

Tailwind CSS v4 Theme Configuration: https://tailwindcss.com/docs/theme
Tailwind CSS Functions and Directives: https://tailwindcss.com/docs/functions-and-directives
shadcn/ui Theming Guide: https://ui.shadcn.com/docs/theming
shadcn/ui Installation (Manual): https://ui.shadcn.com/docs/installation/manual
oklch Color Space: https://oklch.com

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