qc-uiux

技能：qc-uiux

内容

目的与背景

• 目的： 对现有 route/屏幕给出 SENIOR 级 UI/UX 评估——四个方面（无障碍 · 视觉层级 · 一致性 · 反模式），每项包含评分（满分 10 分）、最严重的问题和修复方法；可测量的部分由确定性引擎完成，需人工观察的部分由 LLM 审核。
• 触发条件（何时使用）：
  • 刚搭建或改动 UI（mockup /br、新页面、组件）后，希望由资深人员审视，再最终定稿。
  • 在提交重大 UI 改动前——可选择接入 /orca-workflow，放在 verify-before-commit 之前；并在每次 /br run 生成包含 UI 的 frame 后自动运行。
  • 用户说“qc uiux”“audit ui”“检查界面”“清理 ui 反模式”或“/qc-uiux”。
• 非目标： 不用于整体美学改版（使用 /redesign-existing-projects），也不用于仅截图并比较像素（使用 /visual-qa——qc-uiux 会调用它作为测量引擎）。不审查 CODE（使用 /qc-code）。评估结果不会阻止提交。

心智模型

route/屏幕 → 确定性引擎（DESIGN_AUDIT 测量真实 rect）= 数据 → 4 个方面 ×（评分/10 · 最严重的问题 · 修复方法）= 有数据支撑的意见 → 评估结果 PASS | 需要修复（依据最弱的方面/route）→ 修复 → 再运行引擎（红→绿）。成本高的部分（LLM，手动调用）与成本低的部分（引擎，自动 hook）分开。

输入和输出约定

	字段	是否必需？	含义
输入	route/屏幕	否（默认为现有 mockup/route）	用户指定时，检查指定对象
输入	可运行的 <base-url>	测量部分必需	无头引擎需要服务器；无法启动 → fail-open
输入	route 类型（list/table？）	自动判定	若符合，则加载 references/list-control-checklist.md
输出	4 个方面 × 评分/10 · 最严重的问题 · 修复方法	是	第 3 项附带 drift 表；可测量的问题须引用引擎数据
输出	评估结果	是	PASS 或 需要修复 + 必须修复的问题列表 — 仅供参考
输出	草稿 llmwiki/wiki/sources/draft/DDMMYY-qc-uiux-<route>.md + 索引 + 日志	是（仅运行引擎时除外）	参见“输出报告”一节

规则与能力

• RULE-01 (MUST)：区分高成本和低成本操作： LLM 审核（4 个方面）= 手动调用 / 可选工作流步骤。确定性测量 = 通过 visual-qa 引擎自动运行。hook 中绝不调用 LLM（hook-0-token 原则）。
• RULE-02 (MUST)：评估结果仅供参考，引擎测量结果必须通过——不得让 LLM 评估结果阻止提交；测量数据（contrast/tap-target/geometry）才是依据。
• RULE-03 (MUST)：只读 CSS 会导致几何盲区——所有关于布局/尺寸/contrast 的判断都必须通过引擎测量真实 rect，不能根据静态 CSS 推断。
• RULE-04 (MUST)：避免职责重叠： /redesign-existing-projects = 美学改版 · /visual-qa = 截图并检查像素差异 · /qc-code = 审查 CODE。/qc-uiux = 针对 UI/UX 四个方面给出资深评估 + 复用测量引擎。
• RULE-05 (MUST)：功能优先于美观，不对分数求平均（借鉴 browser-use 的 qa 技能，09/2026）： 如果检查的 route/流程包含用户任务（提交、结账、登录），但任务无法完成 → 无论 4 个方面的分数多高，评估结果都必须是 需要修复——页面再漂亮也救不了中断的流程。 总体评估结果依据最弱的方面/route，不取算术平均值。
• RULE-06 (MUST)：截图干净不代表没有问题——无头运行引擎时，还要查找隐藏问题：console error、pageerror、response >= 400、requestfailed（参见 /playwright-verify 规则）。 页面看起来很漂亮，但每次点击都会报错 → 记入第 4 项，不得给出 PASS。
• RULE-07 (MUST)：a11y 是规则，不是偏好——CLAUDE.md 例外条款：不得在 contrast/tap-target/label 上偷懒。WCAG 仅约 30% 可自动检查 → 其余部分明确标注“需要人工检查 / 欠账 [[150726-unknown-ledger]]”。
• 能力：在无头浏览器中运行页面，以测量 DOM/rect/contrast（0-token）；读取 CSS/DOM；编写 wiki 草稿。审核期间不修改 UI。

