把自己的無障礙報告攤給你看：我們造了一個給 AI Agent 用的掃描器

你看過幾家顧問公司公開自己網站的無障礙健檢報告？

通常你會看到的是——「我們已通過 AAA 標章」、然後一張證書貼上去，沒了。沒人告訴你過程裡修了什麼、哪裡卡住、現在還有哪些懸而未決。

這篇文章我們做相反的事：把睞特官網的真實健檢報告，全部攤開給你看。

我們還沒拿標章，但工具先做、報告先攤——這篇文章順便聊我們為什麼自己造了一個給 AI Agent 用的無障礙掃描器，叫 a11y-moda。

為什麼自己造一個工具？

政府已經有官方工具叫 Freego——點開網頁、輸入網址、報告生出來。它做得很完整，但設計上是給「人」用的——你要坐在電腦前手動操作，看完報告自己回去改 code，改完再點一次。

我們的痛點不是 Freego 不好，是我們不想用人去跑這個迴圈。

睞特日常開發 90% 是 Claude Code、Cursor 這類 AI Agent 在主導。我們想要的工作流是這樣：

• Agent 跑掃描，吐 JSON
• Agent 自己讀 JSON、grep 規則 ID（例如 GN2140300E）
• Agent 自己改 code（alt 文字、對比度、aria 屬性）
• Agent 再跑一次掃描，看哪些 info 被收斂了
• 收斂到剩人工才能判的部分，才把人叫進來

這個迴圈裡，人只在最後一公里出場。前面 80% 的修正，Agent 自己跑得起來。

為了這個工作流，我們在 a11y-moda 做了幾個關鍵的設計選擇：

• JSON 結構化輸出——不是給人看的 PDF，是給 Agent 解析的
• 規則 ID 穩定——Agent 可以靠 ID 對應到 MODA 規則和 WCAG 條款，不用看自然語言描述
• Caveat 誠實標示——工具判不出來的時候，明確說「我判不了，請人看」，而不是給個假分數

最後一條最重要——稍後你會看到，這就是我們網站 7 個 caveat 的故事。

睞特官網的真實報告——28 頁、0 fail、454 info、7 caveat

先看數字：

• 掃描頁數：28 頁（首頁、關於、方案、聯絡、案例、20 篇部落格⋯⋯）
• 🔴 fail：0
• 🟡 info：454
• ⚠️ caveat：7
• 等級：AAA（最嚴格）

如果只看「0 fail」這個數字，你會以為我們已經 AAA 滿分。但這是誤讀。

自動規則 0 fail，意思是「機器能驗的那些條目都過了」。但 AAA 標準裡有大量規則需要人工複核——例如「連結文字是否清楚表達目的地」「標題是否描述內容」「色彩是否傳達唯一資訊」——這些是 454 info 的本質。

Top 5 最多 info 的條目：

• 2.4.4 連結用途：168 處（連結文字描述夠不夠精確）
• 1.4.10 reflow：60 處（縮放到 320px 是否還能用）
• 1.4.11 非文字對比：30 處（按鈕、圖示對比）
• 1.4.12 文字間距：28 處
• 1.4.3 文字對比：22 處 + 3 caveat

報告我們提供三種視角——

• by-rule：依規則分類，給開發者用——「2.4.4 在哪 28 頁出現？」
• by-WCAG：依 WCAG 條款分類，給法遵或 QA 用——「我們 Level AAA 還差什麼？」
• by-URL：依頁面分類，給設計師或老闆用——「這個首頁有哪些待辦？」

同一份資料三種讀法，因為三種角色關心的事情不一樣。

三條真實修正記憶

這份報告不是憑空長出來的——背後是一個一個 commit 修出來的。挑三條最有故事的給你看：

修正 1：「了解更多」全面下架（2.4.4 連結用途）

我們網站第一版有 168 個地方寫「了解更多」、「點這裡」、「看詳情」這種空洞連結文字。

這在視覺上沒問題，但對螢幕閱讀器使用者是災難——他們聽到的是「了解更多」「了解更多」「了解更多」連續 168 次，沒人知道每個連結到底連去哪。

這條我們交給 Claude Code 做：讀 JSON 報告、grep 規則 GN1240401E、把每個「了解更多」改成有意義的連結文字。例如：

• 「了解更多」 → 「了解我們的訂閱方案」
• 「點這裡」 → 「閱讀完整案例研究」
• 「看詳情」 → 「查看醫療排班系統的開發過程」

Agent 一輪掃下來，168 處變 0 處，再跑掃描——這條規則的 fail 全部收斂掉。

修正 2：漸層背景的對比 caveat（1.4.3 / 1.4.6）

我們有 6 個 caveat 來自同一件事——漸層背景。

