第一章. 架构师的开篇：从组件库到设计系统

本章的核心目标是建立一个统一且深刻的认知框架。我们将要构建的，并非一个简单的 UI 组件集合，而是一个能够提升团队生产力、保障产品体验一致性、并作为公司数字产品核心资产的系统性工程解决方案。我们将首先精确定义“设计系统”的内涵与外延，深入分析其技术选型背后的逻辑，并最终构建一个标准化的、自动化的工程开发环境。这是后续所有高级实践的坚实基础。

1.1. 超越组件库：什么是“设计系统”？

在启动任何具体的编码工作之前，首要任务是校准我们对目标的理解。许多技术团队投入资源构建了内部的组件库，却发现随着业务扩张，产品不同模块间的视觉差异依旧越来越大，代码冗余度不降反升，设计与开发之间的协作鸿沟难以逾越。

这些问题的根源在于，一个孤立的、缺乏顶层设计与治理规范的组件库，其本质上仍是一个被动的工具集。而我们的目标，是构建一个更高维度的、主动的、具备自我演进能力的产物——设计系统。它是一种思想、一套流程和一个工程产品的有机结合体。

问题背景的深度剖析:
在一个高速发展且有一定规模的组织中，缺少设计系统所引发的问题是系统性的，并会随着时间推移被急剧放大。例如，市场部门为一次营销活动快速搭建的着陆页，其视觉风格、交互模式与主应用存在明显割裂，这不仅稀释了品牌形象，也增加了用户的认知负荷。在开发层面，不同业务线的团队可能基于不同的技术栈或 UI 理解，重复“发明轮子”，分别实现了功能类似的日期选择器或数据表格，导致了巨大的研发资源浪费和后续高昂的维护成本。当产品需要进行品牌升级，要求全局性地调整主色调和字体规范时，这项任务会演变成一场灾难性的、涉及多个代码仓库的、高风险的“替换工程”。

设计系统正是为了从根本上解决这一系列混乱而诞生的结构性解决方案。它将设计决策转化为可复用、可约束、可治理的工程资产，从而解放生产力。

1.1.1. 剖析设计系统的三大支柱

一个功能完备、可持续发展的设计系统，由三个相互支撑、紧密协作的核心支柱构成：设计语言、组件库、以及模式与文档。

首先，设计语言 是整个系统的理论基础与最高纲领。它是一套用于指导产品设计与开发的、体系化的、抽象的规则与美学愿景的集合。其核心是 设计原则，例如“清晰”、“高效”、“一致”等高阶准则，它们是进行具体设计决策时的重要依据。原则之下是更具体的 设计规范，例如无障碍可访问性规范(WCAG)、8 点栅格系统、动画缓动曲线定义等。而将这一切与工程实现连接起来的关键，是 设计令牌 (Design Tokens)。设计令牌是以平台无关的、结构化的变量形式存在的样式定义，是所有视觉表现的单一数据源。例如，一个颜色令牌可能被定义为 color.brand.primary.default，其值为 #007BFF。这种结构化的命名使其具备极高的可读性和可维护性。

其次，组件库 是设计语言在代码层面的具象化、标准化实现。它是一套封装了样式、交互逻辑与状态管理的、经过完整测试的、可重用的用户界面工程实体。开发者通过调用这些标准化的组件来高效地构建应用界面。一个高质量的组件库不仅要实现设计稿的视觉效果，更要关注其工程属性。这包括提供设计精良的 API，在易用性与灵活性之间取得平衡；包含完备的 测试套件，覆盖单元、集成和视觉回归测试，以保证其健壮性；以及严格遵循 无障碍标准，确保所有用户都能无障碍地使用。

最后，模式与文档 是连接理论与实践、指导团队成员规模化应用设计系统的规范性文件与最佳实践的集合。它扮演着知识库和使用手册的角色，确保系统能够在团队中被正确理解和高效应用。其内容远超基础的组件 API 文档，核心在于沉淀 使用模式。例如，一个“用户认证模式”会详细规定登录和注册表单的整体布局、所需组件（Input, Button, Checkbox）、错误提示的展示方式、加载状态的处理逻辑等，为开发者提供可直接复用的“解决方案级”指引。此外，它还应包含 贡献与治理流程，明确新组件的提案、代码提交、版本发布以及组件废弃的管理办法，确保设计系统自身的健康演进。

为了更清晰地总结三者关系，我们可以参考下表：

1.1.2. 明确我们在课程中扮演的角色：开发者如何与设计师协作

在设计系统驱动的工作流中，开发者的角色定位发生了根本性的转变。开发者不再是设计流程下游的被动执行者，而是以系统共建者的身份，深度参与到从定义到实现的全过程。这种转变要求开发者具备更强的 工程产品化 思维和 跨职能协作 能力。

我们的工作不再是孤立地完成一个页面，而是为整个组织的开发者提供稳定、高效、易用的“开发工具”——组件库。这意味着我们需要对代码质量、API 设计、性能优化和测试覆盖率有更高的要求。同时，我们必须成为设计师最紧密的技术伙伴，将技术的可行性和工程的约束性前置到设计阶段。

以上对话清晰地展示了开发者在设计系统中的核心职责：我们不仅是实现者，更是 技术顾问，负责提供专业的技术可行性评估；是 API 设计师，负责定义组件的编程接口；也是 质量保证者，通过完备的测试和文档，确保交付产物的可靠性。我们深度参与并影响着设计系统的每一个环节，是确保其工程卓越性的关键角色。

1.1.3 本节小结

设计系统是一个由设计语言、组件库、模式与文档三大支柱构成的综合性工程解决方案，其核心目标是通过系统化的方法，解决规模化数字产品开发中的一致性、效率和质量问题。它要求开发者从传统的“功能实现者”转变为系统的“共建者”，深度参与规范制定、技术实现和基础设施维护，以产品化的思维打造高质量的工程资产。

1.2. 技术选型：为什么说 Radix + Tailwind v4 + daisyUI 是现代化的最佳实践？

技术选型并非简单地选择“流行”的工具，而是基于我们第一节所定义的目标——构建一个高度可定制、体验一致、易于维护的设计系统——所做出的审慎的、体系化的决策。我们将要采纳的 Radix + Tailwind v4 + daisyUI 技术栈，代表了一种与传统组件库截然不同的、兼顾了底层灵活性与上层开发效率的先进设计哲学。理解这种哲学上的差异，是理解我们整个课程架构的关键。

1.2.1. 对比分析：与 Ant Design, Material-UI 等传统组件库在设计哲学上的核心差异

业界存在大量成熟的组件库，如 Ant Design (AntD) 和 Material-UI (MUI)。这些库的共同特点是“开箱即用”，它们提供了一整套包含完整样式和交互逻辑的 UI 解决方案。这种模式被称为“All-in-One”或“Opinionated (强观点型)”方案。

• 传统方案的优势: 对于快速构建后台管理系统、内部工具或完全接纳其设计语言的项目而言，这类组件库的效率极高。它们预设了大量的设计细节，开发者无需过多关注 UI，即可快速搭建功能。

• 传统方案的局限性: 其核心问题在于 样式与逻辑的强耦合。当产品的品牌视觉需要高度定制化，与这些库的默认风格存在较大差异时，开发者便会陷入困境。为了覆盖原有样式，我们不得不编写大量“覆盖式”的 CSS，这通常意味着与复杂的 CSS 选择器权重作斗争，甚至滥用 !important，最终导致样式代码难以维护。主题定制功能虽然提供了一定灵活性，但其能力边界有限，无法满足深度的结构性或视觉性定制需求。

我们的目标是构建一个服务于特定品牌、具有独特视觉标识的设计系统，因此，样式的高度可控性是我们的首要考量。这就引出了我们所选择的“Unstyled (无样式)”或“Headless (无头)”范式。这种范式的核心思想，是将组件的 行为逻辑 与 视觉表现 彻底分离。

1.2.2. 深入 Radix UI：理解其“无头”特性如何提供极致的灵活性和一流的可访问性

Radix UI 是“无头”组件理念的最佳实践者之一。它并非一个传统意义上的组件库，而是一个专注于提供 行为、交互和可访问性 的底层 UI 原语的集合。

• 完全的样式控制权: Radix 组件在默认情况下不携带任何 CSS 样式。这意味着，一个 <Dialog.Trigger> 组件在渲染后，除了必要的交互行为外，其视觉表现与一个普通的 <button> 几乎无异。这赋予了我们 100%的样式控制权，我们可以使用任何偏好的样式方案来为其赋予任意的视觉外观，从根本上杜绝了“样式覆盖”的问题。

• 内建的、专业的无障碍可访问性 (a11y): 这是 Radix 最具价值的部分。构建一个真正具备完全可访问性的复杂组件（如下拉菜单、对话框）是一项极其复杂的工作，需要深入理解 WAI-ARIA 规范，处理键盘导航、焦点管理、状态宣告等诸多细节。Radix 为我们处理了所有这些复杂性。我们只需要组合其提供的原语，即可自动获得符合专业标准的、健壮的无障碍体验。

• 预置的复杂交互逻辑: 对于 DropdownMenu 或 Combobox 这类组件，Radix 已经内置了所有必需的状态管理逻辑（例如，菜单的展开/关闭状态）和交互逻辑（例如，点击外部区域自动关闭菜单）。

综上，我们选择 Radix UI 作为我们处理复杂组件 行为逻辑层 的武器。它为我们解决了构建组件过程中最困难的部分（行为逻辑与可访问性），同时将视觉样式完全交由我们掌控。

1.2.3. 拥抱 Tailwind CSS v4：探讨其作为设计系统基石的革命性优势

在拥有了处理行为逻辑的方案后，我们需要一套高效、可约束的样式方案。Tailwind CSS v4 带来了根本性的革新，使其成为与“无头”组件和设计系统理念完美结合的 样式基石。

• CSS 优先的配置与强制的设计约束: v4 版本最核心的变化，是用 CSS 原生的 @theme 指令取代了 tailwind.config.js 作为主题配置的主要方式。这个配置文件正是我们设计令牌 (Design Tokens) 的直接载体。开发者在编码时，只能从这些预设的、源于设计令牌的工具类中进行选择，从而在工具层面强制保证了视觉规范的统一实施。

  1 2 3 4 5 6 7

  /* app.css */ @import "tailwindcss"; @theme { --color-brand-500: oklch(0.637 0.237 25.331); --breakpoint-lg: 64rem; }

• 革命性的性能: v4 采用全新的高性能引擎，能将绝大部分项目的编译时间压缩至 100ms 以内。这种近乎实时的反馈速度，极大地提升了开发体验。

• 杜绝命名冲突与样式冗余: 通过组合原子化的工具类来构建样式，我们不再需要为各种小型组件编写 BEM 风格的类名，从而避免了命名困难和潜在的全局命名冲突。

• 极致的性能优化: Tailwind 能在生产环境构建时，通过扫描所有源码文件，精确地移除所有未被使用的 CSS 工具类，确保最终产出的 CSS 文件体积达到最小化。

1.2.4. 效率加速器：引入 daisyUI 简化组件样式

虽然 Tailwind 提供了极致的底层灵活性，但从零开始组合原子类来构建每一个组件依然是繁琐的。为了教学的简便性和开发的效率，我们引入 daisyUI 作为 Tailwind 之上的 组件样式封装层。

