Vibe design

Vibe Design：审美发现 + 设计规范 + 诊断打磨

两个介入时刻：

时刻	输入	做什么	产出
Pre-build	REQUIREMENTS.md + 用户视觉偏好	帮助用户发现自己喜欢的风格 -> 提取设计规则 -> 生成设计规范	.vibe/doc/DESIGN.md
Post-build	实际 UI 代码 + DESIGN.md	对照设计规范审计 -> 白话诊断 -> 修复 -> 打磨	修复后的 UI + 设计审计报告

面向用户：不会设计、不认识设计术语的普通人。核心命题：非程序员"感觉 UI 不对但说不出来"：这不是审美问题，是翻译层缺失。vibe-design 填补这个翻译层。

---

门禁总览

#	Phase	时刻	门禁条件
D1	DISCOVER	Pre-build	必入
D2	RESEARCH	Pre-build	DISCOVER 产出审美方向
D3	EXTRACT	Pre-build	RESEARCH 完成 或 DISCOVER 产出参考材料
D4	PROTOTYPE	Pre-build	EXTRACT 产出设计原子，或 RESEARCH 找到可复用的设计系统
D5	COMPOSE	Pre-build	EXTRACT 产出设计原子
D6	HANDOFF	Pre-build	必入
D7	AUDIT	Post-build	DESIGN.md 存在 + UI 代码存在
D8	CRITIQUE	Post-build	AUDIT 完成
D9	POLISH	Post-build	用户确认修哪些
D10	SATISFACTION GATE	Post-build	必入
D11	HANDOFF	Post-build	满意度门禁通过

---

Pre-build：发现 -> 规范

---

Phase D1：DISCOVER（审美发现）

门禁：必入

核心问题：用户知道自己喜欢什么，但说不出来。这个 phase 不靠语言描述：靠"指出来"。

Step 1：A-G 审美方向快速定位

你说的"好看"，大概是哪种感觉？

不需要术语，就看这几个方向：
  A) 极简克制：大量留白、字大、颜色很少
  B) 温暖亲近：圆角、暖色调、像翻一本好杂志
  C) 科技锋利：深色背景、荧光色点缀、线条硬朗
  D) 活泼玩具感：圆润、色彩丰富、有插画感
  E) 奢华精致：衬线字体、金色/深色、细节很多
  F) 工业实用：像你每天用的工具，不花哨，就是好用
  G) 我也不知道，但我可以给你看几个我喜欢的东西

Step 2：参考收集

如果用户选了 G（或选了一个方向但想更精确）：

有没有你觉得"就长这样就好了"的产品或网站？

你可以给我：
  - 一个网址（比如 notion.so、linear.app）
  - 几张截图（手机截图也行）
  - 甚至"我特别喜欢 XX App 的那个 XX 页面"

丢给我就行，不用描述为什么喜欢。

主动推荐参考（根据产品类型匹配）：

根据你做的 [产品类型]，这几个产品的设计风格很适合参考：
  - Linear：工具类产品的极简标杆
  - Notion：温暖克制的内容产品
  - Stripe：开发者工具的精致感
  - Vercel：科技品牌的暗色美学

要不要我提取其中一个的设计规则给你看看？

Step 3：如果用户一个参考都拿不出

没关系，我帮你缩小范围。

你的产品给谁用的？在什么场景下用？
  - 工作场景（需要高效、不花哨）
  - 个人生活（可以有温度、有个性）
  - 专业工具（需要可信、精确感）

你希望玩家打开的第一感觉是：
  - "这东西靠谱" -> 偏克制、专业
  - "这东西真好玩" -> 偏活泼、有个性
  - "这东西懂我" -> 偏温暖、有人情味

纪律：

• 不接受"好看就行"：必须收窄到一个具体方向
• 不代用户决定风格：用户可以指"就是那个"，不能靠 AI 猜
• 如果用户给了参考 URL -> 直接进入 Phase D2 提取

输出：

• 确认的审美方向（A-G 之一，或自定义方向）
• 2-5 个视觉参考（URL 或截图描述）
• 产品类型 + 目标玩家 + 使用场景

---

Phase D2：RESEARCH（避免造轮子）

门禁：DISCOVER 产出了审美方向

