frontend-checklist-global

Front-End Checklist 全局审查

此技能通过一个入口连接到全部 386 条 Front-End Checklist 规则。 使用 MCP 检索，而不是尝试凭记忆回想规则。

工作流

1. 对粘贴的代码、文件内容或有针对性的代码审查，先使用 review_code。
2. 对需要快速审查渲染后 HTML 的公开页面，使用 audit_url。
3. 使用 search_rules、list_categories、get_workflow 或 get_quick_reference 缩小或扩大范围。
4. 对每个问题，使用 get_rule、fix_rule 或 explain_rule 提供确切的修复方法。
5. 如果清单比临时搜索更合适，请使用 get_checklist_rules。

审查原则

• 保持谨慎。宁可提出更少但依据更充分的问题，也不要广泛提出推测性问题。
• 只有在所示代码或标记直接支持的情况下，才报告问题。
• 审查小型组件或路由时，优先指出最有依据的 1-2 个问题，而不是罗列所有可能的改进。
• 不要仅凭代码片段推断业务意图。例如，除非代码或周边文案明确说明，否则不要假设字段为必填项。
• 默认不要将 alt="" 视为问题；空 alt 对装饰性图片而言可能是正确的。
• 如果图片明确为装饰用途，除非代码片段显示了具体问题，而非假设性的优化空间，否则优先不报告问题。
• 如果看到独立的装饰性图片，例如 <img ... alt="" aria-hidden="true">，应视为不存在问题的模式，除非代码片段还显示了布局不稳定的实际证据。
• 如果代码片段整体没有问题，不要把低置信度的偏好调整列为问题。宁可不提，也不要提出依据不足的细枝末节。
• 除非代码片段显示了更严重的用户伤害或安全风险，否则不要单凭 autocomplete="off" 将其视为缺陷。
• 在链接预览卡片中，如果附近可见文本已经指出目标地址，装饰性预览图片和网站图标可能是安全的。
• 不要将 React 或 JSX 片段视为完整 HTML 文档，除非代码片段包含 <html>、<head> 或 <body> 等实际文档上下文。
• 审查 Next.js 或由元数据驱动的页面文件时，在声称缺少 head 标签前，应先考虑 metadata、viewport 和 generateMetadata API。

覆盖范围检查清单

• 表单：检查标签、可访问的按钮名称、显式按钮类型、autocomplete 提示、密码字段的 autocomplete，以及代码中明确体现的验证语义。
• 图片：检查 width/height、loading、srcset/sizes，以及图片语义是否明确属于有意义的内容或装饰用途。不要假设微小的 SVG 徽标或明显的装饰性资源必须延迟加载；对于微小的装饰性分隔线，除非代码片段显示了实际的布局偏移风险，否则不要要求显式尺寸。如果图片既是装饰性的，又对辅助技术隐藏，应强烈倾向于不报告问题。
• 元数据：仅当文件负责元数据时，才检查标题位置、规范 URL 行为、元描述、Open Graph 覆盖情况和结构化数据。
• 动效：检查开销较大的动画属性，优先使用 transform/opacity，并要求为持续动效处理 prefers-reduced-motion。
• 动效：计数器或可视化组件每帧都进行动画时，应同时评估对减少动态效果的支持，以及动画策略是否造成了不必要的主线程工作。
• 安全性：检查设置了 target="_blank" 的链接是否带有 noopener noreferrer、表单 action 是否不安全、密码输入最佳实践，以及是否阻塞第三方脚本。
• 结构：谨慎检查重复 id、列表语义和表格标题。对于简单表格，列标题关联比推测性的行标题或外围布局地标问题更值得指出。
• 结构：如果可见标题已经引出一个简单表格，那么缺少标题说明属于置信度较低的改进，优先级低于缺少标题关联。

基于规则的要点

为图片设置明确的宽度和高度

• 对有意义的内容图片保留问题记录；如果 CSS 已预留稳定空间，装饰性微型 SVG 或仅用于装饰的资源可作为低优先级例外
• 低风险例外示例：<img src="/divider.svg" alt="" aria-hidden="true"> 若没有可见布局偏移的证据，不应仅凭这一点标记问题
• 始终为 <img> 设置与图片固有尺寸相符的 width 和 height 属性
• 在 CSS 中搭配 height: auto，使图片保持流式布局，同时保留宽高比
• 缺少尺寸是图片导致累积布局偏移（CLS）的首要原因