daisyUI 是一个基于 Tailwind CSS 的插件，它并不引入新的技术，而是提供了一套语义化的、预先设计好的组件类名。

• 从原子到组件: daisyUI 将常见的 Tailwind 原子类组合封装成了高级组件类。开发者可以直接使用 <button class="btn btn-primary"> 来代替冗长的原子类列表，大幅提升了开发速度。

• 深度主题化: 它内置了数十种主题，并提供了 primary, secondary, accent 等语义化的颜色名称。这些颜色与 Tailwind v4 的主题系统无缝集成，可以轻松实现一键换肤。

• 无缝的定制能力: 最关键的是，daisyUI 从未剥夺我们使用 Tailwind 的能力。如果一个 daisyUI 组件不完全符合我们的需求，我们随时可以追加 Tailwind 的原子类来进行微调和覆盖，例如 <button class="btn btn-primary rounded-full">。这种“随时可穿透”的特性，是它优于传统组件库的核心优势。

1.2.5. 认识 cva：为自定义组件提供变体管理能力

尽管 daisyUI 提供了丰富的组件，但在构建一个完整的设计系统时，我们必然会遇到需要创建 daisyUI 未涵盖的、具有高度业务特性的自定义组件的场景。这时，我们就需要一个工具来优雅地管理这些自定义组件的多种变体，而这正是 cva (Class Variance Authority) 的用武之地。

cva 是一个微型工具库，它允许我们以一种清晰、可读的方式，将组件的 Props 声明式地映射到一组 Tailwind 工具类上。

一个 cva 定义的核心结构如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

import { cva } from "class-variance-authority";

export const customAvatarVariants = cva(
  "inline-flex items-center justify-center rounded-full",
  {
    variants: {
      size: {
        small: "h-8 w-8 text-xs",
        large: "h-12 w-12 text-lg",
      },
      status: {
        online: "ring-2 ring-green-400",
        offline: "grayscale",
      }
    },
    defaultVariants: {
      size: "small",
    },
  }
);

通过 cva，当我们需要构建自己的 CustomAvatar 组件时，可以轻松地管理其 size 和 status 等变体，而无需编写复杂的条件判断逻辑。

技术栈的完美协同:
我们的技术栈是一个分层的、各司其职的有机整体：

• Radix: 在需要处理极其复杂的交互和无障碍性时，作为可选的、最底层的 行为引擎。
• Tailwind v4: 作为设计令牌的载体和高性能的 原子化样式基石。
• daisyUI: 作为日常开发中最高效的 组件样式封装层，加速 80%的开发工作。
• cva: 作为构建自定义组件时，管理样式变体的 可选工具。

这个范式将“做什么”（行为）与“长什么样”（表现）分离，同时提供了从高层抽象到低层控制的完整能力，是构建一个既稳固又灵活的现代设计系统的最佳工程路径。

1.2.3 本节小结

我们的技术选型决策是基于“分层抽象”与“关注点分离”的核心原则。我们采用 Radix 作为处理复杂行为和可访问性的底层保障；以革命性的 Tailwind CSS v4 作为高性能的样式基石，并通过其 @theme 机制承载我们的设计令牌；在此之上，引入 daisyUI 作为高效率的组件样式抽象层，以加速日常开发；最后，保留 cva 作为构建自定义组件时优雅管理变体的可选方案。这套现代化的、高度解耦的架构，不仅极大地提升了定制化能力和开发体验，更从根本上保障了设计系统在长期演进中的可维护性和可扩展性。

1.3. 工程化基石：从零搭建 Prorise UI 项目

至此，我们已经完成了所有必要的理论铺垫，明确了设计系统的“是什么”以及技术选型的“为什么”。现在，我们将进入更激动人心的环节：将理论转化为实践。本节内容将是纯粹的、高强度的动手操作，我们将从一个空无一物的文件夹开始，一步步搭建起一个包含了现代化前端框架、设计系统规范注入、以及自动化代码质量保障体系的、生产级别的项目地基。

1.3.1. 项目初始化：选择 Next.js 作为我们的开发框架

在开始之前，我们需要选择一个承载我们设计系统的项目框架。正如我们之前所探讨的，我们的选择是 Next.js。如果您是一位经验丰富的 React 开发者，但对 Next.js 尚不熟悉，请不必有任何顾虑。Next.js 并非一个需要您从头学习的全新框架，而应被看作是 React 的一套官方推荐的、自带完整工程化方案的最佳实践集合。您将无缝地掌握它，并体会到它为我们免去的繁琐配置工作。

现在，让我们打开终端，执行以下命令来创建我们的项目骨架。我们将项目命名为 prorise-ui。

1

npx create-next-app@latest prorise-ui

执行此命令后，会启动一个交互式安装向导。为了确保项目具备最佳初始状态，请参考以下指引完成选择。我们在此不使用对话格式，而是采用更正式的配置清单形式进行说明：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

✔ Would you like to use TypeScript? … Yes
# 理由：TypeScript 的类型安全对于构建一个健壮、可维护的设计系统至关重要。

✔ Would you like to use ESLint? … Yes
# 理由：我们需要 ESLint 来保证整个项目的代码质量和风格一致性。

✔ Would you like to use Tailwind CSS? … Yes
# 理由：这是我们技术栈的核心基石，Next.js 会为我们完成所有初始配置。

✔ Would you like to use `src/` directory? … Yes
# 理由：使用 src 目录是一种主流的、更清晰的项目结构组织方式。

✔ Would you like to use App Router? (recommended) … Yes
# 理由：App Router 是 Next.js 最新的、功能更强大的路由系统。

✔  Would you like to use Turbopack? (recommended) » Yes
# Turbopack 是一个为 JavaScript 和 TypeScript 优化的新型增量打包工具，主要优点是速度极快

✔ Would you like to customize the default import alias (@/*)? … No
# 理由：默认的 @/* 别名是一个清晰且广泛接受的约定，无需修改。

完成以上步骤后，create-next-app 会自动安装所有依赖并生成项目文件。现在，我们已经拥有了一个名为 prorise-ui 的目录，其中包含了一个配置完备、可立即运行的现代化 Next.js 应用程序。

1.3.2. 设计系统注入：集成 shadcn/ui, daisyUI 与主题规范

项目框架已经就绪，我们的下一步工作是将设计规范的“神经系统”植入其中。

第一步：初始化主题规范与核心工具

我们进入刚刚创建的 prorise-ui 项目目录，并执行 shadcn/ui 的初始化命令。此命令是 项目配置工具，它会为我们的项目写入规范，而不会添加任何运行时依赖。

1
2
3
4
5

# 首先进入项目目录
cd prorise-ui

# 执行初始化命令
npx shadcn@latest init

在弹出的交互式引导中，您只需根据上一步 create-next-app 时选择的路径，确认各项配置即可。此命令的核心动作是：

1. 生成 components.json 配置文件。
2. 在全局 CSS 文件中注入一套完整的、基于 CSS 变量的主题（设计令牌）体系。
3. 自动安装 tailwind-merge, clsx 等必要的辅助工具库。

第二步：集成 daisyUI 组件样式层

接下来，我们安装 daisyUI 作为快速开发的高阶组件样式库。

1

pnpm install -D daisyui@latest

第三步：配置全局样式与设计令牌体系

现在，我们将上述所有配置整合到我们的全局样式文件中。这是本节最关键的一步，我们将在这里看到一个完整的设计令牌体系是如何在代码中呈现的。

文件路径: src/app/globals.css

首先，shadcn-ui init 会将此文件内容 完全替换 为他固定的结构。这就是我们设计系统的令牌基础，它以原生的 CSS 变量形式存在，并已内置完整的亮/暗色模式切换能力。

接下来，我们在此文件顶部引入 daisyUI 插件，并在文件末尾添加自定义主题配置，让 daisyUI 完全由我们刚刚建立的设计令牌驱动，这个部分我们可以使用 daisyui 的主题生成器 daisyUI and Tailwind CSS theme generator，我就使用我们博客的配色风格来了，

文件路径: src/app/globals.css

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74

@import "tailwindcss";
@plugin "daisyui"; /* <-- 步骤一：引入 daisyUI 插件 */

@plugin "daisyui/theme" {
  name: "light";
  default: true;
  prefersdark: false;
  color-scheme: "light";
  --color-base-100: oklch(98% 0 0);
  --color-base-200: oklch(97% 0 0);
  --color-base-300: oklch(92% 0 0);
  --color-base-content: oklch(20% 0 0);
  --color-primary: oklch(0% 0 0);
  --color-primary-content: oklch(100% 0 0);
  --color-secondary: oklch(70% 0.213 47.604);
  --color-secondary-content: oklch(98% 0.016 73.684);
  --color-accent: oklch(62% 0.214 259.815);
  --color-accent-content: oklch(97% 0.014 254.604);
  --color-neutral: oklch(26% 0 0);
  --color-neutral-content: oklch(98% 0 0);
  --color-info: oklch(54% 0.245 262.881);
  --color-info-content: oklch(97% 0.014 254.604);
  --color-success: oklch(62% 0.194 149.214);
  --color-success-content: oklch(98% 0.018 155.826);
  --color-warning: oklch(64% 0.222 41.116);
  --color-warning-content: oklch(98% 0.016 73.684);
  --color-error: oklch(57% 0.245 27.325);
  --color-error-content: oklch(97% 0.013 17.38);
  --radius-selector: 1rem;
  --radius-field: 0.5rem;
  --radius-box: 0.5rem;
  --size-selector: 0.25rem;
  --size-field: 0.25rem;
  --border: 1px;
  --depth: 1;
  --noise: 0;
}


@plugin "daisyui/theme" {
  name: "dark";
  default: false;
  prefersdark: false;
  color-scheme: "dark";
  --color-base-100: oklch(14% 0.005 285.823);
  --color-base-200: oklch(21% 0.006 285.885);
  --color-base-300: oklch(27% 0.006 286.033);
  --color-base-content: oklch(96% 0.001 286.375);
  --color-primary: oklch(44% 0.043 257.281);
  --color-primary-content: oklch(98% 0.003 247.858);
  --color-secondary: oklch(44% 0.017 285.786);
  --color-secondary-content: oklch(98% 0 0);
  --color-accent: oklch(55% 0.288 302.321);
  --color-accent-content: oklch(97% 0.014 308.299);
  --color-neutral: oklch(14% 0.005 285.823);
  --color-neutral-content: oklch(98% 0 0);
  --color-info: oklch(68% 0.169 237.323);
  --color-info-content: oklch(97% 0.013 236.62);
  --color-success: oklch(72% 0.219 149.579);
  --color-success-content: oklch(98% 0.018 155.826);
  --color-warning: oklch(70% 0.213 47.604);
  --color-warning-content: oklch(98% 0.016 73.684);
  --color-error: oklch(63% 0.237 25.331);
  --color-error-content: oklch(97% 0.013 17.38);
  --radius-selector: 1rem;
  --radius-field: 0.5rem;
  --radius-box: 0.5rem;
  --size-selector: 0.25rem;
  --size-field: 0.25rem;
  --border: 1px;
  --depth: 1;
  --noise: 0;
}

至此，我们的项目地基不仅结构稳固，其“血液”也已经完全统一。无论是未来使用 daisyUI 的便捷组件，还是我们自己构建的复杂组件，都将共享同一套视觉基因。

1.3.3. 质量保障体系：配置自动化代码规范工作流

一个专业的项目，尤其是一个将作为团队基础的设计系统项目，必须从第一天起就建立一套自动化的机制来保障代码质量和协作规范。这不仅能避免个人习惯差异导致的代码风格混乱，更能从源头杜绝潜在的低级错误，防止技术债的累积。

我们将集成业界主流的工具链，在代码提交阶段设立一道坚固的 “质量关卡”：

• Prettier: 目前最流行的代码格式化工具，支持多种语言，能够确保团队代码风格的绝对统一。
• ESLint: JavaScript 生态系统的标准代码检查工具，Next.js 已为我们预配置好了核心规则，我们只需将其与 Prettier 整合即可。
• Husky: 现代化的 Git Hooks 管理工具，让我们能在 commit 或 push 等 Git 事件发生时执行自定义脚本。
• lint-staged: 高效的文件过滤工具，确保我们的检查和格式化操作 仅针对 本次提交所修改的文件，而非整个项目，极大地提升了效率。
• commitlint: 提交信息规范校验工具，强制所有提交都遵循约定式提交规范（Conventional Commits），为后续的版本管理和变更日志（CHANGELOG）自动化生成奠定基础。

第一步：安装开发依赖

我们首先在项目根目录，将所有需要的工具作为开发依赖项进行安装。注意，这里我们需要同时安装 Prettier 以及它与 ESLint 的集成插件。

1

pnpm install -D husky lint-staged @commitlint/cli @commitlint/config-conventional prettier eslint-config-prettier eslint-plugin-prettier prettier-plugin-tailwindcss

各依赖项的作用说明：

• prettier: 代码格式化工具
• eslint-config-prettier: 关闭所有与 Prettier 冲突的 ESLint 规则
• eslint-plugin-prettier: 将 Prettier 规则集成到 ESLint 中
• prettier-plugin-tailwindcss: Prettier 的 Tailwind CSS 插件，用于自动排序 Tailwind 类名
• husky: Git Hooks 管理工具
• lint-staged: 暂存文件过滤工具
• @commitlint/cli 和 @commitlint/config-conventional: 提交信息规范工具及其约定式提交预设

第二步：配置 Prettier

Prettier 没有类似 init 的初始化命令，我们需要手动创建配置文件。在项目根目录创建 .prettierrc 文件，并复制以下内容：

文件路径: .prettierrc

1
2
3
4
5
6
7
8
9

{
  "semi": true,
  "trailingComma": "es5",
  "singleQuote": true,
  "printWidth": 80,
  "tabWidth": 2,
  "useTabs": false,
  "plugins": ["prettier-plugin-tailwindcss"]
}

配置说明：

• semi: 语句末尾添加分号
• trailingComma: 在 ES5 兼容的多行语句中添加尾随逗号
• singleQuote: 使用单引号而非双引号
• printWidth: 每行代码最大字符数为 80
• tabWidth: 缩进使用 2 个空格
• useTabs: 使用空格而非 Tab 缩进
• plugins: 启用 Tailwind CSS 类名自动排序插件

同时创建 .prettierignore 文件，告诉 Prettier 哪些文件和目录无需格式化：

文件路径: .prettierignore

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

# 依赖
node_modules
.pnp
.pnp.js

# 构建输出
.next
out
dist
build

# 测试覆盖率
coverage

# 其他
.DS_Store
*.pem
.env*.local
.turbo
package-lock.json
pnpm-lock.yaml
yarn.lock

第三步：集成 ESLint 与 Prettier

Next.js 项目已经自带了 ESLint 配置，我们只需将 Prettier 规则整合进去即可。打开 eslint.config.mjs 文件，将其修改为如下内容：

文件路径: eslint.config.mjs

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

import { dirname } from 'path';
import { fileURLToPath } from 'url';
import { FlatCompat } from '@eslint/eslintrc';

const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);

