1. DESIGN.md 是什么#

DESIGN.md 可以理解为一个项目的“设计说明书”，也可以理解为写给人和 AI 的“界面风格约束文档”。

在传统软件开发中，我们经常会看到这些文档：

• README.md：告诉别人这个项目是什么、怎么安装、怎么运行。
• CONTRIBUTING.md：告诉别人怎么参与贡献、代码规范是什么、提交 PR 要注意什么。
• CHANGELOG.md：记录项目每个版本做了哪些变化。
• API.md：说明接口如何使用。

而 DESIGN.md 关注的不是代码怎么跑，而是界面应该长什么样、为什么这样设计、不同页面之间如何保持一致、组件应该遵守什么规则、AI 生成页面时不能偏离哪些边界。

一句话概括：

DESIGN.md 是把“设计风格、视觉规则、交互原则、组件约束、页面气质”写成 Markdown 的项目级设计规范。

它的核心价值不是“让页面变漂亮”，而是“让页面在长期迭代中仍然保持一致、可控、可沟通、可复用”。

如果没有 DESIGN.md，一个项目很容易出现这些问题：

• 今天生成的页面是圆角卡片风格，明天生成的页面变成大渐变风格。
• 登录页用蓝色，仪表盘用紫色，设置页又变成绿色。
• 按钮有的 36px 高，有的 44px 高，有的圆角 4px，有的圆角 999px。
• 页面文案一会儿像企业官网，一会儿像 SaaS 后台，一会儿像活动落地页。
• AI 每次都重新理解产品，导致输出结果不稳定。
• 开发者不知道一个视觉决定是设计要求，还是某次临时生成出来的偶然结果。

DESIGN.md 要解决的就是这种“风格漂移”和“设计不可复现”的问题。

2. 为什么要学习 DESIGN.md#

学习 DESIGN.md 的意义，不只是学会写一个 Markdown 文件，而是学会把“模糊的审美感觉”转化成“可以执行的设计规则”。

很多初学 UI 设计的人，会用这些词描述界面：

• 好看一点。
• 高级一点。
• 简洁一点。
• 科技感一点。
• 像某某产品一样。
• 不要太土。

这些说法在沟通中很常见，但它们有一个致命问题：太抽象，无法稳定执行。

比如“高级一点”到底是什么意思？

• 是更少的颜色？
• 是更大的留白？
• 是更克制的阴影？
• 是更统一的字体层级？
• 是更精细的间距？
• 是更准确的图标？
• 是更少的装饰？

如果不把这些感觉拆开，设计和实现都会变得非常随意。DESIGN.md 的作用，就是把这些抽象要求拆成可检查的规则。

例如不要只写：

1
界面要简洁高级。

更好的写法是：

1
界面风格应保持克制、清晰、专业：
2
- 页面背景使用接近白色或浅灰色，不使用大面积高饱和渐变。
3
- 主要按钮只保留一个主色，其他按钮使用次级或文本样式。
4
- 卡片圆角控制在 6px 到 8px，避免过度圆润。
5
- 阴影只用于浮层、弹窗和少量强调卡片，不作为主要装饰手段。
6
- 标题层级不超过 3 级，避免页面出现过多不同字号。

这段内容就从“审美评价”变成了“设计约束”。人能读，AI 也能执行，开发者也能验证。

3. DESIGN.md 和设计系统的关系#

DESIGN.md 不是完整意义上的设计系统，但它可以是设计系统的文字入口。

设计系统通常包括：

• 设计原则：产品整体气质、体验目标、品牌表达。
• 设计变量：颜色、字体、字号、间距、圆角、阴影、层级。
• 组件规范：按钮、输入框、表格、卡片、弹窗、导航、标签等。
• 交互模式：加载、错误、空状态、禁用、提示、确认、撤销。
• 内容规范：按钮文案、错误文案、空状态文案、语气风格。
• 资源规范：图标、插画、图片、品牌标识、动效。
• 实现规范：CSS 变量、Tailwind 配置、组件库、设计 Token。

而 DESIGN.md 通常会用文字方式把这些内容组织起来。它不一定替代 Figma，不一定替代代码中的设计 Token，也不一定替代组件库文档。它更像一个“统一解释层”。

可以这样理解：

所以 DESIGN.md 最适合承担这些任务：

• 给 AI 生成 UI 时提供稳定上下文。
• 给新加入项目的人快速理解设计风格。
• 给开发者判断“这个页面是否偏离项目气质”。
• 给设计规范提供文字化、版本化、可追踪的记录。
• 在没有完整设计系统时，作为轻量级设计系统使用。

4. DESIGN.md 应该写给谁看#

DESIGN.md 不是只写给设计师看的，它至少有四类读者。

1
这是一个面向个人写作者的内容管理后台，界面应偏安静、清晰、耐看，不做营销落地页风格。

5. DESIGN.md 的核心组成#

一个完整的 DESIGN.md 通常可以包含下面这些部分：

1. 产品定位。
2. 目标用户。
3. 设计目标。
4. 视觉气质。
5. 品牌与语气。
6. 色彩系统。
7. 字体与排版。
8. 间距与布局。
9. 圆角与阴影。
10. 图标与图片。
11. 组件规范。
12. 页面结构。
13. 交互状态。
14. 响应式规则。
15. 可访问性要求。
16. 内容文案规范。
17. 禁止事项。
18. 示例与模板。

