设计系统实践指南

本文是「设计系统与 Tailwind CSS 深度实践」系列的导航与总结文档。

---

系列文档导航

序号	话题	核心内容
01	设计系统-01-Design-Token核心概念与分层哲学	Token 本质、三层分层、命名基础
02	设计系统-02-Tailwind-CSS设计哲学与深度定制	Utility-First、Config 深度定制
03	设计系统-03-技术选型对比与取舍	Tailwind vs CSS-in-JS vs CSS Modules
04	设计系统-04-多主题与暗黑模式最佳实践	暗黑模式、多品牌、CSS 变量方案
05	设计系统-05-工程化落地方案	Style Dictionary、Monorepo 架构
06	设计系统-06-命名规范深度探讨	命名流派、最佳实践、完整规范

---

核心架构一图流

┌─────────────────────────────────────────────────────────────────┐
│                        设计系统架构                               │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│   ┌─────────────┐    ┌─────────────┐    ┌─────────────┐        │
│   │  Primitive  │───▶│  Semantic   │───▶│  Component  │        │
│   │   Tokens    │    │   Tokens    │    │   Tokens    │        │
│   │             │    │             │    │  (可选)     │        │
│   │  blue-500   │    │ bg-primary  │    │ btn-bg-hover│        │
│   └─────────────┘    └──────┬──────┘    └─────────────┘        │
│                             │                                    │
│                             ▼                                    │
│   ┌─────────────────────────────────────────────────────────┐  │
│   │                   CSS 变量层                              │  │
│   │  :root { --color-primary: 59 130 246 }                  │  │
│   │  .dark { --color-primary: 96 165 250 }                  │  │
│   └─────────────────────────┬───────────────────────────────┘  │
│                             │                                    │
│                             ▼                                    │
│   ┌─────────────────────────────────────────────────────────┐  │
│   │                 tailwind.config.js                       │  │
│   │  primary: 'rgb(var(--color-primary) / <alpha-value>)'   │  │
│   └─────────────────────────┬───────────────────────────────┘  │
│                             │                                    │
│                             ▼                                    │
│   ┌─────────────────────────────────────────────────────────┐  │
│   │                    组件代码                               │  │
│   │  <button className="bg-primary text-primary-foreground"> │  │
│   └─────────────────────────────────────────────────────────┘  │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

---

关键决策速查

技术选型

决策点	推荐方案	相关文档
CSS 方案	Tailwind CSS	设计系统-03-技术选型对比与取舍
Token 分层	Primitive + Semantic 两层	设计系统-01-Design-Token核心概念与分层哲学
暗黑模式	CSS 变量 + class 切换	设计系统-04-多主题与暗黑模式最佳实践
构建工具	Phase 1: 直接 TS / Phase 2: Style Dictionary	设计系统-05-工程化落地方案

命名规范

层级	命名策略	示例	相关文档
Primitive	数值型	blue-500, space-4	设计系统-06-命名规范深度探讨
Semantic	语义型	bg-primary, text-muted	设计系统-06-命名规范深度探讨

Tailwind 配置

配置项	推荐做法	相关文档
darkMode	'class'	设计系统-04-多主题与暗黑模式最佳实践
theme.colors	覆盖（非 extend）	设计系统-02-Tailwind-CSS设计哲学与深度定制
颜色格式	RGB（支持透明度）	设计系统-04-多主题与暗黑模式最佳实践

---

文件结构参考

Phase 1：简单启动

src/
├── tokens/
│   ├── index.ts           # 统一导出
│   ├── colors.ts          # Primitive 颜色
│   ├── spacing.ts         # 间距刻度
│   └── semantic.ts        # 语义 Token
├── styles/
│   └── globals.css        # CSS 变量（Light/Dark）
├── hooks/
│   └── useTheme.ts        # 主题切换
└── tailwind.config.ts

详见 设计系统-05-工程化落地方案

Phase 2：Monorepo 架构

packages/
├── tokens/                # Token 包
│   ├── src/*.json
│   └── style-dictionary.config.js
├── ui/                    # 组件库
│   └── tailwind.config.js
└── apps/                  # 应用

详见 设计系统-05-工程化落地方案

---

常用代码片段

CSS 变量定义

:root {
  --color-bg: 255 255 255;
  --color-text: 17 24 39;
  --color-primary: 59 130 246;
}

.dark {
  --color-bg: 15 23 42;
  --color-text: 248 250 252;
  --color-primary: 96 165 250;
}

完整示例见 设计系统-04-多主题与暗黑模式最佳实践

Tailwind 配置

module.exports = {
  darkMode: 'class',
  theme: {
    colors: {
      background: 'rgb(var(--color-bg) / <alpha-value>)',
      foreground: 'rgb(var(--color-text) / <alpha-value>)',
      primary: {
        DEFAULT: 'rgb(var(--color-primary) / <alpha-value>)',
        foreground: 'rgb(var(--color-primary-foreground) / <alpha-value>)',
      },
    }
  }
}

完整配置见 设计系统-02-Tailwind-CSS设计哲学与深度定制

主题切换 Hook

const { theme, setTheme } = useTheme();
// theme: 'light' | 'dark' | 'system'

完整实现见 设计系统-04-多主题与暗黑模式最佳实践

---

学习路径建议

快速上手（1-2 小时）

1. 阅读 设计系统-01-Design-Token核心概念与分层哲学
2. 复制 设计系统-02-Tailwind-CSS设计哲学与深度定制
3. 实现 设计系统-04-多主题与暗黑模式最佳实践

深入理解（半天）

1. 完整阅读 设计系统-01-Design-Token核心概念与分层哲学
2. 对比 设计系统-03-技术选型对比与取舍 中的方案
3. 学习 设计系统-06-命名规范深度探讨

工程化进阶（按需）

1. 研究 设计系统-05-工程化落地方案
2. 搭建 设计系统-05-工程化落地方案

---

相关资源

官方文档

• Tailwind CSS 官方文档
• Style Dictionary 文档
• Tokens Studio for Figma

推荐组件库

• shadcn/ui - 基于 Tailwind 的组件集合
• Radix UI - 无样式基础组件

设计系统参考

• Tailwind UI
• Vercel Design

---

文档更新记录

日期	更新内容
2026-02-02	初始版本，完成 6 个话题文档

---

#设计系统 #Tailwind #DesignToken #前端架构