失败边界

• 无法启动服务器/headless → 引擎 fail-open（不拦截）；LLM 审计仍会运行，但必须将未测量的部分记录为缺少数据。
• 用户任务无法在路由上完成 → 无论 4 项得分如何，结论均为 CẦN SỬA。
• Console error/pageerror/response >= 400/requestfailed → 记录在第 4 项中，不得判定为 PASS。
• 无法自动化的 WCAG 标准 → 明确记录“需要人工检查 / 欠账 [[150726-unknown-ledger]]”，不得自行判定为 PASS。

HOW

主要工作流

Step	Type	Inputs	Action	Outputs/exit	Failure/next
W00	judgment	route	Route 是 list/table 吗？→ 加载 references/list-control-checklist.md	补充检查清单	否 → 跳过
W01	deterministic	route, <base-url>	确定范围 + 先运行引擎 route-shots.mjs --audit	按 route 列出问题	无法启动 → fail-open，记录备注
W02	judgment	issues + DOM	评定四项：分数/10 · 最严重的问题 · 修复方法	4 项均包含三部分	—
W03	deterministic	issues engine	将引擎数据附到存在可测量问题的项目中	标注来源的测量数据	—
W04	judgment	4 项	得出结论 PASS / CẦN SỬA（按项目/route 中最弱项判断）	结论 + 必须修复项	—
W05	deterministic	UI 已修复	重新运行引擎，证明所有可测量问题已解决（红→绿）	引擎通过	仍有红项 → 仍为 CẦN SỬA
W06	effect	结果	编写 Output Report 草稿 + index + log	草稿	只运行引擎 → 跳过

各步骤详情（W00–W06 的事实来源）：

审计范围（默认 = 现有 mockup/route）

默认检查现有 UI——刚搭建的 mockup route/页面。用户指定 route/屏幕时，就检查指定内容。通过引擎读取 DOM + 测量实际 rect（getBoundingClientRect）；不得根据静态 CSS 猜测（读取 CSS 会误判渲染结果——15/07/26 的经验教训）。

步骤

0. Route 是 list/table 吗？（queue、admin grid、ticket/request list、dashboard summary strip）→ 额外加载 references/list-control-checklist.md——list/table 专有的 11 个常见问题（row 上的配色系统叠加、sort bucket、overflow-clip popover、mobile filter collapse 等），每个问题都已标注对应的下方四项之一。
1. 确定范围——检查哪个 route/屏幕。先运行确定性引擎，获取可测量的数据（见下方“引擎”部分）。
2. 评定四项（见下方）。每项包括：分数/10 · 最严重的问题 · 修复方法。→ 四项均包含这三部分后完成。
3. 为存在可测量问题的项目附上引擎数据（contrast 在哪里失败、哪个 control <24px、哪些元素重叠等）——测量结果是数据，结论是意见。
4. 得出结论——PASS（进入下一步）或 CẦN SỬA（列出必须修复的内容）。→ 结论明确，且 CẦN SỬA 时列出必须修复项后完成。
5. 修复后重新运行引擎，证明所有可测量问题均已解决（红→绿），类似 qc-code 的复现测试。

四项

1. 无障碍（a11y）——分数/10 · 最严重的问题 · 修复方法

检查（大部分可测量——引擎会捕获）：contrast（普通文字 ≥4.5:1，大号文字 ≥3:1，control/边框/icon ≥3:1——WCAG 2.2 AA）· tap-target（交互式 control ≥24×24px CSS，是 AA 2.5.8 的底线；移动端建议 44/48px）· focus-visible（有清晰的焦点环，对比度 ≥3:1）· missing-label（屏幕阅读器读到的按钮/icon/link 为空——缺少 aria-label/text）。这就是无障碍的底线——不能偷懒（a11y 是法律要求，不是个人偏好）。注意：WCAG 标准中只有约 30% 可自动化检查 → 其余部分（keyboard trap、焦点顺序、有意义的 alt）需要人工检查。

2. 视觉层级 — 得分/10 · 最严重的问题 · 修复方法

可测量规则（引擎 fdk/tools/html-visual-gate.mjs，PLAN 220926 — 用户 22/09/2026），在 LLM 评估此项之前运行：

