Figma 组件库文档化(Sticker Sheet)与设计规范页工程化实战:解剖图标注、Props 参数表、Playground 沙盒与 Dev Mode 交付闭环
在团队搭建 Figma 组件库 时,最常见的“半成品陷阱”就是:每个页面里只孤零零摆着一个紫框 Component Set,里面塞了二三十个变体。设计系统作者自己知道哪个变体配哪种圆角、什么时候该开哪个布尔开关,但新入职的业务设计师却只能靠猜,前端工程师切换到 Dev Mode 开发模式 后,面对一排未加说明的 Variant 1 / Property 2 同样一头雾水,最终被迫在微信群里反复截图确认。
即便团队未来会上线 Zeroheight、Supernova 或 Storybook 文档门户(外部平台选型见 设计系统文档门户与规范平台实战),在 Figma 画布内部打造一份高信息密度的“Sticker Sheet(组件规范展示页)”依然是无法替代的第一道防线——因为设计师与研发人员 90% 的日常协作就发生在画布与 Dev Mode 面板里。
一、散装变体页 vs 工程化 Sticker Sheet 文档页核心差异 #
一份真正具备工程化交付价值的组件文档页,应当做到“打开当前 Page,无需口头解释即可直接上手拼页面与写代码”:
| 评估维度 | 散装变体页(仅有 Component Set) | 工程化 Sticker Sheet 文档页(推荐架构) |
|---|---|---|
| 新成员上手成本 | 高,需要翻聊天记录或找老设计师口口相传用法 | 极低:页首状态徽标、使用边界与正反例一目了然 |
| 变量与令牌映射透明度 | 差,前端只能看到某个实例绑了哪个变量,看不到全状态对比表 | 极高:用 Tokens 规范表直观列出默认/悬停/禁用对应的语义变量 |
| 资产面板(Assets)纯净度 | 容易把辅助测试块误发布到全局组件面板 | 100% 受控:所有文档框架、标注图钉均使用 _Doc / 隐藏前缀隔离 |
| Dev Mode 研发交接效率 | 低,研发需要在十几个变体间挨个点开对比间距与字号 | 极高:解剖图直接标注内边距与槽位,配合 Component Playground 实时试参 |
二、工程化 Sticker Sheet 标准五段式页面拓扑 #
为了让团队成员在不同组件(如 Button、Input、Modal、Table)之间形成肌肉记忆,每个组件 Page 推荐严格按照自上而下、纵向 Auto Layout 自动排版的五段式文档画板组织,整体画板宽度可统一设为 1440px 或 1600px:
- Section 1:组件元数据页眉(Header & Governance)
- 包含组件中英文标准名称(如
Modal / 模态弹窗)、当前生命周期状态徽标(Stable 稳定/Beta 公测/Deprecated 废弃)、版本号(如v2.4.0)、适用端(Web / iOS / Android)以及一句话核心职责定位。
- 包含组件中英文标准名称(如
- Section 2:结构解剖图(Anatomy & Slot Breakdown)
- 展示一个放大版的标准组件实例,用带编号圆点的引线标注出各个组成子区域(如
1. Prefix Icon、2. Label Text、3. Slot Container、4. Trailing Action),并在下方紧跟序号对应的元素规范说明(是否必填、最小宽度、字体与截断策略)。
- 展示一个放大版的标准组件实例,用带编号圆点的引线标注出各个组成子区域(如
- Section 3:主组件母版区与状态矩阵(Master Component Set & Matrix)
- 唯一存放紫框
Component Set的区域!建议外围用带有清晰标题的淡灰Section包裹,并按Size × Variant × State整齐网格排列,方便设计系统维护者使用多选编辑(Multi-edit)批量调优。 - 若涉及复合容器组件,建议参考 Slot 插槽工程化架构实战 将槽位与占位符并列展示。
- 唯一存放紫框
- Section 4:Design Tokens 规格与尺寸参数表(Specs & Variables Table)
- 以原生 Auto Layout 表格展示各尺寸档位(
sm / md / lg)的高度、水平内边距、字号、圆角以及绑定的语义变量名(例如height: 36px、padding-x: spacing/3 (12px)、bg: surface/brand/default),让研发一目了然(令牌命名规范见 Design Tokens 标准命名与结构对照手册)。
- 以原生 Auto Layout 表格展示各尺寸档位(
- Section 5:Do & Don't 正反例规范 + 交互沙盒(Playground)
- 用绿框
Do(推荐做法)与红框Don't(禁止踩坑)左右对比真实业务错误案例(如“禁用弹窗内堆叠超过 2 个主按钮”、“禁止长文本不设截断撑破卡片”)。 - 最底部设置一个独立标记为
Ready for Dev的Interactive PlaygroundSection,只放入 1~2 个带有全量交互状态与暴露嵌套属性的复合实例,供研发在 Dev Mode 的沙盒里直接拨动开关验算。
- 用绿框
三、实操一:打造不污染 Assets 面板的 _Doc 文档组件库 #
如果每写一个组件页面都要从头画标题头、编号图钉、表格行和红绿对比卡片,维护成本会高到团队很快放弃更新文档。正确做法是在基础库或独立文档库里先封装一套 _Doc 私有文档辅助组件。
1. 严格使用隐藏前缀防止文档元素泄漏到发布面板 #
- 所有专门用于画文档的辅助组件,必须在命名最前面加上下划线
_或句点.(例如_Doc / Header、_Doc / Callout Pin、_Doc / Spec Row、_Doc / Do-Dont Card),或右键勾选Hide from publishing(详见 组件库发布前隐身治理)。 - 这样一来,哪怕文档组件保存在同一个组件库文件里,业务设计师打开
Assets面板搜“Header”或“Card”时,也绝对不会误把文档图钉拖进真实业务页面。
2. 必建的 4 个高复用文档基座组件 #
_Doc / Page Header:内置标题、Status变体标签(Stable / Draft / Deprecated)、Updated Date文本属性与关联代码仓库链接占位。_Doc / Anatomy Pin:一个20×20px高对比度数字圆点 + 延伸虚线引导线(利用Variant切分上/下/左/右 4 个出线方向),开启自动布局排斥或绝对定位,方便贴在解剖图实例周围。_Doc / Token Pill:胶囊型等宽代码标签(字体用JetBrains Mono或SF Mono),带颜色小圆点预览槽,专门用于在规格表里高亮展示--color-surface-brand或spacing/4。_Doc / Do-Dont Card:包含顶部画布示例展示区(用_Slot占位插槽换入正反例截图或本地实例)+ 底部绿勾/红叉状态条与一句话禁用原因说明。
四、实操二:Component Description 写法与 Dev Mode 交付闭环 #
画布上的 Sticker Sheet 是给人“看大图与结构”的,而选中组件后右侧面板里的 Component Description(组件描述) 与 Dev Resources 则是给 Assets 搜索框与 Dev Mode 研发工具链 消费的“结构化元数据”。
1. 规范化 Component Description 的 Markdown 写法 #
选中最外层的紫框 Component Set(切忌只写在单个子变体上,否则切换变体时会漏掉说明),在右侧 Component configuration 点击铅笔图标填写描述(Figma 支持基础 Markdown、换行与项目符号):
【适用场景】用于页面主行动点触发,同一视图区域内最多仅保留 1 个 Primary 实心主按钮。
【属性契约】
- variant: primary / secondary / ghost / danger
- size: sm (28px) | md (36px) | lg (44px)
- isLoading: 开启时禁用点击事件并保留原按钮宽度防抖动
【检索关键词】btn 按钮 提交 确认 CTA submit action
- 高阶技巧:末尾加上一段中文同义词与英文别名(
btn 按钮 提交 确认),能够极大提升中文设计师在Assets面板用中文搜英文命名组件(如Button)时的命中率! - 若组件有独立外网文档(如 Storybook 或企业内部 Wiki),务必在描述下方粘贴
Documentation link,下游设计师只需点击组件面板上的书本图标就能直达文档(进阶配置与Preferred Values治理见 Component Descriptions 与 Documentation Links 实战)。
2. 打通 Dev Mode 四大研发交付锚点 #
- 将文档页里的状态规范与原生
Annotations结合:对于特殊的交互边界(如z-index层级、防连点节流时间300ms、键盘Esc关闭契约),使用 Dev Mode 原生Annotations(开发标注) 钉在 Playground 实例旁(实操见 Dev Mode 原生 Annotations 与测量线实战)。 - 仅对 Master / Playground 区域标记
Ready for Dev:切忌把整个包含几十个草稿图的 Page 标成绿标;只对整理完备的Section 3(母版)或Section 5(Playground)打标Ready for Dev。 - 挂载
Dev Resources双向跳链:选中组件母版,在 Dev Mode 右侧Dev resources栏填入对应 GitHub 组件源码路径(如packages/ui/src/Button/Button.tsx)与 Storybook 预览链接,此链接会自动透传到全公司所有业务文件里的每一个按钮实例上。 - 联动 Code Connect 与 Expose Nested Instances:如果按钮内部嵌套了图标或徽标,务必在母版开启
Expose properties from nested instances;如果团队已启用 Code Connect UI 可视化映射,确保 Sticker Sheet 文档里的 Props 命名与代码仓库 TypeScript 接口 100% 同名。
五、组件文档化常见踩坑与防失真排查表 #
在推行 Sticker Sheet 文档体系的过程中,以下 5 个高频痛点最容易导致“文档写完就过时、甚至拖垮组件库性能”:
| 踩坑现象 | 底层原因定位 | 标准化治理与防呆方案 |
|---|---|---|
| 文档页做了几十个组件案例后,整个组件库内存暴涨、打开卡顿 | 在每个组件的 Sticker Sheet 页面里塞进了大量高分辨率 PNG 截图,或复制了上百个重度嵌套的复杂全页组件作为正反例 | Do & Don't 案例严格用轻量化局部原生组件实例搭建,禁止堆砌整页大截图;长篇大论与视频 GIF 放进外部文档门户,只通过 Documentation link 跳转 |
设计师在 Assets 面板搜 Card 时,搜出一堆文档用的 Do-Dont Card 与 Spec Table | 创建 _Doc 辅助组件时未加下划线 _ / 句点 . 前缀,且未在发布面板取消勾选发布 | 立即重命名为 _Doc / * 并在右侧设置或发布弹窗中勾选 Hide from publishing,重新 Publish 一次即可从全员资产面板净化 |
| 明明在 Sticker Sheet 改了主组件,但页面顶部解剖图还是旧样式 | 制作 Anatomy 解剖图时不小心把主组件做成了硬拷贝或提前 Detach instance(解绑) 了 | 解剖图与规格展示里的图样必须使用主组件的“实时实例(Live Instance)”,绝不解绑!这样母版一改,全页文档示意图同步实时更新 |
在 Dev Mode 点击 Explore component behavior 沙盒时,里面的下拉选项跟文档写的对不上 | 紫框 Component Set 里残留了历史遗留的隐藏属性或变体命名拼写不统一,且未对嵌套子组件启用属性暴露 | 定期清理 组件属性架构 中的冗余 Variant;开启 Expose nested instances;使用 Propstar 等插件一键刷新组件规格矩阵 |
| 前端按文档写了代码,后来设计师改了内边距却忘了改文档规格表,导致规范撕裂 | 手工敲字填在文本表格里的 padding: 12px 是静态死文本,不会随组件 Auto Layout 数值自动同步 | 表格数值直接标注绑定的 Design Token 变量名(如 spacing/3)而非纯数字,或配合原生 Measurements 永久测量线直接锚定真实实例的间距(自动随组件修改实时跳数) |
核心手册与速查工具
高频手册与实用设计生产力工具直达常见问题与答疑 (FAQ)
高频疑难解析与避坑指南完全不需要。绝大多数核心功能在免费 Starter 计划中均可完整体验与实操练习,无需额外付费购买付费团队版。