流程：审美方向确认后，搜索社区是否已有现成的设计系统或模板。

搜索方向：

搜索内容	方法
参考 URL 的设计系统提取	dmd <参考URL> 自动提取 DESIGN.md
DESIGN.md 模板库	npx getdesign@latest add <参考产品> 获取已有模板
shadcn/ui 主题/registry	npx shadcn add 搜索现成组件主题
同类产品的公开设计规范	GitHub 搜索 DESIGN.md [产品类型]

纪律：

• 参考 URL -> 直接 dmd 提取 -> 能拿到完整设计系统就跳过手动 EXTRACT
• getdesign 库有现成模板 -> 直接复用，只需适配颜色/字体
• 搜不到 -> 记录，继续走 EXTRACT 手动提取
• 发现大量参考材料但质量参差 -> 择优选取 2-3 个最好的

输出：搜索结论 + 如找到：提取到的 DESIGN.md 原文或设计系统片段

---

Phase D3：EXTRACT（设计提取）

门禁：RESEARCH 完成，或 DISCOVER 产出了参考材料（任一途径有参考即可）

流程：从用户提供的参考中提取设计原子。如果给了 URL，尝试 dmd <url> 或直接阅读网站。

提取六维度设计原子：

维度	提取内容	方法
配色	主色、辅色、背景色、文字色、语义色的 hex 值	从参考截图中取色，或从 URL 提取 CSS 变量
字体	标题字体、正文字体、字体大小层级	检查参考网站的 font-family，记录实际使用的字体
间距	页面边距、卡片内边距、组件间距	肉眼估算或检查 CSS，统一到 4px 刻度
圆角	按钮圆角、卡片圆角、输入框圆角	检查 border-radius 值
阴影	卡片阴影、弹窗阴影、悬浮效果	提取 box-shadow 值
图标风格	线性/填充、粗细、风格倾向	参考网站的图标库（Heroicons/Lucide/Phosphor 等）

设计原子表示例：

从 Linear.app 提取的设计原子：

配色:
  主色: #5E6AD2 (紫蓝)
  背景: #0D0D0D (近黑)
  卡片背景: #1A1A1A (深灰)
  文字主色: #FFFFFF
  文字辅色: #8A8F98 (灰蓝)

字体:
  标题: Inter
  正文: Inter
  标题大小: 24px / 20px / 16px
  正文大小: 14px

间距:
  页面边距: 32px
  卡片内边距: 16px
  组件间距: 12px

圆角:
  按钮: 6px
  卡片: 8px
  输入框: 6px

阴影:
  卡片: 无阴影 (靠边框区分)
  弹窗: 0 0 0 1px rgba(255,255,255,0.1), 0 8px 32px rgba(0,0,0,0.4)

图标:
  Phosphor 线性图标, 1.5px 描边

纪律：

• 提取的是"设计规则"而非"拷贝设计"：提取间距刻度、配色逻辑，而不是照搬 hex 值
• 如果参考之间的风格冲突 -> 标注冲突，让用户在 Phase D3 选择
• 不编造数值：提取不到就说"未检测到"，不脑补

输出：设计原子表（6 维度的具体数值 + 规则）

---

Phase D4：PROTOTYPE（视觉原型）

门禁：EXTRACT 产出了设计原子，或 RESEARCH 找到了可复用的设计系统

流程：

生成一个独立的 prototype.html 文件，用户在浏览器打开就能看到实际效果。这不是最终产品：是设计规范的"可视化翻译"。

prototype.html 必须包含：

1. 设计 tokens 的 CSS 变量定义（全部颜色、字体、间距、圆角、阴影）
2. 关键页面的静态骨架：不是交互功能，是视觉骨架：
   • 房间大厅（房间号显示、玩家列表占位、角色卡片骨架）
   • 游戏主舞台（对话区骨架、投票面板骨架、线索栏骨架）
3. 两个以上 DESIGN.md 定义的氛围配色方案（CSS 变量切换按钮）
4. 字体实际加载和渲染（Google Fonts link）

prototype.html 不需要包含：

• 任何实际交互逻辑（按钮可以是空的）
• 数据获取或 API 调用
• 路由跳转

纪律：

