design-review

设计评审技能

角色与范围

ADS 判断的负责人，而不是第二个执行循环。评审重要的视觉工作和用户要求的批评意见；对于小改动，只检查受影响的结果和附近行为。仅修改文案无需研究、多个方案、完整状态矩阵或单独评分。遵守 ADS 规定的任务预算和授权范围。

视觉基础契约

对于重要工作，使用 ADS 在 ../agentic-design-system/contracts/visual-foundation.v2.json 中锁定的基础配置。 已确认的 never 规则会阻止给出就绪结论，但不妨碍如实交接尚未解决的发现。

• 绝不只在圆角矩形的一条边上加边框。完整周边边框仍然有效。
• 绝不使用零模糊或内阴影重现这种单边效果。
• 绝不强制使用全大写样式。编写的界面文案使用句首字母大写或标题式大小写；字面形式的外部标识符若修改会导致失真，则可作为狭义例外。
• 界面文案中绝不使用 em dash。
• 绝不使用静态或动画状态圆点。状态信息不应依赖颜色才能读懂；只有在能实质性提升浏览或理解效率时才添加图标。
• 当前不使用装饰性圆点的偏好也适用于编写的文本分隔符和列表标记，而不只是圆形状态元素。保留字面数据和数学符号。
• 控件有对应图标时，使用真正的图标。保持项目图标系列统一；否则使用获得许可的 Nucleo 或一个开源图标系列，绝不混用。
• 工具类工作应从产品字体、系统无衬线字体或其他常规通用字体系列入手。表现力强的字体排印必须用于符合条件的界面，或有明确成果要求。
• 自定义字距和行高应来自明确声明的字体角色，而非装饰性即兴调整。
• 普通短语能够表达时，避免在界面文案中使用冒号。字面时间、链接、代码、协议、结构化数据和逐字保留的外部数据仍可使用冒号。
• 优先通过留白和分组来组织内容，再添加分隔线。分隔线密度应作为独立的评审判断，而非僵化的自动门槛。

确定评审目标

从请求、源内容以及现有的 DESIGN.md 或指南中还原当前需求、确切界面和需保留的内容。检查实际基线、组件和设计令牌。指定的后端、框架或导出格式并不能证明这就是用户想要的界面。只有在缺失的参考或模式决策确实重要时才进行研究；复用先前的答案和已采纳的示例。对于已选定的方向或小幅修正，不要要求提供新的参考资料。

判断顺序

1. 产品与任务契合度： 这是预期的产品或界面吗？用户能否完成所要求的任务？指出必须保留的基线优势。
2. 信息架构： 不借助实现说明，读者能否识别重要对象、比较内容、时间范围和下一步操作？打开证据或详细信息时，测试返回路径，确保阅读上下文完整保留，包括直接进入时的行为。
3. 参考与视觉方向： 按需求实际借鉴的属性进行比较，且保持预期的还原度。参考内容中偶然出现的装饰性元素不应自动视为任务要求的一部分。
4. 工艺： 在最终尺寸下检查构图、层级、字体排印、间距和一致性。
5. 行为与交付： 验证适用状态、实际交互、目标浏览器，以及所交付的产物能否在用户的评审环境中访问。

不要让后续的机械检查抵消较早阶段的失败。根据实际产物报告观察结果，而不是给出加权自评分。区分已观察到的缺陷、审美判断和证据缺失。仅在获得授权且条件允许时使用独立评审者；对于尚未解决的产品方向和审美判断，保留人工判断。

核心原则

• 克制本身就是设计。
• 间距是最重要的辨识标志。
• 对信息架构而言，字体层级比颜色更重要。
• 添加自己的想法之前，先匹配约定的参考属性和保真度。
• 优先沿用现有模式，而非创建新模式。
• 交互元素应打磨完善，而不是毫无反馈。
• 如果基础错了，再多修饰也无济于事。
• 好的设计是向心的，而不是离心的。

参考文件

只阅读任务所需的内容。保持此 SKILL 精简，按需加载细节：

• references/typography.md — 层级、字号比例、字体搭配、行长
• references/color.md — 克制的配色方案、有色中性色、对比度、OKLCH
• references/spacing.md — 间距系统、节奏、分组、布局密度
• references/motion.md — 时长、缓动、减少动态效果、交互感受、命名动态术语
• references/mobile.md — 移动端审查配置：设计判断与平台缺陷检查、决策分支、严重程度级别
• references/anti-patterns.md — 应当拒绝的常见 Agent 模式
• references/ux-writing.md — 界面文案、术语一致性、标签、错误和空状态

子 Agent 指南

• 根据要构建的内容阅读相关参考文件。
• 新布局或仪表盘？阅读 spacing + anti-patterns。
• 以文字为主的界面？阅读 typography + spacing。
• 配色或主题相关工作？阅读 color + anti-patterns。
• 交互细节打磨？阅读 motion + anti-patterns。
• 移动端 / 响应式 / 应用 / PWA 审查？阅读 mobile + responsive。
• 界面文案或同一概念的名称存在分歧？阅读 ux-writing。
• 仅加载能解决相关设计决策或已发现缺陷的参考文件。

在请求范围内进行验证

判断完成后，使用以下适用的检查项。不要把微小修改扩大成全面审查。无法运行的必需检查应标记为未验证，不得悄然省略。

步骤 1：视觉验证

