accessibility-compliance

accessibility-compliance 技能總覽

accessibility-compliance 技能的作用是什麼

accessibility-compliance 技能可協助代理產出可直接落地的無障礙實作指引，適用於 Web 與行動 UI 工作，重點聚焦在 WCAG 2.2、ARIA 使用方式、鍵盤操作可達性、螢幕閱讀器支援，以及行動裝置無障礙。它最適合正在處理真實介面設計與開發的團隊，而不只是撰寫一份通用的無障礙檢查清單。

哪些人適合安裝 accessibility-compliance

這個技能很適合以下使用情境：

• 需要 accessibility-compliance for UX Audit 的 UX 稽核人員
• 要修正元件無障礙問題的前端工程師
• 正在定義可存取互動模式的設計系統團隊
• 會交付表單、對話框、選單與其他互動式 UI 的產品團隊
• 需要納入 VoiceOver 與 TalkBack 考量的行動端或跨平台團隊

如果你的核心任務是「把這個畫面或元件改到更接近 WCAG 相容，並提出具體修正方式」，那麼這個技能會比泛用型設計 prompt 更實用。

為什麼這個技能和一般 prompt 不一樣

accessibility-compliance skill 的主要價值，在於它會把模型收斂到實務上的無障礙實作模式，而不是停留在模糊原則。這個 repo 內含幾份聚焦參考文件：

• references/wcag-guidelines.md
• references/aria-patterns.md
• references/mobile-accessibility.md

因此，它特別適合拿來處理像是：優先選擇語意化 HTML 而非 ARIA、建立可存取的表單結構、改善鍵盤操作行為，或檢查行動裝置的觸控目標規範等工作。

安裝前多數使用者會在意什麼

多數正在評估 accessibility-compliance install 的使用者，通常會想確認：

• 它提供的是具體、偏程式碼層級的修正，而不是政策式描述
• 它是否同時涵蓋 Web 與行動端議題
• 它是否同時適用於稽核與實作
• 它對原生語意與 ARIA 的取捨是否有明確立場
• 它能否減少 UI 元件審查時來回溝通的成本

就這幾點來看，這個技能表現相當扎實。它最明顯的差異化優勢，是把 WCAG 概念、ARIA 模式與行動無障礙實務整合在同一個套件中，而且偏向可直接執行的做法。

最適合與不適合的使用情境

最適合：

• 稽核互動式元件
• 修正既有程式碼中的無障礙問題
• 規劃對話框、手風琴、表單與導覽元件的可存取行為
• 檢查焦點順序、標籤、提示宣告與降低動態效果支援

不適合：

• 特定司法管轄區的法律合規解讀
• 單靠它完成自動化測試建置
• 與無障礙無關、只看像素細節的視覺設計評論
• 超出參考內容範圍的深度原生平台 API 細節

如何使用 accessibility-compliance 技能

安裝方式與呼叫情境

上游 SKILL.md 沒有提供安裝指令，因此目錄使用者通常會直接從 repo 加入：

npx skills add https://github.com/wshobson/agents --skill accessibility-compliance

安裝後，請用具體的無障礙任務來呼叫它，而不要只下「檢查無障礙」這種過於籠統的要求。accessibility-compliance 技能在輸入內容包含足夠結構資訊、可供審查的元件、流程或畫面時，效果最好。

建議先讀這幾個檔案

想快速上手，建議先看：

1. plugins/ui-design/skills/accessibility-compliance/SKILL.md
2. plugins/ui-design/skills/accessibility-compliance/references/wcag-guidelines.md
3. plugins/ui-design/skills/accessibility-compliance/references/aria-patterns.md
4. plugins/ui-design/skills/accessibility-compliance/references/mobile-accessibility.md

這個閱讀順序也很符合多數團隊的實際工作流：先看合規目標，再看實作模式，最後補平台邊界情境。

要讓技能發揮效果，輸入內容需要包含什麼

accessibility-compliance usage 的品質，高度取決於你給的資訊是否具體。建議提供：

• 元件或頁面類型
• 目前的程式碼或標記
• 使用框架（React、Next.js、Vue、純 HTML、React Native）
• 互動行為
• 目標標準，通常是 WCAG 2.2 AA
• 裝置範圍：desktop web、mobile web、iOS、Android
• 稽核工具或使用者測試中已知的問題

較弱的輸入：