• prototype.html 是一个完全独立的文件，不依赖项目构建工具链。浏览器直接打开即可。
• 生成后告诉用户："这个 HTML 文件可以直接在浏览器打开，你能看到设计规范变成实际页面的样子。骨架是对的但按钮还不能点：那是下一步 build 的工作。"
• 用户反馈"颜色不对""间距太大了"→ 调整 DESIGN.md 的对应数值 → 重新生成 prototype.html

预检门禁（生成后、展示给用户前）：

1. 打开 prototype.html，看三秒后闭眼：你记住的是什么？ 如果没有任何一个元素跳出来 → 签名元素不够强，重做
2. 换一套配色方案（CSS 变量切换）：两套方案看起来像两个不同的产品吗？ 如果看起来只是换了个颜色 → 骨架太通用，重新选宏观结构
3. 给一个不认识这个项目的人看：他能猜到这是什么产品吗？ 猜不到 → 设计太抽象，需要更具体的场景元素
4. 他能猜到这是 AI 做的吗？ 能 → 找到那个露馅的元素，更换它

输出：

• prototype.html 写入项目根目录
• 一句话总结："原型页面已生成，浏览器打开 prototype.html 可以看到设计效果。"

---

Phase D5：COMPOSE（规范组装）

门禁：EXTRACT 产出了设计原子

流程：按 DESIGN.md 9 段标准格式组装。

设计哲学

设计哲学（来自 Anthropic frontend-design v1.1.0）：

"把大胆花在一个地方。"

选一个签名元素作为记忆点，其余一切保持克制：

• 一个反常规的字体选择
• 一个激进的留白策略
• 一个独特的色彩对比
• 一个打破网格的布局
• 一个定制的光标/滚动体验
• 一个背景纹理/噪点

同时避免 Anthropic 命名的三个 AI 陈词滥调——不是禁止使用，而是自问它们是否"没想就选了"：

• 编辑杂志风：暖米色底 + 衬线标题 + 赤陶点缀——这是你深思熟虑后的选择，还是 AI 最常掉进去的坑？
• 暗黑科技风：纯黑底 + 荧光绿/朱红单色点缀——同上
• 宽幅排版风：极细分割线 + 零圆角 + 密集报纸栏——同上

如果看到以上配色方案出现了 → 自问：我是经过推理选出来的，还是因为这是最常见的 AI 默认？如果是后者，换一个。

自问："如果我是设计师，看到这个方案会脱口而出'这就是 AI 生成的'吗？如果会，哪里漏了馅？改掉那一点。"

从 11 个审美方向中选择一个：

极简克制 / 极繁混乱 / 复古未来 / 有机自然 / 奢华精致 /
活泼玩具感 / 编辑杂志风 / 粗野原始 / 装饰艺术几何 /
柔和粉彩 / 工业实用

选择一个"签名元素"：把大胆花在一个地方：

• 一个反常规的字体选择
• 一个激进的留白策略
• 一个独特的色彩对比
• 一个打破网格的布局
• 一个定制的光标/滚动体验
• 一个背景纹理/噪点

其余一切保持克制，让签名元素成为唯一记忆点。

宏观结构选型（来自 Hallmark）

不同产品类型用不同宏观结构：不是换个颜色，是换个骨架：

产品类型	宏观结构	特征
工具/SaaS	三栏控制台	左导航 + 中主内容 + 右细节面板
内容/阅读	单栏排版	宽留白、大字号、65ch 最大行宽
市场/展示	沉浸式 Hero	首屏大图/视频 + 向下滚动叙事
社交/互动	信息流 + 浮动操作	滚动为主、关键操作悬浮
数据/仪表盘	卡片网格	数据模块化、可拖拽、可定制

选择宏观结构后，自问：你选的骨架和其他产品类型的骨架确实不同吗？还是换个颜色就是同一种？如果骨架上没有区分度，说明掉进了"全部居中+卡片网格"的默认陷阱——重新选宏观结构。

DESIGN.md 10 段格式

# DESIGN.md：[项目名]

## 1. Visual Theme & Atmosphere（视觉主题与氛围）
[一段话描述整体感觉，用具体意象不用"clean and modern"]

## 2. Color Palette & Roles（配色与角色）
[语义命名 + hex + 功能角色]
- Primary CTA / Surface / Text Primary / Text Secondary / Border / Success / Warning / Error
- Dark mode 等效色（如需要）