const compat = new FlatCompat({
  baseDirectory: __dirname,
});

const eslintConfig = [
  ...compat.extends('next/core-web-vitals', 'next/typescript', 'prettier'),
  {
    ignores: [
      'node_modules/**',
      '.next/**',
      'out/**',
      'build/**',
      'next-env.d.ts',
    ],
  },
  {
    plugins: {
      prettier: (await import('eslint-plugin-prettier')).default,
    },
    rules: {
      'prettier/prettier': 'warn',
    },
  },
];

export default eslintConfig;

关键改动说明：

1. 在 compat.extends 中添加了 'prettier'，这会引入 eslint-config-prettier 的配置，关闭所有与 Prettier 冲突的 ESLint 规则。
2. 添加了一个新的配置对象，引入 eslint-plugin-prettier 插件，并将 prettier/prettier 规则设置为 warn 级别，这样格式问题会以警告形式显示，不会中断开发流程。

接下来，在 package.json 中添加几个便捷的脚本命令，方便我们手动触发代码检查和格式化：

文件路径: package.json（部分）

1
2
3
4
5
6
7
8
9
10
11
12

{
  "scripts": {
    "dev": "next dev --turbopack",
    "build": "next build --turbopack",
    "start": "next start",
    "lint": "eslint",
    "lint:fix": "eslint --fix",
    "format": "prettier --write .",
    "format:check": "prettier --check .",
    "prepare": "husky"
  }
}

新增的脚本说明：

• lint:fix: 运行 ESLint 并自动修复问题
• format: 使用 Prettier 格式化所有文件
• format:check: 检查所有文件是否符合 Prettier 格式规范（不修改文件）

第四步：配置 lint-staged

lint-staged 的核心价值在于精准打击，避免了每次提交都对全量代码进行检查的漫长等待。我们在 package.json 中添加 lint-staged 字段：

文件路径: package.json（部分）

1
2
3
4
5
6
7
8
9
10
11

{
  "lint-staged": {
    "*.{js,jsx,ts,tsx}": [
      "eslint --fix",
      "prettier --write"
    ],
    "*.{json,md,css}": [
      "prettier --write"
    ]
  }
}

这份配置的含义是：

• 对于所有提交的 js, jsx, ts, tsx 文件，先执行 eslint --fix 尝试自动修复代码问题，然后执行 prettier --write 进行格式化。
• 对于 json, md, css 等文件，仅执行 prettier --write 进行格式化。

第五步：配置 commitlint

commitlint 确保每一条提交信息都清晰、规范，让团队成员和工具都能轻易读懂提交历史。我们将采用包含自定义规则的配置，以建立更明确的团队规范。

在项目根目录创建 commitlint.config.js 文件：

文件路径: commitlint.config.js

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

/** @type {import('@commitlint/types').UserConfig} */
const configuration = {
  extends: ['@commitlint/config-conventional'],
  rules: {
    // 定义允许的提交类型
    'type-enum': [
      2,
      'always',
      [
        'feat',     // 新功能（feature）
        'fix',      // 修复 bug
        'docs',     // 文档更新
        'style',    // 代码格式调整（不影响代码运行）
        'refactor', // 重构（既不是新功能也不是修复 bug）
        'perf',     // 性能优化
        'test',     // 添加或修改测试
        'build',    // 构建系统或外部依赖的变更
        'ci',       // CI/CD 配置文件的变更
        'chore',    // 其他不修改 src 或测试文件的变更
        'revert',   // 回退之前的提交
      ],
    ],
    // 主题不能为空
    'subject-empty': [2, 'never'],
    // 主题不能以句号结尾
    'subject-full-stop': [2, 'never', '.'],
    // 提交信息头部最大长度
    'header-max-length': [2, 'always', 100],
  },
};

module.exports = configuration;

此配置不仅继承了社区的通用规范，还详细定义了我们项目中允许的 11 种提交类型，确保了提交信息的标准化。

提交信息格式说明：

约定式提交的基本格式为：

1
2
3
4
5

<type>: <subject>

[可选的正文]

[可选的脚注]

注意：type 和冒号之后必须有一个空格，这是规范的强制要求。

示例：

1
2
3
4
5
6
7

# 正确格式
git commit -m "feat: 添加用户登录功能"
git commit -m "fix: 修复导航栏在移动端的显示问题"
git commit -m "docs: 更新 README 安装说明"

# 错误格式（缺少空格）
git commit -m "feat:添加用户登录功能"  # ❌ 会被拦截

第六步：初始化 Husky v9 并创建 Hooks

接下来是最关键的一步：激活 husky 并让它来执行我们上面配置好的工具。

6.1 初始化 Husky

在项目根目录执行以下命令：

1

npx husky init

这条命令会自动完成三件事：

1. 创建 .husky/ 目录。
2. 在 package.json 中添加 "prepare": "husky" 脚本。这个脚本会在 pnpm install 后自动运行，确保团队新成员拉取项目后，Husky 能被自动激活。
3. 在 .husky/ 目录下创建一个名为 pre-commit 的钩子文件示例。

6.2 创建 Git Hooks

现在，我们需要创建或修改两个核心的钩子文件。

这是因为 Windows 的 PowerShell 使用 echo 命令创建文件时，默认采用 UTF-16LE 编码，而 Husky 的钩子文件必须使用 UTF-8 编码才能被正确执行。如果您在 PowerShell 中执行了 echo 命令创建钩子文件，在提交时会遇到如下错误：

1
2

.husky/pre-commit: .husky/pre-commit: cannot execute binary file
husky - pre-commit script failed (code 126)

解决方案：

1. 推荐做法：右键项目文件夹，选择 “Git Bash Here”，在打开的 Git Bash 终端中执行下面的命令。
2. 替代方案：如果您坚持使用 PowerShell，请在 VS Code 中手动创建钩子文件，并确保文件编码为 UTF-8，换行符为 LF。

此问题是 Windows 系统特有的，macOS 和 Linux 用户可以忽略。

在 Git Bash 中，执行以下命令创建 pre-commit 钩子，让它在提交前执行 lint-staged：

1

echo "npx lint-staged" > .husky/pre-commit

然后，创建 commit-msg 钩子，让它在提交时校验提交信息：

1

echo 'npx --no -- commitlint --edit $1' > .husky/commit-msg

执行完毕后，我们的 .husky 目录结构如下：

1
2
3
4

.husky/
├── _/              # Husky 内部使用的辅助文件目录
├── commit-msg      # 在提交时，用 commitlint 校验信息
└── pre-commit      # 在提交前，用 lint-staged 检查文件

如果您在 VS Code 中打开这两个钩子文件，请确认右下角显示的文件编码为 UTF-8，换行符为 LF。如果不是，请点击右下角的编码或换行符标识进行切换。

第七步：测试自动化工作流

现在，我们的自动化质量保障体系已全部配置完毕。让我们来亲自验证一下它的效果。

测试 1：验证 pre-commit 钩子 (lint-staged)

1. 打开任意一个 .tsx 文件，故意破坏其代码格式，例如添加多余的空格、使用双引号等。

   1 2 3 4 5 6 7 8

   // src/app/page.tsx export default function Home() { return ( <main> <h1 className="text-2xl" >Prorise UI</h1> </main> ) }

2. 将文件添加到暂存区，并尝试提交。

   1 2	git add . git commit -m "feat: add title to homepage"