不是每个项目都要写得这么全。小项目可以写简化版，大项目可以逐步扩展。

最重要的是：DESIGN.md 不应该写成一堆空话，而应该写成能指导实际输出的规则。

6. 产品定位#

产品定位是 DESIGN.md 的第一层基础。没有产品定位，后面的颜色、字号、布局都会失去判断标准。

产品定位要回答：

• 这是一个什么产品？
• 它解决什么问题？
• 它是给谁用的？
• 用户在什么场景下使用？
• 它更像工具、社区、内容站、官网、后台、游戏，还是电商？

一个好的产品定位示例：

1
本项目是一个面向独立开发者和技术写作者的个人博客系统，核心任务是文章展示、分类浏览、学习笔记沉淀和长期知识管理。界面应强调阅读体验、内容层级和检索效率，不追求强营销感。

这段定位里面包含了几个关键信息：

• 用户：独立开发者、技术写作者。
• 场景：博客、学习笔记、知识管理。
• 核心任务：展示、浏览、沉淀、检索。
• 设计倾向：阅读体验优先，不要营销感。

有了这些信息，后面就可以推导出具体规则：

• 字体要适合长文阅读。
• 正文行高不能太挤。
• 分类和目录要清晰。
• 页面不能被过多装饰干扰。
• 不需要夸张 Hero 和销售转化按钮。

如果是一个后台管理系统，定位可能是：

1
本项目是一个面向运营人员的订单管理后台，用户每天会长时间处理订单、筛选数据、查看异常和批量操作。界面应保持高信息密度、低干扰、强可读性，优先保证效率和准确性。

这个定位会推导出完全不同的设计：

• 表格很重要。
• 筛选器要顺手。
• 状态标签要明确。
• 操作按钮不能太花。
• 页面信息密度要比官网高。

所以写 DESIGN.md 的第一步，不是选颜色，而是先把产品讲清楚。

7. 目标用户#

目标用户决定了界面复杂度、信息密度、语言风格和交互方式。

如果用户是普通消费者，界面可能需要更直观、更少术语、更强引导。

如果用户是专业人员，界面可以更紧凑、更直接、更强调效率。

如果用户是儿童或低龄用户，字体、颜色、图标、反馈方式都要更友好。

如果用户是开发者，界面可以接受更多专业概念，但也要保持清晰。

在 DESIGN.md 中，可以这样写目标用户：

1
## 目标用户
2

3
- 主要用户：有一定技术背景的个人开发者、学生、技术写作者。
4
- 使用场景：阅读学习笔记、查找技术资料、回顾项目经验。
5
- 用户特点：能够接受技术术语，但不希望界面过度复杂。
6
- 体验重点：阅读舒适、结构清晰、内容查找方便。

目标用户最好不要只写“所有人”。因为“所有人”通常意味着没有明确设计方向。

如果真的面向广泛用户，也应该拆成几类：

1
## 目标用户
2

3
- 新用户：第一次访问，需要快速理解网站内容范围。
4
- 常访用户：定期查看新文章，需要快速进入分类和最新内容。
5
- 作者本人：需要长期维护内容，希望文章结构清晰、可复用、易归档。

这样后续设计就能兼顾不同路径。

8. 设计目标#

设计目标是把产品目标翻译成界面目标。

常见设计目标包括：

• 清晰：用户能快速理解页面内容。
• 高效：用户能用较少步骤完成任务。
• 一致：相同类型内容使用相同表现方式。
• 可读：文字、表格、数据不费眼。
• 克制：不让装饰压过内容。
• 专业：符合目标行业和用户预期。
• 可信：通过稳定布局、合理层级和准确文案建立信任。

设计目标不要写太多，最好 3 到 5 个。太多目标会互相冲突。

例如：

1
## 设计目标
2

3
1. 阅读优先：长文章正文应清晰、舒适，避免过窄或过宽的行长。
4
2. 结构明确：分类、目录、标签、发布时间等信息要有稳定位置。
5
3. 风格克制：不使用强营销页面常见的大面积渐变、夸张动效和复杂装饰。
6
4. 易于扩展：新增文章类型、分类和专题时，不需要重做页面结构。

这段内容不仅描述了目标，还暗含了可执行约束。

如果是 SaaS 后台，可以写：

1
## 设计目标
2

3
1. 操作效率优先：常用操作应在首屏或当前工作区内完成。
4
2. 信息密度适中偏高：列表、筛选、详情需要支持快速扫描。
5
3. 状态反馈明确：加载、保存、失败、禁用、空数据都必须有明确状态。
6
4. 视觉表达克制：界面服务于任务，不使用营销式 Hero 和过度装饰。

9. 视觉气质#

视觉气质是 DESIGN.md 里最容易写空，也最需要写具体的部分。

常见的抽象词包括：

• 简洁。
• 高级。
• 专业。
• 现代。
• 温暖。
• 科技感。
• 活泼。
• 克制。
• 轻量。

