with one click
with one click
[HINT] Download the complete skill directory including SKILL.md and all related files
| name | a11y-tw |
| disable-model-invocation | true |
| argument-hint | [path] [--criteria ids] |
| description | 台灣網站無障礙審計工具。掃描 React/Next.js/HTML, 依 WCAG 2.2 AA + 台灣在地規範產出審計報告並輔助修復。 |
| hooks | {"PostToolUse":[{"matcher":"Edit","hooks":[{"type":"prompt","prompt":"An a11y audit fix was applied. Review the edit in $ARGUMENTS.\nFlag (ok=false) if ANY of these are true:\n1. A named CSS class/variable/token was REPLACED with a hardcoded value (e.g., bg-accent-teal → bg-[#0b7d86])\n2. DOM manipulation APIs were introduced (MutationObserver, document.title=, window.addEventListener) for something a framework likely handles natively\n3. An HTML element type was changed (e.g., <p> → <legend>, <div> → <section>) — these have different browser default styles and may break layout\n4. New code reimplements something visible in the old_string context (e.g., custom focus trap when existing component already handles it)\nSimple attribute additions (alt, aria-label, role, lang, scope, autocomplete, aria-*) are always ok=true.\n$ARGUMENTS\n"}]}],"Stop":[{"hooks":[{"type":"agent","prompt":"The a11y-tw audit skill is finishing. Verify completeness:\n1. Read Claude's last message. Did it apply any fixes (Edit calls)?\n2. If fixes were applied, check: was re-verification performed AFTER the fixes?\n Look for evidence of: re-running checks, Playwright re-tests, or a diff table.\n3. If fixes applied but NO re-verification done, return ok=false with reason \"Re-verification required after fixes.\"\n4. If no fixes were applied (report-only), return ok=true.\n5. If fixes AND re-verification were both done, return ok=true.\n$ARGUMENTS\n"}]}]} |
/a11y-tw 幫我檢查所有頁面的無障礙
/a11y-tw src/components/Modal.tsx
/a11y-tw --criteria 1.4.3,2.4.7
任何修復都必須先產出報告,再依據修復類型決定執行方式。
| 修復類型 | 常見範例(非窮舉) |
|---|---|
| 🎨 需確認 | 色彩對比調整、焦點指示器樣式、目標大小調整、新增 Skip Link/定位點、文字間距/行高調整 |
| 🔧 可自動修復 | 加 alt=""、lang、rel、ARIA 屬性、scope、修正標題跳級、加 autoComplete、role、狀態屬性 |
| 📝 需手動處理 | 影片字幕、複雜圖表描述、鍵盤/焦點管理流程設計、一致性導覽/識別、Hover/Focus 狀態的對比度 |
分類原則:不在上表中的修復,依此判斷 — 🎨 會改變畫面上任何可見像素(顏色、大小、間距、佈局、新增/移除視覺元素)?→ 需確認。🔧 純增刪 HTML 屬性或語意標籤、不改變計算後視覺結果?→ 可自動修復。其餘 → 📝 需手動處理。
解析使用者指令,確定掃描範圍:
| 指令 | 範圍 |
|---|---|
/a11y-tw | app/ 或 pages/ 或 src/ 整個前端目錄 |
/a11y-tw <path> | 該路徑下所有 .tsx/.jsx/.html 檔案 |
/a11y-tw <file> | 單一檔案 + 其 import 的元件 |
/a11y-tw --criteria <ids> | 全部檔案但只查指定準則 |
使用者可能以自然語言描述掃描目標(如「幫我看 enterprise 與 public 下所有頁面」)。此時:
依掃描內容按需讀取:
| 場景 | 檔案 |
|---|---|
每次必讀(--criteria 模式時僅讀匹配的準則段落) | references/checklist.md(60 條完整清單 + 台灣法規附錄) |
| 遇到複雜互動元件(Modal、Tab、Accordion、Carousel、Form、Date Picker 等)或台灣定位點實作 | references/patterns.md |
| 掃描包含 1.4.3 / 1.4.11 對比度 | references/contrast.md |
⚠️ Step 3 包含 3a 和 3b 兩個子步驟。兩者都必須執行。完成 3a 後必須立刻進入 3b,不得跳過 3b 直接進入 Step 4。
依 references/checklist.md 排列順序一次掃描全部適用準則:第一原則(可感知)→ 第二原則(可操作)→ 第三原則(可理解)→ 第四原則(穩健性)→ 台灣特有。
對每條準則產出初判結果:
⚠️ 需 runtime 確認3a 完成條件:必須對每條適用準則逐一產出判定(✅/🔴/🟡/⚠️),以結構化清單或表格呈現。僅讀取原始碼檔案不算完成 3a — 讀取是準備工作,逐條準則比對並記錄判定才是 3a 的產出。未見到逐條判定結果,不得進入 3b。
特別強化以下項目(其餘準則仍須依 checklist.md 逐條完整掃描,不得因未列於此處而降低檢查深度):
autocomplete 政策。掃描對比度準則時,依 references/contrast.md 執行靜態分析:
text-* / bg-*)與 inline style,解析前景/背景色:hover / :focus)中宣告的色彩亦同步分析(1.4.11)⚠️ 需 runtime 確認Step 3a 完成後,立刻執行本步驟。
依以下優先順序偵測 dev server URL,取第一個命中的結果:
dev 或 start 腳本中的 port flag(--port、-p、PORT=).env.local → .env.development → .env 中的 PORTnext.config.* / vite.config.* / nuxt.config.* / angular.json)嘗試 browser_navigate 至偵測到的 URL:
references/playwright.md,繼續執行下方批次檢查npm run dev 或對應指令),等待就緒後重試| 批次 | 涵蓋準則 | 操作 |
|---|---|---|
| axe-core 全頁掃描 | 通用 | CDN 注入 + axe.run() |
| 對比度驗證 | 1.4.3, 1.4.11 | getComputedStyle() 批次取色 |
| Tab 序列與焦點 | 2.1.2, 2.4.3, 2.4.7, 2.4.11, TW-03 | 連續 Tab 按鍵 + 每步截圖 |
| Reflow 測試 | 1.4.10 | resize(320) + 截圖 |
| 無障礙樹快照 | 2.5.3, 4.1.2, 4.1.3, 2.4.4 | browser_snapshot |
| 目標大小 | 2.5.8 | getBoundingClientRect() 批次量測 |
| 台灣定位點 | TW-01 | Tab 至定位點 + 截圖 |
上表依操作類型組織 runtime 檢查,「涵蓋準則」列出各批次的主要目標。單一批次的結果可能同時涉及未列出的相關準則(例如 Tab 序列測試同時觀察 3.2.1 焦點觸發行為)。
Runtime 結果覆寫或補充 Step 3a 的靜態初判:
⚠️ 需 runtime 確認 + runtime ✅ → 最終 ✅ 通過⚠️ 需 runtime 確認 + runtime 🔴 → 最終 🔴 失敗截圖用於兩個目的:AI 即時判斷(焦點是否可見、是否被遮蔽、佈局是否正確)+ 報告留存證據。分析截圖時,重點確認:焦點指示器可見性(2.4.7)、焦點未被 sticky 遮蔽(2.4.11)、320px 無水平溢出(1.4.10)。
前置條件:Step 3a 和 3b 都已執行完畢。若 3b 未執行,返回執行 3b。
# 無障礙審計報告
**審計日期**:YYYY-MM-DD
**掃描範圍**:[路徑/檔案]
**目標等級**:WCAG 2.2 AA + 台灣在地規範
**審計結果**:X 通過 / Y 警告 / Z 失敗
**驗證覆蓋**:靜態分析 X 條 / runtime 驗證 Y 條 / 僅靜態(runtime 未驗證)Z 條
---
## 📊 統計摘要
| 原則 | 通過 | 警告 | 失敗 |
|------|------|------|------|
| 可感知 | X | X | X |
| 可操作 | X | X | X |
| 可理解 | X | X | X |
| 穩健性 | X | X | X |
| 台灣特有 | X | X | X |
| **合計** | **X** | **X** | **X** |
## 🔴 失敗(必須修復)
### [F001] 準則編號 — 問題摘要
- **檔案**:`path/to/file.tsx:行號`
- **問題**:具體描述
- **影響**:對使用者的影響
- **驗證方式**:靜態分析 / runtime 驗證 / 靜態 + runtime
- **修復**:具體修復方式
- **修復類型**:🔧 可自動修復 / 🎨 需確認(視覺變更)/ 📝 需手動處理
- **修復風險**:🟢 低(純屬性)/ 🟡 中(CSS/佈局)/ 🔴 高(框架 API/架構)
- **優先級**:🔴 高 / 🟡 中 / 🟢 低
- **證據**:[runtime 截圖/結果,僅靜態分析時省略]
## 🟡 警告(建議修復)
### [W001] ...
## 🟢 通過
- ✅ 準則編號:通過描述
## 📋 台灣特有規範
| 項目 | 狀態 | 說明 |
|------|------|------|
| TW-01 定位點(:::) | ✅/🔴 | ... |
| TW-02 Access Key | ✅/🔴 | ... |
| TW-03 網站導覽 / 3-Tab | ✅/🔴 | ... |
| TW-04 Landmark Roles | ✅/🔴 | ... |
| TW-05 Freego 相容性 | ✅/🔴 | ... |
報告產出後,詢問使用者是否要修復。
在動手修任何東西之前,先理解專案的架構慣例:
package.json,識別框架(Next/Nuxt/Vue/Angular/Svelte/Astro)、CSS 方案(Tailwind/Sass/CSS Modules/styled-components)、元件庫(Radix/MUI/Headless UI/Ant Design)tailwind.config.*、:root CSS 變數、SCSS 變數、theme 檔案)。若專案無設計系統,記錄此事實原則:修復必須是專案既有架構的自然延伸。用專案已有的方式解決問題。用框架原生 API。找不到既有方式時,參考
references/patterns.md。
第一批:🔧 可自動修復 — 批次執行,不需逐項確認。
第二批:🎨 需確認(視覺變更) — 一次列出所有 🎨 項目的修復計畫:
每項須包含:修復方式、視覺影響(改動後畫面上什麼會不同)、影響範圍、修復風險等級。
對每項提供選項:
使用者可逐項選擇,也可批次回覆「全部 A」或「全部 B」。
第三批:📝 需手動處理 — 僅提供修復指引。
回顧本次所有修復,以下列原則逐一審查。若任一項不通過,先修正再進入 Step 6。
根因優先:每項修復是否改動了問題的源頭(定義層),而非在消費端重複修補?若同一類修復散佈 3 個以上檔案,視為警示信號,應考慮是否有更上游的單點可改。
抽象層一致:新增或修改的樣式值、變數、class 是否透過專案既有的抽象層(設計 token、CSS 變數、共用元件)引入?是否繞過了專案已建立的間接層?
框架原生優先:修復是否使用了框架提供的原生機制?是否引入了框架已有對應方案的低階 DOM 操作或瀏覽器 API?
跨狀態有效:修復在所有 viewport、互動狀態(hover/focus/active)、顯示條件(responsive breakpoint、條件渲染)下是否仍然有效?是否有功能仍活躍但修復元素被隱藏的情況?
全域完整:Grep 全專案,確認同一類問題的所有實例都已處理,而非只修了掃描範圍內的檔案。
審查通過後,若本次有任何 🎨 修復被執行,輸出視覺變更摘要:
| 報告編號 | 準則 | 視覺變更描述 | 影響範圍 |
|---|---|---|---|
| F003 | 2.4.7 | 焦點外框從 2px → 3px | 全站互動元素 |
| ... | ... | ... | ... |
此步驟為必要步驟。Step 5 修復完成後立即自動執行,不需使用者再次下指令。
使用者可要求
/a11y-tw完整重掃(full re-scan),此時重新執行 Step 1–4。
審計流程結束後(無論是 Step 4 報告產出後使用者不修復,或 Step 6 再驗證完成後),執行:
a11y-*.png 與 page-*.png以下無法由靜態分析或 Playwright 完成:螢幕閱讀器朗讀(NVDA + Firefox / VoiceOver + Safari)、跨頁一致性(3.2.3 / 3.2.4)、影片字幕/音訊描述(1.2.x)、認知層面(錯誤訊息建議品質、操作指示清晰度)。
本 Skill 的靜態分析 + Playwright 驗證可涵蓋大部分自動化可偵測的問題。 以下工具用於 Skill 無法覆蓋的面向:
| 工具 | 用途 |
|---|---|
| Freego | 台灣官方機器檢測(申請標章必用,僅 Windows) |
| axe DevTools | 瀏覽器擴充自動偵測 |
| NVDA + Firefox | 螢幕閱讀器測試(台灣審查必用) |
| VoiceOver + Safari | macOS 螢幕閱讀器測試 |
| jest-axe | CI 整合:單元測試中加入 axe-core 檢查 |
| eslint-plugin-jsx-a11y | 開發時即時 linting |
螢幕閱讀器手動測試步驟見
README.md。