无障碍审计 (WCAG 2.2 AA)
为所选主题生成一份真实的无障碍问题列表,这些问题可以转化为小任务并在当前阶段修复。审计是只读的:审计期间不要修改应用代码,即使是明显的修复。修复是单独的请求。
技能目录:包含此 SKILL.md 的文件夹(以下称为 $SKILL;在此仓库中通常为 .claude/skills/bbb-a11y-audit)。参考文件在步骤需要时读取:
references/criteria.md:55 条标准,每层能够评估哪些标准、BBB 热点、覆盖规则references/rubric.md:影响、工作量、此阶段还是待办、分组、稳定键、findings.input.json模式references/static-patterns.md:静态工具、如何分类每种模式、eslint 和 axe 映射references/bbb-map.md:流程、代码位置、共享组件、如何运行运行时层references/manual-checks.md:屏幕阅读器脚本runtime/:运行时层,首次使用时安装到 BigBlueButton Playwright 套件中:wcagAudit.spec.ts(场景)、wcagAuditRecorder.ts(axe、截图、每个场景一个 JSON)、wcagAuditChecks.ts(键盘、回流、文本间距、工具提示、焦点返回、ARIA 状态)和wcagAuditAnnouncements.ts(记录到达活动区域的内容)
1. 范围与模式
正常的工作方式是一次一个主题:选择一个准则,审计其中的所有内容,修复发现的问题,再次审计直到完成,然后进入下一个。完整审计是用于选择下一个主题的偶尔性概览。
| 调用方式 | 模式 | 范围 |
|---|---|---|
/bbb-a11y-audit diretriz 2.1(或 guideline;多个:diretriz 2.1 2.4;整个原则:principio 2) | guideline | 主题对应的每条标准,覆盖整个客户端和所有流程,完全决定。本次运行和报告中排除其他所有内容。 |
/bbb-a11y-audit criterio 2.4.7(或 criterion) | criterion | 一条或多条标准,相同深度 |
/bbb-a11y-audit 或 full | full | 全部 55 条标准(概览/地图) |
/bbb-a11y-audit <路径> | path | 该文件夹或文件,所有标准 |
/bbb-a11y-audit diff [base] | diff | 与 git merge-base HEAD <base>(默认 base:仓库主分支 v4.1.x-develop)相比,bigbluebutton-html5/ 下已更改的文件 |
添加 --no-runtime | 跳过运行时层 | |
添加 --server <url> --secret <secret> | 针对另一个 BigBlueButton 测试服务器运行运行时层,而非 bigbluebutton-tests/playwright/.env 中的服务器(<url> 格式如 https://host/bigbluebutton/) |
如果请求不明确,选择最接近的模式并说明使用了哪个。不要询问。
在仓库根目录创建运行目录:a11y-reports/<YYYY-MM-DD_HHMM>[_<topic>]/raw/,例如 2026-11-20_1430_d2.1 或 2026-11-20_1500_full。目录名必须以日期和时间开头:报告会与同主题(即相同的标准,无论如何请求,例如 principio 4 和 diretriz 4.1 是同一主题)的旧运行进行比较,或者首次运行时,与该主题的最新完整运行进行比较。审计不得在仓库中留下痕迹:如果 git check-ignore -q a11y-reports/ 失败,则将 a11y-reports/ 添加到 .git/info/exclude(仅针对此克隆,切勿添加到 .gitignore)。
在 guideline 和 criterion 模式下,在 findings.input.json 中设置 meta.guidelines / meta.criteria(原则是单位数字的准则条目:principio 2 为 "guidelines": ["2"]),并且每一层只关注能够为该主题提供信息的内容(以下每个步骤都有说明)。主题外的标准自动排除。
一致性规则(审计前阅读)
同一代码的两次运行必须得到相同结果,并且每个发现必须是真实的。因此:
- 从上次运行开始。 在寻找任何新内容之前,打开此主题(或最新完整运行)的最新运行的
findings.json。对照当前代码重新检查每个先前的发现和每个discarded条目:仍然存在 → 保留其key(或设置其id);已消失 → 它不是发现,并在meta.summary中说明消失原因(代码已更改,或之前判断错误)。如果提交与该运行的meta.commit相同,并且某个发现似乎消失了,假设你错过了它,在放弃之前再次查找。 - 回答检查清单,然后探索。 如果
references/checklists.json中有针对范围内标准的项目,用pass、fail或na回答每个项目,并提供证据(coverage[c].checklist)。检查清单是基础,不是上限:然后查找在 BBB 中可能导致该标准失败的任何其他内容,并在coverage[c].explored中写下你查找的内容。你在清单外发现的重复性问题值得在最终消息中提议作为新的检查清单项目。 - 证明每个发现。 静态和审查发现带有
quote、location.line处的确切代码;build-report.mjs会拒绝文件、行或引用不存在的发现。运行时发现指向它们来自的规则和屏幕(shots)。没有证据,就没有发现。 - 不填充。 一个发现对应一个修复;合并重复项;不要为了让列表更长而拆分问题,也不要报告不会导致标准失败的样式偏好或最佳实践。如有疑问,再次检查;如果仍然不清楚,改为编写屏幕阅读器脚本而不是发现。
2. 静态层
node $SKILL/scripts/static-scan.mjs [--guidelines=2.1] <scope paths...> > <run>/raw/static.json
$SKILL/scripts/eslint-a11y.sh <run>/raw/eslint.json <scope paths...>
有主题时,将 --guidelines 传递给扫描(它只保留主题的模式),并且只分类其规则映射到主题的 eslint 消息(references/static-patterns.md)。
然后按照 references/static-patterns.md 中的描述对每个候选进行分类:打开代码,决定,按根本原因分组。被拒绝的候选进入 discarded 并附上理由。如果存在上次运行,读取其 findings.json 中的 discarded 列表,并对未更改的代码重用决定,而不是重新读取。
3. 运行时层
首先确保运行时文件已安装,按照 references/bbb-map.md 中的“设置运行时层”进行:$SKILL/runtime/ 中的每个文件必须在 BigBlueButton Playwright 套件中,并且 @axe-core/playwright 在其依赖中。复制它们并安装包是设置,不是对应用程序的代码更改;当它们缺失或过期时执行此操作,并在最终消息中提及。
使用 --server/--secret 时,将它们作为 BBB_URL 和 BBB_SECRET 环境变量传递给 Playwright 命令(它们优先于 .env;切勿将它们写入 .env)。报告记录被审计的服务器及其客户端构建(meta.server);如果该构建不是本地检出版本的提交,则在 meta.summary 中说明运行时发现来自该服务器版本,并且它们的文件和行引用指向可能不同的本地代码。
然后检查它是否可以运行(bigbluebutton-tests/playwright/.env 或 --server/--secret 提供了非空的 BBB_URL 和 BBB_SECRET,node_modules 存在,Chromium 已安装)。如果缺少任何内容,跳过该层,记录 "ran": false 并附上简短 reason,然后在最终消息中明确告诉用户需要设置什么。不要尝试安装 BigBlueButton 服务器或编辑 .env。
当可以运行时,按照 references/bbb-map.md 中的“运行运行时层”进行,使用 A11Y_AUDIT_DIR=<abs run dir>/raw/runtime,以及在主题模式下添加 A11Y_GUIDELINES=<topic>(例如 2.1):规范随后跳过无法为该主题提供信息的检查和场景,并且仅使用主题的规则运行 axe。完整运行:在远程服务器上大约 15 分钟;主题通常更快。允许 30 分钟。它运行九个场景(主持人导览、主持人+参会者交互、分组讨论、嘉宾等候室、预启动设置屏幕、连接丢失、pt-BR、深色主题、移动端)并为每个场景写入一个 JSON 以及每个状态的截图。然后:
- 通过
wcag...标签将每个 axe 违规映射到其标准。跨状态和场景按规则和根本原因分组(在许多状态中的相同规则通常是一个发现)。将选择器追溯到源文件。 - 将
incomplete和自定义检查(keyboard.noOutlineOrShadow、keyboard.obscured、reflow.offenders、textSpacing.newlyClipped、nonTextContrast)视为候选:在报告前确认。被拒绝的进入discarded。 - 读取
announcements(每个参与者、每个时刻到达活动区域的内容)用于 4.1.3 和 4.1.2:在预期有通知但没有的时刻(有人离开、投票开始)是一个候选;regionCreatedWithMessage: true表示区域在插入时带有其文本,可能不会被读取。 - 查看有发现的状态的截图(
raw/runtime/shots/),并将shots附加到发现(参见references/rubric.md),以便报告显示每个问题的位置。 - 状态为
ok: false或检查出错表示未被审计。将其列在meta.notCovered下;不要因此将其标准标记为pass。
在 diff 和 path 模式下,仅保留追溯到范围内代码的运行时发现。
4. 引导式审查
对于 references/criteria.md 中标有 V 且范围内的标准,读取 references/bbb-map.md 中相关流程的代码,直到每条标准被决定。在 full 模式下从核心流程开始;在 guideline 和 criterion 模式下,针对范围内的标准遍历 bbb-map.md 中的每个流程。在 meta.reviewedFlows 中列出你读取的内容。每个审查发现都需要文件和行证据;当你无法通过运行来确认行为时,使用 "confidence": "likely" 并说明需要确认什么。
不要报告你无法指向的内容。如果某些内容只能由人工确认,编写一个脚本(references/manual-checks.md);如果可以通读更多代码或运行时数据来确认,则改为那样做。
5. 分类、覆盖、脚本
- 使用
references/rubric.md对每个发现进行分类(影响、工作量、共享、外部、键)。 - 在运行之间保持 ID 稳定(一致性规则 1):对于仍然存在的每个问题,重用先前的
key,或显式设置id。 - 为每个未失败且在范围内的标准填写
coverage(并将method/how也添加到失败的标准中),遵循references/criteria.md中的覆盖规则:pass或na附带method和how,human仅用于真正需要人工判断的内容(附带其脚本),not-covered仅当本次运行无法决定时(附带缺少的内容)。目标是每个准则可以关闭,不留任何未解决的问题;build-report.mjs拒绝缺少的条目。 - 仅针对自动化无法回答的内容编写
manualChecks:每个human标准对应一个。如果你想用真实的屏幕阅读器确认运行时已经决定的内容,添加"optional": true;切勿为运行时数据或代码可以决定的内容编写脚本(状态更改、通知、倒计时、设备选择都已记录)。 - 填写
meta.summary、meta.reviewedFlows和meta.notCovered:它们构成“O que foi testado”选项卡,告诉读者确切检查了什么和没有检查什么。
6. 构建报告
写入 <run>/raw/findings.input.json(模式见 references/rubric.md),然后:
node $SKILL/scripts/build-report.mjs <run>
它会验证输入(如果报错则修复并重新运行),分配稳定 ID,将每个发现放入此阶段或待办中,添加 EN 301 549 条款,检查每个文件、行和引用是否存在,检查每个检查清单项目是否已回答,记录与上次运行的比较到 findings.json(供下次运行使用;报告不显示它),并写入 <run>/findings.json 和 <run>/report.html。为用户打开报告(Linux 上使用 xdg-open,macOS 上使用 open)。
7. 告知用户
保持聊天消息简短;报告包含详细信息:
- 结论,哪些标准通过、哪些失败,此阶段有多少发现,以及多少进入待办(附原因)
- 按准则:已完成、多少标准失败,或什么仍然未解决(
human、not-covered) - 哪些层运行了、哪些被跳过及原因、哪些会议状态或流程未被覆盖
- 阻塞性和高影响发现,每行一条(标题、标准、文件)
- 如果探索发现清单外的重复性问题,提议新的检查清单项目
- 报告的路径
提供将发现转化为任务的选项,按准则分组(每个准则一个阶段,每个发现一个任务,加上每个 human 标准一个任务)。除非被要求,否则不要开启 issue 或 PR。
安全性: 如果某个发现可能被利用(例如在检查 3.3.8 时发现的认证绕过),将其从报告中排除,并私下告知用户遵循仓库安全策略(私有公告,不要公开 issue 或 PR)。