review-a11y

review-a11y — 对变更代码进行无障碍审查

ultra11y 技能的审查对应版本：ultra11y 会生成完整的审计和合规交付物，而此技能只审查正在变更的代码——差异、分支或 PR——并像代码审查者一样报告。分工方式相同：此技能随附的确定性、免安装引擎负责机械性工作（机器可检查的 WCAG 2.2 AA 不符合项，每项均关联一条成功准则，并注明 file:line），AI Agent负责判断——驳回误报，根据代码静态判断替代文本的相关性／链接目的／焦点逻辑，并将需要渲染 DOM 的内容交由 scan 检查。人工监督最多是可选项。

**引擎解析：**下面的每条命令都是 node scripts/ultra11y.mjs …，其中 scripts/ultra11y.mjs 与此 SKILL.md 位于同一目录（引擎随技能提供；无需安装，也无需密钥）。运行时，将被审查的项目设为工作目录。在 ultra11y 仓库本身，仓库根目录中的 scripts/ultra11y.mjs 是同一个文件。在 Claude Code 中，该路径为 ${CLAUDE_SKILL_DIR}/scripts/ultra11y.mjs；在 Codex 和 OpenCode 中，则是插件安装的技能目录。如果两者均无法解析——例如运行环境没有技能系统——npx -y ultra11y <command> 使用的是同一个引擎。各运行环境的差异见 ultra11y 技能中的 references/harnesses.md。

核心规则（与 ultra11y 共用）：

1. 绝不臆造不符合项：只报告引擎发现的，或你能在受审查代码中看到并注明出处的问题。
2. 审查变更，而非整个项目：受审查范围之外的问题最多用一行备注（“预先存在，不在审查范围内”），绝不与审查结论混在一起。
3. 明确说明未解决项，绝不默认为符合要求：对于变更组件中需要渲染后判断的准则（对比度、焦点可见性、缩放／重排、悬停时显示的内容），要明确列为剩余风险——绝不根据源代码断言，须在渲染后的页面中通过 scan 判断。对于需要判断的准则（替代文本相关性、链接目的、阅读顺序），AI Agent 根据代码本身进行判断并记录理由——没有合理结论就不能标记状态。
4. 语言：使用对话所用的语言撰写审查内容，但技术标记始终保留英文，即使法语文本也一样——aria-live 必须保留为 aria-live（绝不译作 « région live »），tabindex、alt、role="alert" 和 landmark role 名称也一样。

1. 范围 — 审查变更内容

选择第一个适用项（仅在确实有歧义时提问）：

node scripts/ultra11y.mjs audit <files the user named> --jsx --json     # explicit files
node scripts/ultra11y.mjs audit --staged --graph --json                 # staged snapshot (pre-commit review)
node scripts/ultra11y.mjs audit --changed --graph --json                # working diff
node scripts/ultra11y.mjs audit --since origin/main --graph --json     # the whole branch (PR review) — use the repo's default branch

• 对 JSX/TSX 始终传入 --graph（使用真实 AST 和跨文件规则：未命名的纯图标组件用法、在另一个文件中定义的锚点目标等）；它还会抑制一类单文件误报。
• 传入与对话语言匹配的 --lang，使引擎的消息和修复建议使用审查所用的语言（不设置时，CLI 会自动检测——这只是备用方案，不能替代手动设置）。
• 整个仓库审查属于审计，而非审查——应改为提供 ultra11y 技能。
• 默认排除测试／故事文件标记（*.test.*、*.stories.*、__tests__/）；要包含此类文件，请显式指定文件名，或传入 --no-default-excludes。

2. 判断 — 引擎的发现是候选项，而非定论

对于每项发现（--json 会提供 criteria、severity、file:line、message、 remediation）：

