我们做过一个挺像样的组件库:42 个组件,一套完整的文档站,每个组件都有 API 表格、代码示例、设计规范链接。上线一年后做了一次代码扫描,发现线上页面真正 import 过的组件只有 9 个,而且是「Button、Input、Modal、Table」这种最基础的。同一时间,业务仓库里躺着 6 套自己写的按钮:一套圆角 4px,一套圆角 2px,一套带渐变,还有一套「因为设计师说这个场景要不一样」。
更扎心的是,那 33 个没人用的组件,每个都有人维护过:改过 bug、升过依赖、写过文档。维护成本一直在付,收益接近于零。这不是组件写得好不好的问题,是设计系统的定位错了——我们把它当成了一个「组件交付项目」,做完就结束了;而它实际上是一个需要持续运营的产品。
这篇讲我们后来怎么重构这件事:先砍掉大半组件,把契约从「组件」下移到「token」,再补上采用度度量和版本策略。同时把不划算的边界说清楚——有些团队根本不该自建设计系统,用现成的改主题就够了。
先搞清楚为什么没人用
「业务不用组件库」这件事,通常有四个原因。找错原因,后面的改造全是白费。
一是 API 不匹配。业务要的是一个「带搜索、带分页、带批量操作」的列表页,组件库给的是一个「Table,支持 columns 和 dataSource」。差的不是组件,是一整套场景。业务只能自己拼,拼完发现还不如自己写。
二是接入成本高。为了用一个按钮,要引一个 300KB 的包,要配一套构建插件,要接受它自带的全局 reset 样式。算下来不如复制 20 行 CSS。
三是视觉不同步。设计稿改了两轮,组件库还是旧样式,业务等不及,直接在页面上覆盖样式。覆盖一次两次还行,覆盖多了,组件库在业务眼里就成了「需要绕开的东西」。
四是没人对结果负责。组件库有维护者,但没有「采用率」这个指标。做完一个组件,发版,写 changelog,任务就算关闭。至于有没有人用、用了之后体验如何,没人知道,也没人问。
那次决策:砍到只剩契约
重构之前,我们列了当时的约束,因为「设计系统该做多大」完全取决于这些条件。
| 约束 | 实际情况 | 对方案的影响 |
|---|---|---|
| 产品线 | 3 条,界面风格高度相似,都是表单加表格 | 组件复用有基础,但场景差异集中在少数页面 |
| 前端人力 | 20 人分布在 4 个团队,组件库只有 1 人兼职维护 | 不能维护大而全的库,组件数量必须克制 |
| 品牌改版 | 大约每半年一次,颜色和圆角会调 | 必须有 token 层,否则每次改版都要改组件 |
| 存量系统 | 两个 jQuery 老后台,不可能迁移 | 设计系统要能输出纯 CSS,不绑定框架 |
| 设计协作 | 设计用 Figma,有规范文档但没人看 | 规范要从文档变成可执行的变量 |
我们比较了四种做法,最后选了看起来最不「完整」的那个。
A. 继续做大而全的组件库
按设计稿逐个实现,追求覆盖所有场景。好处是「什么都有」,代价是维护者会被 42 个组件的 issue 淹没,每个组件都停在「能用但不够好」的状态。兼职一人根本扛不住。
B. Headless 组件 + 业务自己写样式
组件只提供行为和无障碍,样式全交给业务。灵活度最高,但对我们这种「视觉高度统一」的产品是灾难:每个团队都会写出不一样的表格,最后又要回头收口。
C. Token 为契约 + 少量基础组件 + 场景组件留在业务
颜色、间距、圆角、字体、阴影收敛成 CSS 变量;只维护 10 个左右高频基础组件;带业务语义的组件(比如订单卡片)不进库。这是我们最后选的。
D. 直接用成熟第三方库改主题
省掉大部分开发和维护,代价是品牌差异只能做到「换色换圆角」,深度定制要和库的实现方式对抗,升级大版本时尤其痛苦。我们把它作为基础组件的底座,而不是全部。
选 C 的核心理由是「维护成本必须可预测」。10 个基础组件的 API 面很小,一个人兼职能守住;token 是纯数据,改版时只动变量不动组件;场景组件留在业务,谁用谁维护,不会把业务逻辑污染到通用层。代价也很明确:业务仍然要写一些重复的页面结构,这部分我们接受了。
/* tokens.css:唯一允许出现具体色值的地方 */
:root {
--color-text: #1c1c1a;
--color-text-muted: #6b6b66;
--color-surface: #fbfaf7;
--color-border: #d8d5cc;
--color-accent: #2f5d50;
--space-1: 4px;
--space-2: 8px;
--space-3: 12px;
--space-4: 16px;
--radius-sm: 4px;
--radius-md: 8px;
--font-sans: system-ui, -apple-system, "Segoe UI", sans-serif;
}
/* 暗色主题只换变量,组件代码一行不动 */
[data-theme="dark"] {
--color-text: #e8e6e0;
--color-surface: #1b1e22;
--color-border: #34383d;
--color-accent: #7fb3a2;
}
token 的命名是最容易吵架的地方。我们的规则是「按用途命名,不按外观命名」:--color-text-muted 而不是 --color-gray-500。前者在改版时语义不变,后者一旦色板调整,名字就变成谎言。这条规则省掉了后面无数次「这个灰是哪个灰」的讨论。
组件边界:什么该进库,什么不该
我们的判断标准只有一条:这个组件在两个以上产品线里,交互行为完全一致吗?一致才进库。只是长得像,不算。
按这条标准,Button、Input、Select、Checkbox、Modal、Table、Tabs、Tooltip、Toast、Pagination 进了库。订单卡片、商品选择器、审批流节点、富文本编辑器全部留在业务——它们长得像,但字段、校验、权限、联动逻辑都不一样,硬塞进库只会让 props 越堆越多。
反面案例是我们早期的 Table。为了「通用」,它加了 28 个 props:支持固定列、树形数据、行合并、虚拟滚动、自定义筛选、列设置、导出……每个 prop 都对应一个业务的特殊需求。结果是没人敢改它,因为不知道哪个 prop 被谁用着;新业务也不敢用,因为文档根本读不完。后来我们把它拆成「基础 Table + 业务自己组合」,库里的 Table 只剩 9 个 props,使用量反而涨了三倍。
orderStatus、approvalNode),就说明它已经不是通用组件了。这类东西进库的当天很省事,半年后会变成所有人都不敢动的祖传代码。版本与发布:让业务敢升级
设计系统最现实的死法不是没人用,而是「没人敢升级」。业务锁在 1.2 版本,库已经到 2.0,中间隔了 8 个 breaking change,谁都不敢动。最后库变成了只服务于新项目的摆设。
我们的做法是三条:
第一,破坏性变更必须少而集中。能加 prop 解决的,绝不改 prop 语义。确实要改的,攒到一个大版本一起发,配迁移文档和 codemod。零散的小破坏最伤人,因为它让业务每次升级都要重新评估。
第二,样式变更不算补丁。很多人把「只改了颜色」当成 patch 发出去,结果业务页面视觉全线变化,回归测试挂了才发现。视觉变更至少是 minor,涉及布局的要当 breaking 处理。
第三,同时只维护两个大版本。1.x 只修安全问题,2.x 接新功能,第三个大版本出来时 1.x 停止支持。这条规则让「升级」有了明确的时间压力,而不是无限期拖延。
还有一件小事很关键:changelog 要写「影响」而不是「改动」。「修复 Button 在 disabled 状态下的点击穿透」是改动;「disabled 的按钮不再触发 onClick,依赖此行为的代码需要加判断」才是影响。业务看的是后者。
比版本号更难的是「谁来决定加不加一个组件」。我们试过完全开放,结果半年内多了二十个半成品,每个都有人提 PR、没人负责维护;也试过完全由维护者拍板,结果业务嫌流程慢,直接绕开。最后落成一个很轻的门槛:任何新组件先在业务仓库里活两周,被第二个团队主动复制走,才有资格进库;进库时必须带三个真实场景的示例和一条视觉回归基线。这个规则听着慢,但它筛掉了大部分「只用一次」的需求,也让进库的组件从一开始就有明确的消费者。
文档、示例和视觉回归
文档站最大的问题不是写得不好,是「和实现不同步」。手写的示例三个月后一定过期,然后新人照着示例跑不通,从此不再信任文档。
解决办法是把示例变成可运行、可截图、可测试的资产:每个组件的示例就是一个真实的页面文件,构建时自动渲染,文档站直接引用;CI 里对每个示例做截图,和基线比对,差异超过阈值就阻断。这样文档过期会先让 CI 变红,而不是等用户发现。
视觉回归测试的维护成本要提前想清楚。我们最初给每个组件截 6 个状态,一共 200 多张图,每次改字体渲染都会红一片。后来缩减到「每个组件两个关键状态」,只在 Chromium 上跑,成本降到一个小时能看完,才有可持续性。
注意这里没有「设计规范文档」这一层。规范当然要有,但它的载体应该是 token 和示例,不是一份没人读的 PDF。
真实踩的坑
重构之后一年,遇到的问题基本都在下面这张表里。它们不是「用错了 API」,而是长期维护中必然会遇到的磨损。
| 现象 | 真实原因 | 第一步查什么 |
|---|---|---|
| 组件库没人用,业务重复造轮子 | API 不匹配场景,或接入成本高于自己写 | 统计 import 覆盖率;访谈两个业务团队问真实阻力 |
| 升级一个小版本,页面样式多处错乱 | 业务靠后代选择器和全局 class 覆盖样式 | 全局搜 !important 与组件内部 class 名 |
| 同一个按钮出现三种圆角 | token 没收口,页面里硬编码了 px 和色值 | grep 十六进制色值与 border-radius |
| 组件 props 越加越多,没人敢改 | 业务逻辑被塞进通用组件 | 看 props 列表里有没有业务名词 |
| 设计改版要改三个月 | 没有 token 层,组件与视觉稿一一对应 | 检查颜色、间距是否都走变量 |
| 文档示例跑不起来 | 示例手写、没进 CI | 看示例是否来自可运行文件,CI 是否渲染 |
| 引一个按钮,包大了 300KB | 桶文件全量导出,或组件内部引了重型依赖 | 看产物分析里该组件的依赖树;检查是否支持按需引入 |
第一行和第四行往往是同一个病:库想解决所有人的问题,结果谁的问题都没解决好。克制是设计系统最重要的能力,比组件写得好不好重要得多。
边界与代价:什么时候不该自建
设计系统是一个典型的「有规模才划算」的投入。几条线供参考:
前端少于 10 人、只有一条产品线,不要自建。选一个成熟的第三方库,改主题变量,写好使用约定,足够了。自建的成本不是开发,是后面三五年的维护和升级。
视觉差异不是核心竞争力,不要自建。如果你的界面和竞品看起来差不多,用户也不会因为按钮圆角选择你,那自建设计系统只是在重复造一个更差的轮子。
没有设计侧长期投入,不要自建。设计系统一半是设计问题:token 体系、组件状态、无障碍标准。只有前端单方面推,最后一定变成「把设计稿翻译成代码」,翻译完就没人管了。
维护者少于一个人力,规模必须砍。我们一开始 42 个组件配 1 个兼职,注定烂尾。后来 10 个组件配 1 个兼职,才真正转得动。组件数量和维护人力要匹配,这条比任何架构原则都实在。
维护者换人时,设计系统会经历一次生死。交接如果只传代码不传判断标准,新人会开始「顺手加功能」,半年后又回到大而全的老路。我们的做法是把「为什么不做某个组件」「为什么这个 API 只留这几个 prop」写进决策记录,和代码放在一起。文档不是给别人看的门面,是让下一个人少走弯路的说明书。
还有一个隐性代价:设计系统会让「特殊需求」变慢。业务想做一个不一样的交互,得先说服设计系统维护者,或者绕开它。这个摩擦是必要的,但要提前和产品沟通,否则会被理解成「前端偷懒」。
无障碍是最容易被排到「以后再做」的一项,但它其实应该跟着组件一起做。焦点顺序、键盘操作、颜色对比度、屏幕阅读器标签,这些如果在组件层解决,业务接入时不用再想;如果留到页面层补,每个业务都会补得不一样。我们后来给每个基础组件加了一份无障碍检查清单,CI 里用自动化工具跑一遍能查的部分(对比度、可访问名称、ARIA 属性合法性),人工只负责键盘路径和读屏体验。这部分投入不大,但能避免上线后被合规检查打回来重做。
今天就能动手的五件事
一、数一数硬编码。在业务仓库里 grep 十六进制色值和 border-radius,看看有多少处没走变量。这个数字直接反映 token 的实际覆盖率。
二、算一算采用率。用正则或 AST 统计页面里 import 组件库的次数,再数一数业务自己写的基础组件(Button、Input、Modal)。两个数字放在一起,健康度一目了然。
三、给一个组件写三个真实场景。不要写「基础用法」,写业务里真实出现的三种情况:表单校验失败、禁用态加提示、超长文本。写不出来,说明这个组件的 API 还不成立。
四、加一张截图基线。挑最常用的三个组件,用 Playwright 各截两个状态,存成基线,接进 CI。先感受一下视觉回归的误报率,再决定要不要扩大范围。
五、走一次升级。让一个业务项目从旧版本升到最新版本,记录花了多久、卡在哪。这个体感比任何「版本策略」文档都有说服力。
小结
设计系统的核心不是组件数量,而是「契约」:token 定义视觉,基础组件定义行为,场景留给业务。它需要有人对采用率负责,需要克制地拒绝不合适的需求,需要让升级这件事持续发生。
组件收口之后,页面的「长相」统一了,但线上出问题时我们依然抓瞎:用户说白屏,我们只能看到一句 Script error.。下一篇讲前端监控,把这双眼睛补上。