ultra11y — 審計 WCAG 2.2 AA 並撰寫無障礙標記
關於無障礙，自動化工具只能看到問題的一部分。ultra11y 透過分工來解決這個問題：確定性、無需安裝的引擎（node scripts/ultra11y.mjs <command> — 無需 npm install，無需金鑰；JSX/TSX 解析器已嵌入在套件中）負責執行機械化工作 — 檢測可透過機器檢查的不合規項，並將其連結到對應的 WCAG 成功標準 — 而主動編碼代理則負責裁決判斷標準本身 — 如替代文字的相關性、連結在上下文中的目的、閱讀順序 — 它會根據引擎收集的證據進行靜態分析（verify --manual），每個裁決結果都經過 verify/check 關卡的驗證。只有那些真正涉及渲染後 DOM 的標準（如計算後的對比度、可見焦點、縮放/重排、懸停內容）才會落在 scan 層級（使用真實瀏覽器中的 axe-core）；人類最多只是可選的監督角色。這些關卡可以阻止任何幻覺產生的不合規項存活下來，並且永遠不會有默默「符合」的情況。
不要混淆規則與標準。 該套件包含 93 項靜態檢查，WCAG AA 有 55 個成功標準，而 RGAA 有 106 個標準。多個規則可能指向同一個標準，一個規則可能貢獻給多個套件標準，且大多數標準在掃描或裁決之前仍保持開放狀態。唯一誠實的運行層級覆蓋率是網格中即時的來源統計（moteur + scan + agent，加上任何命名的不可判定殘留項），絕不是像「48 個代理標準」這樣的固定承諾。因此，GitHub 摘要顯示的是 已決定/總數，而不是針對已決定子集的百分比。
WCAG 2.2 Level AA 是全球核心。 各國標準 — 法國的 RGAA、美國的 Section 508、歐盟的 EN 301 549 — 都是可插拔的標準套件，將其標準映射到 WCAG。添加 --standard rgaa 可以重新設定每個命令和每個輸出的鍵值 — 包括 audit 及其結果；使用 --pack ./pack.json（或 .ultra11yrc.json 檔案）在運行時插入外部套件，無需重建；或者貢獻您自己國家的標準（請參閱 references/standards.md）。這些套件（及其具體的實作指南 — RGAA SocialGouv/etalab 的好/壞模式）可以被 AI 吸收，並經由 pack check 進行門控，以防止偽造的映射通過 — 請參閱 references/packs.md 和 references/guidance.md。
大部分工作是您的。 在 55 個 WCAG 2.2 AA 成功標準中，引擎可以直接判定 3 個；14 個需要渲染後的頁面（scan），而 38 個是代理需要裁決的判斷項目。因此，引擎的乾淨運行只是一個起點，絕非最終裁決 — 而 references/adjudication.md 是您實際要工作的頁面。
核心規則：
- 永遠不要發明不符合項：每個
NC都必須引用一個真實、可解析的元素（check會驗證它）。- 原生 HTML 優先，ARIA 最後；永遠不要重複隱含語義。
- 永遠不要發明符合項：一個
C的引用方式與NC完全相同 — 它在citations[]中列出它所清除的已收集證據，每個錨點都可解析且來自該標準實際被展示的證據。一個沒有證據就呈現的標準根本不能為C；它必須保持manual。同樣地，如果其讀取狀態為 INCOMPLETE（evidenceComplete: false），也不能為C：一個您只看到部分證據的標準，您可以基於所見內容判定它失敗，但絕不能因為您沒看到的內容就判定它通過。並且，經裁決的C永遠不會與引擎決定的C合併：報告會將其分開列出，並將其排除在自動通過率之外。 3b. 您所看到的內容是整個群體，每個不同的事物只出現一次。 證據是每個內容類別的一個代表，帶有occurrences、其他錨點位於alsoAt，以及它出現的pages— 跨 38 個捕獲頁面的 887 個連結是 97 個不同的（text, href）配對。對代表做出裁決即等同於對所有連結做出裁決，這正是達成誠實C的基礎；而引用該標準所攜帶任何類別的任何出現次數的引用都是可接受的，因此請引用您實際打開的那個。- 殘留項是明確的，絕不默默符合：AI 代理自行裁決每個判斷標準（
verify --manual，經門控），而渲染標準則交給scan— 當承載某標準的每個規則都在範圍內的每個頁面上執行且沒有引發任何問題時，scan現在會得出C（decidedBy: "scan"）的結論；而當即使只有一個頁面的訊號不完整時，它會保持沉默。任何仍未確定的標準都會保持「待人工評估」狀態 — 沒有狀態是沒有記錄的、有正當理由的裁決。為了使其成為一個門檻而非一個希望，check --in <audit.json> --require-decided在仍有任何項目待評估時會失敗，而--allow-undecided <file>則接受您確實無法決定的標準，每個標準都附有其理由（一個命名的列表，不是一個門檻）。--require-decided=pages將每個頁面自己的網格都置於相同的標準下：一個在一個路徑上失敗的標準，對於該運行而言是已確定的，但對於它從未觸發過的路徑來說，可能仍然不是任何人的裁決，而每個頁面的交付物正是根據這些路徑來評判的。 發出的工作清單是權威的。 它可能故意包含一個運行範圍內狀態已經是NC的標準，因為該失敗並未決定該標準在其他頁面上的狀態。這樣的項目並非冗餘：為它返回一個有根據的裁決（或一個明確的manual理由），永遠不要因為全局統計看起來已經決定就留空。- 查閱標準；永遠不要憑記憶。
criteria [--standard <pack>] <id>— 或透過 MCP 使用ultra11y_criteria— 會返回標準本身的措辭、其編號測試，以及這些測試所引用的詞彙表定義。RGAA 8.3 不是「頁面需要一個lang屬性」；它是測試8.3.1，包含兩個替代條件，而詞彙表決定其術語的含義。一個在閱讀後引用8.3.1的審計區塊是有根據的；一個憑記憶引用的則是穿著引用外衣的猜測。在針對某國標準進行審計之前，請先執行計畫（ultra11y_method）：它會告訴您還有多少標準需要裁決才能獲得 C — 對於 RGAA，106 個中有 104 個。請參閱references/mcp.md。- 最終渲染的語義 HTML 必須正確。 引擎只看到原始碼；一個元件庫（DSFR/MUI…）或
.vue/.svelte/.astroSFC 隱藏了真實的標記，因此綠色的原始碼審計並非證明。請驗證生成的語義 HTML — 安裝零接觸的捕獲收集器（render --setup），以便您的測試渲染的每個元件都被序列化到.ultra11y/captures並進行審計，並使用audit --require-captures門控來處理盲點。請參閱references/automation.md/references/rendered.md。- 語言：始終傳遞
--lang，使其與您與使用者對話的語言匹配；在有歧義時詢問使用者。如果沒有該標誌，CLI 會自動檢測（儲存庫<html lang>→ 啟用標準的預設語言環境 → 英文） — 這是一個腳本/CI 的備案，不能取代您自己傳遞--lang。- 技術標記保持英文，即使在法語散文中也是如此。 在您撰寫的任何法語交付物（報告評論、PRD、追蹤器工單、判斷裁決）中，屬性/元素/角色名稱及其值是程式碼，而非散文 — 永遠不要翻譯它們：
aria-live保持為aria-live（永遠不要寫成「région live」），tabindex、alt、role="alert"、地標角色名稱也是如此。引擎自己的法語目錄遵循此規則；請與之匹配。規範性標準詞彙（RGAA 措辭，例如 « lien d'évitement »）保留其官方法語。
參考資料庫
先了解領域知識，再了解工具。閱讀與您當前問題相匹配的資料。
| 無障礙知識 | |
|---|---|
references/adjudication.md | 如何決定引擎交給您的 52 個標準中的每一個 — 決策規則，何時 NA 是合法的，問題 |
references/naming.md | 無障礙名稱計算，2.5.3 名稱中的標籤，視覺隱藏 CSS，為圖片/SVG/圖形命名 |
references/widgets.md | ARIA APG 複合模式，鍵盤合約，焦點管理，SPA 路由變更，動態區域 |
references/forms-and-errors.md | 標籤與說明，autocomplete 代碼列表，錯誤識別/建議/預防，冗餘輸入，無障礙驗證 |
references/structure.md | 標題，地標，列表與 dl，簡單與複雜表格，有意義的順序 |
references/media-and-motion.md | 字幕/口述影像/逐字稿，指標手勢，目標大小，方向，重排，減少動畫 |
references/forbidden-patterns.md | 15 個反模式：錯誤 → 原因 → 原生修復 → 標準 |
references/focus-and-logic.md | 您擁有的焦點/鍵盤標準，以及如何推理它們 |
references/criteria.md | 55 個標準：等級，自動化類別，引擎規則，套件映射（已生成） |
references/rgaa-automation.md | RGAA 4.1.2：已生成的 106 個標準 / 258 個測試矩陣，決定性規則，候選訊號與靜默策略 |
references/act.md | 引擎被測量到能捕獲什麼 — 以及它明顯不能捕獲什麼（已生成） |
| 執行工具 | |
|---|---|
references/runbook.md | 可靠運行：一個配方，要使用的傳輸方式及原因，以及一次通過的成本。在為裁決付費之前請先閱讀此文件 |
references/claude-code-report.md | Claude Code 的詳細發布路徑：渲染範圍，直接裁決，對抗性驗證，Markdown + HTML + 每頁證據 |
references/audit.md | 端到端的審計循環，以及規範性頁面樣本 |
references/judgment.md | 裁決 + 駁斥工作清單，裁決詞彙，故障封閉折疊 |
references/verify.md | check/verify 門控 |
references/false-positives.md | 發現結果仍可能錯誤的地方，以及如何駁斥它 |
references/rendered.md · references/automation.md | 審計生成的 HTML、捕獲、鉤子和 CI |
references/harnesses.md | 運行環境：Claude Code、Codex CLI、OpenCode 和 AGENTS.md 備案 |
references/orchestrators.md | 從工作流引擎 / 非 GitHub CI 驅動引擎：固定版本、六步驟管線、退出碼、以 JSON 形式為任何追蹤器提供的工單集 |
references/ci.md | `--format sarif |
references/pages.md | 頁面快照 + 每頁標準網格（pages），及其誠實規則 |
references/e2e.md | render --e2e：在 Playwright/Cypress 運行期間審計頁面 |
references/devtools.md | dev：您在開發時的即時疊加層，以及每頁儀表板 |
references/extension.md | 瀏覽器擴充功能：透過 side-car 審計您正在查看的頁面 |
references/dynamic.md | scan 層級：運行時、探針、已認證頁面 |
references/scale.md | 在大型儲存庫上聚焦審計 |
references/fix.md · references/correction.md | 按優先級應用修復，無回歸 |
references/prd.md | 作為待辦事項清單（markdown）的審計區塊 |
references/tickets.md | 將該待辦事項清單歸檔為工單：GitHub、GitLab、Jira 以及粒度 |
references/standards.md · references/packs.md · references/guidance.md | 國家標準，撰寫套件，實作指南 |
references/mcp.md | 作為規則引擎的標準：查閱標準而非憑記憶回憶 — 其編號測試、其定義的術語、修復方法以及工作計畫。作為 MCP 工具和 std:// 資源，或 CLI 上的相同資料 |
references/methodology.md | 狀態、通過率、嚴重性、報告格式 |
references/cross-file.md | --graph：導入和跨檔案規則 |
references/orchestration.md | 將判斷階段分配給子代理 |
依情境選擇
- 「在 Claude Code 中產出詳細的審計/報告」 → 將活動中的 Claude 會話用作審計員，關閉渲染和判斷標準，挑戰其主張，然後發布帶日期的 Markdown 報告、可列印的 HTML 和有證據支援的每頁檔案。閱讀
references/claude-code-report.md。這是互動式發布設定檔；以其完整的交付物集完成。緊湊摘要見下方 CI 分支。 - 「審計 / 合規報告」 →
node scripts/ultra11y.mjs audit … --json，然後report（匯總表 + 每個 NC 標準一個審計員合規區塊 — 與prd和tickets使用的區塊相同），然後check；閱讀references/audit.md。 - 「由庫（DSFR、MUI…）或
.vue/.svelte/.astroSFC 渲染的程式碼 / 避免假陰性」 → 審計生成的 HTML，而非原始碼模板。最簡單的方法：安裝零接觸的捕獲收集器（render --setup），以便您的測試將每個渲染的元件序列化到.ultra11y/captures（自動吸收，發現結果歸因於原始元件；render --coverage和audit --require-captures追蹤盲點）。或者執行render（建置→審計配方或 SSR 快照--scaffold），然後對輸出執行audit，再執行scan以進行計算後的渲染。SFC 原始碼的發現結果會被標記為preliminary（一個scope.sourceTemplate警告）；閱讀references/rendered.md。 - 「發現結果看起來不對 / 元件的假陽性」 → 引擎會自動抑制大多數元件的假陽性（插槽/屬性注入的名稱、元件子項、動態綁定、條件式標題），並將 SFC/庫原始碼的發現結果標記為
preliminary；使用verify --apply確認或駁斥其餘部分；閱讀references/false-positives.md。 - 「大型儲存庫 / 智慧審計」 → 聚焦：
--changed（git diff）、模板優先級排序、去重、--max-files；閱讀references/scale.md。 - 「跨檔案分析（樹狀結構 + 依賴關係），JSX/TSX 作為真實 AST」 →
audit --graph解析匯入並套用跨檔案規則