工具的回應是這樣寫的：「對比無法量測（gradient bg on ancestor）— 共 12 處需人工 review」。

為什麼工具放棄量測？因為漸層每個位置顏色都不同——上邊是粉色、下邊是紫色、中間是過渡色——沒有單一背景色可以拿來算對比。如果工具硬給一個分數，這個分數就是假的。

a11y-moda 的設計選擇是：誠實說「我判不出來」，而不是掰一個分數出來。然後在報告裡明確列出「12 處需人工 review」、附上 CSS selector，讓人或 Agent 知道該去哪確認。

這個設計選擇對 Agent 協作特別重要——Agent 看到 caveat 就知道「這條我不該自己決定」，會主動把問題拋回給人。比起「給個假分數讓 Agent 誤以為過了」，這個設計才是負責任的工具。

我們真的去看了那 12 處——多數是案例頁的「導入後」標籤、案例卡標題。修法是給文字底層加一個半透明 mask，這樣對比基準從「漸層」變成「純色 mask」，工具下次掃就能量測。

修正 3：alt 文字從「圖片」到具體描述（1.1.1）

這條最基本，但最容易掉以輕心。

我們網站有 100 多張圖片，第一版掃出 10 處 alt 不及格。例如有些圖片寫 alt="圖片"、alt="banner"、alt="image"——這等於沒寫。

正確的 alt 應該描述這張圖傳達的訊息，不是描述「這是一張圖」。例如：

• ❌ alt="圖片"
• ✅ alt="老闆腦中三個聲音同時拉扯——回收、方向、拍板"
• ❌ alt="banner"
• ✅ alt="一個人用 AI 工具同時管理整間公司"

這條看起來很基本，但 alt 寫得好不好，直接決定螢幕閱讀器使用者能不能讀懂你的網站。規則是給機器看的，alt 是給人看的——別把它當成填空題草草寫過。

AAA 不是 0/1，是一條持續走的路

看完這份報告，你會有一個直覺：AAA 不是「過了就結束」。

自動可驗的部分——對比度、文件結構、tab order——機器跑完就有答案。但 AAA 嚴格的地方是它要求人工複核大量「語義層」的問題：

• 連結文字是否清楚？
• 標題是否真的描述章節內容？
• 色彩是否傳達唯一資訊（你能不能只靠形狀判斷出來）？
• 表單錯誤訊息是否說明怎麼修正？

這些問題沒有「對錯一刀切」的答案——同一個連結文字，在 A 情境算清楚、在 B 情境就模糊。所以 454 info 不是「未完成的待辦」，是「上線後仍要持續複檢的常駐工作」。

這也是為什麼我們認為 a11y-moda 必須是 Agent 友善——人工複核做一輪就累了，但 Agent 可以每週、每月持續跑，把可疑的點挑出來給人看。人只看「Agent 不確定的那 5%」。

還沒拿標章，但工具先做、報告先攤

你可能注意到——我們還沒拿無障礙等級標章。

標章要送審、要排隊、要費用、要審查週期。我們沒繞過這些步驟，只是次序顛倒——

• 大部分公司：拿到標章 → 才公開談無障礙
• 我們：工具先做 → 報告先攤 → 標章再說

為什麼這樣排？因為標章是結果證明，不是能力證明。一家公司有沒有真本事，看的是工具、流程、報告長什麼樣，不是看牆上掛幾張紙。

而且——這份 0 fail / 454 info / 7 caveat 的報告，本身就是一張更實在的「能力證明」。它說的不是「我們通過了」，而是「我們知道哪些已過、哪些待辦、為什麼」。

你網站值不值得這樣跑一次？

完整的 VLM 掃描不是即時的——對手動點選的人是場硬仗，對排程跑的 Agent 來說剛好可以放在背景。

哪些公司值得跑？

• 必跑：政府標案承作、上市櫃、教育機構、醫療相關、民生公共服務（這些有法規要求）
• 強烈建議：B2C 大流量網站、電商、會員制服務（用戶基數大，1% 的視障使用者就是上萬人）
• 加分項：B2B 顧問業、品牌官網（無障礙是專業度的訊號，不是負擔）

工具是開源的，你想自己跑就自己跑：github.com/light-design-tw/a11y-moda。

如果你不想自己處理工具、模型、排程、解讀這些事——訂閱制顧問方案就是替你扛這些。我們會持續跑、持續看、持續修，不是「掃一次給份報告就走」。這跟訂閱制顧問背後的邏輯一樣：一次性的大健檢，拆成持續性的小檢查。

想先看看自己網站長什麼樣——寫信跟我們聊聊，可以幫你跑一份初步報告，看看 fail / info / caveat 分布，再決定要不要走後續。