• heading-scale（FAIL）：已出现的标题级别必须由大到小（h1 > h2 > h3 > h4），且不能小于正文文字。
• title-scale（FAIL）：页面名称（品牌/徽标/h1）≥ 导航菜单和内容选择标签中最大字号的 1.2 倍。
• sentence-case（FAIL）：标题、标签、按钮、标签页、导航菜单项首字母大写（豁免含数字/-_./:@ 的标识符、专有名称、代码中的文字；通过 data-case="keep" 保留有意使用的小写）。
• eye-rest（WARN）：必须留出视觉休息空间——首屏中，文字/区块占比 ≤ 55%，且不能出现超过 520px 的连续密集区域而缺少 ≥ 24px 的留白；这是框架的启发式阈值。在一个屏幕中塞入太多并列元素（6 个状态徽章 + 3 个标签 + 3 个按钮放在一行）即使每个元素本身正确，也属于错误——应进行合并，并让详细内容在点击后显示（NN/g 渐进式披露）。
• kanban-uniform（FAIL）：看板（≥ 2 个 lane|kanban|[data-kanban-lane] 列）——所有卡片宽度和高度相同（±2px），样式也相同（背景 · 边框 · 圆角 · 内边距 · 字体）；卡片尺寸固定，点击后才查看详情。
• 按钮协调性（独立引擎 fdk/tools/button-harmony.mjs，用户 24/09/2026 — 在 1440 和 390 两种尺寸下运行，只有 rc 0 才能评为 PASS）：lone-action（FAIL）按钮单独占一行，且不是区块的收尾行，并且偏离行宽中心 > 50%——辅助按钮必须与其服务的标题/字段处于同一行；edge-gap（FAIL）右对齐的行中，最末元素距边缘 > 8px；empty-occupant（FAIL）水平行中有 > 48px 的不可见空单元格占位（豁免 flex:1 间距元素）；mixed-edge（WARN）同一区块中各按钮行的结束边缘对齐方式不一致。action-left 规则（优先放在右下角）仍然有效——协调性是额外条件，并非替代规则。需要登录的页面：将渲染后的 DOM 截图保存到文件，移除应用脚本，然后对该文件运行。
• **对照标准：**每个正在审核的 UI 部分都应在示例页面 skills/hallmark/references/design-showcase.html（机器端：~/.claude/skills/hallmark/references/design-showcase.html）中有同类区块。使用 python3 fdk/tools/build-design-showcase.py --get <id>（机器端：python3 ~/.claude/harness/fdk/tools/build-design-showcase.py --get <id>；--list 会输出索引）提取区块，然后逐项比较（尺寸、状态、颜色 token、动效）；若存在差异且页面未声明豁免，即为错误，须在“修复方法”中注明标准区块的 id。
• 特殊要求必须由页面自行声明：<meta name="overstack-exempt" content="heading-scale,…" data-reason="…"> — 审核时必须查看原因，不得自行豁免。 检查（LLM 视觉判断）：按钮看起来像按钮，链接看起来像链接，标题层级的字号差异清晰（如果用户必须“解读”界面 = fail）· CTA 清晰（主要操作突出明确，不含糊）· 内容密度（不要在一个屏幕中塞入太多内容——内容过载 = 层级混乱）。指出视线最先停留的位置，以及那里是否确实是主要操作。

3. 一致性（设计系统）— 得分/10 · 最严重的问题 · 漂移表

检查（LLM 视觉判断，部分可测量）：间距遵循 token（4/8px 刻度——间距混乱 = 节奏失衡）· 颜色一致（没有冲突/混杂的调色板）· 阴影（不滥用/深度不当——引擎会检测 shadow-clipped/monochrome-surface）· 排版（字体组合/字号保持一致）· 跨页面统一（同类元素在每个屏幕中的呈现方式一致）。返回漂移表：

位置	偏离标准之处	修正为
card padding	14px / 20px / 17px 混用	token --sp-4（16px）

4. 反模式与交互 — 得分/10 · 最严重的问题 · 可测量证据

检查：深色模式可读性（文字褪色般过浅/过暗——典型的深色模式问题，引擎会通过深色主题下的 contrast-aa 检测）· 几何布局错乱（重叠 ≥4px、row-misalign——控件相互重叠/高度不一致，引擎会测量 rect）· 反馈缺失（操作没有系统反馈）· 响应式布局错乱（窄屏下出现横向溢出、元素重叠）· 暗黑模式（强迫用户、诱导选择、难以退出）。每个可测量问题 → 引用引擎给出的数字（哪个 route、哪个元素对、重叠多少 px）。

