当团队拥有多个前端应用时重复开发相同的 UI 组件成为最大的效率浪费——同样的按钮、输入框、弹窗在每个项目中都要重新实现一遍。组件库的核心价值正是消除重复、统一体验、提升效率。但随着业务复杂度增长组件库的定位也在不断演进从最初的“UI 物料集合”到“设计系统”的落地载体再到“团队协作基础设施”。本文从组件库的设计原则出发深入讲解原子设计方法论、组件库的技术选型与构建、文档站建设Storybook 7、版本管理与发布以及从“UI 组件库”到“设计系统”的演进路径帮你建立一套可落地的组件库建设体系。一、组件库的演进从“物料”到“设计系统”组件库的成熟度可以分为四个阶段2025 年成熟的组件库建设已经超越了“写组件”的范畴成为连接设计、开发、测试、文档的团队协作基础设施。二、组件库的设计原则2.1 原子设计Atomic Design原子设计是一种将 UI 拆解为层级结构的方法论从最基础的“原子”到最终的“页面”层级 定义 示例原子Atoms 不可再分的最小 UI 元素 Button、Input、Label、Icon分子Molecules 原子的组合具有独立功能 SearchBar、FormField、Card组织Organisms 分子和原子的组合复杂功能块 Header、ProductList、Sidebar模板Templates 页面的布局骨架 登录页布局、列表页布局页面Pages 模板 真实数据 登录页、商品详情页 关键理解原子设计提供了层级结构但要防止大型代码库变成“意大利面条”还需要结合明确的边界、公共 API 和所有权规则。2.2 组件设计的核心原则1单一职责每个组件只做一件事做得好。如果组件的 props 超过 10 个很可能已经承担了过多职责。2一致性与可预测性统一的 API 设计相同功能的组件使用相同的 prop 命名统一的样式变量使用设计令牌Design Tokens而非硬编码颜色/尺寸3可组合性组件之间松耦合可以自由组合。高阶组件优先使用组合Composition而非继承Inheritance。4可访问性Accessibility组件库应内置 WCAG 2.1 标准支持包括键盘导航、屏幕阅读器支持、颜色对比度。三、组件库的技术选型与构建3.1 Monorepo 组件库的架构推荐在 Monorepo 中管理组件库textmy-monorepo/├── packages/│ ├── ui/ # 组件库源码│ ├── storybook/ # Storybook 配置│ └── docs/ # 文档站点可选├── turbo.json└── package.json3.2 构建工具选型Vite 组件库构建配置示例// vite.config.tsimport{defineConfig}fromviteimportreactfromvitejs/plugin-reactimportdtsfromvite-plugin-dtsexportdefaultdefineConfig({plugins:[react(),dts({include:[src]})// 生成 TypeScript 类型定义],build:{lib:{entry:src/index.ts,name:MyUI,formats:[es,cjs],fileName:(format)index.${format}.js},rollupOptions:{external:[react,react-dom],// 不打包 Reactoutput:{globals:{react:React,react-dom:ReactDOM}}}}})3.3 类型定义与树摇Tree Shaking使用 TypeScript 生成 .d.ts 类型声明文件配置 package.json 的 exports 字段支持 ESM/CJS 双输出确保组件库支持 Tree Shaking使用 ESM 格式避免副作用的导入四、文档站建设Storybook 7Storybook 7 的价值不只是预览组件而是把组件文档、交互测试、视觉回归和设计协作放进同一条工作流。4.1 Storybook 7 的核心价值很多团队第一次接触 Storybook 时都会把它理解成一个“组件预览工具”。但在真实团队里组件开发真正缺的往往是一个展示页而是这些能力组件状态能不能被稳定复现文档和代码能不能一起更新视觉变更能不能更早暴露设计、开发、测试能不能共享同一套组件语义Storybook 7 的真正价值在于把组件语义、文档、测试和协作放进同一条可维护链路。4.2 Storybook 7 配置// .storybook/main.jsexportdefault{stories:[../src/**/*.stories.(js|jsx|ts|tsx)],addons:[storybook/addon-essentials,// 文档、控制台、视口等storybook/addon-interactions,// 交互测试storybook/addon-a11y// 可访问性检查[reference:55]],framework:{name:storybook/react-vite,options:{}},typescript:{check:true,reactDocgen:react-docgen-typescript// 从 TS 类型自动生成文档[reference:56]}}4.3 编写 Stories优秀的 stories 应该围绕组件任务来组织// Button.stories.tsximporttype{Meta,StoryObj}fromstorybook/reactimport{Button}from./Buttonconstmeta:MetatypeofButton{title:Components/Button,component:Button,argTypes:{variant:{control:select,options:[primary,secondary,ghost]}}}exportdefaultmeta// 基础状态exportconstPrimary:StoryObj{args:{label:Submit,variant:primary}}// 关键边界禁用状态exportconstDisabled:StoryObj{args:{label:Submit,variant:primary,disabled:true}}// 高风险交互加载状态exportconstLoading:StoryObj{args:{label:Submit,variant:primary,loading:true}}// 典型业务场景exportconstInForm:StoryObj{render:()(forminput placeholderEmail/Button variantprimarySubmit/Button/form)}4.4 使用 MDX 编写组件文档Storybook 7 支持 MDX 格式将文档和代码示例结合mdx{/* Button.mdx */}import { Meta, Story } from ‘storybook/addon-docs’import { Button } from ‘./Button’Button 组件主要用于触发操作或提交表单。Props属性类型默认值描述variant‘primary’ | ‘secondary’‘primary’按钮样式变体size‘sm’ | ‘md’ | ‘lg’‘md’按钮尺寸示例**五、版本管理与发布** 组件库的版本管理应遵循 Semver语义化版本 规范在 Monorepo 中使用 Changesets 管理组件库的版本发布# 1. 添加 changesetpnpmchangeset# 2. 更新版本号和 CHANGELOGpnpmchangeset version# 3. 构建并发布pnpmbuildpnpmpublish-r六、从组件库到设计系统当组件库成熟后下一步是升级为设计系统Design System 。设计系统不仅是组件库还包含设计系统的建设不是“一次性项目”而是持续的投资——它需要设计、开发、产品三方共同维护。七、小结组件库的四个阶段UI 物料 → UI 组件库 → 业务组件库 → 设计系统。原子设计原子 → 分子 → 组织 → 模板 → 页面为 UI 提供层级结构。组件设计原则单一职责、一致性与可预测性、可组合性、可访问性。Storybook 7不仅是组件预览工具更是把组件文档、交互测试、视觉回归和设计协作整合在一起的团队基础设施。Storybook 7 支持 MDX 文档、TypeScript 类型自动生成和可访问性检查。版本管理遵循 Semver 规范使用 Changesets 管理 Monorepo 中组件库的版本发布。设计系统组件库的终极形态包含设计令牌、设计工具、文档站和治理机制。