flows-design-review

Flows 设计评审

这是 Flows 应用认证流程的第 3 步：

flows-app-brief  →  build  →  flows-code-review  →  flows-design-review (this skill)  →  flows-external-app-submit

这是 docs.cognite.com/cdf/flows/guides/quality-guidelines 中介绍的人工设计质量评估。 目标总体平均分：3.8 分或更高，才能达到发布条件。

操作规则

• 先自动化，再提问。 对于每个问题 Q1–Q10，先运行下方列出的探测步骤，从代码仓库收集确凿证据，并在询问用户之前提出建议分数（1–5 分）及评分依据。用户的工作是确认或修改建议分数，而不是从零开始评分。这样可以大幅减轻人工负担。
• **任务操作演练（第 2 步）**是唯一不能跳过的环节——自动化无法判断用户在浏览屏幕时是否会“迷路”。请手动记录演练过程；如果实际使用体验与自动推导的评分不符，请据此修改评分。
• 每个评分都使用 AskQuestion，以确保答案具有结构化形式。每个问题提供三个选项：(a) 接受建议分数、(b) 修改为指定分数、(c) 修改分数并补充说明。
• 如果存在 App-Brief.md frontmatter，请从中预填用户、任务和角色背景。

步骤 0 — 提问前预扫描

在询问用户任何内容之前，务必先进行预扫描。 静默读取以下来源，并将发现作为证据呈现出来——绝不能作为评分，也不能自动保存：

来源	用途
App-Brief.md frontmatter	预填主要用户（userRole）、任务（oneSentenceStory）和成功标准
package.json	确认是否安装了 @cognite/aura，并显示其版本（为 Q1 提供依据）
最新的 reviews/code-review/feedback-round-<N>/code-review-report.md	提取与设计相关的发现（无障碍、错误处理、UX 文案），并作为 Q4/Q10 的证据呈现
src/**/*.{ts,tsx,css}	Q1 探测——查找硬编码的十六进制/RGB 颜色，以及 Aura 设计令牌之外直接使用的 px/rem 值
src/**/*.{ts,tsx}	Q5 探测——查找缺少 role/tabIndex 的非按钮元素上的 onClick
src/**/*.{ts,tsx}	Q10 探测——查找缺少 aria-label 的图标按钮、缺少 alt 的 <img> 以及缺失的焦点样式

在首次评分之前，先在开场消息中向用户展示预扫描结果。这些结果只是起点，并非定论。人工任务操作演练（第 2 步）和用户给出的分数仍具有决定性。

步骤 0b — 选择反馈轮次

查看 reviews/design-review/。如果该目录不存在，则为第 1 轮。否则，递增到下一个尚不存在的 feedback-round-<N>/ 目录。

步骤 1 — 确认用户和任务

根据文档，“质量评估的实用性取决于其所依据的用户和任务是否清晰。”

如果存在 App-Brief.md，请从其 frontmatter 中解析 userRole、oneSentenceStory 和 successCriteria，并将其作为主要用户和任务的建议内容。请用户确认或补充。

通过 AskQuestion 记录：

• 主要用户 — 具体角色和背景（例如：“海上平台上的维护工程师”）。
• 2–3 项关键任务 — 该用户需要完成的工作流（例如：“检查泵的振动警报”、“安排维护工作”）。
• 背景 — 经验水平、时间限制、设备、成功标准。

步骤 2 — 端到端完成每项任务（手动）

请用户：

1. 在干净的浏览器会话中，使用有代表性的测试数据，以该用户的身份打开应用。
2. 不走捷径，从头到尾完成每项任务。
3. 记录痛点：在哪些地方遇到阻碍、感到困惑或犯错。

对于每项任务，请用户粘贴以下内容：发生了什么、在哪里遇到阻碍，以及任何截图或备注。将这些内容记录为报告中的 taskWalkthroughs[]。

在用户确认已完成每项任务的操作演练之前，不要继续评分。如果用户拒绝，请编写一份简要报告，记录“已跳过任务操作演练”，然后退出——不要评分。