这些词可以写，但不能只写这些词。每个词都要落到具体表现。

例如“克制”可以解释成：

• 色彩数量少。
• 不使用大面积高饱和背景。
• 阴影轻。
• 动效短。
• 装饰元素少。
• 文案直接。

“专业”可以解释成：

• 信息层级清楚。
• 表格和表单对齐准确。
• 字号变化有限。
• 图标风格统一。
• 错误提示明确。
• 关键操作有确认或撤销。

“阅读友好”可以解释成：

• 正文字号不小于 16px。
• 行高在 1.7 左右。
• 正文容器不要过宽。
• 标题层级清楚。
• 代码块有明显背景和横向滚动。
• 表格在小屏幕下可滚动。

可以在 DESIGN.md 里用“应该”和“避免”对照写：

1
## 视觉气质
2

3
应该：
4
- 清晰、克制、面向内容。
5
- 使用稳定的版心和明确的标题层级。
6
- 用留白和分隔线组织内容，而不是依赖大量卡片堆叠。
7
- 让正文、代码块、表格成为视觉中心。
8

9
避免：
10
- 大面积紫蓝渐变。
11
- 无业务意义的装饰球、模糊光斑和过度阴影。
12
- 所有内容都包在卡片里的页面。
13
- 为了“高级感”牺牲文字对比度。

这种写法比“要高级、要简洁”有效得多。

10. 色彩系统#

颜色是最容易导致风格失控的部分。DESIGN.md 里应该尽量明确主色、辅助色、中性色和状态色。

一个简化的色彩系统可以这样写：

1
## 色彩系统
2

3
主色：
4
- Primary：#2563EB，用于主要按钮、重要链接、当前导航状态。
5

6
中性色：
7
- Text Primary：#111827，用于正文主文本。
8
- Text Secondary：#4B5563，用于辅助说明。
9
- Border：#E5E7EB，用于边框和分隔线。
10
- Surface：#FFFFFF，用于卡片、弹窗、输入框背景。
11
- Page Background：#F8FAFC，用于页面背景。
12

13
状态色：
14
- Success：#16A34A，用于成功状态。
15
- Warning：#D97706，用于警告状态。
16
- Error：#DC2626，用于错误状态。
17
- Info：#2563EB，用于信息提示。

但只列颜色还不够，还要说明使用规则。

例如：

1
使用规则：
2
- 主色只用于可交互的关键元素，不用于大面积背景。
3
- 状态色只表达状态，不用于普通装饰。
4
- 正文不使用浅灰色，必须保证可读性。
5
- 同一个页面中高强调色不超过 2 种。
6
- 禁止为了丰富视觉而临时添加新的主题色。

颜色系统的关键不是颜色多，而是颜色有明确职责。

11. 字体与排版#

排版决定了一个界面是否好读。

DESIGN.md 中至少要写清楚：

• 字体族。
• 基础字号。
• 标题字号。
• 正文字号。
• 行高。
• 字重。
• 链接样式。
• 代码字体。
• 文章内容宽度。

示例：

1
## 字体与排版
2

3
- 中文字体优先使用系统默认无衬线字体。
4
- 英文和数字使用系统 UI 字体。
5
- 代码使用等宽字体，如 JetBrains Mono、Consolas、Menlo。
6
- 正文字号为 16px，行高 1.7。
7
- 辅助文字不小于 13px。
8
- 页面主标题 28px 到 36px，内容区标题按层级递减。
9
- 不使用负字距。
10
- 不使用视口宽度动态缩放正文文字。

排版最常见的问题是字号层级太多。

比如一个页面同时出现：

• 12px。
• 13px。
• 14px。
• 15px。
• 16px。
• 18px。
• 20px。
• 22px。
• 24px。
• 28px。
• 32px。
• 40px。

这会让页面显得很乱。更好的做法是建立有限层级：

对于博客或学习笔记来说，正文排版尤其重要：

• 行长不要过长。桌面端正文容器可以控制在 720px 到 860px。
• 行高不要太小。中文长文建议 1.6 到 1.9。
• 段落之间要有稳定间距。
• 标题上方间距应大于下方间距，让标题和后面的内容形成一组。
• 列表缩进要清晰。
• 代码块和表格要有足够区分。

12. 间距与布局#

间距是 UI 设计中非常基础但非常重要的规则。

如果间距没有系统，页面会出现：

• 元素粘在一起。
• 相同关系的元素距离不一致。
• 不同模块之间层级不清。
• 卡片内部拥挤。
• 页面整体松散或紧张。

常见的间距系统是 4px 或 8px 倍数。

例如：

1
## 间距系统
2

3
基础单位使用 4px。
4

5
- 4px：图标与文本之间的细小间距。
6
- 8px：同组紧密元素之间的间距。
7
- 12px：表单控件内部或紧密列表间距。
8
- 16px：普通组件内部 padding。
9
- 24px：卡片之间、表单组之间。
10
- 32px：页面模块之间。
11
- 48px：大章节之间。

间距的核心原则是：关系越近，距离越近；关系越远，距离越远。

例如：