## 3. Typography Rules（字体规则）
[完整层级表：级别 | 大小(px/rem) | 字重 | 行高 | 字间距 | 字体]

## 4. Component Stylings（组件样式）
[按钮/卡片/输入框/弹窗，各含 hover/focus/active/disabled 态]

## 5. Layout Principles（布局原则）
[间距刻度(4px基准)、网格系统、最大内容宽度、留白哲学]

## 6. Depth & Elevation（深度与层级）
[阴影刻度、表面层级(底->浮->覆)、边框策略]

## 7. Do's and Don'ts（设计约束）
[每条配 ✅ Good 和 ❌ Bad 代码示例]

## 8. Accessibility（可访问性约束）
硬性约束，写入 DESIGN.md 后 build 阶段必须遵守：
- 颜色对比度：正文 ≥ 4.5:1，大文字(≥18px bold) ≥ 3:1（WCAG AA）
- 触控目标 ≥ 44×44px（移动端），桌面端 ≥ 24×24px
- focus 状态必须可见：不允许 `outline: none` 裸奔；hover 和 focus 不可只靠颜色区分
- 关键状态不可仅靠颜色传达：成功/错误/警告必须配合图标或文字
（这 4 条不是"可选"：不遵守 = Post-build AUDIT 扣分）

## 9. Responsive Behavior（响应式行为）
[断点表、触控最小尺寸44px、移动端适配策略]

## 10. Agent Prompt Guide（Agent 使用指南）
[给下一个 AI（vibe-build）看的一页速查表]

AI Slop 自检

组装完成后，对 DESIGN.md 过一遍 AI Slop Test：

一级测试：只看产品类型，你能猜到 DESIGN.md 会用什么配色吗？

• "能猜到" → 你的配色是 AI 的默认选择，重新选签名元素或调整配色，打乱预期。
• "猜不到" → 通过。

二级测试：告诉别人"这个产品不是常见的 [类别] 风格"，他还能猜到你的审美方向吗？

• "能猜到" → 仍然在 AI 的舒适区，继续调整直到不可预测。
• "猜不到" → 通过。

两者都不能猜到 → 通过 AI Slop Test。

常见失败案例见 references/ai-slop-catalog.md。

自我批评（来自 Anthropic frontend-design）

"如果我把这个设计规范给一个设计师看，他会说'这就是 AI 生成的'吗？ 如果是，哪里露馅了？改掉那一点。"

设计自检习惯（以下规则写入 DESIGN.md §7 Do's and Don'ts）：

组装完成后，逐条自检：

• 暗色文字是纯黑吗？ 纯黑在数字屏幕上显得生硬。加一点色相偏移让它看起来更自然。
• 背景是纯白 #FFF 吗？ 纯白在真实光线下像没刷完的墙。加 5-10% 的暖色或冷色偏移。
• 单一强调色：全页只有一个颜色在"跳出来"吗？如果两个以上的元素在争抢注意力，弱化多余的那个。
• 嵌套圆角自洽吗？ 外层圆角减去内边距之后，内层圆角看起来舒服吗？还是内外一样的圆角显得粗糙？
• 间距均匀吗？ 扫一眼所有 margin/padding/gap：有没有散落在刻度外的值？把所有间距统一到一个刻度上。
• 数字和标签的比例协调吗？ 用户能一眼分清楚哪个是数据、哪个是说明吗？
• 状态色只用于状态吗？ 红色只出现在错误/删除，黄色只出现在警告，绿色只出现在成功。正常状态下它们都是中性的。
• 单焦点原则：每个页面只允许一个视觉焦点。如果有两个元素在争抢注意力，弱化其中一个。
• 每个图标都是 SVG 矢量图标吗？ 如果有 emoji，它们在不同设备上渲染不一致——换成 Lucide/Heroicons/Phosphor。

如果某条自检不通过 → 改掉它。修改后确认：现在看起来自然吗，还是只是在"遵守规则"？

纪律：

• 每个数值必须有角色：不列无用的颜色、不写无场景的间距
• 命名语义化："Primary CTA"而非"Blue"、"Surface"而非"White"
• 描述 + 数值双写："宽松的留白，卡片间距 24px"而非只有数字
• 签名元素只能有一个：花在两个地方就等于没花