第 3 步 — 为 10 个问题打分（探查 → 提议 → 确认）

对于每个问题 Q1–Q10，请遵循相同的流程：

1. 运行列出的探查。 这些具体的 shell／grep／lint／build 命令会从代码仓库中生成确凿证据。
2. 根据探查结果和评分标准，提出一个初步分数（1–5）。 展示评分依据：哪些探查结果对应哪个分数。
3. 与用户在第 2 步的任务走查笔记进行交叉核对（尤其关注导航、可点击性和错误预防）。
4. 通过 AskQuestion 向用户提问，并提供三个选项：(a) 接受建议分数 N、(b) 改为指定分数、(c) 改为指定分数并添加备注。
5. 记录最终分数、一句话理由和一条改进建议。

将探查结果转化为初步分数的启发式规则

以下阈值仅供参考 — 请根据具体证据和评分标准的表述进行调整。最终决定权始终在用户手中。

信号	倾向分数
无反模式匹配，且相关规则的 lint 检查通过	5
≤ 3 处轻微匹配，且大多集中在一个文件中	4
多个文件中有 5–15 处匹配，或存在 1 个系统性问题	3
有 15 处以上匹配，或反模式普遍存在	2
反模式是默认风格	1

每个问题的自动化探查

每个问题的探查列表都是 Agent 在询问用户关于该问题的任何内容之前应首先运行的内容。务必说明运行了哪些探查及其返回结果。

10 个问题和评分标准

Q1 — Aura 设计系统一致性。 是否正确使用了 Aura 设计令牌、布局、组件和模式？

探查（可自动化）：

• grep -c '@cognite/aura' package.json — 确认 Aura 是依赖项
• grep -rlE "from '@cognite/aura'" --include='*.ts' --include='*.tsx' src | wc -l — 统计导入 Aura 的文件数
• grep -rlE '#[0-9a-fA-F]{3,8}' --include='*.css' --include='*.tsx' --include='*.ts' src — 查找包含硬编码十六进制颜色的文件
• grep -rlE '\b(rgb|rgba|hsl|hsla)\(' --include='*.tsx' --include='*.css' src — 查找包含原始 rgb/hsl 值的文件
• npx eslint . --ext .ts,.tsx --rule '{"aura/no-overriding-styles":"error"}' --no-eslintrc --quiet 2>&1 | tail -5，或查看现有 lint 输出中 aura/no-overriding-styles 的警告数量

转换为初步分数： 无硬编码颜色且无 aura/no-overriding-styles 警告 → 5。少量警告（1–5 条）→ 4。警告很多（>15 条）或没有 Aura 导入 → 2–3。

• 5 优秀： 正确应用所有 Aura 设计令牌，不使用硬编码值。具备适当的响应式尺寸和页面布局。使用 Aura 组件且不覆盖样式。遵循最佳实践。
• 4 良好： 大多使用 Aura 设计令牌和组件，仅有 1–2 处轻微例外。布局间距基本一致。几乎没有样式覆盖。
• 3 一般： 混用 Aura 和自定义元素。部分间距设置合理，部分使用随意的数值。在多处覆盖样式。
• 2 低于平均水平： 经常使用自定义颜色、字体或间距，而非 Aura 设计令牌。大量自定义修改破坏了既有模式。
• 1 较差： 完全未使用 Aura。到处都是自定义颜色、字体和间距。

Q2 — 导航、布局和层级结构。 用户能否清楚地知道自己当前所在的位置并轻松导航？

探查（部分可自动化 — 依赖第 2 步的走查）：

• grep -rcE '<Route\b' --include='*.tsx' src — 统计路由数量（了解导航范围）
• grep -rlE 'Breadcrumb' --include='*.tsx' src — 查找使用面包屑组件的文件（位置提示）
• grep -rlE 'NavLink|Link to=|useLocation' --include='*.tsx' src — 查找正在使用的导航原语
• grep -rlE '<Topbar|<Sidebar|<Header' --include='*.tsx' src — 查找顶层界面元素
• 查看路由树（src/routes/）并询问：每个非简单页面是否都显示自身标题并提供返回方式？