• 「幫我把這個做成無障礙。」

較強的輸入：

• 「請審查這個 React modal 是否符合 WCAG 2.2 AA。檢查 keyboard trap 行為、focus return、accessible name/description、escape handling，以及 screen reader announcements。請在上線前提出程式碼修正建議。」

把模糊目標改寫成好用的 prompt

一個好的 accessibility-compliance guide prompt，通常會包含五個部分：

1. 目標 UI
2. 使用者互動方式
3. 合規目標
4. 預期交付內容
5. 限制條件

例如：

• 「Use the accessibility-compliance skill to audit this checkout form for WCAG 2.2 AA. Identify failures by issue, explain user impact, and provide corrected JSX for labels, error messaging, field grouping, and keyboard flow. Keep the current visual design if possible.」

這種寫法會比直接要求「best practices」更好，因為它會逼模型產出可以實際修正的結果。

用在 UX Audit 的最佳 workflow

若是拿來做 accessibility-compliance for UX Audit，建議依照這個流程：

1. 先請它找出問題
2. 再請它說明嚴重程度與使用者影響
3. 再請它對應提出修正方式
4. 再請它給出修正版 markup 或元件程式碼
5. 最後請它整理重測 checklist

這樣做可以避開一個常見失敗模式：第一輪回答停留在概念層，沒有真正走到可實作的細節。這個技能真正有價值的地方，就是你能把它從稽核發現一路推進到實作層面。

不只頁面，元件層更能發揮 accessibility-compliance

這個技能在可重複使用的互動模式上特別強。很適合的目標包括：

• dialogs 與 focus traps
• accordions
• menus 與 disclosures
• forms 與 validation
• tabs
• carousels
• icon buttons
• mobile touch targets

這些正是泛用 prompt 最容易出錯的地方：不是過度使用 ARIA，就是漏掉鍵盤操作和螢幕閱讀器行為。

參考文件在實務上代表什麼

內附參考文件其實透露出三個重要操作原則：

• 先優先使用 semantic HTML，再考慮加入 ARIA
• 預設基準是 WCAG 2.2 AA
• 不只考慮桌面鍵盤使用，也要納入行動無障礙

這些原則在實務上很重要。若想讓輸出更可靠，建議在 prompt 裡明確要求代理盡量減少不必要的 ARIA，並說明每個新增 ARIA 屬性的理由。

讓 accessibility-compliance 輸出更強的 prompt 格式

可以使用這種請求格式：

• Context: “This is a React checkout drawer.”
• Target: “Meet WCAG 2.2 AA.”
• Review scope: “Keyboard access, focus order, visible labels, error association, live region announcements.”
• Constraints: “Do not rewrite the design system API.”
• Deliverable: “Return prioritized issues, corrected JSX, and a manual test checklist.”

這種結構化寫法，一貫比開放式審查要求更能產出高品質的 accessibility-compliance usage 結果。

可以期待 accessibility-compliance skill 回傳什麼內容

一份好的 accessibility-compliance skill 回應，通常應包含：

• 與使用者影響對應的問題清單
• 對應到無障礙原則或準則的說明
• 具體的 markup 或程式碼修正建議
• 鍵盤與焦點行為說明
• 螢幕閱讀器命名與宣告建議
• 若相關，補充行動端特有注意事項

如果輸出只停留在原則說明，沒有到程式碼修正層級，那通常代表你的 prompt 還是太寬泛。

accessibility-compliance 技能 FAQ

accessibility-compliance 適合新手嗎？

適合，但前提是你已經懂基本 UI 結構。這個技能在你能提供 markup、元件或稽核結果時，價值會高很多。新手仍然可以使用，只是通常要再追問：為什麼要選某種語意結構、為什麼某些 ARIA 寫法比較合適。

這比一般的無障礙 prompt 更好嗎？

通常是，尤其在實作工作上。一般 prompt 很容易回傳像「加上 alt text」或「確保可用鍵盤操作」這種泛泛而談的建議。accessibility-compliance skill 比較能緊扣 repo 參考內容中的 WCAG 2.2、ARIA patterns 與行動無障礙考量。

它能取代自動化無障礙測試嗎？

不能。它比較像是自動化工具與人工檢查的補充。你可以用它來解讀問題、提出修正方案，並審查靜態工具經常抓不到的元件行為，例如焦點管理、宣告時機，或行動互動細節。