• 按钮图标和按钮文字是强相关，间距可以是 6px 或 8px。
• 表单 label 和输入框是强相关，间距可以是 6px 或 8px。
• 一个表单项和下一个表单项是同组关系，间距可以是 16px。
• 表单区域和提交按钮区域是不同功能区，间距可以是 24px。
• 页面头部和主体内容是大区域，间距可以是 32px。

1
## 页面布局
2

3
- 内容页使用单栏正文为主，必要时添加右侧目录。
4
- 桌面端正文最大宽度控制在 860px 左右。
5
- 移动端正文左右留白不少于 16px。
6
- 列表页可以使用两栏或三栏，但卡片内容必须保持标题、摘要、日期、标签顺序一致。
7
- 不把所有页面模块都做成浮动卡片，优先使用清晰的内容分区。

1
## 页面布局
2

3
- 桌面端使用左侧导航 + 顶部工具栏 + 主内容区。
4
- 主内容区优先承载表格、筛选器和详情面板。
5
- 筛选区域应靠近数据列表，避免用户上下滚动查找条件。
6
- 常用操作放在列表上方右侧，危险操作放在行内或二次确认中。
7
- 页面不使用营销式 Hero 布局。

13. 圆角、边框与阴影#

圆角、边框和阴影决定了界面的“硬朗”或“柔和”程度。

常见问题：

• 所有元素都是超大圆角，导致专业工具像娱乐应用。
• 阴影太重，页面像浮在背景上。
• 边框颜色太深，页面显得脏。
• 同一项目里卡片圆角 4px、按钮 16px、弹窗 24px，缺乏统一规则。

可以在 DESIGN.md 里这样写：

1
## 圆角
2

3
- 小控件圆角：4px。
4
- 按钮、输入框、标签：6px。
5
- 卡片、弹窗、下拉面板：8px。
6
- 不使用 999px 胶囊圆角，除非是标签、开关或头像。

1
## 边框
2

3
- 默认边框颜色为 #E5E7EB。
4
- 输入框聚焦时使用主色边框。
5
- 卡片优先使用细边框或背景区分，不依赖重阴影。

1
## 阴影
2

3
- 常规页面组件不使用明显阴影。
4
- 阴影主要用于弹窗、下拉菜单、悬浮工具条等浮层。
5
- 阴影应轻，不制造强烈漂浮感。

对于后台、工具、知识库这类产品，轻边框通常比重阴影更稳定。

14. 图标、图片与插画#

图标和图片不是装饰品，它们应该服务于识别和理解。

DESIGN.md 可以写：

1
## 图标
2

3
- 图标用于辅助识别操作，不单独承载复杂含义。
4
- 同一页面使用统一线宽和风格的图标。
5
- 工具按钮优先使用常见图标，如搜索、添加、编辑、删除、保存、下载。
6
- 不使用多个图标库混搭。
7
- 只有图标按钮时必须提供可访问名称或 tooltip。

图片和插画的规则要根据产品类型决定。

对于博客：

1
## 图片
2

3
- 文章配图应与内容主题直接相关。
4
- 不使用纯装饰性图片填充内容。
5
- 图片下方可以添加简短说明。
6
- 技术文章中的截图应清晰，避免压缩导致文字不可读。

对于官网：

1
## 图片
2

3
- 首页首屏应展示真实产品、真实场景或高相关视觉，不使用空泛抽象图。
4
- 图片不能遮挡主要文案。
5
- 产品截图应能看清界面内容，而不是只作为模糊背景。

对于后台：

1
## 图片
2

3
- 后台系统不以插画作为主要视觉语言。
4
- 空状态可以使用轻量插画，但不能占据过大空间。
5
- 操作区和数据区优先于装饰图。

15. 组件规范#

组件规范是 DESIGN.md 中最接近前端实现的部分。

常见组件包括：

• Button 按钮。
• Input 输入框。
• Select 下拉选择。
• Checkbox 复选框。
• Radio 单选框。
• Switch 开关。
• Tabs 标签页。
• Table 表格。
• Card 卡片。
• Modal 弹窗。
• Toast 提示。
• Tooltip 气泡提示。
• Badge 标签。
• Navbar 导航。
• Sidebar 侧边栏。

组件规范要说明：

• 什么时候使用。
• 有哪些类型。
• 默认尺寸是什么。
• 状态有哪些。
• 文案怎么写。
• 禁止怎么用。

1
## Button
2

3
类型：
4
- Primary：页面主操作，一个区域内最多一个。
5
- Secondary：次要操作。
6
- Ghost/Text：低强调操作。
7
- Danger：删除、停用、不可逆操作。
8

9
尺寸：
10
- Small：高度 32px，用于表格行内操作。
11
- Medium：高度 40px，用于常规表单和页面操作。
12
- Large：高度 48px，用于移动端主要操作或少量重点页面。
13

14
状态：
15
- Default。
16
- Hover。
17
- Active。
18
- Focus。
19
- Disabled。
20
- Loading。
21

22
使用规则：
23
- 主要按钮文案使用动词，如“保存”“发布”“新建文章”。
24
- 同一操作区只能有一个最强按钮。
25
- 危险操作不能使用主色按钮。
26
- Loading 状态应防止重复提交。

1
## Input
2

