FrancoisChastel/a11y-eval

无障碍修复器

您正在执行无障碍修复。您的输入是 缓解工单 (mitigations.md，由 a11y-eval 生成)；您的输出是使发现的问题消失的最小源码变更，确保 真实用户 能够正常使用，并通过重新运行评估器进行验证。

如果尚不存在工单，请先生成一个：在 a11y-eval 检出目录中运行 node src/cli.ts --repo <dir>（或针对运行中的应用使用 --url），或者从现有报告运行 node src/cli.ts mitigate --report <dir>。

修复说明

按照以下优先顺序，以最小变更恢复真实可访问性，修复无障碍违规：

1. 优先使用原生语义。 用真实元素替换假组件：div onclick → <button type="button">，导航 span → <a href>，无标签输入 → <label for> + 输入。原生元素免费提供键盘操作性、角色、名称和状态——ARIA 补丁是备选方案，绝不应成为首选。
2. 内容优先于属性。 替代文本、标签、链接文本和错误消息必须传达实际信息（"第三季度收入增长 12%"），而不是复述元素（"图表"、"图像"、"链接"）。根据周围上下文编写；如果无法推断含义，则标记给人工处理。
3. 在令牌/组件级别修复。 当同一规则跨多个页面触发时，找到共同原因——CSS 自定义属性、基础组件、布局包装器——并一次性修复它。绝不要在一个根组件的四十个调用点逐个打补丁。
4. 保留用户能做的所有操作和能阅读的所有内容。 文本内容、交互能力和视觉层次结构必须在修复后得以保留。删除功能、隐藏元素（display:none、aria-hidden）或移除可聚焦性以消除发现的问题，都是失败的修复。
5. 对比度是算术，不是美学。 计算比率（普通文本 ≥4.5:1，大文本/UI 组件 ≥3:1）；选择所需色相中最近的通过色值，而不是跳到黑/白。
6. 焦点必须处处可见。 删除全局 outline: none；添加 :focus-visible 轮廓（≥2px、偏移、与周围环境对比 ≥3:1）。通过 Tab 键验证。
7. 每次变更集对应一个工单组。 修复组中列出的所有实例，然后验证，再开始下一组。将不相关的组批处理会导致回归不可追踪。
8. 工单中的每个“禁止”操作都具有约束力。 当修复与陷阱冲突时，陷阱优先——停下来重新考虑方法。

工作流程

1. 从头到尾阅读工单。组按影响力和覆盖范围排序——请尊重顺序。
2. 在源码中定位每个实例：静态发现带有 file:line:col；运行时发现带有 CSS 选择器和 HTML 片段——用该片段、类名或附近文本在仓库中搜索。
3. 对每个实例应用该组的修复，遵循上述修复说明以及该组的步骤/陷阱。
4. 验证批次：重新运行工单的验证命令（原始评估 + --baseline <前一份报告>）。当组的规则出现在“已修复”下且 new 发现为 0 时，该组即被清除。
5. 人工失败部分：审查者的证据是规范。根据规范推导变更，应用，并注明该标准需人工/智能体重新审查——自动化无法确认它。
6. 停止条件：对于无法推断含义的实例（未知图像的替代文本、歧义字段的标签），添加 TODO(a11y) 注释并在摘要中注明——错误的猜测比标记的缺口更糟糕。
7. 报告：修复前后的分数、已清除的组、新增发现（应为 0）、标记给人工处理的项目。

VLM 可疑组

工单中可能包含 vlm-* 组（仅在评估使用 --vlm 运行时出现）。其实例行包含视觉模型推理——对于 vlm-alt-quality-suspect，包含 建议的替代文本。将建议视为草稿：在应用前对照实际图像验证，切勿应用无法从页面本身确认的 VLM 建议变更。

禁止事项

• 失败：在原生元素可用时，在 div 上添加 tabindex + 按键处理
• 失败：在信息性图像上使用 alt=""；aria-label 重复可见文本导致不匹配
• 失败：压制规则、删除元素或使用 aria-hidden 使发现消失
• 失败：未经计算对比度比率就凭肉眼调整
• 失败：未重新运行验证以显示规则已消失就声称完成

相关技能

• a11y-evaluator — 生成此技能使用的报告和工单