设计系统构建指南

一份结构清晰的指南，用于构建可投入生产的组件库与设计系统。涵盖架构设计、设计令牌（tokens）、组件开发、文档编写、主题定制（theming）、测试策略及发布流程。

快速决策地图

1. 架构与单体仓库（Monorepo）配置

推荐目录结构

使用 pnpm workspaces + Turborepo 管理单体仓库。

my-design-system/
├── packages/
│   ├── tokens/          # 设计令牌（CSS 变量、JS 对象）
│   ├── icons/           # SVG 图标组件
│   ├── components/      # 核心 UI 组件
│   ├── themes/          # 主题定义
│   └── utils/           # 共享工具函数（cn、clsx 等）
├── apps/
│   └── docs/            # Storybook 文档站点
├── package.json         # 根工作区配置
├── pnpm-workspace.yaml
├── turbo.json
└── tsconfig.base.json

初始化命令

# 初始化单体仓库
mkdir my-design-system && cd my-design-system
pnpm init
pnpm add -D turbo -w

# 创建 workspace 配置文件
echo "packages:n  - 'packages/*'n  - 'apps/*'" > pnpm-workspace.yaml

turbo.json —— 任务流水线配置：

{
  "$schema": "https://turbo.build/schema.json",
  "pipeline": {
    "build": { "dependsOn": ["^build"], "outputs": ["dist/**"] },
    "dev": { "cache": false, "persistent": true },
    "test": { "dependsOn": ["^build"] },
    "lint": {}
  }
}

构建工具选型

推荐的 packages/components/package.json 示例：

{
  "name": "@myds/components",
  "version": "0.1.0",
  "main": "./dist/index.cjs",
  "module": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "import": "./dist/index.js",
      "require": "./dist/index.cjs",
      "types": "./dist/index.d.ts"
    }
  },
  "scripts": {
    "build": "tsup src/index.ts --format cjs,esm --dts",
    "dev": "tsup src/index.ts --format cjs,esm --dts --watch"
  }
}

2. 设计令牌（Design Tokens）

设计令牌是视觉决策的唯一事实来源（single source of truth）。

请阅读 references/tokens.md，了解完整的令牌 Schema、命名规范、CSS 变量模式，以及多品牌令牌示例。

快速上手

# 安装 Style Dictionary（令牌转换工具）
pnpm add -D style-dictionary -w

令牌源文件存放在 packages/tokens/src/ 目录下。Style Dictionary 将其转换为 CSS 变量、JS/TS 常量，以及平台专属输出（如 iOS、Android）。

核心令牌类别包括：color、typography、spacing、border-radius、shadow、z-index、motion。

3. 组件开发规范

每个组件都应遵循一致的约定，以保障长期可维护性。

请阅读 references/component-patterns.md，获取详细模式说明：文件组织结构、Props API 设计、复合组件（compound components）、多态组件（polymorphic components）、无障碍（accessibility）要求，以及文档模板。

不可妥协的规则

1. 优先使用 TypeScript —— 所有 Props 必须通过显式接口定义，禁止使用 any
2. forwardRef —— React 中所有叶节点（leaf）组件均需支持
3. aria-* 属性 —— 禁止发布任何不符合无障碍标准的组件
4. 受控（Controlled）与非受控（Uncontrolled）模式 —— 表单类组件必须同时支持两种模式
5. data-testid —— 必须提供，以支持端到端（E2E）测试

组件文件结构

Button/
├── Button.tsx          # 组件实现
├── Button.types.ts     # Props 接口与类型导出
├── Button.test.tsx     # 单元测试 + 交互测试
├── Button.stories.tsx  # Storybook 示例
└── index.ts            # 公共入口（barrel export）

4. Storybook

Storybook 是主要的文档编写与开发环境。

请阅读 references/storybook-setup.md，了解完整配置方案：插件安装、Autodocs、MDX 页面、Controls 控制面板、Storybook UI 主题定制，以及部署方式。

初始化

cd apps/docs
pnpm dlx storybook@latest init
# 提示时选择 React + Vite

必备插件：

• @storybook/addon-essentials（Controls、Actions、Docs、Viewport）
• @storybook/addon-a11y（无障碍审计）
• @storybook/addon-themes（主题切换）
• storybook-addon-pseudo-states（hover/focus/active 等伪状态模拟）

5. 主题系统（Theme System）

请阅读 references/theming.md，了解完整主题架构：CSS 自定义属性（custom properties）策略、暗色模式实现方式（媒体查询 vs 类名控制）、React 的 ThemeProvider 模式，以及 Vue 3 的 provide/inject 方案。

核心概念

令牌定义的是语义别名（semantic aliases），指向基础值（primitives）：

/* 基础值 */
--color-blue-500: #3b82f6;

/* 语义化（具备主题感知能力） */
[data-theme="light"] { --color-primary: var(--color-blue-500); }
[data-theme="dark"]  { --color-primary: var(--color-blue-400); }

组件仅引用语义令牌 —— 不得直接引用基础值。

6. 测试策略

请阅读 references/testing-strategy.md，了解完整的测试金字塔模型：单元测试（Vitest）、交互测试（Testing Library）、视觉回归测试（Chromatic/Percy），以及无障碍自动化检测。

组件库的测试金字塔

        [视觉回归测试]     ← Chromatic / Percy
       [交互测试]          ← @testing-library/react
      [单元测试 / 逻辑测试] ← Vitest

每个组件的最低测试要求：

• 渲染不报错
• Props 输入能产生预期输出
• 交互状态（hover、focus、disabled）正常工作
• 无严重无障碍问题（axe-core 检测）

7. 发布流水线（Release Pipeline）

请阅读 references/release-pipeline.md，了解完整发布流程：Changesets 配置、版本管理策略、自动生成变更日志（changelog）、CI/CD 流水线，以及 npm 发布机制。

工具：Changesets

pnpm add -D @changesets/cli -w
pnpm changeset init

典型工作流：

1. pnpm changeset —— 创建 changeset（描述变更内容）
2. pnpm changeset version —— 提升版本号 + 更新 CHANGELOG.md
3. pnpm changeset publish —— 发布至 npm

Vue 3 注意事项

大部分模式同样适用于 Vue 3，仅需少量适配：

• Props：使用 defineProps() 并配合 TypeScript 泛型
• expose() 替代 React 的 forwardRef
• 主题注入：使用 provide/inject 替代 React Context
• 测试：采用 @vue/test-utils + Vitest
• 详见 references/component-patterns.md 中的 Vue 专属示例

推荐技术栈汇总