ui-review

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Who you are: If
.helpmetest/SOUL.md
exists in this project, read it before starting — it defines your character and shapes how you work.

No MCP? The CLI has full feature parity — use
helpmetest <command>
instead of MCP tools. See the CLI reference.

你的身份： 如果项目中存在
.helpmetest/SOUL.md
文件，请在开始前阅读它——它定义了你的角色并规范你的工作方式。

没有MCP？ CLI具备完全相同的功能——使用
helpmetest <command>
替代MCP工具。查看CLI参考。

UI Review

UI审核

Systematic visual walkthrough of every page in the app. You navigate, screenshot, analyze what you actually see, then deliver opinionated improvement pitches per page and per viewport.

This is NOT a formal test run. It is a design and UX audit through a real browser.

对应用内每个页面的系统性视觉走查。你可以导航页面、截图、分析实际渲染内容，然后针对每个页面和每个视口给出针对性的改进建议。

这不是正式的测试运行，而是通过真实浏览器完成的设计与UX审计。

When to Use This Skill

何时使用该技能

"Review the UI and pitch improvements"
"Walk through the app and tell me what to fix"
"UX audit"
"How does this look on mobile?"
"Give me UI feedback on all pages"

NOT for:

Creating automated tests (use
```
/test-generator
```
)
Finding functional bugs (use
```
/helpmetest
```
)
Debugging a specific broken test (use
```
/debug-tests
```
)

-「审核UI并给出改进建议」 -「遍历应用走查，告诉我需要修复的问题」 -「UX审计」 -「这个在移动端上看起来怎么样？」 -「给我所有页面的UI反馈」

不适用场景：

创建自动化测试（请使用
```
/test-generator
```
）
查找功能Bug（请使用
```
/helpmetest
```
）
调试某个特定的失败测试（请使用
```
/debug-tests
```
）

Phase 0: Orient Before You Act

阶段0：行动前先熟悉情况

Always do this first. Never skip.

helpmetest_status()
how_to({ type: "authentication_state_management" })

Check:

What auth states are saved? (e.g. "Admin", "Helpmetest")
When was the state last used? Is it stale?

始终优先执行本步骤，不得跳过。

helpmetest_status()
how_to({ type: "authentication_state_management" })

检查：

保存了哪些身份验证状态？（例如「Admin」、「Helpmetest」）
状态上次使用是什么时候？是否已失效？

Stale State Protocol

失效状态处理规则

A saved state goes stale if the session expired or if

Save As

was never run against the live app. Signs of stale state: 302 redirects to login, landing on

/login

after

As <Name>

, empty/broken UI.

If stale → refresh it first:

Find the maintaining test (usually named "Setup Auth <Name>" or similar)

Run it:

helpmetest_run_test({ id: "<test-id>" })

It performs login and calls
```
Save As <Name>
```
— now the state is fresh
Only proceed to the walkthrough after that test passes

如果会话过期，或者从未针对线上应用执行过

Save As

操作，保存的状态就会失效。状态失效的迹象：302重定向到登录页、执行

As <Name>

后跳转到

/login

、UI空白/损坏。

如果状态失效→先刷新状态：

找到对应的维护测试用例（通常命名为「Setup Auth <Name>」或类似名称）

运行：

helpmetest_run_test({ id: "<test-id>" })

它会执行登录并调用
```
Save As <Name>
```
——此时状态就已刷新
只有当测试通过后才能继续走查流程

Domain Lock

域名锁定

Auth cookies are scoped to a domain. Once you authenticate on

app.example.com

, stay on that domain for the entire session. Never navigate to a different domain (e.g. prod vs staging) mid-session — it will destroy the auth state silently.

身份验证Cookie的作用域限定在单个域名下。一旦你在

app.example.com

完成身份验证，整个会话期间都要停留在该域名下。绝对不要在会话中途跳转到其他域名（例如生产环境vs测试环境）——这会悄无声息地销毁身份验证状态。

Phase 1: Discover the Pages

阶段1：梳理所有页面

If you don't already know all pages/tabs in the app:

robot

As  <StateName>
Go To  <base-url>

Look at the screenshot. Identify:

Top-level navigation items (tabs, sidebar links)
Any visible sub-pages or drawers
The URL structure

List all pages you will visit. This becomes your review checklist.

如果你还不知道应用内的所有页面/标签页：

robot

As  <StateName>
Go To  <base-url>

查看截图，识别：

顶层导航项（标签页、侧边栏链接）
所有可见的子页面或抽屉
URL结构

列出所有你要访问的页面，这将作为你的审核 checklist。

Phase 2: Desktop Walkthrough (1440x900)

阶段2：桌面端走查（1440x900）

For each page in your checklist:

robot

As  <StateName>
Set Viewport Size  1440  900
Go To  <page-url>

What to observe per screenshot:

Layout: Is the page using space well? Blank areas? Dense areas?
Hierarchy: Does the most important thing dominate visually?
Navigation: Is it clear where you are? Are active states visible?
Actions: Are the primary actions obvious? Are secondary actions buried?
Data density: Too much? Too little? Is it scannable?
Typography: Readable at a glance? Inconsistent sizing?
Empty states: What happens when there's no data?
Loading states: Are they informative or just spinners?
Bugs visible from looking: Wrong labels, truncated text, misalignment, invisible controls