输出：完整的 .vibe/doc/DESIGN.md（10 段）

---

Phase D6：HANDOFF（Pre-build 交付）

门禁：必入

流程：

1. DESIGN.md 写入 .vibe/doc/DESIGN.md
2. 给用户一句话总结：

设计规范写好了。

核心风格: [审美方向]
签名元素: [一个记忆点]
主色调: [颜色名 + hex]
字体: [标题字体] + [正文字体]

你可以说"换个颜色"或"字体严肃了点"，我来改规范。
确认没问题了就进入下一步：技术架构设计。

3. 如果 Post-build 模式（UI 已存在）-> 自动进入 Phase D7

输出：.vibe/doc/DESIGN.md + 用户确认

---

Post-build：审计 -> 打磨

---

Phase D7：AUDIT（设计审计）

门禁：DESIGN.md 存在 + UI 代码存在

流程：对照 DESIGN.md 逐项审计实际 UI。分六个维度，每维度 0-4 分，满分 24。

维度 1：配色审计

检查项	方法
主色是否正确使用	检查 CSS 变量/className 是否匹配 DESIGN.md 2 的 hex 值
中性色是否"有色"	纯黑 #000 / 纯灰 #f5f5f5 -> AI slop，需要 5-10% 色相偏移
语义色覆盖	成功/警告/错误状态是否用了指定颜色
暗色模式	如有 DESIGN.md 暗色定义，是否实现

维度 2：字体审计

检查项	方法
字体是否正确加载	检查 font-family 是否匹配 DESIGN.md 3
层级是否正确	H1-H5、正文、Caption 的大小/字重/行高是否在 DESIGN.md 容差内
禁止字体	Inter / Roboto / Arial / Space Grotesk 作为默认字体 -> 标记

维度 3：间距与布局审计

检查项	方法
间距是否在刻度上	检查 padding/margin/gap 是否在 DESIGN.md 5 的间距刻度内
最大宽度	内容区是否超过 DESIGN.md 规定的最大宽度
卡片网格	是否使用了"完全相同的卡片 xN 排列" -> AI slop 标记
居中一切	是否所有元素居中对齐 -> 缺少空间决策

维度 4：组件审计

检查项	方法
按钮状态完整	是否有 hover/focus/active/disabled 态
圆角一致性	同类组件圆角是否统一
阴影层级	阴影是否匹配 DESIGN.md 6 的层级定义
触控尺寸	交互元素是否 >= 44x44px

维度 5：AI Slop 扫描

打开已渲染的页面，做自检：

"如果在旁边放一个不认识项目的人，问'你觉得这是 AI 生成的还是设计师做的？'，他会犹豫还是直接点头？"

他会犹豫 → 通过自检。 他会直接点头 → 扫一遍 references/ai-slop-catalog.md 找漏网之鱼。找到后问自己：这个设计我用它是因为它是对的，还是因为它是最省事的？如果是后者，换掉它。

维度 6：可访问性审计

检查项	方法
颜色对比度	正文 vs 背景：对比度 ≥ 4.5:1？大文字 vs 背景：≥ 3:1？
focus 可见	所有交互元素有可见的 focus 样式？Tab 键能否遍历所有可操作元素？
状态传达	错误/成功/警告状态是否配合了图标或文字（不只靠颜色）？
alt 属性	所有 <img> 有有意义的 alt 属性？纯装饰图片有 alt=""？

审计输出格式（白话诊断，非技术报告）：

## 设计审计：[项目名]

### RED: Slop（一看就是 AI 做的）
- 整个页面紫蓝渐变背景 + 白色卡片 -> 最经典的 AI 默认审美
  位置: app/page.tsx | 修复: 换 DESIGN.md 指定的配色方案

### YELLOW: 不一致（和设计规范对不上）
- 按钮用 #0066CC，但 DESIGN.md 指定主色是 #5E6AD2
  位置: components/ui/button.tsx:15 | 修复: 替换为 DESIGN.md 2 的 Primary CTA

- 卡片间距 20px，不在间距刻度 (4/8/12/16/24/32) 内
  位置: app/dashboard/page.tsx:42 | 修复: 改为 16px 或 24px

