DESIGN.md — AI 时代的设计规范技能

让 AI 生成的每个页面，都符合你的品牌规范。

---

核心概念

DESIGN.md 是 Google Stitch 提出的设计规范格式——用纯文本 Markdown 描述完整设计系统，AI 能直接理解和执行。

为什么是 Markdown？

• AI 最擅长处理 Markdown
• 比 Figma 文件更好解析
• 比 JSON Design Token 更好读
• 放在项目根目录，AI coding agent 启动即加载

---

触发场景

• "帮我写一个 DESIGN.md"
• "为这个项目创建设计规范"
• "按这个规范生成一个页面"
• "更新项目的 DESIGN.md"
• "让我生成的页面风格一致"

---

DESIGN.md 标准结构（9个模块）

每个 DESIGN.md 必须包含以下内容：

M1 — Visual Theme & Atmosphere

用自然语言描述产品的"气质"，AI 需要理解整体感觉才能生成风格一致的内容。

## M1 — Visual Theme & Atmosphere

DeepFMT 的视觉气质：
- **核心关键词**：专业 / 温暖 / 可信赖 / 轻量
- **情绪版**：医院的专业感，但不像传统医院那么冷；像一位值得信赖的家庭医生
- **设计哲学**：功能清晰，视觉减负；患者不需要在UI里感到压力
- **密度**：中等偏低，内容之间留有充分呼吸空间
- **明暗**：整体偏亮，避免大面积深色带来的压抑感

M2 — Color Palette & Roles

完整颜色系统，每个颜色必须标注：语义名称 / HEX / RGBA / 使用场景。

## M2 — Color Palette & Roles

| 角色 | 色值 | 使用场景 |
|------|------|---------|
| Primary | #2D7A4F | 主按钮、导航激活态、关键数据 |
| Primary Light | #3A9460 | Hover态、次级强调 |
| Primary Dark | #1F5E3A | 按下态、深色背景 |
| Accent | #FF8C42 | CTA按钮、重要提示、亮点 |
| Accent Light | #FFA066 | 渐变辅助、hover |
| Background | #F5F9F6 | 全局背景（医疗绿调白）|
| Surface | #FFFFFF | 卡片、输入框、浮层 |
| Text Primary | #1A1A1A | 正文 |
| Text Secondary | #666666 | 说明文字 |
| Text Tertiary | #999999 | 占位符、次要标签 |
| Border | #E8F2EC | 边框、分割线 |

M3 — Typography Rules

字体系统：字体族 / 字重 / 字号 / 行高 / 字间距全套层级。

## M3 — Typography Rules

### 字体族（移动端优先）
- 中文：'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', sans-serif
- 数字/英文：'SF Pro Display', -apple-system, BlinkMacSystemFont
- 等宽：'SF Mono', 'Fira Code', monospace（用于数据展示）

### 字号层级
| 层级 | 字号 | 字重 | 行高 | 用途 |
|------|------|------|------|------|
| Hero | 28px | 700 | 1.3 | 页面大标题 |
| H1 | 22px | 700 | 1.4 | 模块标题 |
| H2 | 18px | 600 | 1.4 | 卡片标题 |
| Body | 16px | 400 | 1.6 | 正文 |
| Caption | 14px | 400 | 1.5 | 说明文字 |
| XS | 12px | 400 | 1.4 | 标签、角标 |

### 字间距：标题用 -0.5px 负间距压缩感，正文保持标准。

M4 — Component Stylings

所有组件样式，包含各状态（Default / Hover / Active / Disabled / Loading / Error）。

## M4 — Component Stylings

