ux-audit

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

UX Audit

UX审计

Walk through live web apps as a real user to find usability issues and verify functionality. Uses Chrome MCP (for authenticated apps with your session) or Playwright for browser automation. Produces structured audit reports with findings ranked by impact.

以真实用户的视角遍历在线Web应用，找出可用性问题并验证功能。使用Chrome MCP（用于带会话的已认证应用）或Playwright实现浏览器自动化。生成结构化审计报告，其中发现的问题按影响程度排序。

Browser Tool Detection

浏览器工具检测

Before starting any mode, detect available browser tools:

Chrome MCP (
```
mcp__claude-in-chrome__*
```
) — preferred for authenticated apps. Uses the user's logged-in Chrome session, so OAuth/cookies just work.
Playwright MCP (
```
mcp__plugin_playwright_playwright__*
```
) — for public apps or parallel sessions.
playwright-cli — for scripted flows and sub-agent browser tasks.

If none are available, inform the user and suggest installing Chrome MCP or Playwright.

See references/browser-tools.md for tool-specific commands.

在启动任何模式之前，先检测可用的浏览器工具：

Chrome MCP (
```
mcp__claude-in-chrome__*
```
) —— 优先用于需要身份验证的应用。使用用户已登录的Chrome会话，因此OAuth/Cookie可直接生效。
Playwright MCP (
```
mcp__plugin_playwright_playwright__*
```
) —— 用于公共应用或并行会话。
playwright-cli —— 用于脚本化流程和子代理浏览器任务。

如果没有可用工具，告知用户并建议安装Chrome MCP或Playwright。

查看references/browser-tools.md获取工具专属命令。

Operating Modes

运行模式

Mode 1: UX Walkthrough

模式1：UX走查

When: "ux walkthrough", "walk through the app", "is the app intuitive?", "ux audit"

This is the highest-value mode. Instead of mechanically clicking buttons, walk through the app as a first-time user performing a realistic task.

Ask the user for a task scenario (e.g., "I need to create a new patient and book them for surgery")
Navigate to the app's entry point
Attempt the task as a first-time user would — no prior knowledge of the UI
At each screen, evaluate against the walkthrough checklist (see references/walkthrough-checklist.md):
- Is the next step obvious without thinking?
- Do labels and icons make sense?
- Is navigation discoverable?
- Are dangerous actions (delete, override) guarded?
- Is the most important information prominent?
- Does the result match my expectation?
Take screenshots at friction points
After completing (or failing) the task, compile findings into a UX audit report
Write report to
```
docs/ux-audit-YYYY-MM-DD.md
```
using the template from references/report-template.md

Severity levels:

Critical — blocks the user from completing their task
High — causes confusion or significant friction
Medium — suboptimal but the user can work around it
Low — polish and minor improvements

触发指令："ux walkthrough"、"walk through the app"、"is the app intuitive?"、"ux audit"

这是价值最高的模式。不同于机械点击按钮，会以首次使用用户的视角完成一项真实任务。

向用户索要任务场景（例如："我需要创建一个新患者并为其安排手术"）
导航至应用入口
以首次使用用户的方式尝试完成任务——不预设任何UI相关知识
在每个页面，对照走查清单（查看references/walkthrough-checklist.md）进行评估：
- 无需思考就能明确下一步操作吗？
- 标签和图标表意清晰吗？
- 导航是否易于发现？
- 危险操作（删除、覆盖）是否有防护机制？
- 最重要的信息是否突出显示？
- 操作结果符合预期吗？
在体验痛点处截取屏幕截图
完成（或失败）任务后，将发现的问题整理成UX审计报告
使用references/report-template.md中的模板，将报告写入
```
docs/ux-audit-YYYY-MM-DD.md
```

严重等级：

严重 —— 阻碍用户完成任务
高 —— 造成困惑或显著体验障碍
中 —— 体验不佳但用户可绕过
低 —— 细节优化和小幅改进

Mode 2: QA Sweep

模式2：QA全面扫描

When: "qa test", "test all pages", "check everything works", "qa sweep"

Systematic mechanical testing of all pages and features.

Discover pages: Read the app's router config, sitemap, or manually navigate the sidebar/menu to find all routes
Create a task list of areas to test (group by feature area)
For each page/feature:
- Page renders without errors
- Data displays correctly (tables, lists, details)
- Forms submit successfully (create)
- Records can be edited (update)
- Delete operations work with confirmation
- Validation fires on bad input
- Empty states display correctly
- Error states are handled
Cross-cutting concerns:
- Dark mode: all elements visible, no contrast issues
- Mobile viewport (375px): layout doesn't break, touch targets adequate
- Search and filters: return correct results
- Notifications: display and can be dismissed
Produce a QA sweep summary table:

Page Status Issues
/patients Pass —
/patients/new Fail Form validation missing on email
Write report to
```
docs/qa-sweep-YYYY-MM-DD.md
```

Page	Status	Issues
/patients	Pass	—
/patients/new	Fail	Form validation missing on email

触发指令："qa test"、"test all pages"、"check everything works"、"qa sweep"

对所有页面和功能进行系统性机械测试。

发现页面：读取应用的路由配置、站点地图，或手动遍历侧边栏/菜单以找到所有路由
创建测试任务清单（按功能模块分组）
针对每个页面/功能：
- 页面渲染无错误
- 数据显示正确（表格、列表、详情）
- 表单提交成功（创建操作）
- 记录可编辑（更新操作）
- 删除操作需确认且可正常执行
- 输入错误时触发验证
- 空状态显示正确
- 错误状态处理得当
跨模块检查项：
- 深色模式：所有元素可见，无对比度问题
- 移动端视口（375px）：布局无错乱，触控目标尺寸合适
- 搜索和筛选：返回正确结果
- 通知：可正常显示并关闭
生成QA全面扫描汇总表：

页面状态问题
/patients 通过 —
/patients/new 失败表单缺少邮箱验证
将报告写入
```
docs/qa-sweep-YYYY-MM-DD.md
```

页面	状态	问题
/patients	通过	—
/patients/new	失败	表单缺少邮箱验证

Mode 3: Targeted Check

模式3：针对性检查

When: "check [feature]", "test [page]", "verify [component] works"

Focused testing of a specific area.

Navigate to the specific page or feature
Test thoroughly — all states, edge cases, error paths
Report findings inline (no separate file unless user requests)

触发指令："check [feature]"、"test [page]"、"verify [component] works"

针对特定区域的聚焦测试。

导航至目标页面或功能
全面测试——所有状态、边缘情况、错误路径
直接返回检查结果（除非用户要求，否则不生成单独文件）

When to Use

适用场景

Scenario	Mode
After building a feature, before showing users	UX Walkthrough
Before a release, verify nothing is broken	QA Sweep
Quick check on a specific page after changes	Targeted Check
Periodic UX health check	UX Walkthrough
Client demo prep	QA Sweep + UX Walkthrough

Skip this skill for: API-only services, CLI tools, unit/integration tests (use test frameworks), performance testing.

场景	对应模式
功能开发完成后，面向用户展示前	UX走查
发布前，验证功能无异常	QA全面扫描
变更后快速检查特定页面	针对性检查
定期UX健康检查	UX走查
客户演示准备	QA全面扫描 + UX走查

不适用场景：仅API服务、CLI工具、单元/集成测试（使用测试框架）、性能测试。

Autonomy Rules

自主操作规则

Just do it: Navigate pages, take screenshots, read page content, evaluate usability
Brief confirmation: Before starting a full QA sweep (can be lengthy), before writing report files
Ask first: Before submitting forms with real data, before clicking delete/destructive actions

直接执行：遍历页面、截取屏幕、读取页面内容、评估可用性
简短确认：在启动完整QA扫描（可能耗时较长）之前、在写入报告文件之前
先询问：在提交含真实数据的表单之前、在点击删除/破坏性操作之前

Tips

提示

Chrome MCP is ideal for authenticated apps — it uses your real session
For long QA sweeps, use the task list to track progress across pages
Take screenshots at key friction points — they make the report actionable
Run UX walkthrough before QA sweep — finding "buttons work but users are confused" is more valuable than "all buttons work"

Chrome MCP是已认证应用的理想选择——使用真实会话
对于长时间的QA全面扫描，使用任务清单跟踪跨页面的测试进度
在关键体验痛点处截取屏幕截图——让报告更具可执行性
先执行UX走查再做QA全面扫描——发现“按钮可用但用户困惑”比“所有按钮可用”更有价值

Reference Files

参考文件

When	Read
Evaluating each screen during walkthrough	references/walkthrough-checklist.md
Writing the audit report	references/report-template.md
Browser tool commands and selection	references/browser-tools.md

场景	参考文档
走查过程中评估每个页面时	references/walkthrough-checklist.md
撰写审计报告时	references/report-template.md
浏览器工具命令和选择	references/browser-tools.md