Communitygithub.com

ComeOnOliver/skillshub

審查 UI 元件是否符合 WCAG 規範、ARIA 屬性、鍵盤導航及螢幕閱讀器支援。適用於建構前端元件或用戶要求無障礙性改善時。

skillshub 是什麼?

這個 AI 助手技能專門用於審計網頁應用程式的無障礙合規性(WCAG 2.1 Level AA),並提供改善建議。當你建構或審查 UI 元件、用戶提出無障礙性改善需求、準備進行無障礙審計,或用戶提到「accessibility」、「a11y」、「WCAG」、「screen reader」或「keyboard navigation」等關鍵字時,即可使用此技能。它涵蓋了語義 HTML 檢查、ARIA 屬性使用、鍵盤導航支援、替代文字與圖片處理、色彩與對比度要求、表單與標籤、標題與文件結構、動態內容通知、螢幕閱讀器測試技巧,以及常見問題檢查清單。此外,還整合了自動化測試工具(如 Lighthouse、axe-core、pa11y)的 CLI 指令與測試整合範例。支援平台包含任何需要撰寫或審查前端元件的開發環境(例如 Claude Code、Cursor、Codex),透過遵循此技能的逐步指引,開發者能系統性地提升應用程式的無障礙性,確保符合 WCAG 2.1 Level AA 標準。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/ComeOnOliver/skillshub/tree/HEAD/skills/aiskillstore/marketplace/crazydubya/accessibility-auditor

在你喜歡的 AI 中提問

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

預覽

來自技能 README

skillshub preview
skillshub preview
skillshub preview

說明文件

無障礙審計員

審計網頁應用程式的無障礙合規性(WCAG 2.1 Level AA)並提供改善建議。

使用時機

  • 建構或審查 UI 元件時
  • 用戶要求無障礙性改善
  • 準備進行無障礙審計
  • 用戶提到「accessibility」、「a11y」、「WCAG」、「screen reader」或「keyboard navigation」

操作說明

1. 語義 HTML 檢查

使用正確的 HTML 元素:

<!-- 錯誤 -->
<div onclick="submit()">Submit</div>

<!-- 正確 -->
<button onclick="submit()">Submit</button>

語義結構:

  • <header>、<nav>、<main>、<footer>
  • <article>、<section>、<aside>
  • <h1> 至 <h6> 保持正確層級
  • <button> 用於動作,<a> 用於導航

2. ARIA 屬性

何時使用 ARIA:

  • 自訂 Widget(標籤頁、折疊面板、對話框)
  • 動態內容更新
  • 複雜互動
  • 語義 HTML 不足時

常見 ARIA 屬性:

<!-- 地標角色 -->
<nav role="navigation" aria-label="主導航">

<!-- Widget 角色 -->
<div role="button" tabindex="0" aria-pressed="false">

<!-- 即時區域 -->
<div role="alert" aria-live="assertive">發生錯誤</div>

<!-- 標籤與說明 -->
<button aria-label="關閉對話框">×</button>
<input aria-describedby="password-help" />

ARIA 第一條規則: 如果語義 HTML 可用,就不要使用 ARIA

3. 鍵盤導航

所有互動元素必須可透過鍵盤操作:

// 為自訂元素加入鍵盤支援
<div
  role="button"
  tabindex="0"
  onClick={handleClick}
  onKeyDown={(e) => {
    if (e.key === 'Enter' || e.key === ' ') {
      handleClick();
    }
  }}
>
  點擊我
</div>

Tab 順序:

  • 自訂互動元素使用 tabindex="0"
  • 避免使用 tabindex > 0(會造成混亂的 Tab 順序)
  • 僅在需要程式焦點時使用 tabindex="-1"

焦點管理:

  • 可見的焦點指示器
  • 在對話框中鎖定焦點
  • 關閉對話框時返回焦點
  • 為主要內容提供跳過連結

4. 替代文字與圖片

資訊型圖片:

<img src="chart.png" alt="第三季銷售額成長 25%" />

裝飾型圖片:

<img src="decoration.png" alt="" />
<!-- 或 -->
<img src="decoration.png" role="presentation" />

複雜圖片:

<figure>
  <img src="complex-chart.png" alt="每季銷售圖表" />
  <figcaption>
    圖表資料的詳細說明……
  </figcaption>
</figure>

5. 色彩與對比度

對比度(WCAG AA):

  • 一般文字:至少 4.5:1
  • 大字體(18pt 以上):至少 3:1
  • UI 元件:至少 3:1

不要僅依賴顏色:

<!-- 錯誤:僅用顏色 -->
<span style="color: red;">錯誤</span>

