如何写好一篇专业的组件文档？

疯牛叔叔

杭州/设计爱好者/3年前/1035浏览

版权

如何写好一篇专业的组件文档？

疯牛叔叔

阿里内部中台设计分享全记录

2020-11-27 设计双周会分享记录

一个【标签 Tag】组件的故事

大家下午好
前面几位同学分享了比较宏观的设计策略和打法，接下来我会分享一个非常基础的组件故事。先来看一下通过本次分享，你能解锁什么新姿势？

📖 了解「业务组件」0-1的过程
💗 让开发同学爱上你的设计稿
💰 发掘你手上未开垦的业务新油田

今天的主题是《一个「Tag 标签」组件的故事》，标签长啥样（如图）大家应该都不陌生，随处可见，非常简单，有啥可讲的？今天就给大家唠个20分钟～

2020上半年我们有一起小事故，在CPO线的业务中的一个业务方大佬来问我们“咦，这些应用都是你们都是一个团队的，为啥不同页面差那么多呀？”「标签」就是其中一个始作俑者，（如图）是我们目前存在的场景，然后联合业务设计同学小黄就一起，我们开始着手治理这个组件的问题。

开整之前，我们现要理解一个技术背景，2019年我们技术栈全部基于Fusion了，所以要评估此次的改动是否能在Fusion底层的组件结构上支持。这就会涉及到我们是优化“Fusion 基础组件”还是新增“DEEP 业务组件”，Fusion兼顾的是集团整体通用能力，所以在能力优化上会存在周期性，且不会提供过度定制化的能力。“DEEP 业务组件”的话由我们团队前端研发，相对敏捷，也能兼顾我们特有业务场景的需求。

哦，应该还是有不少同学不理解“Fusion 基础组件”和“DEEP 业务组件”的区别吧。举个例子🌰，（如图）乐高的基础元素砖块🧱就是一种基础组件，有2*2，2*3，2*4，3*3等基础单元，有平板、圆弧、连接杆等多种基础形，玩家可以通过这些基础组件DIY出各种造型。但（如图）中的马里奥就是一个在Nintido主题下新增的内容，比如“问号箱子”“云朵”“反派库巴”这些都是为马里奥主题定制的业务组件。

再来看一张图，左边是乐高基础砖块拼成的树，右侧是独立开模制作的树。可以看到基础砖块是万能的，它是原子级物料，三生万物无所不能，但最终效果肯相对抽象，是“树”但不是完美的树。右侧的图中模具呈现了更完美的树，还拓展出了多种属种，即插即用，是特定场景的最佳解决方案。当然它也会使用基础砖块的底座，来和大场景进行更标准化的衔接。这下你应该了解了吧？

好，小黄同学基于业务需求场景输出了初版「Tag 标签」规范，中台介入后进入下一个熟悉的流程：

对比行业 Design Guideline，这里不做赘述，但最重要的准则是Follow业界底层的开发框架，仅在分类和样式上完成规范的制定来满足自身的最佳消费方式。

然后我们输出了一份中台优化版的组件文档。对比之后，我们先来看一下小黄同学的原始业务文档有哪些好的和不足：

然后我们一起看一下优化后的文档，文档可以概括为如下几块：

1组件定义：简介
2引用组件：告知该组件对其它原子组件的引用关系，原子组件的变化会直接体使该组件联动
3基础能力：描述通用的能力
4样式分支：描述组件默认的几种样式选择，以及能被扩展到什么程度
5最佳实践：在组件使用的上下文中的过渡交互以及描述应用场景容易引起的体验偏差

概括一下，我们基本可以通过（下图）来理解这个组件的全貌

最后一步，经过我们的首席前端褚天和业界顾问小强金牌认证🏅️后，我们以“组件包”和“设计指引文档”2份产出物输出。

总会有人说这样冗长的文档就和Switch游戏机说明书一样，没人看呀。其实每一个设计系统都一定会存在文档，它的价值在于不断缩小输出和接收之间的断层，在单一业务场景中可能仅会用到30%，但将缜密的能力更直观地辅助业务正确使用物料即是中台的职责所在，是对使用标准化的指导并间接影响着应用产出的品质。

可以看一下从Fusion基础文档到 DEEP 文档后的增量，Fusion解的是全面而详尽的分镜和聚焦于组件本身的基础交互，我们在集合自身业务场景的需求后补充了额外的3类信息量。

接下来是颁奖环节，这2位同学最近参与了基础组件的共建，除了刚才小黄的标签组件，在阿里大脑的数据场景，我们将业务最前沿的颜色语义沉淀为中台通用能力，滋养更多的旁系业务。

没拿小礼品🎁的同学怎么办？
过年前你们可以获得这2样东西，新站点会将现存的中台零碎能力整合，一个站点解所有。然后基于Fusion迁移后的全量新文档会上线，哪里不懂点哪里，用最专业的文档堵死甲方的突发奇想（指不着边际的过度自定义无理需求）。然后组件包同步上线，目前「图标库」和「插图库」已经发布了大家也用了一段时间了，欢迎反馈使用的意见👏