3. 预期结果: 您会看到终端输出了 lint-staged 的运行信息，ESLint 和 Prettier 依次对文件进行了检查和格式化。提交成功后，再次查看刚才的文件，会发现多余的空格已经被自动清除了。如果存在 ESLint 无法自动修复的错误，提交则会被中止，您需要手动修复后才能继续提交。

测试 2：验证 commit-msg 钩子 (commitlint)

1. 随便修改一个文件，然后尝试使用不规范的提交信息进行提交。

   1 2	git add . git commit -m "更新了一下页面"

2. 预期结果: 提交 失败，commitlint 会立即报错，提示您 type 和 subject 存在问题。

   1 2 3 4 5

   ⧗ input: 更新了一下页面 ✖ subject may not be empty [subject-empty] ✖ type may not be empty [type-empty] ✖ found 2 problems, 0 warnings

3. 使用规范的格式再次提交：

   1	git commit -m "docs: 更新页面文案"

   提交成功。

测试 3：验证格式错误提示

尝试提交一个缺少空格的提交信息：

1

git commit -m "feat:添加新功能"

预期结果: 提交失败，提示格式错误。正确的格式应为：

1

git commit -m "feat: 添加新功能"

注意冒号后面的空格，这是约定式提交规范的强制要求。

至此，我们的自动化 “防火墙” 已成功建立。从现在开始，每一次 git commit 都会自动触发代码质量检查和格式化，每一条提交信息都必须符合团队规范，确保了代码库的长期健康和可维护性，我们现在正确的将项目提交到我们的 github 仓库

1
2
3
4
5
6
7

git commit -m "chore: 配置代码质量保障工具链

- 添加 Husky 9 用于 Git Hooks 管理
- 添加 lint-staged 用于暂存文件检查
- 添加 commitlint 用于提交信息规范
- 添加 Prettier 用于代码格式化
- 集成 ESLint 与 Prettier"

一个比较有意思的是 next 会将默认的脚手架文件做一个提前标记，以做区分是否改动过原脚手架的内容

第八步：引入 conventional-changelog 实现自动化变更日志

在规范化提交信息之后，我们还可以更进一步，利用这些结构化的提交历史自动生成项目的变更日志（CHANGELOG）。conventional-changelog 正是为此而生的工具，它能够读取符合约定式提交规范的 Git 历史，自动生成格式规范、内容清晰的 CHANGELOG.md 文件。

这不仅为团队成员和用户提供了清晰的版本演变记录，更为后续的版本发布、语义化版本管理（Semantic Versioning）奠定了坚实基础。

1.安装 conventional-changelog-cli

在项目根目录执行以下命令，安装 conventional-changelog-cli 作为开发依赖：

1

pnpm install -D conventional-changelog-cli

2 配置 CHANGELOG 生成脚本

打开 package.json，在 scripts 字段中添加以下命令：

文件路径: package.json（部分）

1
2
3
4
5
6

{
  "scripts": {
    "changelog": "conventional-changelog -p angular -i CHANGELOG.md -s",
    "version": "conventional-changelog -p angular -i CHANGELOG.md -s && git add CHANGELOG.md",
  }
}

新增脚本的说明：

• changelog: 手动生成或更新 CHANGELOG.md 文件

  • -p angular: 使用 Angular 提交规范（与我们的 commitlint 配置一致）
  • -i CHANGELOG.md: 将生成的日志写入 CHANGELOG.md 文件
  • -s: 增量模式，只生成自上次发布以来的变更，不会覆盖已有内容

• version: 与 npm/pnpm version 命令配合使用，在版本升级时自动生成 CHANGELOG

  • 执行完 conventional-changelog 后会自动将 CHANGELOG.md 添加到暂存区
  • 通常在执行 pnpm version patch/minor/major 时会自动触发

3. 生成第一份 CHANGELOG

在首次使用时，我们可以生成包含所有历史版本的完整 CHANGELOG：

1
2

# 生成所有历史版本的 CHANGELOG（仅首次）
npx conventional-changelog -p angular -i CHANGELOG.md -s -r 0

参数说明：

• -r 0: 生成所有版本的日志（release count = 0 表示全部）

执行后，项目根目录会生成 CHANGELOG.md 文件，内容按照版本和提交类型（feat、fix、perf 等）自动分类整理。

4. 日常使用流程

配置完成后，您的日常版本发布流程可以如下进行，在这之前我们有必要要了解一下版本号的规范：

• 主版本号 (Major)：当你做了不兼容的 API 修改时，需要升级主版本号。这通常意味着软件发生了重大的变化，可能会导致依赖该软件的旧版本代码无法正常工作。例如，从版本 1.7.0 升级到 2.0.0。
• 次版本号 (Minor)：当你以向下兼容的方式添加了新功能时，需要升级次版本号。“向下兼容”意味着新版本虽然增加了功能，但不会破坏依赖旧版本软件的代码。例如，从版本 1.7.0 升级到 1.8.0。
• 修订号 (Patch)：当你做了向下兼容的问题修复时，需要升级修订号。这通常指的是修复了软件中的 bug，而没有引入新功能或不兼容的改动。例如，从版本 1.7.0 升级到 1.7.1。

1
2
3
4
5
6
7
8
9
10
11
12

# 1. 确保所有代码已提交
git add .
git commit -m "feat: 完成某个新功能"

# 2. 使用 pnpm version 升级版本（会自动生成 CHANGELOG）
pnpm version patch   # 修订号升级 1.0.0 -> 1.0.1
pnpm version minor   # 次版本号升级 1.0.0 -> 1.1.0
pnpm version major   # 主版本号升级 1.0.0 -> 2.0.0

# 3. 推送代码和标签
git push
git push --tags

执行 pnpm version 时，会依次触发以下自动化流程：

1. 更新 package.json 中的版本号
2. 执行 version 脚本，生成最新的 CHANGELOG
3. 将 CHANGELOG.md 添加到暂存区
4. 创建一个 Git commit 和 tag

如果您只想手动生成 CHANGELOG 而不升级版本，可以单独执行：

1

pnpm run changelog

5 CHANGELOG 示例

生成的 CHANGELOG.md 文件格式示例如下：

1
2
3
4
5
6
7
8
9

## [0.1.2](https://github.com/Prorise-cool/Prorise-UI/compare/v0.1.1...v0.1.2) (2025-10-12)

## 0.1.1 (2025-10-12)

### Features