### GREEN: 建议
- 3 个卡片组件有重复的样式，建议抽取一个 Card 组件

评分表：

维度	分数	说明
配色	?/4
字体	?/4
间距与布局	?/4
组件	?/4
AI Slop	?/4
可访问性	?/4

纪律：

• 每条发现带 file:line，不含糊
• 评分不是目的：诊断+修复路径才是
• 不和 DESIGN.md 比较"谁更好"，只比较"是否一致"

输出：审计报告（分类 + 评分 + 修复入口）

---

Phase D8：CRITIQUE（UX 评估）

门禁：AUDIT 完成

流程：不只看设计规范，看玩家体验。

评估维度	核心问题
信息层级	最重要的东西是不是视觉上最突出？一眼扫过去，眼睛应该落在哪？实际落在那了吗？
操作清晰度	不看任何说明，能知道这个页面怎么用吗？按钮的文案说了"点了会发生什么"吗？
情感感受	用了之后什么感觉？专业可信？轻松愉快？焦虑不安？设计规范想传达的感觉达到了吗？
认知负荷	这个页面一次呈现了多少信息？有没有可以折叠/延后/去掉的？

输出：UX 评估（4 维度 + 优先级 + 建议）

---

Phase D9：POLISH（打磨修复）

门禁：用户确认修哪些（从 AUDIT + CRITIQUE 的发现中选择）

流程：修复管线：typeset -> colorize -> arrange -> AI slop 复检 -> 一致性终检

for each 选中的问题（按 RED -> YELLOW -> GREEN 顺序）:
  STEP 1: 独立修复，只改 UI 不动功能
  STEP 2: 运行 TypeScript 编译 + 视觉回归（截图对比前后）
  STEP 3: 复检：修完后这个维度重新打分
    分数提升 -> commit
    分数不变或降低 -> 回滚，标记 STUCK

全部修完后：
  AI Slop 终检：现在给人看，还会说"这就是 AI 做的"吗？

收敛规则：

1 轮修复 -> 复检 -> 仍有 Slop -> 再修 1 轮 -> 最多 2 轮
2 轮后仍有 Slop -> 记录为已知问题，归入"未来版本优化"

纪律：

• 只改样式不碰逻辑：不准改 hooks/state/API 调用
• 优先修 Slop 标记："一看就是 AI 做的"是零容忍项
• 不确定改得对不对 -> 改完截图给用户看，不等用户说"继续"

输出：修复后的 UI + 修复清单（每项: 问题 -> commit -> 新评分）

---

Phase D10：SATISFACTION GATE（满意度门禁）

门禁：必入

→ 执行满意度门禁（详见 hlvibes/references/satisfaction-gate.md）。当前阶段名称：「设计审计与打磨」。

---

Phase D11：HANDOFF（Post-build 交付）

门禁：满意度门禁通过

→ 执行交付（详见 hlvibes/references/handoff.md）。产出设计审计报告，写入 .vibe/doc/REVIEW.md 的设计章节。

HANDOFF 报告格式

## 设计审计

### 评分
- 配色 / 字体 / 间距与布局 / 组件 / AI Slop / 可访问性：各 ?/4 → 总分 ?/24

### 修复记录
- [S01] Fix: [问题] -- commit [hash]

### 遗留
- [遗留项] → 建议 [版本]

---

AI Slop Test 方法论

一级测试（First-Order）：从产品类别能猜到配色吗？

不看项目名，只看产品类型——你猜想 AI 会用"什么风格"来做这个？

"能猜到" → 你的配色方案是 AI 的默认选择，回到 D5 换一个方向。 "猜不到" → 通过。

二级测试（Second-Order）：知道产品类型和反参考后，还能猜到审美方向吗？

告诉别人"不是常见的 [类别] 风格"，再看审美方向是否可预测。

"能猜到" → 仍然在 AI 的舒适区，回到 D5 调整签名元素或配色方向。 "猜不到" → 通过。

通过标准

一级测试猜不到配色，且二级测试猜不到审美方向 = 通过 AI Slop Test。

常见失败案例见 references/ai-slop-catalog.md。

---

通用纪律

→ 完整通用纪律见 hlvibes/references/common-rules.md。