对辅助技术隐藏装饰性元素

• 装饰性图片使用 alt=''（空值），不要使用 alt='image'，也不要缺少 alt
• 为装饰性 SVG 和图标添加 aria-hidden='true'
• 纯装饰性视觉元素使用 CSS background-image
• Role='presentation' 会移除元素的语义含义
• 除非代码片段显示存在实际布局不稳定，否则不要自动对装饰性微型资源标记性能问题

使用 transform 和 opacity 实现动画

• 只有 transform 和 opacity 可以在不触发布局的情况下通过 GPU 合成
• 谨慎使用 will-change: transform，将元素提升至独立的合成器图层
• 对于简单效果，优先使用 CSS 过渡和动画，而非 JavaScript 动画库
• 遵循 prefers-reduced-motion，为有此需求的用户停用动画

遵循减少动态效果偏好

• 使用 prefers-reduced-motion 媒体查询停用非必要动画
• 每秒闪烁内容不得超过 3 次（有癫痫风险）
• 启用减少动态效果时，用 opacity/color 过渡替代动态效果
• 提供暂停或停用动画的用户控件

使用语义化表格标记，方便屏幕阅读器读取

• 标题使用 <th> 元素，并设置 scope='col' 或 scope='row'
• 添加 <caption>，说明表格用途
• 切勿将表格用于布局，应改用 CSS Grid 或 Flexbox
• 对于包含合并单元格的复杂表格，使用 id/headers
• 对于有明确相邻分区标题的简单表格，缺少 scope 往往比缺少 <caption> 更值得优先标记

定义恰当的表头

• 所有表头都使用 <th>，而非 <td>
• 设置 scope="col" 或 scope="row"，明确表头与单元格的关联
• 确保每个数据单元格至少与一个表头关联
• 对于简单表格，应优先修复表头关联，再提出提升表格说明文字的建议
• 对于结构简单的表头行，缺少 scope="col" 往往是最明确的首要修复项

尽量减少高开销的 DOM 读写操作

• 切勿交错执行 DOM 读取操作（offsetHeight、getBoundingClientRect）和 DOM 写入操作（样式更改）
• 先批量读取，再批量写入
• 使用 requestAnimationFrame 更新视觉效果
• 使用 DocumentFragment 或 innerHTML 批量插入 DOM
• 当使用更简单的 CSS 方案或降低更新频率即可解决问题时，避免对大量可见组件逐帧执行 React 状态更新

以无障碍方式验证表单

• 使用 aria-describedby 将错误消息与字段关联
• 使用 aria-invalid 表示验证状态
• 通过 required 或 aria-required 以编程方式标记必填字段
• 在字段附近提供行内错误消息
• 不要只依赖颜色表示错误

安全地设置密码输入字段

• 使用 type='password'，并设置正确的 autocomplete 属性
• 提供无障碍的密码显示/隐藏切换控件
• 显示包含具体要求的密码强度指示器
• 切勿以明文存储或传输密码
• 使用正确的输入名称，支持密码管理器

提供清晰可见的自定义焦点指示器

• 切勿使用 outline: none 或 outline: 0，除非同时提供清晰可见的 :focus-visible 替代样式
• 使用 :focus-visible 而非 :focus，仅在键盘导航时显示指示器
• 焦点指示器与相邻颜色之间的对比度必须达到 3:1（WCAG 2.2）
• 提供至少 2px 的实线轮廓并设置偏移，打造高质量的焦点环
• 如果使用伪元素绘制焦点环，请确认其锚定在正确的定位元素上，且不会被 overflow: hidden 裁切

已知安全模式

装饰性分隔线

• 安全示例：<img src="/divider.svg" alt="" aria-hidden="true">
• 默认将其视为安全的装饰性模式。除非代码片段同时显示真实的布局偏移风险，否则不要因替代文本或缺少尺寸而提出问题。