什麼情況下不該使用 accessibility-compliance？

以下情況建議不要使用：

• 需要法律意見或認證判定
• 需要全程自動化、涵蓋整個 codebase 的掃描
• 需要超出參考模式範圍的深度原生行動平台細節
• 需要的其實是非無障礙導向的 UX 評論

它是指引型技能，不是合規保證。

它對行動無障礙的支援夠好嗎？

以 AI 技能來說算不錯。專門的 mobile-accessibility.md 參考文件涵蓋了 iOS 與 Android 的觸控目標大小、間距，以及螢幕閱讀器相關考量。這讓它在行動端審查上的可信度，明顯高於那些只聚焦桌面 Web 的無障礙 prompt。

可以用在 design system 工作嗎？

可以。它非常適合拿來定義可重用元件的無障礙預設，尤其是那些需要在多個產品之間一致處理語意、鍵盤操作、ARIA state 與 focus management 的情境。

如何改善 accessibility-compliance 技能的使用效果

給 accessibility-compliance 真實素材，不要只給摘要

想快速提升 accessibility-compliance 的結果品質，最有效的方法就是直接提供實際的 JSX、HTML、React Native 程式碼、附註解的截圖，或逐步互動描述。若只是給模糊的產品摘要，這個技能很難可靠推斷焦點順序、標籤設計或宣告內容。

要求問題對應關係，不要只要建議

更強的請求方式是：

• 「請列出每個問題、受影響使用者、違反的原則或準則，以及精確修正方式。」

這會迫使模型產出可稽核的結果。少了這種結構，回答很容易飄回泛泛建議。

明確告訴它你能接受的修改幅度

無障礙修正常常要和設計系統限制取捨，因此請清楚說明代理是否可以：

• 只修改 markup
• 只在必要時加入 ARIA
• 重構元件階層
• 為了提升清楚度調整文案
• 如果現有設計本身不可存取，是否允許更改互動模式

這對結果品質的影響，通常比多數使用者預期的還大。

常見失敗模式：ARIA 用過頭

無障礙工作裡一個很常見的問題，就是在原生 HTML 更合適的情況下，仍然加了過多 ARIA。想改善輸出品質，可以明確加入這句：

• 「Prefer native semantic elements and only use ARIA when native semantics are insufficient.」

這樣的指示和 repo 中的 ARIA 參考一致，也能降低低品質修正的機率。

常見失敗模式：忽略狀態變化

很多第一輪回答會抓到標籤與焦點問題，卻漏掉動態行為。建議特別要求檢查：

• 焦點進入與返回
• 展開／收合狀態宣告
• 驗證錯誤關聯
• 使用 live regions 的非同步狀態訊息
• 若相關，也納入 reduced motion 與 high contrast 的考量

這些細節會實質提升 accessibility-compliance guide 的可用性。

第一輪回答後要繼續迭代

完成初步稽核後，可以接著下列其中一種要求：

• 「Rewrite the component with the fixes applied.”
• “Prioritize only release-blocking issues.”
• “Convert this into QA test steps.”
• “Explain what should be tested with screen readers.”
• “Separate WCAG AA requirements from nice-to-have AAA improvements.”

這樣可以把技能從單純的 reviewer，轉成真正協助交付的工具。

有策略地讀 repository references

不用一開始就把整個 repo 全看完。如果你的問題是：

• 語意結構或合規目標：先看 references/wcag-guidelines.md
• widget 行為或 roles：看 references/aria-patterns.md
• 觸控目標或行動輔助技術：看 references/mobile-accessibility.md

這種有針對性的閱讀路徑，能讓 accessibility-compliance install 與實際導入速度更快。

要提升可信度，就要求它說明理由

可以要求技能解釋每一項修正，為何對鍵盤使用者、螢幕閱讀器使用者、低視能使用者，或對動態效果敏感的使用者重要。這有助於揪出表面修正，也方便團隊在 review 時替實作工作提出合理依據。

取得 production-ready 輸出的最佳方式

如果你想讓 accessibility-compliance usage 產出最高價值，建議一次要求以下內容：

• 排序後的問題清單
• 修正後的程式碼
• 修正理由
• 人工驗證 checklist
• 剩餘風險或前提假設

這一整包內容，才是多數團隊真正需要的東西：能把「我們應該改善無障礙」推進成「我們現在就能實作並驗證」。