转换为初步分数： 默认以走查结论为准，因为静态分析难以衡量导航体验。利用探查标记风险（例如，没有面包屑的路由）。

• **5：**当前位置始终清晰。前进和后退导航简单易用。菜单保持一致。视觉层级分明。内容按逻辑流动（F/Z 模式）。
• **4：**通常清晰。导航大多一致，只有少数例外。
• **3：**有时不清晰。导航可用，但不总是直观。存在层级结构，但有时不够清晰。
• **2：**经常迷失或困惑。页面间的导航方式不一致。层级结构较弱。
• **1：**无法判断当前位置。没有清晰的导航。结构不一致。

Q3 — 标签和语言清晰易懂。 按钮、输入框和操作是否有清晰的标签？

探查项（可自动化）：

• grep -rcE ">(Submit|OK|Click here|Go|Yes|No)<" --include='*.tsx' src — 统计含糊的按钮标签
• grep -rcE '<Button[^>]*>[[:space:]]*</Button>' --include='*.tsx' src — 空按钮（仅含图标且无标签时需要 aria-label，在 Q10 中处理）
• grep -rlE '<Label\b' --include='*.tsx' src 和 grep -rlE '<input\b' --include='*.tsx' src — 输入元素与标签；两者不匹配可能表明输入框未标注
• grep -rcE 'placeholder=' --include='*.tsx' src — 用占位符代替标签是一种反模式；若数量较多但对应的 <Label> 不足，则值得注意

转换为初步评分： 没有含糊的标签，且每个输入框都有对应标签 → 5。只有少数输入框仅使用占位符 → 4。多处存在含糊的标签 → 3。

• 5： 每个元素都有清晰、具体的标签。语言简洁，以操作为导向（“保存更改”“删除项目”）。
• 4： 大多数标签清晰。只有少许含糊之处。
• 3： 有标签，但有时含糊（“提交”“确定”）。存在一些不必要的术语。
• 2： 许多标签不清晰。大量使用未经解释的技术术语。
• 1： 标签缺失、令人困惑或充斥术语。

Q4 — 系统反馈和验证。 用户是否知道当前发生了什么？表单是否易于使用？

探查项（可自动化）：

• grep -rlE 'isLoading|isPending|<Skeleton|<Loader|<Spinner' --include='*.tsx' src — 包含加载提示的文件
• grep -rlE 'isError|onError|<Alert|toast\.' --include='*.tsx' src — 包含错误或成功提示的文件
• grep -rlE 'useMutation' --include='*.tsx' src — 修改操作的位置；交叉检查每处是否都有 onSuccess/onError 处理程序
• grep -rlE 'ErrorBoundary' --include='*.tsx' src — 错误边界（代码审查时也会交叉检查）
• 对每个路由/功能文件夹，(包含加载和错误处理的文件数) ÷ (获取数据的文件数) 的比值应约为 1

转换为初步评分： 每个数据获取/修改操作都有加载和错误状态 → 5。少数修改操作没有明确的错误处理 → 4。覆盖情况不一 → 3。

• 5： 立即提供反馈。加载状态清晰。成功/错误消息有帮助。所有字段都有标签，必填字段有标记，并提供带有具体消息的实时验证。
• 4： 大多数操作都会提供反馈。存在加载状态。验证大多有帮助。
• 3： 提供了一些反馈，但不一致。有时缺少加载状态。错误消息较笼统。
• 2： 反馈很少。用户经常不知道操作是否成功。仅在提交时进行验证。
• 1： 没有反馈。失败时不作提示。只显示技术错误代码。

Q5 — 可点击性和交互。 哪些内容可以点击，是否一目了然？

探查项（可自动化）：