• 为渲染结果截图。
• 如果有参考图，将两者并排比较。
• 检查目标视口，而非任意的开发者工具宽度。
• 通过截图和针对具体状态的交互记录核实状态差异。相同的文本与标记特征只能提示需要比较，并不代表缺少状态：焦点或悬停可能改变像素，却不改变标记。根据渲染证据解决相互冲突的状态判断条件；单凭特征相同或不同，都不能确定预期状态是否已渲染。将注入的诊断样式与主要截图分开，并明确记录。
• 运行渲染后的无障碍检查前，展开嵌套披露项，以及可能同时显示的行内 / 完整详情副本。在手机视口中测量披露项的点击目标，并检查重复的地标名称。对于不适合作为地标的重复项，使用带标签的分组；修复后再次核实展开状态。
• 操作所有可访问的模态界面。验证初始焦点、Tab 和 Shift+Tab 的焦点限制、Escape 关闭、焦点返回以及背景内容不可交互。如果没有站点专属说明就无法打开模态界面，应记录为 not verified，而非判定通过。
• 对话框内的帮助披露项，应在桌面 Chromium 和移动 WebKit 中测试点击 / 轻触后按 Escape，而不只是运行组件测试。必要时，激活后将焦点移至帮助触发器，使 Escape 关闭展开的帮助内容而不关闭对话框；帮助内容关闭后，再让 Escape 作用于对话框。验证焦点仍位于触发器上，且重复的帮助控件彼此独立。

步骤 2：设计审查

• 间距检查 — 分组和密度是否服务于任务，并保留选定的产品语言。
• 颜色检查 — 是否添加了不必要的颜色？
• 排版检查 — 不依赖颜色，层级是否依然清晰？
• 模式检查 — 是否使用了项目现有的组件？
• 交互检查 — 是否存在悬停、焦点和激活状态，且设计是否有意为之？
• 术语检查 — 每个面向用户的概念是否都有一个主要名称；别名是否只在首次出现时引入， 且不会与主要术语相互竞争。
• 完整性检查 — 是否没有占位符、无效状态、损坏的资源或缺失的数据处理？
• 偏好检查 — 检查受影响的渲染文案、标记和生成的 CSS 内容。 在给出通过结论前，根据实际上下文处理适用的捕获结果；字面记法不是装饰。源代码扫描或候选项数量为零并不能证明符合要求。

步骤 3：诚实性检查

• 是否真的完成了？
• 是否符合任务要求，而不是相邻的另一项要求？
• 经得起不带预设立场的审查吗？

步骤 4：运行源代码预检脚本

如果有相关脚本，请对受影响的代码和声明运行相应检查。将 <skills-root> 替换为已安装技能文件夹所在的目录：

# check for common agent anti-patterns
python3 <skills-root>/design-review/scripts/anti-pattern-check.py <your-file.tsx>

# verify loading, empty, and error states exist
python3 <skills-root>/design-review/scripts/state-check.py <your-file.tsx>

# check semantic HTML, aria labels, alt text, heading hierarchy
python3 <skills-root>/design-review/scripts/accessibility-check.py <your-file.tsx>

在提交前调查警告。这些检查会 grep 源代码，设计上成本低且容易被规避；在注释中写上“loading, empty, error”就可能通过状态检查，即使没有渲染任何状态。它们只能提供参考，不能证明工作已通过检查。

对于有实质性视觉变化的内容，请捕获实际路由。选择任务要求的状态； 下面的 default,loading,empty,error 只是示例，并非普遍适用的强制矩阵：

node <skills-root>/agentic-design-system/scripts/run-capture.mjs "<running-route-url>" \
  --states default,loading,empty,error --out evidence/<slug>

检查捕获结果并测试所需交互；自动捕获可能无法触及所有特定于站点的状态。应依据已建立的渲染字段来判断门槛机制，而非个人喜好。证据格式 2 还会记录圆角的单边边框、单边阴影候选项、强制大写、排版异常值、仅含符号的控件、状态圆点候选项、圆点字形／列表标记候选项、分隔线数量、冒号和 em 短横线。这些新增测量结果仍仅供报告，直至其测试夹具的精确度得到验证。

visualFoundation.dotGlyphCandidates 会报告估计为可见的文本、CSS 生成字形和原生圆点列表标记。请检查每个结果：透明或被裁切的字形可能是假阳性，而未标记的数学内容或逐字引用文本可能是合理的。 代码／数学元素不会纳入检查；普通标点不受影响。Shadow DOM、canvas、图像内容和自定义图形标记仍需进行视觉审查。此诊断不会编辑文案。

渲染捕获结果还会报告可见的 aria-modal 契约检查结果，以及缺少 (hover: hover) and (pointer: fine) 的、带有悬停动效的 :hover 规则。在校准期间，这些交互诊断仅供报告。缺失或无法触达的模态框属于“未验证”，不算通过。

CI 适配器用于维护源代码仓库，并非随产品发布的运行时依赖。提出集成方案前，请先确认源代码检出情况和请求范围；不要为了常规设计工作添加 CI。

步骤 5：提供结果和证据

返回任务结果、保留的基线、相关证据和已知缺口。需要远程审查时，请使用可用的附件或已获授权且可访问的 URL。区分本地准备、实际交付、人工验收和发布。构建成功、扫描通过或截图存在，都不能单独证明后三项中的任何一项。

反馈归属

遵循 ADS 反馈分类。明确的偏好归其当前所有者，产品选择归入项目上下文，反复出现且可衡量的缺陷归入基础组件／测试，一次性修复归入任务本身。不要仅仅因为收到反馈就附加一条新的通用规则。保留已接受的示例及其验收证据，而不是 Agent 的自我评价。