### 主按钮
- Default: bg-primary (#2D7A4F), text-white, rounded-btn (8px), py-3 px-6
- Hover: bg-primary-light (#3A9460)
- Active: bg-primary-dark (#1F5E3A), scale(0.98)
- Disabled: opacity-40, cursor-not-allowed
- Loading: 左侧 spinner，文字变为"处理中..."

### 次按钮
- Default: border border-primary text-primary bg-transparent
- Hover: bg-primary/10

### 卡片
- bg-white rounded-card (16px) shadow-sm
- padding: 16px（内容卡片）/ 20px（大卡片）
- 内部分割：border-t border-[#E8F2EC] 或 gap-4

### 输入框
- bg-white rounded-input (12px) border border-[#E8F2EC]
- Focus: border-primary ring-2 ring-primary/20
- Error: border-red-500 ring-2 ring-red-500/20

M5 — Layout Principles

间距体系与网格原则。

## M5 — Layout Principles

### 间距系统（4px基准）
| Token | 值 | 用途 |
|-------|-----|------|
| space-xs | 4px | 图标与文字间距 |
| space-sm | 8px | 紧凑元素间距 |
| space-md | 12px | 标准元素间距 |
| space-lg | 16px | 区块内间距 |
| space-xl | 24px | 区块间间距 |
| space-2xl | 32px | 大区块间距 |

### 页面布局
- 最大内容宽度：max-w-lg (448px)，居中
- 左右安全边距：px-4（16px）
- 页面顶部：pt-4
- 页面底部：pb-[68px]（底部导航高度）

### 栅格：单列布局为主，偶尔2列（卡片并排）。

M6 — Depth & Elevation

阴影层级系统。

## M6 — Depth & Elevation

| Level | 样式 | 用途 |
|-------|------|------|
| L0 | 无阴影 | 默认状态 |
| L1 | shadow-sm | 卡片默认态 |
| L2 | shadow-md | 浮层、弹窗背景 |
| L3 | shadow-lg | Modal、浮出菜单 |
| L4 | shadow-xl | 强层级弹窗 |

### 医疗场景特殊性
- 避免过度阴影（医疗用户不需要"重量感"）
- 阴影 opacity 不超过 0.1，避免压抑
- 优先用 border 代替阴影来区分层级

M7 — Do's and Don'ts

设计禁区与正确示范。

## M7 — Do's and Don'ts

### ✅ 正确做法
- 用 Primary 绿做主操作按钮
- 重要数据（如评分、日期）用 Accent 橙高亮
- 卡片内使用 rounded-card (16px)
- 列表项之间用 border 分割，不用分隔线

### ❌ 错误做法
- 不要用蓝色作为主色调（与医疗信任感冲突）
- 不要用深色背景（患者需要明亮、轻松的氛围）
- 不要用太小的字体（14px以下正文需避免）
- 不要在大面积使用渐变背景
- 不要用纯黑文字（#000000），用 #1A1A1A 减少压迫感

M8 — Responsive Behavior

响应式行为与移动端特殊处理。

## M8 — Responsive Behavior

### 移动端优先
- 设计基于375px宽度的iPhone
- 触控热区最小44×44px
- 底部固定导航高度60px，内容区 pb-[68px]

### 断点（必要时）
- sm: 640px（平板横屏）
- lg: 1024px（桌面端）

### 文字截断
- 单行截断：truncate，max-w-xs
- 两行截断：line-clamp-2

M9 — Agent Prompt Guide

给 AI coding agent 的快速参考与提示模板。

## M9 — Agent Prompt Guide

### 快速颜色参考
- Primary: #2D7A4F
- Accent: #FF8C42
- Background: #F5F9F6
- Surface: #FFFFFF
- Text: #1A1A1A / #666666 / #999999

### AI 生成提示模板
"请按以下规范生成页面：
- 颜色：Primary #2D7A4F，Accent #FF8C42，Background #F5F9F6
- 字体：正文16px，行高1.6
- 圆角：卡片16px，按钮8px，输入框12px
- 间距：16px区块间距，底部导航占68px
- 阴影：卡片用 shadow-sm
- 不要：深色背景、蓝色主色调、过度阴影"

### Tailwind 速查
- 主按钮：bg-primary text-white rounded-btn px-6 py-3
- 卡片：bg-white rounded-card shadow-sm p-4
- 输入框：bg-white rounded-input border border-[#E8F2EC]

---

执行流程

场景1：创建新项目 DESIGN.md

1. 询问用户：产品定位、目标用户、品牌关键词
2. 提取已有设计资源（Tailwind配置、颜色变量、品牌资料）
3. 按 M1-M9 框架撰写完整 DESIGN.md
4. 保存到 DESIGN.md（项目根目录）
5. 给用户一个 AI 使用示例

场景2：更新已有 DESIGN.md

1. 读取现有 DESIGN.md
2. 确认要修改的模块
3. 增量更新对应章节
4. 标注版本号

场景3：按 DESIGN.md 生成页面

1. 读取项目根目录的 DESIGN.md
2. 确认页面需求
3. 生成页面代码，在生成时严格遵循 M1-M9 规范
4. 自检：颜色是否正确、字号层级是否符合、圆角是否匹配

---

参考资源

详细案例参考：

• VoltAgent/awesome-design-md：https://github.com/VoltAgent/awesome-design-md
• Google Stitch DESIGN.md 官方格式：https://stitch.withgoogle.com/docs/design-md/overview/
• 模板文件：references/design-md-template.md