• grep -rcE '<div[^>]*onClick' --include='*.tsx' src — <div> 上的 onClick（缺乏语义化，且通常不支持键盘操作）
• grep -rcE '<span[^>]*onClick' --include='*.tsx' src — 同上，检查 <span>
• grep -rcE 'role="button"' --include='*.tsx' src — 显式设置的角色（无法避免使用 <div onClick> 时，这样做是好的）
• grep -rcE 'hover:|focus:' --include='*.tsx' src — Tailwind 悬停/聚焦工具类的使用情况（数量多通常是好事）
• grep -rcE 'cursor-pointer' --include='*.tsx' src — 显式设置指针光标

转换为初步评分： 没有未设置角色的 <div onClick>，且使用了许多悬停/聚焦工具类 → 5。存在 1–3 处违规 → 4。许多非按钮元素上使用了 onClick → 2–3。

• **5：**所有可点击项都清晰地呈现为可点击。交互元素有悬停效果。光标会相应变化。
• **4：**大多数交互元素都很明显。大多数元素都有悬停效果。
• **3：**悬停状态不一致。有时不清楚哪些元素可以交互。
• **2：**许多交互元素看起来无法点击。很少有悬停效果。
• **1：**无法判断哪些元素可以点击。没有视觉反馈。

Q6 — 错误预防与恢复。 用户能否撤销或取消破坏性操作？

探查项（部分可自动化）：

• grep -rilE 'delete|remove|archive|reset' --include='*.tsx' src | head -20 — 包含潜在破坏性操作的文件
• grep -rlE 'AlertDialog|ConfirmDialog|window\.confirm' --include='*.tsx' src — 确认对话框的使用情况
• grep -rcE 'variant="destructive"|destructive' --include='*.tsx' src — 破坏性按钮的样式
• 对于每个包含破坏性动词的文件，检查同一文件或其导入项中是否有相应的 AlertDialog/ConfirmDialog 调用

**不适用情况指南：**只读查看器应用（Flows 演示的常见情况）没有破坏性操作，默认应得 5 分，并说明“没有破坏性操作”。不要因为应用没有它不需要的确认机制而扣分。

• **5：**破坏性操作前会显示确认对话框。自动保存可防止数据丢失。提供清晰的撤销或取消选项。或者应用没有破坏性操作。
• **4：**大多数破坏性操作都有警告。提供部分自动保存或撤销功能。
• **3：**主要操作有一些警告。撤销或取消功能有限。
• **2：**警告很少。无法撤销。工作容易丢失。
• **1：**没有警告。无法撤销。经常意外丢失数据。

Q7 — 响应式设计与多设备支持。 在不同屏幕尺寸下都能正常使用吗？

探查项（可自动化）：

• grep -rcE '\b(sm|md|lg|xl|2xl):' --include='*.tsx' src — Tailwind 响应式工具类的使用情况（数量越多越好）
• grep -E '<meta name="viewport"' index.html — 是否存在 viewport 元标签
• grep -rcE 'overflow-x-auto|overflow-x-scroll' --include='*.tsx' src — 水平滚动容器（通常是隐患）
• grep -rcE '\bw-\[[0-9]+px\]|\bh-\[[0-9]+px\]' --include='*.tsx' src — 固定像素尺寸（通常会导致小屏幕显示异常）
• 查看 App-Brief.md 中的 userRole — 如果写着“在控制室使用台式机或笔记本电脑”，应用可能是有意设计为仅支持桌面端；这是可接受的，评分标准规定“如果并非面向移动端设计，则可在移动端隐藏或限制功能”

**初步评分换算：**如果根据 App-Brief，应用在设计上仅面向桌面端，并且在 13 英寸及更大尺寸的笔记本电脑上显示正常 → 5 分。响应式工具类使用情况参差不齐 → 4 分。大量使用固定像素尺寸 → 3 分。

• **5：**在桌面、平板和移动设备上都能流畅使用。触控目标至少为 40px。文本易于阅读。没有水平滚动。已考虑触屏设备上的悬停状态。或者根据需求说明有意仅支持桌面端，并且在受支持的屏幕尺寸下显示正常。
• **4：**在大多数设备上运行良好。有轻微问题。
• **3：**在多种设备上可用，但未优化。小屏幕上有一些布局问题。
• **2：**移动端或平板体验较差。布局会错乱。
• **1：**仅支持桌面端。在移动端或平板上无法正常使用。