<!-- 正確:圖示 + 顏色 -->
<span style="color: red;">
  <svg aria-hidden="true"><!-- 錯誤圖示 --></svg>
  <span class="sr-only">錯誤:</span>
  輸入無效
</span>

6. 表單與標籤

每個輸入欄位都需要標籤:

<!-- 明確標籤 -->
<label for="email">電子郵件</label>
<input id="email" type="email" />

<!-- 隱含標籤 -->
<label>
  電子郵件
  <input type="email" />
</label>

<!-- 圖示按鈕使用 aria-label -->
<button aria-label="搜尋">
  <svg><!-- 搜尋圖示 --></svg>
</button>

錯誤訊息:

<input
  id="password"
  aria-invalid="true"
  aria-describedby="password-error"
/>
<div id="password-error" role="alert">
  密碼長度必須至少 8 個字元
</div>

7. 標題與文件結構

正確的標題層級:

<h1>頁面標題</h1>
  <h2>第一節</h2>
    <h3>子節 1.1</h3>
    <h3>子節 1.2</h3>
  <h2>第二節</h2>

不要跳過層級: h1 → h2 → h3(不要 h1 → h3)

8. 動態內容

向螢幕閱讀器宣告更新:

<!-- 有禮:等待用戶暫停 -->
<div role="status" aria-live="polite">
  5 封新訊息
</div>

<!-- 果斷:立即中斷 -->
<div role="alert" aria-live="assertive">
  您的連線將在 1 分鐘後過期
</div>

載入狀態:

<button aria-busy="true" aria-label="載入中……">
  <span aria-hidden="true">載入</span>
</button>

9. 螢幕閱讀器測試

僅對螢幕閱讀器顯示的文字:

.sr-only {
  position: absolute;
  width: 1px;
  height: 1px;
  padding: 0;
  margin: -1px;
  overflow: hidden;
  clip: rect(0, 0, 0, 0);
  white-space: nowrap;
  border-width: 0;
}

隱藏裝飾性元素:

<svg aria-hidden="true"><!-- 圖示 --></svg>

10. 常見檢查問題

遺漏:

  • 圖片的替代文字
  • 表單輸入欄位的標籤
  • 正確的標題層級
  • 鍵盤焦點指示器
  • 圖示按鈕的 ARIA 標籤

不當:

  • 低對比度文字
  • 非語義標記(如用 div 當按鈕)
  • 對話框中缺少焦點管理
  • 鍵盤陷阱
  • 自動播放媒體

測試:

  • 僅使用鍵盤導航
  • 螢幕閱讀器(NVDA、JAWS、VoiceOver)
  • 色盲模擬
  • 縮放至 200%
  • 自動化工具(axe、Lighthouse)

11. 自動化測試

工具:

# Lighthouse
npx lighthouse https://example.com --only-categories=accessibility

# axe-core
npm install --save-dev @axe-core/cli
npx axe https://example.com

# pa11y
npm install --save-dev pa11y
npx pa11y https://example.com

在測試中使用:

import { axe } from 'jest-axe';

test('不應有無障礙違規', async () => {
  const { container } = render(<MyComponent />);
  const results = await axe(container);
  expect(results).toHaveNoViolations();
});

12. WCAG 2.1 Level AA 檢查清單

可感知:

  • 非文字內容的文字替代
  • 音訊/影片的字幕
  • 內容可適配(語義標記)
  • 足夠的色彩對比

可操作:

  • 可透過鍵盤操作
  • 無鍵盤陷阱
  • 適當的時間限制(可調整)
  • 無誘發癲癇的閃爍
  • 跳過導覽連結
  • 描述性的頁面標題
  • 焦點順序合理
  • 連結目的從上下文清楚可知

可理解:

  • 指定頁面語言(<html lang="en">)
  • 可預測的導航
  • 輸入輔助(標籤、指示、錯誤訊息)

穩健:

  • 有效的 HTML
  • 自訂 Widget 的名稱、角色、值
  • 與輔助技術相容

最佳實踐

  • 從一開始就建構無障礙性
  • 使用真實的輔助技術進行測試
  • 優先使用語義 HTML,其次才是 ARIA
  • 保持邏輯的文件結構
  • 提供多種存取內容的方式
  • 徹底測試鍵盤導航
  • 不要停用縮放
  • 使用地標與標題

支援檔案

  • reference/wcag-checklist.md:完整 WCAG 2.1 AA 檢查清單
  • reference/aria-patterns.md:常見 ARIA Widget 模式

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

ComeOnOliver/skillshub

