ARTICLE · 1010295
组件库搭建指南:设计规范 + 组件文档 + 前端实现思路
组件库搭建指南
设计规范 · 组件文档 · 前端实现思路
上一篇我们聊了 B 端页面从需求到交付的完整流程，其中提到了「组件库落地」这个环节。这篇文章把它展开，从零讲清楚怎么搭建一套能用、好用、可持续维护的组件库。
组件库不是设计师在 Figma 里画几个按钮就完了。它需要三个层面的支撑：设计规范（定义长什么样）、组件文档（说明怎么用）、前端实现（让设计稿变成代码）。这三者缺一不可。
下面我们逐个拆开来讲。
1.1 Design Token 体系 / 1.2 色彩 / 1.3 字体 / 1.4 间距与栅格 / 1.5 圆角与阴影
二、组件文档：让所有人都能正确使用
2.1 组件分类 / 2.2 文档结构 / 2.3 命名规范 / 2.4 版本管理
三、前端实现：从设计稿到可用代码
3.1 技术选型 / 3.2 目录结构 / 3.3 组件开发范式 / 3.4 主题方案 / 3.5 与设计工具的衔接
四、常见问题与避坑指南
一、设计规范：组件库的基石
Design Specification
设计规范是组件库的「宪法」。所有组件的视觉表现，都必须从这套规范中派生出来。如果规范不清晰，组件就会各自为政，最后变成一堆拼凑的零件，而不是一套系统。
1.1 Design Token 体系
一切规范的起点
Design Token 是组件库最底层的设计资产。它把颜色、字号、间距等视觉属性抽象成一组可命名、可复用、可映射到代码的变量。
为什么要用 Token 而不是直接写色值？因为 Token 是设计和开发之间的公共语言。设计师说「这个按钮用 color-primary」，开发知道是 var(--color-primary)，两边对得上。
三层 Token 的关系：
语义 Token：赋予含义的别名，如 color-primary = blue-500。表达的是「做什么」而不是「是什么」。
组件 Token：绑定到具体组件的属性，如 button-bg-primary = color-primary。换主题时只需改语义 Token，组件自动跟着变。
1.2 色彩系统
少即是多
B 端色彩系统的核心原则：主色少，功能色准，中性色够用就行。
1.3 字体系统
稳定比好看更重要
B 端字体选择的首要原则：系统默认字体优先。不要为了好看引入自定义字体——B 端页面文字量大，自定义字体的加载时间会严重影响首屏体验。
1.4 间距与栅格
4px 基准，一切皆倍数
间距系统是 B 端设计中最容易出错、也最影响视觉一致性的部分。规则很简单：所有间距值必须是 4 的倍数。
栅格方面，B 端常用的是 24 栏栅格，内容区最大宽度通常为 1200px 或 1440px。侧边栏宽度固定（通常 200-240px 折叠态 64px），内容区自适应。
1.5 圆角与阴影
微小的差异，巨大的秩序感
圆角建议定义 3-4 级就够了：
阴影建议定义 3 级：
shadow-md：0 4px 12px rgba(0,0,0,0.08) — 弹窗、浮层
shadow-lg：0 8px 24px rgba(0,0,0,0.12) — 模态框、全屏弹层
· Design Token 体系（基础层 → 语义层 → 组件层）
· 色彩系统（主色 + 功能色 + 8-10 级灰阶）
· 字体系统（5-6 级字号阶梯）
· 间距系统（4px 基准，6-8 级阶梯）
· 圆角（3-4 级）与阴影（3 级）
· 图标规范（尺寸、线宽、风格统一）
二、组件文档：让所有人都能正确使用
Component Documentation
设计规范定好了，接下来要把每个组件的使用方式文档化。好的组件文档不只是给设计师看的，产品、开发、测试都需要能看懂。
2.1 组件分类
B 端组件库通常把组件分为以下几类：
实际项目中，还会有一类「业务组件」——基于通用组件组合而成、承载特定业务逻辑的高阶组件。比如「审批流程节点」「高级搜索面板」「数据筛选器」等。
2.2 单个组件的文档结构
每个组件的文档应该包含以下内容，缺一不可：
以 Button 为例，API 属性表应该长这样：
2.3 命名规范
组件命名是设计师和开发最容易扯皮的地方。建议在项目启动时就定好规则：
btn / btn--primary / btn__icon前端组件命名：PascalCase，如
Button / Button.Group / DatePicker.RangePickerCSS 类名：kebab-case + 命名空间前缀，如
.my-btn / .my-btn--primary / .my-btn__iconToken 命名：层级-类别-语义-状态，如
color-bg-primary-hover / spacing-component-padding2.4 版本管理
组件库一定要做版本管理，否则迟早会乱。建议：
· 主版本（1.0 → 2.0）：不兼容的 API 变更
· 次版本（1.0 → 1.1）：新增组件或功能，向下兼容
· 修订版本（1.0.0 → 1.0.1）：Bug 修复、样式微调
· 每次发布附带 Changelog，说明改了什么、影响哪些组件
· Figma 组件库用 Page 或 Section 区分版本，或使用 Figma 的 Branch 功能
· 每个组件有完整的 7 段式文档结构
· API 属性表覆盖所有 props，含类型、默认值、说明
· 命名规则在项目开始时就定好，全团队统一执行
· 版本号和 Changelog 跟踪每次变更
三、前端实现：从设计稿到可用代码
Frontend Implementation
设计规范和组件文档解决了「是什么」和「怎么用」的问题，前端实现解决的是「怎么做成代码跑起来」的问题。
3.1 技术选型
组件库的技术选型需要考虑几个维度：
3.2 目录结构
一个典型的组件库目录结构：
my-ui/ ├── components/ // 组件源码 │ ├── button/ │ │ ├── index.tsx // 组件实现 │ │ ├── index.less // 组件样式 │ │ ├── index.test.tsx // 单元测试 │ │ ├── index.md // 组件文档 │ │ └── interface.ts // 类型定义 │ ├── input/ │ ├── table/ │ └── ... ├── styles/ // 全局样式 │ ├── tokens.less // Design Token │ ├── reset.less // 样式重置 │ └── mixins.less // 样式函数 ├── docs/ // 文档站源码 ├── .umirc.ts // 文档站配置 ├── package.json ├── tsconfig.json └── README.md
关键原则：每个组件一个文件夹，所有相关文件（实现、样式、测试、文档、类型）都放在一起。这样维护的时候不用满项目找文件。
3.3 组件开发范式
以 React + TypeScript 为例，一个 Button 组件的基本写法：
export interfaceButtonProps { type?: 'primary' | 'default' | 'dashed' | 'text' | 'link'; size?: 'large' | 'middle' | 'small'; disabled?: boolean; loading?: boolean; icon?: React.ReactNode; onClick?: (e: React.MouseEvent) => void; children?: React.ReactNode; }
import React from'react'; import classNames from'classnames'; import { ButtonProps } from'./interface'; import'./index.less'; constprefixCls = 'my-btn'; constButton: React.FC<ButtonProps> = ({ type = 'default', size = 'middle', disabled = false, loading = false, icon, onClick, children, }) => { const cls = classNames(prefixCls, { [`${prefixCls}--${type}`]: type, [`${prefixCls}--${size}`]: size, [`${prefixCls}--disabled`]: disabled, [`${prefixCls}--loading`]: loading, }); return ( <buttonclassName={cls} disabled={disabled} onClick= {onClick}> {loading && <spanclassName="${prefixCls}__loading" />} {icon && <spanclassName="${prefixCls}__icon">{icon}</span>} <span>{children}</span> </button> ); }; export default Button;
几个关键点：
2. 样式类名用前缀：避免全局污染，如 my-btn--primary 而不是 .primary。
3. 属性有默认值：保证组件在不传任何 props 时也能正常渲染。
4. classnames 库：动态拼接类名的标准做法，比手动拼字符串干净得多。
5. 组件导出方式：default export 用于单组件，命名 export 用于类型。
3.4 主题方案
B 端组件库经常需要支持换肤——同一套组件在不同客户那里需要不同的品牌色。实现主题切换有三种主流方案：
/* 默认主题 */:root { --color-primary: #1f6feb; --color-bg: #ffffff; } /* 深色主题 */[data-theme="dark"] { --color-primary: #388bfd; --color-bg: #0d1117; }
3.5 与设计工具的衔接
设计和开发之间最大的痛点是信息不同步。设计师改了一个颜色，开发不知道；开发发现某个交互实现不了，反馈不回去。解决这个问题需要建立几条通道：
具体来说，推荐以下几个实践：
2. 组件命名一致：Figma 里的组件名和代码里的组件名必须完全对应。Button 就是 Button，不要设计师叫「按钮」开发叫 Btn。
3. 定期走查对齐：每两周做一次设计走查，对比设计稿和线上实现的差异，记录偏差清单。
4. 共享组件 API 文档：把组件文档放在设计师和开发都能访问的地方（如 Notion / Confluence / 内部文档站）。
· 选型跟团队主栈走，TypeScript 必选
· 每个组件一个文件夹，实现/样式/测试/文档/类型放在一起
· 类型定义（interface）单独文件，方便复用
· 主题方案推荐 CSS 变量（兼容性允许的话）
· 和设计工具之间建立 Token 同步 + 命名一致 + 定期走查的协作机制
四、常见问题与避坑指南
踩过的坑就不用再踩了
· 向下兼容：尽量不在小版本中做破坏性变更
· 变更日志透明：每次更新都发 Changelog，标注影响范围
· 自动化检测：用 CI 脚本检测项目中使用的组件版本，落后太多就发告警
· 定期升级日：每月固定一天作为「组件库升级日」，集中处理升级工作
· 组件覆盖率：业务页面中使用组件库组件的比例（目标 > 80%）
· 页面搭建效率：一个新页面从设计到上线的平均耗时是否下降
· 设计还原度：走查时发现的偏差数量是否逐月减少
· 组件复用率：单个组件在多少个页面中被使用
最后
组件库建设这件事，说到底是工程思维在设计领域的落地。
它不是画几套好看的页面就完了，而是要把设计决策系统化、可复用、可演进。设计规范定义标准，组件文档降低沟通成本，前端实现保证落地质量——三者形成闭环，组件库才能真正发挥价值。
最后分享一个判断组件库是否成功的简单标准：一个新来的设计师或开发，能不能在半天之内，只靠看文档就用组件库搭出一个完整的页面？
如果能，说明你的组件库做得不错。如果不能，回去检查一下，大概率是文档的问题。