Community程式設計與開發github.com

bbb-a11y-audit

審計 BigBlueButton HTML5 客戶端是否符合 WCAG 2.2 等級 A 和 AA(EN 301 549 第 9 條),一次一個主題(指南、原則或準則)或整個客戶端,並生成按原則、指南和準則組織的 HTML 報告,每個準則以失敗、通過或不適用結尾,附有證據、標註截圖、修復建議和優先級。

bbb-a11y-audit 是什麼?

這個技能提供了一個完整的可及性審計工作流程,專門用於 BigBlueButton HTML5 客戶端。它結合了靜態掃描、使用 axe-core/Playwright 對即時會議的動態測試,以及引導式程式碼審查,以識別 WCAG 2.2 等級 A 和 AA(EN 301 549 第 9 條)的違規情況。審計是唯讀的,不會修改應用程式程式碼;使用者可以按主題(例如單個指南、原則或準則)或完整審計所有 55 個準則來審計。該技能支援多種模式:guideline、criterion、full、path 和 diff,並包含一個運行時層,用於在實際 BigBlueButton 會議中測試。產出物是一個詳細的 HTML 報告,按原則、指南和準則組織,每個準則都標記為失敗、通過或不適用,並附有證據、標註截圖、修復建議和優先級。它還會將當前結果與同一主題的先前運行進行比較,以追蹤進度並確保一致性。此技能適用於 Claude Code、Cursor 或 Codex 等 AI 代理,用於開發、維護或稽核 BigBlueButton 的可及性。

相容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/gugeldev/bbb-a11y-audit/tree/main/bbb-a11y-audit

Installed? Explore more 程式設計與開發 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

無障礙審計 (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 或 fullfull所有 55 個準則(概覽/地圖)
/bbb-a11y-audit <path>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"]),並且在每個層級中,只查看可以為主題提供資訊的內容(每個步驟下面都說明了如何操作)。主題之外的準則會自動排除。

一致性規則(審計前閱讀)

對相同程式碼的兩次運行必須得出相同的結果,並且每個發現都必須是真實的。因此:

  1. 從上一次運行開始。 在尋找任何新內容之前,打開此主題最新運行(或最新完整運行)的 findings.json。針對當前程式碼重新檢查每個先前的發現和每個 discarded 條目:仍然存在 → 保留其 key(或設定其 id);已消失 → 它不是一個發現,並在 meta.summary 中說明它為何消失(程式碼已更改,或者它是錯誤的)。如果提交與該運行的提交相同,並且一個發現似乎已消失,則假設您遺漏了它,並在將其刪除之前再次查看。
  2. 回答檢查表,然後探索。 如果 references/checklists.json 具有範圍內準則的項目,請回答每個項目:pass、fail 或 na,並附上證據(coverage[c].checklist)。檢查表是下限,而不是上限:然後尋找其他可能導致 BBB 中該準則失敗的內容,並將您尋找的內容寫入 coverage[c].explored。您在檢查表之外發現的重複性問題值得在最終訊息中提議作為新的檢查表項目。
  3. 證明每個發現。 靜態和審查發現帶有 quote,即 location.line 處的確切程式碼;build-report.mjs 會拒絕檔案、行或引號不存在的發現。運行時發現指向它們來自的規則和畫面(shots)。沒有證據,就沒有發現。
  4. 不要填充。 一個發現對應一個修復;合併重複項;不要為使清單更長而拆分問題,也不要報告不會導致準則失敗的樣式偏好或最佳實踐。如有疑問,請再次檢查;如果仍然不清楚,請編寫螢幕閱讀器腳本而不是發現。

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):然後 spec 會跳過無法為主題提供資訊的檢查和情境,並僅使用主題的規則執行 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:它們構成「已測試內容」標籤頁,告訴讀者確切檢查了什麼以及未檢查什麼。

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 準則一個任務)。除非被要求,否則不要開啟問題或 PR。

安全性: 如果一個發現可能被利用(例如在檢查 3.3.8 時發現的認證繞過),則將其排除在報告之外,並私下告知使用者遵循儲存庫的安全策略(私人建議,不要公開問題或 PR)。

相關技能