3
- 输入框高度默认 40px。
4
- Label 放在输入框上方，复杂表单不使用仅 placeholder 作为说明。
5
- Placeholder 只用于示例，不替代字段名称。
6
- 错误信息显示在输入框下方，使用明确文案说明如何修正。
7
- 必填项可以用标记提示，但不要让页面充满红色星号。
8
- 禁用态要明显区别于只读态。

1
## Table
2

3
- 表头文字简短清晰。
4
- 数字列右对齐，文本列左对齐。
5
- 状态列使用语义颜色和标签。
6
- 行内操作放在最右侧。
7
- 批量操作只在用户选择行后出现。
8
- 空数据、加载中、加载失败都必须有状态。
9
- 移动端表格应支持横向滚动或改为列表布局。

1
## Card
2

3
- 卡片用于承载一组相对独立的信息。
4
- 不把页面每一个区块都包成卡片。
5
- 卡片内部应有清晰标题、主体内容和可选操作。
6
- 卡片之间间距保持一致。
7
- 卡片圆角默认 8px，边框使用浅色。
8
- 不在卡片里再嵌套多个卡片，除非是明确的列表项。

1
## Modal
2

3
- 弹窗用于需要用户立即处理的任务，如确认、编辑、创建。
4
- 弹窗标题必须明确说明任务。
5
- 主要操作放在右下角，取消操作在其左侧。
6
- 危险确认要使用清晰文案，不只写“确定”。
7
- 弹窗内容过长时，应考虑独立页面或抽屉。
8
- 关闭弹窗不能导致用户已输入内容意外丢失。

16. 页面结构规范#

组件是局部规则，页面结构是整体规则。

DESIGN.md 可以定义常见页面的结构模板。

例如文章详情页：

1
## 文章详情页
2

3
结构：
4
1. 页面标题。
5
2. 文章元信息：日期、分类、标签。
6
3. 可选目录。
7
4. 正文内容。
8
5. 相关文章或上一篇/下一篇。
9

10
规则：
11
- 正文是视觉中心。
12
- 目录不能遮挡正文。
13
- 标题和正文之间保持足够呼吸感。
14
- 代码块、表格、图片必须适配移动端。

文章列表页：

1
## 文章列表页
2

3
结构：
4
1. 页面标题。
5
2. 分类或标签筛选。
6
3. 文章列表。
7
4. 分页或加载更多。
8

9
文章列表项包含：
10
- 标题。
11
- 摘要。
12
- 发布日期。
13
- 分类和标签。
14

15
规则：
16
- 标题优先级高于摘要。
17
- 列表项之间要有明确分隔。
18
- 不使用过大的封面图压缩信息密度。

后台列表页：

1
## 后台列表页
2

3
结构：
4
1. 页面标题和主要操作。
5
2. 筛选区。
6
3. 数据表格。
7
4. 分页。
8
5. 批量操作区。
9

10
规则：
11
- 筛选条件应靠近表格。
12
- 主操作放在标题行或表格工具栏。
13
- 表格列顺序应按用户判断顺序排列。
14
- 错误和空状态不应该让页面崩掉。

页面结构规范能让不同页面保持同一种思考方式。

17. 交互状态#

很多界面看起来完整，但一到真实使用就出问题，是因为缺少状态设计。

DESIGN.md 必须提醒这些状态：

• Loading：加载中。
• Empty：空数据。
• Error：加载失败。
• Success：操作成功。
• Disabled：禁用。
• Hover：悬停。
• Focus：聚焦。
• Active：按下。
• Selected：选中。
• Skeleton：骨架屏。
• Pending：等待处理。
• Offline：离线或网络异常。

可以这样写：

1
## 交互状态
2

3
- 所有异步操作必须有加载状态。
4
- 表单提交时按钮进入 loading，并禁止重复提交。
5
- 数据为空时显示空状态，说明当前没有什么，以及用户下一步可以做什么。
6
- 错误状态要说明错误原因和恢复方式。
7
- 删除、发布、停用等关键操作需要二次确认或可撤销机制。
8
- 键盘聚焦状态必须可见。

状态设计是可用性的关键。

一个按钮不只是有默认样式，还至少应该有：

• 默认状态。
• 悬停状态。
• 点击状态。
• 聚焦状态。
• 禁用状态。
• 加载状态。

一个列表不只是有数据时的样子，还应该有：

• 首次加载。
• 加载失败。
• 数据为空。
• 筛选无结果。
• 分页加载。
• 局部刷新。

很多 AI 生成页面只生成“理想状态”，DESIGN.md 要明确要求补齐真实状态。

18. 响应式规则#

响应式不是简单地把桌面页面缩小到手机上。

DESIGN.md 应该说明不同屏幕下的布局变化。

例如：

1
## 响应式规则
2

3
桌面端：
4
- 使用最大宽度容器，保持正文可读。
5
- 可以显示侧边目录、筛选栏或辅助信息。
6

7
平板端：
8
- 减少多栏布局，保留主要内容和关键操作。
9
- 表格可以横向滚动。
10

11
移动端：
12
- 使用单栏布局。
13
- 导航折叠为菜单。
14
- 卡片和列表占满可用宽度。
15
- 表格改为横向滚动或摘要列表。
16
- 点击目标不小于 44px。

