本文目录导读：
编写设计稿组件使用说明，核心目标是将“设计意图”和“代码实现”之间的鸿沟填平，让前端开发者能精确还原设计,同时为日后组件的复用和迭代奠定基础。
一份优秀的设计稿组件说明，通常包含 “定义区”、“样式规范”、“状态说明”、“使用约束” 和 “代码关联” 五个部分。
以下是具体的编写指南和模板。
核心编写结构（推荐模板）
你可以直接在 Figma / Sketch / 即时设计 的右侧“备注”栏或“代码”标签页中,按此结构填写。
组件名称与概述
- 名称： 统一使用 [平台-模块-组件名]。
Web-Form-Input或App-Card-Product。 - 用途： 一句话说明这个组件在什么场景下使用。
- 例： “用于用户登录页面输入密码的场景。”
视觉与样式规范（最核心部分）
- 尺寸：
- 固定尺寸：
宽度：320px，高度：48px - 自适应说明：
内容宽度自适应，最小宽度80px
- 固定尺寸：
- 间距： 标注内外边距。
- 例：
内边距：12px（左右），8px（上下） - 例：
与相邻元素间距：16px
- 例：
- 字体与排版：
字号：16px、行高：1.5、字重：Regular（400）、字体：SF Pro Text
- 颜色与填充：
- 背景色：
#FFFFFF - 文字色：
#333333（正常状态）、#CCCCCC（禁用状态） - 不要只说“白色”或“灰色”，务必提供十六进制色值或Design Token名（如
--color-primary）。
- 背景色：
交互状态（必须穷举）
这是前端常容易遗漏的部分,请务必列出所有状态对应的样式变化。
| 状态 | 触发条件 | 视觉变化 | 备注 |
|---|---|---|---|
| 默认 | 初始展示 | 背景：白，边框：1px #E0E0E0 | |
| Hover | 鼠标悬停 | 边框：1px #1890FF，阴影：0 2px 4px rgba | |
| Focus | 获得焦点 | 边框：1px #1890FF，外发光：0 0 0 2px rgba(24,144,255,0.2) |
|
| Error | 输入验证失败 | 边框：1px #FF4D4F，底部出现红色提示文案 | |
| Disabled | 不可编辑 | 背景：#F5F5F5，文字：#BFBFBF，光标：not-allowed | |
| Pressed | 点击按下 | 背景：深色5% |
布局与自适应
- 对齐方式： 左对齐、居中对齐。
- 弹性规则： 描述在父容器变宽/变窄时，组件如何变化。
- 例：
左右边距固定，中间内容自适应（flex:1） - 例：
网格布局下，每列最小宽度200px，列间距16px
- 例：
内容规则与数据
- 最大/最小字符数： 如
标题最多显示15个字符，超出显示省略号“...” - 数据来源： 明确是写死的词条,还是API接口返回。
- 空状态/极限场景：
- 列表无数据时：展示空状态插画。
- 头像未加载时：显示姓名首字母占位图。
与其他组件的关系
- 包含： 该组件内部包含了哪些原子组件？
- 例： “按钮组件由 图标、文字、加载动画 组成。”
- 组合： 该组件通常与什么组件一起使用？
- 例： “输入框通常与提交按钮组合成搜索栏。”
实际编写范例
范例 1：按钮组件 （Button）
组件名： Web-Button-Primary 用途： 页面中主要操作入口（如提交、登录、确认）。
尺寸：
- 高度：40px
- 宽度：自动（由内容撑开，最小宽度：60px）
- 圆角：6px
样式：
- 字体：14px / Regular （400） / #FFFFFF
- 背景色：
--color-primary（#1890FF）- 内边距：水平 24px，垂直 10px
状态：
- Hover：背景色加深 10%（
#40A9FF）- Active：背景色加深 20%（
#096DD9）- Disabled：背景色 #D9D9D9，文字 #FFFFFF（不透明度 60%），无阴影
- Loading：展示旋转图标，文字保留，点击无效
范例 2：卡片组件 （Card）
组件名： App-Card-Product 用途： 商品列表页的单个商品展示。
布局：
- 结构：竖排三行：图片 + 标题 + 价格
- 间距：图片与标题间距 8px，标题与价格间距 4px
- 对齐：全部居中对齐（Center）
自适应：
- 列表容器使用
Grid布局，grid-template-columns: repeat(auto-fill, minmax(160px, 1fr))- 图片宽高比固定
1:1，使用object-fit: cover规则：**- 图片：尺寸 200x200px（@2x 需提供 400x400）
- 标题：最大两行文字，超出显示省略号
- 价格：前置 “¥ ” 符号，保留两位小数
给团队的避坑指南
-
避免“只写视觉描述”
- ❌ 错误： “按钮是蓝色，圆角，好看一点。”
- ✅ 正确： “按钮颜色为
#1890FF，圆角6px，Hover 状态变#40A9FF。”
-
务必明确“自适应逻辑”
- 很多 BUG 出在 “屏幕变窄时，这个输入框是换行？还是缩短？”。
- 建议画一个简单的 “缩放示意图”或直接在备注里写：
min-width: 200px; max-width: 500px;
-
标注“间距”而非“坐标”
- 不要写
组件的位置是 (x:100, y:200)，因为页面是流式布局，应标注margin-top: 16px或与上方元素的间距：16px。
- 不要写
-
图例化（一图胜千言）
当说明很复杂时，在 Figma 里用 “连线 + 文字标签” 的方式标注（例如指向具体的间距数值、字号、颜色）,比纯文字说明更清晰。
-
维护 Design Token 映射表
- 在团队说明的头部，附上 Token 到颜色的映射：
--color-primary=#1890FF--color-danger=#FF4D4F--spacing-unit=8px
- 在团队说明的头部，附上 Token 到颜色的映射：
总结一份 Checklist
当你写完组件说明后,请自己检查一遍：
- [ ] 是否包含 Default（默认）、Hover、Active、Disabled 状态？
- [ ] 是否标注了 字号、字重、行高？
- [ ] 是否标注了 Padding 和 Margin？
- [ ] 是否说明了 父容器变化时的自适应规则？
- [ ] 是否说明了 数据为空、字符超长时的处理？
- [ ] 是否提供了 Design Token 或具体的十六进制色值？
按这个结构写出来的说明，前端开发者几乎不需要再反向追问，可以有效减少 80% 的沟通成本。
标签： 使用指南
版权声明：除非特别标注，否则均为本站原创文章，转载时请以链接形式注明文章出处。