- 完成某个新功能 ([a1bcc83](https://github.com/Prorise-cool/Prorise-UI/commit/a1bcc83c4d11392962cb62c2a24bd2f5aa5df030))

# 0.1.0 (2025-10-12)

可以看到，所有提交按类型自动分类（Features、Bug Fixes、Performance Improvements 等），并且包含了提交信息和 commit hash 链接，方便追溯具体改动。

注意事项

1. 提交信息必须规范：只有符合约定式提交规范的 commit 才会被收集到 CHANGELOG 中。不规范的提交信息会被忽略。

2. 常规改动会被包含：默认情况下，feat、fix、perf 类型的提交会出现在 CHANGELOG 中，而 docs、style、refactor、test、chore 等类型不会出现（但它们仍然是有效的提交类型，只是不会展示给最终用户）。

3. Breaking Changes 会突出显示：如果提交信息中包含 BREAKING CHANGE: 标识，该提交会在 CHANGELOG 中被特别标注，提醒用户这是一个破坏性变更。

示例：

1
2
3

git commit -m "feat: 重构用户认证模块

BREAKING CHANGE: 用户登录接口的响应格式已改变，需要更新客户端代码"

至此，我们不仅建立了规范化的提交信息体系，还拥有了自动化的变更日志生成能力。项目的每一次演进都将被清晰地记录和呈现。

1.3.4 本节小结

在本节中，我们完成了从零到一的飞跃。我们首先使用 create-next-app 初始化了一个功能完备的现代化 React 项目。紧接着，我们利用 shadcn/ui init 命令，为项目注入了一套专业、基于 CSS 变量的底层设计令牌体系。随后，我们集成了 daisyUI 作为高效率的组件样式层，并通过自定义主题配置，使其完全由我们的设计令牌驱动，实现了视觉规范的顶层统一。

最后，我们配置了一套完整的代码质量保障工具链：Prettier 负责代码格式化，ESLint 负责代码质量检查，两者完美集成；Husky 管理 Git Hooks，lint-staged 确保只检查修改的文件，commitlint 强制提交信息规范化。这套自动化工作流在每次提交时都会自动运行，确保入库的每一行代码都符合最高质量标准。

至此，一个结构清晰、规范统一、质量可靠的专业设计系统项目基座已搭建完毕，为后续的组件开发铺平了道路。

第二章. StoryBook 与 Mdx 初识：Button 组件的全景开发

在第一章中，我们投入了大量精力，从零开始构建了一个坚实、专业且自动化的项目基座。现在，万事俱备，是时候真正开始“建设”我们的设计系统了。

本章的核心目标，并非仅仅是实现一个按钮，而是要通过开发这个最基础、最通用的 Button 组件，来完整地建立和演练一套世界级的组件开发 工作流。我们将依次经历 组件编码与变体设计、交互式文档编写 和 自动化单元测试 三个阶段。完成本章后，您将拥有一套可以复用到任何组件开发中的、高效、可靠的“肌肉记忆”。

2.1. 工厂模式：结合 daisyUI 与 cva 实现 Button 的变体

我们首先来解决组件开发中的第一个核心问题：如何优雅地管理组件的多种视觉形态？

2.1.1. 痛点剖析：混乱的条件样式

一个 Button 组件在真实业务场景中，通常需要支持多种变体。例如，按功能分，有主按钮、次按钮、危险按钮；按尺寸分，有大、中、小三种尺寸。在传统的开发模式中，我们可能会写出类似下面这样的代码：

1
2
3
4
5
6
7
8

// 一个难以维护的 Button 组件示例 (错误示范)
function BadButton({ variant, size, ...props }) {
  // ...
  // 使用 if/else 或三元运算符来拼接类名
  const variantClass = variant === 'primary' ? 'bg-blue-500 text-white' : 'bg-gray-200 text-gray-800';
  const sizeClass = size === 'small' ? 'h-9 px-3' : 'h-11 px-8';
  // ...
}

这种写法的弊端显而易见：当变体增加或需要引入新状态（如 disabled）时，组件内部的条件判断逻辑会迅速膨胀，变得难以阅读和扩展。这种将样式判断逻辑与组件渲染逻辑强耦合的方式，违背了“关注点分离”的软件设计基本原则。

2.1.2. 解决方案：daisyUI + cva 的双层抽象

我们的解决方案分为两层，完美地结合了第一章铺垫的技术：

1. 样式层: 我们将直接使用 daisyUI 提供的高语义、预设好的组件类名（如 btn, btn-primary）作为样式的“原子单位”。这让我们无需手动组合大量的 Tailwind 工具类，极大地提升了开发效率。
2. 变体管理层: 我们将使用 cva (Class Variance Authority) 作为“工厂”，它的任务是根据传入的 props，动态地、声明式地选择并组合正确的 daisyUI 类名。

这种模式，让我们既能享受 daisyUI 的便捷，又能拥有 cva 带来的类型安全和优雅的变体管理能力。

2.1.3. 准备工作：创建文件与安装依赖

在开始编码前，我们先准备好环境。

1. 创建组件文件

遵循 shadcn/ui 的约定，我们将所有 UI 组件都放置在 src/components/ui 目录下。

1
2
3

# 在项目根目录下执行
mkdir -p src/components/ui
touch src/components/ui/Button.tsx

2. 安装 Slot 依赖

为了让我们的 Button 组件更具灵活性（例如，有时我们希望它渲染为一个 <a> 标签），我们需要 Radix UI 提供的 Slot 组件。

1

pnpm install @radix-ui/react-slot

2.1.4. 逐步构建：Button 组件的实现

现在，我们打开 src/components/ui/Button.tsx 文件，开始我们的渐进式构建之旅。每一步我们都会展示文件的 完整 状态，并用注释标明该步骤的 新增或修改 之处，确保您清楚每一行代码的上下文。

1. 阶段一：搭建最小化组件骨架

我们的起点，是一个最纯粹的 React 组件骨架。我们使用 React.forwardRef，这是构建可复用组件库的最佳实践，它允许父组件将 ref 直接传递到我们内部渲染的 DOM 元素上。

文件路径: src/components/ui/Button.tsx

1
2
3
4
5
6
7
8
9
10
11
12
13
14

import * as React from 'react';

// 使用 React.forwardRef 创建一个可转发 ref 的组件
const Button = React.forwardRef<HTMLButtonElement>(
  (props, ref) => {
    return (
      <button ref={ref} {...props} />
    );
  }
);
// 设置 displayName 便于在 React DevTools 中调试
Button.displayName = 'Button';

export { Button };

解析: 至此，我们有了一个功能上等同于原生 <button> 的 React 组件。

2. 阶段二：引入 daisyUI 基础样式

现在，让我们为这个骨架穿上 daisyUI 的“基础皮肤”。只需添加 btn 这个核心类名。

文件路径: src/components/ui/Button.tsx

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

import * as React from 'react';

const Button = React.forwardRef<HTMLButtonElement>(
  (props, ref) => {
    return (
      <button
        className="btn" // <-- 修改此行：添加 daisyUI 的基础按钮类
        ref={ref}
        {...props}
      />
    );
  }
);
Button.displayName = 'Button';

export { Button };

解析: 仅仅一个类名，我们的按钮就已经拥有了由 daisyUI 提供的一致的尺寸、字体、内外边距和交互效果，这得益于我们在第一章的全局配置。

3. 阶段三：创建 cva 样式工厂

为了管理 primary, secondary 等变体，我们现在引入 cva 来创建一个样式工厂。这个工厂的职责是根据 props，输出对应的 daisyUI 变体类名。

文件路径: src/components/ui/Button.tsx

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76

import * as React from 'react';
// <-- 新增代码块 开始 -->
import { cva, type VariantProps } from 'class-variance-authority';

import { cn } from '@/lib/utils';

// 1. 创建样式工厂
const buttonVariants = cva(
  // 第一个参数：所有变体共享的基础类名
  'btn',
  {
    // 第二个参数：定义变体
    variants: {
      // "variant" 轴：定义按钮的功能和视觉风格（颜色）
      variant: {
        default: '', // 默认情况，daisyUI 不需要额外类名
        neutral: 'btn-neutral',
        primary: 'btn-primary',
        secondary: 'btn-secondary',
        accent: 'btn-accent',
        info: 'btn-info',
        success: 'btn-success',
        warning: 'btn-warning',
        error: 'btn-error',
      },
      // "buttonStyle" 轴：定义按钮的样式风格（重命名以避免与 React.CSSProperties 的 style 冲突）
      buttonStyle: {
        default: '', // 默认实心样式
        outline: 'btn-outline',
        dash: 'btn-dash',
        soft: 'btn-soft',
        ghost: 'btn-ghost',
        link: 'btn-link',
      },
      // "size" 轴：定义按钮的尺寸
      size: {
        xs: 'btn-xs',
        sm: 'btn-sm',
        md: 'btn-md', // 默认尺寸
        lg: 'btn-lg',
        xl: 'btn-xl',
      },
      // "behavior" 轴：定义按钮的行为状态
      behavior: {
        default: '',
        active: 'btn-active',
        disabled: 'btn-disabled',
      },
      // "modifier" 轴：定义按钮的修饰符
      modifier: {
        default: '',
        wide: 'btn-wide',
        block: 'btn-block',
        square: 'btn-square',
        circle: 'btn-circle',
      },
    },

    // 第三部分：指定默认值
    defaultVariants: {
      variant: 'default',
      buttonStyle: 'default',
      size: 'md',
      behavior: 'default',
      modifier: 'default',
    },
  }
);
// <-- 新增代码块 结束 -->

const Button = React.forwardRef<HTMLButtonElement>(
  // ... 此前代码 ...
);
Button.displayName = 'Button';

export { Button };

解析: 我们在文件顶部定义了 buttonVariants。注意，cva 的第一个参数是 daisyUI 的基础类 btn，而 variants 对象中的值则是 daisyUI 提供的高级变体类，如 btn-primary。这正是两大工具协同工作的核心体现。

4. 阶段四：定义类型安全的 Props 接口

接下来，我们要创建一个 ButtonProps 接口。它必须能接收所有原生按钮属性，并且能以类型安全的方式，理解我们刚刚用 cva 定义的 variant 和 size。

文件路径: src/components/ui/Button.tsx

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

// ... imports 和 buttonVariants 定义 ...

// <-- 新增代码块 开始 -->
// 2. 定义类型安全的 Props 接口
export interface ButtonProps
  extends React.ButtonHTMLAttributes<HTMLButtonElement>, // 继承原生 button 所有属性
    VariantProps<typeof buttonVariants> {
  // 从 cva 工厂自动推断 variant 和 size 类型
  asChild?: boolean;
}
// <-- 新增代码块 结束 -->

const Button = React.forwardRef<HTMLButtonElement>(
  // ... 此前代码 ...
);
// ...

解析: VariantProps<typeof buttonVariants> 是 cva 的一个高级工具类型。它会自动分析 buttonVariants 的 variants 对象，并生成一个包含 variant 和 size 及其所有可能值的联合类型，确保了我们的组件 props 与样式定义永远保持同步。

5. 阶段五：连接 Props 与样式工厂

现在，我们将 Props 与 cva 工厂连接起来，让组件根据传入的 props 动态生成最终的类名。

文件路径: src/components/ui/Button.tsx

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

// ... imports, buttonVariants, ButtonProps 定义 ...

// <-- 修改 Button 组件的实现 -->
const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
  // 从 props 中解构出我们的变体属性和 className
  ({ className, variant, buttonStyle, size, behavior, modifier, ...props }, ref) => {
    return (
      <button
        // 调用样式工厂，并用 cn 函数智能合并类名
        className={cn(buttonVariants({ variant, buttonStyle, size, behavior, modifier, className }))}
        ref={ref}
        {...props}
      />
    );
  }
);
Button.displayName = 'Button';

// <-- 修改导出，额外导出 buttonVariants -->
export { Button, buttonVariants };

解析: 我们修改了 Button 组件的实现。buttonVariants({ variant, size, className }) 会根据传入的 props，从工厂中选择正确的 daisyUI 类名并组合起来。cn 函数则确保这些生成的类名能和任何从外部传入的 className 优雅地合并，并自动解决类名冲突。

6. 阶段六：实现 asChild 组合功能

最后，我们来添加 asChild 这个高级功能，让我们的 Button 组件拥有“附身”到其他元素（如链接 <a>）上的能力。这是最终的完整形态。

文件路径: src/components/ui/Button.tsx

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

import * as React from 'react';
import { Slot } from '@radix-ui/react-slot'; // <-- 确保 Slot 已导入
import { cva, type VariantProps } from 'class-variance-authority';

import { cn } from '@/lib/utils';

const buttonVariants = cva(/* ... */);

export interface ButtonProps
  extends React.ButtonHTMLAttributes<HTMLButtonElement>,
    VariantProps<typeof buttonVariants> {
  asChild?: boolean; // <-- 确保 asChild 已在接口中定义
}

// <-- 修改 Button 组件的实现 -->
const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
  // <-- 修改点 1：从 props 中解构出 asChild -->
  ({ className, variant, buttonStyle, size, behavior, modifier, asChild = false, ...props }, ref) => {
        // <-- 修改点 2：动态决定渲染的组件 -->
    const Comp = asChild ? Slot : 'button';
    return (
            // <-- 修改点 3：使用动态组件 Comp 进行渲染 -->
      <Comp
        // 调用样式工厂，并用 cn 函数智能合并类名
        className={cn(buttonVariants({ variant, buttonStyle, size, behavior, modifier, className }))}
        ref={ref}
        {...props}
      />
    );
  }
);
Button.displayName = 'Button';

export { Button, buttonVariants };

解析: 当 asChild 为 true 时，Comp 会变成 Slot 组件。Slot 会将其接收到的所有属性（包括我们生成的 className）“克隆”并传递给它的直接子元素，而自身不渲染任何 DOM 节点。这使得 <Button asChild><a href="/">Home</a></Button> 这样的写法成为可能，最终渲染出的会是一个带有完整按钮样式的 <a> 标签。

至此，一个集 daisyUI 的高效、cva 的优雅和 Radix Slot 的灵活于一体的、生产级的 Button 组件已构建完毕。

7. 阶段七：验证与消费组件

理论和代码构建已经完成，现在是收获成果的时候。我们将修改 Next.js 应用的首页，来实际使用和展示我们刚刚创建的 Button 组件的所有变体。这个过程不仅能验证我们的工作成果，也能让您直观地感受到 cva 变体系统的强大之处。

首先，为了更好地展示图标按钮，我们需要安装一个图标库。lucide-react 是 shadcn/ui 生态中最常用的图标库，我们来安装它。

1

pnpm install lucide-react

接下来，我们清空并修改首页文件，将其变为一个 Button 组件的“陈列室”。

文件路径: src/app/page.tsx

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87

import { Button } from '@/components/ui/Button';
import { Mail } from 'lucide-react'; // 导入一个图标用于演示