响应式设计要重点关注：

• 文本是否溢出。
• 按钮是否太小。
• 表格是否挤压。
• 导航是否可用。
• 弹窗是否超出屏幕。
• 固定定位元素是否遮挡内容。
• 图片是否变形。

对于博客文章，移动端尤其要注意：

• 代码块横向滚动。
• 表格横向滚动。
• 长英文链接换行。
• 图片宽度自适应。
• 目录不要遮挡正文。

19. 可访问性#

可访问性不是额外加分项，而是基础质量。

DESIGN.md 可以写：

1
## 可访问性
2

3
- 正文和背景必须有足够对比度。
4
- 交互元素必须支持键盘访问。
5
- 图标按钮必须有可访问名称。
6
- 表单错误不能只依赖颜色表达。
7
- 链接文字应能说明目的，避免大量“点击这里”。
8
- 图片需要根据情况提供 alt 文本。
9
- 焦点状态必须可见。

常见可访问性问题：

• 浅灰字太浅。
• 红色错误只用颜色表示，没有文字说明。
• 只有图标没有文字，也没有 aria-label。
• 弹窗打开后焦点没有进入弹窗。
• 键盘无法操作菜单。
• 图片缺少说明。
• 字号太小。

可访问性也是设计规范的一部分，不应该只交给开发最后补。

20. 内容文案规范#

文案也是界面设计的一部分。

不同产品的语气不同：

• 后台系统：直接、准确、少情绪。
• 消费 App：友好、自然、轻松。
• 金融产品：严谨、可信、避免夸张。
• 开发者工具：准确、简洁、尊重专业用户。
• 博客：清晰、有结构、便于长期阅读。

可以在 DESIGN.md 中写：

1
## 文案语气
2

3
- 使用简洁、直接、可理解的表达。
4
- 按钮文案优先使用动词，如“保存”“发布”“下载”。
5
- 错误信息说明问题和解决方法。
6
- 避免空泛营销词，如“极致”“颠覆”“赋能”。
7
- 技术内容可以使用专业术语，但首次出现时应有解释。

按钮文案示例：

错误文案也要具体。

不推荐：

1
出错了。

推荐：

1
文章保存失败，请检查网络后重试。

更好的文案会降低用户的不确定感。

21. 禁止事项#

DESIGN.md 里非常值得写“不要做什么”。

因为 AI 或团队成员经常会默认加入一些看起来流行但不适合项目的设计。

例如：

1
## 禁止事项
2

3
- 不使用大面积紫蓝渐变作为默认背景。
4
- 不使用无意义的装饰球、光斑、模糊背景。
5
- 不把工具型页面做成营销落地页。
6
- 不在一个页面中混用多个图标风格。
7
- 不为了视觉丰富随意增加颜色。
8
- 不使用过小字号承载关键内容。
9
- 不用 placeholder 替代表单 label。
10
- 不让按钮文字换行或溢出。
11
- 不在卡片内部继续嵌套大量卡片。
12
- 不只设计有数据的理想状态，必须考虑空、错、加载、禁用状态。

禁止事项的作用是设边界。边界越清晰，输出越稳定。

22. DESIGN.md 的简化模板#

小项目不需要一开始写很复杂。可以先用简化模板。

1
## 产品定位
2

3
这是一个面向什么用户、解决什么问题的产品。
4

5
## 目标用户
6

7
- 用户是谁。
8
- 使用场景是什么。
9
- 用户最关心什么。
10

11
## 设计目标
12

13
1. 目标一。
14
2. 目标二。
15
3. 目标三。
16

17
## 视觉气质
18

19
应该：
20
- ...
21
- ...
22

23
避免：
24
- ...
25
- ...
26

27
## 色彩
28

29
- 主色：...
30
- 背景色：...
31
- 正文色：...
32
- 边框色：...
33
- 成功/警告/错误色：...
34

35
## 字体与排版
36

37
- 正文字号：...
38
- 标题层级：...
39
- 行高：...
40
- 代码字体：...
41

42
## 间距与布局
43

44
- 基础间距单位：...
45
- 页面版心：...
46
- 移动端规则：...
47

48
## 组件规则
49

50
### Button
51

52
### Input
53

54
### Card
55

56
### Table
57

58
### Modal
59

60
## 状态
61

62
- Loading。
63
- Empty。
64
- Error。
65
- Disabled。
66
- Focus。
67

68
## 文案
69

70
- 语气。
71
- 按钮文案。
72
- 错误文案。
73

74
## 禁止事项
75

76
- ...
77
- ...

这个模板适合个人项目、课程项目、AI 生成 UI 项目、早期产品原型。

23. DESIGN.md 的进阶模板#

如果项目更复杂，可以使用进阶模板。

1
## 1. Overview
2

3
### 1.1 Product
4
### 1.2 Users
5
### 1.3 Core Scenarios
6
### 1.4 Design Principles
7

8
## 2. Brand
9

10
### 2.1 Personality
11
### 2.2 Tone of Voice
12
### 2.3 Visual Direction
13

14
## 3. Foundations
15

