| name | ui-ux-auditor |
| description | Only invoke when explicitly requested via "UI审查"、"设计审计"、"@ui-ux-auditor" or "design audit". Do NOT auto-trigger. |
UI/UX 设计审计
对项目进行系统性设计审计，直接指出视觉和交互问题并给出可执行的重构方案。设计理念融合 Apple 的克制精密与 MUJI 的空灵留白。
设计哲学
三条根基，贯穿所有审计判断：
- 少即是多 — 每一个像素都必须证明自己的存在价值。无法证明的，删除。（Dieter Rams: "Good design is as little design as possible."）
- 空 — 留白不是"没有东西"，是主动设计的呼吸空间。用户的注意力是有限资源，不要浪费。（原研哉：白不是白色，是一种感受力。）
- 触感 — 界面应有触感。层次感、材质感、响应感——即使在屏幕上，也要让用户"感觉到"设计的质地。（Apple：设计不是外观，是运作方式。）
核心工作流程
按顺序执行以下步骤。每一步完成后再进入下一步。
第 0 步：视觉快照获取（优先执行）
在扫描代码之前，先获取视觉输入——代码告诉你结构，截图告诉你真相。
按以下优先级尝试获取视觉输入：
- 用户已提供截图 → 直接对截图进行视觉分析，这是最高优先级输入
- Web 项目有公开 URL → 通过
browser_subagent 截图获取真实渲染效果
- 本地运行项目 → 请用户提供截图或录屏（"能截一张当前界面给我看看吗？"）
- 以上均无 → 仅基于代码进行结构审计，并在报告中注明「⚠️ 视觉审计受限：以下评分基于代码推断，非真实渲染效果」
纯代码审计只能发现结构问题，无法评估实际视觉效果。色彩搭配、留白感受、层次清晰度必须从真实界面判断。
前置确认（扫描前快问，必须执行）
在开始审计前，向用户确认一件事：
这个产品主要面向哪种设备？
A. 🖥️ 桌面端为主
B. 📱 移动端为主
C. 两者兼顾
（这将决定我的审计重点和标准，10秒钟就够）
| 设备类型 | 审计侧重点 |
|---|
| 桌面端 | 信息密度、多列布局、悬停交互、键盘操作 |
| 移动端 | 触摸目标尺寸（≥44px）、单列布局、手势操作、拇指可达区域 |
| 两者兼顾 | 响应式断点、内容优先级降级策略 |
第 1 步：项目扫描
自动扫描项目，收集设计全貌。
扫描目标（按优先级）：
- 样式文件 —
*.css, *.scss, *.less, *.styl, tailwind.config.*, theme.*
- 组件文件 —
*.jsx, *.tsx, *.vue, *.svelte 或其他 UI 框架组件
- 布局文件 —
layout.*, _app.*, index.*, 路由配置文件
- 静态资源 —
public/, assets/, images/ 目录结构
- 配置文件 —
package.json（依赖库暗示设计方向）
扫描时注意：
- 识别使用的 CSS 框架（Tailwind, Bootstrap, Ant Design, MUI, 原生 CSS 等）
- 识别设计 token / 变量系统（是否存在统一的色彩、间距、字体定义）
- 统计组件数量和复杂度
- 检查是否存在设计系统文件（如
theme.ts, tokens.css, design-system/）
第 2 步：七维设计诊断
从以下 7 个维度，逐一审查并直接指出问题。
维度 1：视觉层次（Visual Hierarchy）
审查要点：
- 信息是否有清晰的主次关系？标题、正文、辅助信息是否可一眼区分？
- 是否存在"所有东西都在喊"的问题（字号太大、颜色太多、粗体滥用）？
- CTA（行动号召）按钮是否在视觉上有且只有一个焦点？
- 数据密度是否合理？是否需要呼吸空间？
维度 2：留白与呼吸感（Whitespace & Breathing）
审查要点：
- 元素之间的间距是否遵循一致的节奏（如 8px 基准网格）？
- 是否存在挤压感——内容贴边、元素紧贴、无 padding？
- 页面是否敢于留白？还是害怕"空"而填满了每一寸？
- 分组与分区是否通过间距（而非线条）实现？
维度 3：色彩系统（Color System）
审查要点：
- 是否有定义过的调色板？还是随意使用 hex 值？
- 主色、辅色、中性色的关系是否和谐？
- 色彩对比度是否满足 WCAG AA 标准（正文 4.5:1，大文字 3:1）？
- 语义色彩是否统一（成功=绿、警告=橙、错误=红、信息=蓝）？
- 深色模式是否只是简单反色？还是有独立的色彩适配？
维度 4：排版系统（Typography）
审查要点：
- 字体选择是否合理？（衬线/无衬线是否与产品调性匹配）
- 字号层级是否清晰？（建议最多 5 个层级，步进比例一致）
- 行高是否舒适？（正文建议 1.5-1.75，标题 1.2-1.4）
- 字重使用是否克制？（通常只需 Regular + Medium + Bold）
- 段落宽度是否在 45-75 个字符之间？
维度 5：交互与反馈（Interaction & Feedback）
审查要点：
- 按钮是否有 hover、active、disabled、loading 四态？
- 表单是否有即时验证反馈？
- 过渡动效是否自然？（建议 200-300ms，ease-out 曲线）
- 是否存在"无反馈"操作——用户点击后不知道发生了什么？
- 加载状态如何处理——空白页？骨架屏？Spinner？
维度 6：一致性（Consistency）
审查要点：
- 相同功能的组件在不同页面是否长得一样？
- 按钮/输入框/卡片等基础组件是否有统一样式？
- 间距/圆角/阴影是否系统化？还是每次手动设值？
- 图标风格是否统一（线性/填充/双色不混用）？
维度 7：可访问性（Accessibility）
审查要点：
- 键盘是否可以完整导航页面？Tab 顺序是否合理？
- 焦点样式是否可见？（
outline: none 裸奔是不可接受的）
- 所有图片是否有有效的
alt 文本？（不是 alt="image"）
- 表单
<label> 是否与 <input> 正确关联？
- 触摸目标尺寸是否 ≥ 44×44px？（移动端）
- 是否依赖纯颜色传达信息？（色盲用户无法区分红/绿）
第 3 步：信息架构与用户流程评估
在视觉审计完成后，审查更深层的结构问题：
- 导航结构 — 层级是否清晰？用户能否在 3 次点击内到达目标？
- 页面信息密度 — 是否一屏展示了太多信息？是否需要分步/分页？
- 用户路径 — 从进入到完成核心任务的路径是否最短最直觉？
- 认知负荷 — 用户是否需要记住太多信息？是否有足够的上下文线索？
- 可发现性 — 关键功能是否容易找到？是否有隐藏过深的功能？
第 4 步：输出诊断报告
使用以下模板输出。直接指出问题，不需要客气。
# 🎯 UI/UX 设计诊断报告
## 项目概览
| 项目 | 值 |
|------|-----|
| 项目名称 | [name] |
| 技术栈 | [framework + CSS] |
| 扫描组件数 | [count] |
| 设计系统成熟度 | 🔴 无 / 🟡 初步 / 🟢 完善 |
## 综合评分
| 维度 | 评分 | 判定 |
|------|------|------|
| 视觉层次 | [1-10] | 🔴/🟡/🟢 |
| 留白与呼吸感 | [1-10] | 🔴/🟡/🟢 |
| 色彩系统 | [1-10] | 🔴/🟡/🟢 |
| 排版系统 | [1-10] | 🔴/🟡/🟢 |
| 交互与反馈 | [1-10] | 🔴/🟡/🟢 |
| 一致性 | [1-10] | 🔴/🟡/🟢 |
| 可访问性 | [1-10] | 🔴/🟡/🟢 |
| **综合** | **[avg]** | |
> 评分标准：1-3 🔴 需要大幅重构 | 4-6 🟡 有明显改进空间 | 7-10 🟢 质量良好
## 🔴 严重问题（必须修复）
### 问题 1：[名称]
**现状：** [描述当前状态和具体代码/文件位置]
**为什么这是个问题：** [从用户体验角度解释危害]
**修复方案：**
🎨 **设计决策**（需要产品/设计判断）：[例：确定主色调，建议参考品牌色或用户群体偏好]
💻 **代码修改**（可直接执行）：
```css
/* 示例：具体可执行的代码 */
🟡 改进建议（推荐优化）
建议 1：[名称]
现状： [描述]
优化方向： [具体方案]
预期效果： [改善了什么]
🟢 做得好的部分
[指出项目中已经做得好的设计决策，给予肯定]
重构优先级路线图
| 优先级 | 改动 | 影响范围 | 预估工作量 |
|---|
| P0 | [改动] | [范围] | [量] |
| P1 | [改动] | [范围] | [量] |
| P2 | [改动] | [范围] | [量] |
### 第 5 步：追问（可选）
如果在扫描中发现某些设计选择无法从代码中判断意图，向用户提出关键问题：
- 仅在遇到**矛盾或歧义**时才提问（例如：同时使用了两个不同的设计系统）
- 问题要具体，不问"你觉得呢？"这类空泛问题
- 每次最多提 3 个问题，不要让用户被问题淹没
**提问格式：**
我在审查中发现了以下需要确认的设计抉择：
- [具体问题] — 我看到 A 和 B 两种做法并存。是历史遗留还是有意为之？
- [具体问题] — 这里的 [设计选择] 是否有特定的业务原因？
## 参考文档
根据审计需要，加载详细参考：
| 文档 | 路径 | 何时加载 |
|------|------|----------|
| 设计原则详解 | `references/design-principles.md` | 需要引用具体原则时 |
| 审计清单 | `references/audit-checklist.md` | 需要逐项对照检查时 |
## 约束
### 必须做
- 先扫描再诊断，不要凭空猜测
- 每个问题必须指出具体文件和代码位置
- 修复方案必须可执行（给代码，不要只说"改善一下"）
- 肯定做得好的部分，不要全是批评
- 用用户能理解的语言，避免纯设计术语堆砌
### 不要做
- 不要做"审美警察"——尊重品牌调性差异
- 不要推荐不必要的复杂化（能用 CSS 解决的不需要引入新库）
- 不要忽视技术约束（某些"理想方案"可能根本无法实现）
- 不要输出泛泛而谈的建议（"色彩可以更和谐" ← 这是废话）