export default function HomePage() {
  return (
    <main className="flex min-h-screen flex-col items-center justify-center gap-8 bg-background p-24">
      <div className="flex flex-col items-center gap-2">
        <h1 className="text-2xl font-bold">Button Variant Showcase</h1>
        <p className="text-muted-foreground">功能与视觉风格</p>
      </div>
      <div className="flex flex-wrap items-center justify-center gap-4">
        <Button variant="default">Default</Button>
        <Button variant="neutral">Neutral</Button>
        <Button variant="primary">Primary</Button>
        <Button variant="secondary">Secondary</Button>
        <Button variant="accent">Accent</Button>
        <Button variant="info">Info</Button>
        <Button variant="success">Success</Button>
        <Button variant="warning">Warning</Button>
        <Button variant="error">Error</Button>
      </div>

      <div className="flex flex-col items-center gap-2">
        <h2 className="text-xl font-bold">Button Style Showcase</h2>
        <p className="text-muted-foreground">样式风格</p>
      </div>
      <div className="flex flex-wrap items-center justify-center gap-4">
        <Button buttonStyle="default" variant="primary">Default</Button>
        <Button buttonStyle="outline" variant="primary">Outline</Button>
        <Button buttonStyle="dash" variant="primary">Dash</Button>
        <Button buttonStyle="soft" variant="primary">Soft</Button>
        <Button buttonStyle="ghost" variant="primary">Ghost</Button>
        <Button buttonStyle="link" variant="primary">Link</Button>
      </div>

      <div className="flex flex-col items-center gap-2">
        <h2 className="text-xl font-bold">Button Size Showcase</h2>
        <p className="text-muted-foreground">尺寸与规格</p>
      </div>
      <div className="flex flex-wrap items-center justify-center gap-4">
        <Button size="xs">Extra Small</Button>
        <Button size="sm">Small</Button>
        <Button size="md">Medium</Button>
        <Button size="lg">Large</Button>
        <Button size="xl">Extra Large</Button>
      </div>

      <div className="flex flex-col items-center gap-2">
        <h2 className="text-xl font-bold">Button Behavior Showcase</h2>
        <p className="text-muted-foreground">行为状态</p>
      </div>
      <div className="flex flex-wrap items-center justify-center gap-4">
        <Button behavior="default" variant="primary">Default</Button>
        <Button behavior="active" variant="primary">Active</Button>
        <Button behavior="disabled" variant="primary">Disabled</Button>
      </div>

      <div className="flex flex-col items-center gap-2">
        <h2 className="text-xl font-bold">Button Modifier Showcase</h2>
        <p className="text-muted-foreground">修饰符</p>
      </div>
      <div className="flex flex-wrap items-center justify-center gap-4">
        <Button modifier="default" variant="primary">Default</Button>
        <Button modifier="wide" variant="primary">Wide</Button>
        <Button modifier="block" variant="primary">Block</Button>
        <Button modifier="square" variant="primary">
          <Mail className="h-4 w-4" />
        </Button>
        <Button modifier="circle" variant="primary">
          <Mail className="h-4 w-4" />
        </Button>
      </div>
      
      <div className="flex flex-col items-center gap-2">
        <h2 className="text-xl font-bold">asChild Prop Showcase</h2>
        <p className="text-muted-foreground">组合与渲染</p>
      </div>
      <div className="flex flex-wrap items-center justify-center gap-4">
        <Button asChild buttonStyle="outline" variant="primary">
          <a href="https://github.com/google/gemini-pro" target="_blank" rel="noopener noreferrer">
            I am a Link
          </a>
        </Button>
      </div>
    </main>
  );
}

运行与验证

现在，回到您的终端，确保您在 prorise-ui 项目的根目录下，然后启动开发服务器：

1

pnpm run dev

打开浏览器并访问 http://localhost: 3000。您应该能看到一个清晰展示了所有按钮变体和尺寸的页面。您可以尝试点击、悬浮，并观察不同变体的交互效果。

这个页面的成功渲染，不仅证明了我们的 Button 组件代码是正确的，更重要的是，它验证了我们从第一章开始搭建的整个技术体系——从 Next.js 框架，到 Tailwind CSS 和 shadcn/ui 变量的注入，再到 daisyUI 插件的集成——已经完全打通并协同工作。

2.1.5 本节小结

在本节中，我们严格遵循“渐进式构建”的原则，成功创建了设计系统的第一个核心组件 Button。我们没有直接堆砌原子类，而是巧妙地将 daisyUI 的高语义组件类作为 cva 样式工厂的输出，完美结合了二者的优点。通过分步实现组件骨架、类型接口、样式映射和组合功能，我们将一个复杂的组件构建过程拆解为一系列聚焦单一概念的、易于理解的步骤。这个过程不仅产出了一个具体的组件，更重要的是，为我们后续所有组件的开发，奠定了一套可复用的、优雅的、层次分明的编码范式。

2.2. 文档驱动开发：集成 Storybook 8 与组件可视化

现在，我们已经拥有了一个功能完备的 Button 组件。但一个孤立的组件代码文件，对于使用它的其他开发者、以及与之协作的设计师来说，仍然是一个“黑盒”。如何直观地展示它的所有功能、变体和交互状态？如何为它创建一份易于维护、永远与代码同步的“活文档”？

答案就是 Storybook。本节，我们将为项目集成最新版的 Storybook 8，并将其配置为我们组件的“可视化工作台”和文档中心。

2.2.1. 一键安装：使用 Storybook 8 CLI 初始化工作环境

1.核心理念：组件驱动开发

在集成工具之前，我们先要理解其背后的思想——组件驱动开发 (Component-Driven Development, CDD)。其核心主张是，将 UI 组件作为开发的基本单元，在独立、隔离的环境中进行构建和测试，然后再集成到复杂的应用中。

Storybook 正是实践这一理念的行业标准工具。它为我们提供了一个脱离主应用的、专门用于开发和展示组件的“实验室”环境。在这个环境中，我们可以轻松地模拟组件的每一种状态和变体，而无需为了看到一个特定状态的按钮，而去手动操作整个复杂的业务流程。

2.初始化命令

Storybook 8 提供了强大的 CLI 工具，可以自动检测我们的项目技术栈（Next.js, React, Tailwind CSS）并完成所有必需的配置。

在您的项目 prorise-ui 的根目录下，执行以下命令：

1

npx storybook@latest init

该命令会执行一系列自动化操作：

• 探测项目配置，并询问您是否确认安装。
• 安装所有必要的 Storybook 依赖包，例如 @storybook/react-nextjs, @storybook/addon-essentials 等。
• 在项目根目录下创建一个 .storybook 目录，其中包含 Storybook 的核心配置文件。
• 在 src/ 目录下创建一个 stories 目录，并生成一些示例故事文件，以验证安装是否成功。

3.分析生成的文件

安装完成后，您的项目目录结构会新增以下关键部分：

1
2
3
4
5
6
7
8
9
10

prorise-ui/
├── .storybook/
│   ├── main.ts         # ⬅️ Storybook 的主配置文件
│   └── preview.ts      # ⬅️ 全局配置文件，用于“包裹”所有故事
├── src/
│   └── stories/        # ⬅️ Storybook 自动生成的示例故事
│       ├── Button.stories.ts
│       ├── Header.stories.ts
│       └── Page.stories.ts
└── ...

我们重点关注 .storybook 目录下的两个核心文件：

1. .storybook/main.ts: 这是 Storybook 的“控制面板”。

• stories: 定义了 Storybook 去哪里寻找我们的故事文件（.stories.tsx）。

  • addons: 注册了需要加载的插件，例如 addon-essentials 包含了一系列核心功能（如 Controls, Actions, Viewport 等）。

  • framework: 指定了 Storybook 需要适配的框架，这里它会自动配置为 @storybook/nextjs-vite。

2. .storybook/preview.ts: 这是所有故事的“全局画布”。我们可以在这里定义全局参数、添加全局装饰器（Decorators），或者导入全局样式。这个文件对于后续的主题集成至关重要。

4.首次运行

1
2
3
4
5
6
7

const config = {
  plugins: {
    '@tailwindcss/postcss': {},
  },
};

export default config;

Storybook 的 init 命令会自动在 package.json 中添加一个 storybook 脚本。现在，让我们运行它。

1

pnpm run storybook

执行后，Storybook 会启动一个本地开发服务器，并自动在浏览器中打开。您应该能看到 Storybook 的欢迎界面，以及左侧导航栏中由 CLI 生成的 Button, Header, Page 等示例故事。

5.清理工作

这些自动生成的示例故事很好地验证了我们的安装，但它们并不是我们 Prorise UI 设计系统的一部分。为了保持项目整洁，我们将它们删除，为下一节编写我们自己的第一个故事做准备。

在终端中执行以下命令（或手动删除该文件夹）：

1
2
3
4
5

# Linux / macOS
rm -rf src/stories

# Windows (PowerShell Prompt)
Remove-Item -Path "src\stories" -Recurse -Force

现在，我们拥有了一个纯净、与项目深度集成的 Storybook 8 环境。但您可能会发现，示例故事中的按钮样式似乎并不正确——这正是我们下一节要解决的问题。

2.2.2. 主题集成：让 Storybook 理解我们的全局样式与暗色模式

痛点剖析：隔离的预览环境

当您运行 pnpm storybook 时，您所看到的组件预览区域（通常称为 “Canvas”）实际上是 一个独立的 iframe 页面。这个页面与我们的 Next.js 应用是完全隔离的，因此它默认不会加载 src/app/globals.css 文件。这就导致了两个问题：

1. 所有由 shadcn/ui 生成的 CSS 变量（如 --primary, --background）都未定义。
2. Tailwind 和 daisyUI 的样式虽然被 Storybook 的构建过程所编译，但由于缺少基础变量，渲染效果会完全错乱。
3. Tailwind CSS 的暗色模式依赖于 <html> 标签上是否存在一个 dark 类，Storybook 默认也不知道如何控制这个类。

我们的任务就是解决这三个问题，让 Storybook 的预览环境与我们的主应用环境完全同步。

前置准备：确保构建工具兼容性

在开始配置之前，我们需要处理一个潜在的兼容性问题。当您使用 npx storybook@latest init 安装 Storybook 时，它会自动选择 @storybook/nextjs-vite 框架。这意味着 Storybook 将使用 Vite 作为构建引擎，而不是 Next.js 的默认构建工具。

这带来了一个问题：Next.js 15 生成的 postcss.config.mjs 文件使用的是数组格式的插件配置，而 Vite 要求使用对象格式。我们需要先修正这个配置，否则 Storybook 将无法正常启动。

文件路径: postcss.config.mjs

请将您的 PostCSS 配置文件修改为以下格式：

1
2
3
4
5
6
7

const config = {
  plugins: {
    '@tailwindcss/postcss': {},
  },
};

export default config;

解析: 将 plugins 从数组格式（["@tailwindcss/postcss"]）改为对象格式（{ "@tailwindcss/postcss": {} }）。这种对象格式同时兼容 Next.js 和 Vite，不会影响您的 Next.js 应用的正常运行，只是写法上的差异。

现在，您可以成功运行 pnpm storybook 了，虽然此时 Storybook 可能会提示 “找不到任何故事”，这是正常的，因为我们还没有编写任何故事文件。

第一步：注入全局样式

这是最关键、也是最简单的一步。我们需要告诉 Storybook，在渲染任何故事之前，都必须先加载我们的全局样式文件。这个配置在 .storybook/preview.ts 文件中完成。

文件路径: .storybook/preview.ts

1
2
3
4

import type { Preview } from "@storybook/react";

// <-- 新增：导入项目的全局样式文件 -->
import "../src/app/globals.css";

解析: 只需在文件顶部添加 import "../src/app/globals.css"; 这一行，Webpack (或 Vite) 在打包 Storybook 时就会将我们的全局样式包含进去。此时，如果您重新运行 pnpm storybook，会发现组件的颜色、字体等基础样式已经基本正确，因为 CSS 变量已经被正确加载。

第二步：安装并注册主题切换插件

为了在 Storybook 中方便地切换亮/暗色模式，我们需要一个专门的插件。官方的 @storybook/addon-themes 是最佳选择。

首先，安装它作为开发依赖：

1

pnpm add -D @storybook/addon-themes

然后，我们需要在 Storybook 的主配置文件中“注册”这个插件，让 Storybook 加载它。

文件路径: .storybook/main.ts

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

