24 - UI 美化指南
doc-11 定义了三阶段 UI 开发工作流：骨架 → 验证 → 美化。本文档是第三阶段的深度手册——功能稳定后，如何用 AI 高效完成视觉翻新。
执行者：Designer Agent（.claude/agents/designer.md）。Developer Agent 负责 Phase 1-2 的功能骨架，Designer Agent 接手 Phase 3 的视觉美化。Designer Agent 的知识库（agents/designer/knowledge/）包含本文档方法论的可操作子集：
| 知识文件 | 内容 | 与本文档的关系 |
|---|---|---|
visual-checklist.md | 7 条高频视觉问题诊断 + 修复模式 | §2 方法论的前置步骤——先做减法修问题，再做加法上风格 |
baseline-tokens.md | 跨风格通用组件 Token（按钮/容器/字体/间距） | §3 风格预设的基础层——无论选哪套预设都适用的基线值 |
style-presets.md | 风格选型决策树 + 反同质化清单 | §3 风格预设的判断指南，不重复 Token 值 |
1. 与 design-spec 的关系
有 design-spec.md → 按 Token 系统执行，本文档的风格预设仅作填写起点
无 design-spec.md → 从 §3 选一套风格预设，写入 CLAUDE.md，AI 直接遵循两条路径都能工作。区别是 design-spec 提供项目级的完整约束（含组件规范、交互模式），风格预设只覆盖视觉 Token 层。中小项目直接用预设足够；多页面正式产品建议走 design-spec。
2. 方法论
2.1 Research First — 先研究再动手
直接让 AI "做一个漂亮的 Dashboard"，它会从训练数据中随机采样，产出平庸且不可预测。正确做法是加一步研究：
第一轮（研究）：
"研究 Linear / Vercel / Stripe 的 Dashboard 设计模式，
总结它们共同的视觉特征：配色策略、字体层级、间距节奏、卡片样式、动效。"
第二轮（执行）：
"基于以上研究结果，美化我的 Dashboard 页面。保持功能不变，只改样式。"AI 有了明确的参考锚点后，输出质量显著提升。这个方法对任何风格都适用——关键是给 AI 一个具体的目标，而不是让它自由发挥。
2.2 截图驱动 — 视觉参考胜过千言万语
文字描述"现代简约风"，十个人有十种理解。截图是最高效的视觉沟通方式：
操作流程：
- 从 Mobbin / Godly / Dribbble 收集 2-3 张目标风格截图
- 发给 AI，要求分析截图的设计模式（配色、间距、字体、组件风格）
- AI 基于分析结果生成代码
AI 能从截图中提取的信息远超文字描述：配色方案、对比度、间距节奏、组件组合模式、字体层级。尤其适合"我说不清楚但看到就知道"的场景。
2.3 像设计总监提示 — 技术约束 + 视觉方向
多数开发者只给功能需求，缺少视觉方向。同时给出两者，AI 才能生成兼顾功能和美感的代码。
❌ 差的提示：
做一个用户列表页面✅ 好的提示：
做一个用户列表页面。参考 Linear 的极简风格：
- 14px 正文 / 20px 标题的字体层级
- 卡片 hover 时 subtle shadow 过渡（200ms ease）
- 表格行间距宽松（py-4）
- 空状态需要插画引导
- 使用 shadcn/ui Table + Badge + Avatar2.4 微交互收尾 — 好与优秀的差距
静态 UI 完成后，追加一步动画层。这是区分"能用"和"好用"的关键：
"为这个页面添加微交互，保持功能不变：
- 卡片 hover 缩放 1.02 + shadow 加深（duration-200 ease-out）
- 列表项交错入场动画（stagger 50ms，fade-in + translateY 8px）
- 按钮点击弹簧回弹效果
- 页面切换 fade 过渡"注意节制——微交互是调味料，不是主菜。每个动画都应该有功能目的（引导注意力、确认操作、建立空间关系），纯装饰性动画适得其反。
3. 风格预设速查
参考层，时效 2025-2026。选择建议：不确定就用 Clean Minimal，它最安全；想要辨识度就用 Neo-Brutalism 或 Dark Premium。
3.1 Clean Minimal — 干净极简
适合：SaaS、后台管理、工具类产品。最安全的选择，不会出错。
| Token | 值 |
|---|---|
| 背景 | 白 #FFFFFF，浅灰区块 #F9FAFB |
| 文字 | 主 #111827，次 #6B7280 |
| 强调色 | 蓝 #2563EB 或紫 #7C3AED（只用一个） |
| 字体 | Inter / Geist Sans，正文 14-16px，标题 24-32px，行高 1.5-1.6 |
| 圆角 | 8-12px（rounded-lg / rounded-xl） |
| 阴影 | shadow-sm 或 shadow-md，极淡 |
| 间距 | 宽松：section 间 64-96px，卡片内 24px |
| 动画 | hover scale 1.02，transition 150-200ms ease |
代表：Linear, Vercel, Stripe Dashboard
Prompt 模板（复制即用）：
使用 Clean Minimal 风格。白色背景，大量留白，单一蓝色强调色 #2563EB。
Inter 字体，14px 正文 / 24px 标题。卡片用 rounded-xl + shadow-sm。
hover 时 subtle shadow 加深，transition-all duration-200。
保持功能不变，只改样式。3.2 Glassmorphism — 玻璃拟态
适合：Landing page、登录页、仪表盘、科技感产品。
| Token | 值 |
|---|---|
| 背景 | 深色渐变（深紫 #1a1a2e → 深蓝 #16213e） |
| 卡片 | bg-white/10 到 bg-white/20 |
| 模糊 | backdrop-blur-xl（16-24px） |
| 边框 | 1px border-white/20，微妙高光 |
| 阴影 | shadow-2xl + 低透明度 |
| 圆角 | 16-24px（rounded-2xl） |
| 文字 | 白 #FFFFFF，次要 #CBD5E1 |
| 光斑 | 背景 2-3 个大面积模糊渐变色块（紫/蓝/粉） |
代表：Apple Liquid Glass, Windows 11 Fluent
Prompt 模板：
使用 Glassmorphism 风格。深色渐变背景（从 #1a1a2e 到 #16213e），
卡片 bg-white/10 + backdrop-blur-xl + border border-white/20 + rounded-2xl。
背景放 2-3 个大面积模糊渐变色块（紫/蓝/粉）。
文字白色，强调色亮青 #22D3EE。保持功能不变。3.3 Soft UI — 柔和立体
适合：控制面板、音乐播放器、智能家居、仪表盘。
| Token | 值 |
|---|---|
| 背景 | 浅灰 #F0F0F3 |
| 元素 | 同色系，与背景融为一体 |
| 阴影 | 双阴影：shadow-[8px_8px_16px_#d1d1d1,-8px_-8px_16px_#ffffff] |
| 交互 | 按下时阴影反转为 inset（凸→凹） |
| 圆角 | 12-20px（rounded-2xl） |
| 强调 | 柔和渐变色点缀（按钮/进度条） |
代表：Dribbble 上的仪表盘概念设计
Prompt 模板：
使用 Soft UI 风格。背景 #F0F0F3，元素同色系。
每个可交互元素双阴影：shadow-[8px_8px_16px_#d1d1d1,-8px_-8px_16px_#ffffff]。
按钮按下时阴影反转为 inset。圆角 rounded-2xl。
强调色用柔和渐变。保持功能不变。3.4 Neo-Brutalism — 新粗野主义
适合：创意类、个人网站、独立产品。想要辨识度的首选。
| Token | 值 |
|---|---|
| 配色 | 高饱和撞色：亮黄 #FFE500、粉 #FF6B9D、蓝 #3B82F6、黑 #000 |
| 边框 | 粗黑 2-4px border-2 border-black |
| 阴影 | 硬阴影无模糊 shadow-[4px_4px_0px_#000] |
| 字体 | 粗体为主，大号标题，Space Grotesk / DM Sans |
| 圆角 | 小 4-8px 或直角 |
| hover | 阴影偏移 shadow-[6px_6px_0px_#000] + translate(-2px,-2px) |
| active | 阴影归零 + translate 归零（按下感） |
代表：Gumroad, Figma Community
Prompt 模板：
使用 Neo-Brutalism 风格。高饱和配色（亮黄 #FFE500 为主背景 + 黑色文字）。
所有卡片和按钮 border-2 border-black + shadow-[4px_4px_0px_#000]。
hover 时 shadow-[6px_6px_0px_#000] + -translate-x-0.5 -translate-y-0.5。
active 时 shadow-none translate-0。字体粗、大。保持功能不变。3.5 Bento Grid — 便当盒布局
适合：产品介绍页、Feature 展示、Dashboard 概览。严格说是布局模式而非视觉风格，可与其他风格组合使用。
| Token | 值 |
|---|---|
| 布局 | CSS Grid，混合 1x1、2x1、1x2、2x2 卡片 |
| 间距 | gap 16-24px（gap-4 / gap-6） |
| 卡片 | 各自独立背景色 + rounded-2xl + p-6 |
| 内容 | 每格一个 feature：图标 + 标题 + 简述 或 小型可视化 |
| 动画 | 交错入场 stagger 50-100ms，hover 微缩放 1.02 |
代表：Apple 产品页, GitHub Homepage
Prompt 模板：
使用 Bento Grid 布局展示功能特性。CSS Grid 混合不同尺寸卡片
（col-span-1/2, row-span-1/2）。gap-4 或 gap-6。
每个卡片独立浅色背景 + rounded-2xl + p-6。
入场动画 stagger fade-in-up。保持功能不变。3.6 Dark Premium — 暗色高级感
适合：开发者工具、AI 产品、加密/金融、高端品牌。
| Token | 值 |
|---|---|
| 背景 | 纯黑 #09090B 或深灰 #18181B |
| 文字 | 主 #FAFAFA，次 #A1A1AA |
| 强调 | 渐变文字 from-blue-400 via-purple-400 to-pink-400 |
| 边框 | 极细 border-zinc-800 |
| 光效 | 顶部 radial-gradient 蓝紫光晕，按钮 hover glow |
| 字体 | Geist Sans + Geist Mono（代码），紧凑行高 |
| 背景纹理 | 微妙网格点或噪点 |
代表：Vercel, Raycast, OpenAI
Prompt 模板：
使用 Dark Premium 风格。背景 #09090B，文字 #FAFAFA，次要 #A1A1AA。
卡片 bg-zinc-900 + border border-zinc-800 + rounded-xl。
标题渐变色 bg-gradient-to-r from-blue-400 via-purple-400 to-pink-400
bg-clip-text text-transparent。页面顶部加大面积模糊蓝紫色光晕。
按钮 hover 加 glow shadow。保持功能不变。4. 工具与配置
4.1 shadcn Skills — 让 AI 了解你的项目
AI 生成 UI 质量不高的首要原因是不了解项目上下文——不知道你装了哪些组件、用什么 Tailwind 配置、什么 import 路径。shadcn Skills 解决这个问题：
npx skills add shadcn/ui安装后 AI 能读取 components.json，第一次就生成正确的代码。推荐 Skills 组合：
| Skill | 作用 |
|---|---|
shadcn-ui | 组件注册表感知，正确的 import 和用法 |
frontend-design | 美学原则（原则型，不过度约束创造力） |
web-accessibility | 无障碍合规 |
web-design-guidelines | 通用 Web 设计规范 |
安全提醒：Snyk ToxicSkills 研究发现社区 Skills 中 36% 存在 prompt injection。安装前务必审查 SKILL.md 内容。Skills 规范已被 Claude Code / Codex / Cursor / Gemini CLI 等多平台采纳，是开放标准。
4.2 AI 原生设计工具
参考层，时效 2026 年初。工具迭代快，链接和能力以官方为准。
代码侧（开发者直接用）：
| 工具 | 特点 | 与本体系的配合 |
|---|---|---|
| v0 (Vercel) | 文字/截图→React 组件，默认 shadcn/ui + Tailwind | 生成组件后复制到项目，走 /review 审查 |
| Flowstep | 无限画布构建完整 flow，截图捕捉任意网站 UI | 导出 React/Tailwind 代码，适合整页参考 |
| Motiff AI | 线框图→高保真 UI，一键导出 React/HTML | 适合从草图快速出视觉方案 |
设计侧（非开发者友好）：
| 工具 | 特点 |
|---|---|
| Google Stitch (原 Galileo AI) | 文字描述→完整 UI + HTML/CSS |
| Figma Make | 自然语言→Figma 原型，无缝进入精修 |
这些工具的产出都可以作为截图参考喂给 Claude Code，走 §2.2 的截图驱动流程。不需要绑定任何一个工具。
4.3 避免同质化
大量项目使用 v0 + shadcn 默认配置，导致 UI "千篇一律"。AI 没有视觉方向时，会从训练数据的统计中心采样——Inter 字体、灰蓝配色、相同的卡片布局。
对策：
- 自定义 Preset：在 shadcn/ui 的 Presets 机制中定义品牌配色、字体、圆角，AI 和团队共享同一套 Token
- 选择差异化风格：§3 的 Neo-Brutalism 和 Dark Premium 天然避开"默认脸"
- 独特字体：换掉 Inter。Space Grotesk、DM Sans、Outfit、Sora 都是免费的优质替代
- 个性化微交互：相同的布局，不同的动效就能建立辨识度
5. 写入 CLAUDE.md 的模板
选定风格后，在项目 CLAUDE.md 中加入以下内容（以 Dark Premium 为例），AI 生成代码时自动遵循：
## UI 风格
本项目使用 Dark Premium 风格：
- 背景 #09090B，文字 #FAFAFA，次要文字 #A1A1AA
- 卡片：bg-zinc-900 + border border-zinc-800 + rounded-xl
- 强调色：蓝紫渐变 from-blue-400 via-purple-400 to-pink-400
- 按钮 hover 加 glow，交互 transition-all duration-200
- 字体 Geist Sans + Geist Mono3-5 行足够。AI 需要的是明确的约束，不是详尽的规格书——详尽的部分交给 design-spec.md。
前置文档：11-UI 开发策略（三阶段工作流、技术栈选型） | 23-产品设计契约（design-spec 完整流程）关联模板：docs/templates/design-spec-template.md（Token 系统完整定义）执行 Agent：Designer Agent（视觉诊断与美化） | 知识库 agents/designer/knowledge/