本文目录导读：
- 📄 第一部分：总览与基本原则
- 🎨 第二部分：基础视觉元素（Design Tokens）
- 🧱 第三部分：核心组件库（Components）
- ✍️ 第四部分：撰写与表达技巧
- 🚀 第五部分：文档结构与维护
- 📦 示例：一个“按钮”组件的规范写法
- 💡 推荐工具
编写一份优秀的设计稿设计规范文档（通常称为 Design System 或 UI Kit 文档），其核心目标是统一团队语言、保证视觉一致性、提升开发和设计协作效率。
一份好的设计规范文档不仅是一份视觉指南，更是一份“产品基础设施说明书”。
以下是一份标准的设计规范文档大纲及撰写要点，分为 5 个核心模块。
📄 第一部分：总览与基本原则
文档目的与范围
- 背景： 为什么要写这份规范？（解决多版本混乱、提升跨部门协作效率、新品牌升级等）
- 适用对象： 设计师、前端开发、产品经理。
- 阅读与使用规则： 如何查找组件？更新迭代的流程是怎样的？
设计价值观与设计语言
- 品牌调性： 1-3 个关键词，专业、高效、友好；或者：年轻、活力、极致。
- 设计原则：
- 清晰： 避免模糊的表达。
- 一致： 相同的场景使用相同的元素。
- 高效： 减少不必要的交互层级。
设计环境与工具
- 设计工具： Figma / Sketch / Adobe XD 及版本要求。
- 开发环境： 支持哪些浏览器、移动端系统版本。
- 响应式断点（Responsive Breakpoints）： Desktop (1440+), Tablet (768-1024), Mobile (375-414)。
🎨 第二部分：基础视觉元素（Design Tokens）
这是整个规范体系的“原子”,所有组件都基于此构建。
色彩（Colors）
- 主色（Primary）： 品牌标志色，注明 HEX、RGB、CMYK 值。
- 辅助色（Secondary/Accent）： 用于功能区分，如按钮、链接、标签。
- 中性色（Neutral）： 文本色、背景色、边框色、占位符色，分号层级（如 #333, #666, #999）。
- 语义色（Semantic）： 成功（绿色）、警告（橙色）、错误（红色）、信息（蓝色）。
- 使用规范： 什么情况下用主色？什么情况下用浅色背景？一定要注明“不要做什么”（如：不要在黑色背景上用红色作为正文字体）。
字体与排版（Typography）
- 字体家族： 中文字体（如 PingFang SC, Noto Sans SC）、英文字体（如 Roboto, Inter）。
- 字体等级（Scale）： H1, H2, H3, Body, Caption, Small，注明字号、行高、字重、字间距。
- 使用规范： 段落间距规则、最小可读字号（移动端通常不低于 12px）。
间距与网格（Spacing & Grid）
- 基础单位（Base Unit）： 通常为 8px 或 4px，所有边距、内边距、组件间隔都应遵循该单位的倍数（如 8, 16, 24, 32, 40）。
- 网格系统： 列数、列间距（Gutter）、边距（Margin）。
图标（Icons）
- 图标集： 使用哪套图标库（如 Material Icons, Font Awesome）？
- 尺寸规范： 小图标（16x16）、中图标（24x24）、大图标（32x32）。
- 风格要求： 线型还是面型？线宽统一？圆角规范？是否允许倾斜？
阴影与层级（Shadows & Elevation）
- 层级定义： 普通卡片、弹窗、下拉菜单、模态框分别对应几级阴影？
- 阴影参数： X/Y 偏移量、模糊半径、颜色透明度。
🧱 第三部分：核心组件库（Components）
将基础元素组合成可复用的 UI 模块。
通用组件
-
按钮（Buttons）： 主按钮、次按钮、文字按钮、图标按钮，每种状态的样式（Normal, Hover, Pressed, Disabled）。
-
输入框（Inputs）： 未输入、已输入、聚焦、错误、禁用状态，前/后缀图标规范。
-
选择器（Selects/Dropdowns）： 默认态、展开态、选中态、选项分组。
-
导航（Navigation）： 顶部导航、侧边导航、标签导航（Tabs）。 展示组件**
-
卡片（Cards）： 圆角大小（Radius）、内边距、阴影层级、卡片内部布局。
-
列表（Lists）： 单行列表、双行列表、带图标的列表。
-
表格（Tables）： 表头样式、行高、斑马纹、排序图标、分页器。
反馈与弹窗组件
- 提示（Toast / Snackbar）： 出现位置、消失时间、类型（成功/失败）。
- 对话框（Modal / Dialog）： 标题区、内容区、操作区（按钮位置固定）,是否允许点击蒙层关闭？
- 加载状态（Loading）： 骨架屏（Skeleton）规范、加载旋转图标样式。
特殊组件（按需添加）
- 日期选择器、上传组件、图表（Chart）配色及风格。
✍️ 第四部分：撰写与表达技巧
图文并茂（高阶）
- 标注图： 比文字更直观，用箭头和数字标注关键部位（如间距、圆角）。
- 状态图： 每个组件最好附带 Normal、Hover、Active、Disabled 四张截图。
- 动效示例： 如果支持动效，用 GIF 或视频链接展示（如按钮点击反馈、页面切换过渡）。
明确的“DO & DON‘T”
- 错误示例： 很多规范只写“要用什么”，但开发更容易踩雷的是“不要做什么”。
- 示例：
- ✅ DO： 按钮宽度随文字自适应，左右内边距为 24px。
- ❌ DON’T： 不要给按钮设置固定宽度，除非是整行铺满的“全宽按钮”。
代码参考（紧贴开发）
- CSS 变量名： 写明设计对应的代码 Token（如
$color-primary: #1890FF）,这会极大减少设计师和开发的沟通成本。 - 框架适配： 如果是 React/Vue 项目，可以注明该组件对应哪个 UI 库的哪个组件（如 Ant Design 的
Button）。
异常状态与极端情况
- 空状态（Empty State）长什么样？
- 文字过长被截断时,是显示省略号还是折行？
- 图片加载失败时的占位图是什么？
🚀 第五部分：文档结构与维护
组织方式：
- 目录结构： 推荐分为：原则 -> 基础 -> 组件 -> 模式。
- 搜索功能： 如果是网页版文档（如 ZeroHeight, Storybook, Notion）,务必有全局搜索。
- 版本更新日志（Changelog）： 记录每次规范的修改，注明“新增”、“修改”、“废弃”。
更新流程（关键）：
- 谁可以提案？ 团队成员都可以。
- 谁来审批？ 主设计师 + 前端负责人。
- 更新频率： 尽量按版本迭代（如 V1.0 -> V1.1）,避免频繁小改动导致开发跟不上。
📦 示例：一个“按钮”组件的规范写法
组件：主按钮 (Primary Button)
使用场景： “提交表单”、“保存设置”、“确认操作”等核心高亮操作。
视觉规范：
- 颜色： 背景色
#1890FF，文字色#FFFFFF。- 圆角：
4px (Radius 4)。- 内边距： 左右
24px，上下12px。- 字号： 16px (Regular 400)。
- 阴影： 无阴影。
状态展示：
- Normal: 实心蓝底白字。
- Hover: 背景色加深至
#40A9FF。- Pressed: 背景色加深至
#096DD9，内阴影 1px。- Disabled: 背景色
#D9D9D9，文字色#A6A6A6，鼠标指针变not-allowed。变体（Variants）：
- 加载中（带旋转 Loader 图标，文字保持）。
- 图标按钮（带左侧图标，如“添加”图标 + 文字）。
❌ 禁止行为：
- 不要在按钮上使用渐变。
- 不要将主色按钮置于灰色背景上（对比度不足）。
- 不要调整按钮内部的图标与文字间距，固定为 8px。
代码 Token：
--btn-primary-bg: #1890FF;--btn-primary-border: none;
💡 推荐工具
- Figma 组件库（推荐）： 直接在 Figma 里制作配套的 UI Kit，并利用 Figma 的“链接式组件”功能,让设计师可以直接拖拽使用。
- 文档托管平台：
- ZeroHeight / Backlight / Supernova： 专为设计系统而生，支持将 Figma 设计稿与文档关联。
- Storybook： 开发端最常用，是组件的“游乐场”。
- Confluence / Notion： 适合小型团队快速搭建轻量级规范。
- GitHub / GitBook： 适合技术驱动的团队,可以版本控制。
写设计规范文档，不要追求面面俱到，而要追求“落地可执行”。
给你的建议：
- 从“最痛”的地方开始写： 如果你的团队最常为“按钮”是什么样而争论，就先写清楚按钮规范,不必一开始就写完所有组件。
- 让开发参与进来： 在写文档时，请前端开发一起确认 CSS Token 的命名。
- 保持“活文档”： 定期（如每季度）检查规范与实际产出的偏差,及时更新。
如果你手上已有混乱的稿子，可以先整理出一份 “配色 + 字体 + 间距 + 按钮” 的简版文档，这往往能解决 80% 的视觉不一致问题。
