Figma 组件库文档化(Sticker Sheet)与设计规范页工程化实战:解剖图标注、Props 参数表、Playground 沙盒与 Dev Mode 交付闭环

2026 年 11 月 20 日

在团队搭建 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:

  1. Section 1:组件元数据页眉(Header & Governance)
    • 包含组件中英文标准名称(如 Modal / 模态弹窗)、当前生命周期状态徽标(Stable 稳定 / Beta 公测 / Deprecated 废弃)、版本号(如 v2.4.0)、适用端(Web / iOS / Android)以及一句话核心职责定位。
  2. Section 2:结构解剖图(Anatomy & Slot Breakdown)
    • 展示一个放大版的标准组件实例,用带编号圆点的引线标注出各个组成子区域(如 1. Prefix Icon、2. Label Text、3. Slot Container、4. Trailing Action),并在下方紧跟序号对应的元素规范说明(是否必填、最小宽度、字体与截断策略)。
  3. Section 3:主组件母版区与状态矩阵(Master Component Set & Matrix)
    • 唯一存放紫框 Component Set 的区域!建议外围用带有清晰标题的淡灰 Section 包裹,并按 Size × Variant × State 整齐网格排列,方便设计系统维护者使用多选编辑(Multi-edit)批量调优。
    • 若涉及复合容器组件,建议参考 Slot 插槽工程化架构实战 将槽位与占位符并列展示。
  4. 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 标准命名与结构对照手册)。
  5. Section 5:Do & Don't 正反例规范 + 交互沙盒(Playground)
    • 用绿框 Do(推荐做法) 与红框 Don't(禁止踩坑) 左右对比真实业务错误案例(如“禁用弹窗内堆叠超过 2 个主按钮”、“禁止长文本不设截断撑破卡片”)。
    • 最底部设置一个独立标记为 Ready for Dev 的 Interactive Playground Section,只放入 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 个高复用文档基座组件 #

  1. _Doc / Page Header:内置标题、Status 变体标签(Stable / Draft / Deprecated)、Updated Date 文本属性与关联代码仓库链接占位。
  2. _Doc / Anatomy Pin:一个 20×20px 高对比度数字圆点 + 延伸虚线引导线(利用 Variant 切分上/下/左/右 4 个出线方向),开启自动布局排斥或绝对定位,方便贴在解剖图实例周围。
  3. _Doc / Token Pill:胶囊型等宽代码标签(字体用 JetBrains Mono 或 SF Mono),带颜色小圆点预览槽,专门用于在规格表里高亮展示 --color-surface-brand 或 spacing/4。
  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 四大研发交付锚点 #

  1. 将文档页里的状态规范与原生 Annotations 结合:对于特殊的交互边界(如 z-index 层级、防连点节流时间 300ms、键盘 Esc 关闭契约),使用 Dev Mode 原生 Annotations(开发标注) 钉在 Playground 实例旁(实操见 Dev Mode 原生 Annotations 与测量线实战)。
  2. 仅对 Master / Playground 区域标记 Ready for Dev:切忌把整个包含几十个草稿图的 Page 标成绿标;只对整理完备的 Section 3(母版) 或 Section 5(Playground) 打标 Ready for Dev。
  3. 挂载 Dev Resources 双向跳链:选中组件母版,在 Dev Mode 右侧 Dev resources 栏填入对应 GitHub 组件源码路径(如 packages/ui/src/Button/Button.tsx)与 Storybook 预览链接,此链接会自动透传到全公司所有业务文件里的每一个按钮实例上。
  4. 联动 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)

高频疑难解析与避坑指南
A

完全不需要。绝大多数核心功能在免费 Starter 计划中均可完整体验与实操练习,无需额外付费购买付费团队版。