Material Design 3 审查
根据 Material Design 3(M3)审查用户界面,并尊重项目自身的指南,生成一份可供用户逐项决策的编号报告。然后记录决策并输出被接受的更改。
何时使用 / 何时不使用
当用户要求以下内容时使用:
- “根据 Material 3 审查这个屏幕/页面/组件”、“这是 M3 合规的吗?”、“M3 审核”、“设计审查”
- 检查现有 UI 的触摸目标、对比度、字阶、颜色角色、形状、间距或组件
- 在发布前,将截图或运行的页面与 Material 指南进行比对
- 决定哪些与 Material 的偏差要保留,哪些要修复
当以下情况时不要使用:
- 用户想要生成新 UI、构建主题或从头编写代码(“帮我做个 M3 登录页面”);本技能用于审查,不生成
- 目标设计系统明确不是 Material(Apple HIG、Fluent、没有 M3 基础的自定义系统),除非用户仅想要最低检查
- 问题是一个单一事实查询(“FAB 高度是多少?”);直接从参考文件中回答
审查期间不要更改代码。仅在用户做出决策后要求时才更改代码。
层级与优先级
按此顺序应用规则。更高层级的规则覆盖较低层级的规则。
- 最低规则,层级 F:无障碍和可用性最低要求(目标、对比度、焦点、标签、文本缩放、减少动效)。不可协商。项目指南不能豁免它们。
- 项目指南和已记录决策,通过适配器协议(
references/adapter-protocol.md)找到。 - M3 核心,层级 C:角色、令牌、字阶、形状阶、组件规范。偏离需要明确的决策。
- M3 表达性和可选项目,层级 E。不要将它们的缺失报告为缺陷。
当项目指南或已记录决策与层级 C 或 E 规则冲突时,不要报告违规。在“决策候选”下列出冲突一次(仅当它尚未记录在决策记录中时)。当它与层级 F 规则冲突时,报告 F 发现并在其证据中注明冲突的指南。
容忍度
两种模式。默认为 inspired。
strict:每个层级 C 不匹配都是一个议题;层级 E 项目是建议。inspired:层级 C 不匹配是建议,除非它们损害可用性(此时它们是议题);层级 E 项目仅当它们增加明确价值时才是建议。- 在两种模式下,每个层级 F 发现都是一个议题。
使用用户命名的模式。如果项目指南指定了一个,则使用它。否则使用 inspired 并在报告头部说明。
证据标签
为每个发现和每个注释标注恰好以下标签之一:
measured-rendered:从渲染页面读取(DOM、计算样式、命中测试),给出选择器和值。measured-code:从源代码或声明的 CSS 读取,未在渲染页面上确认。measured-simulation:在渲染页面上模拟条件下测量(用于文本缩放的窄视口,模拟设置如深色模式、减少动效或强制颜色)。建议在真实设备上确认。estimated:从图像推断。
将 v0.1 标签 measured 视为 measured-rendered。当发现结合多种来源时,使用最弱的标签。除非比例已知(CSS px 中的视口宽度和 devicePixelRatio,或已知参考元素),否则永远不要从截图中给出精确的 dp 或 px 值。询问一次比例,或者给出范围并标记为 estimated。永远不要从压缩图像中给出精确的对比度比率;给出近似比率并标记为 estimated。
工作流程
第 0 步:确定审查面
根据给定的材料或通过询问一次来确定:
- 审查内容:截图、源文件、URL 或本地页面、设计工具导出
- 平台:Web、Android(Compose 或 Views)、Flutter、iOS、跨平台
- 外形尺寸和窗口大小类别:紧凑(< 600)、中(600-839)、扩展(840-1199)、大或超大
- 浅色、深色,或两者;是否存在高对比度、减少动效或应用内文本大小设置
如果审查面显示个人数据(姓名、金额、地址、消息、健康或账户数据),在回复顶部说明并建议审查已编辑或演示状态。不要将截图或页面数据存储在文件、内存或决策记录中。仅引用识别元素所需的最少文本。
第 1 步:加载适配器
遵循 references/adapter-protocol.md:查找项目设计指南、决策记录、约定列表、变更列表格式和审查设置(要测试的宽度和文本大小设置)。如果未找到,用单个简短问题询问一次;如果用户不回答或说没有,则仅使用 M3 和默认值继续。
设计简报:当提供或找到简报时(来自 m3-design-brief,或任何带有验收标准 AC-nn 的简报),将其视为项目指南。其决策(B-nn)在其范围内作为已记录决策(不是决策候选);其容忍度、宽度和主题是审查设置;层级 F 仍然胜出。检查每个 AC 并填写报告的“简报验收标准”部分(通过、失败或未检查,附带证据)。
第 2 步:选择容忍度
strict 或 inspired(参见容忍度)。如果用户或指南已经决定,则不要询问。
第 3 步:测量
优先测量而非估算。按此顺序:
- 可用渲染页面(Playwright、浏览器自动化工具、DevTools):评估页面中的
scripts/measure.js并使用其 JSON(references/measurement.md,“如何运行”和“输出字段及其馈送的规则”)。分别测量每个宽度和主题:来自适配器的宽度和文本大小设置,否则是一个紧凑宽度(例如 390 px)和一个扩展宽度(例如 1280 px),浅色和深色。 - 仅可用源代码:读取 CSS/HTML/JS 或组件代码;从中计算大小、颜色和半径,并将结果标记为
measured-code。 - 仅可用图像:估算,标记为
estimated,如果精确数字重要则询问比例。
在读取任何结果之前进行设置检查(measurement.md,“设置检查”):
- 使用
expectWidth传递您打算测试的 CSS 宽度。 - 如果
warnings包含viewport-meta-missing或viewport-width-mismatch,则停止。页面布局在您未意图的宽度(通常是 980 px)下,因此每个大小都是错误的。修复设置(设置视口,或注入生产环境提供的相同视口元标签),重新运行,然后才能继续。永远不要报告来自此类运行的大小;如果生产环境本身缺少此标签,则报告一次。
有效点击区域(measurement.md,“有效点击区域”):启用 hitScan(默认)时,根据 hitWidth x hitHeight 判断目标大小,而不是视觉框。hitAreaVia 说明区域是如何找到的(box,label,pseudo,probe);probe 说明命中测试是否确认了它(ok)或未确认(covered,offscreen,limited:仅几何,在报告精确大小之前确认)。
由 ::before/::after 放大的 pseudo 区域算数;检查其框是否未被边框缩小或被 overflow: hidden 祖先裁剪,并在代码中确认可疑情况。
对于文本缩放,遵循 measurement.md,“食谱:200% 文本”(结果是 measured-simulation);对于菜单、对话框、工作表、选项卡、单选组和视图变化,遵循 measurement.md,“食谱:焦点流”。
将脚本输出(包括 truncated, nonTextContrast, labelInName, ariaConflicts)视为候选,而非定论:在根据其规则报告之前确认每个。状态和动效样式未被测量;当它们重要时通过代码或交互检查。
当脚本无法解析对比度(渐变、图像或半透明背景)时,手动计算最坏情况(文本下的最暗和最亮停止点,或与实际背景合成的 alpha 颜色)并将其报告为 estimated,附带使用的停止点。对于 color-mix() 或 alpha 文本颜色,使用最终的合成颜色。如果页面没有深色变体,则报告一次(主题对等规则在 references/color.md 中),而不是每个元素。
第 4 步:仅加载相关参考
渐进式披露:永远不要加载所有参考文件。根据屏幕上显示的内容选择。
| 审查面包含 | 加载 |
|---|---|
| 任何审查面(始终) | references/layout-interaction-a11y.md,首先加载“无障碍最低要求”和“跨组件规则”部分 |
| 颜色、主题、深色模式、令牌、对比度 | references/color.md |
| 排版、圆角、高度、间距、动效、图标 | references/styles.md |
| 应用栏、徽章、底部工作表、按钮组、按钮、卡片、轮播、复选框、芯片、日期选择器、对话框、分隔线 | references/components-1.md |
| 扩展 FAB、FAB 菜单、FAB、图标按钮、列表、加载指示器、菜单、导航栏/抽屉/导轨、进度指示器、单选按钮 | references/components-2.md |
| 搜索、分段按钮、侧面工作表、滑块、操作条、拆分按钮、开关、标签页、文本字段、时间选择器、工具栏、工具提示 | references/components-3.md |
| 表达性功能、弹簧动效、形状变形,或用户询问表达性 | references/expressive.md |
| 编写报告 | references/report-template.md |
| 记录决策、约定、变更列表 | references/adapter-protocol.md |
在大文件中,仅读取屏幕上组件的相关部分。首先列出标题(grep -n '^## ' references/components-1.md),然后只读取那些行范围(sed -n 'START,ENDp' file)。如果某个参考文件缺失,说明情况并用其他文件继续;不要发明规则来填补空白。
第 5 步:检查、分类、分组
对于每个候选:
- 首先根据功能分类控件(CMP-01),然后找到规则。引用其 ID 和其
Source与参考文件中完全相同。当多个规则重叠时(组件规则和相同目标大小的最低规则),引用最具体的一个并在其后列出其他规则(“也是 A11-01”)。 - 如果没有规则 ID 支持它,不要将其报告为 M3 发现。如果它违反项目指南,或参考中规则未覆盖的 WCAG 2.2 成功标准,则将其放入“项目和 WCAG 注释”(
N-01...),并使用指南部分或WCAG 2.2 SC x.y.z作为其来源(典型情况:缺少lang属性、禁用缩放的视口元标签)。否则省略它。 - 检查决策记录:已记录的偏差不再报告(在一行中提及被抑制项目的计数)。
- 检查项目指南:与层级 C 或 E 的冲突转到“决策候选”,而不是发现。如果项目选择没有 M3 规则可偏离,则候选使用规则 ID
none (project convention)。 - 分类:根据容忍度确定层级(F、C、E)和种类(议题或建议)。在
inspired模式下,层级 C 不匹配“损害可用性”(因此是议题)仅当它使内容难以阅读、难以操作、或对典型用户不明确时:文本低于 12 px、控件目的或状态不清楚、在支持的宽度下布局中断。否则它是建议。 - 分组:每个根原因一个发现。当相同问题出现在多个地方,或来自一个共享组件、类或令牌时,报告一次,附带计数和每个出现(或两三个示例加上总数:“14 个图标按钮,32 x 32 px,例如
.toolbar button,#close”),以便单个决策覆盖它。将发现放在修复所在的区域。
按影响排序:层级 F 议题优先,然后是影响任务完成的议题,然后是层级 C 议题,然后是建议。在组内,按范围排序(涉及多少元素或屏幕)。报告上限约为 25 个发现;如果存在更多,说明有多少被排除并提供二次传递。
如果发现很少或没有,直接说明。不要添加空洞的赞美。不要为了填充报告而捏造问题。
第 6 步:呈现
精确使用 references/report-template.md。每个发现包含:运行 ID(F-01,不是层级)、区域、层级和种类、证据(选择器或图像区域、值、证据标签、出现次数)、规则 ID 及其来源、为什么重要(一行,用户影响优先)、具体提议更改(min-height: 48px, color: var(--md-sys-color-on-surface-variant), “圆角大号,28dp”;永远不要说“改善对比度”)、努力程度(S 一个属性或令牌、M 一个组件或多个文件、L 结构性或跨屏幕)以及决策框。
报告头部说明:审查的审查面和宽度、容忍度、参考快照日期(加载的参考文件头部中最旧的“快照日期”)、是否找到项目指南和决策记录、以及证据组合(四个标签各自的计数)。对于简报,一个违反规则的失败 AC 也是一个发现(或注释);其 AC 行指向那个 F-nn/N-nn,而不是重复证据。
新鲜度:将快照日期与今天的日期比较。如果超过 6 个月,或用户提到更新的 Material 版本,在头部说明,建议在实施层级 C 更改前刷新参考(仓库的 maintenance/UPDATING.md),并提供首先根据 https://m3.material.io/ 验证受影响规则的选项。层级 F 发现无论快照年龄如何都有效。
第 7 步:应用决策
当用户回答时(例如“接受 F-01 到 F-05,F-07 偏差:品牌药丸按钮,拒绝其余”):
- 对于层级 C 或 E 规则的每个
deviation:在决策记录中追加一条记录(日期、规则 ID、范围、一行理由、发现 ID),格式为references/adapter-protocol.md。层级 F 发现不能是偏差:将其记录为accepted risk并继续在摘要行中报告。如果没有决策记录存在,提议其路径并仅在用户同意后创建。 - 对于使用规则 ID
none(...)的每个决策候选:如果用户决定遵循项目指南,则将其作为项目约定记录在决策记录中。