Create stunning, animation-rich HTML presentations from scratch or by converting PowerPoint files. Use when the user wants to build a presentation, convert a PPT/PPTX to web, or create slides for a talk/pitch. Helps non-designers discover their aesthetic through visual exploration rather than abstract choices.

ComeOnOliver/skillshub

Next.js 16+ 和 Turbopack — 增量打包、文件系统缓存、开发速度,以及何时使用 Turbopack 与 webpack。

ComeOnOliver/skillshub

SwiftUI architecture patterns, state management with @Observable, view composition, navigation, performance optimization, and modern iOS/macOS UI best practices.

ComeOnOliver/skillshub

See, Understand, Act on video and audio. See- ingest from local files, URLs, RTSP/live feeds, or live record desktop; return realtime context and playable stream links. Understand- extract frames, build visual/semantic/temporal indexes, and search moments with timestamps and auto-clips. Act- transcode and normalize (codec, fps, resolution, aspect ratio), perform timeline edits (subtitles, text/image overlays, branding, audio overlays, dubbing, translation), generate media assets (image, audio, video), and create real time alerts for events from live streams or desktop capture.

ComeOnOliver/skillshub

AI-assisted video editing workflows for cutting, structuring, and augmenting real footage. Covers the full pipeline from raw capture through FFmpeg, Remotion, ElevenLabs, fal.ai, and final polish in Descript or CapCut. Use when the user wants to edit video, cut footage, create vlogs, or build video content.

ComeOnOliver/skillshub

Next.js 15 애플리케이션을 위한 프론트엔드 개발 가이드라인. React 19, TypeScript, Shadcn/ui, Tailwind CSS를 사용한 모던 패턴. Server Components, Client Components, App Router, 파일 구조, Shadcn/ui 컴포넌트, 성능 최적화, TypeScript 모범 사례 포함. 컴포넌트, 페이지, 기능 생성, 데이터 페칭, 스타일링, 라우팅, 프론트엔드 코드 작업 시 사용.

ComeOnOliver/skillshub

Provides Tamagui patterns for config v4, compiler optimization, styled context, and cross-platform styling. Must use when working with Tamagui projects (tamagui.config.ts, @tamagui imports).

ComeOnOliver/skillshub

Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, or applications. Generates creative, polished code that avoids generic AI aesthetics.

ComeOnOliver/skillshub

Create high-converting, visually distinctive landing pages. Use when building marketing pages, product launches, SaaS homepages, or any single-page conversion-focused website. Guides section-by-section composition with anti-AI-slop principles.

ComeOnOliver/skillshub

Auto-loaded context for Portfolio Buddy 2 development. Use for ANY task involving: React 19 development, TypeScript, portfolio analysis features, metrics calculations, trading strategy comparison, or working with the Portfolio Buddy 2 codebase. Contains tech stack, known issues, and architectural constraints.

ComeOnOliver/skillshub

Next.js development tooling via MCP. Inspect routes, components, build info, and debug Next.js apps. Use when working on Next.js applications, debugging routing, or inspecting app structure. NOT for general React or non-Next.js projects.

ComeOnOliver/skillshub

Implement UI using Shadcn MCP (atoms/theme) and 21st.dev MCP (complex sections). Use when adding buttons, layouts, or generating landing pages.

ComeOnOliver/skillshub

A conceptual skill for building an API client in Next.js that handles JWT tokens

ComeOnOliver/skillshub

Best practices and patterns for Next.js App Router, Server Actions, and Routing in this project.

ComeOnOliver/skillshub

The Design System, Theme, and UX rules for the Physical AI Hub.

ComeOnOliver/skillshub

Comprehensive frontend development skill for building modern, performant web applications using ReactJS, NextJS, TypeScript, Tailwind CSS. Includes component scaffolding, performance optimization, bundle analysis, and UI best practices. Use when developing frontend features, optimizing performance, implementing UI/UX designs, managing state, or reviewing frontend code.

ComeOnOliver/skillshub

This document captures learnings from fixing keyboard navigation issues when floating components (Select, DropdownMenu, Popover) have CSS open/close animations.

ComeOnOliver/skillshub

Build Next.js 16 applications with correct patterns and distinctive design. Use when creating pages, layouts, dynamic routes, upgrading from Next.js 15, or implementing proxy.ts. Covers breaking changes (async params/searchParams, Turbopack, cacheComponents) and frontend aesthetics. NOT when building non-React or backend-only applications.

ComeOnOliver/skillshub

Comprehensive Framer Motion animation library for React. Covers motion components, variants, gestures, page transitions, and scroll animations. Use when adding animations to React/Next.js applications.

ComeOnOliver/skillshub

Build interfaces that resonate, not just render. This skill enforces bold, intentional

相關技能