Communitygithub.com

rhpxgr8pzm-max/claude-skills

設計、實現並稽核符合 WCAG 2.2 Level AA 的無障礙 UI,涵蓋 Web、iOS 和 Android — 包括語義 ARIA 角色與標籤、無障礙特徵與提示、焦點管理、對比度、目標尺寸以及螢幕閱讀器支援。當您在建置或稽核 UI 以符合無障礙規範、鍵盤導航或螢幕閱讀器支援時使用。

claude-skills 是什麼?

這項技能確保數位介面對所有使用者(包括使用螢幕閱讀器、切換控制或鍵盤導航的使用者)來說,是可感知、可操作、可理解且穩健的(POUR)。它專注於 WCAG 2.2 成功標準的技術實現,協助開發人員在 Web(HTML/ARIA)、iOS(SwiftUI)和 Android(Compose)平台上建置或稽核無障礙 UI。該技能涵蓋關鍵領域,例如使用語義元素進行跨平台對應、焦點管理、目標尺寸(24x24 CSS 像素),以及對動態內容使用 `aria-live` 等即時區域。透過遵循逐步流程——從識別元件角色到驗證穩健的相容性——它確保 UI 不僅符合規範,而且對所有使用者來說都能實際使用。此外,它還識別了常見的反模式,例如僅透過顏色傳達意義或未受限的模態焦點,並提供了針對每個平台的最佳實務清單和具體程式碼範例。

相容平台✓Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/rhpxgr8pzm-max/claude-skills/tree/HEAD/plugins/tally-dev/skills/accessibility

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

無障礙 (WCAG 2.2)

這項技能確保數位介面對於所有使用者(包括使用螢幕閱讀器、切換控制或鍵盤導航的使用者)來說,是可感知、可操作、可理解且穩健的(POUR)。它專注於 WCAG 2.2 成功標準的技術實作。

使用時機

  • 定義 Web、iOS 或 Android 的 UI 元件規格時。
  • 稽核現有程式碼以發現無障礙障礙或合規差距時。
  • 實作新的 WCAG 2.2 標準,例如目標尺寸(最小值)和焦點外觀時。
  • 將高階設計需求對應到技術屬性(ARIA 角色、特徵、提示)時。

核心概念

  • POUR 原則:WCAG 的基礎(可感知、可操作、可理解、穩健)。
  • 語義對應:使用原生元素而非通用容器來提供內建的無障礙性。
  • 無障礙樹:輔助技術實際「讀取」的 UI 表示。
  • 焦點管理:控制鍵盤/螢幕閱讀器游標的順序和可見性。
  • 標籤與提示:透過 aria-label、accessibilityLabel 和 contentDescription 提供上下文。

運作方式

步驟 1:識別元件角色

確定功能目的(例如,這是按鈕、連結還是標籤頁?)。在使用自訂角色之前,優先使用最具語義的原生元素。

步驟 2:定義可感知屬性

  • 確保文字對比度符合 4.5:1(一般文字)或 3:1(大型文字/UI 元件)。
  • 為非文字內容(圖片、圖示)新增文字替代方案。
  • 實作回應式重排(最多 400% 縮放而不失功能)。

步驟 3:實作可操作控制項

  • 確保最小 24x24 CSS 像素 的目標尺寸(WCAG 2.2 SC 2.5.8)。
  • 驗證所有互動元素都可透過鍵盤到達,並具有可見的焦點指示器(SC 2.4.11)。
  • 為拖曳動作提供單一指標替代方案。

步驟 4:確保可理解的邏輯

  • 使用一致的導航模式。
  • 提供描述性的錯誤訊息和修正建議(SC 3.3.3)。
  • 實作「冗餘輸入」(SC 3.3.7),避免要求使用者重複輸入相同資料。

步驟 5:驗證穩健的相容性

  • 使用正確的「名稱、角色、值」模式。
  • 為動態狀態更新實作 aria-live 或即時區域。

無障礙架構圖

flowchart TD
  UI["UI 元件"] --> Platform{平台?}
  Platform -->|Web| ARIA["WAI-ARIA + HTML5"]
  Platform -->|iOS| SwiftUI["無障礙特徵 + 標籤"]
  Platform -->|Android| Compose["語義 + 內容描述"]

  ARIA --> AT["輔助技術(螢幕閱讀器、切換控制)"]
  SwiftUI --> AT
  Compose --> AT

跨平台對應表

功能Web (HTML/ARIA)iOS (SwiftUI)Android (Compose)
主要標籤aria-label / <label>.accessibilityLabel()contentDescription
次要提示aria-describedby.accessibilityHint()Modifier.semantics { stateDescription = ... }
動作角色role="button".accessibilityAddTraits(.isButton)Modifier.semantics { role = Role.Button }
即時更新aria-live="polite".accessibilityLiveRegion(.polite)Modifier.semantics { liveRegion = LiveRegionMode.Polite }

範例

Web:無障礙搜尋

<form role="search">
  <label for="search-input" class="sr-only">搜尋產品</label>
  <input type="search" id="search-input" placeholder="搜尋..." />
  <button type="submit" aria-label="提交搜尋">
    <svg aria-hidden="true">...</svg>
  </button>
</form>

iOS:無障礙動作按鈕

Button(action: deleteItem) {
    Image(systemName: "trash")
}
.accessibilityLabel("刪除項目")
.accessibilityHint("從您的清單中永久移除這個項目")
.accessibilityAddTraits(.isButton)

Android:無障礙切換開關

Switch(
    checked = isEnabled,
    onCheckedChange = { onToggle() },
    modifier = Modifier.semantics {
        contentDescription = "啟用通知"
    }
)

應避免的反模式

  • Div-按鈕:使用 <div> 或 <span> 來處理點擊事件,卻未新增角色和鍵盤支援。
  • 僅靠顏色傳達意義:僅透過顏色變化(例如將邊框變紅)來指示錯誤或狀態。
  • 未受限的模態焦點:模態視窗沒有限制焦點,導致鍵盤使用者在模態視窗開啟時仍可與背景內容互動。焦點必須被限制在模態視窗內,並且可以透過 Escape 鍵或明確的關閉按鈕來逃脫(WCAG SC 2.1.2)。
  • 冗餘替代文字:在替代文字中使用「圖片...」或「照片...」(螢幕閱讀器已會宣告「圖片」角色)。

最佳實務檢查清單

  • 互動元素符合 24x24px(Web)或 44x44pt(原生)的目標尺寸。
  • 焦點指示器清晰可見且對比度高。
  • 模態視窗在開啟時 限制焦點,並在關閉時乾淨地釋放焦點(Escape 鍵或關閉按鈕)。
  • 下拉式選單和選單在關閉時,將焦點恢復到觸發元素。
  • 表單提供基於文字的錯誤建議。
  • 所有僅含圖示的按鈕都有一個描述性的文字標籤。
  • 文字縮放時,內容能正確重排。

參考資料

相關技能

  • frontend-patterns
  • design-system
  • liquid-glass-design
  • swiftui-patterns

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

相關技能