16
### 3.1 Colors
17
### 3.2 Typography
18
### 3.3 Spacing
19
### 3.4 Radius
20
### 3.5 Shadow
21
### 3.6 Iconography
22
### 3.7 Motion
23

24
## 4. Layout
25

26
### 4.1 Grid
27
### 4.2 Page Width
28
### 4.3 Navigation
29
### 4.4 Responsive Breakpoints
30

31
## 5. Components
32

33
### 5.1 Button
34
### 5.2 Form Controls
35
### 5.3 Table
36
### 5.4 Card
37
### 5.5 Modal
38
### 5.6 Toast
39
### 5.7 Tabs
40
### 5.8 Navigation
41

42
## 6. Patterns
43

44
### 6.1 Loading
45
### 6.2 Empty State
46
### 6.3 Error Handling
47
### 6.4 Confirmation
48
### 6.5 Search and Filter
49
### 6.6 Create/Edit Flow
50

51
## 7. Content
52

53
### 7.1 Voice
54
### 7.2 Button Labels
55
### 7.3 Error Messages
56
### 7.4 Empty State Messages
57

58
## 8. Accessibility
59

60
## 9. Do and Don't
61

62
## 10. Examples

进阶模板的重点是把“基础变量”“组件”“模式”分开。

• 基础变量解决颜色、字体、间距。
• 组件解决单个控件怎么长。
• 模式解决多个组件组合后的用户流程。

24. 给博客项目写 DESIGN.md 的示例#

下面是一个适合个人技术博客的 DESIGN.md 示例。

1
## 产品定位
2

3
这是一个个人技术博客，用于记录学习笔记、项目经验、UI 设计学习、前端开发和 AI 编程实践。网站的核心价值是长期沉淀内容，而不是短期营销转化。
4

5
## 目标用户
6

7
- 作者本人：用于整理长期学习记录。
8
- 技术学习者：阅读教程、笔记和经验总结。
9
- 访问者：通过分类、标签和文章列表快速找到感兴趣内容。
10

11
## 设计目标
12

13
1. 阅读舒适：长文内容应清晰、稳定、适合长时间阅读。
14
2. 结构清楚：分类、标题、目录、代码块和表格层级明确。
15
3. 风格克制：视觉为内容服务，不用强装饰抢占注意力。
16
4. 易维护：新增文章和分类不需要额外设计调整。
17

18
## 视觉气质
19

20
应该：
21
- 清晰、安静、耐看。
22
- 以正文内容为中心。
23
- 使用稳定的版心和充足行高。
24
- 用标题、列表、表格和代码块组织知识。
25

26
避免：
27
- 营销落地页风格。
28
- 大面积渐变背景。
29
- 无意义装饰图形。
30
- 过多卡片嵌套。
31

32
## 排版
33

34
- 正文字号不小于 16px。
35
- 中文正文行高建议 1.7。
36
- 文章正文最大宽度控制在适合阅读的范围。
37
- 标题上方间距大于下方间距。
38
- 代码使用等宽字体，并提供明显背景。
39

40
## 内容组件
41

42
### 文章列表
43

44
- 标题优先。
45
- 摘要简短。
46
- 显示日期、分类和标签。
47
- 列表项之间保持稳定分隔。
48

49
### 文章详情
50

51
- 标题、日期、分类应位于正文前。
52
- 正文段落间距稳定。
53
- 表格需要清晰边框。
54
- 代码块支持横向滚动。
55

56
### 导航
57

58
- 导航项命名简短。
59
- 当前页面状态明确。
60
- 移动端导航不能遮挡正文。
61

62
## 状态
63

64
- 图片加载失败时不应影响正文阅读。
65
- 长代码块和宽表格在移动端横向滚动。
66
- 链接悬停状态要明显。
67

68
## 文案
69

70
- 技术概念尽量解释清楚。
71
- 标题准确描述内容，不做夸张标题党。
72
- 学习笔记可以使用分层编号，方便回顾。

这个示例不是为了追求“炫”，而是为了让博客长期稳定。

25. 给后台管理系统写 DESIGN.md 的示例#

后台管理系统和博客完全不同，它更强调效率、准确性和状态反馈。

1
## 产品定位
2

3
这是一个面向运营人员和管理员的后台管理系统，主要用于查看数据、处理订单、管理用户、配置内容和追踪异常。
4

5
## 目标用户
6

7
- 运营人员：每天高频使用，需要快速筛选、查看和处理数据。
8
- 管理员：需要配置系统、管理权限和查看关键指标。
9
- 客服人员：需要快速定位用户问题。
10

11
## 设计目标
12

13
1. 高效：常用操作路径短。
14
2. 清晰：数据状态和操作结果明确。
15
3. 稳定：页面结构可预测，不频繁变化。
16
4. 可扫描：表格、标签、筛选器便于快速比较。
17

18
## 视觉气质
19

20
应该：
21
- 专业、克制、工作导向。
22
- 信息密度适中偏高。
23
- 视觉重点服务于状态和操作。
24

25
避免：
26
- 大面积插画。
27
- 营销式首屏。
28
- 低信息密度的大卡片堆叠。
29
- 过度圆角和强阴影。
30

31
## 布局
32