import type { StorybookConfig } from "@storybook/nextjs-vite";
const config: StorybookConfig = {
  "stories": [
    "../src/**/*.mdx",
    "../src/**/*.stories.@(js|jsx|mjs|ts|tsx)"
  ],
  "addons": [
    "@chromatic-com/storybook",
    "@storybook/addon-docs",
    "@storybook/addon-onboarding",
    "@storybook/addon-a11y",
    "@storybook/addon-vitest",
    "@storybook/addon-themes", // <-- 新增：在此处注册主题插件
  ],
  "framework": {
    "name": "@storybook/nextjs-vite",
    "options": {}
  },
  "staticDirs": [
    "..\\public"
  ]
};
export default config;

解析: 在 addons 数组中添加 @storybook/addon-themes，即可激活该插件。

第三步：配置主题切换装饰器

插件激活后，我们还需要告诉它我们的主题是如何工作的。这里有一个重要的技术决策需要做出。

在我们的项目中，我们使用了 daisyUI 作为 UI 组件库。daisyUI 的主题系统是基于 HTML 的 data-theme 属性来工作的，而不是 CSS 类。当您在 HTML 根元素上设置 data-theme="dark" 时，daisyUI 会自动应用该主题中定义的所有 CSS 变量（如 --color-primary、--color-accent 等）。

因此，我们需要使用 @storybook/addon-themes 提供的 withThemeByDataAttribute 工具，而不是常见的 withThemeByClassName。

我们将使用一个 “装饰器 (Decorator)” 来完成这个配置。装饰器是 Storybook 的一个强大功能，它像一个包装纸，可以将我们所有的故事都包裹在里面，从而提供统一的上下文或功能。

文件路径: .storybook/preview.ts

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

import type { Preview } from "@storybook/nextjs-vite";
import { withThemeByDataAttribute } from "@storybook/addon-themes"; // <-- 1. 导入正确的工具

import "../src/app/globals.css";

const preview: Preview = {
  parameters: {
    controls: {
      matchers: {
        color: /(background|color)$/i,
        date: /Date$/i,
      },
    },
  },
  // <-- 2. 新增 decorators 配置 -->
  decorators: [
    withThemeByDataAttribute({
      themes: {
        // 为每个主题起一个名字，并指定它对应的 data-theme 属性值
        light: "light",
        dark: "dark",
      },
      // 指定默认主题
      defaultTheme: "light",
      // 指定要操作的属性名
      attributeName: "data-theme",
    }),
  ],
};

export default preview;

代码深度解析:

• decorators: 这是 preview.ts 中的一个关键属性，它是一个数组，可以包含多个装饰器。
• withThemeByDataAttribute: 这是 @storybook/addon-themes 导出的一个装饰器工厂函数，专门用于处理基于 HTML 属性的主题切换。
• themes 对象: 我们在这里定义了我们拥有的主题。键名（如 light, dark）将作为工具栏中选项的名称，值（如 "light", "dark"）则是当该主题被选中时，需要设置到 HTML 根元素 data-theme 属性上的值。
• attributeName: 明确指定我们要操作的属性名为 data-theme。这与 daisyUI 的主题系统完全匹配。
• defaultTheme: 指定 Storybook 默认加载时使用的主题。

为什么选择 withThemeByDataAttribute？能否同时使用两个装饰器？

您可能会看到很多 Storybook 教程使用 withThemeByClassName，那是因为纯 Tailwind CSS 项目通常通过 .dark 类来切换主题。而我们的项目使用了 daisyUI，它有自己的主题系统，需要通过 data-theme 属性来激活。

理论上，您确实可以同时使用两个装饰器：

1
2
3
4
5
6
7
8
9
10
11

decorators: [
  withThemeByDataAttribute({
    themes: { light: "light", dark: "dark" },
    defaultTheme: "light",
    attributeName: "data-theme",
  }),
  withThemeByClassName({
    themes: { light: "", dark: "dark" },
    defaultTheme: "light",
  }),
],

这样配置后，切换主题时会同时：

1. 设置 data-theme="dark" 属性（激活 daisyUI 主题）
2. 添加 .dark 类（激活 Tailwind 的暗色模式工具类）

那么什么时候需要两个装饰器，什么时候只需要一个？

这取决于您的代码中是否使用了 Tailwind 的 dark: 变体类。让我们分析两种场景：

场景 1：只使用 daisyUI 组件

如果您的组件完全依赖 daisyUI 的类名（如 btn, btn-primary），这些类名的样式是由 daisyUI 的 CSS 变量驱动的。只要 data-theme 属性正确设置，daisyUI 就会应用正确的颜色。此时，只需要 withThemeByDataAttribute 就足够了。

1
2

// 这个组件只需要 data-theme 属性
<button className="btn btn-primary">按钮</button>

场景 2：混合使用 Tailwind 暗色模式类

如果您的组件中使用了 Tailwind 的 dark: 前缀类名，例如：

1
2
3

<div className="bg-white dark:bg-gray-900 text-black dark:text-white">
  <button className="btn btn-primary">按钮</button>
</div>

在这种情况下，您需要同时使用两个装饰器。因为：

• dark:bg-gray-900 和 dark:text-white 需要 .dark 类才能生效
• btn btn-primary 需要 data-theme 属性才能获得正确的颜色

我们项目的选择

在我们当前的项目中，由于 Button 组件是基于 daisyUI 的 btn 类构建的，并且 globals.css 中已经通过 @layer base 定义了全局的背景和文字颜色：

1
2
3
4
5
6
7
8

@layer base {
  * {
    @apply border-border outline-ring/50;
  }
  body {
    @apply bg-background text-foreground;
  }
}

这些基础样式会自动根据 CSS 变量变化，而这些变量在 globals.css 的 :root 和 .dark 选择器中已经定义。因此，使用单个 withThemeByDataAttribute 装饰器已经足以满足需求。

但如果您在后续开发中，在组件内部大量使用了 dark: 前缀的 Tailwind 类，那时再添加 withThemeByClassName 装饰器也不迟。Storybook 的装饰器系统支持随时添加或移除装饰器，这是一个可以根据项目需求灵活调整的配置。

第四步：最终验证

所有配置都已就绪。现在让我们重新启动 Storybook（如果它正在运行，请先停止它）：

1

pnpm storybook

Storybook 应该能够成功启动。虽然此时您可能还看不到任何组件（因为我们还没有编写故事文件），但您会在 Storybook 界面的右上角工具栏中看到一个新的图标 —— 这就是主题切换器，通常显示为画笔或太阳/月亮图标。

点击这个图标，您会看到两个选项：light 和 dark。当您在它们之间切换时，整个 Storybook 预览区域的背景色会随之变化。这证明了以下几点：

1. globals.css 已经成功加载到 Storybook 的预览环境中。
2. @storybook/addon-themes 插件正在正常工作。
3. data-theme 属性正在被正确设置和切换。

理解主题切换的工作原理:

当您切换到暗色主题时，Storybook 会在预览区域的根 HTML 元素上设置 data-theme="dark"。此时，daisyUI 会读取这个属性，并应用 globals.css 中定义的暗色主题配置（第 162-195 行的 @plugin "daisyui/theme" { name: "dark"; ... } 部分）。这个配置会覆盖所有的颜色变量，例如：

• --color-accent 从亮色模式的 oklch(62% 0.214 259.815)（柔和的蓝紫色）变为 oklch(55% 0.288 302.321)（鲜艳的紫色）
• --color-base-100 从 oklch(98% 0 0)（接近白色）变为 oklch(14% 0.005 285.823)（深灰色）

这就是为什么使用 withThemeByDataAttribute 如此重要 —— 它确保了 daisyUI 的整套主题系统能够被正确激活，而不仅仅是改变背景色。

至此，我们的 Storybook 环境已经配置完毕，它成为了一个能够 100% 精确反映我们应用真实样式的、强大的可视化开发与调试平台。在下一章中，我们将学习如何为组件编写故事文件，让它们在这个完美的环境中得以展现。

2.2.3. 编写第一个 Story：Button 组件的 CSF 3.0 实践

在上一节中，我们成功地将 Storybook 的预览环境与我们的项目主题完全同步。现在，这个“可视化工作台”已经准备就绪，是时候将我们精心打造的第一个“产品”——Button 组件——放上展台了。

本节我们将学习如何使用最新、最主流的 组件故事格式 3.0，为 Button 组件编写它的第一个“故事 (Story)”。

核心理念：什么是 Story？什么是 CSF？

• Story: 一个 Story 代表一个组件的 单一、可被渲染的状态。例如，“一个主色、大尺寸的按钮”就是一个 Story，“一个禁用状态的、次要颜色的按钮”是另一个 Story。通过为组件编写一系列 Stories，我们就能完整地记录和展示它的所有可能性。

• CSF (Component Story Format): 这是 Storybook 官方推荐的、基于标准 ES 模块的 Story 编写规范。CSF 3.0 是其最新版本，它通过一个 meta 对象来定义组件级的元数据，并通过具名导出 (Named Exports) 来定义每一个独立的 Story。这种格式不仅写法简洁，而且与 TypeScript 的结合极为出色，能提供强大的类型推断和自动补全能力。

第一步：创建 Story 文件

按照社区的最佳实践，组件的 Story 文件应该与组件源文件并置存放，并以 .stories.tsx 作为后缀。这样做的好处是便于查找和维护。

让我们为 Button 组件创建它的 Story 文件：

1
2

# 在项目根目录下执行
touch src/components/ui/Button.stories.tsx

第二步：构建基础结构 (Meta 对象)

每一个 Story 文件都必须有一个默认导出 (default export)，我们称之为 meta 对象。它负责告诉 Storybook 这个文件是关于哪个组件的，以及如何对它进行分类和展示。

文件路径: src/components/ui/Button.stories.tsx

1
2
3
4
5
6
7
8
9
10
11
12
13
14

import type { Meta, StoryObj } from '@storybook/react';
import { Button } from './Button'; // 1. 导入我们需要为其编写故事的组件

// 2. 定义 Meta 对象，描述我们的组件故事集
const meta = {
  title: 'Components/Button', // 故事在 Storybook 侧边栏中的显示路径
  component: Button, // 将这个 Story 文件与 Button 组件本身进行强关联
  parameters: {
    layout: 'centered', // 让组件在 Canvas 中居中显示
  },
  tags: ['autodocs'], // 开启自动文档生成
} satisfies Meta<typeof Button>;

export default meta;

代码深度解析:

• title: 定义组件在 Storybook 侧边栏中的显示路径。'Components/Button' 会在侧边栏生成 Components 文件夹，其下有 Button 条目。
• component: 将 Story 文件与组件进行强关联。这使得 Storybook 能够读取组件的 TypeScript 类型，自动生成 Controls 控件和文档。
• parameters.layout: 控制组件在 Canvas 中的布局方式，'centered' 让组件居中显示，便于观察。
• tags: ['autodocs']: 启用 Storybook 的自动文档生成功能，会为组件创建一个 “Docs” 标签页。
• satisfies Meta<typeof Button>: TypeScript 的类型断言语法，确保 meta 对象符合 Storybook 的 Meta 类型要求，同时保留类型推断能力。

第三步：编写第一个 Story (Primary)

现在，我们来定义第一个具体的 Story。一个 Story 就是一个简单的、具名导出的对象。

文件路径: src/components/ui/Button.stories.tsx

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

import type { Meta, StoryObj } from '@storybook/react';
import { Button } from './Button';

const meta = {
  // ... 此前定义的 meta 对象 ...
} satisfies Meta<typeof Button>;