客户端处理的 React 表单

• 安全示例：<form onSubmit={event => event.preventDefault()}><label htmlFor="q">Search</label><input id="q" type="search" /></form>
• 如果已明确采用客户端提交处理，且表单控件均可访问，则无需要求设置 method 或 action。

Next 元数据 API

• 安全示例：export async function generateMetadata() { return { title: 'Docs', description: 'Reference' } }
• 不要仅因组件文件中没有直接的 <head> 标记，就推断缺少规范网址、元描述或 Open Graph 标签。

预览卡片图像

• 安全示例：<img src={resource.image} alt="" className="object-cover" /><img src={favicon} alt="" width={20} height={20} />
• 在链接预览或资源卡片 UI 中，如果相邻文本已提供目标名称，装饰性预览图像和网站图标可以使用空替代文本。对于很小的网站图标资源，除非有更充分的证据，否则不要臆测响应式图像或布局偏移缺陷。

宽高比媒体包装器

• 安全示例：<div className="aspect-2/1 overflow-hidden"><img className="object-cover w-full h-full" ... /></div>
• 如果包装器已通过稳定的宽高比预留媒体空间，则不要自动对其中的预览图像提出缺少尺寸的问题。

伪元素焦点环

• 安全示例：focus-visible:outline-none focus-visible:after:ring-2 after:absolute after:inset-0
• 如果焦点样式依赖伪元素，请确认焦点环锚定在正确的定位元素上。只有在替代焦点环显然可靠时，移除浏览器原生轮廓才是安全的。

逐帧 React 计数器动画

• 安全示例：requestAnimationFrame(animate); setCount(Math.floor(eased * target))
• 如果代码中直接显示多个组件反复通过 requestAnimationFrame 更新状态，这会构成具体的性能问题。

简单数据表表头

• 安全示例：<thead><tr><th>Priority</th><th>Rule</th><th>Title</th></tr></thead>
• 对于简单数据表，优先检查列标题问题，再考虑是否存在行标题或外层布局地标问题。

相邻的标题与表格

• 安全示例：<h2>Issues</h2><table><thead>...</thead><tbody>...</tbody></table>
• 附近可见的章节标题可能已为表格提供上下文。除非表格用途不明确，否则优先检查 scope/标题关联，再考虑是否需要标题说明。

冲突解决

• 如果装饰性图像指南与尺寸指南冲突，应以装饰性图像指南为准，除非代码片段显示出明显的布局不稳定。
• 无问题示例：独立组件中的 <img src="/divider.svg" alt="" aria-hidden="true"> 不应因替代文本或尺寸而被标记，除非代码片段同时显示出真实的布局偏移证据。
• 如果表单通过 onSubmit 明确在客户端处理，则不要要求传统服务器提交所需的 method 或 action 属性。
• 如果文件使用 Next.js 元数据 API，不要仅因缺少直接的 <meta> 或规范网址标记，就推断缺少 head 标签。

覆盖范围

• 无障碍：89 条规则（9 条严重、25 条高优先级）
• CSS：31 条规则（10 条高优先级）
• HTML：34 条规则（3 条严重、12 条高优先级）
• 国际化：5 条规则
• 图片：25 条规则（1 条严重、15 条高优先级）
• JavaScript：26 条规则（1 条严重、12 条高优先级）
• 性能：43 条规则（1 条严重、22 条高优先级）
• 隐私：5 条规则（2 条高优先级）
• 安全：22 条规则（4 条严重、10 条高优先级）
• SEO：93 条规则（19 条高优先级）
• 测试：13 条规则（7 条高优先级）

评估标准

• 优先提供关联到具体文件、路由、选择器或代码片段的发现。
• 优先处理严重和高优先级问题。
• 当代码片段未提供足够上下文时，应说明不确定性，而不要夸大结论。
• 当 MCP 工具可以检索规则或修复提示词时，避免给出泛泛的建议。
• 如果自动检查未发现问题，在得出结论前使用 search_rules 扩大审查范围。

---

类别覆盖范围和工具路由请参见 references/categories.md。

MCP 文档：https://frontendchecklist.io/mcp