33
- 桌面端使用侧边导航。
34
- 顶部区域放置页面标题、面包屑和主要操作。
35
- 筛选区放在表格上方。
36
- 表格是列表页主要内容。
37
- 详情信息可以使用抽屉或独立详情页。
38

39
## 表格
40

41
- 文本左对齐，数字右对齐。
42
- 状态使用标签展示。
43
- 操作列固定在最右侧。
44
- 支持加载、空数据、错误、筛选无结果状态。
45
- 批量操作在选择数据后出现。
46

47
## 表单
48

49
- label 放在输入框上方。
50
- 错误提示紧跟字段。
51
- 保存按钮进入 loading 后禁止重复提交。
52
- 离开未保存表单时需要提醒。
53

54
## 操作反馈
55

56
- 成功使用 toast。
57
- 危险操作使用确认弹窗。
58
- 长耗时任务显示进度或后台处理状态。
59
- 错误信息说明原因和下一步。

这个版本的关键词是“工作导向”。如果后台做得像官网，就会牺牲效率。

26. 给 AI 使用 DESIGN.md 的方法#

如果 DESIGN.md 是给 AI 使用的，写法要更明确、更直接。

AI 不擅长猜测隐含偏好，所以要给它清楚边界：

• 你要做什么。
• 你不要做什么。
• 页面属于什么类型。
• 优先级是什么。
• 哪些东西必须出现。
• 哪些风格禁止出现。

可以在提示词中这样使用：

1
请根据项目中的 DESIGN.md 生成一个文章列表页。
2
必须遵守其中的视觉气质、排版、颜色、组件和响应式规则。
3
不要生成营销落地页，不要使用大面积渐变背景，不要添加无意义装饰。

如果是让 AI 修改页面，可以写：

1
请检查当前页面是否符合 DESIGN.md。
2
重点检查：
3
1. 颜色是否超出规范。
4
2. 字号和间距是否混乱。
5
3. 是否滥用卡片、圆角和阴影。
6
4. 是否缺少 loading、empty、error 状态。
7
5. 移动端是否存在文字溢出和布局挤压。

如果是让 AI 生成组件，可以写：

1
请根据 DESIGN.md 实现 Button 组件。
2
组件需要包含 primary、secondary、ghost、danger 四种类型，以及 disabled、loading、focus 状态。
3
请不要临时创造新的颜色和圆角。

给 AI 用的 DESIGN.md 要注意两点：

第一，规则要具体。不要只写“美观大方”，要写颜色、间距、圆角、层级。

第二，禁止事项要明确。AI 很容易默认加入流行设计套路，所以“不做什么”非常重要。

27. DESIGN.md 和代码实现如何连接#

DESIGN.md 如果只停留在文字层面，长期会和代码脱节。更好的方式是把它和代码中的变量、组件、测试连接起来。

1
Primary：#2563EB
2
Border：#E5E7EB
3
Radius Medium：8px

1
:root {
2
  --color-primary: #2563eb;
3
  --color-border: #e5e7eb;
4
  --radius-md: 8px;
5
}

1
theme: {
2
  extend: {
3
    colors: {
4
      primary: "#2563eb",
5
      border: "#e5e7eb"
6
    },
7
    borderRadius: {
8
      md: "8px"
9
    }
10
  }
11
}

28. DESIGN.md 的维护方法#

DESIGN.md 不是一次写完就不管的文件。它应该随着项目演进。

1
界面要美观、现代、简洁、好用、高级、有科技感。

1
页面背景使用浅灰，内容区使用白色表面。主按钮使用蓝色，其他按钮使用次级样式。卡片圆角 8px，阴影只用于弹窗和下拉菜单。正文不小于 16px，行高不小于 1.6。

29. 常见错误#

1
整体风格简洁大气，高端专业。

1
整体风格克制、专业。页面背景使用浅灰或白色；主色只用于关键操作；卡片圆角 8px；阴影只用于浮层；标题层级不超过 3 级；正文对比度必须保证长时间阅读。

30. 学习 DESIGN.md 的方法#

学习 DESIGN.md 可以按四步走。

31. 一份高质量 DESIGN.md 的判断标准#

可以用下面的清单判断一份 DESIGN.md 是否合格。

32. 总结#

DESIGN.md 的本质不是“多写一个文档”，而是把设计判断显性化。

它让项目从“凭感觉设计”变成“按规则设计”，从“每次重新解释”变成“长期共享上下文”，从“页面各做各的”变成“风格稳定统一”。

对于个人学习来说，写 DESIGN.md 可以训练自己把审美拆成结构化规则。

对于团队协作来说，写 DESIGN.md 可以减少反复沟通，让设计、产品、开发有共同依据。

对于 AI 编程和 AI 生成 UI 来说，写 DESIGN.md 几乎是必要的。因为 AI 默认会补很多它认为合理的设计，而 DESIGN.md 可以告诉它：这个项目真正需要什么，以及哪些东西不能出现。

可以记住这句话：

好的 DESIGN.md 不是描述“页面要好看”，而是定义“什么样的页面才算符合这个项目”。

学习 DESIGN.md，最终学到的不是 Markdown 写法，而是一种把设计经验沉淀成工程规则的能力。