结论（verdict）

二选一，并说明理由：

• PASS — 所有项均无严重问题；可测量的无障碍性检查通过；可以进入下一步。
• CẦN SỬA — 具体列出必须修改的内容（优先处理可测量的无障碍性问题和几何布局破损，再处理层级/一致性问题）。

Verdict 仅供参考 — 由人决定，不阻止提交。 硬性把关由确定性引擎负责（contrast/tap-target/overlap/misalign 从红转绿）。不要让用户误以为“qc-uiux PASS = UI 完美”；它只是资深人士的审查意见，不是证据。

确定性引擎（0-token，不使用 LLM）— 复用 visual-qa

可测量部分共用 /visual-qa 的引擎（skills/visual-qa/assets/route-shots.mjs，headless playwright）；DESIGN_AUDIT 函数会测量页面中的实际 rect，并检查以下规则：contrast-aa · tap-target · missing-label · overlap · row-misalign · shadow-clipped · monochrome-surface · rogue-slab。运行：

node skills/visual-qa/assets/route-shots.mjs <base-url> --audit    # in issues theo route; exit ≠0 nếu a11y/hình học fail

这是“UI 变更时自动挂接”的部分——只挂接成本低的确定性检查；LLM 审计（本技能的 4 项）仍由人工调用。如果尚未启动 server/headless，则 fail-open（不阻止）。与 qc-code 的 qc-regression.py --run 类似：verify-before-commit 的步骤 3b 会调用它；UI 变更后，可测量的反模式不会悄悄卷土重来。

分支

ID	Kind	Guard	行为	Skip / failure	Rejoin
B01	conditional_required	route 是 list/table（queue、admin grid、ticket/request 列表、dashboard summary strip）	加载 references/list-control-checklist.md，将 11 个错误预先归入 4 项	其他 route → 跳过	W01
B02	recovery	无法启动 server/headless	引擎 fail-open（不阻止），继续进行 LLM 审计，并记录可测量部分尚无数据	—	W02
B03	conditional_required	route 上的用户操作（submit、checkout、登录）无法完成	无论 4 项得分如何，verdict 均为 CẦN SỬA	—	W04

验证与停止条件

可测量部分（contrast、tap-target、overlap、misalign、missing-label 等）由确定性引擎判定；失败时 exit ≠0；层级/偏差/dark-pattern 则由 LLM 审查，verdict 仅供参考。4 项均包含三个部分且 verdict 明确后即可停止；修改后，引擎必须通过（W05）。

示例

• 正向： /br run 后对 /qc-uiux 的注册表单 frame 进行检查 → 引擎通过，4 项得分为 8–9/10，第 3 项最严重的问题是卡片 padding 分别为 14/20/17px → 偏差表对齐到 --sp-4 → verdict 为 PASS，草稿为 DDMMYY-qc-uiux-signup.md。
• 边界/失败： 暗色模式下辅助文字 contrast 为 2.8:1 + 图标按钮为 20×20px → 引擎报告 contrast-aa + tap-target 未通过，并提供具体数值 → 第 1 项列出最严重问题和修复方法 → CẦN SỬA；修复后重新运行引擎，必须通过。
• 边界： 页面美观，4 项得分都很高，但 submit 按钮触发 pageerror → 第 4 项记录该错误，verdict 为 CẦN SỬA。

参考 — 相关内容

• references/list-control-checklist.md — 针对 list/table 的 11 个专属错误（阅读 Steps 的步骤 0）。
• skills/visual-qa/assets/route-shots.mjs — 本技能复用的确定性测量引擎（DESIGN_AUDIT）。
• llmwiki/skills/dev-loop/qc-code.md — 关联技能：采用相同的高成本 LLM / 低成本确定性模式，用于 CODE。
• harness/scripts/qc-regression.py — 确定性 qc-* 测试运行器（qc-code），在 verify-before-commit 时运行。
• llmwiki/skills/dev-loop/build-now-adapt-later.md — 关于将高成本/低成本部分拆分隔离的模式。

交付 — 输出报告

审计完成后，写入草稿 llmwiki/wiki/sources/draft/DDMMYY-qc-uiux-<route>.md（OKF frontmatter 为 type: draft，包含 ## Origin），总结：已检查的 route · 4 项得分 · 引擎检测到的可测量问题 · verdict + 必须修改的内容。向 index.md + log.md 添加一行。如果只运行测量引擎（没有新的判断），则跳过。