Scroll if the page is long:

robot

Scroll By  0  800

Interact to see more states:

robot

undefined

针对checklist中的每个页面：

robot

As  <StateName>
Set Viewport Size  1440  900
Go To  <page-url>

每张截图需要观察的点：

布局： 页面空间利用是否合理？有没有空白区域？内容有没有过于拥挤？
层级： 最重要的内容是否在视觉上占主导地位？
导航： 是否清晰展示当前所在位置？激活状态是否可见？
操作： 主要操作是否明显？次要操作有没有被隐藏？
数据密度： 太多还是太少？是否便于快速浏览？
排版： 一眼看上去是否易读？字号有没有不一致的问题？
空状态： 没有数据时的展示效果如何？
加载状态： 是否有有效信息，还是只有加载动画？
视觉可见的Bug：标签错误、文本截断、对齐错位、控件不可见

如果页面较长请滚动：

robot

Scroll By  0  800

交互查看更多状态：

robot

undefined

Open a dropdown, expand a row, hover a button — whatever reveals more UI

打开下拉框、展开行、悬停按钮——任何可以展示更多UI的操作

Click <selector> Hover <selector>

---

Click <selector> Hover <selector>

---

Phase 3: Mobile Walkthrough (375x667)

阶段3：移动端走查（375x667）

Repeat for every page at iPhone SE viewport:

robot

Set Viewport Size  375  667
Go To  <page-url>

Mobile-specific things to check:

Does the layout collapse correctly? No horizontal scroll, no text clipping
Touch targets: Are buttons big enough? (min 44x44px recommended)
Navigation: Is the nav accessible? Hidden behind hamburger? Visible at all?
Tables/grids: Do they reflow? Or do they overflow off-screen?
Text: Does it resize? Is anything too small to read?
Modals/popups: Do they fit the viewport? Can you scroll inside them?
Forms: Are inputs full-width? Keyboard-friendly?

在iPhone SE视口下重复所有页面的走查：

robot

Set Viewport Size  375  667
Go To  <page-url>

移动端专属检查项：

布局是否正确折叠？ 没有横向滚动、没有文本裁剪
触摸目标： 按钮尺寸是否足够？（建议最小44x44px）
导航： 导航是否可访问？是否隐藏在汉堡菜单后？是否完全可见？
表格/网格： 是否会自适应重排？还是会溢出屏幕？
文本： 是否支持缩放？有没有过小难以阅读的内容？
模态框/弹窗： 是否适配视口大小？内部是否支持滚动？
表单： 输入框是否是全宽？是否适配键盘操作？

Phase 4: Tablet Walkthrough (768x1024)

阶段4：平板端走查（768x1024）

Repeat for every page at iPad viewport:

robot

Set Viewport Size  768  1024
Go To  <page-url>

Tablet-specific things to check:

Breakpoint fallback: Does it inherit desktop or mobile layout? Is it the right choice?
Column count: Single-column mobile vs multi-column desktop — what happens in between?
Navigation: Hamburger or full nav? Right call for this width?
Data tables: Readable? Or horizontally scrolling?
Cards/grids: Good column count or oddly sparse?

在iPad视口下重复所有页面的走查：

robot

Set Viewport Size  768  1024
Go To  <page-url>

平板端专属检查项：

断点降级： 继承的是桌面端还是移动端布局？选择是否合理？
列数： 移动端单栏vs桌面端多栏，中间尺寸下的展示效果如何？
导航： 用汉堡菜单还是全量导航？当前宽度下的选择是否合理？
数据表格： 是否易读？还是需要横向滚动？
卡片/网格： 列数是否合理，还是过于稀疏？

Phase 5: Deliver the Pitch

阶段5：输出改进建议

After all screenshots, write a structured UI improvement pitch.

Format per page:

undefined

完成所有截图后，编写结构化的UI改进建议。

每个页面的格式：

undefined

[Page Name]

[页面名称]

What I Saw (Desktop / Tablet / Mobile)

所见内容（桌面端/平板端/移动端）