• 确认问题是否存在：打开引用的行；被指出的问题元素必须确实存在于正在审查的变更中。
• preliminary: true 发现（.vue/.svelte/.astro 源文件、库组件）： 模板解析器无法识别插槽、条件逻辑或 provide/inject 连线。如果有捕获结果（位于 .ultra11y/captures，由 ultra11y 技能的 render --setup 收集器生成），请据此确认； 否则，应注明为暂定并说明这一限制，或提供代码证据予以驳回。
• 由库渲染的 JSX（DSFR、MUI……）：即使源码审查没有发现问题，最终 HTML 仍可能存在缺陷（假阴性）——如果变更涉及此类组件，请明确说明这一点，并建议检查渲染后的 DOM（使用 scan 或 ultra11y 捕获流水线）。
• 判断标准由 AI Agent 裁定：替代文本是否相关、链接目的在上下文中是否明确、可见标签与可访问名称是否一致、变更组件的键盘/焦点逻辑（应阅读完整组件源码，而非只看被标记的行），并为每项判断记录理由。
• 驳回某项发现时，必须提供引用证据（能够推翻该发现的代码）；禁止默默略过发现。

3. 报告 — 审查结果，而非合规文档

使用对话所用语言（核心规则 4），并按严重程度分组：

## Accessibility review — <scope, e.g. branch feat/x vs main, 12 files>

### 🔴 Blocking
- `src/components/Form.tsx:42` — **3.3.2 Labels or Instructions** — input has no
  label and placeholder is its only hint → associate a real <label for>, keep the
  placeholder as an example only.

### 🟠 Major / 🟡 Minor
- …same shape…

### Residual risks (rendering-dependent — resolve in the rendered page via scan)
- contrast of the new button variants (1.4.3), focus visibility on the custom menu (2.4.7)

### Verdict
1 blocking, 2 major to fix before merge; 2 provisional SFC findings to confirm on the
rendered DOM; residual risks listed above.

• 将引擎的 remediation 文本作为每项修复建议的基础——它已完成本地化，并以判断标准为依据。
• 审查过程中顺带发现的既存问题，只能放在最后一行，且不得纳入判定结果。

作为子 Agent 运行。 此技能通常由其他流程调用，而非手动输入：可能由插件钩子在待执行 git commit / git push / gh pr create 时调用，也可能由 ultra11y 技能在审计完成修复后调用。在这种情况下，上述报告就是返回值——它会作为工具结果返回给调用方，而不是发给人类的消息。因此，请原样完整返回报告，不要添加其他内容：不要加开场白，不要说“我运行了引擎并发现……”，也不要提出代为修复。调用方若收到摘要，就只能猜测具体发现；而防止这种情况正是此技能存在的目的。第 4 节中的所有操作均为可选项，且应由调用方决定，而非由你执行。

4. 审查之后（可选）

• 安全的机械修复：使用 fix --staged --write --safe（自动将安全的代码转换应用到暂存文件并重新暂存），或运行 node scripts/ultra11y.mjs fix <files> --write； 不带 --write 可试运行。
• 正式交付物（带日期的报告、审计员合规区块、PRD 待办事项、GitHub 问题、RGAA/国家标准术语）：交由 ultra11y 技能处理——使用相同的引擎和发现（report、prd、check/verify 门禁）。
• 实现自动化：安装为 Claude Code 插件后，PreToolUse 钩子会拦截包含发现的待执行 git commit / git push / gh pr create，并将这些发现交给此技能处理——无需任何人请求，即可触发此技能。针对相同发现，它不会重复触发，因此重试可以正常完成。若要设置无需 Agent 的门禁，ultra11y 技能的 init --hook 会安装机械式的提交前运行流程，对暂存内容执行同一审计。

请勿

• 捏造引擎未发现且你无法引用证据的问题。
• 根据源码断言对比度/焦点/缩放情况——在渲染前，这些都只是剩余风险（使用 scan 进行确认）。
• 将仓库中既存的问题混入对本次变更的判定结果。
• 翻译法语文本中的技术标记（aria-live，绝不要译为「实时区域」）。