Q8 — 空状态与首次使用体验。 没有数据时，用户是否清楚接下来该做什么？

探查项（可自动化）：

• grep -rilE 'empty|no\s+(data|results|items|files|matches)' --include='*.tsx' src — 包含空状态文案的文件
• grep -rlE '<EmptyState|EmptyPlaceholder' --include='*.tsx' src — 明确的空状态组件
• 对每个面板/列表模块（任何包含 .list( 或 .items.map( 的模块），检查是否至少有一个分支处理 items.length === 0，并提供用户可见的文案。列出有和没有此类处理的面板。
• grep -rcE 'items\.length === 0|items\.length > 0' --include='*.tsx' src — 明确的空状态检查

**初步评分换算：**每个获取数据的面板都有包含文案的空状态分支 → 5 分。缺少一两个 → 4 分。许多面板缺少 → 2–3 分。

• 5： 所有空状态都显示有帮助的信息和明确的后续步骤。新用户清楚地知道该怎么做。
• 4： 大多数空状态都有帮助。存在少量不足。
• 3： 对部分空状态提供了解释。新用户能够自行弄明白。
• 2： 很多页面空白，且没有任何指引。
• 1： 到处都是空白页面，没有任何指引。

Q9 — 性能与效率。 应用加载速度快吗？

探查项（可自动化）：

首先，检查是否已有近期构建产物——如果 dist/ 是最新的，就能避免缓慢的重新构建：

find dist -maxdepth 1 -newer package.json -name '*.js' 2>/dev/null | wc -l
du -sh dist/ 2>/dev/null

如果计数为 0（没有近期构建产物），则使用以下备用方案：

npm run build 2>&1 | tail -20

然后收集其余指标：

• grep -rcE 'React\.lazy|lazy\(' --include='*.tsx' src — 路由代码拆分（表现良好）
• grep -rcE 'useMemo|useCallback' --include='*.tsx' src — 记忆化用法（反映渲染效率）
• grep -rlE 'useVirtual|react-window|react-virtual' --include='*.tsx' src — 列表虚拟化（适用于大型列表）
• grep -rlE '\.list\([^)]*\)' --include='*.ts' --include='*.tsx' src | xargs -I{} grep -l 'limit:' {} 2>/dev/null | wc -l 与列表调用点总数对比 — 分页覆盖率
• 对照最新的 code-review-report.md 中标准 2.3（限制与分页）的得分

转换为初步评分： 构建产物小于 1 MB（gzip 压缩后）+ 每个列表都有数量限制 + 使用了 react-query → 5。构建产物为 1–2 MB，或部分列表缺少数量限制 → 4。构建产物大于 2 MB，或普遍存在无界数据获取 → 2–3。

• 5： 加载迅速，内容渐进显示。支持批量操作和键盘快捷键。完成常见任务所需的点击次数极少。
• 4： 加载速度合理。大多数任务流程顺畅。
• 3： 性能尚可。完成任务需要适度投入。快捷方式较少。
• 2： 加载缓慢。完成任务需要很多步骤。
• 1： 非常缓慢或没有响应。

Q10 — 无障碍（WCAG AA 2.1）。 人们能使用辅助技术操作它吗？

探查项（可自动化）：

• 分别统计 <img> 标签和带有 alt 属性的 <img> 标签数量，以找出缺少替代文本的情况：

  grep -rcE '<img\b' --include='*.tsx' src
  grep -rcE '<img[^>]*\balt=' --include='*.tsx' src
  

  两者数量有差异就表示有图片缺少 alt。
• grep -rcE '<button[^>]*>[[:space:]]*<(svg|Icon)' --include='*.tsx' src — 仅含图标的按钮（需要 aria-label）
• grep -rcE 'aria-label=' --include='*.tsx' src — ARIA 标签的使用情况
• grep -rcE 'focus-visible:|focus:' --include='*.tsx' src — 焦点样式
• grep -rcE 'tabIndex=\{-1\}|tabIndex="?-1' --include='*.tsx' src — 从 Tab 键顺序中移除的元素（有时是有意为之，有时则是错误）
• 如果已安装 eslint-plugin-jsx-a11y：npx eslint . --ext .ts,.tsx --no-eslintrc --rule '{"jsx-a11y/alt-text":"error","jsx-a11y/anchor-is-valid":"error","jsx-a11y/click-events-have-key-events":"error"}' 2>&1 | tail -10
• 如果可用 axe-core：建议用户在运行中的应用里执行 axe 扫描并粘贴结果——自动化可以标记潜在问题，但无法强制检查对比度

转换为初步评分： 缺少替代文本的图片为 0 + 缺少 aria-label 的仅含图标按钮为 0 + 各处均有焦点样式 → 5。存在少量违规 → 4。普遍存在不足 → 2–3。

• 5： 所有交互都可通过键盘完成。文本对比度符合 WCAG AA。焦点指示清晰。ARIA 标签设置正确。图片均有替代文本。触控目标至少 40px / 鼠标目标至少 20px。表单错误会通过屏幕阅读器播报。
• 4： 满足大多数要求。存在少量例外。
• 3： 提供基本的键盘支持，但部分功能不支持。对比度基本可接受。具备焦点指示，但有时不够清晰。
• 2： 键盘支持有限。存在多处对比度不达标。焦点指示较弱。
• 1： 不支持键盘导航。对比度差。没有焦点指示。无法使用辅助技术操作。

第 4 步 — 计算平均分和质量等级

平均分 = 10 项评分之和 ÷ 10。

根据文档中的质量等级表确定等级：

平均分	质量等级	建议
4.5 – 5.0	优秀 — 可以发布	后续逐步改进
3.8 – 4.4	良好 — 修复少量问题后即可发布	解决得分较低的部分
3.0 – 3.7	一般 — 需要改进	发布前修复主要问题
低于 3.0	需要大量工作	需要进行大幅改进

flows-external-app-submit 的门槛是 平均分 ≥ 3.8。

第 5 步 — 编写报告

创建 reviews/design-review/feedback-round-<N>/design-review-report.md，并采用以下结构：

# Design Review — <appName> — round <N>

## User and tasks

- **Primary user:** ...
- **Tasks evaluated:**
  1. ...
  2. ...
  3. ...
- **Context:** ...

## Task walkthrough findings

- **Task 1 — ...** ...
- **Task 2 — ...** ...
- **Task 3 — ...** ...

## Scores

| Question | Score | Rationale | Improvement note |
| --- | --- | --- | --- |
| Q1 Aura consistency | n | ... | ... |
| Q2 Navigation & hierarchy | n | ... | ... |
| Q3 Labels & language | n | ... | ... |
| Q4 Feedback & validation | n | ... | ... |
| Q5 Clickability | n | ... | ... |
| Q6 Error prevention | n | ... | ... |
| Q7 Responsive | n | ... | ... |
| Q8 Empty states | n | ... | ... |
| Q9 Performance | n | ... | ... |
| Q10 Accessibility | n | ... | ... |

## Summary

- Average score: <X.X>
- Quality level: <Excellent | Good | Average | Needs significant work>

## Must Fix (any score < 3)

- ...

## Should Fix (any score 3 – 3.7)

- ...

## Nice to Fix (any score 3.8 – 4.4)

- ...

Average score: 行必须严格采用此格式，以便机器读取 — flows-external-app-submit 会解析该行。

第 6 步 — 输出门槛状态

写入后，在终端输出：

• 平均分
• 质量等级
• 结果是否达到 flows-external-app-submit 的门槛（≥ 3.8）
• 如果低于 3.8，提示用户修复 Must Fix 和 Should Fix 项，并在新一轮反馈中重新运行此技能。