export default meta;

// <-- 新增代码块 开始 -->
// 为我们的 Story 对象定义一个基础类型，以获得更好的 TypeScript 智能提示
type Story = StoryObj<typeof meta>;

// 导出一个名为 Default 的 Story（最简单的状态）
export const Default: Story = {
  args: {
    children: 'Button',
  },
};

// 导出一个名为 Primary 的 Story
export const Primary: Story = {
  args: {
    variant: 'primary',
    children: 'Primary Button',
  },
};
// <-- 新增代码块 结束 -->

代码深度解析:

• type Story = StoryObj<typeof meta>;: 这是一个 TypeScript 的最佳实践。StoryObj 是 Storybook 提供的泛型，typeof meta 会将我们 meta 对象中关于组件类型的信息传递给它，从而创建一个与 Button 组件 props 完全匹配的 Story 类型。
• export const Primary: Story = { ... };: 我们通过具名导出的方式创建了一个名为 Primary 的 Story。这个导出的名称会成为它在 Storybook 侧边栏中的显示名称。
• args: 这是定义一个 Story 最核心的部分。args 对象中的每一个键值对，都会被作为 props 传递给被渲染的 Button 组件。在 Default Story 中，我们只设置了 children，让组件使用其默认样式。在 Primary Story 中，我们指定了 variant 为 primary，这会应用 daisyUI 的 btn-primary 类名。

第四步：为更多变体编写 Stories

Storybook 的强大之处在于能够清晰地罗列和展示组件的所有状态。让我们继续为 Button 的其他重要变体添加对应的 Stories。

文件路径: src/components/ui/Button.stories.tsx

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88

// ... 此前的 meta, Story 类型, Default 和 Primary Stories ...

// <-- 新增代码块 开始 -->
// 不同颜色变体
export const Secondary: Story = {
  args: {
    variant: 'secondary',
    children: 'Secondary Button',
  },
};

export const Accent: Story = {
  args: {
    variant: 'accent',
    children: 'Accent Button',
  },
};

export const Success: Story = {
  args: {
    variant: 'success',
    children: 'Success Button',
  },
};

export const Warning: Story = {
  args: {
    variant: 'warning',
    children: 'Warning Button',
  },
};

export const Error: Story = {
  args: {
    variant: 'error',
    children: 'Error Button',
  },
};

// 不同样式风格
export const Outline: Story = {
  args: {
    variant: 'primary',
    buttonStyle: 'outline',
    children: 'Outline Button',
  },
};

export const Ghost: Story = {
  args: {
    variant: 'primary',
    buttonStyle: 'ghost',
    children: 'Ghost Button',
  },
};

// 不同尺寸
export const Small: Story = {
  args: {
    size: 'sm',
    children: 'Small Button',
  },
};

export const Large: Story = {
  args: {
    size: 'lg',
    children: 'Large Button',
  },
};

// 不同状态
export const Disabled: Story = {
  args: {
    variant: 'primary',
    behavior: 'disabled',
    children: 'Disabled Button',
  },
};

export const Active: Story = {
  args: {
    variant: 'primary',
    behavior: 'active',
    children: 'Active Button',
  },
};
// <-- 新增代码块 结束 -->

解析: 我们的 Button 组件基于 daisyUI 构建，拥有丰富的变体选项。我们为不同的 variant（颜色变体如 secondary、accent、success 等），不同的 buttonStyle（样式风格如 outline、ghost），不同的 size（尺寸如 sm、lg），以及不同的 behavior（行为状态如 disabled、active）都创建了独立的 Story。每一个具名导出都会在 Storybook 的侧边栏生成一个对应的条目，让我们可以轻松地在不同状态之间切换查看。

注意我们使用了 buttonStyle 而不是将 outline 放在 variant 中，这是因为 daisyUI 将颜色和样式风格分离为两个独立的维度，使得组合更加灵活。例如，您可以创建一个 “accent 颜色的 outline 样式按钮”，只需同时设置 variant="accent" 和 buttonStyle="outline"。

第五步：最终验证

现在，再次运行 Storybook（如果它已经在运行，通常会自动热更新）：

1

pnpm storybook

打开浏览器，您现在应该能在左侧的侧边栏中看到 Components/Button 条目，展开它，下面会列出我们刚刚编写的所有 Stories：Default, Primary, Secondary, Accent, Success, Warning, Error, Outline, Ghost, Small, Large, Disabled, Active 等。点击其中任意一个，右侧的 Canvas 区域都会立刻渲染出对应状态的 Button 组件。

特别值得注意的是，当您切换 Storybook 的主题（使用右上角的主题切换器）时，按钮的颜色会根据 daisyUI 的主题配置自动变化。例如，Accent 按钮在亮色模式下显示为柔和的蓝紫色，而在暗色模式下则变为鲜艳的紫色，这证明了我们在上一节配置的 data-theme 属性正在正常工作。

我们已经成功地为组件创建了一份 “可视化说明书”。但这还不够，目前我们只能查看预设的状态。如何才能在 Storybook 界面上自由地、动态地组合所有 props 来探索组件的全部潜力呢？这正是我们下一节要解决的问题。

2.2.4. 交互式调试：利用 Controls Addon 动态修改 Props

核心理念：Props 的自动化 UI

您可能会想，Button.stories.tsx 文件中定义的 args 对象，仅仅是为组件传递了固定的 props。这背后隐藏着 Storybook 一个极其强大的特性：它能够动态地解析这些 args 以及组件本身的 TypeScript 类型，并自动为它们生成一套可交互的图形界面。这个功能由 @storybook/addon-essentials 中包含的 Controls Addon 提供。

它的工作原理如下：

1. Storybook 读取 meta.component，找到我们的 Button 组件。
2. 它分析 Button 组件的 ButtonProps 接口，识别出 variant, size, children, disabled 等所有可配置的 props 及其类型。
3. 对于 variant 和 size 这种拥有明确联合类型 ('primary' | 'secondary' ...) 的 prop，它能智能地判断出这是一个“选择题”。
4. 最终，它在 Storybook 界面的附加面板中，为我们动态生成一个包含下拉菜单、单选框、文本输入框等控件的表单，让我们能够实时修改这些 props。

第一步：改造 Story 为交互式模板

为了激活 Controls 功能，我们不需要为每个变体都编写一个 Story，而是只需要一个“模板 Story”。这个 Story 的 args 定义了组件的默认状态，然后由 Controls 来动态改变这些 args。

让我们来改造 Button.stories.tsx 文件。我们将 Primary 这个 Story 重命名为 InteractivePlayground，并暂时移除其他冗余的 Story，使其成为我们唯一的、可交互的“实验台”。

文件路径: src/components/ui/Button.stories.tsx

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69

import type { Meta, StoryObj } from '@storybook/react';

import { Button } from './Button';

const meta: Meta<typeof Button> = {
  title: 'UI/Button',
  component: Button,
  parameters: {
    layout: 'centered',
  },
  tags: ['autodocs'],
  // 我们将在下一步中配置 argTypes
};

export default meta;
type Story = StoryObj<typeof meta>;

// 交互式实验台 - 可以通过 Controls 面板动态调整所有属性
export const InteractivePlayground: Story = {
  args: {
    variant: 'primary',
    buttonStyle: 'default',
    size: 'md',
    behavior: 'default',
    modifier: 'default',
    children: 'Button',
  },
};

// 默认按钮
export const Default: Story = {
  args: {
    children: 'Button',
  },
};

// 不同尺寸
export const Sizes: Story = {
  render: () => (
    <div className="flex items-center gap-4">
      <Button size="xs">Extra Small</Button>
      <Button size="sm">Small</Button>
      <Button size="md">Medium</Button>
      <Button size="lg">Large</Button>
      <Button size="xl">Extra Large</Button>
    </div>
  ),
};

// 不同颜色变体
export const Variants: Story = {
  render: () => (
    <div className="flex flex-col gap-4">
      <div className="flex gap-2">
        <Button variant="default">Default</Button>
        <Button variant="neutral">Neutral</Button>
        <Button variant="primary">Primary</Button>
        <Button variant="secondary">Secondary</Button>
      </div>
      <div className="flex gap-2">
        <Button variant="accent">Accent</Button>
        <Button variant="info">Info</Button>
        <Button variant="success">Success</Button>
        <Button variant="warning">Warning</Button>
        <Button variant="error">Error</Button>
      </div>
    </div>
  ),
};

解析: 我们将 Primary Story 重构为了 InteractivePlayground，并为其 args 提供了更完整的默认值。现在，当您查看这个 Story 时，Storybook 的 Controls 插件将会被激活。

验证: 运行 pnpm storybook，在侧边栏中导航到 UI/Button/InteractivePlayground。在底部的 Addons 面板中，切换到 “Controls” 标签页。您会看到 Storybook 已经为 variant 和 size 自动生成了下拉选择框，为 children 生成了文本输入框，为 disabled 生成了开关。尝试修改这些控件的值，您会看到画布中的按钮实时地发生变化！

第二步：优化交互体验：配置 argTypes

自动生成的下拉框已经很好用了，但我们可以做得更好。例如，对于选项较少的 size，使用单选框（Radio buttons）可能比下拉框更直观。我们可以通过在 meta 对象中配置 argTypes 属性，来精确地定制每一个 prop 在 Controls 面板中的外观和行为。

文件路径: src/components/ui/Button.stories.tsx

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75

import type { Meta, StoryObj } from '@storybook/react';
import { Button } from './Button';

const meta: Meta<typeof Button> = {
  title: 'UI/Button',
  component: Button,
  parameters: {
    layout: 'centered',
  },
  tags: ['autodocs'],
  // <-- 新增：配置 argTypes 来优化 Controls 面板 -->
  argTypes: {
    variant: {
      control: 'select',
      options: ['default', 'neutral', 'primary', 'secondary', 'accent', 'info', 'success', 'warning', 'error'],
      description: '按钮的颜色变体',
      table: {
        type: { summary: 'string' },
        defaultValue: { summary: 'default' },
      },
    },
    buttonStyle: {
      control: 'select',
      options: ['default', 'outline', 'dash', 'soft', 'ghost', 'link'],
      description: '按钮的样式风格',
      table: {
        type: { summary: 'string' },
        defaultValue: { summary: 'default' },
      },
    },
    size: {
      control: 'radio',
      options: ['xs', 'sm', 'md', 'lg', 'xl'],
      description: '按钮的尺寸',
      table: {
        type: { summary: 'string' },
        defaultValue: { summary: 'md' },
      },
    },
    behavior: {
      control: 'radio',
      options: ['default', 'active', 'disabled'],
      description: '按钮的行为状态',
      table: {
        type: { summary: 'string' },
        defaultValue: { summary: 'default' },
      },
    },
    modifier: {
      control: 'radio',
      options: ['default', 'wide', 'block', 'square', 'circle'],
      description: '按钮的修饰符',
      table: {
        type: { summary: 'string' },
        defaultValue: { summary: 'default' },
      },
    },
    children: {
      control: 'text',
      description: '按钮显示的文本或子元素',
    },
  },
};

export default meta;
type Story = StoryObj<typeof meta>;

export const InteractivePlayground: Story = {
  args: {
    variant: 'primary',
    size: 'default',
    children: 'Button',
    disabled: false,
  },
};