ultra11y

ultra11y — 稽核 RGAA 4.1.2 並撰寫可及程式碼

在無障礙領域，自動化工具只能看到部分問題。 ultra11y 透過分工來處理這個問題：引擎（確定性、零相依，使用 node scripts/ultra11y.mjs <指令> — 無需 npm install，無需金鑰）負責機械性工作 — 偵測可機器驗證的不符合事項並歸類到正確的 RGAA 準則；您負責判斷 — 替代文字是否恰當、標題是否合於語境、閱讀順序是否正確 — 以及需要實際渲染才能驗證的準則（對比度、焦點、縮放）。防護閘可防止任何幻覺產生的不符合事項存活。

核心規則：

1. 絕不虛構不符合事項：每個 NC 都引用實際存在且可解決的元素（check 會驗證）。
2. 先原生 HTML，最後才用 ARIA；不要重複隱含的語義。
3. 殘餘風險明確列出：所有需要渲染/判斷且無法證明的準則都歸入「需人工評估」，絕不會被默認為符合。

根據情境選擇

• 「進行稽核 / 製作符合性報告」 → node scripts/ultra11y.mjs audit … --json， 然後 report，再 check；閱讀 references/audit.md。
• 「針對大型倉儲 / 聰明稽核」 → 聚焦：使用 --changed（git diff）、 優先處理模板、去重、加上 --max-files；閱讀 references/scale.md。
• 「進行修正」 → 使用 fix（預設為試執行，--write 套用安全的修正， 其餘僅建議而不會擅自新增）；閱讀 references/fix.md。
• 「在倉儲中設定自動防護（hook / CI）」 → 使用 init --hook/--ci/--baseline （只在遇到新的不符合事項時才會失敗）；閱讀 references/automation.md。
• 「讓這段程式碼可及 / 審查程式碼」 → 使用 audit - < 元件.html 稽核片段， 並遵循先原生後 ARIA 的原則；閱讀 references/authoring.md 和 references/forbidden-patterns.md。
• 「查詢某個準則的意義 / 某個主題」 → 使用 criteria；參閱 references/criteria.md。
• 「國際標準閱讀（WCAG / EN 301 549 / Section 508）」 → 在 report/criteria 使用 --standard wcag；參閱 references/methodology.md。
• 「高保證度稽核」 → 使用 verify --report … --semantic；參閱 references/verify.md。方法論與格式：references/methodology.md。
• 「檢查對比度 / 渲染（選用 Docker 層）」 → 使用 scan <url> --merge … （在無頭瀏覽器中使用 axe-core）；參閱 references/dynamic.md。

指令速查表

node scripts/ultra11y.mjs audit "src/**/*.html" --json > audit.json
node scripts/ultra11y.mjs audit - < 元件.html        # 從標準輸入讀取 HTML
node scripts/ultra11y.mjs audit "src/**/*.tsx" --jsx       # 盡量支援 JSX/TSX
node scripts/ultra11y.mjs audit --changed --json           # 僅稽核 git diff（大型倉儲）
node scripts/ultra11y.mjs report --in audit.json --out audits
node scripts/ultra11y.mjs report --in audit.json --standard wcag   # WCAG 檢視（簡報用）
node scripts/ultra11y.mjs criteria 11.1                    # 查詢單一準則及其測試
node scripts/ultra11y.mjs criteria --theme 8 --list        # 查詢某個主題 / 列出所有準則
node scripts/ultra11y.mjs check  --report audits/rgaa-AAAA-MM-JJ.md
node scripts/ultra11y.mjs verify --report audits/rgaa-AAAA-MM-JJ.md --semantic
node scripts/ultra11y.mjs fix "src/**/*.html"              # 試執行；加上 --write 才套用
node scripts/ultra11y.mjs init --hook --baseline           # 回歸防護（hook + baseline）
node scripts/ultra11y.mjs scan https://example.fr --merge audits/audit-latest.json  # Docker 層

所有指令搭配 --json 都有機器可讀輸出。報告預設為法文，支援 --lang en。

組合引擎、判斷與殘餘風險

audit 輸出會將每個準則分類：靜態子集為 C/NC/NA；需要渲染/判斷的準則歸為 manual（列在 residualRisks 中）。引擎產生的 NC 是確認的候選事項（會標註 檔案:行號）。您需要裁決 manual 類別的準則，並標記需要渲染的準則為「需人工驗證」。只有當每個適用的準則都有合理的 C/NC/NA 歸類，且每個殘餘風險都已命名時，報告才算完整。

禁止事項

• 虛構引擎未發現、且您也無法親眼驗證的不符合事項（對於程式碼中直接寫死的顏色，對比度可在靜態階段判斷；計算後的對比度 — 來自外部 CSS、變數 — 需透過 scan（Docker 層）或在渲染後驗證才能宣告）。
• 新增會重複原生語義的 ARIA。
• 未經人工驗證就將需要渲染/判斷的準則標記為「符合」。
• 手動編輯 references/criteria.md（該檔案是從官方參考資料庫自動生成的）。

適用範圍

靜態引擎：離線、確定性、零相依；接受 HTML + JSX/TSX（盡量支援）+ 標準輸入。渲染相關準則（計算對比度、reflow）由選用的 scan 層（Docker 中的 axe-core）處理；可見焦點、文字放大 200% 以及懸浮內容仍需人工審查（列為殘餘風險）。資料來源：RGAA 4.1.2 © DINUM，使用 Licence Ouverte / Etalab 2.0（詳見 NOTICE）。