[2-4 sentences describing actual visual observations. Reference specific elements by name. Mention what's good too — not everything needs fixing.]

[2-4句话描述实际的视觉观察结果，明确提及具体元素名称，同时也要提到做得好的地方——不是所有内容都需要修复。]

Issues Found

发现的问题

[Specific issue]: [What you saw, what it breaks for the user]
[Specific issue]: [What you saw, what it breaks for the user]

[具体问题]：[你看到的现象，对用户造成的影响]
[具体问题]：[你看到的现象，对用户造成的影响]

Improvement Pitches

改进建议

[Change name] — [What to change, why, expected impact]
[Change name] — [What to change, why, expected impact]

[变更名称] —— [要修改的内容、修改原因、预期效果]
[变更名称] —— [要修改的内容、修改原因、预期效果]

Viewport Notes

视口备注

Desktop: [anything desktop-specific]
Tablet: [any breakpoint weirdness]
Mobile: [any mobile-specific issues or wins]


End with a **Priority Stack** — a ranked list of the top 5 changes across all pages that would have the biggest impact:

桌面端：[任何桌面端专属的说明]
平板端：[任何断点异常的问题]
移动端：[任何移动端专属的问题或亮点]


最后附上**优先级排序**——从所有页面的改进点中选出影响最大的前5项，按优先级排序：

Top 5 Improvements (Ranked by Impact)

前5项改进建议（按影响排序）

[Page] — [Change] — [Why it's #1]
...
...
...
...

---

[页面] —— [变更内容] —— [排在第一位的原因]
...
...
...
...

---

Interaction Patterns

交互模式

Use these to reveal more UI states during the walkthrough:

robot

undefined

走查过程中使用以下操作展示更多UI状态：

robot

undefined

Check hover states

检查悬停状态

Hover <selector>

Open dropdowns, menus, modals

打开下拉框、菜单、模态框

Click <selector>

Fill in a search to see filtered states

输入搜索内容查看筛选状态

Fill Text input[type="search"] test

Scroll to bottom to check footer / infinite scroll

滚动到底部检查页脚/无限滚动

Scroll By 0 9999

Check empty state by navigating to a page with no data

导航到无数据页面检查空状态

Go To <empty-page-url>

Check loading state (if possible)

检查加载状态（如果可能）

Navigate to a slow page and screenshot immediately

跳转到加载较慢的页面后立即截图

Go To <url>

---

Go To <url>

---

Guidelines

规范

Ground everything in screenshots. Do not describe what you think the page looks like from reading the code. Navigate, take the screenshot, describe what is actually rendered.

Be specific and opinionated.

Bad: "The layout could be improved"
Good: "The GROUP BY tabs are nearly invisible at 30% opacity — users won't know they can filter by status. Make them solid with a clear active indicator."

Name the element. Always say which button, which column, which tab, which card. "The button" is useless. "The 'Run Test' button in the test card's bottom-right corner" is actionable.

Cover the full picture.

What is good (don't tear down everything)
What is confusing or broken
What is missing that users will want
What is there that users don't need

Separate viewport feedback. Desktop feedback != mobile feedback. A layout can be great on desktop and terrible on mobile. Call both out separately.

Respect existing conventions. If the app has an established design language (colors, spacing, component styles), pitch improvements that fit within it — don't suggest wholesale redesigns unless the system is fundamentally broken.

所有内容都要基于截图。 不要根据代码推测页面的样子，要实际导航、截图、描述实际渲染的内容。

内容要具体、有明确观点。

反面示例：「布局可以优化」
正面示例：「GROUP BY标签的透明度只有30%，几乎不可见——用户不知道可以按状态筛选。请将其改为不透明样式，并添加清晰的激活状态指示器。」

明确元素名称。 始终说明是哪个按钮、哪一列、哪个标签、哪张卡片。「那个按钮」没有任何作用，「测试卡片右下角的『运行测试』按钮」才是可落地的。

覆盖完整情况。

做得好的地方（不要否定所有内容）
令人困惑或损坏的内容
用户需要但缺失的内容
用户不需要但多余的内容

区分不同视口的反馈。 桌面端的反馈≠移动端的反馈，同一个布局在桌面端可能很好，在移动端可能很差，要分开说明。

尊重现有规范。 如果应用已经有成熟的设计语言（颜色、间距、组件样式），给出的改进建议要符合现有规范——除非设计系统本身存在根本性问题，否则不要建议全盘重设计。

Example Session Skeleton

会话流程示例框架

robot

undefined

robot

undefined

Phase 0: Orient

阶段0：熟悉情况

→ checked auth states, found "Helpmetest" state, ran Setup Auth test to refresh it

→ 检查了身份验证状态，找到「Helpmetest」状态，运行Setup Auth测试刷新状态

Phase 1: Discover pages

阶段1：梳理页面

As Helpmetest Set Viewport Size 1440 900 Go To https://app.example.com

→ screenshot shows: Dashboard, Tests, Updates, Artifacts, Settings tabs

→ 截图显示：Dashboard、Tests、Updates、Artifacts、Settings标签页

Phase 2: Desktop

阶段2：桌面端

Go To https://app.example.com/dashboard

screenshot + notes

截图 + 备注

Go To https://app.example.com/tests

screenshot + notes

截图 + 备注

Go To https://app.example.com/updates

screenshot + notes

截图 + 备注

Go To https://app.example.com/artifacts

screenshot + notes

截图 + 备注

Go To https://app.example.com/settings

screenshot + notes

截图 + 备注

Phase 3: Mobile

阶段3：移动端

Set Viewport Size 375 667 Go To https://app.example.com/dashboard

screenshot + notes

截图 + 备注

... repeat for all pages ...

... 重复所有页面的走查 ...

Phase 4: Tablet

阶段4：平板端

Set Viewport Size 768 1024 Go To https://app.example.com/dashboard

screenshot + notes

截图 + 备注

... repeat for all pages ...

... 重复所有页面的走查 ...

Phase 5: Write the pitch

阶段5：编写改进建议

---

---